@myagentroam/agent 0.11.39 → 0.11.40

package/dist/cli/subagent/wait.js

@@ -0,0 +1,453 @@
+import { AgentError } from '@myagentroam/agent';
+import { waitForToolCondition } from '@myagentroam/agent/extensions';
+import { target } from './control.js';
+import { boundedUtf8, nativeChildSnapshot, projectChildEvent, publicChildSnapshot } from './snapshot.js';
+import { modelWaitAgent } from './wait-output.js';
+function terminalStatus(type) {
+    if (type === 'execution.completed')
+        return 'completed';
+    if (type === 'execution.failed')
+        return 'failed';
+    if (type === 'execution.cancelled')
+        return 'cancelled';
+    return undefined;
+}
+function terminalFact(event, full = false) {
+    const status = terminalStatus(event?.type);
+    if (!status || !event)
+        return undefined;
+    return {
+        status,
+        ...(event.type === 'execution.failed'
+            ? {
+                errorCode: event.code,
+                ...(event.message === undefined
+                    ? {}
+                    : { errorMessage: full ? event.message : boundedUtf8(event.message, 1000).value })
+            }
+            : {}),
+        ...(event.type === 'execution.completed' && event.permissionStop !== undefined
+            ? {
+                permissionStop: full
+                    ? event.permissionStop
+                    : {
+                        ...event.permissionStop,
+                        reason: boundedUtf8(event.permissionStop.reason, 1000).value
+                    }
+            }
+            : {})
+    };
+}
+async function captureTarget(agent, session, observations, signal, history) {
+    observations.observe(session);
+    let executionId;
+    let terminal;
+    let projection = { changedFiles: [] };
+    const listeners = new Set();
+    const snapshot = session.subscribe((event) => {
+        if (event.executionId !== executionId)
+            return;
+        projectChildEvent(projection, event, observations.full);
+        const fact = terminalFact(event, observations.full);
+        if (!fact)
+            return;
+        terminal = fact;
+        for (const listener of listeners)
+            listener();
+    });
+    executionId = snapshot.activeExecutionId;
+    if (executionId)
+        projection = observations.snapshot(session.id, executionId);
+    terminal = terminalFact(snapshot.terminalEvent, observations.full);
+    if (executionId)
+        return {
+            session,
+            executionId,
+            startedBeforeTerminal: !terminal,
+            terminal: () => terminal,
+            snapshot: () => projection,
+            subscribe: (listener) => {
+                listeners.add(listener);
+                return () => {
+                    listeners.delete(listener);
+                };
+            },
+            close: () => {
+                listeners.clear();
+                snapshot.unsubscribe();
+            }
+        };
+    snapshot.unsubscribe();
+    let cursor;
+    let last;
+    const pages = [];
+    do {
+        signal.throwIfAborted();
+        const page = await history.sessionHistory(session.id, {
+            limit: 100,
+            ...(cursor === undefined ? {} : { cursor })
+        });
+        signal.throwIfAborted();
+        if (!last)
+            last = page.entries
+                .flatMap((entry) => (entry.kind === 'event' ? [entry.event] : []))
+                .findLast((event) => event.type === 'execution.started' || terminalStatus(event.type));
+        const events = page.entries.flatMap((entry) => entry.kind === 'event' && entry.event.executionId === last?.executionId ? [entry.event] : []);
+        pages.push(events);
+        cursor = events.some((event) => event.type === 'execution.started')
+            ? undefined
+            : page.nextCursor;
+    } while (cursor);
+    const observed = observations.terminal(session.id);
+    if (observed &&
+        (observed.executionId !== last?.executionId || last.type === 'execution.started')) {
+        const fact = terminalFact(observed, observations.full);
+        return {
+            session,
+            executionId: observed.executionId,
+            terminal: () => fact,
+            snapshot: () => observations.snapshot(session.id, observed.executionId),
+            subscribe: () => () => { },
+            close: () => { }
+        };
+    }
+    if (last &&
+        (terminalStatus(last.type) ||
+            (last.type === 'execution.started' &&
+                (await agent.sessionExecutionWasInterrupted(session.id, last.executionId, { signal }))))) {
+        for (const events of pages.reverse())
+            for (const event of events)
+                projectChildEvent(projection, event, observations.full);
+        const finalEvent = last;
+        const fact = finalEvent.type === 'execution.started'
+            ? { status: 'interrupted' }
+            : terminalFact(finalEvent, observations.full);
+        return {
+            session,
+            executionId: finalEvent.executionId,
+            terminal: () => fact,
+            snapshot: () => projection,
+            subscribe: () => () => { },
+            close: () => { }
+        };
+    }
+    throw new AgentError('MAR_AGENT_SUBAGENT_EXECUTION_NOT_FOUND', 'Session has no Execution to wait for.');
+}
+/** A foreground wait observes fixed Execution identities, never owning or cancelling them. */
+export function registerWait(context, agent, observations, history = agent) {
+    context.tools.register({
+        name: 'agent_wait',
+        description: 'Wait for direct child completion or a message; defaults to completion for 30 seconds.',
+        allowedCallers: ['direct', 'programmatic'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: ['string', 'null'], minLength: 1 },
+                agentIds: {
+                    type: ['array', 'null'],
+                    minItems: 1,
+                    maxItems: 8,
+                    uniqueItems: true,
+                    items: { type: 'string', minLength: 1 }
+                },
+                mode: { type: ['string', 'null'], enum: ['any', 'all', null] },
+                waitFor: { type: ['string', 'null'], enum: ['message', 'completion', null] },
+                waitMs: { type: ['integer', 'null'], minimum: 0, maximum: 300000 }
+            },
+            additionalProperties: false
+        },
+        async execute(raw, call) {
+            const value = raw;
+            const input = {
+                agentId: value.agentId ?? undefined,
+                agentIds: value.agentIds ?? undefined,
+                mode: value.mode ?? undefined,
+                waitFor: value.waitFor ?? undefined,
+                waitMs: value.waitMs ?? undefined
+            };
+            return waitForChild(context, agent, observations, input, call, 'model', observations, history);
+        }
+    });
+}
+/** Model and native callers share target capture and acknowledgement, not their limits or cursors. */
+export async function waitForChild(context, agent, observations, input, call, mode, receipts = observations, history = agent) {
+    call.signal.throwIfAborted();
+    if ((input.agentId !== undefined && input.agentIds !== undefined) ||
+        (input.mode !== undefined && input.agentIds === undefined) ||
+        (input.agentIds &&
+            (!input.agentIds.length ||
+                (mode === 'model' && input.agentIds.length > 8) ||
+                new Set(input.agentIds).size !== input.agentIds.length)))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Invalid wait targets.');
+    if (input.untilSettled && (mode !== 'native' || !input.agentId || input.waitFor === 'message'))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'An unbounded wait requires one completion target.');
+    if (input.waitMs !== undefined &&
+        (!Number.isSafeInteger(input.waitMs) ||
+            input.waitMs < 0 ||
+            (mode === 'model' && input.waitMs > 300000)))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Invalid wait duration.');
+    const single = input.agentIds === undefined;
+    let ids = input.agentIds ?? (input.agentId ? [input.agentId] : undefined);
+    if (!ids) {
+        const parent = await agent.getSession(context.sessionId);
+        call.signal.throwIfAborted();
+        const registration = agent.observeSessionExecutions(() => { });
+        ids = registration.sessions
+            .filter((session) => session.source.parentSessionId === context.sessionId &&
+            session.workspace === parent.workspace)
+            .map((session) => session.id);
+        registration.unsubscribe();
+        if (!ids.length) {
+            const candidates = [];
+            let cursor;
+            do {
+                call.signal.throwIfAborted();
+                const page = await agent.listSessions({
+                    parentSessionId: context.sessionId,
+                    limit: 100,
+                    ...(cursor === undefined ? {} : { cursor })
+                });
+                call.signal.throwIfAborted();
+                candidates.push(...page.sessions
+                    .filter((session) => session.workspace === parent.workspace)
+                    .map(({ id, createdAt }) => ({ id, createdAt })));
+                cursor = page.nextCursor;
+            } while (cursor);
+            candidates.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+            for (const candidate of candidates) {
+                call.signal.throwIfAborted();
+                try {
+                    const child = await agent.getSession(candidate.id);
+                    if (child.source.parentSessionId === context.sessionId &&
+                        child.workspace === parent.workspace) {
+                        ids = [candidate.id];
+                        break;
+                    }
+                }
+                catch (error) {
+                    if (!(error instanceof AgentError) || error.code !== 'MAR_AGENT_SESSION_NOT_FOUND')
+                        throw error;
+                }
+            }
+        }
+    }
+    if (!ids.length)
+        throw new AgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'No direct child Session is available.');
+    const sessions = await Promise.all(ids.map(async (id) => {
+        const result = await target(agent, context.sessionId, id);
+        if (!result.child)
+            throw new AgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Session is not available.');
+        const source = result.summary.source;
+        return {
+            session: result.session,
+            metadata: {
+                description: source.type === 'subagent' ? source.description : result.summary.title,
+                ...(source.type === 'subagent'
+                    ? {
+                        role: source.role,
+                        ...(source.extensionId === undefined ? {} : { extensionId: source.extensionId })
+                    }
+                    : {}),
+                ...(result.summary.modelId === undefined ? {} : { modelId: result.summary.modelId }),
+                ...(result.summary.modelName === undefined
+                    ? {}
+                    : { modelName: result.summary.modelName }),
+                ...(result.summary.reasoningEffort === undefined
+                    ? {}
+                    : { reasoningEffort: result.summary.reasoningEffort })
+            }
+        };
+    }));
+    const targets = [];
+    const receiptIdentities = [];
+    try {
+        for (const { session, metadata } of sessions) {
+            const captured = await captureTarget(agent, session, observations, call.signal, history);
+            targets.push({ ...captured, metadata });
+            const identity = receipts.receipt(session.id);
+            const historical = mode === 'model' && !identity && captured.executionId
+                ? await agent.sessionInputReceipt(session.id, {
+                    executionId: captured.executionId,
+                    source: {
+                        sessionId: context.sessionId,
+                        extensionId: 'subagent',
+                        actors: ['model', 'code-mode']
+                    },
+                    signal: call.signal
+                })
+                : undefined;
+            receiptIdentities.push(identity ??
+                (historical && {
+                    clientMessageId: historical.clientMessageId,
+                    executionId: historical.executionId
+                }));
+        }
+        call.signal.throwIfAborted();
+        const waitFor = input.waitFor ?? 'completion';
+        const read = (item) => {
+            const observation = item.executionId
+                ? observations.capture(item.session.id, item.executionId)
+                : undefined;
+            const snapshot = item.session.subscribe(() => { });
+            snapshot.unsubscribe();
+            const observed = observation?.updates.find((update) => update.kind === 'terminal');
+            const observedStatus = terminalStatus(observed?.value);
+            const terminal = item.terminal() ??
+                (snapshot.activeExecutionId === item.executionId
+                    ? terminalFact(snapshot.terminalEvent)
+                    : undefined) ??
+                (observedStatus === undefined
+                    ? undefined
+                    : {
+                        status: observedStatus,
+                        ...(observed?.errorCode === undefined ? {} : { errorCode: observed.errorCode }),
+                        ...(observed?.errorMessage === undefined
+                            ? {}
+                            : { errorMessage: observed.errorMessage }),
+                        ...(observed?.permissionStop === undefined
+                            ? {}
+                            : { permissionStop: observed.permissionStop })
+                    });
+            const message = observation?.updates.some((update) => update.kind === 'message') === true;
+            return { observation, terminal, ready: !!terminal || (waitFor === 'message' && message) };
+        };
+        const ready = () => {
+            const items = targets.map(read);
+            return input.mode === 'all'
+                ? items.every((item) => item.ready)
+                : items.some((item) => item.ready);
+        };
+        const duration = input.untilSettled
+            ? Number.MAX_SAFE_INTEGER
+            : (input.waitMs ?? (mode === 'model' ? 30000 : 0));
+        let outcome = 'snapshot';
+        if (duration !== 0)
+            outcome = await waitForToolCondition({
+                ready,
+                subscribe: (listener) => {
+                    const releases = [
+                        observations.wake.subscribe(listener),
+                        ...targets.map((target) => target.subscribe(listener))
+                    ];
+                    return () => {
+                        for (const release of releases)
+                            release();
+                    };
+                },
+                waitMs: mode === 'model' ? Math.max(10000, duration) : duration,
+                signal: call.signal,
+                ...(mode === 'model' ? { interrupt: call.waitInterrupt } : {})
+            });
+        call.signal.throwIfAborted();
+        const values = targets.map((item) => ({ item, ...read(item) }));
+        const selected = single
+            ? [
+                values.find((value) => value.ready) ??
+                    values.find((value) => value.observation) ??
+                    values[0]
+            ]
+            : values;
+        const receiptFacts = await Promise.all(selected.map(async ({ item }) => {
+            const identity = receiptIdentities[targets.indexOf(item)];
+            if (!identity)
+                return undefined;
+            const fact = await agent.sessionInputReceipt(item.session.id, identity);
+            return fact &&
+                (fact.executionId === item.executionId || fact.appliedExecutionId === item.executionId)
+                ? fact
+                : undefined;
+        }));
+        call.signal.throwIfAborted();
+        const agents = selected.map(({ item, observation, terminal, ready: isReady }, index) => {
+            const waitOutcome = outcome === 'snapshot'
+                ? 'snapshot'
+                : terminal
+                    ? 'completion'
+                    : isReady
+                        ? 'message'
+                        : outcome === 'interrupted'
+                            ? 'interrupted'
+                            : outcome === 'timeout'
+                                ? 'timeout'
+                                : 'snapshot';
+            const include = outcome !== 'snapshot' && (isReady || outcome === 'timeout' || outcome === 'interrupted');
+            const freshTerminal = include &&
+                terminal &&
+                item.executionId &&
+                (observations.claimTerminal(item.session.id, item.executionId) ||
+                    item.startedBeforeTerminal);
+            const progress = mode === 'native' && include && !terminal && observation
+                ? nativeChildSnapshot(item.snapshot())
+                : undefined;
+            const projection = freshTerminal
+                ? mode === 'native'
+                    ? nativeChildSnapshot(item.snapshot())
+                    : publicChildSnapshot(item.snapshot())
+                : progress
+                    ? {
+                        ...(progress.latestMessage ? { latestMessage: progress.latestMessage } : {}),
+                        ...(progress.latestActivity ? { latestActivity: progress.latestActivity } : {})
+                    }
+                    : {};
+            const updates = mode === 'model' &&
+                'summary' in projection &&
+                projection.summary &&
+                !projection.summaryTruncated
+                ? observation?.updates.filter((update) => !('final' in update && update.final))
+                : observation?.updates;
+            if (include)
+                observation?.acknowledge();
+            return {
+                agentId: item.session.id,
+                ...(item.executionId ? { executionId: item.executionId } : {}),
+                ...(mode === 'native' ? item.metadata : {}),
+                status: terminal?.status ?? 'running',
+                waitOutcome,
+                ...(terminal?.errorCode === undefined ? {} : { errorCode: terminal.errorCode }),
+                ...(terminal?.errorMessage === undefined ? {} : { errorMessage: terminal.errorMessage }),
+                ...(terminal?.permissionStop === undefined
+                    ? {}
+                    : { permissionStop: terminal.permissionStop }),
+                ...projection,
+                ...(receiptFacts[index] ? { receipt: receiptFacts[index] } : {}),
+                ...(include && updates?.length ? { updates } : {})
+            };
+        });
+        const groupOutcome = outcome === 'ready'
+            ? values.filter((value) => value.ready).every((value) => value.terminal)
+                ? 'completion'
+                : 'message'
+            : outcome;
+        const data = single
+            ? {
+                ...agents[0],
+                waitFor,
+                ...(groupOutcome === 'interrupted' ? { waitOutcome: 'interrupted', reason: 'steer' } : {})
+            }
+            : {
+                mode: input.mode ?? 'any',
+                waitFor,
+                waitOutcome: groupOutcome,
+                ...(groupOutcome === 'interrupted' ? { reason: 'steer' } : {}),
+                agents,
+                pendingAgentIds: values
+                    .filter((value) => !value.ready)
+                    .map((value) => value.item.session.id)
+            };
+        if (mode === 'native')
+            return { data, content: JSON.stringify(data) };
+        const modelAgents = agents.map((item) => modelWaitAgent(item, Math.floor(34000 / agents.length)));
+        const modelData = single
+            ? {
+                ...modelAgents[0],
+                waitFor,
+                ...(groupOutcome === 'interrupted' ? { waitOutcome: 'interrupted', reason: 'steer' } : {})
+            }
+            : { ...data, agents: modelAgents };
+        return { data, content: JSON.stringify(modelData) };
+    }
+    finally {
+        for (const item of targets)
+            item.close();
+    }
+}

package/dist/extensions/contracts.d.ts

@@ -3,7 +3,6 @@ import type { ExtensionPromptSection } from './prompt-composition.js';
 import type { ExtensionCapabilitySnapshot } from './capabilities.js';
 import type { ExtensionPromptComposition } from './prompt-composition.js';
 import type { ExtensionModelsApi } from './models.js';
-import type { ExtensionAgentsApi } from './agents.js';
 import type { ExtensionDataApi } from './data.js';
 import type { ExtensionMcpApi } from './mcp.js';
 import type { ExtensionFilesApi } from './files.js';
@@ -18,7 +17,6 @@ import type { ExtensionOperationContext } from './operation.js';
 import type { ExtensionDisposer, ExtensionResourceRegistration, ExtensionResourceScope } from './resources.js';
 import type { ExtensionServiceRegistry } from './services.js';
 import type { ExtensionToolRef, ExtensionToolInvocation, ExtensionToolCheck, ExtensionToolSpec } from './tools.js';
-import type { DomainAgentOperations, DomainAgentFacts } from './agents.js';
 import type { DomainCompactOperations, DomainCompactFacts } from './compaction.js';
 import type { DomainEnvironmentOperations, DomainEnvironmentFacts } from './environment.js';
 import type { DomainFileOperations, DomainFileFacts } from './files.js';
@@ -32,9 +30,9 @@ import type { DomainPromptInputOperations, DomainPromptInputFacts } from './prom
 import type { DomainSessionOperations, DomainSessionFacts } from './session-input.js';
 import type { DomainSettingsOperations, DomainSettingsFacts } from './settings.js';
 import type { DomainToolOperations, DomainToolFacts } from './tools.js';
-export interface ExtensionDomainOperations extends DomainAgentOperations, DomainCompactOperations, DomainEnvironmentOperations, DomainFileOperations, DomainMcpOperations, DomainModelRequestOperations, DomainModelStreamOperations, DomainNetworkOperations, DomainProcessOperations, DomainPromptCompositionOperations, DomainPromptInputOperations, DomainSessionOperations, DomainSettingsOperations, DomainToolOperations {
+export interface ExtensionDomainOperations extends DomainCompactOperations, DomainEnvironmentOperations, DomainFileOperations, DomainMcpOperations, DomainModelRequestOperations, DomainModelStreamOperations, DomainNetworkOperations, DomainProcessOperations, DomainPromptCompositionOperations, DomainPromptInputOperations, DomainSessionOperations, DomainSettingsOperations, DomainToolOperations {
 }
-export interface ExtensionDomainFacts extends DomainAgentFacts, DomainCompactFacts, DomainEnvironmentFacts, DomainFileFacts, DomainMcpFacts, DomainModelRequestFacts, DomainModelStreamFacts, DomainNetworkFacts, DomainProcessFacts, DomainPromptCompositionFacts, DomainPromptInputFacts, DomainSessionFacts, DomainSettingsFacts, DomainToolFacts {
+export interface ExtensionDomainFacts extends DomainCompactFacts, DomainEnvironmentFacts, DomainFileFacts, DomainMcpFacts, DomainModelRequestFacts, DomainModelStreamFacts, DomainNetworkFacts, DomainProcessFacts, DomainPromptCompositionFacts, DomainPromptInputFacts, DomainSessionFacts, DomainSettingsFacts, DomainToolFacts {
 }
 export interface ExtensionHookRegistrar {
     intercept<Key extends keyof ExtensionDomainOperations>(key: Key, handler: ExtensionInterceptor<ExtensionDomainOperations[Key]['input'], ExtensionDomainOperations[Key]['output']>, options?: ExtensionHookOptions): ExtensionResourceRegistration;
@@ -55,7 +53,6 @@ export interface AgentExtensionContext {
 }
 export interface SessionExtensionContext extends AgentExtensionContext {
     readonly mcp?: ExtensionMcpApi;
-    readonly agents?: ExtensionAgentsApi;
     readonly environment?: ExtensionEnvironmentApi;
     readonly settings?: ExtensionSettingsApi;
     readonly processes?: ExtensionProcessesApi;

package/dist/extensions/manager.d.ts

@@ -7,7 +7,6 @@ import type { ExtensionModelsBackend } from './models.js';
 import type { ExtensionCheckpointBackend, ExtensionStoreBackend } from './data.js';
 import type { ExtensionSessionBackend } from './session-input.js';
 import type { AgentHostExtensionPorts } from './host-ports.js';
-import { type ExtensionAgentsBackend } from './agents.js';
 export interface ExtensionManagerOptions {
     readonly toolRuntime: ExtensionToolRuntime;
     readonly hostPorts?: AgentHostExtensionPorts;
@@ -19,7 +18,6 @@ export interface ExtensionManagerOptions {
     readonly checkpoint?: ExtensionCheckpointBackend;
     readonly store?: ExtensionStoreBackend;
     readonly sessionBackend?: (sessionId: string) => ExtensionSessionBackend | undefined;
-    readonly agentsBackend?: (sessionId: string) => ExtensionAgentsBackend | undefined;
     readonly allowTool?: (sessionId: string, name: string, definition?: ExtensionToolBinding['definition']) => boolean;
     readonly scheduleTool?: (sessionId: string) => ExtensionSession['scheduleTool'];
 }

package/dist/extensions/manager.js

@@ -4,7 +4,6 @@ import { ExtensionResourceScope } from './resources.js';
 import { ExtensionServices } from './services.js';
 import { ExtensionSession } from './session.js';
 import { coreSettingsBinding, settingsCapabilities } from './settings.js';
-import { agentCapabilities } from './agents.js';
 /** Agent admission coordinates a single composition generation, never parallel replacement loops. */
 export class ExtensionManager {
     options;
@@ -109,7 +108,7 @@ export class ExtensionManager {
                 throw new AgentError('MAR_AGENT_EXTENSION_COMPOSITION_FAILED', 'Required extension initialization failed.');
             let session = this.#sessions.get(sessionId);
             if (!session) {
-                session = new ExtensionSession(this.options.toolRuntime, sessionId, this.#epochs.get(sessionId) ?? 0, this.#agentServices, this.operations, agentCapabilities(this.capabilities, this.options.agentsBackend?.(sessionId) !== undefined), (diagnostic) => this.#diagnose(diagnostic), (context) => this.options.baseTools?.(sessionId, context) ?? [], this.options.models, this.options.checkpoint, this.options.sessionBackend?.(sessionId), this.options.hostPorts, this.options.agentsBackend?.(sessionId), (name, definition) => this.options.allowTool?.(sessionId, name, definition) ?? true, this.options.scheduleTool?.(sessionId), this.options.store);
+                session = new ExtensionSession(this.options.toolRuntime, sessionId, this.#epochs.get(sessionId) ?? 0, this.#agentServices, this.operations, this.capabilities, (diagnostic) => this.#diagnose(diagnostic), (context) => this.options.baseTools?.(sessionId, context) ?? [], this.options.models, this.options.checkpoint, this.options.sessionBackend?.(sessionId), this.options.hostPorts, (name, definition) => this.options.allowTool?.(sessionId, name, definition) ?? true, this.options.scheduleTool?.(sessionId), this.options.store);
                 this.#sessions.set(sessionId, session);
                 try {
                     await this.#attach(session, loadingSignal, baseTools);

package/dist/extensions/models.d.ts

@@ -13,6 +13,9 @@ export interface ExtensionModelDescription {
     readonly maxOutputTokens: number;
     readonly inputCapabilities: readonly string[];
     readonly reasoningEfforts: readonly AgentReasoningEffort[];
+    readonly defaultReasoningEffort: AgentReasoningEffort;
+    readonly conversationModel: boolean;
+    readonly subagentModel: boolean;
     readonly isDefault: boolean;
 }
 export type ExtensionModelTextBlock = ModelTextBlock;

package/dist/extensions/operation.d.ts

@@ -10,6 +10,14 @@ export interface ExtensionOperationContext {
     /** Correlation with the actual enclosing tool call; not an authority token. */
     readonly toolCallId?: string;
     readonly parentToolCallId?: string;
+    /** Wakes a foreground tool wait when its Execution receives a steering input. */
+    readonly waitInterrupt?: import('../runtime/wait.js').ToolWaitInterrupt;
+    /** Present only for the exact tool invocation explicitly approved by the Host. */
+    readonly permission?: Readonly<{
+        readonly decision: 'approved';
+    }>;
+    /** Effective execution permission mode, when the invocation has an execution owner. */
+    readonly permissionMode?: import('../tools/permission-contract.js').PermissionMode;
     readonly actor: 'model' | 'sdk' | 'extension' | 'code-mode';
     readonly entry: 'direct' | 'programmatic' | 'native-api';
     readonly signal: AbortSignal;

package/dist/extensions/operation.js

@@ -59,6 +59,9 @@ export class ExtensionOperations {
                     ...((identity.parentToolCallId ?? parent.parentToolCallId) === undefined
                         ? {}
                         : { parentToolCallId: identity.parentToolCallId ?? parent.parentToolCallId }),
+                    ...((identity.waitInterrupt ?? parent.waitInterrupt) === undefined
+                        ? {}
+                        : { waitInterrupt: identity.waitInterrupt ?? parent.waitInterrupt }),
                     entry: parent.entry,
                     signal: AbortSignal.any([identity.signal, parent.signal])
                 }

package/dist/extensions/services.d.ts

@@ -1,9 +1,16 @@
 import type { ExtensionResourceScope } from './resources.js';
+import type { ExtensionOperationRunner } from './operation.js';
+export interface ExtensionServiceConsumer {
+    readonly run: ExtensionOperationRunner;
+    readonly onDispose: (dispose: () => void | Promise<void>) => void;
+}
 export interface ExtensionServiceKey<T> {
     readonly id: string;
     readonly scope: 'agent' | 'session';
     /** Compile-time service contract; never examined at runtime. */
     readonly contract?: (implementation: T) => T;
+    /** Bind a service to the framework-owned consuming Session scope. */
+    readonly bindConsumer?: (implementation: T, consumer: ExtensionServiceConsumer) => T;
 }
 export interface ExtensionServiceRegistry {
     provide<T>(key: ExtensionServiceKey<T>, implementation: T): void;
@@ -23,9 +30,10 @@ export declare class ExtensionServices {
         readonly id: string;
         readonly scope: 'agent' | 'session';
     }): boolean;
+    resolve<T>(key: ExtensionServiceKey<T>): T | undefined;
     hasOwned(key: {
         readonly id: string;
         readonly scope: 'agent' | 'session';
     }, owner: ExtensionResourceScope): boolean;
-    bind(owner: ExtensionResourceScope): ExtensionServiceRegistry;
+    bind(owner: ExtensionResourceScope, run?: ExtensionOperationRunner): ExtensionServiceRegistry;
 }

package/dist/extensions/services.js

@@ -11,16 +11,30 @@ export class ExtensionServices {
     has(key) {
         return this.#find(key) !== undefined;
     }
+    resolve(key) {
+        return this.#find(key)?.value;
+    }
     hasOwned(key, owner) {
         return (key.scope === this.scope &&
             (this.#entries.get(key.id)?.some((entry) => entry.owner === owner) ?? false));
     }
-    bind(owner) {
+    bind(owner, run) {
         const consume = (key, options) => {
             const entry = this.#find(key);
             if (!entry && !options?.optional)
                 throw new AgentError('MAR_AGENT_EXTENSION_DEPENDENCY_MISSING', 'Required service is unavailable.');
-            return entry?.value;
+            if (!entry)
+                return undefined;
+            if (!entry.bindConsumer)
+                return entry.value;
+            if (!run)
+                throw new AgentError('MAR_AGENT_EXTENSION_SERVICE_SCOPE', 'Service requires a Session consumer.');
+            return entry.bindConsumer(entry.value, {
+                run,
+                onDispose: (dispose) => {
+                    owner.effect(() => dispose);
+                }
+            });
         };
         const publish = (key, value, replace) => {
             if (key.scope !== this.scope)
@@ -32,7 +46,16 @@ export class ExtensionServices {
                 throw new AgentError('MAR_AGENT_EXTENSION_SERVICE_CONFLICT', 'Service is already provided.');
             if (!entries.length && replace)
                 throw new AgentError('MAR_AGENT_EXTENSION_DEPENDENCY_MISSING', 'Service replacement has no lower provider.');
-            const entry = { value, owner };
+            const binder = key.bindConsumer;
+            const entry = {
+                value,
+                owner,
+                ...(binder
+                    ? {
+                        bindConsumer: (implementation, consumer) => binder(implementation, consumer)
+                    }
+                    : {})
+            };
             owner.effect(() => () => {
                 const index = entries.indexOf(entry);
                 if (index !== -1)

package/dist/extensions/session-context.d.ts

@@ -0,0 +1,18 @@
+import type { ExtensionServiceKey } from './services.js';
+/** Context proposed by a Session-scoped extension, confirmed only after durable submission. */
+export interface ExtensionSessionContextItem {
+    readonly content: string;
+    /** Synchronously confirm only the version captured by collect, not later observations. */
+    acknowledge(): void;
+}
+export interface ExtensionSessionContextProvider {
+    collect(signal: AbortSignal): readonly ExtensionSessionContextItem[] | Promise<readonly ExtensionSessionContextItem[]>;
+    /** Bounded resource summary for normal and compact context reconstruction; consumes no updates. */
+    resources?(signal: AbortSignal): readonly string[] | Promise<readonly string[]>;
+    /** Wakes an active wait when unread model-visible context becomes available. */
+    readonly wake?: {
+        pending(): boolean;
+        subscribe(listener: () => void): () => void;
+    };
+}
+export declare const SESSION_CONTEXT_PROVIDER: ExtensionServiceKey<ExtensionSessionContextProvider>;

package/dist/extensions/session-context.js

@@ -0,0 +1,4 @@
+export const SESSION_CONTEXT_PROVIDER = {
+    id: 'core.session-context-provider',
+    scope: 'session'
+};