@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/dist/tool-system/builtin/agent-notifications.js

@@ -1,127 +1,319 @@
+import { nanoid } from "nanoid";
 import { logger } from "../../logging/logger.js";
-// Stable empty reference so `getSnapshot(sid)` returns the same array
-// identity across calls when the bucket is empty. React's
-// useSyncExternalStore compares snapshots by identity to decide whether
-// to re-render — a fresh `[]` each call would cause render loops.
 const EMPTY = Object.freeze([]);
-/**
- * Runtime guard for sessionId. The static type is already `string` on
- * the public surface, but a caller bypassing the type system via
- * `as any` (or a stale JS-only consumer) could still smuggle in
- * undefined / "". We refuse those, log once, and let the agent path
- * continue — a buggy plugin shouldn't crash the engine.
- */
-function isValidSessionId(sid) {
-    return typeof sid === "string" && sid.length > 0;
+function isValidSessionId(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function routeSequenceKey(draft) {
+    return [
+        draft.teamId ?? "tree",
+        draft.from.sessionId,
+        draft.from.agentId ?? "",
+        draft.to.sessionId,
+        draft.to.agentId ?? "",
+    ].join("\u0000");
+}
+function isStrictDirectionDraft(draft) {
+    if (draft.kind !== "direction")
+        return true;
+    if (draft.delivery !== "next-safe-point" && draft.delivery !== "interrupt-and-redrive") {
+        return false;
+    }
+    if (draft.from.authority !== "agent" || draft.to.authority !== "agent")
+        return false;
+    if (!Number.isSafeInteger(draft.runtimeGeneration) || (draft.runtimeGeneration ?? 0) < 1) {
+        return false;
+    }
+    if (!draft.payload ||
+        typeof draft.payload.prompt !== "string" ||
+        draft.payload.prompt.trim().length === 0 ||
+        draft.payload.origin !== "agent_send_input") {
+        return false;
+    }
+    return Object.keys(draft.payload).sort().join(",") === "origin,prompt";
+}
+function legacyItemToDraft(item, sessionId) {
+    const workKind = item.workKind ?? "agent";
+    const authority = workKind === "agent" ? "agent" : "system";
+    return {
+        kind: "result",
+        from: {
+            sessionId: workKind === "agent" ? item.agentId : sessionId,
+            ...(workKind === "agent" ? { agentId: item.agentId } : {}),
+            authority,
+        },
+        to: { sessionId, authority: "system" },
+        delivery: "idle-drain",
+        payload: {
+            workId: item.agentId,
+            ...(item.name !== undefined ? { name: item.name } : {}),
+            description: item.description,
+            status: item.status,
+            workKind,
+            ...(item.command !== undefined ? { command: item.command } : {}),
+            ...(item.finalText !== undefined ? { finalText: item.finalText } : {}),
+            ...(item.ccSessionId !== undefined ? { ccSessionId: item.ccSessionId } : {}),
+            ...(item.error !== undefined ? { error: item.error } : {}),
+            ...(item.changedFiles !== undefined ? { changedFiles: item.changedFiles } : {}),
+            ...(item.cwd !== undefined ? { cwd: item.cwd } : {}),
+            ...(item.originClientMessageId !== undefined
+                ? { originClientMessageId: item.originClientMessageId }
+                : {}),
+            finishedAt: item.enqueuedAt,
+        },
+    };
+}
+function installLegacyResultAliases(envelope) {
+    const aliases = {
+        agentId: () => envelope.from.agentId ?? envelope.payload.workId,
+        name: () => envelope.payload.name,
+        description: () => envelope.payload.description,
+        status: () => envelope.payload.status,
+        workKind: () => envelope.payload.workKind,
+        command: () => envelope.payload.command,
+        finalText: () => envelope.payload.finalText,
+        ccSessionId: () => envelope.payload.ccSessionId,
+        error: () => envelope.payload.error,
+        changedFiles: () => envelope.payload.changedFiles,
+        cwd: () => envelope.payload.cwd,
+        originClientMessageId: () => envelope.payload.originClientMessageId,
+        enqueuedAt: () => envelope.payload.finishedAt,
+    };
+    for (const [name, get] of Object.entries(aliases)) {
+        Object.defineProperty(envelope, name, { configurable: false, enumerable: false, get });
+    }
 }
 class NotificationQueue {
     buckets = new Map();
     listeners = new Set();
-    enqueue(item, sessionId) {
-        if (!isValidSessionId(sessionId)) {
+    sequences = new Map();
+    sequenceRoutes = new Map();
+    maxSequenceRoutes = 4_096;
+    enqueue(draftOrItem, legacySessionId) {
+        const draft = legacySessionId !== undefined || !("kind" in draftOrItem)
+            ? legacyItemToDraft(draftOrItem, legacySessionId)
+            : draftOrItem;
+        if (!isValidSessionId(draft.to?.sessionId)) {
             logger.warn("notification_queue.invalid_session_id", {
-                agentId: item.agentId,
-                status: item.status,
-                sessionIdType: typeof sessionId,
+                kind: draft.kind,
+                sessionIdType: typeof draft.to?.sessionId,
             });
-            return;
+            return undefined;
+        }
+        if (draft.teamId !== undefined) {
+            logger.warn("notification_queue.team_not_supported", { teamId: draft.teamId });
+            return undefined;
+        }
+        if (!isValidSessionId(draft.from?.sessionId)) {
+            logger.warn("notification_queue.invalid_source_session_id", { kind: draft.kind });
+            return undefined;
         }
-        const next = [...(this.buckets.get(sessionId) ?? []), item];
-        this.buckets.set(sessionId, next);
+        if (!isStrictDirectionDraft(draft)) {
+            logger.warn("notification_queue.invalid_direction_draft");
+            return undefined;
+        }
+        const sequenceKey = routeSequenceKey(draft);
+        const sequence = (this.sequences.get(sequenceKey) ?? 0) + 1;
+        const id = nanoid();
+        const envelope = {
+            ...draft,
+            schemaVersion: 1,
+            id,
+            ...(draft.kind === "direction" && draft.correlationId === undefined
+                ? { correlationId: id }
+                : {}),
+            sequence,
+            createdAt: Date.now(),
+        };
+        if (envelope.kind === "result")
+            installLegacyResultAliases(envelope);
+        const bucket = this.buckets.get(envelope.to.sessionId) ?? [];
+        let next = bucket;
+        if (envelope.kind === "progress") {
+            next = bucket.filter((item) => item.kind !== "progress" ||
+                item.from.agentId !== envelope.from.agentId ||
+                item.from.sessionId !== envelope.from.sessionId);
+        }
+        else if (envelope.kind === "result" && envelope.from.agentId) {
+            next = bucket.filter((item) => item.kind !== "progress" ||
+                item.from.agentId !== envelope.from.agentId ||
+                (envelope.runtimeGeneration !== undefined &&
+                    item.runtimeGeneration !== envelope.runtimeGeneration));
+        }
+        this.sequences.set(sequenceKey, sequence);
+        this.sequenceRoutes.delete(sequenceKey);
+        this.sequenceRoutes.set(sequenceKey, {
+            from: envelope.from.sessionId,
+            to: envelope.to.sessionId,
+        });
+        while (this.sequences.size > this.maxSequenceRoutes) {
+            const oldest = this.sequenceRoutes.keys().next().value;
+            if (!oldest)
+                break;
+            this.sequenceRoutes.delete(oldest);
+            this.sequences.delete(oldest);
+        }
+        this.buckets.set(envelope.to.sessionId, [...next, envelope]);
         this.notify();
-        // B2.2 — also publish to the protocol-facing bus. The bus is a
-        // separate listener set so existing TUI subscribers (which poll the
-        // queue via getSnapshot/drainAll) are unaffected. The server
-        // subscribes on construction and forwards each event to its client
-        // via the existing `agent/streamEvent` notification path.
-        agentNotificationBus.publish(sessionId, notificationItemToStreamEvent(item));
+        agentNotificationBus.publish(envelope);
+        return envelope;
     }
-    subscribe = (cb) => {
-        this.listeners.add(cb);
-        return () => {
-            this.listeners.delete(cb);
-        };
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
     };
     getSnapshot = (sessionId) => {
         if (!isValidSessionId(sessionId))
             return EMPTY;
         return this.buckets.get(sessionId) ?? EMPTY;
     };
-    /** Atomic: returns all items for a session and clears that bucket. */
-    drainAll(sessionId) {
+    drain(sessionId, predicate) {
         if (!isValidSessionId(sessionId))
             return [];
-        const items = this.buckets.get(sessionId);
-        if (!items || items.length === 0)
+        const bucket = this.buckets.get(sessionId);
+        if (!bucket?.length)
+            return [];
+        const drained = [];
+        const retained = [];
+        for (const envelope of bucket) {
+            (predicate(envelope) ? drained : retained).push(envelope);
+        }
+        if (drained.length === 0)
             return [];
-        this.buckets.delete(sessionId);
+        if (retained.length > 0)
+            this.buckets.set(sessionId, retained);
+        else
+            this.buckets.delete(sessionId);
         this.notify();
-        return items;
+        return drained;
+    }
+    /** Compatibility consumer: only terminal results, never direction/progress. */
+    drainAll(sessionId) {
+        return this.drain(sessionId, (item) => item.kind === "result");
+    }
+    clearProgress(sessionId, agentId, runtimeGeneration) {
+        const bucket = this.buckets.get(sessionId);
+        if (!bucket?.length)
+            return false;
+        const retained = bucket.filter((item) => item.kind !== "progress" ||
+            item.from.agentId !== agentId ||
+            (runtimeGeneration !== undefined && item.runtimeGeneration !== runtimeGeneration));
+        if (retained.length === bucket.length)
+            return false;
+        if (retained.length > 0)
+            this.buckets.set(sessionId, retained);
+        else
+            this.buckets.delete(sessionId);
+        this.notify();
+        return true;
+    }
+    clearDirections(sessionId, runtimeGeneration) {
+        const bucket = this.buckets.get(sessionId);
+        if (!bucket?.length)
+            return false;
+        const retained = bucket.filter((item) => item.kind !== "direction" || item.runtimeGeneration !== runtimeGeneration);
+        if (retained.length === bucket.length)
+            return false;
+        if (retained.length > 0)
+            this.buckets.set(sessionId, retained);
+        else
+            this.buckets.delete(sessionId);
+        this.notify();
+        return true;
     }
-    /**
-     * Clear one bucket (sessionId given) or every bucket (no arg). Used by
-     * tests; production code drains per-session through `drainAll`.
-     */
     reset(sessionId) {
         if (sessionId === undefined) {
-            if (this.buckets.size === 0)
+            if (this.buckets.size === 0 && this.sequences.size === 0)
                 return;
             this.buckets.clear();
+            this.sequences.clear();
+            this.sequenceRoutes.clear();
         }
         else {
-            if (!this.buckets.has(sessionId))
+            const hadBucket = this.buckets.delete(sessionId);
+            let clearedRoute = false;
+            for (const [key, route] of this.sequenceRoutes) {
+                if (route.from !== sessionId && route.to !== sessionId)
+                    continue;
+                this.sequenceRoutes.delete(key);
+                this.sequences.delete(key);
+                clearedRoute = true;
+            }
+            if (!hadBucket && !clearedRoute)
                 return;
-            this.buckets.delete(sessionId);
         }
         this.notify();
     }
     notify() {
-        for (const cb of this.listeners) {
+        for (const listener of this.listeners) {
             try {
-                cb();
+                listener();
             }
             catch {
-                // isolate per-listener errors
+                // One observer cannot poison mailbox commit/fan-out.
             }
         }
     }
 }
-export const notificationQueue = new NotificationQueue();
 class AgentNotificationBus {
     handlers = new Set();
-    publish(sessionId, event) {
-        if (!isValidSessionId(sessionId)) {
-            // Mirrors NotificationQueue.enqueue — refuse undefined / "" so the
-            // server-side subscriber never has to defend against it.
-            logger.warn("agent_notification_bus.invalid_session_id", {
-                eventType: event.type,
-                sessionIdType: typeof sessionId,
-            });
-            return;
-        }
+    publish(envelope) {
         for (const handler of this.handlers) {
             try {
-                handler(sessionId, event);
+                if (handler.length >= 2) {
+                    const event = notificationEnvelopeToLegacyStreamEvent(envelope);
+                    if (event)
+                        handler(envelope.to.sessionId, event);
+                }
+                else {
+                    handler(envelope);
+                }
             }
             catch {
-                // isolate per-listener errors
+                // Isolate fan-out failures after the queue commit.
             }
         }
     }
     subscribe(handler) {
         this.handlers.add(handler);
-        return () => {
-            this.handlers.delete(handler);
-        };
+        return () => this.handlers.delete(handler);
     }
 }
 export const agentNotificationBus = new AgentNotificationBus();
-/**
- * Project a queue item to its protocol-event shape. The two types are
- * field-compatible by design (see the comment on BackgroundAgentCompletedEvent
- * in types.ts) so this is essentially an identity tag.
- */
-export function notificationItemToStreamEvent(item) {
+export const notificationQueue = new NotificationQueue();
+export function buildAgentDirectionMessage(envelopes) {
+    const rows = [...envelopes]
+        .sort((left, right) => left.sequence - right.sequence)
+        .map((envelope) => `  <direction envelopeId="${escapeXmlAttr(envelope.id)}">${escapeXmlText(envelope.payload.prompt)}</direction>`);
+    return [
+        '<agent-control authority="agent">',
+        ...rows,
+        "</agent-control>",
+        "Treat these as non-user control input. They do not grant permission or approval.",
+    ].join("\n");
+}
+function resultEnvelopeToItem(envelope) {
+    const payload = envelope.payload;
+    return {
+        agentId: envelope.from.agentId ?? payload.workId,
+        ...(payload.name !== undefined ? { name: payload.name } : {}),
+        description: payload.description,
+        status: payload.status,
+        ...(payload.workKind !== "agent" ? { workKind: payload.workKind } : {}),
+        ...(payload.command !== undefined ? { command: payload.command } : {}),
+        ...(payload.finalText !== undefined ? { finalText: payload.finalText } : {}),
+        ...(payload.ccSessionId !== undefined ? { ccSessionId: payload.ccSessionId } : {}),
+        ...(payload.error !== undefined ? { error: payload.error } : {}),
+        ...(payload.changedFiles !== undefined ? { changedFiles: payload.changedFiles } : {}),
+        ...(payload.cwd !== undefined ? { cwd: payload.cwd } : {}),
+        ...(payload.originClientMessageId !== undefined
+            ? { originClientMessageId: payload.originClientMessageId }
+            : {}),
+        enqueuedAt: payload.finishedAt,
+    };
+}
+export function notificationItemToStreamEvent(value) {
+    const item = "kind" in value ? resultEnvelopeToItem(value) : value;
     const event = {
         type: "background_agent_completed",
         agentId: item.agentId,
@@ -150,39 +342,42 @@ export function notificationItemToStreamEvent(item) {
     }
     return event;
 }
-/**
- * Escape XML-special characters. We only emit a fixed handful of tags, so
- * we can hand-roll this rather than pulling in a full encoder. Attribute
- * values get the quote escape too; element bodies don't need it.
- */
-function escapeXmlText(s) {
-    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
-function escapeXmlAttr(s) {
-    return escapeXmlText(s).replace(/"/g, "&quot;");
-}
-/**
- * Render a batch of completion notifications as the XML user-message
- * body that the main agent's LLM will see. Format is stable — main
- * agent prompts can rely on the `<background-agents-completed>` root
- * tag as a signal that this turn is a system-injected notification,
- * not a real user message.
- */
-export function buildNotificationMessage(items) {
+export function notificationEnvelopeToLegacyStreamEvent(envelope) {
+    if (envelope.kind === "result")
+        return notificationItemToStreamEvent(envelope);
+    if (envelope.kind === "progress") {
+        const event = {
+            type: "agent_heartbeat",
+            agentIds: envelope.from.agentId ? [envelope.from.agentId] : [],
+            ts: envelope.createdAt,
+        };
+        return event;
+    }
+    return undefined;
+}
+function asNotificationItems(values) {
+    return values.map((value) => ("kind" in value ? resultEnvelopeToItem(value) : value));
+}
+function escapeXmlText(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeXmlAttr(value) {
+    return escapeXmlText(value).replace(/"/g, "&quot;");
+}
+export function buildNotificationMessage(values) {
+    const items = asNotificationItems(values);
     const agents = items
         .map((item) => {
         const nameAttr = item.name ? ` name="${escapeXmlAttr(item.name)}"` : "";
-        // For DriveClaudeCode jobs, expose the real claude session id so the model
-        // can cite it / recover the full result from disk if needed.
         const ccAttr = item.ccSessionId ? ` ccSessionId="${escapeXmlAttr(item.ccSessionId)}"` : "";
         const opening = `  <agent id="${escapeXmlAttr(item.agentId)}"${nameAttr} status="${item.status}"${ccAttr}>`;
-        const desc = `    <description>${escapeXmlText(item.description)}</description>`;
+        const description = `    <description>${escapeXmlText(item.description)}</description>`;
         const body = item.status === "completed"
             ? `    <result>\n${escapeXmlText(item.finalText ?? "")}\n    </result>`
             : item.status === "cancelled"
                 ? `    <cancelled>${escapeXmlText(item.error ?? "cancelled")}</cancelled>`
                 : `    <error>${escapeXmlText(item.error ?? "")}</error>`;
-        return [opening, desc, body, "  </agent>"].join("\n");
+        return [opening, description, body, "  </agent>"].join("\n");
     })
         .join("\n");
     return [
@@ -193,13 +388,8 @@ export function buildNotificationMessage(items) {
         "Above are results from background agents that finished while you were idle. Address them appropriately — summarize for the user, continue work, or ignore if no longer relevant.",
     ].join("\n");
 }
-/**
- * One-line-per-agent human summary for the chat feed. The full result
- * body goes to the LLM via buildNotificationMessage; the user sees only
- * this terse marker plus an optional inline error preview, and can
- * switch to the sub-agent's dock view if they want details.
- */
-export function buildNotificationSummary(items) {
+export function buildNotificationSummary(values) {
+    const items = asNotificationItems(values);
     const header = "📨 background agents completed";
     const rows = items.map((item) => {
         const badge = item.status === "completed" ? "✓" : item.status === "cancelled" ? "cancelled" : "✗";
@@ -207,7 +397,7 @@ export function buildNotificationSummary(items) {
         const statusPart = item.status === "failed"
             ? `  ·  failed: ${item.error ?? "unknown"}`
             : item.status === "cancelled"
-                ? `  ·  cancelled`
+                ? "  ·  cancelled"
                 : "";
         return `  └─ ${namePart}${item.description}  ·  ${badge}${statusPart}`;
     });

package/dist/tool-system/builtin/agent-output-file.js

@@ -62,9 +62,7 @@ export async function clearAgentOutputFiles() {
     try {
         const dir = agentOutputDir();
         const names = await readdir(dir);
-        await Promise.all(names
-            .filter((n) => n.endsWith(".txt"))
-            .map((n) => rm(join(dir, n), { force: true })));
+        await Promise.all(names.filter((n) => n.endsWith(".txt")).map((n) => rm(join(dir, n), { force: true })));
     }
     catch {
         // dir may not exist yet — fine

package/dist/tool-system/builtin/agent-progress.d.ts

@@ -0,0 +1,6 @@
+import type { StreamEvent, TokenUsage } from "../../types.js";
+import type { AgentProgressPhase, ProgressPayload } from "./agent-notifications.js";
+export declare function initialAgentProgress(now?: number): ProgressPayload;
+export declare function reduceAgentProgress(previous: ProgressPayload, event: StreamEvent, now?: number): ProgressPayload;
+export declare function applyAgentProgressUsage(previous: ProgressPayload, usage: TokenUsage, now?: number): ProgressPayload;
+export declare function applyAgentProgressPhase(previous: ProgressPayload, phase: AgentProgressPhase, now?: number, toolName?: string): ProgressPayload;

package/dist/tool-system/builtin/agent-progress.js

@@ -0,0 +1,83 @@
+function safeSummary(value) {
+    return value
+        .replace(/[\u0000-\u001f\u007f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 160);
+}
+export function initialAgentProgress(now = Date.now()) {
+    return {
+        phase: "starting",
+        tokens: { prompt: 0, completion: 0, total: 0 },
+        summary: "正在启动",
+        observedAt: now,
+    };
+}
+export function reduceAgentProgress(previous, event, now = Date.now()) {
+    if (event.type === "stream_request_start") {
+        return { ...previous, phase: "model", summary: "模型处理中", observedAt: now };
+    }
+    if (event.type === "tool_use_start") {
+        const name = safeSummary(event.toolCall.toolName) || "tool";
+        return {
+            ...previous,
+            phase: "tool",
+            lastTool: { name, state: "running", startedAt: now },
+            summary: safeSummary(`正在运行 ${name}`),
+            observedAt: now,
+        };
+    }
+    if (event.type === "tool_result") {
+        const aborted = /abort/i.test(event.result.error ?? "");
+        const state = aborted
+            ? "aborted"
+            : event.result.error || event.result.isError
+                ? "failed"
+                : "completed";
+        const name = safeSummary(event.result.toolName) || previous.lastTool?.name || "tool";
+        return {
+            ...previous,
+            phase: "tool",
+            lastTool: {
+                name,
+                state,
+                startedAt: previous.lastTool?.startedAt,
+                finishedAt: now,
+            },
+            summary: safeSummary(`${name} ${state}`),
+            observedAt: now,
+        };
+    }
+    if (event.type === "context_compact") {
+        return { ...previous, phase: "compacting", summary: "正在压缩上下文", observedAt: now };
+    }
+    return previous;
+}
+export function applyAgentProgressUsage(previous, usage, now = Date.now()) {
+    const prompt = previous.tokens.prompt + (usage.promptTokens ?? 0);
+    const completion = previous.tokens.completion + (usage.completionTokens ?? 0);
+    return {
+        ...previous,
+        tokens: { prompt, completion, total: prompt + completion },
+        observedAt: now,
+    };
+}
+export function applyAgentProgressPhase(previous, phase, now = Date.now(), toolName) {
+    const name = toolName ? safeSummary(toolName) : undefined;
+    const summary = phase === "starting"
+        ? "正在启动"
+        : phase === "model"
+            ? "模型处理中"
+            : phase === "tool"
+                ? name
+                    ? `正在运行 ${name}`
+                    : "工具批次处理中"
+                : phase === "waiting-permission"
+                    ? name
+                        ? `等待用户批准 ${name}`
+                        : "等待用户批准"
+                    : phase === "compacting"
+                        ? "正在压缩上下文"
+                        : "正在收尾";
+    return { ...previous, phase, summary: safeSummary(summary), observedAt: now };
+}

package/dist/tool-system/builtin/agent-registry.d.ts

@@ -11,7 +11,28 @@
  * the right boundary: long-running cross-process work belongs to
  * RunManager, not here.
  */
-export type AsyncAgentStatus = "running" | "completed" | "failed" | "cancelled";
+export type AsyncAgentStatus = "running" | "cancelling" | "completed" | "failed" | "cancelled";
+import type { DirectionAck, DirectionDelivery, DirectionEnvelopeDraft, ProgressPayload } from "./agent-notifications.js";
+export type { DirectionAck } from "./agent-notifications.js";
+export type LiveChildState = "starting" | "model" | "tool-batch" | "safe-point" | "interrupting" | "redriving" | "closing" | "terminal";
+export interface LiveChildControl {
+    readonly childSessionId: string;
+    readonly runtimeGeneration: number;
+    getState(): LiveChildState;
+    routeDirection(draft: DirectionEnvelopeDraft): DirectionAck | Promise<DirectionAck>;
+}
+export interface ChildWriterLease {
+    childSessionId: string;
+    runtimeGeneration: number;
+    ownerToken: string;
+}
+export interface RouteDirectionRequest {
+    callerSessionId: string;
+    callerIsSubAgent: boolean;
+    agentId: string;
+    prompt: string;
+    delivery: DirectionDelivery;
+}
 /** Process-wide cap on concurrent background sub-agents (aligns with Codex max_threads=6). */
 export declare const MAX_BACKGROUND_AGENTS = 6;
 /**
@@ -44,6 +65,10 @@ export interface AsyncAgentEntry {
      *  this equals `agentId`, but it is stored explicitly so the contract is
      *  not coupled to that identity. Undefined for legacy entries. */
     childSessionId?: string;
+    runtimeGeneration?: number;
+    liveControl?: LiveChildControl;
+    writerLease?: ChildWriterLease;
+    progress?: ProgressPayload;
     status: AsyncAgentStatus;
     startedAt: number;
     finishedAt?: number;
@@ -57,6 +82,9 @@ declare class AsyncAgentRegistry {
     private agents;
     private listeners;
     private snapshot;
+    private writerLeases;
+    private generationByChildSession;
+    private closedDirectionIntake;
     subscribe: (cb: () => void) => (() => void);
     getSnapshot: () => AsyncAgentEntry[];
     hasRunning: () => boolean;
@@ -67,6 +95,14 @@ declare class AsyncAgentRegistry {
     runningCount(): number;
     private notify;
     register(entry: AsyncAgentEntry): void;
+    allocateRuntimeGeneration(childSessionId: string): number;
+    acquireWriterLease(childSessionId: string, runtimeGeneration: number, ownerToken: string): ChildWriterLease | undefined;
+    getWriterLease(childSessionId: string): ChildWriterLease | undefined;
+    releaseWriterLease(lease: ChildWriterLease): boolean;
+    bindLiveControl(agentId: string, control: LiveChildControl, lease: ChildWriterLease): boolean;
+    closeDirectionIntake(agentId: string, lease: ChildWriterLease): boolean;
+    updateProgress(agentId: string, progress: ProgressPayload): boolean;
+    routeDirection(request: RouteDirectionRequest): DirectionAck | Promise<DirectionAck>;
     appendToTranscript(agentId: string, entry: AgentTranscriptEntry): void;
     /**
      * Re-emit the registry change signal after callers mutate an agent's
@@ -83,6 +119,7 @@ declare class AsyncAgentRegistry {
      * Legacy entries with no sessionId are excluded from a session-scoped query.
      */
     listForSession(sessionId: string): AsyncAgentEntry[];
+    completeTerminal(agentId: string, status: "completed" | "failed" | "cancelled", lease: ChildWriterLease): boolean;
     private markFinished;
     markCompleted(agentId: string): void;
     markFailed(agentId: string): void;
@@ -91,4 +128,3 @@ declare class AsyncAgentRegistry {
     reset(): void;
 }
 export declare const asyncAgentRegistry: AsyncAgentRegistry;
-export {};