@huanlin/dsh-plugin-yet-another-subagent 0.1.2 → 0.1.4

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 };

package/lib/types/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Profile data model for yet-another-subagent.
+ *
+ * @module @huanlin/dsh-plugin-yet-another-subagent/types
+ */
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+/** A model-facing tool name is `subagent_<id>`. */
+export interface SubagentProfile {
+    /** Unique id; lowercase letters, digits, hyphens; 1–32 chars. Used as `subagent_<id>`. */
+    readonly id: string;
+    /** Display name (nav label / card title). */
+    readonly label: string;
+    /**
+     * Model selection. `kind: 'auto'` inherits the parent model (provider/model
+     * are ignored); `kind: 'manual'` pins a specific provider/model.
+     */
+    readonly model: {
+        readonly kind: 'auto' | 'manual';
+        readonly provider: string;
+        readonly model: string;
+    };
+    /**
+     * Persona selection. `kind: 'inherit'` omits the per-child persona so the
+     * child uses the deployment `system-prompt` persona (same as the official
+     * `tool-subagent` default when no `persona` is configured). `kind: 'custom'`
+     * shadows the deployment persona with the provided text.
+     */
+    readonly persona: {
+        readonly kind: 'inherit';
+    } | {
+        readonly kind: 'custom';
+        readonly text: string;
+    };
+    /**
+     * Tool filter selection. `kind: 'none'` applies no filter (child sees every
+     * visible global tool). `kind: 'allow'` keeps only the named tools;
+     * `kind: 'deny'` removes the named tools. The chosen tools are only sent to
+     * the provider when `kind` is not `'none'`.
+     */
+    readonly toolFilter: {
+        readonly kind: 'none';
+    } | {
+        readonly kind: 'allow';
+        readonly tools: readonly string[];
+    } | {
+        readonly kind: 'deny';
+        readonly tools: readonly string[];
+    };
+    /** Maximum delegation depth (non-negative safe integer); default 3. */
+    readonly maxDepth: number;
+    /**
+     * Background policy when `run_in_background: true` is set. `'continuable'`
+     * (default, matches the base bundle) starts a background subagent that keeps
+     * its conversation — the caller receives only its subagent id and sends more
+     * work via `send_message`. `'one-shot'` starts a background task that returns
+     * a job id — the caller collects the result with `job_output` and stops it
+     * with `job_kill`.
+     */
+    readonly backgroundMode: 'continuable' | 'one-shot';
+    /**
+     * Whether this profile is part of the bundle seed (cordis.patch.yml) and
+     * therefore labelled `builtin` in the UI. User-added profiles are `false`.
+     * Builtin profiles can still be edited or removed (unless `generalFixed`
+     * protects them); the flag is purely a presentation hint.
+     */
+    readonly builtin: boolean;
+}
+/** Top-level config. */
+export interface YaSubagentConfig {
+    /** Initial profile list (cordis.yml layer). Runtime mutations live in memory only. */
+    readonly profiles: readonly SubagentProfile[];
+    /** When true, the `general` profile cannot be removed. */
+    readonly generalFixed: boolean;
+}
+/**
+ * Coerce a possibly-stale profile shape (from an older `settings.yaml` or a
+ * caller that still uses the legacy `persona?: string` / `toolFilter?: { allow?, deny? }`
+ * form) into the current {@link SubagentProfile} shape. Idempotent on already-
+ * current shapes.
+ *
+ * Rules:
+ *   - `persona: undefined | '' | null` → `{ kind: 'inherit' }`
+ *   - `persona: string` (non-empty) → `{ kind: 'custom', text }`
+ *   - `persona: { kind: 'inherit' }` → as-is
+ *   - `persona: { kind: 'custom', text }` → as-is (text trimmed; empty → inherit)
+ *   - `toolFilter: undefined | null` → `{ kind: 'none' }`
+ *   - `toolFilter: { allow: [...], deny: [...] }` → allow wins if non-empty, else deny, else none
+ *   - `toolFilter: { kind: 'none' | 'allow' | 'deny', tools? }` → as-is (tools defaulted to [])
+ *   - `builtin: undefined | null` → `false`
+ */
+export declare function migrateProfile(input: unknown): SubagentProfile;
+/** Derive agentOptions from a profile's model selection. */
+export declare function agentOptionsFor(profile: SubagentProfile): {
+    readonly agentOptions?: AgentOptions;
+};
+/**
+ * Project the persona field onto the request shape: `undefined` for `inherit`
+ * (omit the field so the child uses the deployment persona) and the text for
+ * `custom`.
+ */
+export declare function personaForRequest(profile: SubagentProfile): {
+    readonly persona?: string;
+};
+/**
+ * Project the toolFilter field onto the request shape: `undefined` for `none`
+ * (omit the field so the child sees every visible tool) and the allow/deny
+ * pair for `allow`/`deny`.
+ */
+export declare function toolFilterForRequest(profile: SubagentProfile): {
+    readonly toolFilter?: {
+        readonly allow?: readonly string[];
+        readonly deny?: readonly string[];
+    };
+};
+/** Validate a profile id: lowercase letters, digits, hyphens; 1–32 chars. */
+export declare function isValidProfileId(id: string): boolean;