@kolisachint/hoocode-agent 0.4.78 → 0.4.79

package/dist/core/subagent-inbox.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Subagent inbox: the notify-and-pull bookkeeping behind background `Task`
+ * dispatch and the `TaskOutput` tool.
+ *
+ * Background dispatches don't push their full result into the parent's context.
+ * Instead the parent gets a compact notification ("explore#1 finished") and the
+ * body is retained here, keyed by task id, until the model explicitly pulls it
+ * with TaskOutput. This keeps a wide swarm of subagents from flooding the
+ * context with N full summaries, and gives the model a queryable liveness view
+ * (running / done / failed + last activity) so it can tell a working subagent
+ * from a rogue one. The same surface works at every delegation depth.
+ *
+ * Lifecycle per task:
+ *   running ──▶ done   (body retained) ──collect──▶ collected (body dropped)
+ *           ├─▶ failed
+ *           ├─▶ stalled
+ *           └─▶ timeout
+ */
+import type { SubagentPool, TaskResult } from "./subagent-pool.js";
+export type TaskLifecycle = "running" | "done" | "failed" | "stalled" | "timeout" | "collected";
+/** A non-terminal task is still doing work; the rest have settled. */
+export declare function isOutstanding(lifecycle: TaskLifecycle): boolean;
+export interface InboxRecord {
+    taskId: string;
+    /** Friendly handle shown to the model, e.g. "explore#1". */
+    label: string;
+    agentType: string;
+    lifecycle: TaskLifecycle;
+    startedAt: number;
+    endedAt?: number;
+    /** Tool the subagent is currently running, from the pool's progress stream. */
+    lastActivity?: string;
+    /** First line of the result/summary, kept even after the body is collected. */
+    summaryLine?: string;
+    /** Full subagent summary, retained only while `done` and uncollected. */
+    body?: string;
+    /** Failure reason when the task did not succeed. */
+    error?: string;
+}
+declare class SubagentInbox {
+    private records;
+    /** Insertion order of task ids, for stable listing and pruning. */
+    private order;
+    private labelCounters;
+    private observedPools;
+    /** One-shot callbacks fired after any record settles, for the wait helpers. */
+    private settleListeners;
+    private notifySettle;
+    /**
+     * Resolve once the given task settles (or immediately if already settled /
+     * unknown), bounded by `timeoutMs`. Backs TaskOutput's per-task wait.
+     */
+    waitFor(handle: string, timeoutMs: number): Promise<InboxRecord | undefined>;
+    /** Resolve once nothing is outstanding (the swarm barrier), bounded by `timeoutMs`. */
+    waitForAll(timeoutMs: number): Promise<void>;
+    /** Allocate the next friendly label for an agent type (`explore#1`, `explore#2`, …). */
+    nextLabel(agentType: string): string;
+    /**
+     * Track a pool's `task_progress` events so running records carry a live
+     * `lastActivity`. Idempotent per pool, so callers can wire it on every dispatch.
+     */
+    observe(pool: SubagentPool): void;
+    /** Register a freshly dispatched background task as running. */
+    start(taskId: string, label: string, agentType: string): InboxRecord;
+    /** Settle a task from its dispatch result: retain the body on success, the reason on failure. */
+    finish(taskId: string, result: TaskResult): InboxRecord | undefined;
+    /** Settle a task that never produced a TaskResult (e.g. a thrown dispatch error). */
+    fail(taskId: string, reason: string, lifecycle?: TaskLifecycle): InboxRecord | undefined;
+    /** Look up a record by task id or by friendly label. */
+    get(handle: string): InboxRecord | undefined;
+    /**
+     * Read a done task's body and mark it collected, dropping the body so it is not
+     * re-fed to the model. Returns the record (with `body` still populated for this
+     * one read) or undefined for an unknown handle.
+     */
+    collect(handle: string): {
+        record: InboxRecord;
+        body: string;
+    } | undefined;
+    /** All records, oldest first. */
+    list(): InboxRecord[];
+    /** Records still doing work. */
+    outstanding(): InboxRecord[];
+    /** Test/teardown helper. */
+    clear(): void;
+    /** Drop the oldest settled records once past the cap; running records are kept. */
+    private prune;
+}
+/** Process-wide subagent inbox shared by the Task and TaskOutput tools. */
+export declare const subagentInbox: SubagentInbox;
+export {};
+//# sourceMappingURL=subagent-inbox.d.ts.map

package/dist/core/subagent-inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-inbox.d.ts","sourceRoot":"","sources":["../../src/core/subagent-inbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGnE,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;AAEhG,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,CAE/D;AAED,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAgCD,cAAM,aAAa;IAClB,OAAO,CAAC,OAAO,CAAkC;IACjD,mEAAmE;IACnE,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,aAAa,CAA+B;IACpD,+EAA+E;IAC/E,OAAO,CAAC,eAAe,CAAyB;IAEhD,OAAO,CAAC,YAAY;IAIpB;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAsB3E;IAED,uFAAuF;IACvF,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3C;IAED,0FAAwF;IACxF,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAInC;IAED;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAYhC;IAED,gEAAgE;IAChE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAMnE;IAED,iGAAiG;IACjG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,CAkBlE;IAED,qFAAqF;IACrF,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,aAAwB,GAAG,WAAW,GAAG,SAAS,CAUjG;IAED,wDAAwD;IACxD,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAO3C;IAED;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAOzE;IAED,iCAAiC;IACjC,IAAI,IAAI,WAAW,EAAE,CAEpB;IAED,gCAAgC;IAChC,WAAW,IAAI,WAAW,EAAE,CAE3B;IAED,4BAA4B;IAC5B,KAAK,IAAI,IAAI,CAIZ;IAED,mFAAmF;IACnF,OAAO,CAAC,KAAK;CAkBb;AAED,2EAA2E;AAC3E,eAAO,MAAM,aAAa,eAAsB,CAAC","sourcesContent":["/**\n * Subagent inbox: the notify-and-pull bookkeeping behind background `Task`\n * dispatch and the `TaskOutput` tool.\n *\n * Background dispatches don't push their full result into the parent's context.\n * Instead the parent gets a compact notification (\"explore#1 finished\") and the\n * body is retained here, keyed by task id, until the model explicitly pulls it\n * with TaskOutput. This keeps a wide swarm of subagents from flooding the\n * context with N full summaries, and gives the model a queryable liveness view\n * (running / done / failed + last activity) so it can tell a working subagent\n * from a rogue one. The same surface works at every delegation depth.\n *\n * Lifecycle per task:\n *   running ──▶ done   (body retained) ──collect──▶ collected (body dropped)\n *           ├─▶ failed\n *           ├─▶ stalled\n *           └─▶ timeout\n */\n\nimport type { SubagentPool, TaskResult } from \"./subagent-pool.js\";\nimport type { SubagentResultFile } from \"./subagent-result.js\";\n\nexport type TaskLifecycle = \"running\" | \"done\" | \"failed\" | \"stalled\" | \"timeout\" | \"collected\";\n\n/** A non-terminal task is still doing work; the rest have settled. */\nexport function isOutstanding(lifecycle: TaskLifecycle): boolean {\n\treturn lifecycle === \"running\";\n}\n\nexport interface InboxRecord {\n\ttaskId: string;\n\t/** Friendly handle shown to the model, e.g. \"explore#1\". */\n\tlabel: string;\n\tagentType: string;\n\tlifecycle: TaskLifecycle;\n\tstartedAt: number;\n\tendedAt?: number;\n\t/** Tool the subagent is currently running, from the pool's progress stream. */\n\tlastActivity?: string;\n\t/** First line of the result/summary, kept even after the body is collected. */\n\tsummaryLine?: string;\n\t/** Full subagent summary, retained only while `done` and uncollected. */\n\tbody?: string;\n\t/** Failure reason when the task did not succeed. */\n\terror?: string;\n}\n\n/** Cap on settled (terminal) records kept for late pulls; running records are never pruned. */\nconst MAX_SETTLED = 50;\n\n/** First non-empty line of a block of text, length-capped. */\nfunction firstLine(text: string, max = 120): string {\n\tconst line = (\n\t\ttext\n\t\t\t.trim()\n\t\t\t.split(\"\\n\")\n\t\t\t.find((l) => l.trim()) ?? \"\"\n\t).trim();\n\treturn line.length > max ? `${line.slice(0, max - 1)}…` : line;\n}\n\n/** Map a subagent's terminal `status` onto an inbox lifecycle. */\nfunction failLifecycle(status: string | undefined): TaskLifecycle {\n\tif (status === \"stalled\") return \"stalled\";\n\tif (status === \"timeout\") return \"timeout\";\n\treturn \"failed\";\n}\n\n/** Derive the \"currently running X\" activity label from a forwarded progress event. */\nfunction activityFromEvent(event: Record<string, unknown>): string | undefined {\n\tif (event.type === \"tool_execution_start\" && typeof event.toolName === \"string\") {\n\t\treturn event.toolName;\n\t}\n\tif (event.type === \"turn_end\") return \"thinking\";\n\treturn undefined;\n}\n\nclass SubagentInbox {\n\tprivate records = new Map<string, InboxRecord>();\n\t/** Insertion order of task ids, for stable listing and pruning. */\n\tprivate order: string[] = [];\n\tprivate labelCounters = new Map<string, number>();\n\tprivate observedPools = new WeakSet<SubagentPool>();\n\t/** One-shot callbacks fired after any record settles, for the wait helpers. */\n\tprivate settleListeners = new Set<() => void>();\n\n\tprivate notifySettle(): void {\n\t\tfor (const listener of [...this.settleListeners]) listener();\n\t}\n\n\t/**\n\t * Resolve once the given task settles (or immediately if already settled /\n\t * unknown), bounded by `timeoutMs`. Backs TaskOutput's per-task wait.\n\t */\n\twaitFor(handle: string, timeoutMs: number): Promise<InboxRecord | undefined> {\n\t\tconst current = this.get(handle);\n\t\tif (!current || !isOutstanding(current.lifecycle)) return Promise.resolve(current);\n\t\treturn new Promise((resolve) => {\n\t\t\tconst cleanup = () => {\n\t\t\t\tthis.settleListeners.delete(check);\n\t\t\t\tclearTimeout(timer);\n\t\t\t};\n\t\t\tconst check = () => {\n\t\t\t\tconst rec = this.get(handle);\n\t\t\t\tif (!rec || !isOutstanding(rec.lifecycle)) {\n\t\t\t\t\tcleanup();\n\t\t\t\t\tresolve(rec);\n\t\t\t\t}\n\t\t\t};\n\t\t\tconst timer = setTimeout(() => {\n\t\t\t\tcleanup();\n\t\t\t\tresolve(this.get(handle));\n\t\t\t}, timeoutMs);\n\t\t\ttimer.unref?.();\n\t\t\tthis.settleListeners.add(check);\n\t\t});\n\t}\n\n\t/** Resolve once nothing is outstanding (the swarm barrier), bounded by `timeoutMs`. */\n\twaitForAll(timeoutMs: number): Promise<void> {\n\t\tif (this.outstanding().length === 0) return Promise.resolve();\n\t\treturn new Promise((resolve) => {\n\t\t\tconst cleanup = () => {\n\t\t\t\tthis.settleListeners.delete(check);\n\t\t\t\tclearTimeout(timer);\n\t\t\t};\n\t\t\tconst check = () => {\n\t\t\t\tif (this.outstanding().length === 0) {\n\t\t\t\t\tcleanup();\n\t\t\t\t\tresolve();\n\t\t\t\t}\n\t\t\t};\n\t\t\tconst timer = setTimeout(() => {\n\t\t\t\tcleanup();\n\t\t\t\tresolve();\n\t\t\t}, timeoutMs);\n\t\t\ttimer.unref?.();\n\t\t\tthis.settleListeners.add(check);\n\t\t});\n\t}\n\n\t/** Allocate the next friendly label for an agent type (`explore#1`, `explore#2`, …). */\n\tnextLabel(agentType: string): string {\n\t\tconst n = (this.labelCounters.get(agentType) ?? 0) + 1;\n\t\tthis.labelCounters.set(agentType, n);\n\t\treturn `${agentType}#${n}`;\n\t}\n\n\t/**\n\t * Track a pool's `task_progress` events so running records carry a live\n\t * `lastActivity`. Idempotent per pool, so callers can wire it on every dispatch.\n\t */\n\tobserve(pool: SubagentPool): void {\n\t\t// Tolerate a non-EventEmitter stand-in (test fakes): without progress events\n\t\t// records simply carry no live activity.\n\t\tif (typeof (pool as { on?: unknown }).on !== \"function\") return;\n\t\tif (this.observedPools.has(pool)) return;\n\t\tthis.observedPools.add(pool);\n\t\tpool.on(\"task_progress\", (data: { task_id: string; event: Record<string, unknown> }) => {\n\t\t\tconst rec = this.records.get(data.task_id);\n\t\t\tif (!rec || rec.lifecycle !== \"running\") return;\n\t\t\tconst activity = activityFromEvent(data.event);\n\t\t\tif (activity) rec.lastActivity = activity;\n\t\t});\n\t}\n\n\t/** Register a freshly dispatched background task as running. */\n\tstart(taskId: string, label: string, agentType: string): InboxRecord {\n\t\tconst rec: InboxRecord = { taskId, label, agentType, lifecycle: \"running\", startedAt: Date.now() };\n\t\tthis.records.set(taskId, rec);\n\t\tthis.order.push(taskId);\n\t\tthis.prune();\n\t\treturn rec;\n\t}\n\n\t/** Settle a task from its dispatch result: retain the body on success, the reason on failure. */\n\tfinish(taskId: string, result: TaskResult): InboxRecord | undefined {\n\t\tconst rec = this.records.get(taskId);\n\t\tif (!rec) return undefined;\n\t\trec.endedAt = Date.now();\n\t\trec.lastActivity = undefined;\n\t\tconst r = result.result;\n\t\tconst data = r?.result_data as SubagentResultFile | undefined;\n\t\tif (r?.ok) {\n\t\t\trec.lifecycle = \"done\";\n\t\t\trec.body = data?.summary?.trim() || \"(subagent returned no output)\";\n\t\t\trec.summaryLine = firstLine(rec.body);\n\t\t} else {\n\t\t\trec.lifecycle = failLifecycle(r?.status);\n\t\t\trec.error = r?.error ?? (r?.status ? `subagent ${r.status}` : \"unknown error\");\n\t\t\trec.summaryLine = rec.error;\n\t\t}\n\t\tthis.notifySettle();\n\t\treturn rec;\n\t}\n\n\t/** Settle a task that never produced a TaskResult (e.g. a thrown dispatch error). */\n\tfail(taskId: string, reason: string, lifecycle: TaskLifecycle = \"failed\"): InboxRecord | undefined {\n\t\tconst rec = this.records.get(taskId);\n\t\tif (!rec) return undefined;\n\t\trec.endedAt = Date.now();\n\t\trec.lastActivity = undefined;\n\t\trec.lifecycle = lifecycle;\n\t\trec.error = reason;\n\t\trec.summaryLine = reason;\n\t\tthis.notifySettle();\n\t\treturn rec;\n\t}\n\n\t/** Look up a record by task id or by friendly label. */\n\tget(handle: string): InboxRecord | undefined {\n\t\tconst byId = this.records.get(handle);\n\t\tif (byId) return byId;\n\t\tfor (const rec of this.records.values()) {\n\t\t\tif (rec.label === handle) return rec;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Read a done task's body and mark it collected, dropping the body so it is not\n\t * re-fed to the model. Returns the record (with `body` still populated for this\n\t * one read) or undefined for an unknown handle.\n\t */\n\tcollect(handle: string): { record: InboxRecord; body: string } | undefined {\n\t\tconst rec = this.get(handle);\n\t\tif (!rec || rec.lifecycle !== \"done\" || rec.body === undefined) return undefined;\n\t\tconst body = rec.body;\n\t\trec.lifecycle = \"collected\";\n\t\trec.body = undefined;\n\t\treturn { record: rec, body };\n\t}\n\n\t/** All records, oldest first. */\n\tlist(): InboxRecord[] {\n\t\treturn this.order.map((id) => this.records.get(id)).filter((r): r is InboxRecord => r !== undefined);\n\t}\n\n\t/** Records still doing work. */\n\toutstanding(): InboxRecord[] {\n\t\treturn this.list().filter((r) => isOutstanding(r.lifecycle));\n\t}\n\n\t/** Test/teardown helper. */\n\tclear(): void {\n\t\tthis.records.clear();\n\t\tthis.order = [];\n\t\tthis.labelCounters.clear();\n\t}\n\n\t/** Drop the oldest settled records once past the cap; running records are kept. */\n\tprivate prune(): void {\n\t\tlet settled = this.order.filter((id) => {\n\t\t\tconst r = this.records.get(id);\n\t\t\treturn r !== undefined && !isOutstanding(r.lifecycle);\n\t\t}).length;\n\t\tif (settled <= MAX_SETTLED) return;\n\t\tconst kept: string[] = [];\n\t\tfor (const id of this.order) {\n\t\t\tconst r = this.records.get(id);\n\t\t\tif (r && !isOutstanding(r.lifecycle) && settled > MAX_SETTLED) {\n\t\t\t\tthis.records.delete(id);\n\t\t\t\tsettled--;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tkept.push(id);\n\t\t}\n\t\tthis.order = kept;\n\t}\n}\n\n/** Process-wide subagent inbox shared by the Task and TaskOutput tools. */\nexport const subagentInbox = new SubagentInbox();\n"]}

package/dist/core/subagent-inbox.js

@@ -0,0 +1,245 @@
+/**
+ * Subagent inbox: the notify-and-pull bookkeeping behind background `Task`
+ * dispatch and the `TaskOutput` tool.
+ *
+ * Background dispatches don't push their full result into the parent's context.
+ * Instead the parent gets a compact notification ("explore#1 finished") and the
+ * body is retained here, keyed by task id, until the model explicitly pulls it
+ * with TaskOutput. This keeps a wide swarm of subagents from flooding the
+ * context with N full summaries, and gives the model a queryable liveness view
+ * (running / done / failed + last activity) so it can tell a working subagent
+ * from a rogue one. The same surface works at every delegation depth.
+ *
+ * Lifecycle per task:
+ *   running ──▶ done   (body retained) ──collect──▶ collected (body dropped)
+ *           ├─▶ failed
+ *           ├─▶ stalled
+ *           └─▶ timeout
+ */
+/** A non-terminal task is still doing work; the rest have settled. */
+export function isOutstanding(lifecycle) {
+    return lifecycle === "running";
+}
+/** Cap on settled (terminal) records kept for late pulls; running records are never pruned. */
+const MAX_SETTLED = 50;
+/** First non-empty line of a block of text, length-capped. */
+function firstLine(text, max = 120) {
+    const line = (text
+        .trim()
+        .split("\n")
+        .find((l) => l.trim()) ?? "").trim();
+    return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+}
+/** Map a subagent's terminal `status` onto an inbox lifecycle. */
+function failLifecycle(status) {
+    if (status === "stalled")
+        return "stalled";
+    if (status === "timeout")
+        return "timeout";
+    return "failed";
+}
+/** Derive the "currently running X" activity label from a forwarded progress event. */
+function activityFromEvent(event) {
+    if (event.type === "tool_execution_start" && typeof event.toolName === "string") {
+        return event.toolName;
+    }
+    if (event.type === "turn_end")
+        return "thinking";
+    return undefined;
+}
+class SubagentInbox {
+    records = new Map();
+    /** Insertion order of task ids, for stable listing and pruning. */
+    order = [];
+    labelCounters = new Map();
+    observedPools = new WeakSet();
+    /** One-shot callbacks fired after any record settles, for the wait helpers. */
+    settleListeners = new Set();
+    notifySettle() {
+        for (const listener of [...this.settleListeners])
+            listener();
+    }
+    /**
+     * Resolve once the given task settles (or immediately if already settled /
+     * unknown), bounded by `timeoutMs`. Backs TaskOutput's per-task wait.
+     */
+    waitFor(handle, timeoutMs) {
+        const current = this.get(handle);
+        if (!current || !isOutstanding(current.lifecycle))
+            return Promise.resolve(current);
+        return new Promise((resolve) => {
+            const cleanup = () => {
+                this.settleListeners.delete(check);
+                clearTimeout(timer);
+            };
+            const check = () => {
+                const rec = this.get(handle);
+                if (!rec || !isOutstanding(rec.lifecycle)) {
+                    cleanup();
+                    resolve(rec);
+                }
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                resolve(this.get(handle));
+            }, timeoutMs);
+            timer.unref?.();
+            this.settleListeners.add(check);
+        });
+    }
+    /** Resolve once nothing is outstanding (the swarm barrier), bounded by `timeoutMs`. */
+    waitForAll(timeoutMs) {
+        if (this.outstanding().length === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const cleanup = () => {
+                this.settleListeners.delete(check);
+                clearTimeout(timer);
+            };
+            const check = () => {
+                if (this.outstanding().length === 0) {
+                    cleanup();
+                    resolve();
+                }
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                resolve();
+            }, timeoutMs);
+            timer.unref?.();
+            this.settleListeners.add(check);
+        });
+    }
+    /** Allocate the next friendly label for an agent type (`explore#1`, `explore#2`, …). */
+    nextLabel(agentType) {
+        const n = (this.labelCounters.get(agentType) ?? 0) + 1;
+        this.labelCounters.set(agentType, n);
+        return `${agentType}#${n}`;
+    }
+    /**
+     * Track a pool's `task_progress` events so running records carry a live
+     * `lastActivity`. Idempotent per pool, so callers can wire it on every dispatch.
+     */
+    observe(pool) {
+        // Tolerate a non-EventEmitter stand-in (test fakes): without progress events
+        // records simply carry no live activity.
+        if (typeof pool.on !== "function")
+            return;
+        if (this.observedPools.has(pool))
+            return;
+        this.observedPools.add(pool);
+        pool.on("task_progress", (data) => {
+            const rec = this.records.get(data.task_id);
+            if (!rec || rec.lifecycle !== "running")
+                return;
+            const activity = activityFromEvent(data.event);
+            if (activity)
+                rec.lastActivity = activity;
+        });
+    }
+    /** Register a freshly dispatched background task as running. */
+    start(taskId, label, agentType) {
+        const rec = { taskId, label, agentType, lifecycle: "running", startedAt: Date.now() };
+        this.records.set(taskId, rec);
+        this.order.push(taskId);
+        this.prune();
+        return rec;
+    }
+    /** Settle a task from its dispatch result: retain the body on success, the reason on failure. */
+    finish(taskId, result) {
+        const rec = this.records.get(taskId);
+        if (!rec)
+            return undefined;
+        rec.endedAt = Date.now();
+        rec.lastActivity = undefined;
+        const r = result.result;
+        const data = r?.result_data;
+        if (r?.ok) {
+            rec.lifecycle = "done";
+            rec.body = data?.summary?.trim() || "(subagent returned no output)";
+            rec.summaryLine = firstLine(rec.body);
+        }
+        else {
+            rec.lifecycle = failLifecycle(r?.status);
+            rec.error = r?.error ?? (r?.status ? `subagent ${r.status}` : "unknown error");
+            rec.summaryLine = rec.error;
+        }
+        this.notifySettle();
+        return rec;
+    }
+    /** Settle a task that never produced a TaskResult (e.g. a thrown dispatch error). */
+    fail(taskId, reason, lifecycle = "failed") {
+        const rec = this.records.get(taskId);
+        if (!rec)
+            return undefined;
+        rec.endedAt = Date.now();
+        rec.lastActivity = undefined;
+        rec.lifecycle = lifecycle;
+        rec.error = reason;
+        rec.summaryLine = reason;
+        this.notifySettle();
+        return rec;
+    }
+    /** Look up a record by task id or by friendly label. */
+    get(handle) {
+        const byId = this.records.get(handle);
+        if (byId)
+            return byId;
+        for (const rec of this.records.values()) {
+            if (rec.label === handle)
+                return rec;
+        }
+        return undefined;
+    }
+    /**
+     * Read a done task's body and mark it collected, dropping the body so it is not
+     * re-fed to the model. Returns the record (with `body` still populated for this
+     * one read) or undefined for an unknown handle.
+     */
+    collect(handle) {
+        const rec = this.get(handle);
+        if (!rec || rec.lifecycle !== "done" || rec.body === undefined)
+            return undefined;
+        const body = rec.body;
+        rec.lifecycle = "collected";
+        rec.body = undefined;
+        return { record: rec, body };
+    }
+    /** All records, oldest first. */
+    list() {
+        return this.order.map((id) => this.records.get(id)).filter((r) => r !== undefined);
+    }
+    /** Records still doing work. */
+    outstanding() {
+        return this.list().filter((r) => isOutstanding(r.lifecycle));
+    }
+    /** Test/teardown helper. */
+    clear() {
+        this.records.clear();
+        this.order = [];
+        this.labelCounters.clear();
+    }
+    /** Drop the oldest settled records once past the cap; running records are kept. */
+    prune() {
+        let settled = this.order.filter((id) => {
+            const r = this.records.get(id);
+            return r !== undefined && !isOutstanding(r.lifecycle);
+        }).length;
+        if (settled <= MAX_SETTLED)
+            return;
+        const kept = [];
+        for (const id of this.order) {
+            const r = this.records.get(id);
+            if (r && !isOutstanding(r.lifecycle) && settled > MAX_SETTLED) {
+                this.records.delete(id);
+                settled--;
+                continue;
+            }
+            kept.push(id);
+        }
+        this.order = kept;
+    }
+}
+/** Process-wide subagent inbox shared by the Task and TaskOutput tools. */
+export const subagentInbox = new SubagentInbox();
+//# sourceMappingURL=subagent-inbox.js.map

package/dist/core/subagent-inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-inbox.js","sourceRoot":"","sources":["../../src/core/subagent-inbox.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Subagent inbox: the notify-and-pull bookkeeping behind background `Task`\n * dispatch and the `TaskOutput` tool.\n *\n * Background dispatches don't push their full result into the parent's context.\n * Instead the parent gets a compact notification (\"explore#1 finished\") and the\n * body is retained here, keyed by task id, until the model explicitly pulls it\n * with TaskOutput. This keeps a wide swarm of subagents from flooding the\n * context with N full summaries, and gives the model a queryable liveness view\n * (running / done / failed + last activity) so it can tell a working subagent\n * from a rogue one. The same surface works at every delegation depth.\n *\n * Lifecycle per task:\n *   running ──▶ done   (body retained) ──collect──▶ collected (body dropped)\n *           ├─▶ failed\n *           ├─▶ stalled\n *           └─▶ timeout\n */\n\nimport type { SubagentPool, TaskResult } from \"./subagent-pool.js\";\nimport type { SubagentResultFile } from \"./subagent-result.js\";\n\nexport type TaskLifecycle = \"running\" | \"done\" | \"failed\" | \"stalled\" | \"timeout\" | \"collected\";\n\n/** A non-terminal task is still doing work; the rest have settled. */\nexport function isOutstanding(lifecycle: TaskLifecycle): boolean {\n\treturn lifecycle === \"running\";\n}\n\nexport interface InboxRecord {\n\ttaskId: string;\n\t/** Friendly handle shown to the model, e.g. \"explore#1\". */\n\tlabel: string;\n\tagentType: string;\n\tlifecycle: TaskLifecycle;\n\tstartedAt: number;\n\tendedAt?: number;\n\t/** Tool the subagent is currently running, from the pool's progress stream. */\n\tlastActivity?: string;\n\t/** First line of the result/summary, kept even after the body is collected. */\n\tsummaryLine?: string;\n\t/** Full subagent summary, retained only while `done` and uncollected. */\n\tbody?: string;\n\t/** Failure reason when the task did not succeed. */\n\terror?: string;\n}\n\n/** Cap on settled (terminal) records kept for late pulls; running records are never pruned. */\nconst MAX_SETTLED = 50;\n\n/** First non-empty line of a block of text, length-capped. */\nfunction firstLine(text: string, max = 120): string {\n\tconst line = (\n\t\ttext\n\t\t\t.trim()\n\t\t\t.split(\"\\n\")\n\t\t\t.find((l) => l.trim()) ?? \"\"\n\t).trim();\n\treturn line.length > max ? `${line.slice(0, max - 1)}…` : line;\n}\n\n/** Map a subagent's terminal `status` onto an inbox lifecycle. */\nfunction failLifecycle(status: string | undefined): TaskLifecycle {\n\tif (status === \"stalled\") return \"stalled\";\n\tif (status === \"timeout\") return \"timeout\";\n\treturn \"failed\";\n}\n\n/** Derive the \"currently running X\" activity label from a forwarded progress event. */\nfunction activityFromEvent(event: Record<string, unknown>): string | undefined {\n\tif (event.type === \"tool_execution_start\" && typeof event.toolName === \"string\") {\n\t\treturn event.toolName;\n\t}\n\tif (event.type === \"turn_end\") return \"thinking\";\n\treturn undefined;\n}\n\nclass SubagentInbox {\n\tprivate records = new Map<string, InboxRecord>();\n\t/** Insertion order of task ids, for stable listing and pruning. */\n\tprivate order: string[] = [];\n\tprivate labelCounters = new Map<string, number>();\n\tprivate observedPools = new WeakSet<SubagentPool>();\n\t/** One-shot callbacks fired after any record settles, for the wait helpers. */\n\tprivate settleListeners = new Set<() => void>();\n\n\tprivate notifySettle(): void {\n\t\tfor (const listener of [...this.settleListeners]) listener();\n\t}\n\n\t/**\n\t * Resolve once the given task settles (or immediately if already settled /\n\t * unknown), bounded by `timeoutMs`. Backs TaskOutput's per-task wait.\n\t */\n\twaitFor(handle: string, timeoutMs: number): Promise<InboxRecord | undefined> {\n\t\tconst current = this.get(handle);\n\t\tif (!current || !isOutstanding(current.lifecycle)) return Promise.resolve(current);\n\t\treturn new Promise((resolve) => {\n\t\t\tconst cleanup = () => {\n\t\t\t\tthis.settleListeners.delete(check);\n\t\t\t\tclearTimeout(timer);\n\t\t\t};\n\t\t\tconst check = () => {\n\t\t\t\tconst rec = this.get(handle);\n\t\t\t\tif (!rec || !isOutstanding(rec.lifecycle)) {\n\t\t\t\t\tcleanup();\n\t\t\t\t\tresolve(rec);\n\t\t\t\t}\n\t\t\t};\n\t\t\tconst timer = setTimeout(() => {\n\t\t\t\tcleanup();\n\t\t\t\tresolve(this.get(handle));\n\t\t\t}, timeoutMs);\n\t\t\ttimer.unref?.();\n\t\t\tthis.settleListeners.add(check);\n\t\t});\n\t}\n\n\t/** Resolve once nothing is outstanding (the swarm barrier), bounded by `timeoutMs`. */\n\twaitForAll(timeoutMs: number): Promise<void> {\n\t\tif (this.outstanding().length === 0) return Promise.resolve();\n\t\treturn new Promise((resolve) => {\n\t\t\tconst cleanup = () => {\n\t\t\t\tthis.settleListeners.delete(check);\n\t\t\t\tclearTimeout(timer);\n\t\t\t};\n\t\t\tconst check = () => {\n\t\t\t\tif (this.outstanding().length === 0) {\n\t\t\t\t\tcleanup();\n\t\t\t\t\tresolve();\n\t\t\t\t}\n\t\t\t};\n\t\t\tconst timer = setTimeout(() => {\n\t\t\t\tcleanup();\n\t\t\t\tresolve();\n\t\t\t}, timeoutMs);\n\t\t\ttimer.unref?.();\n\t\t\tthis.settleListeners.add(check);\n\t\t});\n\t}\n\n\t/** Allocate the next friendly label for an agent type (`explore#1`, `explore#2`, …). */\n\tnextLabel(agentType: string): string {\n\t\tconst n = (this.labelCounters.get(agentType) ?? 0) + 1;\n\t\tthis.labelCounters.set(agentType, n);\n\t\treturn `${agentType}#${n}`;\n\t}\n\n\t/**\n\t * Track a pool's `task_progress` events so running records carry a live\n\t * `lastActivity`. Idempotent per pool, so callers can wire it on every dispatch.\n\t */\n\tobserve(pool: SubagentPool): void {\n\t\t// Tolerate a non-EventEmitter stand-in (test fakes): without progress events\n\t\t// records simply carry no live activity.\n\t\tif (typeof (pool as { on?: unknown }).on !== \"function\") return;\n\t\tif (this.observedPools.has(pool)) return;\n\t\tthis.observedPools.add(pool);\n\t\tpool.on(\"task_progress\", (data: { task_id: string; event: Record<string, unknown> }) => {\n\t\t\tconst rec = this.records.get(data.task_id);\n\t\t\tif (!rec || rec.lifecycle !== \"running\") return;\n\t\t\tconst activity = activityFromEvent(data.event);\n\t\t\tif (activity) rec.lastActivity = activity;\n\t\t});\n\t}\n\n\t/** Register a freshly dispatched background task as running. */\n\tstart(taskId: string, label: string, agentType: string): InboxRecord {\n\t\tconst rec: InboxRecord = { taskId, label, agentType, lifecycle: \"running\", startedAt: Date.now() };\n\t\tthis.records.set(taskId, rec);\n\t\tthis.order.push(taskId);\n\t\tthis.prune();\n\t\treturn rec;\n\t}\n\n\t/** Settle a task from its dispatch result: retain the body on success, the reason on failure. */\n\tfinish(taskId: string, result: TaskResult): InboxRecord | undefined {\n\t\tconst rec = this.records.get(taskId);\n\t\tif (!rec) return undefined;\n\t\trec.endedAt = Date.now();\n\t\trec.lastActivity = undefined;\n\t\tconst r = result.result;\n\t\tconst data = r?.result_data as SubagentResultFile | undefined;\n\t\tif (r?.ok) {\n\t\t\trec.lifecycle = \"done\";\n\t\t\trec.body = data?.summary?.trim() || \"(subagent returned no output)\";\n\t\t\trec.summaryLine = firstLine(rec.body);\n\t\t} else {\n\t\t\trec.lifecycle = failLifecycle(r?.status);\n\t\t\trec.error = r?.error ?? (r?.status ? `subagent ${r.status}` : \"unknown error\");\n\t\t\trec.summaryLine = rec.error;\n\t\t}\n\t\tthis.notifySettle();\n\t\treturn rec;\n\t}\n\n\t/** Settle a task that never produced a TaskResult (e.g. a thrown dispatch error). */\n\tfail(taskId: string, reason: string, lifecycle: TaskLifecycle = \"failed\"): InboxRecord | undefined {\n\t\tconst rec = this.records.get(taskId);\n\t\tif (!rec) return undefined;\n\t\trec.endedAt = Date.now();\n\t\trec.lastActivity = undefined;\n\t\trec.lifecycle = lifecycle;\n\t\trec.error = reason;\n\t\trec.summaryLine = reason;\n\t\tthis.notifySettle();\n\t\treturn rec;\n\t}\n\n\t/** Look up a record by task id or by friendly label. */\n\tget(handle: string): InboxRecord | undefined {\n\t\tconst byId = this.records.get(handle);\n\t\tif (byId) return byId;\n\t\tfor (const rec of this.records.values()) {\n\t\t\tif (rec.label === handle) return rec;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Read a done task's body and mark it collected, dropping the body so it is not\n\t * re-fed to the model. Returns the record (with `body` still populated for this\n\t * one read) or undefined for an unknown handle.\n\t */\n\tcollect(handle: string): { record: InboxRecord; body: string } | undefined {\n\t\tconst rec = this.get(handle);\n\t\tif (!rec || rec.lifecycle !== \"done\" || rec.body === undefined) return undefined;\n\t\tconst body = rec.body;\n\t\trec.lifecycle = \"collected\";\n\t\trec.body = undefined;\n\t\treturn { record: rec, body };\n\t}\n\n\t/** All records, oldest first. */\n\tlist(): InboxRecord[] {\n\t\treturn this.order.map((id) => this.records.get(id)).filter((r): r is InboxRecord => r !== undefined);\n\t}\n\n\t/** Records still doing work. */\n\toutstanding(): InboxRecord[] {\n\t\treturn this.list().filter((r) => isOutstanding(r.lifecycle));\n\t}\n\n\t/** Test/teardown helper. */\n\tclear(): void {\n\t\tthis.records.clear();\n\t\tthis.order = [];\n\t\tthis.labelCounters.clear();\n\t}\n\n\t/** Drop the oldest settled records once past the cap; running records are kept. */\n\tprivate prune(): void {\n\t\tlet settled = this.order.filter((id) => {\n\t\t\tconst r = this.records.get(id);\n\t\t\treturn r !== undefined && !isOutstanding(r.lifecycle);\n\t\t}).length;\n\t\tif (settled <= MAX_SETTLED) return;\n\t\tconst kept: string[] = [];\n\t\tfor (const id of this.order) {\n\t\t\tconst r = this.records.get(id);\n\t\t\tif (r && !isOutstanding(r.lifecycle) && settled > MAX_SETTLED) {\n\t\t\t\tthis.records.delete(id);\n\t\t\t\tsettled--;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tkept.push(id);\n\t\t}\n\t\tthis.order = kept;\n\t}\n}\n\n/** Process-wide subagent inbox shared by the Task and TaskOutput tools. */\nexport const subagentInbox = new SubagentInbox();\n"]}

package/dist/core/subagent-pool.d.ts

@@ -67,6 +67,9 @@ export interface DispatchOptions {
     provider?: string;
     /** Explicit session file to persist/continue (used by resume). */
     sessionFile?: string;
+    /** Caller-supplied task id. Defaults to a generated `dispatch-…` id. Lets a
+     *  caller register liveness/inbox state under the id before dispatch resolves. */
+    taskId?: string;
 }
 export interface SubagentPoolOptions {
     /** Path to the hoocode executable (or the runtime, e.g. node, when prefixArgs is set). */
@@ -180,13 +183,6 @@ export declare class SubagentPool extends EventEmitter {
     get_status(task_id: string): "running" | "queued" | "done" | "failed" | "stalled" | "timeout" | "unknown";
     /** Wait for a task to complete and return its result. */
     wait_for(task_id: string): Promise<SubagentResult>;
-    /**
-     * Wait for a task to finish without consuming its result. Returns the result
-     * once the task reaches a terminal state, or undefined if the task is not
-     * found. Unlike wait_for(), the result remains in the completed map so
-     * collect() can still read it afterward.
-     */
-    wait_for_completion(task_id: string): Promise<SubagentResult | undefined>;
     /** Number of currently running subagents. */
     running_count(): number;
     /** Number of tasks waiting in the queue. */