@myagentroam/agent 0.9.158 → 0.9.160

package/dist/agent-core/sdk/types.d.ts

@@ -1,4 +1,5 @@
 import type { MarAgentHost } from '../host/contracts.js';
+import type { CoreExtensionSource, CoreRuntimeExtension } from '../extensions/contracts.js';
 import type { MarAgentModelConfiguration } from '../model/configuration.js';
 import type { ExecutionResult, RolloutBudgetOptions, RunInput } from '../runtime/contracts.js';
 import type { MarAgentEvent } from '../runtime/events.js';
@@ -29,6 +30,7 @@ export interface MarAgentSession {
     cancel(executionId: string): Promise<void>;
 }
 export interface MarAgent {
+    extensionDiagnostics(): readonly import('../extensions/contracts.js').CoreExtensionDiagnostic[];
     createSession(input: CreateSessionInput): Promise<MarAgentSession>;
     openSession(sessionId: string): Promise<MarAgentSession>;
     listSessions(input?: SessionListInput): Promise<MarAgentSessionPage>;
@@ -59,5 +61,6 @@ export interface CreateMarAgentOptions {
         readonly physicalPath: string;
     };
     rolloutBudget?: false | RolloutBudgetOptions;
+    runtimeExtensions?: readonly CoreRuntimeExtension[] | CoreExtensionSource;
 }
 export type { MarAgentSessionSummary, SessionListInput, SessionSource };

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

@@ -659,7 +659,7 @@ function modelContextCallId(payload) {
     return typeof value === 'string' ? value : undefined;
 }
 function modelContextToolName(payload) {
-    if (payload.role === 'tool_call' && typeof payload.name === 'string')
+    if ((payload.role === 'tool_call' || payload.role === 'tool') && typeof payload.name === 'string')
         return payload.name;
     if (payload.role !== 'provider' || !isRecord(payload.item))
         return undefined;

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

@@ -1,4 +1,5 @@
-import type { ModelUsage } from '../model/contracts.js';
+import { type CoreCheckpoint, type CoreJsonValue } from '../extensions/data.js';
+import type { ModelMessage, ModelUsage } from '../model/contracts.js';
 import type { EnvironmentContextState } from '../runtime/context/contracts.js';
 import { type CodeModeStateEntry } from '../tools/code-mode/state.js';
 import { type TodoSnapshot } from '../tools/agent/todo.js';
@@ -16,6 +17,13 @@ export interface SessionRecord {
     type: string;
     payload: unknown;
 }
+interface SessionRecordInput {
+    type: string;
+    payload: unknown;
+    executionId?: string;
+    turnId?: string;
+    timestamp?: string;
+}
 export interface SessionExecutionState {
     automaticTitlePending: boolean;
     todo: TodoSnapshot;
@@ -139,15 +147,19 @@ export declare class JsonlSessionStore {
         source: SessionSource;
         automaticTitlePending: boolean;
     }>;
-    append(sessionId: string, input: {
-        type: string;
-        payload: unknown;
-        executionId?: string;
-        turnId?: string;
-        timestamp?: string;
+    /** Serialize physical writes and honor cancellation before entering the writer. */
+    append(sessionId: string, input: SessionRecordInput, options?: {
+        readonly signal?: AbortSignal;
     }): Promise<SessionRecord>;
     read(sessionId: string): Promise<SessionRecord[]>;
     readCodeModeState(sessionId: string): Promise<CodeModeStateEntry[]>;
+    readExtensionCheckpoint(sessionId: string, extensionId: string, key: string): Promise<CoreCheckpoint>;
+    writeExtensionCheckpoint(sessionId: string, extensionId: string, key: string, value: CoreJsonValue | undefined, expectedRevision: number | undefined, input: {
+        owner: object;
+        signal: AbortSignal;
+        executionId?: string;
+        turnId?: string;
+    }): Promise<CoreCheckpoint>;
     commitCodeModeState(sessionId: string, mutations: unknown, input: {
         readonly executionId: string;
         readonly turnId: string;
@@ -168,6 +180,7 @@ export declare class JsonlSessionStore {
     compact(sessionId: string, input: {
         summary: string;
         replacementHistory?: readonly CompactHistoryMessage[];
+        retainedModelContext?: readonly ModelMessage[];
         environment?: EnvironmentContextState;
         automatic?: boolean;
         modelId?: string;
@@ -175,10 +188,14 @@ export declare class JsonlSessionStore {
         usage?: ModelUsage;
         executionId?: string;
         turnId?: string;
+    }, options?: {
+        readonly signal?: AbortSignal;
     }): Promise<SessionRecord>;
     /** 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;
+    /** Native writes join their Agent's sole writer, without admitting another Execution. */
+    acquireSessionWriteLease(sessionId: string, owner: object): Promise<() => Promise<void>>;
     retainSessionLease(sessionId: string, owner: object): Promise<() => Promise<void>>;
     list(input?: SessionListInput): Promise<{
         nextCursor?: string;
@@ -208,7 +225,10 @@ export declare class JsonlSessionStore {
             readonly type: "subagent";
             readonly parentSessionId: string;
             readonly rootSessionId: string;
-            readonly parentExecutionId: string;
+            readonly parentExecutionId?: string;
+            readonly parentOperationId?: string;
+            readonly ownerInstanceId?: string;
+            readonly extensionId?: string;
             readonly role: "general-purpose" | "explore";
             readonly description: string;
         };

package/dist/agent-core/session/jsonl-store.js

@@ -2,9 +2,10 @@ import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { copyFile, lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
-import { setTimeout as delay } from 'node:timers/promises';
 import { isDeepStrictEqual } from 'node:util';
 import { MarAgentError } from '../error.js';
+import { acquireFileLock } from '../storage/file-lock.js';
+import { cloneCoreJson } from '../extensions/data.js';
 import { applyCodeModeStateMutations, parseCodeModeStateMutations, restoreCodeModeState } from '../tools/code-mode/state.js';
 import { todoItemsFromSnapshot } from '../tools/agent/todo.js';
 import { contextGcBaseFromRecords, contextGcBaseSequence, contextGcMinimumUsageGrowth, contextGcSourceProjectionHash, latestValidContextGcCheckpoint, normalizeContextGcReplacements, parseContextGcCheckpoint, sameContextGcBase, validateContextGcCheckpoint } from './context-gc-checkpoint.js';
@@ -153,6 +154,7 @@ export class JsonlSessionStore {
         return {
             root,
             index,
+            indexOperations: Promise.resolve(),
             pendingSessions: new Map(),
             references: 1,
             closed: false,
@@ -170,6 +172,14 @@ export class JsonlSessionStore {
     }
     /** Merge dirty metadata with disk membership; only createdIds publish locally new entries. */
     async #saveIndex(deletedIds, createdIds = []) {
+        return this.#serializeIndexOperation(() => this.#commitIndex(deletedIds, createdIds));
+    }
+    async #serializeIndexOperation(operation) {
+        const next = this.#shared.indexOperations.then(operation, operation);
+        this.#shared.indexOperations = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    async #commitIndex(deletedIds, createdIds = []) {
         const release = await acquireFileLock(join(this.#shared.root, 'sessions', 'index.lock'));
         const path = join(this.#shared.root, 'sessions', 'index.json');
         try {
@@ -229,6 +239,9 @@ export class JsonlSessionStore {
         }
     }
     async #refreshIndex() {
+        return this.#serializeIndexOperation(() => this.#readCurrentIndex());
+    }
+    async #readCurrentIndex() {
         const disk = await readSessionIndex(join(this.#shared.root, 'sessions', 'index.json'));
         if (!disk)
             throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Session index is missing.');
@@ -874,7 +887,7 @@ export class JsonlSessionStore {
                     installedPaths.push(item.path);
                 }
                 meta.lastActivityAt = clearedAt;
-                meta.nextSequence = 2;
+                meta.nextSequence = retained.length + 1;
                 meta.storageTransactionId = transactionId;
                 meta.resume = { version: 1, todoRevision: 0, firstUserMessageIndexed: true };
                 meta.segments = staged.segments;
@@ -945,8 +958,14 @@ export class JsonlSessionStore {
             automaticTitlePending: meta.automaticTitlePending === true
         };
     }
-    async append(sessionId, input) {
-        return this.#serializeRecordOperation(sessionId, () => this.#appendRecord(sessionId, input));
+    /** Serialize physical writes and honor cancellation before entering the writer. */
+    async append(sessionId, input, options = {}) {
+        this.#assertOpen();
+        options.signal?.throwIfAborted();
+        return this.#serializeRecordOperation(sessionId, () => {
+            options.signal?.throwIfAborted();
+            return this.#appendRecord(sessionId, input);
+        });
     }
     async #serializeRecordOperation(sessionId, action) {
         const operation = (this.#shared.recordWrites.get(sessionId) ?? Promise.resolve())
@@ -1058,6 +1077,42 @@ export class JsonlSessionStore {
     async readCodeModeState(sessionId) {
         return restoreCodeModeState(await this.read(sessionId));
     }
+    async readExtensionCheckpoint(sessionId, extensionId, key) {
+        return restoreExtensionCheckpoint(await this.read(sessionId), extensionId, key);
+    }
+    async writeExtensionCheckpoint(sessionId, extensionId, key, value, expectedRevision, input) {
+        if (typeof key !== 'string' ||
+            (expectedRevision !== undefined &&
+                (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0)))
+            throw new MarAgentError('MAR_AGENT_EXTENSION_DATA_INVALID', 'Checkpoint key or expected revision is invalid.');
+        const copied = value === undefined ? undefined : cloneCoreJson(value);
+        input.signal.throwIfAborted();
+        const release = await this.acquireSessionWriteLease(sessionId, input.owner);
+        try {
+            return await this.#serializeRecordOperation(sessionId, async () => {
+                const current = restoreExtensionCheckpoint(await this.#readRecords(sessionId), extensionId, key);
+                if (expectedRevision !== undefined && expectedRevision !== current.revision)
+                    throw new MarAgentError('MAR_AGENT_EXTENSION_DATA_CONFLICT', 'Checkpoint revision changed before commit.');
+                input.signal.throwIfAborted();
+                const revision = current.revision + 1;
+                await this.#appendRecord(sessionId, {
+                    type: 'extension.checkpoint.updated',
+                    payload: {
+                        extensionId,
+                        key,
+                        revision,
+                        ...(copied === undefined ? { deleted: true } : { value: copied })
+                    },
+                    ...(input.executionId ? { executionId: input.executionId } : {}),
+                    ...(input.turnId ? { turnId: input.turnId } : {})
+                });
+                return { revision, ...(copied === undefined ? {} : { value: cloneCoreJson(copied) }) };
+            });
+        }
+        finally {
+            await release();
+        }
+    }
     async commitCodeModeState(sessionId, mutations, input) {
         const operation = (this.#shared.codeStateWrites.get(sessionId) ?? Promise.resolve())
             .catch(() => undefined)
@@ -1212,7 +1267,7 @@ export class JsonlSessionStore {
         const previousBeforeSequence = hasEarlier ? page[0]?.sequence : undefined;
         return { records: page, ...(previousBeforeSequence ? { previousBeforeSequence } : {}) };
     }
-    async compact(sessionId, input) {
+    async compact(sessionId, input, options = {}) {
         if (!input.summary.trim())
             throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Compact summary is required.');
         const meta = this.#shared.index.sessions.find((item) => item.id === sessionId);
@@ -1225,6 +1280,9 @@ export class JsonlSessionStore {
                 ...(input.replacementHistory === undefined
                     ? {}
                     : { replacementHistory: input.replacementHistory }),
+                ...(input.retainedModelContext?.length
+                    ? { retainedModelContext: input.retainedModelContext }
+                    : {}),
                 ...(input.environment === undefined ? {} : { environment: input.environment }),
                 boundarySequence: meta.nextSequence - 1,
                 automatic: input.automatic === true,
@@ -1236,7 +1294,7 @@ export class JsonlSessionStore {
             },
             ...(input.executionId ? { executionId: input.executionId } : {}),
             ...(input.turnId ? { turnId: input.turnId } : {})
-        });
+        }, options);
     }
     /** A warm cell retains physical writer ownership between Executions of the same Agent. */
     async acquireSessionLease(sessionId, owner) {
@@ -1268,6 +1326,30 @@ export class JsonlSessionStore {
         const lease = this.#shared.writerLeases.get(sessionId);
         return lease?.owner === owner && lease.retained > 0;
     }
+    /** Native writes join their Agent's sole writer, without admitting another Execution. */
+    async acquireSessionWriteLease(sessionId, owner) {
+        return this.#serializeRecordOperation(sessionId, async () => {
+            this.#assertOpen();
+            let lease = this.#shared.writerLeases.get(sessionId);
+            if (lease && lease.owner !== owner)
+                throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', 'Session already has a writer.');
+            if (!lease) {
+                const release = await this.#acquireSessionLease(sessionId);
+                lease = { owner, executing: false, retained: 0, release };
+                this.#shared.writerLeases.set(sessionId, lease);
+            }
+            lease.retained++;
+            const current = lease;
+            let released = false;
+            return () => this.#serializeRecordOperation(sessionId, async () => {
+                if (released)
+                    return;
+                released = true;
+                current.retained--;
+                await this.#releaseUnusedWriter(sessionId, current);
+            });
+        });
+    }
     async retainSessionLease(sessionId, owner) {
         return this.#serializeRecordOperation(sessionId, async () => {
             const lease = this.#shared.writerLeases.get(sessionId);
@@ -2167,9 +2249,20 @@ function normalizeSessionSource(value) {
     if (value === undefined || value.type === 'user')
         return { type: 'user' };
     if (value.type !== 'subagent' ||
-        !value.parentSessionId ||
-        !value.rootSessionId ||
-        !value.parentExecutionId ||
+        typeof value.parentSessionId !== 'string' ||
+        !value.parentSessionId.trim() ||
+        typeof value.rootSessionId !== 'string' ||
+        !value.rootSessionId.trim() ||
+        (!value.parentExecutionId && !value.parentOperationId) ||
+        [
+            value.parentExecutionId,
+            value.parentOperationId,
+            value.ownerInstanceId,
+            value.extensionId
+        ].some((identity) => identity !== undefined && (typeof identity !== 'string' || !identity.trim())) ||
+        ((value.ownerInstanceId !== undefined || value.extensionId !== undefined) &&
+            value.parentOperationId === undefined) ||
+        typeof value.description !== 'string' ||
         !value.description.trim() ||
         (value.role !== 'general-purpose' && value.role !== 'explore'))
         throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Session source is invalid.');
@@ -2177,7 +2270,14 @@ function normalizeSessionSource(value) {
         type: 'subagent',
         parentSessionId: value.parentSessionId,
         rootSessionId: value.rootSessionId,
-        parentExecutionId: value.parentExecutionId,
+        ...(value.parentExecutionId === undefined
+            ? {}
+            : { parentExecutionId: value.parentExecutionId }),
+        ...(value.parentOperationId === undefined
+            ? {}
+            : { parentOperationId: value.parentOperationId }),
+        ...(value.ownerInstanceId === undefined ? {} : { ownerInstanceId: value.ownerInstanceId }),
+        ...(value.extensionId === undefined ? {} : { extensionId: value.extensionId }),
         role: value.role,
         description: value.description.trim()
     };
@@ -2630,81 +2730,21 @@ function segmentNumberFromPath(path) {
     const match = /events-(\d{6})\.jsonl$/.exec(path);
     return match === null ? undefined : Number(match[1]);
 }
-async function acquireFileLock(path, message = 'Session index is busy.', waitMs = 5000) {
-    const deadline = Date.now() + waitMs;
-    for (;;) {
-        let handle;
-        try {
-            handle = await open(path, 'wx', 0o600);
-        }
-        catch (cause) {
-            if (cause.code !== 'EEXIST')
-                throw cause;
-            if (await removeDeadOwner(path))
-                continue;
-            if (Date.now() >= deadline)
-                throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', message, { cause });
-            await delay(25 + Math.floor(Math.random() * 25));
+function restoreExtensionCheckpoint(records, extensionId, key) {
+    for (const record of [...records].reverse()) {
+        if (record.type !== 'extension.checkpoint.updated')
             continue;
-        }
-        try {
-            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
-        }
-        catch (error) {
-            try {
-                await handle.close();
-            }
-            finally {
-                await rm(path, { force: true });
-            }
-            throw error;
-        }
-        let released = false;
-        return async () => {
-            if (released)
-                return;
-            released = true;
-            await handle.close();
-            await rm(path, { force: true });
+        const payload = record.payload;
+        if (!payload || payload.extensionId !== extensionId || payload.key !== key)
+            continue;
+        if (typeof payload.revision !== 'number' ||
+            !Number.isSafeInteger(payload.revision) ||
+            payload.revision < 1)
+            throw new MarAgentError('MAR_AGENT_SESSION_CORRUPT', 'Extension checkpoint revision is corrupt.');
+        return {
+            revision: payload.revision,
+            ...(payload.deleted === true ? {} : { value: cloneCoreJson(payload.value) })
         };
     }
-}
-async function removeDeadOwner(path) {
-    const reclaimerPath = `${path}.reclaim`;
-    let reclaimer;
-    try {
-        // Only one process may unlink a dead owner's path; all other contenders wait.
-        reclaimer = await open(reclaimerPath, 'wx', 0o600);
-    }
-    catch (error) {
-        if (error.code === 'EEXIST')
-            return false;
-        throw error;
-    }
-    try {
-        const owner = JSON.parse(await readFile(path, 'utf8'));
-        if (typeof owner.pid !== 'number' || !Number.isSafeInteger(owner.pid))
-            return false;
-        try {
-            process.kill(owner.pid, 0);
-            return false;
-        }
-        catch (error) {
-            if (error.code !== 'ESRCH')
-                return false;
-            await rm(path, { force: true });
-            return true;
-        }
-    }
-    catch {
-        return false;
-    }
-    finally {
-        try {
-            await reclaimer.close();
-        }
-        finally {
-            await rm(reclaimerPath, { force: true });
-        }
-    }
+    return { revision: 0 };
 }

package/dist/agent-core/session/types.d.ts

@@ -5,7 +5,10 @@ export type SessionSource = {
     readonly type: 'subagent';
     readonly parentSessionId: string;
     readonly rootSessionId: string;
-    readonly parentExecutionId: string;
+    readonly parentExecutionId?: string;
+    readonly parentOperationId?: string;
+    readonly ownerInstanceId?: string;
+    readonly extensionId?: string;
     readonly role: 'general-purpose' | 'explore';
     readonly description: string;
 };

package/dist/agent-core/storage/file-lock.d.ts

@@ -0,0 +1,4 @@
+export declare function acquireFileLock(path: string, message?: string, waitMs?: number, options?: {
+    readonly signal?: AbortSignal;
+    readonly code?: string;
+}): Promise<() => Promise<void>>;

package/dist/agent-core/storage/file-lock.js

@@ -0,0 +1,83 @@
+import { open, readFile, rm } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { MarAgentError } from '../error.js';
+export async function acquireFileLock(path, message = 'Session index is busy.', waitMs = 5000, options = {}) {
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        options.signal?.throwIfAborted();
+        let handle;
+        try {
+            handle = await open(path, 'wx', 0o600);
+        }
+        catch (cause) {
+            if (cause.code !== 'EEXIST')
+                throw cause;
+            if (await removeDeadOwner(path))
+                continue;
+            if (Date.now() >= deadline)
+                throw new MarAgentError(options.code ?? 'MAR_AGENT_SESSION_LOCKED', message, { cause });
+            await delay(25 + Math.floor(Math.random() * 25), undefined, options.signal ? { signal: options.signal } : {});
+            continue;
+        }
+        try {
+            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+            options.signal?.throwIfAborted();
+        }
+        catch (error) {
+            try {
+                await handle.close();
+            }
+            finally {
+                await rm(path, { force: true });
+            }
+            throw error;
+        }
+        let released = false;
+        return async () => {
+            if (released)
+                return;
+            released = true;
+            await handle.close();
+            await rm(path, { force: true });
+        };
+    }
+}
+async function removeDeadOwner(path) {
+    const reclaimerPath = `${path}.reclaim`;
+    let reclaimer;
+    try {
+        // Only one process may unlink a dead owner's path; all other contenders wait.
+        reclaimer = await open(reclaimerPath, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    try {
+        const owner = JSON.parse(await readFile(path, 'utf8'));
+        if (typeof owner.pid !== 'number' || !Number.isSafeInteger(owner.pid))
+            return false;
+        try {
+            process.kill(owner.pid, 0);
+            return false;
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                return false;
+            await rm(path, { force: true });
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            await reclaimer.close();
+        }
+        finally {
+            await rm(reclaimerPath, { force: true });
+        }
+    }
+}

package/dist/agent-core/subagent/contracts.d.ts

@@ -39,6 +39,8 @@ export type SubagentLatestActivity = {
 export interface SubagentTaskSnapshot extends Record<string, unknown> {
     agentId: string;
     description: string;
+    role?: SubagentTaskInput['role'];
+    extensionId?: string;
     status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled' | 'interrupted';
     modelId?: string;
     modelName?: string;
@@ -67,17 +69,25 @@ export interface SubagentMessageOptions {
     signal?: AbortSignal;
 }
 export interface SubagentRunOptions {
+    turnSignal?: AbortSignal;
+    waitFor?: 'start' | 'completion';
     signal?: AbortSignal;
     onCreated?: (task: SubagentTaskSnapshot) => Promise<void> | void;
 }
 export interface SubagentOutputOptions {
+    untilSettled?: true;
     waitMs?: number;
     waitFor?: SubagentWaitFor;
     signal?: AbortSignal;
 }
+export interface SubagentHandledResult {
+    readonly outcome: 'handled';
+    readonly value?: unknown;
+}
+export type SubagentRunResult = SubagentTaskSnapshot | SubagentHandledResult;
 export interface SubagentController {
     beginExecution?(runner: (task: SubagentTaskInput, signal: AbortSignal) => Promise<SubagentTaskResult>): void;
-    run(input: SubagentTaskInput, options?: SubagentRunOptions): Promise<SubagentTaskSnapshot>;
+    run(input: SubagentTaskInput, options?: SubagentRunOptions): Promise<SubagentRunResult>;
     output(agentId: string, options?: SubagentOutputOptions): Promise<SubagentTaskSnapshot>;
     outputAny(options?: SubagentOutputOptions): Promise<SubagentTaskSnapshot>;
     message(agentId: string, message: string, options?: SubagentMessageOptions): Promise<SubagentTaskSnapshot>;

package/dist/agent-core/subagent/scheduler.d.ts

@@ -16,6 +16,8 @@ export declare class SubagentScheduler implements SubagentController {
         waitOutcome: "snapshot";
         agentId: string;
         description: string;
+        role?: SubagentTaskInput["role"];
+        extensionId?: string;
         status: "queued" | "running" | "completed" | "failed" | "cancelled" | "interrupted";
         modelId?: string;
         modelName?: string;
@@ -39,6 +41,8 @@ export declare class SubagentScheduler implements SubagentController {
         waitOutcome: "completion" | "timeout";
         agentId: string;
         description: string;
+        role?: SubagentTaskInput["role"];
+        extensionId?: string;
         status: "queued" | "running" | "completed" | "failed" | "cancelled" | "interrupted";
         modelId?: string;
         modelName?: string;
@@ -63,6 +67,8 @@ export declare class SubagentScheduler implements SubagentController {
         waitOutcome: "snapshot";
         agentId: string;
         description: string;
+        role?: SubagentTaskInput["role"];
+        extensionId?: string;
         status: "queued" | "running" | "completed" | "failed" | "cancelled" | "interrupted";
         modelId?: string;
         modelName?: string;
@@ -86,6 +92,8 @@ export declare class SubagentScheduler implements SubagentController {
         waitOutcome: "completion" | "timeout";
         agentId: string;
         description: string;
+        role?: SubagentTaskInput["role"];
+        extensionId?: string;
         status: "queued" | "running" | "completed" | "failed" | "cancelled" | "interrupted";
         modelId?: string;
         modelName?: string;

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

@@ -1,3 +1,4 @@
+import type { CoreOperationContext } from '../extensions/operation.js';
 import type { MarAgentReasoningEffort } from '../model/configuration.js';
 import type { ExecutionResult } from '../runtime/contracts.js';
 import type { MarAgentEvent } from '../runtime/events.js';
@@ -18,7 +19,10 @@ export interface SubagentTurnHandle extends AsyncIterable<MarAgentEvent> {
 }
 export interface SubagentMessageDelivery {
     readonly messageId: string;
+    readonly origin?: CoreOperationContext;
+    readonly signal?: AbortSignal;
     applied(): void;
+    settled?(status: 'cancelled' | 'failed'): void;
 }
 export interface SubagentMailboxMessage {
     readonly text: string;
@@ -39,8 +43,18 @@ export interface SubagentParentExecution {
         readonly initialMailbox: readonly SubagentMailboxMessage[];
         readonly turnId: string;
         readonly delivery?: SubagentMessageDelivery;
+        readonly origin?: CoreOperationContext;
     }): Promise<SubagentTurnHandle>;
 }
+/** A native operation has its own provenance even when no parent Execution is active. */
+export interface SubagentParentOperation extends Omit<SubagentParentExecution, 'executionId'> {
+    readonly operationId: string;
+    readonly executionId?: string;
+    readonly ownerInstanceId?: string;
+    readonly extensionId?: string;
+    readonly signal: AbortSignal;
+    readonly origin?: CoreOperationContext;
+}
 export interface PersistedSubagentSession {
     readonly id: string;
     readonly createdAt: string;
@@ -85,8 +99,15 @@ 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;
+    captureExecution(executionId?: string): SubagentController;
+    /** SDK physical tool ingress shares the same captured parent as its model controls. */
+    captureParentFrame(executionId?: string): <Value>(run: () => Value) => Value;
+    withOperation<T>(operation: SubagentParentOperation, run: () => T): T;
+    inspect(agentId: string): Promise<SubagentTaskSnapshot>;
+    inspectAll(): readonly SubagentTaskSnapshot[];
+    cancelOwned(ownerInstanceId: string): Promise<void>;
     endParentExecution(executionId: string): void;
+    parentExecution(executionId: string): SubagentParentExecution | undefined;
     run(input: SubagentTaskInput, options?: SubagentRunOptions): Promise<SubagentTaskSnapshot>;
     output(agentId: string, options?: SubagentOutputOptions): Promise<SubagentTaskSnapshot>;
     outputAny(options?: SubagentOutputOptions): Promise<SubagentTaskSnapshot>;