feat(protocol): accept client-chosen id in session.spawn

This commit is contained in:
Kit Langton
2026-11-04 23:50:36 -08:00
Unverified
parent 114189e274
commit 8b99133169
8 changed files with 348 additions and 4 deletions
+1
View File
@@ -586,6 +586,7 @@ export type ExperimentalSessionWaitOperation<E = never> = (
export type ExperimentalSessionSpawnInput = {
readonly sessionID: Session.ID
readonly id?: Session.ID | undefined
readonly notify?: boolean | undefined
readonly agent?: Agent.ID | undefined
readonly model?: Model.Ref | undefined
+1
View File
@@ -851,6 +851,7 @@ const EndpointExperimentalSessionSpawn = (raw: RawClient["server.session"]) => (
raw["session.spawn"]({
params: { sessionID: input["sessionID"] },
payload: {
id: input["id"],
notify: input["notify"],
agent: input["agent"],
model: input["model"],
+1
View File
@@ -1127,6 +1127,7 @@ export function make(options: ClientOptions) {
method: "POST",
path: `/api/experimental/session/${encodeURIComponent(input.sessionID)}/spawn`,
body: {
id: input["id"],
notify: input["notify"],
agent: input["agent"],
model: input["model"],
+1
View File
@@ -3875,6 +3875,7 @@ export type ExperimentalSessionWaitOutput = SessionWaitResponse["data"]
export type ExperimentalSessionSpawnInput = {
readonly sessionID: string
readonly id?: string | null | undefined
readonly notify?: boolean | null | undefined
readonly agent?: string | null | undefined
readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null | undefined
+248 -3
View File
@@ -2761,8 +2761,15 @@
],
"security": [],
"responses": {
"204": {
"description": "<No Content>"
"200": {
"description": "SessionWaitResponse",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionWaitResponse"
}
}
}
},
"400": {
"description": "InvalidRequestError",
@@ -2794,6 +2801,16 @@
}
}
},
"500": {
"description": "UnknownError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnknownErrorEncoded"
}
}
}
},
"503": {
"description": "ServiceUnavailableError",
"content": {
@@ -2805,10 +2822,172 @@
}
}
},
"description": "Wait for a session agent loop to become idle.",
"description": "Wait for a session agent loop to become idle and report its outcome and final text.",
"summary": "Wait for session"
}
},
"/api/experimental/session/{sessionID}/spawn": {
"post": {
"tags": ["session"],
"operationId": "experimental.session.spawn",
"parameters": [
{
"name": "sessionID",
"in": "path",
"schema": {
"$ref": "#/components/schemas/Session.ID"
},
"required": true
}
],
"security": [],
"responses": {
"200": {
"description": "SessionSpawnResponse",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionSpawnResponse"
}
}
}
},
"400": {
"description": "InvalidRequestError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvalidRequestErrorEncoded"
}
}
}
},
"401": {
"description": "UnauthorizedError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedErrorEncoded"
}
}
}
},
"404": {
"description": "SessionNotFoundError | LocationNotFoundError",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/SessionNotFoundErrorEncoded"
},
{
"$ref": "#/components/schemas/LocationNotFoundErrorEncoded"
}
]
}
}
}
},
"409": {
"description": "ConflictError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConflictErrorEncoded"
}
}
}
},
"500": {
"description": "UnknownError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnknownErrorEncoded"
}
}
}
}
},
"description": "Experimental: may change without compatibility guarantees. Create a child session under this session and optionally admit its first prompt. Pass an optional `id` to make the call retry-safe; reusing an id owned by another session fails with 409.",
"summary": "Spawn subagent session",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"$ref": "#/components/schemas/Session.ID"
},
{
"type": "null"
}
],
"description": "Client-chosen child id. A retry with the same id under the same parent returns the recorded child without admitting its prompt again. An id recorded under another parent, on a root session, or equal to the parent fails with 409."
},
"notify": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"agent": {
"anyOf": [
{
"$ref": "#/components/schemas/Agent.ID"
},
{
"type": "null"
}
]
},
"model": {
"anyOf": [
{
"$ref": "#/components/schemas/Model.Ref"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"prompt": {
"anyOf": [
{
"$ref": "#/components/schemas/PromptInput"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
}
},
"required": true
}
}
},
"/api/session/{sessionID}/revert/stage": {
"post": {
"tags": ["session"],
@@ -21735,6 +21914,34 @@
"required": ["id", "name"],
"additionalProperties": false
},
"PromptInput": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PromptInput.FileAttachment"
}
},
"agents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Prompt.AgentAttachment"
}
},
"skills": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PromptInput.SkillAttachment"
}
}
},
"required": ["text"],
"additionalProperties": false
},
"PromptInput.FileAttachment": {
"type": "object",
"properties": {
@@ -24476,6 +24683,23 @@
"required": ["_tag", "sessionID", "message"],
"additionalProperties": false
},
"SessionSpawnResponse": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/Session.ID"
}
},
"required": ["id"],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
},
"SessionStats.Activity": {
"type": "object",
"properties": {
@@ -24832,6 +25056,27 @@
"required": ["info", "messages"],
"additionalProperties": false
},
"SessionWaitResponse": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"outcome": {
"type": "string",
"enum": ["succeeded", "failed", "interrupted"]
},
"text": {
"type": "string"
}
},
"required": ["text"],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
},
"SessionsCursor": {
"type": "string",
"description": "Opaque pagination cursor returned as cursor.previous or cursor.next in the previous response."
+5 -1
View File
@@ -475,6 +475,10 @@ export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S, FormI ext
HttpApiEndpoint.post("session.spawn", "/api/experimental/session/:sessionID/spawn", {
params: { sessionID: Session.ID },
payload: Schema.Struct({
id: Schema.optional(Session.ID).annotate({
description:
"Client-chosen child id. A retry with the same id under the same parent returns the recorded child without admitting its prompt again. An id recorded under another parent, on a root session, or equal to the parent fails with 409.",
}),
notify: Schema.Boolean.pipe(Schema.optional),
agent: Agent.ID.pipe(Schema.optional),
model: Model.Ref.pipe(Schema.optional),
@@ -492,7 +496,7 @@ export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S, FormI ext
identifier: "experimental.session.spawn",
summary: "Spawn subagent session",
description:
"Experimental: may change without compatibility guarantees. Create a child session under this session and optionally admit its first prompt.",
"Experimental: may change without compatibility guarantees. Create a child session under this session and optionally admit its first prompt. Pass an optional `id` to make the call retry-safe; reusing an id owned by another session fails with 409.",
}),
),
)
+1
View File
@@ -329,6 +329,7 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
return {
data: yield* session
.spawn({
id: ctx.payload.id,
parent: { id: ctx.params.sessionID, notify: ctx.payload.notify },
agent: ctx.payload.agent,
model: ctx.payload.model,
@@ -109,6 +109,96 @@ it.live("spawns a child session and reports it under the parent", () =>
}).pipe(Effect.scoped),
)
it.live("spawns a child at a caller-chosen id and replays a retry without duplicating it", () =>
Effect.gen(function* () {
const handler = yield* ServerFetch.make({
app: { version: "test" },
database: { path: ":memory:" },
fs: { filewatcher: false },
models: { fetch: false },
})
const parent = Schema.decodeUnknownSync(SessionResponse)(
yield* Effect.promise(async () => {
const response = await handler(
new Request("http://opencode.local/api/session", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ title: "Parent" }),
}),
)
expect(response.status).toBe(200)
return response.json()
}),
).data
const body = JSON.stringify({ id: Session.ID.create(), title: "Child", notify: false })
const spawn = () =>
Effect.promise(async () => {
const response = await handler(
new Request(`http://opencode.local/api/experimental/session/${parent.id}/spawn`, {
method: "POST",
headers: { "content-type": "application/json" },
body,
}),
)
expect(response.status).toBe(200)
return Schema.decodeUnknownSync(Schema.Struct({ data: Schema.Struct({ id: Session.ID }) }))(
await response.json(),
).data
})
const spawned = yield* spawn()
const replayed = yield* spawn()
const children = Schema.decodeUnknownSync(SessionsResponse)(
yield* Effect.promise(async () => {
const response = await handler(new Request(`http://opencode.local/api/session?parentID=${parent.id}`))
expect(response.status).toBe(200)
return response.json()
}),
)
expect(spawned.id).toBe(JSON.parse(body).id)
expect(replayed.id).toBe(spawned.id)
expect(children.data.map((session) => session.id)).toEqual([spawned.id])
}).pipe(Effect.scoped),
)
it.live("returns conflict when the spawn id is not a child of this parent", () =>
Effect.gen(function* () {
const handler = yield* ServerFetch.make({
app: { version: "test" },
database: { path: ":memory:" },
fs: { filewatcher: false },
models: { fetch: false },
})
const parent = Schema.decodeUnknownSync(SessionResponse)(
yield* Effect.promise(async () => {
const response = await handler(
new Request("http://opencode.local/api/session", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ title: "Parent" }),
}),
)
expect(response.status).toBe(200)
return response.json()
}),
).data
const response = yield* Effect.promise(() =>
handler(
new Request(`http://opencode.local/api/experimental/session/${parent.id}/spawn`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ id: parent.id, title: "Child", notify: false }),
}),
),
)
expect(response.status).toBe(409)
expect(yield* Effect.promise(() => response.json())).toMatchObject({
_tag: "ConflictError",
resource: parent.id,
})
}).pipe(Effect.scoped),
)
it.live("returns not found when spawning under a missing session", () =>
Effect.gen(function* () {
const handler = yield* ServerFetch.make({