feat(subagent): continuable background subagents

Implement the continuable background subagents RFC: a durable child session with a series of Task-backed activations, each disposing its run before the Task settles. - dsh-subagent: rename SubagentRun.sendMessage to strict steer, drop run-level resume, add SubagentProvider.resume dispatch via SubagentService.resume, the continuation start field, and the versioned model-hidden subagent/descriptor session event. - dsh-subagent-inprocess/-spawn/-fork: publish the control-allocated child id, append the descriptor inside the initial turn, implement cold resume from the child's own transcript under the live parent scope, and strict running-only steer. - dsh-subagent-control (new): SubagentControlService owning stable child ids, descriptor snapshot/fold/authorization, Task-backed activation with settle-then-dispose ordering, the process-local active-run association, and steer-or-resume sendMessage routing. - dsh-tool-subagent: background route branches on the provider's resume capability (continuable via the control service; one-shot task for ACP), returning both child and task ids. - dsh-tool-subagent-control (new): the globally named send_message tool rendering steered/started routes. Keyless coverage spans Task ownership and disposal ordering, running delivery, cold follow-up, descriptor rejection and rollback, known-id reconstruction, kill during lookup, admission races, and a new subagent-continuable ACP snapshot scenario.
2026-07-23 17:07:38 +08:00
parent 76ff841279
commit 99a778d63f
83 changed files with 3167 additions and 627 deletions
@@ -0,0 +1,74 @@
+/**
+ * The globally named `send_message` tool: a thin model-facing adapter over
+ * `ctx.subagentControl.sendMessage()`. It performs no lifecycle routing of its
+ * own — steer-or-resume orchestration belongs to the control service — and it
+ * lives apart from the provider-bound `@deepseek-ai/dsh-tool-subagent`
+ * instances so multiple delegation tools share one control tool.
+ * @module @deepseek-ai/dsh-tool-subagent-control
+ */
+
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-subagent-control'
+
+export const name = 'tool-subagent-control'
+export const inject = ['tools', 'subagentControl']
+
+/**
+ * Register the `send_message` tool.
+ * @param ctx - context carrying the tool registry and the control service.
+ */
+export function apply(ctx: Context): void {
+  ctx.tools.register(defineTool({
+    name: 'send_message',
+    description:
+      'Send a follow-up message to a background subagent by its subagent id. If it is still working, the '
+      + 'message joins its current task; if it has finished, this starts a new task that continues the same '
+      + 'subagent conversation. Either way the response arrives through the returned task id — collect it '
+      + 'with `task_output`. A failure means the message was NOT delivered.',
+    parameters: {
+      subagent_id: {
+        type: 'string',
+        required: true,
+        description: 'The subagent id returned when the background subagent was started.',
+      },
+      message: {
+        type: 'string',
+        required: true,
+        description: 'The message to deliver to the subagent.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          route: {
+            type: 'string',
+            required: true,
+            enum: ['steered', 'started'],
+          },
+          taskId: { type: 'string', required: true },
+        },
+      },
+      render: (args, value) => [{
+        type: 'text',
+        text: value.route === 'steered'
+          ? `message delivered to running task ${value.taskId}`
+          : `message started task ${value.taskId} continuing subagent ${args.subagent_id}`,
+      }],
+    },
+    execute(args, exec) {
+      const parent = exec.agent
+      if (!parent) {
+        // Non-agent callers have no session to authorize Task access with.
+        throw new Error('send_message requires a calling agent (exec.agent was undefined)')
+      }
+      const message: ContentBlock[] = [{ type: 'text', text: args.message }]
+      const result = ctx.subagentControl.sendMessage(parent, SessionId(args.subagent_id), message)
+      return Promise.resolve(result)
+    },
+  }))
+}
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-subagent-control`.
+ * @module @deepseek-ai/dsh-tool-subagent-control/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-subagent-control'
+
+/** Cordis companion plugin name. */
+export const name = 'tool-subagent-control-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this model-facing adapter has no independent lifecycle stream; delivery
+ * and activation relations are owned by the control service it calls.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */