@huanlin/dsh-plugin-yet-another-subagent 0.3.0 → 0.4.1

package/lib/types/projection.d.ts

@@ -1,214 +1,200 @@
-/**
- * Two session projections (design doc §3.6):
- *
- *   - `subagentProfile` (parent session): fold `tool/call` (name `subagent`,
- *     profile in `arguments.profile`) + the matching `tool/result.subagentId`,
- *     building a `childId → profileId` map. Used as a cross-check / fallback
- *     for SubagentCard (which usually reads `profileLabel` straight from the
- *     result content).
- *
- *   - `yaSubagentProgress` (child session): toolcall count, token usage,
- *     and lifecycle state. Pushed over the projection frame so the parent's
- *     SubagentCard can subscribe even though client runtime drops non-current
- *     `session/event` frames (single-stage model).
- *
- * Both units are pure synchronous folds; the framework drives them and the
- * host wire layer ships the validated views.
- *
- * Alpha.3 change-feed contract (`@deepseek-ai/dsh-session-projection`): the
- * drive publishes a client view only when its raw output changes by
- * `Object.is`, so an object-valued view MUST reuse its reference while the
- * wire content is unchanged — a fresh object per call republishes on every
- * internal-only state change (e.g. the excluded `streamingText`
- * accumulator). Both `view`s below go through {@link memoizeView} for that
- * reference-stability guarantee.
- *
- * @module @huanlin/dsh-plugin-yet-another-subagent/projection
- */
-import { z } from 'zod';
-import type { SessionEvent } from '@deepseek-ai/dsh-session';
-/** `subagentProfile` wire shape: childId → profileId, plus callId → childId. */
-export interface SubagentProfileProjection {
-    /** childId → profileId (durable). */
-    readonly children: Record<string, string>;
-    /** callId → childId (for foreground calls where the result text has no embedded id). */
-    readonly calls: Record<string, string>;
-}
-/**
- * Internal fold state for `subagentProfile`. Plain JSON only (the persisted
- * projection-cache precondition), so the pending callId map is a Record,
- * not a Map.
- */
-interface ProfileState {
-    /** callId → profileId, awaiting the matching `tool/result`. */
-    readonly pending: Record<string, string>;
-    /** childId → profileId (the durable mapping). */
-    readonly mapping: Record<string, string>;
-    /** callId → childId (survives after the pending entry is consumed). */
-    readonly callToChild: Record<string, string>;
-}
-/**
- * Fold the parent session's `tool/call` + `tool/result` for tool name
- * `subagent`. The profile id is carried in `tool/call.arguments.profile`
- * (JSON-encoded). The result content embeds `subagentId` (continuable branch)
- * or `runId` (foreground branch); the continuable branch is the durable
- * child identity that survives across activations.
- */
-export declare const subagentProfileProjection: {
-    key: "subagentProfile";
-    stateSchema: z.ZodObject<{
-        pending: z.ZodRecord<z.ZodString, z.ZodString>;
-        mapping: z.ZodRecord<z.ZodString, z.ZodString>;
-        callToChild: z.ZodRecord<z.ZodString, z.ZodString>;
-    }, z.core.$strict>;
-    stateVersion: number;
-    init: () => {
-        pending: {};
-        mapping: {};
-        callToChild: {};
-    };
-    apply: (state: NoInfer<ProfileState>, event: SessionEvent) => ProfileState;
-    wire: {
-        viewSchema: z.ZodObject<{
-            children: z.ZodRecord<z.ZodString, z.ZodString>;
-            calls: z.ZodRecord<z.ZodString, z.ZodString>;
-        }, z.core.$strict>;
-        view: (state: NoInfer<ProfileState>) => {
-            children: Record<string, string>;
-            calls: Record<string, string>;
-        };
-    };
-};
-/** `yaSubagentProgress` wire shape: live child progress for the parent's card. */
-export interface YaSubagentProgressProjection {
-    /** Number of `tool/call` events folded so far. */
-    readonly toolCallCount: number;
-    /** Cumulative token usage folded from `assistant/message.usage`. */
-    readonly tokens: {
-        readonly input: number;
-        readonly output: number;
-        readonly cacheRead: number;
-        readonly cacheWrite: number;
-        readonly reasoning: number;
-    };
-    /** Lifecycle state derived from turn boundaries. */
-    readonly state: 'running' | 'idle' | 'settled';
-    /** Latest activity: streaming text, tool call, or finalized message text. */
-    readonly activity?: Activity;
-}
-/** Discriminated activity union: text or tool call. */
-export type Activity = {
-    readonly kind: 'text';
-    readonly text: string;
-} | {
-    readonly kind: 'tool';
-    readonly name: string;
-    readonly args?: string;
-};
-interface ProgressState {
-    readonly toolCallCount: number;
-    readonly tokens: {
-        readonly input: number;
-        readonly output: number;
-        readonly cacheRead: number;
-        readonly cacheWrite: number;
-        readonly reasoning: number;
-    };
-    readonly state: 'running' | 'idle' | 'settled';
-    /** Accumulator for the current text block's streaming deltas. */
-    readonly streamingText: string;
-    readonly activity?: Activity;
-}
-/**
- * Fold the child session's own events into a compact progress view. Token
- * usage accumulates from `assistant/message.usage` (cache fields are
- * optional); tool calls are counted; lifecycle follows turn boundaries.
- */
-export declare const yaSubagentProgressProjection: {
-    key: "yaSubagentProgress";
-    stateSchema: z.ZodObject<{
-        toolCallCount: z.ZodNumber;
-        tokens: z.ZodObject<{
-            input: z.ZodNumber;
-            output: z.ZodNumber;
-            cacheRead: z.ZodNumber;
-            cacheWrite: z.ZodNumber;
-            reasoning: z.ZodNumber;
-        }, z.core.$strict>;
-        state: z.ZodUnion<readonly [z.ZodLiteral<"running">, z.ZodLiteral<"idle">, z.ZodLiteral<"settled">]>;
-        activity: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
-            kind: z.ZodLiteral<"text">;
-            text: z.ZodString;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"tool">;
-            name: z.ZodString;
-            args: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        streamingText: z.ZodString;
-    }, z.core.$strict>;
-    stateVersion: number;
-    init: () => {
-        toolCallCount: number;
-        tokens: {
-            input: number;
-            output: number;
-            cacheRead: number;
-            cacheWrite: number;
-            reasoning: number;
-        };
-        state: "idle";
-        streamingText: string;
-    };
-    apply: (state: NoInfer<ProgressState>, event: SessionEvent) => ProgressState;
-    wire: {
-        viewSchema: z.ZodObject<{
-            toolCallCount: z.ZodNumber;
-            tokens: z.ZodObject<{
-                input: z.ZodNumber;
-                output: z.ZodNumber;
-                cacheRead: z.ZodNumber;
-                cacheWrite: z.ZodNumber;
-                reasoning: z.ZodNumber;
-            }, z.core.$strict>;
-            state: z.ZodUnion<readonly [z.ZodLiteral<"running">, z.ZodLiteral<"idle">, z.ZodLiteral<"settled">]>;
-            activity: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
-                kind: z.ZodLiteral<"text">;
-                text: z.ZodString;
-            }, z.core.$strict>, z.ZodObject<{
-                kind: z.ZodLiteral<"tool">;
-                name: z.ZodString;
-                args: z.ZodOptional<z.ZodString>;
-            }, z.core.$strict>]>>;
-        }, z.core.$strict>;
-        view: (state: NoInfer<ProgressState>) => {
-            toolCallCount: number;
-            tokens: {
-                readonly input: number;
-                readonly output: number;
-                readonly cacheRead: number;
-                readonly cacheWrite: number;
-                readonly reasoning: number;
-            };
-            state: "running" | "idle" | "settled";
-            activity?: Activity;
-        };
-    };
-};
-/** Convenience: the projection keys registered by this plugin. */
-export declare const PROJECTION_KEYS: readonly ["subagentProfile", "yaSubagentProgress"];
-/** Type-side declaration merges so consumers can read these keys via the projection registry. */
-declare module '@deepseek-ai/dsh-session-projection/types' {
-    interface SessionProjectionMap {
-        /** Parent-session map of childId → profileId. */
-        subagentProfile: SubagentProfileProjection;
-        /** Child-session live progress (toolcall count + token usage + state). */
-        yaSubagentProgress: YaSubagentProgressProjection;
-    }
-    interface SessionProjectionStateMap {
-        /** Host fold state behind {@link SubagentProfileProjection}. */
-        subagentProfile: ProfileState;
-        /** Host fold state behind {@link YaSubagentProgressProjection}. */
-        yaSubagentProgress: ProgressState;
-    }
-}
-export type { SessionEvent };
+/**
+ * Two session projections (design doc §3.6):
+ *
+ *   - `subagentProfile` (parent session): fold `tool/call` (name `subagent`,
+ *     profile in `arguments.profile`) + the matching `tool/result.subagentId`,
+ *     building a `childId → profileId` map. Used as a cross-check / fallback
+ *     for SubagentCard (which usually reads `profileLabel` straight from the
+ *     result content).
+ *
+ *   - `yaSubagentProgress` (child session): toolcall count, token usage,
+ *     and lifecycle state. Pushed over the projection frame so the parent's
+ *     SubagentCard can subscribe even though client runtime drops non-current
+ *     `session/event` frames (single-stage model).
+ *
+ * Both units are pure synchronous folds; the framework drives them and the
+ * host wire layer ships the validated views.
+ *
+ * Change-feed contract (`@deepseek-ai/dsh-session-projection`): the drive
+ * publishes a client view only when its raw output changes by `Object.is`, so
+ * an object-valued view MUST reuse its reference while the wire content is
+ * unchanged — a fresh object per call republishes on every internal-only
+ * state change. Both `view`s below go through {@link memoizeView} for that
+ * reference-stability guarantee.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/projection
+ */
+import { z } from 'zod';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** `subagentProfile` wire shape: childId → profileId, plus callId → childId. */
+export interface SubagentProfileProjection {
+    /** childId → profileId (durable). */
+    readonly children: Record<string, string>;
+    /** callId → childId (for foreground calls where the result text has no embedded id). */
+    readonly calls: Record<string, string>;
+}
+/**
+ * Internal fold state for `subagentProfile`. Plain JSON only (the persisted
+ * projection-cache precondition), so the pending callId map is a Record,
+ * not a Map.
+ */
+interface ProfileState {
+    /** callId → profileId, awaiting the matching `tool/result`. */
+    readonly pending: Record<string, string>;
+    /** childId → profileId (the durable mapping). */
+    readonly mapping: Record<string, string>;
+    /** callId → childId (survives after the pending entry is consumed). */
+    readonly callToChild: Record<string, string>;
+}
+/**
+ * Fold the parent session's `tool/call` + `tool/result` for tool name
+ * `subagent`. The profile id is carried in `tool/call.arguments.profile`
+ * (JSON-encoded). The result content embeds `subagentId` (continuable branch)
+ * or `runId` (foreground branch); the continuable branch is the durable
+ * child identity that survives across activations.
+ */
+export declare const subagentProfileProjection: {
+    key: "subagentProfile";
+    stateSchema: z.ZodObject<{
+        pending: z.ZodRecord<z.ZodString, z.ZodString>;
+        mapping: z.ZodRecord<z.ZodString, z.ZodString>;
+        callToChild: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>;
+    stateVersion: number;
+    init: () => {
+        pending: {};
+        mapping: {};
+        callToChild: {};
+    };
+    apply: (state: NoInfer<ProfileState>, event: SessionEvent) => ProfileState;
+    wire: {
+        viewSchema: z.ZodObject<{
+            children: z.ZodRecord<z.ZodString, z.ZodString>;
+            calls: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strict>;
+        view: (state: NoInfer<ProfileState>) => {
+            children: Record<string, string>;
+            calls: Record<string, string>;
+        };
+    };
+};
+/** `yaSubagentProgress` wire shape: live child progress for the parent's card. */
+export interface YaSubagentProgressProjection {
+    /** Number of `tool/call` events folded so far. */
+    readonly toolCallCount: number;
+    /** Cumulative token usage folded from `assistant/message.usage`. */
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead: number;
+        readonly cacheWrite: number;
+        readonly reasoning: number;
+    };
+    /** Lifecycle state derived from turn boundaries. */
+    readonly state: 'running' | 'idle' | 'settled';
+    /** Latest activity: a tool call or the finalized message text. */
+    readonly activity?: Activity;
+}
+/** Discriminated activity union: text or tool call. */
+export type Activity = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'tool';
+    readonly name: string;
+    readonly args?: string;
+};
+interface ProgressState {
+    readonly toolCallCount: number;
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead: number;
+        readonly cacheWrite: number;
+        readonly reasoning: number;
+    };
+    readonly state: 'running' | 'idle' | 'settled';
+    readonly activity?: Activity;
+}
+/**
+ * Fold the child session's own events into a compact progress view. Token
+ * usage accumulates from `assistant/message.usage` (cache fields are
+ * optional); tool calls are counted; lifecycle follows turn boundaries.
+ * Since dsh 0.1.5 the session log carries no streaming events — activity
+ * text updates only when a message finalizes.
+ */
+export declare const yaSubagentProgressProjection: {
+    key: "yaSubagentProgress";
+    stateSchema: z.ZodObject<{
+        toolCallCount: z.ZodNumber;
+        tokens: z.ZodObject<{
+            input: z.ZodNumber;
+            output: z.ZodNumber;
+            cacheRead: z.ZodNumber;
+            cacheWrite: z.ZodNumber;
+            reasoning: z.ZodNumber;
+        }, z.core.$strict>;
+        state: z.ZodUnion<readonly [z.ZodLiteral<"running">, z.ZodLiteral<"idle">, z.ZodLiteral<"settled">]>;
+        activity: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"tool">;
+            name: z.ZodString;
+            args: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>>;
+    }, z.core.$strict>;
+    stateVersion: number;
+    init: () => {
+        toolCallCount: number;
+        tokens: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+            reasoning: number;
+        };
+        state: "idle";
+    };
+    apply: (state: NoInfer<ProgressState>, event: SessionEvent) => ProgressState;
+    wire: {
+        viewSchema: z.ZodObject<{
+            toolCallCount: z.ZodNumber;
+            tokens: z.ZodObject<{
+                input: z.ZodNumber;
+                output: z.ZodNumber;
+                cacheRead: z.ZodNumber;
+                cacheWrite: z.ZodNumber;
+                reasoning: z.ZodNumber;
+            }, z.core.$strict>;
+            state: z.ZodUnion<readonly [z.ZodLiteral<"running">, z.ZodLiteral<"idle">, z.ZodLiteral<"settled">]>;
+            activity: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"text">;
+                text: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"tool">;
+                name: z.ZodString;
+                args: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>;
+        }, z.core.$strict>;
+        view: (state: NoInfer<ProgressState>) => ProgressState;
+    };
+};
+/** Convenience: the projection keys registered by this plugin. */
+export declare const PROJECTION_KEYS: readonly ["subagentProfile", "yaSubagentProgress"];
+/** Type-side declaration merges so consumers can read these keys via the projection registry. */
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionMap {
+        /** Parent-session map of childId → profileId. */
+        subagentProfile: SubagentProfileProjection;
+        /** Child-session live progress (toolcall count + token usage + state). */
+        yaSubagentProgress: YaSubagentProgressProjection;
+    }
+    interface SessionProjectionStateMap {
+        /** Host fold state behind {@link SubagentProfileProjection}. */
+        subagentProfile: ProfileState;
+        /** Host fold state behind {@link YaSubagentProgressProjection}. */
+        yaSubagentProgress: ProgressState;
+    }
+}
+export type { SessionEvent };

package/lib/types/repair.d.ts

@@ -1,66 +1,66 @@
-/**
- * One-shot session-log repair: physically REMOVE legacy `ya-subagent/started`
- * event rows so the harness persistence read path (`assertEventsSupported`)
- * loads the log again.
- *
- * Background: plugin versions ≤0.1.2 appended `ya-subagent/started` via
- * `session.append(...)`. `KNOWN_SESSION_EVENT_TYPES` is code-generated with no
- * plugin registration surface, and v0.1.2-alpha.1 refuses EVERY log row whose
- * type is outside that set — the old `ignorable` envelope flag no longer
- * exists, so stamping it (the ≤0.1.5 repair) cannot help. The only repair is
- * removal.
- *
- * Rows cannot simply be deleted: the read path enforces contiguous `seq`
- * numbers. This module therefore rewrites the log in place (after a `.bak`
- * backup):
- *
- *   - drops every `ya-subagent/started` row;
- *   - decrements the `seq` of every later ordinary event row (packed
- *     `text-chunks` / `reasoning-chunks` / `tool-call-chunks` storage rows
- *     shift their `seq0` instead);
- *   - shifts every `sourceEventSeqs` citation by the number of dropped rows
- *     ahead of it (dropped rows are never cited: only surface events carry
- *     provenance and they cite assistant chunks / surface nodes, which a
- *     plugin row never is).
- *
- * Two physical encodings (mirrors `session-persistence-jsonl`):
- *   - `.jsonl`        — plaintext, one JSON record per line.
- *   - `.jsonl.zstd`   — concatenated independent Zstandard frames: the first
- *                       frame holds the session header line, subsequent
- *                       frames each hold one append batch of event lines.
- *                       Each frame is independently decodable + checksummed.
- *                       The first frame containing a dropped row and every
- *                       frame after it are recompressed (their rows renumber);
- *                       untouched earlier frames are copied verbatim.
- *
- * Modified rows are re-encoded with `JSON.stringify`, which reproduces the
- * write path's canonical single-line form and preserves the parsed key order;
- * untouched lines stay byte-identical.
- *
- * Idempotent: a log with no target rows is left untouched (no backup, no
- * rewrite). A corrupt (unparsable) line is left untouched — that is the
- * harness's refusal job, not ours.
- *
- * @module @huanlin/dsh-plugin-yet-another-subagent/repair
- */
-/** Aggregate result of one repair run. */
-export interface RepairStats {
-    /** Session log files examined (`.jsonl` + `.jsonl.zstd`). */
-    readonly scanned: number;
-    /** Files rewritten because at least one target row was removed. */
-    readonly repaired: number;
-    /** Files with no target rows (already clean). */
-    readonly skipped: number;
-    /** Per-file errors (path + message); empty on a clean run. */
-    readonly errors: readonly {
-        readonly path: string;
-        readonly message: string;
-    }[];
-}
-/**
- * Recursively repair every session log under `sessionsRoot`.
- *
- * @param sessionsRoot - absolute path to `$DSH_HOME/sessions`.
- * @returns aggregate stats. Never throws — per-file failures land in `errors`.
- */
-export declare function repairSessions(sessionsRoot: string): Promise<RepairStats>;
+/**
+ * One-shot session-log repair: physically REMOVE legacy `ya-subagent/started`
+ * event rows so the harness persistence read path (`assertEventsSupported`)
+ * loads the log again.
+ *
+ * Background: plugin versions ≤0.1.2 appended `ya-subagent/started` via
+ * `session.append(...)`. `KNOWN_SESSION_EVENT_TYPES` is code-generated with no
+ * plugin registration surface, and v0.1.2-alpha.1 refuses EVERY log row whose
+ * type is outside that set — the old `ignorable` envelope flag no longer
+ * exists, so stamping it (the ≤0.1.5 repair) cannot help. The only repair is
+ * removal.
+ *
+ * Rows cannot simply be deleted: the read path enforces contiguous `seq`
+ * numbers. This module therefore rewrites the log in place (after a `.bak`
+ * backup):
+ *
+ *   - drops every `ya-subagent/started` row;
+ *   - decrements the `seq` of every later ordinary event row (packed
+ *     `text-chunks` / `reasoning-chunks` / `tool-call-chunks` storage rows
+ *     shift their `seq0` instead);
+ *   - shifts every `sourceEventSeqs` citation by the number of dropped rows
+ *     ahead of it (dropped rows are never cited: only surface events carry
+ *     provenance and they cite assistant chunks / surface nodes, which a
+ *     plugin row never is).
+ *
+ * Two physical encodings (mirrors `session-persistence-jsonl`):
+ *   - `.jsonl`        — plaintext, one JSON record per line.
+ *   - `.jsonl.zstd`   — concatenated independent Zstandard frames: the first
+ *                       frame holds the session header line, subsequent
+ *                       frames each hold one append batch of event lines.
+ *                       Each frame is independently decodable + checksummed.
+ *                       The first frame containing a dropped row and every
+ *                       frame after it are recompressed (their rows renumber);
+ *                       untouched earlier frames are copied verbatim.
+ *
+ * Modified rows are re-encoded with `JSON.stringify`, which reproduces the
+ * write path's canonical single-line form and preserves the parsed key order;
+ * untouched lines stay byte-identical.
+ *
+ * Idempotent: a log with no target rows is left untouched (no backup, no
+ * rewrite). A corrupt (unparsable) line is left untouched — that is the
+ * harness's refusal job, not ours.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/repair
+ */
+/** Aggregate result of one repair run. */
+export interface RepairStats {
+    /** Session log files examined (`.jsonl` + `.jsonl.zstd`). */
+    readonly scanned: number;
+    /** Files rewritten because at least one target row was removed. */
+    readonly repaired: number;
+    /** Files with no target rows (already clean). */
+    readonly skipped: number;
+    /** Per-file errors (path + message); empty on a clean run. */
+    readonly errors: readonly {
+        readonly path: string;
+        readonly message: string;
+    }[];
+}
+/**
+ * Recursively repair every session log under `sessionsRoot`.
+ *
+ * @param sessionsRoot - absolute path to `$DSH_HOME/sessions`.
+ * @returns aggregate stats. Never throws — per-file failures land in `errors`.
+ */
+export declare function repairSessions(sessionsRoot: string): Promise<RepairStats>;