@qduc/term2 0.10.1 → 0.11.1

package/dist/services/subagents/subagent-manager.js

@@ -4,11 +4,13 @@ import { isAbortLike, safeEmit } from './utils.js';
 import { normalizeAgentRunUsage, extractUsage } from '../../utils/ai/token-usage.js';
 import { adaptLegacyRole, adaptLegacyDefinition } from '../agent-runtime/legacy-adapter.js';
 import { createAgentRuntimeFromSubagentRuntime } from '../agent-runtime/compose-agent-runtime.js';
+import { SubagentRegistryError } from './subagent-async-registry.js';
 export class SubagentManager {
     #logger;
     #settings;
     #onEvent;
     #runtime;
+    #mentorActive = false;
     constructor(deps) {
         this.#logger = deps.logger;
         this.#settings = deps.settings;
@@ -17,6 +19,7 @@ export class SubagentManager {
     }
     resetMentorSession() {
         this.#runtime.mentorRunner.reset();
+        this.#runtime.asyncRegistry.reset();
     }
     clearCache() {
         this.#runtime.nestedRunner.clearCache();
@@ -67,8 +70,14 @@ export class SubagentManager {
             parentTool: request.parentTool,
         });
         try {
+            if (request.role === 'mentor') {
+                if (this.#mentorActive || this.#runtime.asyncRegistry.hasActiveRunForRole('mentor')) {
+                    throw new SubagentRegistryError('already_active', 'Mentor session is already active');
+                }
+                this.#mentorActive = true;
+            }
             const result = request.role === 'mentor'
-                ? await this.#runtime.mentorRunner.run(agentId, request.task, request.signal)
+                ? await this.#runtime.mentorRunner.run(agentId, request.task, request.signal, undefined, request.executionBudget)
                 : await this.#runtime.executionRunner.run(agentId, request, this.#resolveRoleDefinition(request.role));
             safeEmit(this.#logger, this.#onEvent, { type: 'subagent_completed', result });
             return result;
@@ -95,6 +104,57 @@ export class SubagentManager {
             safeEmit(this.#logger, this.#onEvent, { type: 'subagent_completed', result });
             return result;
         }
+        finally {
+            if (request.role === 'mentor')
+                this.#mentorActive = false;
+        }
+    }
+    /**
+     * Start an asynchronous subagent run.
+     *
+     * Delegates to the SubagentAsyncRegistry, which owns the live session and
+     * run lifecycle. The returned handle exposes only the live-run contract.
+     */
+    startRunAsync(request) {
+        if (request.role === 'mentor' && this.#mentorActive) {
+            throw new SubagentRegistryError('already_active', 'Mentor session is already active');
+        }
+        return this.#runtime.asyncRegistry.startRun(request);
+    }
+    /**
+     * Retrieve the result of a previously started asynchronous subagent run.
+     */
+    getRunResult(runId, signal) {
+        return this.#runtime.asyncRegistry.getResult(runId, signal);
+    }
+    /**
+     * Non-blocking progress snapshot for the peek (get_subagent_status) tool.
+     * One run when `runId` is provided, all non-evicted runs otherwise. Never
+     * awaits and never carries completion detail.
+     */
+    getRunStatus(runId) {
+        return this.#runtime.asyncRegistry.getRunStatus(runId);
+    }
+    /** Queue parent steering or an ask_orchestrator answer without awaiting a run. */
+    sendMessageToAsyncRun(params) {
+        return this.#runtime.asyncRegistry.sendMessage(params.target, params.message, params.reply_to);
+    }
+    /** Request two-phase parent cancellation by canonical runId or active name. */
+    cancelAsyncRun(target) {
+        return this.#runtime.asyncRegistry.cancelRun(target);
+    }
+    abortAsyncRun(runId) {
+        this.#runtime.asyncRegistry.abortRun(runId);
+    }
+    resetAsyncRuns() {
+        this.#runtime.asyncRegistry.reset();
+    }
+    /** Cancel all live asynchronous runs for an explicit parent abort. */
+    cancelAllAsyncRuns() {
+        this.#runtime.asyncRegistry.cancelAllRuns();
+    }
+    dispose() {
+        this.#runtime.asyncRegistry.dispose();
     }
 }
 //# sourceMappingURL=subagent-manager.js.map

package/dist/services/subagents/subagent-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"subagent-manager.js","sourceRoot":"","sources":["../../../source/services/subagents/subagent-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"subagent-manager.js","sourceRoot":"","sources":["../../../source/services/subagents/subagent-manager.ts"],"names":[],"mappings":"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"}

package/dist/services/subagents/subagent-notification-store.d.ts

@@ -0,0 +1,107 @@
+import type { ConversationEvent } from '../conversation/conversation-events.js';
+/** A completed background run that still owes the main agent a notification. */
+export interface BackgroundSubagentCompletionNotification {
+    kind: 'completion';
+    /** Stable per logical run, so replay cannot duplicate a completion. */
+    messageId: string;
+    runId: string;
+    role: string;
+    status: 'completed' | 'failed' | 'cancelled';
+    preview: string;
+    error?: string;
+    completedAt: number;
+}
+/** A live execution segment's bounded request for its owning orchestrator. */
+export interface BackgroundSubagentQuestionNotification {
+    kind: 'question';
+    messageId: string;
+    runId: string;
+    name?: string;
+    role: string;
+    question: string;
+    askedAt: number;
+}
+/** A message-id-keyed queue item for a background async subagent. */
+export type BackgroundSubagentNotification = BackgroundSubagentCompletionNotification | BackgroundSubagentQuestionNotification;
+export type BackgroundSubagentTaskStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+/** The single most recent tool call observed for a live background run. */
+export interface BackgroundSubagentTaskTool {
+    /** Display-ready command line, e.g. `grep "TODO" src/`. */
+    label: string;
+    state: 'running' | 'success' | 'failed';
+}
+/** Conversation-scoped projection of one background subagent lifecycle. */
+export interface BackgroundSubagentTask {
+    runId: string;
+    role: string;
+    task: string;
+    status: BackgroundSubagentTaskStatus;
+    startedAt: number;
+    completedAt?: number;
+    /** Absent until the run calls its first tool; dropped once the run settles. */
+    lastTool?: BackgroundSubagentTaskTool;
+}
+/**
+ * The delivery half of {@link SubagentNotificationStore}, for callers that hand
+ * pending notifications to the main agent but never produce them.
+ */
+export interface BackgroundSubagentNotificationPort {
+    readonly pendingCount: number;
+    drain(): BackgroundSubagentNotification[];
+    retain(notifications: readonly BackgroundSubagentNotification[]): void;
+}
+/** Read-only lifecycle projection used by the background-tasks UI. */
+export interface BackgroundSubagentTaskPort {
+    getSnapshot(): readonly BackgroundSubagentTask[];
+    setObserver(observer: (() => void) | null): void;
+}
+export interface SubagentNotificationStoreDeps {
+    /** Injectable clock so completion timestamps stay deterministic under test. */
+    now?: () => number;
+    /** How long terminal tasks remain visible in the background overview. */
+    recentTaskRetentionMs?: number;
+    /**
+     * Upper bound on remembered notification ids. The async registry caps
+     * sessions at 50 and TTLs terminal runs out after 30 minutes, so a few
+     * hundred ids covers replay protection while staying O(1) in memory.
+     */
+    deliveredIdCap?: number;
+}
+export declare const BACKGROUND_TASK_RECENT_RETENTION_MS = 5000;
+/**
+ * Pending notifications for background (async) subagent runs.
+ *
+ * Owns three invariants the callers must not have to re-derive:
+ *  - Only async completions and async registry questions are notifiable.
+ *    Foreground and nested activity has no async flag and never surfaces here.
+ *  - A message is announced at most once, ever. Completion ids are stable per
+ *    run while each question has its own id, allowing one live run to ask more
+ *    than once over its lifetime without replaying either message.
+ *  - Delivery is confirmed by the caller, not by reading. `drain()` hands over
+ *    the pending batch and clears it; a caller whose delivery failed calls
+ *    `retain()` to put the batch back at the front of the queue. Drain/retain
+ *    was chosen over peek/commit because the common path (delivery succeeds) is
+ *    then a single call, and because retained notifications are handed back as
+ *    values rather than leaving the store holding provisional state. A message
+ *    id stays deduped across both paths, so a retained notification is
+ *    redelivered exactly once and a replayed event for it is still dropped.
+ */
+export declare class SubagentNotificationStore implements BackgroundSubagentNotificationPort {
+    #private;
+    constructor(deps?: SubagentNotificationStoreDeps);
+    /**
+     * Updates the read-only task projection for async starts, tool activity, and
+     * completions. Only the newest tool call of a live run is kept: the overview
+     * answers "what is it doing now", not "what has it done".
+     */
+    recordLifecycle(event: ConversationEvent): boolean;
+    getTaskSnapshot(): readonly BackgroundSubagentTask[];
+    /** Records one novel async completion or question, returning whether it woke the queue. */
+    enqueue(event: ConversationEvent): boolean;
+    get pendingCount(): number;
+    /** Hands over every pending notification in completion order and clears them. */
+    drain(): BackgroundSubagentNotification[];
+    /** Returns undelivered notifications to the queue, ahead of anything newer. */
+    retain(notifications: readonly BackgroundSubagentNotification[]): void;
+}
+//# sourceMappingURL=subagent-notification-store.d.ts.map

package/dist/services/subagents/subagent-notification-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-notification-store.d.ts","sourceRoot":"","sources":["../../../source/services/subagents/subagent-notification-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,wCAAwC,CAAC;AAKhD,gFAAgF;AAChF,MAAM,WAAW,wCAAwC;IACvD,IAAI,EAAE,YAAY,CAAC;IACnB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,8EAA8E;AAC9E,MAAM,WAAW,sCAAsC;IACrD,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qEAAqE;AACrE,MAAM,MAAM,8BAA8B,GACtC,wCAAwC,GACxC,sCAAsC,CAAC;AAE3C,MAAM,MAAM,4BAA4B,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE5F,2EAA2E;AAC3E,MAAM,WAAW,0BAA0B;IACzC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;CACzC;AAED,2EAA2E;AAC3E,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,4BAA4B,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,0BAA0B,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,KAAK,IAAI,8BAA8B,EAAE,CAAC;IAC1C,MAAM,CAAC,aAAa,EAAE,SAAS,8BAA8B,EAAE,GAAG,IAAI,CAAC;CACxE;AAED,sEAAsE;AACtE,MAAM,WAAW,0BAA0B;IACzC,WAAW,IAAI,SAAS,sBAAsB,EAAE,CAAC;IACjD,WAAW,CAAC,QAAQ,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,6BAA6B;IAC5C,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,yEAAyE;IACzE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAGD,eAAO,MAAM,mCAAmC,OAAQ,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,yBAA0B,YAAW,kCAAkC;;IASlF,YAAY,IAAI,GAAE,6BAAkC,EAInD;IAED;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CA+CjD;IA6BD,eAAe,IAAI,SAAS,sBAAsB,EAAE,CAQnD;IAED,2FAA2F;IAC3F,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAQzC;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,iFAAiF;IACjF,KAAK,IAAI,8BAA8B,EAAE,CAOxC;IAED,+EAA+E;IAC/E,MAAM,CAAC,aAAa,EAAE,SAAS,8BAA8B,EAAE,GAAG,IAAI,CASrE;CA+CF"}

package/dist/services/subagents/subagent-notification-store.js

@@ -0,0 +1,209 @@
+import { formatToolCommand, parseToolArguments } from '../../utils/conversation/conversation-utils.js';
+import { truncatePreview } from './utils.js';
+const DEFAULT_DELIVERED_ID_CAP = 256;
+export const BACKGROUND_TASK_RECENT_RETENTION_MS = 5_000;
+/**
+ * Pending notifications for background (async) subagent runs.
+ *
+ * Owns three invariants the callers must not have to re-derive:
+ *  - Only async completions and async registry questions are notifiable.
+ *    Foreground and nested activity has no async flag and never surfaces here.
+ *  - A message is announced at most once, ever. Completion ids are stable per
+ *    run while each question has its own id, allowing one live run to ask more
+ *    than once over its lifetime without replaying either message.
+ *  - Delivery is confirmed by the caller, not by reading. `drain()` hands over
+ *    the pending batch and clears it; a caller whose delivery failed calls
+ *    `retain()` to put the batch back at the front of the queue. Drain/retain
+ *    was chosen over peek/commit because the common path (delivery succeeds) is
+ *    then a single call, and because retained notifications are handed back as
+ *    values rather than leaving the store holding provisional state. A message
+ *    id stays deduped across both paths, so a retained notification is
+ *    redelivered exactly once and a replayed event for it is still dropped.
+ */
+export class SubagentNotificationStore {
+    #pending = new Map();
+    #seen = new Set();
+    #tasks = new Map();
+    #settledTaskIds = new Set();
+    #now;
+    #deliveredIdCap;
+    #recentTaskRetentionMs;
+    constructor(deps = {}) {
+        this.#now = deps.now ?? Date.now;
+        this.#deliveredIdCap = Math.max(1, deps.deliveredIdCap ?? DEFAULT_DELIVERED_ID_CAP);
+        this.#recentTaskRetentionMs = Math.max(0, deps.recentTaskRetentionMs ?? BACKGROUND_TASK_RECENT_RETENTION_MS);
+    }
+    /**
+     * Updates the read-only task projection for async starts, tool activity, and
+     * completions. Only the newest tool call of a live run is kept: the overview
+     * answers "what is it doing now", not "what has it done".
+     */
+    recordLifecycle(event) {
+        if (event.type === 'subagent_tool_started' || event.type === 'subagent_command_message') {
+            return this.#recordToolActivity(event);
+        }
+        if (event.type === 'subagent_started' && event.async === true) {
+            if (this.#settledTaskIds.has(event.agentId))
+                return false;
+            const existing = this.#tasks.get(event.agentId);
+            if (existing && existing.status !== 'running')
+                return false;
+            if (existing?.status === 'running' && existing.role === event.role && existing.task === event.task) {
+                return false;
+            }
+            this.#tasks.set(event.agentId, {
+                runId: event.agentId,
+                role: event.role,
+                task: event.task,
+                status: 'running',
+                startedAt: existing?.startedAt ?? this.#now(),
+            });
+            return true;
+        }
+        if (event.type !== 'subagent_completed' || event.async !== true)
+            return false;
+        const result = event.result;
+        if (!result?.agentId)
+            return false;
+        if (this.#settledTaskIds.has(result.agentId))
+            return false;
+        const existing = this.#tasks.get(result.agentId);
+        if (existing && existing.status !== 'running')
+            return false;
+        const completedAt = this.#now();
+        this.#tasks.set(result.agentId, {
+            runId: result.agentId,
+            role: existing?.role ?? result.role,
+            task: existing?.task ?? '',
+            status: result.status,
+            startedAt: existing?.startedAt ?? completedAt,
+            completedAt,
+        });
+        this.#settledTaskIds.add(result.agentId);
+        while (this.#settledTaskIds.size > this.#deliveredIdCap) {
+            const oldest = this.#settledTaskIds.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.#settledTaskIds.delete(oldest);
+        }
+        return true;
+    }
+    /**
+     * Projects the newest tool call of a live run. Tool events carry no `async`
+     * flag, so membership in the running task map is what scopes this to
+     * background runs — foreground and nested activity never registers a task.
+     */
+    #recordToolActivity(event) {
+        const task = this.#tasks.get(event.agentId);
+        if (!task || task.status !== 'running')
+            return false;
+        const lastTool = event.type === 'subagent_tool_started'
+            ? {
+                label: formatToolCommand(event.toolName, parseToolArguments(event.arguments)),
+                state: 'running',
+            }
+            : {
+                label: event.message?.command ?? '',
+                state: event.message?.success === false ? 'failed' : 'success',
+            };
+        if (!lastTool.label)
+            return false;
+        if (task.lastTool?.label === lastTool.label && task.lastTool.state === lastTool.state)
+            return false;
+        this.#tasks.set(event.agentId, { ...task, lastTool });
+        return true;
+    }
+    getTaskSnapshot() {
+        const now = this.#now();
+        for (const [runId, task] of this.#tasks) {
+            if (task.completedAt !== undefined && now - task.completedAt >= this.#recentTaskRetentionMs) {
+                this.#tasks.delete(runId);
+            }
+        }
+        return [...this.#tasks.values()];
+    }
+    /** Records one novel async completion or question, returning whether it woke the queue. */
+    enqueue(event) {
+        const notification = this.#notificationFor(event);
+        if (!notification || this.#seen.has(notification.messageId))
+            return false;
+        this.#pending.set(notification.messageId, notification);
+        this.#seen.add(notification.messageId);
+        this.#evictOldestSeen();
+        return true;
+    }
+    get pendingCount() {
+        return this.#pending.size;
+    }
+    /** Hands over every pending notification in completion order and clears them. */
+    drain() {
+        const drained = [...this.#pending.values()];
+        this.#pending.clear();
+        // Handing the batch over is the point at which old ids become evictable:
+        // nothing is owed a notification any more, only replay protection.
+        this.#evictOldestSeen();
+        return drained;
+    }
+    /** Returns undelivered notifications to the queue, ahead of anything newer. */
+    retain(notifications) {
+        if (notifications.length === 0)
+            return;
+        const newer = [...this.#pending.values()];
+        this.#pending.clear();
+        for (const notification of notifications) {
+            this.#pending.set(notification.messageId, notification);
+            this.#seen.add(notification.messageId);
+        }
+        for (const notification of newer)
+            this.#pending.set(notification.messageId, notification);
+    }
+    /**
+     * Drops the oldest remembered ids once the cap is exceeded, skipping runs that
+     * still owe a notification: correctness of an undelivered notification wins
+     * over the memory bound, and the pending queue is itself bounded by the number
+     * of runs the registry will retain. Forgetting an id only costs replay
+     * protection for a run that was delivered long ago.
+     */
+    #evictOldestSeen() {
+        if (this.#seen.size <= this.#deliveredIdCap)
+            return;
+        for (const messageId of this.#seen) {
+            if (this.#seen.size <= this.#deliveredIdCap)
+                return;
+            if (this.#pending.has(messageId))
+                continue;
+            this.#seen.delete(messageId);
+        }
+    }
+    #notificationFor(event) {
+        if (event.type === 'subagent_completed' && event.async === true) {
+            const result = event.result;
+            const runId = result?.agentId;
+            if (!result || !runId)
+                return undefined;
+            return {
+                kind: 'completion',
+                messageId: `completion:${runId}`,
+                runId,
+                role: result.role,
+                status: result.status,
+                preview: truncatePreview(result.finalText || result.error),
+                ...(result.error ? { error: result.error } : {}),
+                completedAt: this.#now(),
+            };
+        }
+        if (event.type === 'subagent_question' && event.async === true && event.messageId && event.runId) {
+            return {
+                kind: 'question',
+                messageId: event.messageId,
+                runId: event.runId,
+                ...(event.name !== undefined ? { name: event.name } : {}),
+                role: event.role,
+                question: event.question,
+                askedAt: this.#now(),
+            };
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=subagent-notification-store.js.map

package/dist/services/subagents/subagent-notification-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-notification-store.js","sourceRoot":"","sources":["../../../source/services/subagents/subagent-notification-store.ts"],"names":[],"mappings":"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"}

package/dist/services/subagents/subagent-run-control.d.ts

@@ -0,0 +1,41 @@
+export interface SubagentRunControlOptions {
+    maxMailboxMessages?: number;
+    maxMailboxCharacters?: number;
+    maxContinuationSegments?: number;
+    createQuestionId?: () => string;
+}
+export interface PendingSubagentQuestion {
+    messageId: string;
+    question: string;
+}
+export interface AskedSubagentQuestion extends PendingSubagentQuestion {
+    answer: Promise<string>;
+}
+/**
+ * Per-logical-run coordination state. The registry owns lifecycle and identity;
+ * runners receive only the narrow callbacks they need for a segment.
+ */
+export declare class SubagentRunControl {
+    #private;
+    constructor(options?: SubagentRunControlOptions);
+    get currentSegmentController(): AbortController | undefined;
+    get activeToolCount(): number;
+    get cancellationRequested(): boolean;
+    get hasQueuedSteering(): boolean;
+    get currentSegmentAbortReason(): 'steer' | 'cancel' | undefined;
+    get continuationSegments(): number;
+    canStartContinuation(): boolean;
+    startContinuation(): boolean;
+    get pendingQuestion(): PendingSubagentQuestion | undefined;
+    beginSegment(): AbortController;
+    endSegment(controller: AbortController): void;
+    onToolStart(): void;
+    onToolComplete(): void;
+    enqueueSteering(message: string): void;
+    consumeSteering(): string | undefined;
+    ask(question: string): AskedSubagentQuestion;
+    answer(messageId: string, answer: string): boolean;
+    requestCancellation(): void;
+    settle(reason?: Error): void;
+}
+//# sourceMappingURL=subagent-run-control.d.ts.map

package/dist/services/subagents/subagent-run-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-run-control.d.ts","sourceRoot":"","sources":["../../../source/services/subagents/subagent-run-control.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,yBAAyB;IACxC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAOD;;;GAGG;AACH,qBAAa,kBAAkB;;IAgB7B,YAAY,OAAO,GAAE,yBAA8B,EAKlD;IAED,IAAI,wBAAwB,IAAI,eAAe,GAAG,SAAS,CAE1D;IAED,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,IAAI,qBAAqB,IAAI,OAAO,CAEnC;IAED,IAAI,iBAAiB,IAAI,OAAO,CAE/B;IAED,IAAI,yBAAyB,IAAI,OAAO,GAAG,QAAQ,GAAG,SAAS,CAE9D;IAED,IAAI,oBAAoB,IAAI,MAAM,CAEjC;IAED,oBAAoB,IAAI,OAAO,CAE9B;IAED,iBAAiB,IAAI,OAAO,CAI3B;IAED,IAAI,eAAe,IAAI,uBAAuB,GAAG,SAAS,CAEzD;IAED,YAAY,IAAI,eAAe,CAO9B;IAED,UAAU,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI,CAM5C;IAED,WAAW,IAAI,IAAI,CAElB;IAED,cAAc,IAAI,IAAI,CAIrB;IAED,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAarC;IAED,eAAe,IAAI,MAAM,GAAG,SAAS,CAQpC;IAED,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAe3C;IAED,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAMjD;IAED,mBAAmB,IAAI,IAAI,CAO1B;IAED,MAAM,CAAC,MAAM,QAA+C,GAAG,IAAI,CAKlE;CAaF"}

package/dist/services/subagents/subagent-run-control.js

@@ -0,0 +1,166 @@
+import { randomUUID } from 'node:crypto';
+const DEFAULT_MAX_MAILBOX_MESSAGES = 4;
+const DEFAULT_MAX_MAILBOX_CHARACTERS = 4_000;
+const DEFAULT_MAX_CONTINUATION_SEGMENTS = 3;
+const MAX_QUESTION_CHARACTERS = 1_200;
+const TRUNCATION_MARKER = '[Earlier steering omitted]';
+/**
+ * Per-logical-run coordination state. The registry owns lifecycle and identity;
+ * runners receive only the narrow callbacks they need for a segment.
+ */
+export class SubagentRunControl {
+    #maxMailboxMessages;
+    #maxMailboxCharacters;
+    #maxContinuationSegments;
+    #createQuestionId;
+    #controller;
+    #abortReason;
+    #activeToolCount = 0;
+    #interruptWhenToolsIdle = false;
+    #cancellationRequested = false;
+    #mailbox = [];
+    #mailboxCharacters = 0;
+    #mailboxTruncated = false;
+    #continuationSegments = 0;
+    #question;
+    constructor(options = {}) {
+        this.#maxMailboxMessages = options.maxMailboxMessages ?? DEFAULT_MAX_MAILBOX_MESSAGES;
+        this.#maxMailboxCharacters = options.maxMailboxCharacters ?? DEFAULT_MAX_MAILBOX_CHARACTERS;
+        this.#maxContinuationSegments = options.maxContinuationSegments ?? DEFAULT_MAX_CONTINUATION_SEGMENTS;
+        this.#createQuestionId = options.createQuestionId ?? randomUUID;
+    }
+    get currentSegmentController() {
+        return this.#controller;
+    }
+    get activeToolCount() {
+        return this.#activeToolCount;
+    }
+    get cancellationRequested() {
+        return this.#cancellationRequested;
+    }
+    get hasQueuedSteering() {
+        return this.#mailbox.length > 0;
+    }
+    get currentSegmentAbortReason() {
+        return this.#abortReason;
+    }
+    get continuationSegments() {
+        return this.#continuationSegments;
+    }
+    canStartContinuation() {
+        return !this.#cancellationRequested && this.#continuationSegments < this.#maxContinuationSegments;
+    }
+    startContinuation() {
+        if (!this.canStartContinuation())
+            return false;
+        this.#continuationSegments++;
+        return true;
+    }
+    get pendingQuestion() {
+        return this.#question && { messageId: this.#question.messageId, question: this.#question.question };
+    }
+    beginSegment() {
+        if (this.#controller)
+            throw new Error('A subagent segment is already active.');
+        const controller = new AbortController();
+        this.#controller = controller;
+        this.#abortReason = undefined;
+        if (this.#cancellationRequested)
+            this.#abortCurrentSegment('cancel');
+        return controller;
+    }
+    endSegment(controller) {
+        if (this.#controller !== controller)
+            return;
+        this.#controller = undefined;
+        this.#abortReason = undefined;
+        this.#activeToolCount = 0;
+        this.#interruptWhenToolsIdle = false;
+    }
+    onToolStart() {
+        this.#activeToolCount++;
+    }
+    onToolComplete() {
+        if (this.#activeToolCount === 0)
+            return;
+        this.#activeToolCount--;
+        if (this.#activeToolCount === 0 && this.#interruptWhenToolsIdle)
+            this.#abortCurrentSegment();
+    }
+    enqueueSteering(message) {
+        this.#mailbox.push(message);
+        this.#mailboxCharacters += message.length;
+        while (this.#mailbox.length > this.#maxMailboxMessages ||
+            (this.#mailbox.length > 1 && this.#mailboxCharacters > this.#maxMailboxCharacters)) {
+            const removed = this.#mailbox.shift();
+            this.#mailboxCharacters -= removed?.length ?? 0;
+            this.#mailboxTruncated = true;
+        }
+        this.#interruptWhenToolsIdle = true;
+        if (this.#activeToolCount === 0)
+            this.#abortCurrentSegment();
+    }
+    consumeSteering() {
+        if (this.#mailbox.length === 0)
+            return undefined;
+        const messages = this.#mailbox;
+        const truncated = this.#mailboxTruncated;
+        this.#mailbox = [];
+        this.#mailboxCharacters = 0;
+        this.#mailboxTruncated = false;
+        return [truncated ? TRUNCATION_MARKER : undefined, ...messages].filter(Boolean).join('\n');
+    }
+    ask(question) {
+        const boundedQuestion = question.trim();
+        if (boundedQuestion.length === 0)
+            throw new Error('A subagent question cannot be empty.');
+        if (boundedQuestion.length > MAX_QUESTION_CHARACTERS)
+            throw new Error(`Question exceeds ${MAX_QUESTION_CHARACTERS} characters.`);
+        if (this.#question)
+            throw new Error('A subagent question is already pending.');
+        let resolve;
+        let reject;
+        const answer = new Promise((resolveAnswer, rejectAnswer) => {
+            resolve = resolveAnswer;
+            reject = rejectAnswer;
+        });
+        const pending = { messageId: this.#createQuestionId(), question: boundedQuestion, resolve, reject };
+        this.#question = pending;
+        return { messageId: pending.messageId, question: boundedQuestion, answer };
+    }
+    answer(messageId, answer) {
+        if (!this.#question || this.#question.messageId !== messageId)
+            return false;
+        const pending = this.#question;
+        this.#question = undefined;
+        pending.resolve(answer);
+        return true;
+    }
+    requestCancellation() {
+        this.#cancellationRequested = true;
+        this.#mailbox = [];
+        this.#mailboxCharacters = 0;
+        this.#mailboxTruncated = false;
+        this.#rejectPendingQuestion(new Error('The subagent run was cancelled.'));
+        this.#abortCurrentSegment('cancel');
+    }
+    settle(reason = new Error('The subagent run was cancelled.')) {
+        this.#mailbox = [];
+        this.#mailboxCharacters = 0;
+        this.#mailboxTruncated = false;
+        this.#rejectPendingQuestion(reason);
+    }
+    #rejectPendingQuestion(reason) {
+        if (!this.#question)
+            return;
+        const pending = this.#question;
+        this.#question = undefined;
+        pending.reject(reason);
+    }
+    #abortCurrentSegment(reason = 'steer') {
+        this.#abortReason = reason;
+        if (this.#controller && !this.#controller.signal.aborted)
+            this.#controller.abort();
+    }
+}
+//# sourceMappingURL=subagent-run-control.js.map