praxis-agent 0.33.0 → 0.35.0

package/README.md

@@ -236,6 +236,10 @@ npm ci
 npm run check
 ```
 
+`npm run build:native` compiles the current Praxis-owned core, provider
+adapters, and native data-plane slice without the Claude compatibility adapter.
+`npm run check` also enforces the corresponding source dependency direction.
+
 Contributions use Conventional Commit pull-request titles and the protected
 squash-merge workflow. Read
 [CONTRIBUTING.md](https://github.com/Forest-Isle/Praxis/blob/main/CONTRIBUTING.md)

package/dist/application/background-agent-manager.d.ts

@@ -10,11 +10,15 @@ export interface BackgroundAgentRunResult {
     isolationPath?: string;
     isolationRetained?: boolean;
     isolationWarning?: string;
+    notificationId?: string;
 }
 export declare class BackgroundAgentRunError extends Error {
     readonly result?: BackgroundAgentRunResult | undefined;
     constructor(message: string, result?: BackgroundAgentRunResult | undefined, cause?: unknown);
 }
+export declare class BackgroundAgentShutdownError extends Error {
+    constructor();
+}
 export interface BackgroundAgentTaskSpec {
     agentId: string;
     name?: string;
@@ -24,9 +28,18 @@ export interface BackgroundAgentTaskSpec {
     toolUseId: string;
     outputFile: string;
     resolvedModel: string;
-    run(message: string, signal: AbortSignal, continuation: boolean): Promise<BackgroundAgentRunResult>;
+    markBackground?(): void;
+    acknowledgeNotification?(notificationId: string): Promise<void>;
+    prepareNotificationDetached?(notificationId: string, model: string): Promise<void>;
+    confirmNotificationDetached?(notificationId: string): Promise<void>;
+    run(message: string, signal: AbortSignal, continuation: boolean, toolUseId: string): Promise<BackgroundAgentRunResult>;
+}
+type BackgroundAgentStatus = 'running' | 'completed' | 'failed' | 'stopped' | 'interrupted';
+export interface BackgroundAgentNotificationIdentity {
+    agentId: string;
+    toolUseId: string;
+    status: 'completed' | 'failed' | 'killed';
 }
-type BackgroundAgentStatus = 'running' | 'completed' | 'failed' | 'stopped';
 export interface BackgroundAgentSnapshot {
     agentId: string;
     status: BackgroundAgentStatus;
@@ -38,13 +51,33 @@ export interface BackgroundAgentSnapshot {
     startedAt: number;
     durationMs: number | null;
 }
+export declare function backgroundAgentNotificationMarkers(notification: BackgroundAgentNotificationIdentity): readonly string[];
 export declare class BackgroundAgentManager {
     private readonly tasks;
     private readonly names;
+    private readonly closedSignal;
+    private resolveClosed;
     private closed;
+    constructor();
     launch(spec: BackgroundAgentTaskSpec): BackgroundAgentSnapshot;
+    adopt(options: {
+        spec: BackgroundAgentTaskSpec;
+        controller: AbortController;
+        operation: Promise<BackgroundAgentRunResult>;
+        startedAt: number;
+    }): BackgroundAgentSnapshot;
     registerCompleted(spec: BackgroundAgentTaskSpec, result: BackgroundAgentRunResult): BackgroundAgentSnapshot;
+    registerInterrupted(spec: BackgroundAgentTaskSpec, error?: string): BackgroundAgentSnapshot;
+    registerTerminal(spec: BackgroundAgentTaskSpec, status: 'failed' | 'stopped', error: string): BackgroundAgentSnapshot;
+    registerPersistedNotification(agentId: string, notification: {
+        id: string;
+        status: 'completed' | 'failed' | 'stopped';
+        result: BackgroundAgentRunResult | null;
+        error: string | null;
+        toolUseId: string;
+    }): void;
     has(agentId: string): boolean;
+    notificationClaimAgentIds(): string[];
     snapshotById(agentId: string): BackgroundAgentSnapshot | null;
     snapshots(): readonly BackgroundAgentSnapshot[];
     output(agentId: string, options: {
@@ -52,11 +85,14 @@ export declare class BackgroundAgentManager {
         timeout: number;
     }): Promise<string>;
     stop(agentId: string): string;
-    close(): Promise<void>;
+    stopAndWait(agentId: string, timeout?: number): Promise<string>;
+    stopAll(): readonly string[];
+    close(drainMilliseconds?: number): Promise<void>;
     send(agentId: string, message: string, summary: string | undefined, toolUseId: string): string;
     notifications(options: {
         waitForRunning: boolean;
         excludeAgentId?: string;
+        consume?: boolean;
     }): Promise<{
         messages: string[];
         usage: ModelUsage;
@@ -64,8 +100,17 @@ export declare class BackgroundAgentManager {
         durationApiMs?: number;
         durationApiWithoutRetriesMs?: number;
     }>;
+    acknowledge(messages: readonly string[]): Promise<void>;
+    prepareNotificationsDetached(messages: readonly string[]): Promise<void>;
+    confirmNotificationsDetached(messages: readonly string[]): Promise<void>;
+    private forEachMatchingNotification;
+    acknowledgeDelivered(delivered: (notification: BackgroundAgentNotificationIdentity) => boolean): Promise<void>;
+    acknowledgeDeliveredAsDetached(delivered: (notification: BackgroundAgentNotificationIdentity) => boolean): Promise<void>;
     private start;
+    private track;
+    private registerTask;
     private resolveOptional;
+    private stopTask;
     private assertNameAvailable;
     private finishStopped;
     private resolveRequired;

package/dist/application/background-agent-manager.js

@@ -1,5 +1,7 @@
-const AGENT_ID_PATTERN = /^a[0-9a-f]{16}$/u;
+import { randomUUID } from 'node:crypto';
+import { isClaudeAgentId } from '../compatibility/claude/sidechain.js';
 const MAX_TIMEOUT_MS = 600_000;
+const DEFAULT_CLOSE_DRAIN_MS = 5_000;
 export class BackgroundAgentRunError extends Error {
     result;
     constructor(message, result, cause) {
@@ -8,8 +10,14 @@ export class BackgroundAgentRunError extends Error {
         this.name = 'BackgroundAgentRunError';
     }
 }
+export class BackgroundAgentShutdownError extends Error {
+    constructor() {
+        super('Background agent manager closed');
+        this.name = 'BackgroundAgentShutdownError';
+    }
+}
 function assertAgentId(agentId) {
-    if (!AGENT_ID_PATTERN.test(agentId)) {
+    if (!isClaudeAgentId(agentId)) {
         throw new Error(`Invalid background agent ID: ${agentId}`);
     }
 }
@@ -21,6 +29,13 @@ function escapeXml(value) {
         .replaceAll('"', '"')
         .replaceAll("'", ''');
 }
+export function backgroundAgentNotificationMarkers(notification) {
+    return [
+        `<task-id>${notification.agentId}</task-id>`,
+        `<tool-use-id>${escapeXml(notification.toolUseId)}</tool-use-id>`,
+        `<status>${notification.status}</status>`,
+    ];
+}
 function waitBounded(operation, milliseconds) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(resolve, milliseconds);
@@ -149,71 +164,95 @@ function mergeToolModelUsage(map, breakdown) {
 export class BackgroundAgentManager {
     tasks = new Map();
     names = new Map();
+    closedSignal;
+    resolveClosed;
     closed = false;
+    constructor() {
+        this.closedSignal = new Promise((resolve) => {
+            this.resolveClosed = resolve;
+        });
+    }
     launch(spec) {
-        if (this.closed)
-            throw new Error('Background agent manager is closed');
-        assertAgentId(spec.agentId);
-        if (spec.name !== undefined &&
-            !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/u.test(spec.name)) {
-            throw new Error(`Invalid background agent name: ${spec.name}`);
-        }
-        if (this.tasks.has(spec.agentId)) {
-            throw new Error(`Background agent ${spec.agentId} already exists`);
-        }
-        this.assertNameAvailable(spec.name, spec.agentId);
-        if (spec.name !== undefined)
-            this.names.set(spec.name, spec.agentId);
-        const task = {
-            spec,
+        const { task } = this.registerTask(spec, {
             status: 'running',
             controller: null,
-            promise: null,
             result: null,
             error: null,
-            notifications: [],
             generation: 0,
-            queuedMessages: [],
             startedAt: Date.now(),
             durationMs: null,
-        };
-        this.tasks.set(spec.agentId, task);
+        }, 'throw');
+        spec.markBackground?.();
         this.start(task, spec.prompt, false, spec.toolUseId);
         return this.snapshot(task);
     }
+    adopt(options) {
+        const { spec } = options;
+        const { task } = this.registerTask(spec, {
+            status: 'running',
+            controller: options.controller,
+            result: null,
+            error: null,
+            generation: 1,
+            startedAt: options.startedAt,
+            durationMs: null,
+        }, 'throw');
+        spec.markBackground?.();
+        this.track(task, options.operation, 1, spec.toolUseId);
+        return this.snapshot(task);
+    }
     registerCompleted(spec, result) {
-        if (this.closed)
-            throw new Error('Background agent manager is closed');
-        assertAgentId(spec.agentId);
-        if (spec.name !== undefined &&
-            !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/u.test(spec.name)) {
-            throw new Error(`Invalid background agent name: ${spec.name}`);
-        }
-        const existing = this.tasks.get(spec.agentId);
-        if (existing)
-            return this.snapshot(existing);
-        this.assertNameAvailable(spec.name, spec.agentId);
-        if (spec.name !== undefined)
-            this.names.set(spec.name, spec.agentId);
-        const task = {
-            spec,
+        const { task } = this.registerTask(spec, {
             status: 'completed',
             controller: null,
-            promise: null,
             result,
             error: null,
-            notifications: [],
             generation: 0,
-            queuedMessages: [],
             startedAt: Date.now() - result.durationMs,
             durationMs: result.durationMs,
-        };
-        this.tasks.set(spec.agentId, task);
+        }, 'return-existing');
+        return this.snapshot(task);
+    }
+    registerInterrupted(spec, error = 'Persisted agent was interrupted before completion') {
+        const { task } = this.registerTask(spec, {
+            status: 'interrupted',
+            controller: null,
+            result: null,
+            error,
+            generation: 0,
+            startedAt: Date.now(),
+            durationMs: 0,
+        }, 'return-existing');
         return this.snapshot(task);
     }
+    registerTerminal(spec, status, error) {
+        const { task } = this.registerTask(spec, {
+            status,
+            controller: null,
+            result: null,
+            error,
+            generation: 0,
+            startedAt: Date.now(),
+            durationMs: 0,
+        }, 'return-existing');
+        return this.snapshot(task);
+    }
+    registerPersistedNotification(agentId, notification) {
+        const task = this.tasks.get(agentId);
+        if (!task)
+            throw new Error(`No task found with ID: ${agentId}`);
+        if (task.notifications.some(({ id }) => id === notification.id))
+            return;
+        task.notifications.push(notification);
+    }
     has(agentId) {
         return this.tasks.has(this.resolveOptional(agentId) ?? agentId);
     }
+    notificationClaimAgentIds() {
+        return [...this.tasks.entries()]
+            .filter(([, task]) => task.status === 'running' || task.notifications.length > 0)
+            .map(([agentId]) => agentId);
+    }
     snapshotById(agentId) {
         const task = this.tasks.get(agentId);
         return task ? this.snapshot(task) : null;
@@ -254,32 +293,52 @@ export class BackgroundAgentManager {
         const task = this.tasks.get(agentId);
         if (!task)
             throw new Error(`No task found with ID: ${agentId}`);
-        if (task.status !== 'running' || !task.controller) {
-            throw new Error(`Task ${agentId} is not running (status: ${task.status})`);
-        }
-        task.status = 'stopped';
-        task.error = 'Stopped by TaskStop';
-        task.durationMs ??= Date.now() - task.startedAt;
-        task.queuedMessages.length = 0;
-        task.controller.abort();
+        this.stopTask(task, 'Stopped by TaskStop');
         return `Task ${agentId} stopped successfully`;
     }
-    async close() {
+    async stopAndWait(agentId, timeout = DEFAULT_CLOSE_DRAIN_MS) {
+        const message = this.stop(agentId);
+        const task = this.tasks.get(agentId);
+        if (task?.promise)
+            await waitBounded(task.promise, timeout);
+        return message;
+    }
+    stopAll() {
+        const stopped = [];
+        for (const task of this.tasks.values()) {
+            if (task.status !== 'running' || !task.controller)
+                continue;
+            this.stopTask(task, 'Stopped by explicit bulk kill');
+            stopped.push(task.spec.agentId);
+        }
+        return stopped;
+    }
+    async close(drainMilliseconds = DEFAULT_CLOSE_DRAIN_MS) {
         if (this.closed)
             return;
+        if (!Number.isFinite(drainMilliseconds) ||
+            drainMilliseconds < 0 ||
+            drainMilliseconds > MAX_TIMEOUT_MS) {
+            throw new Error(`close drain must be between 0 and ${MAX_TIMEOUT_MS} milliseconds`);
+        }
         this.closed = true;
+        this.resolveClosed();
         const running = [];
         for (const task of this.tasks.values()) {
-            if (task.status !== 'running' || !task.controller)
-                continue;
-            task.status = 'stopped';
-            task.error = 'Stopped because the background agent manager closed';
-            task.queuedMessages.length = 0;
-            task.controller.abort();
+            if (task.status === 'running' && task.controller) {
+                task.status = 'stopped';
+                task.error = 'Stopped because the background agent manager closed';
+                task.suppressNotifications = true;
+                task.notifications.length = 0;
+                task.queuedMessages.length = 0;
+                task.controller.abort(new BackgroundAgentShutdownError());
+            }
             if (task.promise)
                 running.push(task.promise);
         }
-        await Promise.allSettled(running);
+        await waitBounded(Promise.allSettled(running).then(() => undefined), drainMilliseconds);
+        this.tasks.clear();
+        this.names.clear();
     }
     send(agentId, message, summary, toolUseId) {
         if (message.trim().length === 0)
@@ -317,8 +376,9 @@ export class BackgroundAgentManager {
                 .filter((task) => task.status === 'running')
                 .map((task) => task.promise)
                 .filter((promise) => promise !== null);
-            if (running.length > 0)
-                await Promise.race(running);
+            if (running.length > 0) {
+                await Promise.race([Promise.race(running), this.closedSignal]);
+            }
         }
         const notifications = [];
         let usage = { inputTokens: 0, outputTokens: 0 };
@@ -352,16 +412,86 @@ export class BackgroundAgentManager {
         const modelUsage = modelUsageByModel.size === 0
             ? undefined
             : Object.fromEntries(modelUsageByModel);
+        if (options.consume !== false) {
+            for (const task of consumedTasks) {
+                if (!task.spec.acknowledgeNotification)
+                    continue;
+                for (const notification of task.notifications) {
+                    await task.spec.acknowledgeNotification(notification.id);
+                }
+            }
+        }
         const result = {
             messages: notifications,
             usage,
             ...(modelUsage === undefined ? {} : { modelUsage }),
             ...(durationSeen ? { durationApiMs, durationApiWithoutRetriesMs } : {}),
         };
-        for (const task of consumedTasks)
-            task.notifications.splice(0);
+        if (options.consume !== false) {
+            for (const task of consumedTasks)
+                task.notifications.splice(0);
+        }
         return result;
     }
+    async acknowledge(messages) {
+        await this.forEachMatchingNotification(messages, async (task, notification) => {
+            await task.spec.acknowledgeNotification?.(notification.id);
+            task.notifications.splice(task.notifications.indexOf(notification), 1);
+        });
+    }
+    async prepareNotificationsDetached(messages) {
+        await this.forEachMatchingNotification(messages, async (task, notification) => {
+            await task.spec.prepareNotificationDetached?.(notification.id, task.spec.resolvedModel);
+        });
+    }
+    async confirmNotificationsDetached(messages) {
+        await this.forEachMatchingNotification(messages, async (task, notification) => {
+            await task.spec.confirmNotificationDetached?.(notification.id);
+        });
+    }
+    async forEachMatchingNotification(messages, operation) {
+        const remaining = [...messages];
+        for (const task of this.tasks.values()) {
+            for (const notification of [...task.notifications]) {
+                const message = this.formatNotification(task, notification);
+                const index = remaining.indexOf(message);
+                if (index < 0)
+                    continue;
+                await operation(task, notification);
+                remaining.splice(index, 1);
+            }
+        }
+    }
+    async acknowledgeDelivered(delivered) {
+        for (const [agentId, task] of this.tasks) {
+            for (const notification of [...task.notifications]) {
+                if (notification.status === 'interrupted')
+                    continue;
+                const status = notification.status === 'stopped' ? 'killed' : notification.status;
+                if (!delivered({ agentId, toolUseId: notification.toolUseId, status })) {
+                    continue;
+                }
+                await task.spec.acknowledgeNotification?.(notification.id);
+                task.notifications.splice(task.notifications.indexOf(notification), 1);
+            }
+        }
+    }
+    async acknowledgeDeliveredAsDetached(delivered) {
+        for (const [agentId, task] of this.tasks) {
+            for (const notification of [...task.notifications]) {
+                if (notification.status === 'interrupted')
+                    continue;
+                const status = notification.status === 'stopped' ? 'killed' : notification.status;
+                if (!delivered({ agentId, toolUseId: notification.toolUseId, status })) {
+                    continue;
+                }
+                await task.spec.prepareNotificationDetached?.(notification.id, task.spec.resolvedModel);
+                await task.spec.confirmNotificationDetached?.(notification.id);
+                await task.spec.acknowledgeNotification?.(notification.id);
+                task.notifications.splice(task.notifications.indexOf(notification), 1);
+            }
+        }
+    }
     start(task, message, continuation, toolUseId) {
         task.generation += 1;
         const generation = task.generation;
@@ -372,8 +502,10 @@ export class BackgroundAgentManager {
         task.controller = controller;
         task.result = null;
         task.error = null;
-        task.promise = task.spec
-            .run(message, controller.signal, continuation)
+        this.track(task, task.spec.run(message, controller.signal, continuation, toolUseId), generation, toolUseId);
+    }
+    track(task, operation, generation, toolUseId) {
+        task.promise = operation
             .then((result) => {
             if (task.generation !== generation)
                 return;
@@ -386,6 +518,7 @@ export class BackgroundAgentManager {
             task.durationMs = result.durationMs;
             task.error = null;
             task.notifications.push({
+                id: result.notificationId ?? randomUUID(),
                 status: 'completed',
                 result,
                 error: null,
@@ -406,8 +539,9 @@ export class BackgroundAgentManager {
                 failedResult?.durationMs ?? Date.now() - task.startedAt;
             task.error = error instanceof Error ? error.message : String(error);
             task.notifications.push({
+                id: failedResult?.notificationId ?? randomUUID(),
                 status: 'failed',
-                result: null,
+                result: failedResult ?? null,
                 error: task.error,
                 toolUseId,
             });
@@ -423,11 +557,50 @@ export class BackgroundAgentManager {
             }
         });
     }
+    registerTask(spec, state, duplicate) {
+        if (this.closed)
+            throw new Error('Background agent manager is closed');
+        assertAgentId(spec.agentId);
+        if (spec.name !== undefined &&
+            !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/u.test(spec.name)) {
+            throw new Error(`Invalid background agent name: ${spec.name}`);
+        }
+        const existing = this.tasks.get(spec.agentId);
+        if (existing) {
+            if (duplicate === 'throw') {
+                throw new Error(`Background agent ${spec.agentId} already exists`);
+            }
+            return { task: existing, created: false };
+        }
+        this.assertNameAvailable(spec.name, spec.agentId);
+        if (spec.name !== undefined)
+            this.names.set(spec.name, spec.agentId);
+        const task = {
+            spec,
+            ...state,
+            promise: null,
+            notifications: [],
+            queuedMessages: [],
+            suppressNotifications: false,
+        };
+        this.tasks.set(spec.agentId, task);
+        return { task, created: true };
+    }
     resolveOptional(identifier) {
-        if (AGENT_ID_PATTERN.test(identifier))
+        if (isClaudeAgentId(identifier))
             return identifier;
         return this.names.get(identifier);
     }
+    stopTask(task, reason) {
+        if (task.status !== 'running' || !task.controller) {
+            throw new Error(`Task ${task.spec.agentId} is not running (status: ${task.status})`);
+        }
+        task.status = 'stopped';
+        task.error = reason;
+        task.durationMs ??= Date.now() - task.startedAt;
+        task.queuedMessages.length = 0;
+        task.controller.abort();
+    }
     assertNameAvailable(name, agentId) {
         if (name === undefined)
             return;
@@ -445,16 +618,19 @@ export class BackgroundAgentManager {
         };
         task.result = stoppedResult;
         task.durationMs ??= stoppedResult.durationMs || Date.now() - task.startedAt;
-        task.notifications.push({
-            status: 'stopped',
-            result: stoppedResult,
-            error: task.error,
-            toolUseId: task.spec.toolUseId,
-        });
+        if (!task.suppressNotifications) {
+            task.notifications.push({
+                id: stoppedResult.notificationId ?? randomUUID(),
+                status: 'stopped',
+                result: stoppedResult,
+                error: task.error,
+                toolUseId: task.spec.toolUseId,
+            });
+        }
     }
     resolveRequired(identifier) {
         const resolved = this.resolveOptional(identifier);
-        if (!AGENT_ID_PATTERN.test(identifier) &&
+        if (!isClaudeAgentId(identifier) &&
             !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/u.test(identifier)) {
             assertAgentId(identifier);
         }

package/dist/application/background-task-runtime.d.ts

@@ -12,7 +12,14 @@ export interface BackgroundBashTaskSource {
 }
 export interface BackgroundAgentTaskSource {
     backgroundSnapshots(): readonly BackgroundAgentSnapshot[];
-    stopBackgroundTask(taskId: string): string;
+    outputBackgroundTask(taskId: string, options: {
+        block: boolean;
+        timeout: number;
+    }): Promise<string>;
+    stopBackgroundTask(taskId: string): Promise<string>;
+    sendBackgroundMessage(agentId: string, message: string, summary: string | undefined, toolUseId: string): string;
+    hasForegroundTask(): boolean;
+    backgroundForegroundTask(): BackgroundAgentSnapshot;
 }
 export interface WorkflowTaskSource {
     list(sessionId?: string): readonly WorkflowTaskSnapshot[];
@@ -29,6 +36,18 @@ export declare class BackgroundTaskRuntime {
     registerAgents(sessionId: string, source: BackgroundAgentTaskSource): void;
     snapshot(sessionId: string): Promise<BackgroundTaskSnapshot>;
     stop(sessionId: string, taskId: string): Promise<void>;
+    outputAgent(sessionId: string, agentId: string, options: {
+        block: boolean;
+        timeout: number;
+    }): Promise<string | null>;
+    stopAgent(sessionId: string, agentId: string): Promise<string | null>;
+    sendAgent(sessionId: string, agentId: string, message: string, summary: string | undefined, toolUseId: string): string | null;
+    sendAgentWithOwner(sessionId: string, agentId: string, message: string, summary: string | undefined, toolUseId: string): {
+        content: string;
+        owner: BackgroundAgentTaskSource;
+    } | null;
+    backgroundForeground(sessionId: string): BackgroundAgentSnapshot;
     clear(): void;
+    private agentSource;
 }
 //# sourceMappingURL=background-task-runtime.d.ts.map

package/dist/application/background-task-runtime.js

@@ -38,22 +38,61 @@ export class BackgroundTaskRuntime {
             await source.stopBackgroundTask(taskId);
             return;
         }
-        for (const source of this.agentSources.get(sessionId) ?? []) {
-            if (!source.backgroundSnapshots().some(({ agentId }) => agentId === taskId)) {
-                continue;
-            }
-            source.stopBackgroundTask(taskId);
+        if ((await this.stopAgent(sessionId, taskId)) !== null)
             return;
-        }
         if (this.workflows?.hasForSession(sessionId, taskId)) {
             await this.workflows.stopAndWait(taskId);
             return;
         }
         throw new Error(`No task found with ID: ${taskId}`);
     }
+    async outputAgent(sessionId, agentId, options) {
+        const source = this.agentSource(sessionId, agentId);
+        return source ? source.outputBackgroundTask(agentId, options) : null;
+    }
+    async stopAgent(sessionId, agentId) {
+        const source = this.agentSource(sessionId, agentId);
+        return source ? source.stopBackgroundTask(agentId) : null;
+    }
+    sendAgent(sessionId, agentId, message, summary, toolUseId) {
+        return (this.sendAgentWithOwner(sessionId, agentId, message, summary, toolUseId)
+            ?.content ?? null);
+    }
+    sendAgentWithOwner(sessionId, agentId, message, summary, toolUseId) {
+        const source = this.agentSource(sessionId, agentId);
+        return source
+            ? {
+                content: source.sendBackgroundMessage(agentId, message, summary, toolUseId),
+                owner: source,
+            }
+            : null;
+    }
+    backgroundForeground(sessionId) {
+        const sources = [...(this.agentSources.get(sessionId) ?? [])].reverse();
+        const source = sources.find((candidate) => candidate.hasForegroundTask());
+        if (!source)
+            throw new Error('No foreground agent is running');
+        return source.backgroundForegroundTask();
+    }
     clear() {
         this.bashSources.clear();
         this.agentSources.clear();
     }
+    agentSource(sessionId, identifier) {
+        const sources = [...(this.agentSources.get(sessionId) ?? [])];
+        const idMatches = sources.filter((source) => source
+            .backgroundSnapshots()
+            .some(({ agentId }) => agentId === identifier));
+        if (idMatches.length > 1) {
+            throw new Error(`Multiple background agent owners claim ID: ${identifier}`);
+        }
+        if (idMatches[0])
+            return idMatches[0];
+        const nameMatches = sources.filter((source) => source.backgroundSnapshots().some(({ name }) => name === identifier));
+        if (nameMatches.length > 1) {
+            throw new Error(`Multiple live background agents are named '${identifier}'`);
+        }
+        return nameMatches[0] ?? null;
+    }
 }
 //# sourceMappingURL=background-task-runtime.js.map

package/dist/application/managed-worktree.d.ts

@@ -12,4 +12,12 @@ export declare function createManagedWorktree(options: {
     directoryName: string;
     label: 'Agent' | 'Workflow';
 }): Promise<ManagedWorktree>;
+/** Reattaches only to a real, registered Git worktree. Persisted metadata is
+ * untrusted input, so an arbitrary directory can never become an execution
+ * cwd merely because it exists. Restored worktrees are retained for audit. */
+export declare function restoreManagedWorktree(options: {
+    cwd: string;
+    path: string;
+    label: 'Agent' | 'Workflow';
+}): Promise<ManagedWorktree>;
 //# sourceMappingURL=managed-worktree.d.ts.map