@dsh-cc/subagent-task 0.5.0

package/lib/catalog.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The per-agent "Available subagents" system-prompt section.
+ *
+ * A single global section (mount once on the root context) serves every
+ * agent: the text callback receives the assembling agent through
+ * `AssembleContext.scope` (the agent loop passes `scope: agent`) and renders
+ * that agent's workspace `.claude/agents` definitions. Because `text()` is a
+ * synchronous callback it cannot `await` discovery, so the section renders
+ * from a snapshot cache that a fire-and-forget `registry.ensure(cwd)` populates
+ * in the background. An `system-prompt/assemble` waterfall listener
+ * reconciles the placeholder in the same assembly: for a scope whose
+ * snapshot has not landed it joins the in-flight discovery (bounded), stores
+ * the snapshot, and re-renders the section with the same render function, so
+ * the FIRST assembly already carries the real catalog and no later request
+ * sees a different prefix; on timeout the placeholder ships and the
+ * `system-prompt/change` path lands the catalog on a later assembly. When a
+ * workspace defines no agents of its own (or there is no agent to scope to)
+ * the section still lists the bundled agents, or renders an empty string when
+ * there is nothing to scope to.
+ *
+ * @module @dsh-cc/subagent-task/catalog
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AgentDefinition } from '@dsh-cc/claude-code-agents';
+import type { AgentRegistry } from './registry.ts';
+/** Default order slot for the catalog section (tool guidance owns 100–199). */
+export declare const CATALOG_SECTION_ORDER = 110;
+/** The section's unique name. */
+export declare const CATALOG_SECTION_NAME = "cc:subagent-catalog";
+/**
+ * Owner of the cached catalog section text. Holds one sorted definition list
+ * per workspace root so the synchronous section provider can compose the text,
+ * and fills each root's snapshot from a background `registry.ensure`.
+ */
+export declare class AgentCatalogSection {
+    private readonly ctx;
+    private readonly registry;
+    /** Sorted definitions per workspace root, populated once discovery lands. */
+    private readonly snapshot;
+    /** Roots whose background discovery has already been kicked off. */
+    private readonly seen;
+    /**
+     * Create a catalog cache holder bound to a registry.
+     * @param ctx - the host context whose `system-prompt` seam and
+     *   `system-prompt/change` channel drive refresh.
+     * @param registry - the per-workspace definition cache to load from.
+     */
+    constructor(ctx: Context, registry: AgentRegistry);
+    /** Register the catalog section plus its assemble-waterfall reconciliation.
+     *
+     * The seam is fetched with `ctx.get` rather than the `ctx.systemPrompt`
+     * property: cordis strict mode rejects property access for services the
+     * plugin never declared via `inject`, and a throw here fails the whole
+     * preset mount (every session in the preset dies at creation).
+     *
+     * The waterfall listener removes the first-assembly placeholder jitter:
+     * `systemPrompt.assemble()` runs BEFORE the agent pre-step, so the section
+     * text callback cannot await discovery — but the waterfall can. After the
+     * base assembly, a scope whose snapshot has not landed yet joins the
+     * in-flight `registry.ensure` (bounded by {@linkcode READINESS_BUDGET_MS}),
+     * stores the snapshot itself, and re-renders the section with the same
+     * render function the section callback uses, so the first assembly already
+     * carries the real catalog and request 2 of the first turn keeps its
+     * prefix. Timeout or failure keeps the placeholder (the background
+     * `system-prompt/change` path still lands it on a later assembly).
+     * @returns the exact Cordis effect disposer for the section and listener. */
+    start(): () => void;
+    /**
+     * Compose the catalog text for the agent behind an assemble scope.
+     * Kicks the root's background discovery on first sight; renders from the
+     * snapshot until it lands. Returns '' (section drops out) when there is no
+     * agent or the snapshot holds no definitions.
+     */
+    private render;
+    /**
+     * Kick background discovery for one workspace root exactly once. When it
+     * lands, the snapshot is populated and `system-prompt/change` fires so the
+     * next assembly renders the catalog. Failures are swallowed: a missing or
+     * unreadable agents directory simply leaves an empty snapshot (the section
+     * stays absent, which is itself the correct "no agents" rendering).
+     * @param root - the workspace root.
+     */
+    private ensureDefs;
+}
+/**
+ * Mount the single global catalog section.
+ * @param ctx - the plug context carrying the `systemPrompt` seam.
+ * @param registry - the per-workspace definition cache.
+ * @returns the exact Cordis effect disposer, or undefined when the seam is absent.
+ */
+export declare function mountAgentCatalog(ctx: Context, registry: AgentRegistry): (() => void) | undefined;
+/**
+ * Compose the section text from the sorted definitions. Returns '' when empty
+ * so the section contributes nothing to the prompt.
+ * @param defs - the sorted definitions to list.
+ * @returns the rendered catalog, or '' when no definitions are available.
+ */
+export declare function renderCatalog(defs: readonly AgentDefinition[]): string;
+//# sourceMappingURL=catalog.d.ts.map

package/lib/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAElD,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC,iCAAiC;AACjC,eAAO,MAAM,oBAAoB,wBAAwB,CAAA;AAoCzD;;;;GAIG;AACH,qBAAa,mBAAmB;IAa5B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAb3B,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;IACzE,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IAEzC;;;;;OAKG;gBAEgB,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,aAAa;IAG1C;;;;;;;;;;;;;;;;;iFAiB6E;IAC7E,KAAK,IAAI,MAAM,IAAI;IA0CnB;;;;;OAKG;IACH,OAAO,CAAC,MAAM;IAQd;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;CAcnB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,aAAa,GACtB,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAG1B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,CAUtE"}

package/lib/catalog.js

@@ -0,0 +1,197 @@
+/**
+ * The per-agent "Available subagents" system-prompt section.
+ *
+ * A single global section (mount once on the root context) serves every
+ * agent: the text callback receives the assembling agent through
+ * `AssembleContext.scope` (the agent loop passes `scope: agent`) and renders
+ * that agent's workspace `.claude/agents` definitions. Because `text()` is a
+ * synchronous callback it cannot `await` discovery, so the section renders
+ * from a snapshot cache that a fire-and-forget `registry.ensure(cwd)` populates
+ * in the background. An `system-prompt/assemble` waterfall listener
+ * reconciles the placeholder in the same assembly: for a scope whose
+ * snapshot has not landed it joins the in-flight discovery (bounded), stores
+ * the snapshot, and re-renders the section with the same render function, so
+ * the FIRST assembly already carries the real catalog and no later request
+ * sees a different prefix; on timeout the placeholder ships and the
+ * `system-prompt/change` path lands the catalog on a later assembly. When a
+ * workspace defines no agents of its own (or there is no agent to scope to)
+ * the section still lists the bundled agents, or renders an empty string when
+ * there is nothing to scope to.
+ *
+ * @module @dsh-cc/subagent-task/catalog
+ */
+import { cwdOf } from '@dsh-cc/memory';
+/** Default order slot for the catalog section (tool guidance owns 100–199). */
+export const CATALOG_SECTION_ORDER = 110;
+/** The section's unique name. */
+export const CATALOG_SECTION_NAME = 'cc:subagent-catalog';
+/**
+ * How long the assemble waterfall may wait for a workspace's in-flight
+ * discovery before giving up and shipping the placeholder. Bounded so a slow
+ * or wedged scan delays the first request by at most this much; the
+ * background `system-prompt/change` path remains the fallback.
+ */
+const READINESS_BUDGET_MS = 500;
+/**
+ * Join `promise`, but reject after `ms` milliseconds either way. The loser
+ * keeps running in the background (its eventual rejection is contained); the
+ * caller gets a rejection to degrade on.
+ */
+function withinBudget(promise, ms) {
+    let timer;
+    const budget = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`readiness budget of ${ms}ms expired`)), ms);
+    });
+    budget.catch(() => { });
+    return Promise.race([promise, budget]).finally(() => clearTimeout(timer));
+}
+/**
+ * Extract the assembling agent from an `AssembleContext`. The agent loop
+ * assembles with `scope: agent` (a runtime contract; `ScopeKey` is opaque),
+ * so the scope IS the agent whenever a session drives the assembly.
+ */
+function agentFromScope(scope) {
+    if (typeof scope === 'object' && scope !== null && 'session' in scope) {
+        return scope;
+    }
+    return undefined;
+}
+/**
+ * Owner of the cached catalog section text. Holds one sorted definition list
+ * per workspace root so the synchronous section provider can compose the text,
+ * and fills each root's snapshot from a background `registry.ensure`.
+ */
+export class AgentCatalogSection {
+    ctx;
+    registry;
+    /** Sorted definitions per workspace root, populated once discovery lands. */
+    snapshot = new Map();
+    /** Roots whose background discovery has already been kicked off. */
+    seen = new Set();
+    /**
+     * Create a catalog cache holder bound to a registry.
+     * @param ctx - the host context whose `system-prompt` seam and
+     *   `system-prompt/change` channel drive refresh.
+     * @param registry - the per-workspace definition cache to load from.
+     */
+    constructor(ctx, registry) {
+        this.ctx = ctx;
+        this.registry = registry;
+    }
+    /** Register the catalog section plus its assemble-waterfall reconciliation.
+     *
+     * The seam is fetched with `ctx.get` rather than the `ctx.systemPrompt`
+     * property: cordis strict mode rejects property access for services the
+     * plugin never declared via `inject`, and a throw here fails the whole
+     * preset mount (every session in the preset dies at creation).
+     *
+     * The waterfall listener removes the first-assembly placeholder jitter:
+     * `systemPrompt.assemble()` runs BEFORE the agent pre-step, so the section
+     * text callback cannot await discovery — but the waterfall can. After the
+     * base assembly, a scope whose snapshot has not landed yet joins the
+     * in-flight `registry.ensure` (bounded by {@linkcode READINESS_BUDGET_MS}),
+     * stores the snapshot itself, and re-renders the section with the same
+     * render function the section callback uses, so the first assembly already
+     * carries the real catalog and request 2 of the first turn keeps its
+     * prefix. Timeout or failure keeps the placeholder (the background
+     * `system-prompt/change` path still lands it on a later assembly).
+     * @returns the exact Cordis effect disposer for the section and listener. */
+    start() {
+        const seam = this.ctx.get('systemPrompt');
+        const disposeSection = seam === undefined
+            ? () => { }
+            : seam.section({
+                name: CATALOG_SECTION_NAME,
+                order: CATALOG_SECTION_ORDER,
+                text: (context) => this.render(context.scope),
+            });
+        const disposeListener = this.ctx.on('system-prompt/assemble', async (_assembly, context, next) => {
+            const result = await next();
+            const agent = agentFromScope(context.scope);
+            if (agent === undefined)
+                return result;
+            const root = cwdOf(agent);
+            if (this.snapshot.has(root))
+                return result;
+            try {
+                const defs = await withinBudget(this.registry.ensure(root), READINESS_BUDGET_MS);
+                this.snapshot.set(root, [...defs.values()].sort((a, b) => a.agentType.localeCompare(b.agentType)));
+            }
+            catch (error) {
+                this.ctx.logger.warn(`subagent catalog: discovery for ${root} did not land within ${READINESS_BUDGET_MS}ms of the first assembly: ${String(error)}; keeping the placeholder`);
+                return result;
+            }
+            return {
+                ...result,
+                sections: result.sections.map(section => section.name === CATALOG_SECTION_NAME
+                    ? { ...section, text: this.render(agent) }
+                    : section),
+            };
+        });
+        return () => {
+            disposeListener();
+            disposeSection();
+        };
+    }
+    /**
+     * Compose the catalog text for the agent behind an assemble scope.
+     * Kicks the root's background discovery on first sight; renders from the
+     * snapshot until it lands. Returns '' (section drops out) when there is no
+     * agent or the snapshot holds no definitions.
+     */
+    render(scope) {
+        const agent = agentFromScope(scope);
+        if (agent === undefined)
+            return '';
+        const root = cwdOf(agent);
+        this.ensureDefs(root);
+        return renderCatalog(this.snapshot.get(root) ?? []);
+    }
+    /**
+     * Kick background discovery for one workspace root exactly once. When it
+     * lands, the snapshot is populated and `system-prompt/change` fires so the
+     * next assembly renders the catalog. Failures are swallowed: a missing or
+     * unreadable agents directory simply leaves an empty snapshot (the section
+     * stays absent, which is itself the correct "no agents" rendering).
+     * @param root - the workspace root.
+     */
+    ensureDefs(root) {
+        if (this.seen.has(root))
+            return;
+        this.seen.add(root);
+        void this.registry.ensure(root).then(defs => {
+            this.snapshot.set(root, [...defs.values()].sort((a, b) => a.agentType.localeCompare(b.agentType)));
+            this.ctx.emit('system-prompt/change');
+        }, () => { });
+    }
+}
+/**
+ * Mount the single global catalog section.
+ * @param ctx - the plug context carrying the `systemPrompt` seam.
+ * @param registry - the per-workspace definition cache.
+ * @returns the exact Cordis effect disposer, or undefined when the seam is absent.
+ */
+export function mountAgentCatalog(ctx, registry) {
+    if (ctx.get('systemPrompt') === undefined)
+        return undefined;
+    return new AgentCatalogSection(ctx, registry).start();
+}
+/**
+ * Compose the section text from the sorted definitions. Returns '' when empty
+ * so the section contributes nothing to the prompt.
+ * @param defs - the sorted definitions to list.
+ * @returns the rendered catalog, or '' when no definitions are available.
+ */
+export function renderCatalog(defs) {
+    if (defs.length === 0)
+        return '';
+    const lines = [
+        '## Available subagents',
+        '',
+        ...defs.map(def => `- ${def.agentType} — ${def.whenToUse}`),
+        '',
+        'To delegate to one, pass its name as the `subagent_type` argument of the Task tool.',
+    ];
+    return lines.join('\n');
+}
+//# sourceMappingURL=catalog.js.map

package/lib/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/lib/epoch-collector.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The dsh-cc epoch collector: inline first-epoch collection of a continuable
+ * subagent child with zero harness changes (normative design:
+ * `docs/plans/2026-09-10-epoch-collector-dsh-cc.md`).
+ *
+ * One shared `subagent/start` + `subagent/end` listener pair and one watch
+ * map (`Map<childId, { runId?, resolve }>`) serve every collector of the
+ * process. The reservation is placed BEFORE `startContinuable` so an
+ * immediate settle cannot fall between start and subscription; the runId is
+ * captured from the child's first `subagent/start` and the end event is
+ * matched by runId (a cold-resumed later epoch has a new runId and never
+ * satisfies a stale watcher). The shared listeners are disposed when the map
+ * empties.
+ *
+ * This module is the ONE-FILE swap seam (§7): when upstream later ships the
+ * collectable continuable handle, only this file's `collectFirstEpoch`
+ * implementation is replaced — the Task tool and TUI surfaces are untouched.
+ *
+ * @module @dsh-cc/subagent-task/epoch-collector
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+/** One output content block of the child's closing message. */
+export interface EpochOutputBlock {
+    type: string;
+    text?: string;
+}
+/** The child's terminal as observed on `subagent/end`. */
+export interface EpochTerminal {
+    stopReason: string;
+    output?: readonly EpochOutputBlock[];
+}
+/**
+ * The collect race outcome: the epoch's real terminal, or the prompt
+ * synthetic `aborted` (abort never awaits child quiescence — §4).
+ */
+export type EpochOutcome = ({
+    kind: 'epoch';
+} & EpochTerminal) | {
+    kind: 'aborted';
+    stopReason: 'aborted';
+} | {
+    kind: 'promoted';
+};
+/** Duck-typed interrupt surface on the subagents seam (harness `interrupt`). */
+export interface SubagentsInterruptLike {
+    /**
+     * Interrupt a live child's current turn. Admission is synchronous; an
+     * absent/settled target is an accepted no-op. Absent on a seam without the
+     * capability → the collector degrades to a non-interrupting prompt resolve.
+     */
+    interrupt?(childId: string, authority: {
+        kind: 'ancestor';
+        agent: Agent;
+    }): void;
+}
+/** Duck-typed event bus (cordis `ctx.on`) the lifecycle events arrive on. */
+export interface EpochEventBus {
+    on(event: string, listener: (info: Record<string, unknown>) => void): (() => void) | void;
+}
+/** Instrumentation for tests and diagnostics: live watch entries. */
+export declare function epochWatchSize(): number;
+/** Mark a child's settlement notice for drop (done at collect reservation). */
+export declare function markCollectedForSuppression(childId: string): void;
+/**
+ * Un-mark a child (a promoted child is never suppressed — its notice flows
+ * normally; Slice 3's `promote()` calls this).
+ */
+export declare function releaseCollectedForSuppression(childId: string): void;
+/** Whether a child's settlement notice is currently marked for drop. */
+export declare function isCollectedForSuppression(childId: string): boolean;
+/** A live foreground collect the TUI can promote (Ctrl+B) or abort. */
+export interface CollectorRegistration {
+    childId: string;
+    /** Release the wait to background: un-suppress + resolve `async_launched`. */
+    promote(): void;
+    /** Interrupt exactly once + prompt synthetic resolve (§4). */
+    abort(): void;
+}
+/** Registry key: parentSessionId + toolCallToken. */
+export declare function collectorKey(parentSessionId: string, toolCallToken: string): string;
+export declare function registerCollector(key: string, handle: CollectorRegistration): void;
+export declare function unregisterCollector(key: string): void;
+export declare function collectorFor(key: string): CollectorRegistration | undefined;
+/**
+ * All live registrations of ONE parent session (the TUI busy-branch Ctrl+B
+ * query, F9): every armed collect whose compound key starts with the session
+ * prefix. A promoted/settled/aborted collect unregisters itself, so an
+ * armed entry here is exactly a promotable foreground wait.
+ */
+export declare function collectorsForSession(parentSessionId: string): CollectorRegistration[];
+/** Instrumentation for tests and diagnostics: live registration count. */
+export declare function registeredCollectorCount(): number;
+export interface CollectFirstEpochDeps {
+    /** The cordis context (bus) the subagent lifecycle events arrive on. */
+    bus: EpochEventBus;
+    /** The preallocated durable child id the watch is keyed by. */
+    childId: string;
+    /** The calling agent — the interrupt authority credential. */
+    agent: Agent;
+    /** The tool call's signal; abort maps to the §4 semantics. */
+    signal: AbortSignal;
+    /** The subagents seam, probed for `interrupt` (M5). */
+    subagents?: SubagentsInterruptLike;
+    /**
+     * Performs the actual `startContinuable` call. The reservation is placed
+     * BEFORE this runs (subscribe-before-start, §8); a throw from it releases
+     * the reservation and the suppression mark (tombstone parity lives in the
+     * caller, mirroring `startBackground`).
+     */
+    start: () => Promise<void>;
+    /**
+     * The collecting parent session id — half of the promotion-registry key
+     * (§6). Both this and {@link CollectFirstEpochDeps.toolCallToken} must be
+     * provided for the collect to register itself as promotable; without them
+     * the collect is a plain Slice 2 collect (never discoverable by the TUI).
+     */
+    parentSessionId?: string;
+    /** The tool-call token — the other half of the registry key (§6). */
+    toolCallToken?: string;
+}
+/**
+ * Collect a continuable child's first epoch inline. Never awaits the parent's
+ * inbound messages — only bus events (§3 deadlock rule).
+ */
+export declare function collectFirstEpoch(deps: CollectFirstEpochDeps): Promise<EpochOutcome>;
+//# sourceMappingURL=epoch-collector.d.ts.map

package/lib/epoch-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epoch-collector.d.ts","sourceRoot":"","sources":["../src/epoch-collector.ts"],"names":[],"mappings":"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"}