@huanlin/dsh-plugin-yet-another-subagent 0.1.6 → 0.4.0

package/lib/types/projection.d.ts

@@ -1,103 +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.
- *
- * @module @huanlin/dsh-plugin-yet-another-subagent/projection
- */
-import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
-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`. */
-interface ProfileState {
-    /** callId → profileId, awaiting the matching `tool/result`. */
-    readonly pending: Map<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: ProjectionDefinition<'subagentProfile', ProfileState>;
-/** `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: ProjectionDefinition<'yaSubagentProgress', ProgressState>;
-/** Convenience: the projection keys registered by this plugin. */
-export declare const PROJECTION_KEYS: readonly ["subagentProfile", "yaSubagentProgress"];
-/** Type-side declaration merge 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. Empty object when no children yet. */
-        subagentProfile: SubagentProfileProjection;
-        /** Child-session live progress (toolcall count + token usage + state). */
-        yaSubagentProgress: YaSubagentProgressProjection;
-    }
-}
-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,49 +1,66 @@
-/**
- * One-shot session-log repair: stamp `"ignorable": true` onto legacy
- * `ya-subagent/started` events so the harness persistence read path
- * (`assertEventsSupported`) will skip them instead of refusing the whole log.
- *
- * Background: older plugin versions wrote `ya-subagent/started` via
- * `session.append(...)`, but `session.append` cannot set the `ignorable`
- * envelope flag, and `KNOWN_SESSION_EVENT_TYPES` is code-generated with no
- * plugin registration surface. The read path therefore refuses any log
- * containing the type unless each occurrence carries `ignorable: true`.
- * This module rewrites on-disk artifacts in place (after a `.bak` backup) to
- * add that flag to every `ya-subagent/started` row missing it.
- *
- * 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.
- *                       Only frames whose decoded plaintext contains a target
- *                       row are recompressed; untouched frames are copied
- *                       verbatim so byte-identity is preserved where possible.
- *
- * Idempotent: rows already carrying `ignorable: true` are skipped; files with
- * no target rows are left untouched (no backup, no rewrite).
- *
- * @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 patched. */
-    readonly repaired: number;
-    /** Files with no patchable rows (already clean or no target events). */
-    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>;

package/lib/types/rpc.d.ts

@@ -1,59 +1,69 @@
-/**
- * RPC handler: profile list CRUD + tool list on a dedicated `/ya-subagent`
- * channel registered via `ctx.connection.rpc.handle('/ya-subagent', ...)`.
- *
- * A dedicated channel avoids the single-interceptor limit on the shared `/api`
- * channel (the Typert gateway owns that slot; staking it here would shadow
- * `commands/execute` and every other `/api` endpoint).
- *
- * Endpoints (all POST, payload shape noted):
- *   - `profiles.list`   payload: {}                          → { profiles: SubagentProfile[] }
- *   - `profiles.add`    payload: { profile: SubagentProfile } → { profiles: ... } | error
- *   - `profiles.update` payload: { profile: SubagentProfile } → { profiles: ... } | error
- *   - `profiles.remove` payload: { id: string }              → { profiles: ... } | error
- *   - `tools.list`      payload: {}                          → { tools: { name, description }[] }
- *
- * Returns the existing RpcResult shape; business errors use the `internal`
- * code with a descriptive message (the RpcError code union is closed; we do
- * not extend it for plugin-specific failures — see design doc §3.5).
- *
- * @module @huanlin/dsh-plugin-yet-another-subagent/rpc
- */
-import type { Context } from 'cordis';
-import type { SubagentProfile } from './types.ts';
-import type { ProfileStore } from './profile-store.ts';
-import { type RepairStats } from './repair.ts';
-/** Wire shape for `profiles.list` responses. */
-export interface ProfileListResponse {
-    readonly profiles: readonly SubagentProfile[];
-}
-/** Wire shape for `tools.list` responses. */
-export interface ToolListResponse {
-    readonly tools: readonly {
-        readonly name: string;
-        readonly description: string;
-    }[];
-}
-/** Wire shape for `profiles.add` request payload. */
-export interface ProfileAddPayload {
-    readonly profile: SubagentProfile;
-}
-/** Wire shape for `profiles.update` request payload. */
-export interface ProfileUpdatePayload {
-    readonly profile: SubagentProfile;
-}
-/** Wire shape for `profiles.remove` request payload. */
-export interface ProfileRemovePayload {
-    readonly id: string;
-}
-/** All ya-subagent RPC endpoint result values. */
-export type YaSubagentValue = ProfileListResponse | ToolListResponse | RepairStats;
-/**
- * Register the ya-subagent RPC channel on the host's connection service.
- * `connection` is in the plugin's inject list, so `ctx.connection` is
- * directly available; the channel route rolls back on fiber disposal
- * (the inner `owner.effect` owns cleanup).
- * @param ctx - host context.
- * @param store - profile store.
- */
-export declare function registerRpc(ctx: Context, store: ProfileStore): void;
+/**
+ * RPC surface: profile list CRUD + tool list + session repair, exposed as
+ * exact Fetch routes on the shared `/api` channel via
+ * `ctx.connection.fetch.register(...)`.
+ *
+ * Why not a dedicated `rpc.handle` channel: the host-side dedicated-channel
+ * registry resolves `webServer` through the connection service's origin
+ * context chain, and the web profile mounts the webserver as a sibling
+ * loader row — never an ancestor of client-connection — so every dedicated
+ * channel fails to register with `cannot get property "webServer" without
+ * inject`. Exact Fetch routes dispatch inside the already-mounted `/api`
+ * carrier instead (the dsh-client-file-upload pattern), inheriting its
+ * Host/Origin trust fence and browser authentication for free, and the
+ * shared `/api` interceptor slot stays owned by the Typert gateway.
+ *
+ * Wire endpoints (all POST; URL path `/api/ya-subagent.<endpoint>`, body and
+ * response use the Connection client-request / server-response envelopes):
+ *   - `ya-subagent.profiles.list`    payload: {}                            → { profiles: SubagentProfile[] }
+ *   - `ya-subagent.profiles.add`     payload: { profile: SubagentProfile }  → { profiles: ... } | error
+ *   - `ya-subagent.profiles.update`  payload: { profile: SubagentProfile }  → { profiles: ... } | error
+ *   - `ya-subagent.profiles.remove`  payload: { id: string }                → { profiles: ... } | error
+ *   - `ya-subagent.tools.list`       payload: {}                            → { tools: { name, description }[] }
+ *   - `ya-subagent.sessions.repair`  payload: {}                            → RepairStats | error
+ *
+ * Returns the existing RpcResult shape; business errors use the `internal`
+ * code with a descriptive message (the RpcError code union is closed; we do
+ * not extend it for plugin-specific failures — see design doc §3.5).
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/rpc
+ */
+import type { Context } from 'cordis';
+import type { SubagentProfile } from './types.ts';
+import type { ProfileStore } from './profile-store.ts';
+import { type RepairStats } from './repair.ts';
+/** Wire shape for `profiles.list` responses. */
+export interface ProfileListResponse {
+    readonly profiles: readonly SubagentProfile[];
+}
+/** Wire shape for `tools.list` responses. */
+export interface ToolListResponse {
+    readonly tools: readonly {
+        readonly name: string;
+        readonly description: string;
+    }[];
+}
+/** Wire shape for `profiles.add` request payload. */
+export interface ProfileAddPayload {
+    readonly profile: SubagentProfile;
+}
+/** Wire shape for `profiles.update` request payload. */
+export interface ProfileUpdatePayload {
+    readonly profile: SubagentProfile;
+}
+/** Wire shape for `profiles.remove` request payload. */
+export interface ProfileRemovePayload {
+    readonly id: string;
+}
+/** All ya-subagent RPC endpoint result values. */
+export type YaSubagentValue = ProfileListResponse | ToolListResponse | RepairStats;
+/**
+ * Register the ya-subagent RPC routes on the host's connection service.
+ * `connection` is provided by the host; the routes roll back with the
+ * plugin fiber (each `fetch.register` disposer is collected by an effect).
+ * Trust and browser authentication live on the physical `/api` carrier, so
+ * the routes carry no authority options of their own.
+ * @param ctx - host context.
+ * @param store - profile store.
+ */
+export declare function registerRpc(ctx: Context, store: ProfileStore): void;