@khorsheed/dsh-local-agent-dsh 0.2.0-rc.3 → 0.2.1

package/lib/types/session-mirror.d.ts

@@ -29,6 +29,19 @@
  * passes never duplicate an identical snapshot and the child's `todos`
  * projection (and the official TodoPanel in non-takeover views) reads the
  * member's task list for free.
+ *
+ * Interrupted-tail closure: a sub-dsh that dies mid-step (the exec kill
+ * ladder, a live-runtime crash) leaves its log's step — and any advertised
+ * tool calls — OPEN, and the verbatim copy carries that open tail into the
+ * child session. The released-log reader (harness
+ * session-format-v3-to-v4/relationships.ts) rejects a `turn/end` over an open
+ * step on every cold read, so the provider's settle flow calls
+ * {@link closeMirroredOpenStep} after the settle mirror pass and before its
+ * own `turn/end`: each advertised-but-unresolved call receives a synthesized
+ * interrupted `tool/result` (the family's shared placeholder for a started
+ * call, the validator's exact TOOL_NOT_STARTED repair for one that never
+ * started) and the copied step receives its `step/end`. Mid-round the open
+ * pair still crosses as-is — the sub-dsh may yet write its end.
  * @module @khorsheed/dsh-local-agent-dsh/session-mirror
  */
 import type { DshSessionLog } from './session-log.ts';
@@ -98,6 +111,48 @@ export interface DshMirrorDelta {
 }
 /** How much of the live event stream crosses into the child session. */
 export type DshLiveMirrorGranularity = 'event' | 'token';
+/**
+ * The placeholder text of the synthesized result for a tool call the sub-dsh
+ * started but never resolved (its process died between `tool/call` and
+ * `tool/result`). Shared verbatim with the kimi family's fold.
+ */
+export declare const DSH_INTERRUPTED_TOOL_RESULT = "\uFF08\u5DE5\u5177\u8C03\u7528\u88AB\u4E2D\u65AD\uFF0C\u672A\u80FD\u8BB0\u5F55\u8FD4\u56DE\u7ED3\u679C\uFF09";
+/** What {@link closeMirroredOpenStep} synthesized, when it closed anything. */
+export interface DshMirrorTailClosure {
+    /** The copied open step this closure ended. */
+    readonly step: {
+        turn: number;
+        step: number;
+    };
+    /** The advertised calls that received a synthesized interrupted result, in advertisement order. */
+    readonly repairedCalls: readonly string[];
+}
+/**
+ * The child session's currently-open copied step: the (turn, step) of a
+ * `step/start` whose `step/end` has not crossed, inside a turn the provider
+ * has not closed. Undefined when nothing is open. The live driver's
+ * interrupted-stream fold consults it: the fold's assistant/message may land
+ * only while its step is still open (a graceful sub-dsh unwind writes its own
+ * message and step/end, and the fold must not append at the closed step).
+ */
+export declare function mirroredOpenStep(childSession: Session): {
+    turn: number;
+    step: number;
+} | undefined;
+/**
+ * Close the copied open tail of the child session's current turn at settle,
+ * before the provider's `turn/end`: the released-log reader rejects a
+ * `turn/end` over an open step ('turn/end does not match the open turn with
+ * no open step') and a step/end leaving an advertised call unresolved, so an
+ * interrupted sub-dsh's open step is ended here — each advertised-but-
+ * unresolved tool call first receiving its synthesized interrupted result
+ * (the family's placeholder for a started call; the validator's exact
+ * TOOL_NOT_STARTED repair for one that never started). Mid-round transports
+ * never call this: the sub-dsh may yet write its own end, and a synthesized
+ * step/end would collide with it on a later pass. Returns what it
+ * synthesized, or undefined when the copied tail was already balanced.
+ */
+export declare function closeMirroredOpenStep(childSession: Session): DshMirrorTailClosure | undefined;
 /**
  * Mirror ONE live-pushed sub-dsh session event (the serve mode's
  * `session/event` wire notification) into the child session. This is the

package/lib/types/session-mirror.js

@@ -29,6 +29,19 @@
  * passes never duplicate an identical snapshot and the child's `todos`
  * projection (and the official TodoPanel in non-takeover views) reads the
  * member's task list for free.
+ *
+ * Interrupted-tail closure: a sub-dsh that dies mid-step (the exec kill
+ * ladder, a live-runtime crash) leaves its log's step — and any advertised
+ * tool calls — OPEN, and the verbatim copy carries that open tail into the
+ * child session. The released-log reader (harness
+ * session-format-v3-to-v4/relationships.ts) rejects a `turn/end` over an open
+ * step on every cold read, so the provider's settle flow calls
+ * {@link closeMirroredOpenStep} after the settle mirror pass and before its
+ * own `turn/end`: each advertised-but-unresolved call receives a synthesized
+ * interrupted `tool/result` (the family's shared placeholder for a started
+ * call, the validator's exact TOOL_NOT_STARTED repair for one that never
+ * started) and the copied step receives its `step/end`. Mid-round the open
+ * pair still crosses as-is — the sub-dsh may yet write its end.
  * @module @khorsheed/dsh-local-agent-dsh/session-mirror
  */
 import { readFile, readdir } from 'node:fs/promises';
@@ -247,7 +260,9 @@ function appendMirroredToolEvent(childSession, event) {
  * index registers the same step the sub-dsh wrote. Shared by the file
  * mirror's span loop and the live driver's per-event mirror. An interrupted
  * step crosses as an OPEN pair (start without end): the location resolves to
- * the step either way, and no boundary is ever synthesized.
+ * the step either way, and mid-round no boundary is synthesized — the sub-dsh
+ * may yet write its end. At settle the provider closes the copied tail with
+ * {@link closeMirroredOpenStep} before its own `turn/end`.
  */
 function appendMirroredStepBoundary(childSession, event) {
     if (event.type === 'step/start') {
@@ -274,6 +289,145 @@ function appendMirroredMessageEvent(childSession, event) {
     }
     return mirroredEventText(event);
 }
+/**
+ * The placeholder text of the synthesized result for a tool call the sub-dsh
+ * started but never resolved (its process died between `tool/call` and
+ * `tool/result`). Shared verbatim with the kimi family's fold.
+ */
+export const DSH_INTERRUPTED_TOOL_RESULT = '（工具调用被中断，未能记录返回结果）';
+/**
+ * The released-log reader's exact repair text for a call that was advertised
+ * but never recorded as started: relationships.ts's notStartedRepair admits
+ * only that shape (the `interrupted-tool-result-<callId>-<n>` id, the
+ * ToolNotStartedError/TOOL_NOT_STARTED error, no sourceEventSeqs, and this
+ * single text block) — no other wording resolves the call.
+ */
+const TOOL_NOT_STARTED_REPAIR_TEXT = 'The tool call was interrupted before the Harness recorded it as started. Retry it if it is still needed.';
+/**
+ * The child session's currently-open copied step: the (turn, step) of a
+ * `step/start` whose `step/end` has not crossed, inside a turn the provider
+ * has not closed. Undefined when nothing is open. The live driver's
+ * interrupted-stream fold consults it: the fold's assistant/message may land
+ * only while its step is still open (a graceful sub-dsh unwind writes its own
+ * message and step/end, and the fold must not append at the closed step).
+ */
+export function mirroredOpenStep(childSession) {
+    const events = childSession.snapshotEvents();
+    // Backward: the latest boundary event says the state — a step/start opens,
+    // a step/end or any turn boundary closes the question.
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const type = events[index]?.type;
+        if (type === 'step/start')
+            return events[index]?.data;
+        if (type === 'step/end' || type === 'turn/start' || type === 'turn/end')
+            return undefined;
+    }
+    return undefined;
+}
+/**
+ * Close the copied open tail of the child session's current turn at settle,
+ * before the provider's `turn/end`: the released-log reader rejects a
+ * `turn/end` over an open step ('turn/end does not match the open turn with
+ * no open step') and a step/end leaving an advertised call unresolved, so an
+ * interrupted sub-dsh's open step is ended here — each advertised-but-
+ * unresolved tool call first receiving its synthesized interrupted result
+ * (the family's placeholder for a started call; the validator's exact
+ * TOOL_NOT_STARTED repair for one that never started). Mid-round transports
+ * never call this: the sub-dsh may yet write its own end, and a synthesized
+ * step/end would collide with it on a later pass. Returns what it
+ * synthesized, or undefined when the copied tail was already balanced.
+ */
+export function closeMirroredOpenStep(childSession) {
+    const events = childSession.snapshotEvents();
+    // Only the current (last) turn can hold the copied open tail: an earlier
+    // turn closed with the provider's turn/end, which no valid prefix crossed
+    // with open state.
+    let turnStart = -1;
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const type = events[index]?.type;
+        if (type === 'turn/end')
+            return undefined;
+        if (type === 'turn/start') {
+            turnStart = index;
+            break;
+        }
+    }
+    if (turnStart < 0)
+        return undefined;
+    let openStep;
+    // The turn's tool-call ledger: an assistant/message's tool-call blocks
+    // advertise, a tool/call starts, a tool/result resolves — its message names
+    // the call at the top level (the V4 tool-role shape) or in its single
+    // content block (the pre-V4 user-role shape); read both, a mirrored log may
+    // predate the upgrade.
+    const advertised = new Set();
+    const started = new Map();
+    const resolved = new Set();
+    for (const event of events.slice(turnStart + 1)) {
+        if (event.type === 'step/start') {
+            openStep = event.data;
+        }
+        else if (event.type === 'step/end') {
+            openStep = undefined;
+        }
+        else if (event.type === 'assistant/message') {
+            const content = event.data.message?.content ?? [];
+            for (const block of content) {
+                if (block?.type === 'tool-call' && typeof block.id === 'string')
+                    advertised.add(block.id);
+            }
+        }
+        else if (event.type === 'tool/call') {
+            const callId = event.data.callId;
+            if (typeof callId === 'string')
+                started.set(callId, event.seq);
+        }
+        else if (event.type === 'tool/result') {
+            const message = event.data.message;
+            const id = message?.toolCallId ?? message?.content?.[0]?.toolCallId;
+            if (typeof id === 'string')
+                resolved.add(id);
+        }
+    }
+    if (openStep === undefined)
+        return undefined;
+    const step = openStep;
+    const repaired = [];
+    // The seq the next appended event occupies (seq == log length), so the
+    // synthesized ids carry the harness's repair-id convention.
+    let nextSeq = events.length;
+    for (const callId of advertised) {
+        if (resolved.has(callId))
+            continue;
+        const callSeq = started.get(callId);
+        const message = {
+            id: `interrupted-tool-result-${callId}-${nextSeq}`,
+            role: 'tool',
+            toolCallId: callId,
+            isError: true,
+            source: { kind: 'tool', callId },
+            content: [{ type: 'text', text: callSeq === undefined ? TOOL_NOT_STARTED_REPAIR_TEXT : DSH_INTERRUPTED_TOOL_RESULT }],
+        };
+        nextSeq += 1;
+        childSession.append('tool/result', {
+            turn: step.turn,
+            step: step.step,
+            message,
+            error: callSeq === undefined
+                ? { name: 'ToolNotStartedError', code: 'TOOL_NOT_STARTED' }
+                : { name: 'ToolOutcomeUnknownError', code: 'TOOL_OUTCOME_UNKNOWN' },
+        }, {
+            surfaceOp: 'append',
+            // The not-started repair must carry NO sourceEventSeqs (the reader
+            // admits exactly that shape); the started repair pairs with the copied
+            // call event, exactly as a real mirrored result does.
+            ...callSeq === undefined ? {} : { sourceEventSeqs: [callSeq] },
+        });
+        repaired.push(callId);
+    }
+    childSession.append('step/end', { turn: step.turn, step: step.step });
+    return { step, repairedCalls: repaired };
+}
 /**
  * Mirror ONE live-pushed sub-dsh session event (the serve mode's
  * `session/event` wire notification) into the child session. This is the

package/lib/types/tool.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The session-granted `subagent_dsh` delegation tool — this package's
+ * `./tool` composition entry (the worktrees 0.3.0 / room 0.2.0 fold pattern)
+ * for agent-preset compositions. The row provides NO service (the
+ * preset-mount isolate-realm rule forbids service rows); it registers the
+ * model-facing tool into the host tools registry through the family factory
+ * (`@khorsheed/dsh-local-agent/tool-factory`), delegating to the `dsh-cli`
+ * provider this package's main row registers at the profile root — the
+ * official tool-row shape (the shipped `tool-bash` rows work the same way).
+ * Granting is therefore per-session: a preset names the row
+ * (`- id: tool-subagent-dsh / name: '@khorsheed/dsh-local-agent-dsh/tool'`),
+ * its sessions get the tool; every other preset's sessions do not.
+ *
+ * This row replaced the dsh package's own dynamic mount: the tool used to
+ * mount at the profile root while the card's 启用 switch was on, which granted
+ * every session. With the switch gone (the harness is always registered), the
+ * tool follows the other providers — a preset names the row to grant it.
+ *
+ * @module @khorsheed/dsh-local-agent-dsh/tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type z from '@deepseek-ai/schemastery';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "local-agent-dsh-tool";
+/**
+ * The family core's `localAgent` service is a declared inject (the
+ * owning-family companion exception to the community-service probe rule): a
+ * preset's standing scope mounts at registry-activation time, BEFORE the
+ * profile's later bundle rows provide the core, so a one-shot ctx.get probe
+ * at apply saw ABSENT there and nothing re-ran the row (rc.1 boot order; the
+ * worktrees `./tool` entry documents the incident). The declared inject pends
+ * the row until the core provides, then the body applies.
+ */
+export declare const inject: string[];
+/** Config: every field optional, defaulting to THIS provider's own values. */
+export interface Config {
+    /** The `ctx.subagents` provider name to delegate to (default `dsh-cli`). */
+    provider?: string;
+    /** Model-facing tool name (default `subagent_dsh`). */
+    toolName?: string;
+}
+export declare const Config: z;
+/**
+ * Plugin body: mount the delegation tool through the family factory, stamped
+ * with THIS package as the tool-origin owner (AGENTS.md § Tool origin
+ * tagging — the shared factory never hardcodes an owner).
+ * @param ctx - Cordis context (the preset's agent-plane mount).
+ * @param config - row config (schema defaults already applied; the `??`
+ * fallbacks cover a direct ctx.plugin caller that bypassed validation).
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=tool.d.ts.map

package/lib/types/tool.js

@@ -0,0 +1,34 @@
+import { mountSubagentDelegationTool, subagentToolConfigSchema } from '@khorsheed/dsh-local-agent/tool-factory';
+const PACKAGE_NAME = '@khorsheed/dsh-local-agent-dsh';
+/** This entry's own defaults: a preset row needs no config. */
+const DEFAULT_PROVIDER = 'dsh-cli';
+const DEFAULT_TOOL_NAME = 'subagent_dsh';
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'local-agent-dsh-tool';
+/**
+ * The family core's `localAgent` service is a declared inject (the
+ * owning-family companion exception to the community-service probe rule): a
+ * preset's standing scope mounts at registry-activation time, BEFORE the
+ * profile's later bundle rows provide the core, so a one-shot ctx.get probe
+ * at apply saw ABSENT there and nothing re-ran the row (rc.1 boot order; the
+ * worktrees `./tool` entry documents the incident). The declared inject pends
+ * the row until the core provides, then the body applies.
+ */
+export const inject = ['tools', 'subagents', 'localAgent'];
+// Bare `z` annotation per the shared helper's variance note.
+export const Config = subagentToolConfigSchema(DEFAULT_PROVIDER, DEFAULT_TOOL_NAME);
+/**
+ * Plugin body: mount the delegation tool through the family factory, stamped
+ * with THIS package as the tool-origin owner (AGENTS.md § Tool origin
+ * tagging — the shared factory never hardcodes an owner).
+ * @param ctx - Cordis context (the preset's agent-plane mount).
+ * @param config - row config (schema defaults already applied; the `??`
+ * fallbacks cover a direct ctx.plugin caller that bypassed validation).
+ */
+export function apply(ctx, config) {
+    const resolved = {
+        provider: config.provider ?? DEFAULT_PROVIDER,
+        toolName: config.toolName ?? DEFAULT_TOOL_NAME,
+    };
+    mountSubagentDelegationTool(ctx, resolved, PACKAGE_NAME);
+}

package/package.json

@@ -8,7 +8,7 @@
     "local-agent",
     "subagent"
   ],
-  "version": "0.2.0-rc.3",
+  "version": "0.2.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -29,6 +29,10 @@
       "types": "./lib/types/dsh-cli-provider.d.ts",
       "default": "./lib/dsh-cli-provider.js"
     },
+    "./tool": {
+      "types": "./lib/types/tool.d.ts",
+      "default": "./lib/tool.js"
+    },
     "./client": {
       "types": "./lib/types/client/index.d.ts",
       "default": "./lib/client.js"
@@ -36,7 +40,8 @@
     "./src/*": "./src/*",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json",
-    "./locale/*.json": "./locale/*.json"
+    "./locale/*.json": "./locale/*.json",
+    "./tool/locale/*.json": "./locale/*.json"
   },
   "dsh": {
     "references": [
@@ -75,8 +80,8 @@
     "dsh": ">=0.1.5-rc.1 <0.3.0-0"
   },
   "dependencies": {
-    "@khorsheed/dsh-local-agent": "^0.2.0-rc.3",
-    "@khorsheed/dsh-local-agent-dsh-headless": "^0.2.0-rc.3",
+    "@khorsheed/dsh-local-agent": "^0.2.1",
+    "@khorsheed/dsh-local-agent-dsh-headless": "^0.2.1",
     "js-yaml": "^4.3.1"
   },
   "peerDependencies": {