@huanlin/dsh-plugin-yet-another-subagent 0.1.3 → 0.1.5

package/lib/types/client/SettingsPage.d.ts

@@ -0,0 +1,49 @@
+/**
+ * SettingsPage — the `ya-subagent` settings section: profile list CRUD.
+ *
+ * Visual language: matches ModelsSection / GeneralSection — outlined rowCard
+ * per profile (border-l2, r12, p12/14), filled editor surface
+ * (bg-module-platform, r12, p14/16), capsule controls (h36 r18 primary,
+ * h28 r14 secondary), 32px fields with border-l2 / bg-layer-1, 12/18 caption
+ * labels. Every color resolves through --dsw-alias-* tokens.
+ *
+ * Each profile card is collapsible (chevron in the row head); the editor
+ * surface is hidden when collapsed. Builtin profiles (cordis.yml seed) carry
+ * a `builtin`/`内置` badge next to the title. The "+ Add subagent" button at
+ * the bottom reveals an inline draft card with all fields editable (including
+ * id) and Create / Cancel actions.
+ *
+ * The persona field is a radio (inherit deployment persona vs custom text);
+ * the textarea is shown only when custom. The tool filter is a select
+ * (none / allow / deny); a multi-select dropdown is shown only when allow or
+ * deny is picked, populated from `tools.list` (the host's current
+ * `ctx.tools.schemas()`).
+ *
+ * Pulls the profile list once on mount via `connection.rpc.call('/ya-subagent',
+ * 'profiles.list')`, dispatches add/update/remove through the
+ * same RPC. The toolview slot is keyed by `subagent` and registered once at
+ * plugin load, so profile mutations do not need to re-register slots.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/client/SettingsPage
+ */
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ClientConnectionRpc } from '@deepseek-ai/dsh-client-connection/client';
+import type { SubagentProfile } from '../types.ts';
+/** Inject face: RPC handle + locale translate. */
+export interface YaSubagentSettingsInjected {
+    readonly rpc: ClientConnectionRpc;
+    /** Refetch the profile list from the host. */
+    readonly fetchProfiles: () => Promise<readonly SubagentProfile[]>;
+    /** Bound locale translator for the ya-subagent namespace. */
+    readonly t: (key: string) => string;
+}
+/** Full props: settings.section runtime share + locale seat + inject. */
+type SettingsPageProps = PropsRuntime<'settings.section'> & PropsLocale<'ya-subagent'> & YaSubagentSettingsInjected;
+/**
+ * Render the subagent profiles settings page.
+ * @param props - settings.section runtime share + locale + inject.
+ * @returns the page element.
+ */
+export declare function SettingsPage({ rpc, fetchProfiles, t }: SettingsPageProps): import("react").JSX.Element;
+export {};

package/lib/types/client/SubagentCard.d.ts

@@ -0,0 +1,56 @@
+/**
+ * SubagentCard — the model-facing toolcall card for the `subagent` tool.
+ *
+ * Three display branches:
+ *   1. **Running** (block is `RunningToolCall`): the tool call is in flight.
+ *      Show "running" with a spinner dot; no child session to subscribe to.
+ *   2. **Continuable settled** (result text matches `started <label>
+ *      subagent <id>`): subscribe to the child's `yaSubagentProgress`
+ *      projection for live toolcall/token counts; clickable to open.
+ *   3. **Foreground settled** (result text is the child's output): the
+ *      one-shot child has completed; show "completed" with an output
+ *      preview. No child session survives.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/client/SubagentCard
+ */
+import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client';
+import type { InjectFace, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+/** Sessions service shape consumed by this card (narrow face of ISessions). */
+export interface SubagentCardSessions {
+    binding(id: string): {
+        session: {
+            projections: {
+                faceOf(key: string): {
+                    getSnapshot(): unknown;
+                    subscribe(fn: () => void): () => void;
+                } | undefined;
+            };
+        };
+    } | undefined;
+    openSubagent(address: {
+        parentSessionId: string;
+        childSessionId: string;
+        mode: 'continuable' | 'one-shot';
+    }): void;
+    subagentAddress(id: string): {
+        parentSessionId: string;
+        childSessionId: string;
+        mode: 'continuable' | 'one-shot';
+    } | undefined;
+    refreshSubagents(parentSessionId: string): Promise<void>;
+}
+/** Inject face: the sessions service handle + profile label lookup. */
+export type SubagentCardInjected = {
+    sessions: SubagentCardSessions;
+    /** Resolve a profile id to its display label; undefined if unknown. */
+    profileLabelOf: (id: string) => string | undefined;
+};
+/** Full props: toolview runtime share + this package's locale seat + inject. */
+type SubagentCardProps = ToolCallViewProps & PropsLocale<'ya-subagent'> & InjectFace<SubagentCardInjected>;
+/**
+ * Render one `subagent` tool call as a compact live card.
+ * @param props - keyed toolview payload + locale seat + sessions inject.
+ * @returns the dedicated subagent card.
+ */
+export declare function SubagentCard({ block, callId, toolName, sessionId, sessions, profileLabelOf, t }: SubagentCardProps): import("react").JSX.Element;
+export {};

package/lib/types/client/SubagentTreeView.d.ts

@@ -0,0 +1,63 @@
+/**
+ * SubagentTreeView — a `conversation.view` entry showing the root session's
+ * full subagent tree (all depths) with live progress.
+ *
+ * Uses `sessions.subagentsByParent` (the catalog) as the primary tree
+ * structure source — this works for ALL depths without needing per-session
+ * bindings. `setSubagentCatalogOpen` keeps catalogs auto-refreshing.
+ * Projections (`yaSubagentProgress`) are used additionally when a session
+ * binding is available (current session + opened children) for richer data.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/client/SubagentTreeView
+ */
+import type { ConvViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { InjectFace, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+/** Catalog entry shape (narrow face of SubagentListEntry). */
+interface CatalogEntry {
+    readonly kind: string;
+    readonly id: string;
+    readonly mode?: string;
+    readonly activity?: string;
+    readonly hasChildren?: boolean;
+    readonly label?: string;
+}
+/** Sessions service shape consumed by this view. */
+interface TreeSessions {
+    binding(id: string): {
+        session: {
+            projections: {
+                faceOf(key: string): {
+                    getSnapshot(): unknown;
+                    subscribe(fn: () => void): () => void;
+                } | undefined;
+            };
+        };
+    } | undefined;
+    openSubagent(address: {
+        parentSessionId: string;
+        childSessionId: string;
+        mode: 'continuable' | 'one-shot';
+    }): void;
+    subagentAddress(id: string): {
+        parentSessionId: string;
+        childSessionId: string;
+        mode: 'continuable' | 'one-shot';
+    } | undefined;
+    refreshSubagents(parentSessionId: string): Promise<void>;
+    setSubagentCatalogOpen(parentSessionId: string, open: boolean): void;
+    subagentsByParent: Readonly<Record<string, {
+        entries: readonly CatalogEntry[];
+        parentAvailable: boolean;
+    }>>;
+}
+export type SubagentTreeViewInjected = {
+    sessions: TreeSessions;
+    profileLabelOf: (id: string) => string | undefined;
+};
+type SubagentTreeViewProps = ConvViewProps & PropsLocale<'ya-subagent'> & InjectFace<SubagentTreeViewInjected>;
+/**
+ * Render the subagent tree view. Always shows the ROOT session's full tree;
+ * highlights the current session if it is a subagent.
+ */
+export declare function SubagentTreeView({ sessionId, sessions, profileLabelOf, t }: SubagentTreeViewProps): import("react").JSX.Element;
+export {};

package/lib/types/client/dictionaries.d.ts

@@ -0,0 +1,17 @@
+/**
+ * dictionaries.ts — the 19 better-locale override languages for the
+ * yet-another-subagent copy, keyed by language id. Each dictionary carries
+ * the same key set as `en`/`zh` in `./locales.ts` (enforced by the
+ * `Record<YaSubagentKey, string>` annotation); values keep `{placeholder}`
+ * interpolation, matching the better-locale store's `LocaleDict` contract.
+ *
+ * The apply function registers these into `ctx.betterLocale` (the override
+ * store) under `NS`, so when the user selects an override language through
+ * dsh-plugin-better-locale (and DSH is on 'en', whose slot the override
+ * borrows), the plugin UI renders in the override language.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/client/dictionaries
+ */
+import type { YaSubagentKey } from './locales.ts';
+/** All override-language dictionaries for the `ya-subagent` namespace. */
+export declare const dicts: Record<string, Record<YaSubagentKey, string>>;

package/lib/types/client/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * yet-another-subagent — browser half.
+ *
+ * Single bundle, dual entry: this is the client half (exports `./client`).
+ * Host half ships via `.` (see `src/index.ts`).
+ *
+ * Two registrations:
+ *   1. `settings.section` slot — the profile editor page (SettingsPage).
+ *   2. `tool.call.toolview` keyed slot, key `subagent` — the live toolcall
+ *      card (SubagentCard). A single key covers all profiles because the
+ *      tool name is always `subagent`; the profile is a call parameter.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/client
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type YaSubagentKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The subagent settings page + tool card copy. */
+        'ya-subagent': YaSubagentKey;
+    }
+}
+/** Required services: settings/tool slots, locale, sessions, connection. */
+export declare const inject: string[];
+/**
+ * Client plugin body: register settings page + single `subagent` toolview slot.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Locale dictionaries for yet-another-subagent.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/client/locales
+ */
+/** All copy keys for the ya-subagent namespace. */
+export type YaSubagentKey = 'nav' | 'page.title' | 'page.empty' | 'page.add' | 'page.add.placeholder.id' | 'page.add.placeholder.label' | 'page.add.submit' | 'page.add.error' | 'page.add.cancel' | 'row.label' | 'row.id' | 'row.model.kind.auto' | 'row.model.kind.manual' | 'row.model.provider' | 'row.model.model' | 'row.model.provider.placeholder' | 'row.model.model.placeholder' | 'row.model.noModels' | 'row.persona' | 'row.persona.kind.inherit' | 'row.persona.kind.custom' | 'row.persona.text' | 'row.toolFilter' | 'row.toolFilter.kind.none' | 'row.toolFilter.kind.allow' | 'row.toolFilter.kind.deny' | 'row.toolFilter.tools' | 'row.toolFilter.tools.search' | 'row.toolFilter.tools.empty' | 'row.toolFilter.tools.selected' | 'row.toolFilter.tools.selectAll' | 'row.toolFilter.tools.clear' | 'row.maxDepth' | 'row.delete' | 'row.delete.confirm' | 'row.save' | 'row.saved' | 'row.error' | 'row.expand' | 'row.collapse' | 'badge.builtin' | 'card.starting' | 'card.waiting' | 'card.idle' | 'card.running' | 'card.completed' | 'card.child-running' | 'card.child-idle' | 'card.toolcalls' | 'card.tokens' | 'card.calling' | 'card.open' | 'card.unavailable' | 'tree.tab' | 'tree.empty' | 'tree.rootHint' | 'tree.toolcalls' | 'tree.tokens' | 'tree.calling' | 'tree.state.running' | 'tree.state.idle' | 'tree.state.settled' | 'repair.button' | 'repair.confirm.title' | 'repair.confirm.body' | 'repair.confirm.warning' | 'repair.confirm.cancel' | 'repair.confirm.proceed' | 'repair.running' | 'repair.result.title' | 'repair.result.scanned' | 'repair.result.repaired' | 'repair.result.skipped' | 'repair.result.errors' | 'repair.result.errorEntry' | 'repair.result.close' | 'repair.error';
+/** Locale namespace id. */
+export declare const NS = "ya-subagent";
+/** English dictionary. */
+export declare const en: Record<YaSubagentKey, string>;
+/** Chinese dictionary. */
+export declare const zh: Record<YaSubagentKey, string>;

package/lib/types/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * yet-another-subagent — host plugin entry.
+ *
+ * Single bundle, dual entry: this is the host half (exports `.`). The browser
+ * half ships via `./client` (see `src/client/index.ts`).
+ *
+ * Architecture (design doc §1):
+ *   - A single `subagent` tool is exposed to the model. The desired profile
+ *     is selected via the `profile` parameter (enum of profile ids). Profile
+ *     add/remove updates the enum without changing the tool name set.
+ *   - The tool reuses the official `spawn` provider via `ctx.subagents.startContinuable`.
+ *   - Profiles live in an in-memory `ProfileStore` mutated through RPC.
+ *   - Two projections (`subagentProfile` on parent, `yaSubagentProgress` on
+ *     child) bridge the single-stage client runtime so SubagentCard can
+ *     subscribe to live child progress.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent
+ */
+import type { Context } from 'cordis';
+import z from 'schemastery';
+import type { YaSubagentConfig } from './types.ts';
+export declare const name = "yet-another-subagent";
+export declare const inject: string[];
+export type { SubagentProfile, YaSubagentConfig } from './types.ts';
+/** Settings namespace under which profile state persists (`$DSH_HOME/settings.yaml`). */
+export declare const SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export interface Config extends YaSubagentConfig {
+}
+export declare const Config: z<Config>;
+/**
+ * Plugin body: register profile tools, RPC, and projections.
+ *
+ * Persistence: when a settings service is mounted, the profile list lives
+ * under the `ya-subagent` namespace in `$DSH_HOME/settings.yaml`. The
+ * cordis.yml `profiles` field is the composition `base` (first-boot seed);
+ * runtime mutations persist through `scope.replace()`. Headless assemblies
+ * without a settings provider fall back to in-memory state (cordis.yml seed
+ * only, no persistence).
+ * @param ctx - host context carrying `tools`, `subagents`, `sessionProjections`.
+ * @param config - resolved config (seed profiles + generalFixed).
+ */
+export declare function apply(ctx: Context, config: Config): void;

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@huanlin/dsh-plugin-yet-another-subagent`.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/invariant
+ */
+import type { Context } from 'cordis';
+/** Cordis companion plugin name. */
+export declare const name = "yet-another-subagent-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/lib/types/profile-store.d.ts

@@ -0,0 +1,59 @@
+/**
+ * In-memory profile store with CRUD. Backed by `ctx.settings` when a settings
+ * service is mounted (persists to `$DSH_HOME/settings.yaml` under the
+ * `ya-subagent` namespace); falls back to a plain Map in headless assemblies
+ * where no settings provider is available (cordis.yml seed only, no
+ * persistence).
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/profile-store
+ */
+import type { SettingsScope } from '@deepseek-ai/dsh-settings';
+import type { SubagentProfile, YaSubagentConfig } from './types.ts';
+/** CRUD result for RPC: the success branch carries the latest list. */
+export type ProfileMutationResult = {
+    readonly ok: true;
+    readonly profiles: readonly SubagentProfile[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** Shape stored under the `ya-subagent` settings namespace. */
+export interface YaSubagentSettings {
+    readonly profiles: readonly SubagentProfile[];
+    readonly generalFixed: boolean;
+}
+/**
+ * Mutable profile store. Owns the canonical list; tool registration and RPC
+ * handlers share one instance per plugin fiber. When `scope` is set, every
+ * mutation persists through `scope.update`; otherwise the store is in-memory
+ * only (cordis.yml seed, lost on unload).
+ */
+export declare class ProfileStore {
+    private readonly profiles;
+    /** Whether `general` is locked (cannot be removed). */
+    readonly generalFixed: boolean;
+    /** Optional settings scope for persistence; absent in headless mode. */
+    private scope;
+    constructor(seed: YaSubagentConfig);
+    /**
+     * Attach a settings scope. Subsequent mutations persist through it; the
+     * initial in-memory state is replaced with the scope's resolved value
+     * (which layers schema defaults, the composition `base`, and the user
+     * document).
+     */
+    attachScope(scope: SettingsScope<YaSubagentSettings>): void;
+    /** Reload the in-memory map from the settings scope's current resolved value. */
+    reloadFromScope(): void;
+    /** Snapshot of all profiles, in insertion order. */
+    list(): readonly SubagentProfile[];
+    /** Look up one profile by id. */
+    get(id: string): SubagentProfile | undefined;
+    /** Add a new profile. Returns failure for duplicate id or invalid shape. */
+    add(profile: SubagentProfile): ProfileMutationResult;
+    /** Update an existing profile. Returns failure if the id is unknown. */
+    update(profile: SubagentProfile): ProfileMutationResult;
+    /** Remove a profile. Returns failure for unknown id or protected `general`. */
+    remove(id: string): ProfileMutationResult;
+    /** Persist the current list through the attached settings scope (fire-and-forget; errors logged). */
+    private persist;
+}

package/lib/types/projection.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 };

package/lib/types/repair.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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>;

package/lib/types/rpc.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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;

package/lib/types/tool-factory.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Tool factory: compile the profile list into a single `defineTool` definition.
+ *
+ * One `subagent` tool is exposed to the model regardless of how many profiles
+ * are configured. The desired profile is selected via the `profile` parameter
+ * (an enum of available profile ids). This keeps the tool surface flat — the
+ * model learns one tool, not N — and profile add/remove does not change the
+ * tool name set the model was trained against.
+ *
+ * Two profile-specific extensions are preserved from the per-profile design:
+ *   1. The continuable result content embeds `profileLabel` so SubagentCard
+ *      can render with zero RPC (SkillRow paradigm, design doc §4.4).
+ *   2. The `profile` parameter enum lists the live profile ids.
+ *
+ * Foreground (one-shot) path is kept for `run_in_background: false`; the
+ * default is continuable background.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/tool-factory
+ */
+import type { Context } from 'cordis';
+import type { SubagentProvider, SubagentResult, SubagentRun } from '@deepseek-ai/dsh-subagent';
+import type { JobOutcome } from '@deepseek-ai/dsh-jobs';
+import type { SubagentProfile } from './types.ts';
+/** Merge-extensible session event: child started for a tool call. */
+declare module '@deepseek-ai/dsh-session' {
+    interface SessionEventMap {
+        'ya-subagent/started': {
+            callId: string;
+            childId: string;
+            profileId: string;
+        };
+    }
+}
+/** Settle pending startup without rejecting the task producer contract. */
+declare function settleStart(start: Promise<SubagentRun>, signal: AbortSignal): Promise<JobOutcome>;
+/**
+ * Build the single model-facing `subagent` tool definition.
+ *
+ * @param profiles - the live profile list (drives the `profile` enum).
+ * @param ctx - host context carrying `subagents` (and `jobs` for one-shot background).
+ * @returns a `defineTool` definition ready for `ctx.tools.register`.
+ */
+export declare function buildTool(profiles: readonly SubagentProfile[], ctx: Context): import("@deepseek-ai/dsh-tools").ToolDefinition;
+export { settleStart };
+export type { SubagentProvider, SubagentResult, SubagentRun, JobOutcome };