@myagentroam/agent 0.9.136 → 0.9.138

package/dist/sdk/types.d.ts

@@ -22,6 +22,8 @@ export interface ToolExecutionContext {
         readonly data: Buffer;
     }[];
     codeMode?: {
+        retainSession?(): Promise<() => Promise<void>>;
+        onSettled?(result: CodeCellEventData): Promise<void>;
         supportsImages?: boolean;
         tools: readonly import('../model/contracts.js').ClientToolDefinition[];
         state?: readonly CodeModeStateEntry[];
@@ -92,7 +94,17 @@ export interface ToolExecutionResult {
     }[];
     artifacts?: readonly MarAgentToolArtifact[];
 }
+export interface CodeCellEventData {
+    cellId: string;
+    status: 'running' | 'completed' | 'failed' | 'cancelled';
+    cached?: boolean;
+}
 export interface HostSessionResourceSnapshot {
+    codeCells?: readonly {
+        cellId: string;
+        status: 'running' | 'completed' | 'failed' | 'cancelled';
+        executionId: string;
+    }[];
     idleTtlMs?: number;
     processes: readonly {
         processId: string;
@@ -143,7 +155,7 @@ export type MarAgentEvent = MarAgentEventBase & ({
     modelName: string;
 } | {
     type: 'model.performance';
-    ttftMs: number;
+    latencyMs: number;
     outputTokens?: number | undefined;
     outputDurationMs?: number | undefined;
     tokensPerSecond?: number | undefined;
@@ -186,19 +198,22 @@ export type MarAgentEvent = MarAgentEventBase & ({
     type: 'tool.started';
     toolName: string;
     callId: string;
+    parentCallId?: string;
     input?: unknown;
 } | {
     type: 'tool.completed';
     toolName: string;
     callId: string;
+    parentCallId?: string;
     summary: string;
     truncated?: boolean;
     artifacts?: readonly MarAgentToolArtifact[];
-    data?: import('../tools/exec.js').ExecResult | Omit<import('../tools/exec.js').ExecResult, 'stdout' | 'stderr'> | import('../tools/apply-patch.js').ApplyPatchResult | import('../tools/read.js').ReadEventData | import('../tools/view-image.js').ViewImageResult | import('../subagent/scheduler.js').SubagentTaskSnapshot;
+    data?: CodeCellEventData | import('../tools/exec.js').ExecResult | Omit<import('../tools/exec.js').ExecResult, 'stdout' | 'stderr'> | import('../tools/apply-patch.js').ApplyPatchResult | import('../tools/read.js').ReadEventData | import('../tools/view-image.js').ViewImageResult | import('../subagent/scheduler.js').SubagentTaskSnapshot;
 } | {
     type: 'tool.failed';
     toolName: string;
     callId: string;
+    parentCallId?: string;
     code: string;
     message?: string;
 } | {

package/dist/session/context-gc-checkpoint.d.ts

@@ -50,7 +50,7 @@ export type ContextGcReplacement = {
     readonly evidenceSequences: readonly number[];
 } | {
     readonly kind: 'TOOL_CALL_INPUT';
-    readonly toolName: 'apply_patch' | 'exec' | 'code_mode';
+    readonly toolName: 'apply_patch' | 'exec' | 'code_mode' | 'code_exec';
     readonly callId: string;
     readonly target: ContextGcTarget;
     readonly replacementArguments: unknown;

package/dist/session/context-gc-checkpoint.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { posix, win32 } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { parseReadContextOutput } from '../tools/read-context.js';
-import { contextGcApplyPatchInputReplacement, contextGcCodeModeInputReplacement, contextGcCodeModeOutputReplacement, contextGcExecInputReplacement, contextGcExecOutputReplacement, contextGcPatchResultFromCompletedPayload, contextGcStaleReadReplacement, contextGcWebOutputReplacement, normalizeContextGcCodeModeInput, normalizeContextGcExecResult } from './context-gc-replacements.js';
+import { codeCellCompletionSequence, contextGcApplyPatchInputReplacement, contextGcCodeModeInputReplacement, contextGcCodeModeOutputReplacement, contextGcExecInputReplacement, contextGcExecOutputReplacement, contextGcPatchResultFromCompletedPayload, contextGcStaleReadReplacement, contextGcWebOutputReplacement, normalizeContextGcCodeModeInput, normalizeContextGcExecResult } from './context-gc-replacements.js';
 import { contextGcSubagentNeedsRetainedPriorFinal, contextGcSubagentOutputReplacement, contextGcSubagentSnapshotIsPreciselyCovered, contextGcSubagentSnapshotIsSuperseded, normalizeContextGcSubagentSnapshot } from './context-gc-subagent.js';
 export const CONTEXT_GC_CHECKPOINT_VERSION = 1;
 export const CONTEXT_GC_MAX_TARGETS = 4_096;
@@ -266,17 +266,22 @@ function replacementMatchesRecords(replacement, records, recordsBySequence, work
             result !== undefined &&
             isDeepStrictEqual(replacement.replacementArguments, contextGcApplyPatchInputReplacement(source.payload.arguments, result, replacement.evidenceSequence, applyPatchReplacementFormatVersion(replacement.replacementArguments))));
     }
-    if (replacement.kind === 'TOOL_CALL_INPUT' && replacement.toolName === 'code_mode') {
-        const evidence = successfulToolEvidence(records, recordsBySequence, replacement.evidenceSequence, 'code_mode');
+    if (replacement.kind === 'TOOL_CALL_INPUT' &&
+        (replacement.toolName === 'code_mode' || replacement.toolName === 'code_exec')) {
+        const evidence = successfulToolEvidence(records, recordsBySequence, replacement.evidenceSequence, replacement.toolName);
         const input = normalizeContextGcCodeModeInput(source.payload.arguments);
         return (evidence?.callId === replacement.callId &&
+            codeCellCompletionSequence(records, evidence.completed) !== undefined &&
             evidence.call.sequence === replacement.target.sequence &&
             input !== undefined &&
             isDeepStrictEqual(replacement.replacementArguments, contextGcCodeModeInputReplacement(input)));
     }
     if (replacement.kind === 'CODE_MODE_OUTPUT') {
-        const evidence = successfulToolEvidence(records, recordsBySequence, replacement.evidenceSequence, 'code_mode');
+        const evidence = ['code_mode', 'code_exec', 'code_exec_wait']
+            .map((name) => successfulToolEvidence(records, recordsBySequence, replacement.evidenceSequence, name))
+            .find((item) => item !== undefined);
         return (evidence?.callId === replacement.callId &&
+            codeCellCompletionSequence(records, evidence.completed) !== undefined &&
             evidence.result.sequence === replacement.target.sequence &&
             isRecord(evidence.result.payload) &&
             typeof evidence.result.payload.content === 'string' &&
@@ -626,7 +631,8 @@ function isContextGcReplacement(value) {
             value.target.role === 'tool_call' &&
             (value.toolName === 'apply_patch' ||
                 value.toolName === 'exec' ||
-                value.toolName === 'code_mode') &&
+                value.toolName === 'code_mode' ||
+                value.toolName === 'code_exec') &&
             value.target.toolName === value.toolName &&
             Array.isArray(value.providerAliasTargets) &&
             value.providerAliasTargets.every((target) => isContextGcTarget(target) &&

package/dist/session/context-gc-replacements.d.ts

@@ -60,3 +60,5 @@ export declare function contextGcExecInputReplacement(arguments_: unknown, forma
 export declare function contextGcExecOutputReplacement(result: ContextGcExecResult, formatVersion?: 1 | 2 | 3): string;
 export declare function normalizeContextGcExecResult(modelContent: unknown, completedPayload: unknown): ContextGcExecResult | undefined;
 export declare function parseContextGcExecResult(value: unknown): ContextGcExecResult | undefined;
+/** A returned tool wait is not proof that its retained JavaScript cell finished. */
+export declare function codeCellCompletionSequence(records: readonly import('./jsonl-store.js').SessionRecord[], completed: import('./jsonl-store.js').SessionRecord): number | undefined;

package/dist/session/context-gc-replacements.js

@@ -314,3 +314,21 @@ function isNonemptyString(value) {
 function isNonnegativeInteger(value) {
     return Number.isSafeInteger(value) && Number(value) >= 0;
 }
+/** A returned tool wait is not proof that its retained JavaScript cell finished. */
+export function codeCellCompletionSequence(records, completed) {
+    if (!isRecord(completed.payload))
+        return undefined;
+    if (completed.payload.toolName === 'code_mode')
+        return completed.sequence;
+    const data = completed.payload.data;
+    if (!isRecord(data) || typeof data.cellId !== 'string')
+        return undefined;
+    if (data.status === 'completed')
+        return completed.sequence;
+    if (data.status !== 'running')
+        return undefined;
+    return records.findLast((record) => record.type === 'code.cell.completed' &&
+        isRecord(record.payload) &&
+        record.payload.cellId === data.cellId &&
+        record.payload.status === 'completed')?.sequence;
+}

package/dist/session/jsonl-store.d.ts

@@ -151,6 +151,7 @@ export declare class JsonlSessionStore {
     commitCodeModeState(sessionId: string, mutations: unknown, input: {
         readonly executionId: string;
         readonly turnId: string;
+        readonly expectedState?: readonly CodeModeStateEntry[];
     }): Promise<CodeModeStateEntry[]>;
     readExecutionState(sessionId: string): Promise<SessionExecutionState>;
     readContext(sessionId: string): Promise<SessionRecord[]>;
@@ -175,8 +176,10 @@ export declare class JsonlSessionStore {
         executionId?: string;
         turnId?: string;
     }): Promise<SessionRecord>;
-    /** Recover files under the sole writer lock; flush dirty index state before releasing it. */
-    acquireSessionLease(sessionId: string): Promise<() => Promise<void>>;
+    /** A warm cell retains physical writer ownership between Executions of the same Agent. */
+    acquireSessionLease(sessionId: string, owner?: object): Promise<() => Promise<void>>;
+    hasRetainedSessionLease(sessionId: string, owner: object): boolean;
+    retainSessionLease(sessionId: string, owner: object): Promise<() => Promise<void>>;
     list(input?: SessionListInput): Promise<{
         nextCursor?: string;
         sessions: {

package/dist/session/jsonl-store.js

@@ -157,6 +157,9 @@ export class JsonlSessionStore {
             indexDirty: false,
             dirtySessionVersions: new Map(),
             pendingPublishIds: new Set(),
+            codeStateWrites: new Map(),
+            recordWrites: new Map(),
+            writerLeases: new Map(),
             segments: new Map(),
             executionModelReads: new Map()
         };
@@ -897,6 +900,22 @@ export class JsonlSessionStore {
         };
     }
     async append(sessionId, input) {
+        return this.#serializeRecordOperation(sessionId, () => this.#appendRecord(sessionId, input));
+    }
+    async #serializeRecordOperation(sessionId, action) {
+        const operation = (this.#shared.recordWrites.get(sessionId) ?? Promise.resolve())
+            .catch(() => undefined)
+            .then(action);
+        this.#shared.recordWrites.set(sessionId, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            if (this.#shared.recordWrites.get(sessionId) === operation)
+                this.#shared.recordWrites.delete(sessionId);
+        }
+    }
+    async #appendRecord(sessionId, input) {
         this.#assertOpen();
         const meta = this.#shared.index.sessions.find((item) => item.id === sessionId) ??
             this.#shared.pendingSessions.get(sessionId);
@@ -974,6 +993,9 @@ export class JsonlSessionStore {
         return record;
     }
     async read(sessionId) {
+        return this.#serializeRecordOperation(sessionId, () => this.#readRecords(sessionId));
+    }
+    async #readRecords(sessionId) {
         this.#assertOpen();
         try {
             const records = [];
@@ -991,17 +1013,32 @@ export class JsonlSessionStore {
         return restoreCodeModeState(await this.read(sessionId));
     }
     async commitCodeModeState(sessionId, mutations, input) {
-        const parsed = parseCodeModeStateMutations(mutations);
-        if (parsed.length === 0)
-            return this.readCodeModeState(sessionId);
-        const state = applyCodeModeStateMutations(await this.readCodeModeState(sessionId), parsed);
-        await this.append(sessionId, {
-            type: 'code.state.updated',
-            payload: { mutations: parsed },
-            executionId: input.executionId,
-            turnId: input.turnId
+        const operation = (this.#shared.codeStateWrites.get(sessionId) ?? Promise.resolve())
+            .catch(() => undefined)
+            .then(async () => {
+            const parsed = parseCodeModeStateMutations(mutations);
+            if (parsed.length === 0)
+                return this.readCodeModeState(sessionId);
+            const current = await this.readCodeModeState(sessionId);
+            if (input.expectedState && !isDeepStrictEqual(current, input.expectedState))
+                throw new MarAgentError('MAR_AGENT_CODE_STATE_CONFLICT', 'Session state changed while this cell was running.');
+            const state = applyCodeModeStateMutations(current, parsed);
+            await this.append(sessionId, {
+                type: 'code.state.updated',
+                payload: { mutations: parsed },
+                executionId: input.executionId,
+                turnId: input.turnId
+            });
+            return state;
         });
-        return state;
+        this.#shared.codeStateWrites.set(sessionId, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            if (this.#shared.codeStateWrites.get(sessionId) === operation)
+                this.#shared.codeStateWrites.delete(sessionId);
+        }
     }
     async readExecutionState(sessionId) {
         this.#assertOpen();
@@ -1155,8 +1192,64 @@ export class JsonlSessionStore {
             ...(input.turnId ? { turnId: input.turnId } : {})
         });
     }
+    /** A warm cell retains physical writer ownership between Executions of the same Agent. */
+    async acquireSessionLease(sessionId, owner) {
+        return this.#serializeRecordOperation(sessionId, async () => {
+            this.#assertOpen();
+            let lease = this.#shared.writerLeases.get(sessionId);
+            if (lease) {
+                if (lease.executing || owner === undefined || lease.owner !== owner)
+                    throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', 'Session already has a writer.');
+                lease.executing = true;
+            }
+            else {
+                const release = await this.#acquireSessionLease(sessionId);
+                lease = { owner, executing: true, retained: 0, release };
+                this.#shared.writerLeases.set(sessionId, lease);
+            }
+            const current = lease;
+            let released = false;
+            return () => this.#serializeRecordOperation(sessionId, async () => {
+                if (released)
+                    return;
+                released = true;
+                current.executing = false;
+                await this.#releaseUnusedWriter(sessionId, current);
+            });
+        });
+    }
+    hasRetainedSessionLease(sessionId, owner) {
+        const lease = this.#shared.writerLeases.get(sessionId);
+        return lease?.owner === owner && lease.retained > 0;
+    }
+    async retainSessionLease(sessionId, owner) {
+        return this.#serializeRecordOperation(sessionId, async () => {
+            const lease = this.#shared.writerLeases.get(sessionId);
+            if (!lease || !lease.executing || lease.owner !== owner)
+                throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', 'Retained work requires its originating Session writer.');
+            lease.retained++;
+            let released = false;
+            return () => this.#serializeRecordOperation(sessionId, async () => {
+                if (released)
+                    return;
+                released = true;
+                lease.retained--;
+                await this.#releaseUnusedWriter(sessionId, lease);
+            });
+        });
+    }
+    async #releaseUnusedWriter(sessionId, lease) {
+        if (lease.executing || lease.retained)
+            return;
+        try {
+            await lease.release();
+        }
+        finally {
+            this.#shared.writerLeases.delete(sessionId);
+        }
+    }
     /** Recover files under the sole writer lock; flush dirty index state before releasing it. */
-    async acquireSessionLease(sessionId) {
+    async #acquireSessionLease(sessionId) {
         this.#assertOpen();
         await this.#refreshIndex();
         if (!this.#shared.index.sessions.some((item) => item.id === sessionId))
@@ -1509,7 +1602,7 @@ export class JsonlSessionStore {
         const latestPath = paths.at(-1);
         await repairSegmentTail(latestPath);
         const records = await readRecords(latestPath);
-        await recoverPendingInputImages(this.sessionDirectory(sessionId), () => this.read(sessionId));
+        await recoverPendingInputImages(this.sessionDirectory(sessionId), () => this.#readRecords(sessionId));
         const last = records.at(-1);
         const match = /events-(\d{6})\.jsonl$/.exec(latestPath);
         const segment = Number(match?.[1] ?? 1);

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

@@ -83,6 +83,8 @@ export declare class SubagentSessionController implements SubagentController {
         };
     }): Promise<SubagentSessionController>;
     beginParentExecution(execution: SubagentParentExecution): Promise<void>;
+    /** A retained cell must not borrow a later model Execution's identity or task budget. */
+    captureExecution(): SubagentController;
     endParentExecution(executionId: string): void;
     run(input: SubagentTaskInput, options?: SubagentRunOptions): Promise<SubagentTaskSnapshot>;
     output(agentId: string, options?: SubagentOutputOptions): Promise<SubagentTaskSnapshot>;

package/dist/subagent/session-controller.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 import { MarAgentError, describeMarAgentError } from '../error.js';
 import { TOOL_EXECUTION_LIMITS } from '../tools/execution-limits.js';
@@ -14,7 +15,8 @@ export class SubagentSessionController {
     #resourceRevision = 0;
     #running = 0;
     #disposed = false;
-    #createdInExecution = 0;
+    #creationBudget = { count: 0 };
+    #retainedExecution = new AsyncLocalStorage();
     #execution;
     constructor(parentSessionId, rootSessionId, backend, limits = { maxTasks: 8, maxConcurrent: 4 }) {
         this.parentSessionId = parentSessionId;
@@ -36,10 +38,23 @@ export class SubagentSessionController {
         if (this.#disposed)
             throw new MarAgentError('MAR_AGENT_SUBAGENT_LIMIT', 'Subagent controller is disposed.');
         this.#execution = execution;
-        this.#createdInExecution = 0;
+        this.#creationBudget = { count: 0 };
         for (const state of this.#agents.values())
             await this.#publishTerminal(state);
     }
+    /** A retained cell must not borrow a later model Execution's identity or task budget. */
+    captureExecution() {
+        const context = { execution: this.#requireExecution(), budget: this.#creationBudget };
+        return {
+            run: (input, options) => this.#retainedExecution.run(context, () => this.run(input, options)),
+            message: (id, message, options) => this.#retainedExecution.run(context, () => this.message(id, message, options)),
+            output: (id, options) => this.output(id, options),
+            outputAny: (options) => this.outputAny(options),
+            cancel: (id) => this.cancel(id),
+            listSessionResources: () => this.listSessionResources(),
+            dispose: () => this.dispose()
+        };
+    }
     endParentExecution(executionId) {
         if (this.#execution?.executionId === executionId)
             this.#execution = undefined;
@@ -48,7 +63,8 @@ export class SubagentSessionController {
         options.signal?.throwIfAborted();
         const execution = this.#requireExecution();
         validateTaskInput(input);
-        if (this.#createdInExecution >= this.limits.maxTasks)
+        if ((this.#retainedExecution.getStore()?.budget ?? this.#creationBudget).count >=
+            this.limits.maxTasks)
             throw new MarAgentError('MAR_AGENT_SUBAGENT_LIMIT', 'Subagent task limit was reached.');
         const source = {
             type: 'subagent',
@@ -85,7 +101,7 @@ export class SubagentSessionController {
             terminalObserved: false,
             resourceRevision: ++this.#resourceRevision
         };
-        this.#createdInExecution++;
+        (this.#retainedExecution.getStore()?.budget ?? this.#creationBudget).count++;
         this.#agents.set(state.agentId, state);
         const knownModel = execution.models.get(input.modelId ?? execution.modelId);
         if (knownModel) {
@@ -589,9 +605,10 @@ export class SubagentSessionController {
     #requireExecution() {
         if (this.#disposed)
             throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
-        if (!this.#execution)
+        const execution = this.#retainedExecution.getStore()?.execution ?? this.#execution;
+        if (!execution)
             throw new MarAgentError('MAR_AGENT_SUBAGENT_FAILED', 'Subagent control requires an active parent execution.');
-        return this.#execution;
+        return execution;
     }
     #receiptSnapshot(state) {
         return this.#snapshot(state, {

package/dist/tools/callers.d.ts

@@ -2,3 +2,5 @@ import type { ClientToolDefinition, ToolCaller } from '../model/contracts.js';
 /** Normalize trusted Host policy independently of discovery, Agent scope and parallel safety. */
 export declare function toolCallers(tool: ClientToolDefinition): readonly ToolCaller[];
 export declare function allowsToolCaller(tool: ClientToolDefinition, caller: ToolCaller): boolean;
+/** Code Mode Only changes model exposure, never the Host's underlying caller permissions. */
+export declare function allowsDirectTool(tool: ClientToolDefinition, codeModeEnabled: boolean): boolean;

package/dist/tools/callers.js

@@ -12,7 +12,13 @@ export function toolCallers(tool) {
 }
 export function allowsToolCaller(tool, caller) {
     // Control tools cannot be widened by a Host override or historical definition.
-    if (caller === 'programmatic' && ['code_mode', 'tool_search', 'question'].includes(tool.name))
+    if (caller === 'programmatic' &&
+        ['code_exec', 'code_exec_wait', 'code_mode', 'tool_search', 'question'].includes(tool.name))
         return false;
     return toolCallers(tool).includes(caller);
 }
+/** Code Mode Only changes model exposure, never the Host's underlying caller permissions. */
+export function allowsDirectTool(tool, codeModeEnabled) {
+    return (allowsToolCaller(tool, 'direct') &&
+        (!codeModeEnabled || !allowsToolCaller(tool, 'programmatic')));
+}

package/dist/tools/code-mode/cells.d.ts

@@ -0,0 +1,20 @@
+import type { ToolExecutionContext, ToolExecutionResult } from '../../sdk/types.js';
+export interface CellOutput {
+    text(value: string): void;
+    image(value: NonNullable<ToolExecutionResult['images']>[number]): void;
+    yield(): void;
+}
+type Status = 'running' | 'completed' | 'failed' | 'cancelled';
+/** Session-owned execution, separate from the cancellable model-tool wait. */
+export declare class CodeCells {
+    #private;
+    start(value: unknown, context: ToolExecutionContext, run: (code: string, context: ToolExecutionContext, output: CellOutput) => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>;
+    wait(value: unknown, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    snapshot(sessionId: string): {
+        cellId: string;
+        status: Status;
+        executionId: string;
+    }[];
+    dispose(sessionId?: string): Promise<void>;
+}
+export {};