@myagentroam/agent 0.10.61 → 0.10.62

package/dist/agent-core/sdk/extension-agents.js

@@ -28,11 +28,7 @@ export function createExtensionAgentsBackend(input) {
                     throw new MarAgentError(created.errorCode ?? 'MAR_AGENT_SUBAGENT_FAILED', created.errorMessage ?? 'Agent could not start.');
             }
         })),
-        list: (call) => withController(call, async (controller) => {
-            await controller.prepareAll(call.signal);
-            call.signal.throwIfAborted();
-            return controller.inspectAll();
-        }),
+        list: (call) => withController(call, (controller) => controller.list(call.signal)),
         inspect: (target, call) => withController(call, (controller) => controller.inspect(target.agentId)),
         wait: (target, call) => withController(call, (controller) => {
             const selection = parseAgentWaitTargets(target);

package/dist/agent-core/sdk/session.js

@@ -282,6 +282,7 @@ export function createSessionOpener(services) {
             let releaseSession;
             let exhaustedModelAttempt;
             // Serialize durable events before either the local stream or Host observes them.
+            let persistedTerminal = false;
             const emit = (event, assertLive) => {
                 assertLive?.();
                 const full = {
@@ -303,6 +304,10 @@ export function createSessionOpener(services) {
                             executionId,
                             turnId
                         });
+                        if (full.type === 'execution.completed' ||
+                            full.type === 'execution.failed' ||
+                            full.type === 'execution.cancelled')
+                            persistedTerminal = true;
                         if (full.type === 'message.completed') {
                             const message = liveModelMessages.findLast((item) => item.role === 'assistant' && item.content === full.text);
                             if (message)
@@ -1953,6 +1958,9 @@ export function createSessionOpener(services) {
                 executionResults.delete(executionKey);
             });
             return {
+                get persistedEvents() {
+                    return persistedTerminal;
+                },
                 executionId,
                 turnId,
                 [Symbol.asyncIterator]: () => queue[Symbol.asyncIterator](),

package/dist/agent-core/subagent/session-controller.d.ts

@@ -16,6 +16,8 @@ export interface SubagentModelOption {
 export interface SubagentTurnHandle extends AsyncIterable<MarAgentEvent> {
     readonly executionId: string;
     readonly turnId: string;
+    /** True only after the child terminal event was durably appended. */
+    readonly persistedEvents?: boolean;
     result(): Promise<ExecutionResult>;
     cancel(): void;
     enqueueMessage(message: string, delivery?: SubagentMessageDelivery): boolean;
@@ -109,6 +111,7 @@ export declare class SubagentSessionController implements SubagentController {
     withOperation<T>(operation: SubagentParentOperation, run: () => T): T;
     inspect(agentId: string): Promise<SubagentTaskSnapshot>;
     inspectAll(): readonly SubagentTaskSnapshot[];
+    list(signal?: AbortSignal): Promise<readonly SubagentTaskSnapshot[]>;
     /** Full listing is explicit; ordinary opens and executions never require it. */
     prepareAll(signal?: AbortSignal): Promise<void>;
     prepareSessionResources(signal?: AbortSignal): Promise<void>;

package/dist/agent-core/subagent/session-controller.js

@@ -5,6 +5,16 @@ import { MarAgentError, describeMarAgentError } from '../error.js';
 import { TOOL_EXECUTION_LIMITS } from '../tools/execution-limits.js';
 import { parseAgentWaitTargets, waitForAgentCondition } from './wait.js';
 const RECENT_TERMINAL_RESOURCE_LIMIT = 16;
+const DETAIL_FIELDS = [
+    'latestMessage',
+    'latestActivity',
+    'summary',
+    'changedFiles',
+    'verification',
+    'evidence',
+    'permissionStop',
+    'errorMessage'
+];
 export class SubagentSessionController {
     parentSessionId;
     rootSessionId;
@@ -14,6 +24,8 @@ export class SubagentSessionController {
     // Discovery order is independent of the order in which history is requested.
     #discovered = new Map();
     #loading = new Map();
+    #readers = new Map();
+    #allReaders = 0;
     #queue = [];
     #completionWaiters = new Set();
     #activityWaiters = new Set();
@@ -63,6 +75,7 @@ export class SubagentSessionController {
         this.#creationBudget = { count: 0 };
         for (const state of this.#agents.values())
             await this.#publishTerminal(state);
+        this.#releaseOldDetails();
     }
     /** A retained cell must not borrow a later model Execution's identity or task budget. */
     captureExecution(executionId) {
@@ -98,13 +111,21 @@ export class SubagentSessionController {
         return this.#retainedExecution.run({ execution: operation, budget: { count: 0 }, native: true }, run);
     }
     async inspect(agentId) {
-        return this.#snapshot(await this.#find(agentId), { full: true });
+        return this.#using([agentId], async () => {
+            return this.#snapshot(await this.#find(agentId), { full: true });
+        });
     }
     inspectAll() {
         if (this.#disposed)
             throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
         return this.#orderedStates().map((state) => this.#snapshot(state, { full: true }));
     }
+    async list(signal) {
+        return this.#using(undefined, async () => {
+            await this.prepareAll(signal);
+            return this.inspectAll();
+        });
+    }
     /** Full listing is explicit; ordinary opens and executions never require it. */
     async prepareAll(signal) {
         for (const id of this.#discovered.keys()) {
@@ -129,6 +150,7 @@ export class SubagentSessionController {
                 break;
         }
         signal?.throwIfAborted();
+        this.#releaseOldDetails();
     }
     async #restoreDiscovered(agentId) {
         try {
@@ -250,183 +272,125 @@ export class SubagentSessionController {
         catch (error) {
             await this.#deleteUnstartedSession(created.id, error);
         }
-        const state = {
-            agentId: created.id,
-            description: source.description,
-            role: input.role,
-            ...(source.ownerInstanceId === undefined ? {} : { ownerInstanceId: source.ownerInstanceId }),
-            ...(source.extensionId === undefined ? {} : { extensionId: source.extensionId }),
-            status: 'queued',
-            messageRevision: 0,
-            observedMessageRevision: 0,
-            latestMessageActivityRevision: 0,
-            changedFiles: [],
-            verification: [],
-            evidence: [],
-            terminalPending: false,
-            observedTerminalRevision: -1,
-            resourceRevision: ++this.#resourceRevision
-        };
-        if (!native)
-            (this.#retainedExecution.getStore()?.budget ?? this.#creationBudget).count++;
-        this.#agents.set(state.agentId, state);
-        this.#discovered.set(state.agentId, state.resourceRevision);
-        const knownModel = execution.models.get(input.modelId ?? execution.modelId);
-        if (knownModel) {
-            state.modelId = knownModel.id;
-            state.modelName = knownModel.name;
-        }
-        try {
-            const selected = resolveModel(execution, input);
-            state.modelId = selected.id;
-            state.modelName = selected.name;
-            state.reasoningEffort = selected.reasoningEffort;
-        }
-        catch (error) {
-            this.#setFailure(state, error);
-        }
-        try {
-            await options.onCreated?.(this.#receiptSnapshot(state));
-            if (this.#disposed)
-                throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
-            this.#requireExecution();
-            options.signal?.throwIfAborted();
-        }
-        catch (error) {
-            await this.#deleteUnstartedSession(state.agentId, error);
-        }
-        if (state.status === 'failed') {
-            await this.#publishTerminal(state);
-            this.#observeTerminal(state);
-            return this.#snapshot(state);
-        }
-        this.#queueTurn(state, input.prompt, execution, [], undefined, undefined, options.signal, options.turnSignal);
-        if (options.waitFor === 'start' || (options.waitFor === undefined && input.background))
-            return this.#receiptSnapshot(state);
-        await waitForPromise(state.turn.completion, options.signal);
-        const includeLatestMessage = this.#hasUnreadMessage(state);
-        const includeTerminalDetails = this.#observeTerminal(state);
-        this.#observeLatestMessage(state);
-        return this.#snapshot(state, { includeLatestMessage, includeTerminalDetails });
-    }
-    async output(agentId, options = {}) {
-        options.signal?.throwIfAborted();
-        const state = await this.#find(agentId);
-        options.signal?.throwIfAborted();
-        validateOutputOptions(options, this.#retainedExecution.getStore()?.native === true);
-        if (options.untilSettled) {
-            if (state.turn)
-                await waitForPromise(state.turn.completion, options.signal);
-            options.signal?.throwIfAborted();
-            const includeLatestMessage = this.#hasUnreadMessage(state);
-            const includeTerminalDetails = this.#observeTerminal(state);
-            this.#observeLatestMessage(state);
-            return {
-                ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
-                waitOutcome: 'completion'
+        return this.#using([created.id], async () => {
+            const state = {
+                agentId: created.id,
+                description: source.description,
+                role: input.role,
+                ...(source.ownerInstanceId === undefined
+                    ? {}
+                    : { ownerInstanceId: source.ownerInstanceId }),
+                ...(source.extensionId === undefined ? {} : { extensionId: source.extensionId }),
+                status: 'queued',
+                messageRevision: 0,
+                observedMessageRevision: 0,
+                latestMessageActivityRevision: 0,
+                changedFiles: [],
+                verification: [],
+                evidence: [],
+                terminalPending: false,
+                observedTerminalRevision: -1,
+                resourceRevision: ++this.#resourceRevision
             };
-        }
-        if (options.waitMs === undefined || options.waitMs === 0)
-            return {
-                ...this.#snapshot(state, {
-                    includeLatestMessage: false,
-                    includeTerminalDetails: false
-                }),
-                waitOutcome: 'snapshot'
-            };
-        if (isTerminalState(state)) {
+            if (!native)
+                (this.#retainedExecution.getStore()?.budget ?? this.#creationBudget).count++;
+            this.#agents.set(state.agentId, state);
+            this.#discovered.set(state.agentId, state.resourceRevision);
+            const knownModel = execution.models.get(input.modelId ?? execution.modelId);
+            if (knownModel) {
+                state.modelId = knownModel.id;
+                state.modelName = knownModel.name;
+            }
+            try {
+                const selected = resolveModel(execution, input);
+                state.modelId = selected.id;
+                state.modelName = selected.name;
+                state.reasoningEffort = selected.reasoningEffort;
+            }
+            catch (error) {
+                this.#setFailure(state, error);
+            }
+            try {
+                await options.onCreated?.(this.#receiptSnapshot(state));
+                if (this.#disposed)
+                    throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
+                this.#requireExecution();
+                options.signal?.throwIfAborted();
+            }
+            catch (error) {
+                await this.#deleteUnstartedSession(state.agentId, error);
+            }
+            if (state.status === 'failed') {
+                await this.#publishTerminal(state);
+                this.#observeTerminal(state);
+                return this.#snapshot(state);
+            }
+            this.#queueTurn(state, input.prompt, execution, [], undefined, undefined, options.signal, options.turnSignal);
+            if (options.waitFor === 'start' || (options.waitFor === undefined && input.background))
+                return this.#receiptSnapshot(state);
+            await waitForPromise(state.turn.completion, options.signal);
             const includeLatestMessage = this.#hasUnreadMessage(state);
             const includeTerminalDetails = this.#observeTerminal(state);
             this.#observeLatestMessage(state);
-            return {
-                ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
-                waitOutcome: 'completion'
-            };
-        }
-        const waitFor = options.waitFor ?? 'completion';
-        if (waitFor === 'message' && this.#hasUnreadMessage(state)) {
-            this.#observeLatestMessage(state);
-            return { ...this.#snapshot(state), waitOutcome: 'message' };
-        }
-        const waitMs = this.#retainedExecution.getStore()?.native
-            ? options.waitMs
-            : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
-        if (waitFor === 'completion') {
-            const completed = await this.#waitForCompletion(state, waitMs, options.signal, options.waitInterrupt);
-            options.signal?.throwIfAborted();
-            const includeLatestMessage = this.#hasUnreadMessage(state);
-            const includeTerminalDetails = completed ? this.#observeTerminal(state) : false;
-            if (includeLatestMessage)
-                this.#observeLatestMessage(state);
-            return {
-                ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
-                ...waitMetadata(completed ? 'completion' : options.waitInterrupt?.pending() ? 'interrupted' : 'timeout')
-            };
-        }
-        const activity = await this.#waitForMessageOrCompletion([state], waitMs, options.signal, options.waitInterrupt);
-        options.signal?.throwIfAborted();
-        const includeLatestMessage = activity?.kind === 'message' ||
-            (activity?.kind === 'completion' && this.#hasUnreadMessage(activity.state));
-        const includeTerminalDetails = activity?.kind === 'completion' ? this.#observeTerminal(activity.state) : false;
-        if (activity)
-            this.#observeLatestMessage(activity.state);
-        return {
-            ...this.#snapshot(activity?.state ?? state, {
-                includeLatestMessage,
-                includeTerminalDetails
-            }),
-            ...waitMetadata(activity?.kind ?? (options.waitInterrupt?.pending() ? 'interrupted' : 'timeout'))
-        };
+            return this.#snapshot(state, { includeLatestMessage, includeTerminalDetails });
+        });
     }
-    async outputAny(options = {}) {
-        options.signal?.throwIfAborted();
-        if (options.untilSettled)
-            throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'An unbounded wait requires an agent id.');
-        validateOutputOptions(options, this.#retainedExecution.getStore()?.native === true);
-        const hasLive = [...this.#agents.values()].some((state) => !isTerminalState(state));
-        if (!hasLive) {
-            for (const id of [...this.#discovered.keys()].reverse()) {
+    async output(agentId, options = {}) {
+        return this.#using([agentId], async () => {
+            options.signal?.throwIfAborted();
+            const state = await this.#find(agentId);
+            options.signal?.throwIfAborted();
+            validateOutputOptions(options, this.#retainedExecution.getStore()?.native === true);
+            if (options.untilSettled) {
+                if (state.turn)
+                    await waitForPromise(state.turn.completion, options.signal);
                 options.signal?.throwIfAborted();
-                if (await this.#restoreDiscovered(id))
-                    break;
+                const includeLatestMessage = this.#hasUnreadMessage(state);
+                const includeTerminalDetails = this.#observeTerminal(state);
+                this.#observeLatestMessage(state);
+                return {
+                    ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
+                    waitOutcome: 'completion'
+                };
             }
-        }
-        options.signal?.throwIfAborted();
-        const states = this.#orderedStates();
-        if (states.length === 0)
-            throw new MarAgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Subagent was not found.');
-        const live = states.filter((state) => state.status === 'queued' || state.status === 'running');
-        if (options.waitMs === undefined || options.waitMs === 0)
-            return {
-                ...this.#snapshot(live.at(-1) ?? states.at(-1), {
-                    includeLatestMessage: false,
-                    includeTerminalDetails: false
-                }),
-                waitOutcome: 'snapshot'
-            };
-        if (live.length === 0) {
-            const state = states.at(-1);
-            const includeLatestMessage = this.#hasUnreadMessage(state);
-            const includeTerminalDetails = this.#observeTerminal(state);
-            this.#observeLatestMessage(state);
-            return {
-                ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
-                waitOutcome: 'completion'
-            };
-        }
-        const waitFor = options.waitFor ?? 'completion';
-        if (waitFor === 'message') {
-            const pending = this.#oldestUnreadMessage(live);
-            if (pending) {
-                this.#observeLatestMessage(pending);
-                return { ...this.#snapshot(pending), waitOutcome: 'message' };
+            if (options.waitMs === undefined || options.waitMs === 0)
+                return {
+                    ...this.#snapshot(state, {
+                        includeLatestMessage: false,
+                        includeTerminalDetails: false
+                    }),
+                    waitOutcome: 'snapshot'
+                };
+            if (isTerminalState(state)) {
+                const includeLatestMessage = this.#hasUnreadMessage(state);
+                const includeTerminalDetails = this.#observeTerminal(state);
+                this.#observeLatestMessage(state);
+                return {
+                    ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
+                    waitOutcome: 'completion'
+                };
             }
-        }
-        const waitMs = this.#retainedExecution.getStore()?.native
-            ? options.waitMs
-            : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
-        if (waitFor === 'message') {
-            const activity = await this.#waitForMessageOrCompletion(live, waitMs, options.signal, options.waitInterrupt);
+            const waitFor = options.waitFor ?? 'completion';
+            if (waitFor === 'message' && this.#hasUnreadMessage(state)) {
+                this.#observeLatestMessage(state);
+                return { ...this.#snapshot(state), waitOutcome: 'message' };
+            }
+            const waitMs = this.#retainedExecution.getStore()?.native
+                ? options.waitMs
+                : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
+            if (waitFor === 'completion') {
+                const completed = await this.#waitForCompletion(state, waitMs, options.signal, options.waitInterrupt);
+                options.signal?.throwIfAborted();
+                const includeLatestMessage = this.#hasUnreadMessage(state);
+                const includeTerminalDetails = completed ? this.#observeTerminal(state) : false;
+                if (includeLatestMessage)
+                    this.#observeLatestMessage(state);
+                return {
+                    ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
+                    ...waitMetadata(completed ? 'completion' : options.waitInterrupt?.pending() ? 'interrupted' : 'timeout')
+                };
+            }
+            const activity = await this.#waitForMessageOrCompletion([state], waitMs, options.signal, options.waitInterrupt);
             options.signal?.throwIfAborted();
             const includeLatestMessage = activity?.kind === 'message' ||
                 (activity?.kind === 'completion' && this.#hasUnreadMessage(activity.state));
@@ -434,27 +398,93 @@ export class SubagentSessionController {
             if (activity)
                 this.#observeLatestMessage(activity.state);
             return {
-                ...this.#snapshot(activity?.state ?? live.at(-1), {
+                ...this.#snapshot(activity?.state ?? state, {
                     includeLatestMessage,
                     includeTerminalDetails
                 }),
                 ...waitMetadata(activity?.kind ?? (options.waitInterrupt?.pending() ? 'interrupted' : 'timeout'))
             };
-        }
-        const completed = await this.#waitForAnyCompletion(live, waitMs, options.signal, options.waitInterrupt);
-        options.signal?.throwIfAborted();
-        const state = completed ?? this.#oldestUnreadMessage(live) ?? live.at(-1);
-        const includeLatestMessage = this.#hasUnreadMessage(state);
-        const includeTerminalDetails = completed ? this.#observeTerminal(state) : false;
-        if (includeLatestMessage)
-            this.#observeLatestMessage(state);
-        return {
-            ...this.#snapshot(state, {
-                includeLatestMessage,
-                includeTerminalDetails
-            }),
-            ...waitMetadata(completed ? 'completion' : options.waitInterrupt?.pending() ? 'interrupted' : 'timeout')
-        };
+        });
+    }
+    async outputAny(options = {}) {
+        return this.#using(undefined, async () => {
+            options.signal?.throwIfAborted();
+            if (options.untilSettled)
+                throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'An unbounded wait requires an agent id.');
+            validateOutputOptions(options, this.#retainedExecution.getStore()?.native === true);
+            const hasLive = [...this.#agents.values()].some((state) => !isTerminalState(state));
+            if (!hasLive) {
+                for (const id of [...this.#discovered.keys()].reverse()) {
+                    options.signal?.throwIfAborted();
+                    if (await this.#restoreDiscovered(id))
+                        break;
+                }
+            }
+            options.signal?.throwIfAborted();
+            const states = this.#orderedStates();
+            if (states.length === 0)
+                throw new MarAgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Subagent was not found.');
+            const live = states.filter((state) => state.status === 'queued' || state.status === 'running');
+            if (options.waitMs === undefined || options.waitMs === 0)
+                return {
+                    ...this.#snapshot(live.at(-1) ?? states.at(-1), {
+                        includeLatestMessage: false,
+                        includeTerminalDetails: false
+                    }),
+                    waitOutcome: 'snapshot'
+                };
+            if (live.length === 0) {
+                const state = states.at(-1);
+                const includeLatestMessage = this.#hasUnreadMessage(state);
+                const includeTerminalDetails = this.#observeTerminal(state);
+                this.#observeLatestMessage(state);
+                return {
+                    ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
+                    waitOutcome: 'completion'
+                };
+            }
+            const waitFor = options.waitFor ?? 'completion';
+            if (waitFor === 'message') {
+                const pending = this.#oldestUnreadMessage(live);
+                if (pending) {
+                    this.#observeLatestMessage(pending);
+                    return { ...this.#snapshot(pending), waitOutcome: 'message' };
+                }
+            }
+            const waitMs = this.#retainedExecution.getStore()?.native
+                ? options.waitMs
+                : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
+            if (waitFor === 'message') {
+                const activity = await this.#waitForMessageOrCompletion(live, waitMs, options.signal, options.waitInterrupt);
+                options.signal?.throwIfAborted();
+                const includeLatestMessage = activity?.kind === 'message' ||
+                    (activity?.kind === 'completion' && this.#hasUnreadMessage(activity.state));
+                const includeTerminalDetails = activity?.kind === 'completion' ? this.#observeTerminal(activity.state) : false;
+                if (activity)
+                    this.#observeLatestMessage(activity.state);
+                return {
+                    ...this.#snapshot(activity?.state ?? live.at(-1), {
+                        includeLatestMessage,
+                        includeTerminalDetails
+                    }),
+                    ...waitMetadata(activity?.kind ?? (options.waitInterrupt?.pending() ? 'interrupted' : 'timeout'))
+                };
+            }
+            const completed = await this.#waitForAnyCompletion(live, waitMs, options.signal, options.waitInterrupt);
+            options.signal?.throwIfAborted();
+            const state = completed ?? this.#oldestUnreadMessage(live) ?? live.at(-1);
+            const includeLatestMessage = this.#hasUnreadMessage(state);
+            const includeTerminalDetails = completed ? this.#observeTerminal(state) : false;
+            if (includeLatestMessage)
+                this.#observeLatestMessage(state);
+            return {
+                ...this.#snapshot(state, {
+                    includeLatestMessage,
+                    includeTerminalDetails
+                }),
+                ...waitMetadata(completed ? 'completion' : options.waitInterrupt?.pending() ? 'interrupted' : 'timeout')
+            };
+        });
     }
     async outputMany(agentIds, options = {}) {
         options.signal?.throwIfAborted();
@@ -464,187 +494,198 @@ export class SubagentSessionController {
         validateOutputOptions(options, this.#retainedExecution.getStore()?.native === true);
         if (!ids || 'untilSettled' in options)
             throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Group waits require a bounded deadline.');
-        const states = await Promise.all(ids.map((id) => this.#find(id)));
-        options.signal?.throwIfAborted();
-        const waitFor = options.waitFor ?? 'completion';
-        const targets = states.map((state) => ({
-            state,
-            turn: state.turn,
-            view: copyWaitState(state),
-            observation: this.#nativeObservation(state)
-        }));
-        const refresh = () => {
-            for (const target of targets) {
-                if (!isTerminalState(target.view) &&
-                    (target.state.turn === target.turn ||
-                        (target.state.turn === undefined && isTerminalState(target.state))))
-                    target.view = copyWaitState(target.state);
+        return this.#using(ids, async () => {
+            const states = await Promise.all(ids.map((id) => this.#find(id)));
+            options.signal?.throwIfAborted();
+            const waitFor = options.waitFor ?? 'completion';
+            const targets = states.map((state) => ({
+                state,
+                turn: state.turn,
+                view: copyWaitState(state),
+                observation: this.#nativeObservation(state)
+            }));
+            const refresh = () => {
+                for (const target of targets) {
+                    if (!isTerminalState(target.view) &&
+                        (target.state.turn === target.turn ||
+                            (target.state.turn === undefined && isTerminalState(target.state))))
+                        target.view = copyWaitState(target.state);
+                }
+            };
+            const unread = (target) => target.view.messageRevision >
+                (target.observation?.messageRevision ?? target.state.observedMessageRevision);
+            const ready = (target) => isTerminalState(target.view) || (waitFor === 'message' && unread(target));
+            const snapshot = options.waitMs === undefined || options.waitMs === 0;
+            let satisfied = false;
+            if (!snapshot) {
+                const waitMs = this.#retainedExecution.getStore()?.native
+                    ? options.waitMs
+                    : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
+                satisfied = await waitForAgentCondition({
+                    waitMs,
+                    signal: options.signal,
+                    interrupt: options.waitInterrupt,
+                    ready: () => {
+                        refresh();
+                        return mode === 'all' ? targets.every(ready) : targets.some(ready);
+                    },
+                    subscribe: (notify) => {
+                        const listener = () => notify();
+                        this.#activityWaiters.add(listener);
+                        return () => this.#activityWaiters.delete(listener);
+                    }
+                });
+                options.signal?.throwIfAborted();
             }
-        };
-        const unread = (target) => target.view.messageRevision >
-            (target.observation?.messageRevision ?? target.state.observedMessageRevision);
-        const ready = (target) => isTerminalState(target.view) || (waitFor === 'message' && unread(target));
-        const snapshot = options.waitMs === undefined || options.waitMs === 0;
-        let satisfied = false;
-        if (!snapshot) {
-            const waitMs = this.#retainedExecution.getStore()?.native
-                ? options.waitMs
-                : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
-            satisfied = await waitForAgentCondition({
-                waitMs,
-                signal: options.signal,
-                interrupt: options.waitInterrupt,
-                ready: () => {
-                    refresh();
-                    return mode === 'all' ? targets.every(ready) : targets.some(ready);
-                },
-                subscribe: (notify) => {
-                    const listener = () => notify();
-                    this.#activityWaiters.add(listener);
-                    return () => this.#activityWaiters.delete(listener);
+            refresh();
+            if (!snapshot)
+                satisfied = mode === 'all' ? targets.every(ready) : targets.some(ready);
+            const pendingAgentIds = targets
+                .filter((target) => !ready(target))
+                .map((target) => target.state.agentId);
+            const agents = targets.map((target) => {
+                const { state, view, observation } = target;
+                const terminal = isTerminalState(view);
+                const outcome = snapshot
+                    ? 'snapshot'
+                    : terminal
+                        ? 'completion'
+                        : ready(target)
+                            ? 'message'
+                            : satisfied
+                                ? 'snapshot'
+                                : options.waitInterrupt?.pending()
+                                    ? 'interrupted'
+                                    : 'timeout';
+                const includeLatestMessage = outcome !== 'snapshot' && unread(target);
+                const includeTerminalDetails = outcome === 'completion' &&
+                    (observation
+                        ? observation.terminalRevision < view.resourceRevision
+                        : state.observedTerminalRevision < view.resourceRevision);
+                const result = {
+                    ...this.#snapshot(view, { includeLatestMessage, includeTerminalDetails }),
+                    ...(target.turn === undefined ? {} : { turnId: target.turn.turnId }),
+                    ...waitMetadata(outcome)
+                };
+                if (includeLatestMessage) {
+                    if (observation)
+                        observation.messageRevision = Math.max(observation.messageRevision, view.messageRevision);
+                    else
+                        state.observedMessageRevision = Math.max(state.observedMessageRevision, view.messageRevision);
+                }
+                if (includeTerminalDetails) {
+                    if (observation)
+                        observation.terminalRevision = Math.max(observation.terminalRevision, view.resourceRevision);
+                    else
+                        state.observedTerminalRevision = Math.max(state.observedTerminalRevision, view.resourceRevision);
                 }
+                return result;
             });
-            options.signal?.throwIfAborted();
-        }
-        refresh();
-        if (!snapshot)
-            satisfied = mode === 'all' ? targets.every(ready) : targets.some(ready);
-        const pendingAgentIds = targets
-            .filter((target) => !ready(target))
-            .map((target) => target.state.agentId);
-        const agents = targets.map((target) => {
-            const { state, view, observation } = target;
-            const terminal = isTerminalState(view);
-            const outcome = snapshot
-                ? 'snapshot'
-                : terminal
-                    ? 'completion'
-                    : ready(target)
-                        ? 'message'
-                        : satisfied
-                            ? 'snapshot'
-                            : options.waitInterrupt?.pending()
-                                ? 'interrupted'
-                                : 'timeout';
-            const includeLatestMessage = outcome !== 'snapshot' && unread(target);
-            const includeTerminalDetails = outcome === 'completion' &&
-                (observation
-                    ? observation.terminalRevision < view.resourceRevision
-                    : state.observedTerminalRevision < view.resourceRevision);
-            const result = {
-                ...this.#snapshot(view, { includeLatestMessage, includeTerminalDetails }),
-                ...(target.turn === undefined ? {} : { turnId: target.turn.turnId }),
-                ...waitMetadata(outcome)
+            return {
+                mode,
+                waitFor,
+                agents,
+                pendingAgentIds,
+                ...waitMetadata(snapshot
+                    ? 'snapshot'
+                    : !satisfied
+                        ? options.waitInterrupt?.pending()
+                            ? 'interrupted'
+                            : 'timeout'
+                        : agents.some((agent) => agent.waitOutcome === 'message')
+                            ? 'message'
+                            : 'completion')
             };
-            if (includeLatestMessage) {
-                if (observation)
-                    observation.messageRevision = Math.max(observation.messageRevision, view.messageRevision);
-                else
-                    state.observedMessageRevision = Math.max(state.observedMessageRevision, view.messageRevision);
-            }
-            if (includeTerminalDetails) {
-                if (observation)
-                    observation.terminalRevision = Math.max(observation.terminalRevision, view.resourceRevision);
-                else
-                    state.observedTerminalRevision = Math.max(state.observedTerminalRevision, view.resourceRevision);
-            }
-            return result;
         });
-        return {
-            mode,
-            waitFor,
-            agents,
-            pendingAgentIds,
-            ...waitMetadata(snapshot
-                ? 'snapshot'
-                : !satisfied
-                    ? options.waitInterrupt?.pending()
-                        ? 'interrupted'
-                        : 'timeout'
-                    : agents.some((agent) => agent.waitOutcome === 'message')
-                        ? 'message'
-                        : 'completion')
-        };
     }
     async message(agentId, message, options = {}) {
-        const execution = this.#requireExecution();
-        if (typeof message !== 'string' ||
-            message.trim().length === 0 ||
-            (this.#retainedExecution.getStore()?.native !== true &&
-                Buffer.byteLength(message) > TOOL_EXECUTION_LIMITS.subagentMessageMaxBytes) ||
-            (options.delivery !== undefined &&
-                options.delivery !== 'append' &&
-                options.delivery !== 'replace'))
-            throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Agent message input is invalid.');
-        const state = await this.#find(agentId);
-        return this.#control(state, async () => {
-            this.#requireExecution();
-            options.signal?.throwIfAborted();
-            // Resolve before cancelling so an unavailable model does not stop valid work.
-            const selected = resolveExistingModel(execution, state);
-            if (options.delivery === 'replace')
-                await this.#cancelState(state);
-            this.#requireExecution();
-            options.signal?.throwIfAborted();
-            const turnId = state.turn?.turnId ?? randomUUID();
-            const receipt = { messageId: randomUUID(), turnId, deliveryStatus: 'accepted' };
-            const mutableReceipt = receipt;
-            const delivery = this.#createDelivery(state, execution, mutableReceipt, options.signal);
-            try {
-                if (state.status === 'running' && state.turn) {
-                    const turn = state.turn;
-                    if (!turn.handle)
-                        await turn.handleReady;
-                    this.#requireExecution();
-                    options.signal?.throwIfAborted();
-                    delivery.signal?.throwIfAborted();
-                    if (state.status === 'running' &&
-                        state.turn === turn &&
-                        turn.handle?.enqueueMessage(message, delivery)) {
+        return this.#using([agentId], async () => {
+            const execution = this.#requireExecution();
+            if (typeof message !== 'string' ||
+                message.trim().length === 0 ||
+                (this.#retainedExecution.getStore()?.native !== true &&
+                    Buffer.byteLength(message) > TOOL_EXECUTION_LIMITS.subagentMessageMaxBytes) ||
+                (options.delivery !== undefined &&
+                    options.delivery !== 'append' &&
+                    options.delivery !== 'replace'))
+                throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Agent message input is invalid.');
+            const state = await this.#find(agentId);
+            return this.#control(state, async () => {
+                this.#requireExecution();
+                options.signal?.throwIfAborted();
+                // Resolve before cancelling so an unavailable model does not stop valid work.
+                const selected = resolveExistingModel(execution, state);
+                if (options.delivery === 'replace')
+                    await this.#cancelState(state);
+                this.#requireExecution();
+                options.signal?.throwIfAborted();
+                const turnId = state.turn?.turnId ?? randomUUID();
+                const receipt = { messageId: randomUUID(), turnId, deliveryStatus: 'accepted' };
+                const mutableReceipt = receipt;
+                const delivery = this.#createDelivery(state, execution, mutableReceipt, options.signal);
+                try {
+                    if (state.status === 'running' && state.turn) {
+                        const turn = state.turn;
+                        if (!turn.handle)
+                            await turn.handleReady;
+                        this.#requireExecution();
+                        options.signal?.throwIfAborted();
+                        delivery.signal?.throwIfAborted();
+                        if (state.status === 'running' &&
+                            state.turn === turn &&
+                            turn.handle?.enqueueMessage(message, delivery)) {
+                            delivery.accepted();
+                            state.receipt = mutableReceipt;
+                            return this.#messageReceiptSnapshot(state);
+                        }
+                        await turn.completion;
+                    }
+                    else if (state.status === 'queued' && state.turn) {
                         delivery.accepted();
+                        state.turn.pendingMessages.push({ text: message, delivery });
                         state.receipt = mutableReceipt;
                         return this.#messageReceiptSnapshot(state);
                     }
-                    await turn.completion;
-                }
-                else if (state.status === 'queued' && state.turn) {
+                    this.#requireExecution();
+                    options.signal?.throwIfAborted();
+                    delivery.signal?.throwIfAborted();
+                    state.modelId = selected.id;
+                    state.modelName = selected.name;
+                    state.reasoningEffort = selected.reasoningEffort;
+                    // A closing turn may have rejected append; reserve a fresh identity for its successor.
+                    mutableReceipt.turnId = randomUUID();
                     delivery.accepted();
-                    state.turn.pendingMessages.push({ text: message, delivery });
                     state.receipt = mutableReceipt;
+                    this.#queueTurn(state, message, execution, [], mutableReceipt.turnId, delivery, options.signal);
                     return this.#messageReceiptSnapshot(state);
                 }
-                this.#requireExecution();
-                options.signal?.throwIfAborted();
-                delivery.signal?.throwIfAborted();
-                state.modelId = selected.id;
-                state.modelName = selected.name;
-                state.reasoningEffort = selected.reasoningEffort;
-                // A closing turn may have rejected append; reserve a fresh identity for its successor.
-                mutableReceipt.turnId = randomUUID();
-                delivery.accepted();
-                state.receipt = mutableReceipt;
-                this.#queueTurn(state, message, execution, [], mutableReceipt.turnId, delivery, options.signal);
-                return this.#messageReceiptSnapshot(state);
-            }
-            catch (error) {
-                delivery.settled?.(options.signal?.aborted || ('signal' in execution && execution.signal.aborted)
-                    ? 'cancelled'
-                    : 'failed');
-                throw error;
-            }
+                catch (error) {
+                    delivery.settled?.(options.signal?.aborted || ('signal' in execution && execution.signal.aborted)
+                        ? 'cancelled'
+                        : 'failed');
+                    throw error;
+                }
+            });
         });
     }
     async cancel(agentId) {
-        const state = await this.#find(agentId);
-        await this.#control(state, () => this.#cancelState(state));
-        const includeLatestMessage = this.#hasUnreadMessage(state);
-        const includeTerminalDetails = this.#observeTerminal(state);
-        this.#observeLatestMessage(state);
-        return this.#snapshot(state, { includeLatestMessage, includeTerminalDetails });
+        return this.#using([agentId], async () => {
+            const state = await this.#find(agentId);
+            await this.#control(state, () => this.#cancelState(state));
+            const includeLatestMessage = this.#hasUnreadMessage(state);
+            const includeTerminalDetails = this.#observeTerminal(state);
+            this.#observeLatestMessage(state);
+            return this.#snapshot(state, { includeLatestMessage, includeTerminalDetails });
+        });
     }
     #control(state, operation) {
         const result = (state.controlTail ?? Promise.resolve()).then(operation);
-        state.controlTail = result.catch(() => undefined);
+        const tail = result.then(() => undefined, () => undefined);
+        state.controlTail = tail;
+        void tail.then(() => {
+            if (state.controlTail === tail)
+                delete state.controlTail;
+        });
         return result;
     }
     async #cancelState(state) {
@@ -730,6 +771,7 @@ export class SubagentSessionController {
                     ? native.signal
                     : AbortSignal.any([native.signal, signal]));
         state.status = 'queued';
+        state.restorable = false;
         this.#touchResource(state);
         delete state.summary;
         delete state.permissionStop;
@@ -807,9 +849,18 @@ export class SubagentSessionController {
         await this.#consumeTurn(state, turn);
     }
     async #consumeTurn(state, turn) {
+        const previousActivity = state.latestActivity;
+        const previousMessageRevision = state.messageRevision;
+        let terminal;
         try {
             const consume = (async () => {
                 for await (const event of turn.handle) {
+                    if (event.type === 'execution.completed')
+                        terminal = 'completed';
+                    else if (event.type === 'execution.failed')
+                        terminal = 'failed';
+                    else if (event.type === 'execution.cancelled')
+                        terminal = 'cancelled';
                     if (!observeAgentEvent(state, event))
                         continue;
                     state.messageRevision++;
@@ -835,6 +886,14 @@ export class SubagentSessionController {
                 state.errorCode = result.errorCode ?? 'MAR_AGENT_SUBAGENT_FAILED';
                 state.errorMessage = result.errorMessage ?? 'Subagent execution failed.';
             }
+            state.restorable =
+                turn.handle.persistedEvents === true &&
+                    terminal === state.status &&
+                    (previousActivity === undefined || state.latestActivity !== previousActivity) &&
+                    (state.latestMessage === undefined || state.messageRevision > previousMessageRevision) &&
+                    (state.status !== 'completed' ||
+                        (state.latestMessage?.phase === 'final_answer' &&
+                            state.summary === state.latestMessage.text));
             state.terminalPending = true;
             this.#touchResource(state, true);
             this.#closeReceipt(state);
@@ -869,6 +928,7 @@ export class SubagentSessionController {
     #setFailure(state, error) {
         const diagnostic = describeMarAgentError(error, 'MAR_AGENT_SUBAGENT_FAILED');
         state.status = 'failed';
+        state.restorable = false;
         state.errorCode = diagnostic.code;
         state.errorMessage = diagnostic.message;
         state.terminalPending = true;
@@ -1014,11 +1074,61 @@ export class SubagentSessionController {
         }
         throw error;
     }
+    async #using(ids, operation) {
+        if (ids === undefined)
+            this.#allReaders++;
+        else
+            for (const id of ids)
+                this.#readers.set(id, (this.#readers.get(id) ?? 0) + 1);
+        try {
+            return await operation();
+        }
+        finally {
+            if (ids === undefined)
+                this.#allReaders--;
+            else
+                for (const id of ids) {
+                    const count = this.#readers.get(id) - 1;
+                    if (count)
+                        this.#readers.set(id, count);
+                    else
+                        this.#readers.delete(id);
+                }
+        }
+    }
+    #releaseOldDetails() {
+        if (this.#allReaders)
+            return;
+        const terminal = [...this.#agents.values()]
+            .filter(isTerminalState)
+            .sort((a, b) => b.resourceRevision - a.resourceRevision);
+        for (const state of terminal.slice(RECENT_TERMINAL_RESOURCE_LIMIT)) {
+            if (state.detailsEvicted ||
+                !state.restorable ||
+                state.turn ||
+                state.controlTail ||
+                this.#readers.has(state.agentId) ||
+                this.#loading.has(state.agentId) ||
+                state.terminalPending ||
+                state.messageRevision > state.observedMessageRevision ||
+                (state.terminalRevision !== undefined &&
+                    state.terminalRevision > state.observedTerminalRevision) ||
+                [...this.#pendingDeliveries].some((pending) => pending.state === state))
+                continue;
+            // Keep identity and cursors for old acknowledgements; only the disk-backed body unloads.
+            for (const key of DETAIL_FIELDS)
+                delete state[key];
+            state.changedFiles = [];
+            state.verification = [];
+            state.evidence = [];
+            state.detailsEvicted = true;
+        }
+    }
     async #find(agentId) {
         if (this.#disposed)
             throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
         const known = this.#agents.get(agentId);
-        if (known)
+        if (known && !known.detailsEvicted)
             return known;
         const pending = this.#loading.get(agentId);
         if (pending)
@@ -1027,12 +1137,25 @@ export class SubagentSessionController {
             const persisted = await this.backend.loadChild(this.parentSessionId, agentId);
             if (this.#disposed)
                 throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
-            if (!persisted)
+            if (!persisted) {
+                this.#agents.delete(agentId);
+                this.#discovered.delete(agentId);
                 throw new MarAgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Subagent was not found.');
+            }
             const existing = this.#agents.get(agentId);
-            if (existing)
+            if (existing && !existing.detailsEvicted)
                 return existing;
             const restored = restoreAgentState(persisted);
+            if (existing) {
+                for (const key of DETAIL_FIELDS) {
+                    if (key in restored)
+                        Object.assign(existing, { [key]: restored[key] });
+                    else
+                        delete existing[key];
+                }
+                delete existing.detailsEvicted;
+                return existing;
+            }
             let revision = this.#discovered.get(agentId);
             if (revision === undefined) {
                 revision = ++this.#resourceRevision;
@@ -1223,6 +1346,7 @@ function restoreAgentState(session) {
     const terminal = currentRecords.findLast((record) => ['execution.completed', 'execution.failed', 'execution.cancelled'].includes(eventType(record) ?? ''));
     const terminalType = eventType(terminal);
     const state = {
+        restorable: true,
         agentId: session.id,
         description: session.source.description,
         role: session.source.role,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.10.61",
+  "version": "0.10.62",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",