@morlay/dsh-subagent 0.0.5 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morlay/dsh-subagent",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Thin-shell fork of @deepseek-ai/dsh-subagent: takes over the official `subagent` row for two wording changes — the continuable child's return guidance in Chinese wording and the child's Chinese delegation-scope runtime context (`subagent:delegation`) — plus the row-id reuse (same `subagent` id, so the official settings card stays); everything not intentionally changed is imported from the vendored upstream source.",
   "keywords": [
     "dsh",
@@ -14,49 +14,57 @@
     "url": "https://github.com/morlay/dsh-plugin.git"
   },
   "files": [
+    "src",
     "locale/*.json",
     "dist",
-    "!**/__tests__"
+    "!**/__tests__",
+    "!**/vendor/**/__tests__"
   ],
   "type": "module",
   "exports": {
-    ".": "./dist/index.mjs",
-    "./rows": "./dist/rows.mjs",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./rows": {
+      "types": "./dist/rows.d.mts",
+      "default": "./dist/rows.mjs"
+    },
     "./package.json": "./package.json",
     "./locale/*.json": "./locale/*.json"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-brand": "^0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "~3.18.4"
+    "@deepseek-ai/dsh-brand": "^0.2.1-alpha.5",
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent-loop": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-chunked-list": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-invariants": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-subagent-fork-in-process": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-subagent-spawn-in-process": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-tool-subagent-control": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-util-values": "0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "~3.18.4",
+    "@deepseek-ai/dsh-agent-loop": "0.2.1-alpha.5",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.1-alpha.5",
+    "@deepseek-ai/dsh-chunked-list": "0.2.1-alpha.5",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.2.1-alpha.5",
+    "@deepseek-ai/dsh-subagent-fork-in-process": "0.2.1-alpha.5",
+    "@deepseek-ai/dsh-subagent-spawn-in-process": "0.2.1-alpha.5",
+    "@deepseek-ai/dsh-tool-subagent-control": "0.2.1-alpha.5",
+    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.5",
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.2",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-agent": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-agent-preset-registry": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-attachment": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-scope": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-session": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-session-query": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-subagent": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-util-time": "^0.2.0-rc.2"
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@deepseek-ai/dsh-agent": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-agent-preset-registry": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-attachment": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-llm": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-scope": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-session": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-session-persistence": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-session-query": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-subagent": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-alpha.5",
+    "@deepseek-ai/dsh-tools": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-typert-protocol": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-util-time": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-working-directory": "^0.2.1-alpha.5"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-session-persistence": {

package/src/continuation-messages.ts

@@ -0,0 +1,185 @@
+/**
+ * Model-visible messages owned by continuable-subagent orchestration.
+ *
+ * @module @deepseek-ai/dsh-subagent/continuation-messages
+ */
+
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { SubagentResult } from './vendor/dsh-subagent/types.ts'
+
+/** Durable attribution for one model-authored message between Agents. */
+export interface AgentMessageSource {
+  readonly kind: 'agent-message'
+  /** A message another agent addressed to this one (`relay` context form). */
+  readonly form: 'relay'
+  /** Session id of the Agent whose tool call produced the message. */
+  readonly senderSessionId: SessionId
+}
+
+/**
+ * Durable attribution for the runtime's own account of a continuable child
+ * settling. Deliberately a different kind from
+ * {@link AgentMessageSource}: an Agent message is content the sender chose,
+ * while this message is the manager stating what became of the child, and a
+ * transcript that merged them would credit the child with words it never wrote.
+ */
+export interface SubagentSettledMessageSource {
+  readonly kind: 'subagent-settled'
+  /** A runtime account shown without expanding the row (`notice` context form). */
+  readonly form: 'notice'
+  /** One-line account of how the child ended. */
+  readonly summary: string
+  /** Session id of the child that settled. */
+  readonly senderSessionId: SessionId
+}
+
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    'agent-message': AgentMessageSource
+    'subagent-settled': SubagentSettledMessageSource
+  }
+}
+
+/** Build durable attribution for one adjacent-Agent message. */
+function agentMessageSource(sender: Agent): AgentMessageSource {
+  return {
+    kind: 'agent-message',
+    form: 'relay',
+    senderSessionId: sender.id,
+  }
+}
+
+/**
+ * Build the model-visible and durable representation of one adjacent-Agent message.
+ * @param sender - exact live Agent that authored the message.
+ * @param content - model-visible message blocks supplied by the sender.
+ * @returns the durable user-message representation delivered to the recipient.
+ */
+export function createAgentMessage(
+  sender: Agent,
+  content: ContentBlock[],
+): ReturnType<typeof createUserMessage> {
+  return createUserMessage({
+    content: [
+      { type: 'text' as const, text: `Agent ${sender.id} sent a message: ` },
+      ...content,
+    ],
+    source: agentMessageSource(sender),
+  })
+}
+
+/**
+ * Whether this session's return guidance takes this package's Chinese wording.
+ *
+ * **默认对任意 preset 生效**：名单（本行的 `config.localizedReturnGuidancePresets`）不配就是不限制——官方四个
+ * shipped preset、部署自建的、以及还没绑 preset 的会话（不装 registry 的部署、还没 join 的 agent）都拿中文。
+ * 配了名单才反过来收窄成"只有这些 preset 的会话用中文"。文案是模型可见的东西，判据留在 host 平面
+ * （`subagents` 是进程单例，这一行不能搬进 preset realm）。
+ *
+ * @param composedPreset - the preset id the session is mounted on, if any.
+ * @param configured - preset ids this deployment restricts the Chinese wording to; empty means every session.
+ * @returns whether the Chinese guidance applies to this session.
+ */
+export function localizedReturnGuidance(
+  composedPreset: string | undefined,
+  configured: readonly string[],
+): boolean {
+  if (configured.length === 0) return true
+  return composedPreset !== undefined && configured.includes(composedPreset)
+}
+/**
+ * Append adjacent-Agent return guidance to a continuable child's initial task.
+ * @param parentId - durable parent session id named in the guidance.
+ * @param prompt - initial model-visible task blocks.
+ * @returns task blocks followed by the continuable return guidance.
+ */
+export function withContinuableReturnGuidance(
+  parentId: SessionId,
+  prompt: ContentBlock[],
+): ContentBlock[] {
+  const encodedParentId = JSON.stringify(parentId)
+  return [
+    ...prompt,
+    {
+      type: 'text',
+      text: `你的父智能体 id 是 ${encodedParentId}。完成前用 send_message({ agent_id: ${encodedParentId}, `
+        + 'message: "<自包含的结论>" }) 把结果发给它。父智能体与你共享工作区，但不会自动收到你的对话、'
+        + '工具输出与推理过程。发现会改变父智能体下一步行动的事情时也尽早再发一条；发消息不会结束你的回合。',
+    },
+  ]
+}
+
+/**
+ * One line telling a parent that a background child is finished and why, in
+ * the parent's own task vocabulary.
+ * @param childId - the durable child the parent knows by id.
+ * @param stopReason - how the child's last ordinary turn ended.
+ * @param continuable - whether the child accepts a later message.
+ * @returns the model-facing opening line of the settlement notice.
+ */
+function settlementSummary(childId: SessionId, stopReason: SubagentResult['stopReason'], continuable: boolean): string {
+  const subject = `Background subagent ${childId}`
+  switch (stopReason) {
+    case 'completed':
+      return continuable
+        ? `${subject} finished and will do no further work unless you send it more.`
+        : `${subject} finished. It cannot receive follow-up messages.`
+    case 'aborted':
+      return `${subject} was stopped before it finished.`
+    case 'max-tokens':
+      return `${subject} ran out of room before it finished.`
+    // A pre-step rejection — a hook deny, a policy plugin — discarded input
+    // the child had claimed, so the parent must not treat the task as done.
+    case 'refusal':
+      return `${subject} declined the task.`
+    case 'error':
+      return `${subject} failed before it finished.`
+    /* v8 ignore next 4 -- `SubagentResult['stopReason']` is merge-extensible, so this arm
+     * needs a backend that adds a variant; an unnameable ending is reported as unfinished
+     * rather than silently as success. */
+    default:
+      return `${subject} ended abnormally (${String(stopReason)}) before it finished.`
+  }
+}
+
+/**
+ * Build the runtime-owned settlement notice from the child's nonempty closing text.
+ * @param childId - durable child session id named in the notice.
+ * @param terminal - recorded terminal state for the settled Activation.
+ * @param continuable - whether the child can accept another task.
+ * @returns the durable user-message representation delivered to the parent.
+ */
+export function createSettlementMessage(
+  childId: SessionId,
+  terminal: SubagentResult,
+  continuable = true,
+): ReturnType<typeof createUserMessage> {
+  const summary = settlementSummary(childId, terminal.stopReason, continuable)
+  // Parent providers receive this notice as a user message and may reject
+  // nontext assistant blocks. Keep this conversion local so SDK/UI consumers
+  // retain the complete child output.
+  const closingText = terminal.output.flatMap(block =>
+    block.type === 'text' && block.text.length > 0 ? [block] : [],
+  )
+  return createUserMessage({
+    content: [
+      { type: 'text' as const, text: summary },
+      ...closingText.length === 0
+        ? [{ type: 'text' as const, text: 'It left no closing message.' }]
+        : [{ type: 'text' as const, text: 'Its closing message:' }, ...closingText],
+      ...terminal.structured !== undefined
+        ? [{ type: 'text' as const, text: `Structured result: ${JSON.stringify(terminal.structured)}` }] : [],
+      ...terminal.diagnostic !== undefined
+        ? [{ type: 'text' as const, text: terminal.diagnostic }] : [],
+    ],
+    source: {
+      kind: 'subagent-settled' as const,
+      form: 'notice' as const,
+      summary: boundContextSummary(summary),
+      senderSessionId: childId,
+    },
+  })
+}

package/src/delegation-context.ts

@@ -0,0 +1,39 @@
+// 汉化 `subagent:delegation`：上游在**子代理自己的 agent 作用域**上注册这条运行时上下文
+// （`child-agent.ts` 的 `applyChildComposition`），于是两条常规接管手法都不通：
+//
+// - **同名遮蔽**：同一 scope 里重复注册同名 context 会抛错（`NamedEntries.insert` 报
+//   `prompt context "subagent:delegation" is already registered in this scope`），而装配用的 scope 就是子代理自己
+//   （`assembleContextFor(agent)` → `scope: agent`），与上游那次注册同层；
+// - **fork `child-agent.ts`**：注册这条文本的调用方现在只剩本包已复制的 `manager.ts`（上游 0.2.1-alpha.2 把一次性
+//   driver 并进了它）——但 fork 要再复制一份 290 行、并改本包 manager 的接线，而且对外部 backend（`subagent-acp` /
+//   `subagent-dsh-sdk`）在别的进程里装配的子代理无效。
+//
+// 这里改的是**装配结果**：`SystemPrompt.assemble()` 先 merge 好 contexts、再进 `system-prompt/assemble` 瀑布，本包
+// 在瀑布里把该名字那条的文本换成中文。它在**该次**装配内生效（第一次装配就是中文），两条派发路径一起覆盖；父 agent
+// 的装配不碰（这条本来只对子代理注册）。
+import type { Context } from "@deepseek-ai/cordis";
+import type {} from "@deepseek-ai/dsh-system-prompt";
+
+// 上游注册的运行时上下文名：同名才叫接管。
+export const DELEGATION_CONTEXT_NAME = "subagent:delegation";
+
+// 模型看到的委派范围说明：权限在创建时固定、需要审批的操作一律被拒，超出范围时说明限制而不是重试。
+export const DELEGATION_CONTEXT_TEXT =
+  "你是被派发的子代理：权限范围在创建时就固定，本会话内不能放宽——需要审批的操作一律被自动拒绝。\n" +
+  "任务需要超出这个范围时不要重试被拒的操作，在回复里说明这个限制，让派发你的智能体处理。";
+
+// 装配期替换那一条文本；子代理装配才动（`parentSession` 是委派出来的判据）。
+export function installDelegationContext(ctx: Context): void {
+  ctx.on("system-prompt/assemble", async (assembly, context, next) => {
+    const assembled = await next();
+    if (context.agent?.session.header.parentSession === undefined) return assembled;
+    return {
+      ...assembled,
+      contexts: assembled.contexts.map((entry) =>
+        entry.name === DELEGATION_CONTEXT_NAME
+          ? { ...entry, text: DELEGATION_CONTEXT_TEXT }
+          : entry,
+      ),
+    };
+  });
+}