@myagentroam/agent 0.11.33 → 0.11.34

package/dist/sdk/execution-input.js

@@ -0,0 +1,266 @@
+import { AgentError } from '../error.js';
+import { recordSessionInputCommit } from '../extensions/session-input.js';
+import { inputMetadataFromRecord } from '../session/record-projection.js';
+import { AGENT_EXECUTION_POLICY } from '../runtime/execution-policy.js';
+import { publishModelResources } from '../runtime/resource-publication.js';
+import { extensionInputSource } from './extension-session-launch.js';
+import { renderSubagentUpdate } from '../subagent/model-update.js';
+/** Owns committed input, mailbox admission and live projection for one Execution. */
+export function createExecutionInput(input) {
+    const { host, store, sessionId, executionId, turnId, mode, controller, inputs, messages, pendingInputs, messageSources, modelContext, model, tokens, setSmartInput, withRecordProjection, appendExtensionMessage, startCompact, compactContext } = input;
+    const sessionSource = { type: input.source };
+    const writeInputRecord = async (content, type, metadata, call, commitEvidence, projectCommitted) => {
+        call.signal.throwIfAborted();
+        if (content.images?.length && !model().inputCapabilities.includes('IMAGE'))
+            throw new AgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'Selected model does not support image input.');
+        await withRecordProjection(async () => {
+            call.signal.throwIfAborted();
+            const smartPercent = tokens() === undefined ? undefined : (tokens() * 100) / model().contextWindowTokens;
+            const smartCompaction = mode !== 'compact' &&
+                sessionSource.type === 'user' &&
+                type === 'turn.user' &&
+                metadata.inputSource === undefined &&
+                smartPercent !== undefined &&
+                smartPercent >= AGENT_EXECUTION_POLICY.smartCompactionPercent &&
+                smartPercent < AGENT_EXECUTION_POLICY.automaticCompactionPercent;
+            const modelImages = await publishModelResources(host, content.images, {
+                sessionId,
+                executionId
+            }, store);
+            const actualContent = modelImages === content.images
+                ? content
+                : {
+                    ...content,
+                    ...(modelImages === undefined ? {} : { images: modelImages })
+                };
+            const images = modelImages?.length
+                ? await store.persistInputImages(sessionId, modelImages)
+                : [];
+            const record = await store.append(sessionId, {
+                type,
+                payload: {
+                    ...metadata,
+                    prompt: content.text,
+                    ...(smartCompaction ? { smartCompaction: true } : {}),
+                    ...(content.modelText === undefined ? {} : { modelText: content.modelText }),
+                    ...(content.context === undefined ? {} : { context: content.context }),
+                    ...(content.modelContext === undefined ? {} : { modelContext: content.modelContext }),
+                    ...(images.length ? { images } : {})
+                },
+                executionId,
+                turnId
+            }, { signal: call.signal });
+            commitEvidence(record.recordId);
+            const inputMetadata = inputMetadataFromRecord(record);
+            setSmartInput({
+                recordId: record.recordId,
+                eligible: smartCompaction,
+                requested: false
+            });
+            modelContext.rememberInput({
+                content: content.modelText ?? content.text,
+                metadata: inputMetadata
+            });
+            projectCommitted(actualContent, record.recordId, inputMetadata);
+            for (const text of content.modelContext ?? content.context ?? [])
+                messages.push({ role: 'user', content: text, contextKind: 'contextual' });
+        });
+    };
+    const appendMailboxMessages = async (restoring = false) => inputs.drain(async (entry, request, call) => {
+        call.signal.throwIfAborted();
+        if (request.kind === 'compact') {
+            if (request.input.async) {
+                const flight = startCompact()(request.input);
+                entry.start();
+                return { changed: await flight.result, executionId };
+            }
+            return { changed: await compactContext()(request.input), executionId };
+        }
+        if (request.kind === 'append') {
+            const result = await appendExtensionMessage(entry, request, call);
+            return { ...result, executionId };
+        }
+        if (entry.nativeSteer?.recordId) {
+            const received = pendingInputs.get(entry.nativeSteer.recordId);
+            if (!received)
+                return { changed: false, modelChanged: false };
+            return withRecordProjection(async () => {
+                call.signal.throwIfAborted();
+                const payload = received.payload;
+                const images = await store.readInputImages(sessionId, payload.images);
+                if (images.length && !model().inputCapabilities.includes('IMAGE'))
+                    throw new AgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'Selected model does not support image input.');
+                const percent = tokens() === undefined ? undefined : (tokens() * 100) / model().contextWindowTokens;
+                const eligible = sessionSource.type === 'user' &&
+                    percent !== undefined &&
+                    percent >= AGENT_EXECUTION_POLICY.smartCompactionPercent &&
+                    percent < AGENT_EXECUTION_POLICY.automaticCompactionPercent;
+                const actual = {
+                    ...payload,
+                    ...(eligible ? { smartCompaction: true } : {})
+                };
+                const content = (actual.modelText ?? actual.prompt);
+                const applied = await store.append(sessionId, {
+                    type: 'model.context',
+                    payload: {
+                        role: 'user',
+                        content,
+                        inputRef: received.recordId,
+                        input: actual
+                    },
+                    executionId,
+                    turnId
+                }, { signal: call.signal });
+                const outcome = {
+                    changed: true,
+                    modelChanged: true,
+                    executionId,
+                    recordId: received.recordId
+                };
+                recordSessionInputCommit(entry, outcome);
+                pendingInputs.delete(received.recordId);
+                const metadata = inputMetadataFromRecord({ ...received, payload: actual });
+                const message = {
+                    role: 'user',
+                    content,
+                    metadata,
+                    ...(images.length ? { images } : {})
+                };
+                messages.push(message);
+                messageSources.set(message, applied);
+                modelContext.rememberInput({ content, metadata });
+                setSmartInput({ recordId: received.recordId, eligible, requested: false });
+                for (const text of (payload.modelContext ?? payload.context ?? []))
+                    messages.push({ role: 'user', content: text, contextKind: 'contextual' });
+                return outcome;
+            });
+        }
+        const parent = entry.parentMessage;
+        let outcome;
+        const content = {
+            text: request.input.text,
+            ...(request.input.modelText === undefined ? {} : { modelText: request.input.modelText }),
+            ...(request.input.context === undefined ? {} : { context: request.input.context }),
+            ...(request.input.modelContext === undefined
+                ? {}
+                : { modelContext: request.input.modelContext }),
+            ...(request.input.images === undefined ? {} : { images: request.input.images })
+        };
+        await writeInputRecord(content, parent && !parent.delivery?.origin ? 'turn.user' : 'extension.input', parent && !parent.delivery?.origin
+            ? {
+                inputSource: 'parent_agent',
+                ...(parent.delivery ? { messageId: parent.delivery.messageId } : {})
+            }
+            : {
+                source: extensionInputSource(call, request.input.provenance, request.input.modelAttribution),
+                ...(parent?.delivery ? { messageId: parent.delivery.messageId } : {})
+            }, call, (recordId) => {
+            outcome = { changed: true, executionId, recordId };
+            recordSessionInputCommit(entry, outcome);
+        }, (actual, recordId, metadata) => {
+            messages.push({
+                role: 'user',
+                content: actual.modelText ?? actual.text,
+                metadata,
+                ...(actual.images?.length
+                    ? {
+                        images: actual.images.map((image) => ({ ...image }))
+                    }
+                    : {})
+            });
+            parent?.delivery?.applied();
+        });
+        return outcome;
+    }, {
+        executionId,
+        turnId,
+        signal: controller.signal,
+        ...(restoring ? { restoring: true } : {})
+    }, inputs.boundarySize);
+    const startInitialInput = async (ports) => {
+        if (pendingInputs.size)
+            await appendMailboxMessages(true);
+        let entered = false;
+        const write = async (content, call) => {
+            call.signal.throwIfAborted();
+            if ((content.images?.length || ports.restoredImages) &&
+                !model().inputCapabilities.includes('IMAGE'))
+                throw new AgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'Selected model does not support image input.');
+            if (entered) {
+                await ports.enqueue(content, call);
+                return {};
+            }
+            await modelContext.recordEnvironment();
+            call.signal.throwIfAborted();
+            const { internal, input: request } = ports;
+            await writeInputRecord(content, internal.inputSource === 'extension' ? 'extension.input' : 'turn.user', {
+                ...(internal.extensionSource ? { source: internal.extensionSource } : {}),
+                ...(internal.delivery ? { messageId: internal.delivery.messageId } : {}),
+                ...(internal.inputSource === undefined ? {} : { inputSource: internal.inputSource }),
+                ...(request.clientMessageId ? { clientMessageId: request.clientMessageId } : {})
+            }, call, (recordId) => {
+                entered = true;
+                internal.inputCommitted?.(recordId);
+            }, (actual, _recordId, metadata) => {
+                ports.project(actual, metadata);
+                internal.delivery?.applied();
+            });
+            return {};
+        };
+        const { input: request, internal } = ports;
+        const content = {
+            text: request.prompt,
+            ...(internal.modelText === undefined ? {} : { modelText: internal.modelText }),
+            ...(internal.inputContext === undefined ? {} : { context: internal.inputContext }),
+            ...(internal.modelContext === undefined ? {} : { modelContext: internal.modelContext }),
+            ...(request.images === undefined ? {} : { images: request.images })
+        };
+        await ports.operation((call) => internal.promptAdmitted ? write(content, call) : ports.admit(content, call, write));
+        return entered;
+    };
+    const receiveSteer = (content, clientMessageId, call) => withRecordProjection(async () => {
+        call.signal.throwIfAborted();
+        if (content.images?.length && !model().inputCapabilities.includes('IMAGE'))
+            throw new AgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'Selected model does not support image input.');
+        const modelImages = await publishModelResources(host, content.images, { sessionId, executionId }, store);
+        const images = modelImages?.length
+            ? await store.persistInputImages(sessionId, modelImages)
+            : [];
+        const record = await store.append(sessionId, {
+            type: 'turn.user',
+            payload: {
+                deferred: true,
+                prompt: content.text,
+                ...(content.modelText === undefined ? {} : { modelText: content.modelText }),
+                ...(content.context === undefined ? {} : { context: content.context }),
+                ...(content.modelContext === undefined ? {} : { modelContext: content.modelContext }),
+                clientMessageId,
+                ...(images.length ? { images } : {})
+            },
+            executionId,
+            turnId
+        }, { signal: call.signal });
+        pendingInputs.set(record.recordId, record);
+        return record;
+    });
+    const appendSubagentUpdates = async (subagents) => {
+        if (!subagents)
+            return;
+        await withRecordProjection(async () => {
+            controller.signal.throwIfAborted();
+            for (const update of subagents.collectModelUpdates()) {
+                controller.signal.throwIfAborted();
+                const message = {
+                    role: 'user',
+                    content: renderSubagentUpdate(update.snapshot, update.truncated),
+                    contextKind: 'contextual'
+                };
+                const stored = await store.append(sessionId, { type: 'model.context', payload: message, executionId, turnId }, { signal: controller.signal });
+                messages.push(message);
+                messageSources.set(message, stored);
+                update.acknowledge();
+            }
+        });
+    };
+    return { startInitialInput, receiveSteer, appendSubagentUpdates, appendMailboxMessages };
+}

package/dist/sdk/execution-model-context.d.ts

@@ -0,0 +1,52 @@
+import { restoreMessages } from '../runtime/context/restore.js';
+import { type ContextualWorldState } from '../runtime/context/world-state.js';
+import type { EnvironmentContextState } from '../prompts/core.js';
+import { type buildCompactedHistory } from '../runtime/compaction/history.js';
+import type { CompactUserInput, SessionRecord } from '../session/record-contract.js';
+import type { SessionStore } from '../session/store/contracts.js';
+import type { SessionModelMessage as ModelMessage } from '../session/model-request.js';
+import type { ContextGcCommitResult } from '../runtime/context/gc-runtime.js';
+import type { ResourceInputProjection } from './resource-input.js';
+interface ExecutionModelContextPorts {
+    readonly restored: Awaited<ReturnType<typeof restoreMessages>>;
+    readonly initialContextualWorldState: ContextualWorldState;
+    readonly store: Parameters<typeof restoreMessages>[0] & Pick<SessionStore, 'append' | 'writeContextualWorldState'>;
+    readonly sessionId: string;
+    readonly executionId: string;
+    readonly turnId: string;
+    readonly mode: 'run' | 'plan' | 'compact';
+    readonly contextRecords: readonly SessionRecord[];
+    readonly contextualWorldStateGeneration: string | undefined;
+    readonly compactMayContainAgentInstructions: boolean;
+    readonly messageSources: WeakMap<ModelMessage, SessionRecord>;
+    updateWorldState(state: ContextualWorldState): void;
+    environment(): EnvironmentContextState;
+    instructionSnapshot(): string | undefined;
+    renderInstructions(previous: boolean): string | undefined;
+    retainedResourceSnapshot(): Promise<string | undefined>;
+    mcpNavigation(): string | undefined;
+    reportSidecarFailure(): void;
+    resetGc(): void;
+    restoreMcp(): void;
+    resetContinuation(): void;
+    resetSmartContext(): void;
+    replaceResources(messages: ModelMessage[]): void;
+    adoptGcResources(state: Parameters<ResourceInputProjection['adoptGc']>[0]): void;
+    clearAppendedMessages(): void;
+    appendedAfter(boundary: number, restoredIds: ReadonlySet<string>): ModelMessage[];
+}
+/** Execution-owned live history and projections derived from committed Session records. */
+export declare function createExecutionModelContext(ports: ExecutionModelContextPorts): {
+    messages: ModelMessage[];
+    readonly worldState: ContextualWorldState;
+    commitWorldState: (next: ContextualWorldState) => Promise<void>;
+    recordEnvironment: () => Promise<void>;
+    syncMcpWorldState: (index?: number) => Promise<void>;
+    rememberInput(input: CompactUserInput): void;
+    compactInputs(prefix: readonly ModelMessage[]): CompactUserInput[];
+    initializeWorldState(): Promise<void>;
+    replaceCompactMessages(replacementHistory: ReturnType<typeof buildCompactedHistory>, retainedModelContext: readonly ModelMessage[]): void;
+    adoptCompactCheckpoint(recordId: string, replacementHistory: ReturnType<typeof buildCompactedHistory>, retainedModelContext: readonly ModelMessage[], resources: string | undefined): Promise<void>;
+    adoptGcCheckpoint(committed: ContextGcCommitResult, appendBoundary: number): Promise<void>;
+};
+export {};

package/dist/sdk/execution-model-context.js

@@ -0,0 +1,156 @@
+import { isDeepStrictEqual } from 'node:util';
+import { restoreMessages } from '../runtime/context/restore.js';
+import { contextualInstructionInsertIndex, latestContextualWorldStateGeneration, persistContextualWorldState, resetContextualWorldState, updateContextualWorldState } from '../runtime/context/world-state.js';
+import { environmentContextUpdate } from '../runtime/context/environment.js';
+import { compactedHistoryMessages } from '../runtime/compaction/history.js';
+import { compactSummaryFromCheckpoint } from '../session/record-projection.js';
+/** Execution-owned live history and projections derived from committed Session records. */
+export function createExecutionModelContext(ports) {
+    const { restored, initialContextualWorldState, store, sessionId, executionId, turnId, mode, contextRecords, contextualWorldStateGeneration, compactMayContainAgentInstructions, messageSources } = ports;
+    const messages = restored.messages;
+    let userMessages = [...restored.userMessages];
+    let recordedEnvironment = restored.environmentState;
+    let instructionInsertIndex = 0;
+    let worldState = initialContextualWorldState;
+    const commitWorldState = async (next) => {
+        await persistContextualWorldState(store, sessionId, next);
+        worldState = next;
+        ports.updateWorldState(next);
+    };
+    const resetCompactWorldState = async (generation, committed) => {
+        instructionInsertIndex = contextualInstructionInsertIndex(messages);
+        const next = resetContextualWorldState(generation, instructionInsertIndex, {
+            instructionSnapshot: ports.instructionSnapshot(),
+            instructionContent: ports.renderInstructions(true),
+            resourceSnapshot: committed ? committed.resources : await ports.retainedResourceSnapshot()
+        });
+        if (!committed)
+            await commitWorldState(next);
+        else {
+            // The checkpoint is authoritative; its sidecar is recoverable on restart.
+            worldState = next;
+            ports.updateWorldState(next);
+            try {
+                await persistContextualWorldState(store, sessionId, next);
+            }
+            catch {
+                ports.reportSidecarFailure();
+            }
+        }
+    };
+    const recordEnvironment = async () => {
+        const message = environmentContextUpdate(ports.environment(), recordedEnvironment);
+        if (!message)
+            return;
+        await store.append(sessionId, {
+            type: 'context.environment',
+            payload: { version: 1, state: ports.environment() },
+            executionId,
+            turnId
+        });
+        messages.push(message);
+        recordedEnvironment = ports.environment();
+    };
+    const syncMcpWorldState = async (index = instructionInsertIndex) => {
+        const snapshot = ports.mcpNavigation();
+        if (worldState.mcpSnapshot === snapshot)
+            return;
+        const next = {
+            ...worldState,
+            mcpSnapshot: snapshot,
+            entries: [
+                ...worldState.entries,
+                {
+                    index,
+                    kind: 'mcp',
+                    content: snapshot ?? '<mcp_catalog>No deferred MCP tools remain.</mcp_catalog>'
+                }
+            ]
+        };
+        await commitWorldState(next);
+    };
+    return {
+        messages,
+        get worldState() {
+            return worldState;
+        },
+        commitWorldState,
+        recordEnvironment,
+        syncMcpWorldState,
+        rememberInput(input) {
+            userMessages.push(input);
+        },
+        compactInputs(prefix) {
+            return userMessages.filter((entry) => prefix.some((message) => message.role === 'user' &&
+                message.contextKind === undefined &&
+                (entry.metadata?.recordId
+                    ? message.metadata?.recordId === entry.metadata.recordId
+                    : message.content === entry.content)));
+        },
+        async initializeWorldState() {
+            instructionInsertIndex =
+                mode === 'compact' ? contextualInstructionInsertIndex(messages) : messages.length;
+            // Only the latest Compact may rebuild missing sidecar resources, never a GC boundary.
+            if (!worldState.initialized &&
+                contextRecords.some((record) => record.recordId === contextualWorldStateGeneration &&
+                    compactSummaryFromCheckpoint(record) !== undefined))
+                await resetCompactWorldState(contextualWorldStateGeneration);
+            const nextInstructionWorldState = updateContextualWorldState(worldState, instructionInsertIndex, {
+                instructionSnapshot: ports.instructionSnapshot(),
+                instructionContent: ports.renderInstructions(compactMayContainAgentInstructions || worldState.instructionSnapshot !== undefined)
+            });
+            if (!isDeepStrictEqual(worldState, nextInstructionWorldState))
+                await commitWorldState(nextInstructionWorldState);
+        },
+        // Must run inside the existing writer/projection commit window.
+        replaceCompactMessages(replacementHistory, retainedModelContext) {
+            messages.splice(0, messages.length, environmentContextUpdate(ports.environment()), ...compactedHistoryMessages(replacementHistory), ...retainedModelContext);
+            ports.clearAppendedMessages();
+            ports.replaceResources(messages);
+            ports.resetContinuation();
+        },
+        // Derived state follows the committed splice, never delays it past the writer window.
+        async adoptCompactCheckpoint(recordId, replacementHistory, retainedModelContext, resources) {
+            ports.resetGc();
+            ports.restoreMcp();
+            recordedEnvironment = ports.environment();
+            userMessages = replacementHistory
+                .filter((message) => message.kind !== 'summary')
+                .map((message) => ({
+                content: message.content,
+                ...(message.metadata ? { metadata: { ...message.metadata } } : {})
+            }));
+            userMessages.push(...retainedModelContext
+                .filter((message) => message.role === 'user' && message.contextKind === undefined)
+                .map((message) => ({
+                content: message.content,
+                ...(message.metadata ? { metadata: message.metadata } : {})
+            })));
+            await resetCompactWorldState(recordId, { resources });
+        },
+        async adoptGcCheckpoint(committed, appendBoundary) {
+            ports.resetSmartContext();
+            ports.resetContinuation();
+            const refreshed = await restoreMessages(store, sessionId, committed.records, {
+                includeImages: true,
+                currentTurnId: turnId,
+                messageSources,
+                projection: committed.projection
+            });
+            const restoredIds = new Set(committed.records.map((record) => record.recordId));
+            const lateMessages = ports.appendedAfter(appendBoundary, restoredIds);
+            messages.splice(0, messages.length, ...refreshed.messages, ...lateMessages);
+            ports.replaceResources(messages);
+            ports.adoptGcResources(committed.projection.checkpoint?.inlineMedia?.state);
+            ports.restoreMcp();
+            recordedEnvironment = refreshed.environmentState;
+            userMessages = [...refreshed.userMessages];
+            instructionInsertIndex = contextualInstructionInsertIndex(messages);
+            const next = resetContextualWorldState(latestContextualWorldStateGeneration(committed.records), instructionInsertIndex, {
+                instructionSnapshot: ports.instructionSnapshot(),
+                instructionContent: ports.renderInstructions(committed.records.some((record) => compactSummaryFromCheckpoint(record) !== undefined))
+            });
+            await commitWorldState(next);
+        }
+    };
+}

package/dist/sdk/execution-model-lifecycle.d.ts

@@ -0,0 +1,39 @@
+import type { ModelEvent, ModelTurnSession } from '../model/contracts.js';
+import type { SessionModelMessage, SessionModelRequest } from '../session/model-request.js';
+import type { SessionRuntime } from './session-runtime.js';
+import type { ResourceInputProjection } from './resource-input.js';
+import type { AuthoritativeModelUsage } from '../runtime/context/usage.js';
+/** Owns request publication, continuation accounting and provider usage for one Execution. */
+export declare class ExecutionModelLifecycle {
+    private readonly ports;
+    private dispatchedInputs;
+    private dispatchedLocal;
+    private readonly completedMedia;
+    private contextTokens;
+    private smartTokens;
+    private lastUsage;
+    constructor(ports: {
+        modelId: string;
+        contextWindowTokens: number;
+        signal: AbortSignal;
+        messages: SessionModelMessage[];
+        turn: ModelTurnSession;
+        runtime: Pick<SessionRuntime, 'recordRequest' | 'completeRequest'>;
+        resources: Pick<ResourceInputProjection, 'complete'>;
+        stream(start: (signal: AbortSignal) => AsyncIterable<ModelEvent>, signal: AbortSignal): AsyncIterable<ModelEvent>;
+        compactPending(): boolean;
+        startCompact(): void;
+        updateBoundary(value: number): void;
+        initialUsage: AuthoritativeModelUsage | undefined;
+        initialSmartTokens: number | undefined;
+    });
+    get tokens(): number | undefined;
+    get smartContextTokens(): number | undefined;
+    get usage(): AuthoritativeModelUsage | undefined;
+    resetSmart(): void;
+    invalidate(): void;
+    start(request: SessionModelRequest): AsyncIterable<ModelEvent>;
+    afterModel(closedPrefixLength: number, request: SessionModelRequest | undefined): Promise<void>;
+    observeTokens(tokens: number): void;
+    observeUsage(usage: Omit<AuthoritativeModelUsage, 'historyMessages'> | undefined): void;
+}

package/dist/sdk/execution-model-lifecycle.js

@@ -0,0 +1,73 @@
+import { AGENT_EXECUTION_POLICY } from '../runtime/execution-policy.js';
+/** Owns request publication, continuation accounting and provider usage for one Execution. */
+export class ExecutionModelLifecycle {
+    ports;
+    dispatchedInputs = 0;
+    dispatchedLocal = 0;
+    completedMedia = new WeakSet();
+    contextTokens;
+    smartTokens;
+    lastUsage;
+    constructor(ports) {
+        this.ports = ports;
+        this.lastUsage = ports.initialUsage;
+        this.contextTokens = ports.initialUsage?.contextInputTokens;
+        this.smartTokens = ports.initialSmartTokens;
+    }
+    get tokens() {
+        return this.contextTokens;
+    }
+    get smartContextTokens() {
+        return this.smartTokens;
+    }
+    get usage() {
+        return this.lastUsage;
+    }
+    resetSmart() {
+        this.smartTokens = undefined;
+    }
+    invalidate() {
+        this.contextTokens = undefined;
+        this.smartTokens = undefined;
+        this.lastUsage = undefined;
+    }
+    async *start(request) {
+        const snapshot = this.ports.runtime.recordRequest(this.ports.modelId, request);
+        this.dispatchedInputs = request.messages.length;
+        this.dispatchedLocal = this.ports.messages.length;
+        const ports = this.ports;
+        const completed = this.completedMedia;
+        yield* ports.stream(async function* (signal) {
+            for await (const event of ports.turn.start(request, signal)) {
+                if (event.type === 'completed' && event.reason !== 'cancelled') {
+                    completed.add(request.messages);
+                    ports.runtime.completeRequest(snapshot);
+                }
+                yield event;
+            }
+        }, ports.signal);
+    }
+    async afterModel(closedPrefixLength, request) {
+        this.ports.turn.commitContinuationInput?.(this.dispatchedInputs + this.ports.messages.length - this.dispatchedLocal);
+        if (request && this.completedMedia.has(request.messages)) {
+            await this.ports.resources.complete(request);
+            this.ports.updateBoundary(closedPrefixLength);
+        }
+        if (this.contextTokens !== undefined &&
+            (this.contextTokens * 100) / this.ports.contextWindowTokens >=
+                AGENT_EXECUTION_POLICY.backgroundCompactionPercent &&
+            !this.ports.compactPending())
+            this.ports.startCompact();
+    }
+    observeTokens(tokens) {
+        this.contextTokens = tokens;
+        this.smartTokens = tokens;
+    }
+    observeUsage(usage) {
+        if (usage !== undefined) {
+            this.contextTokens = usage.contextInputTokens;
+            this.smartTokens = usage.contextInputTokens;
+            this.lastUsage = { ...usage, historyMessages: [...this.ports.messages] };
+        }
+    }
+}

package/dist/sdk/execution-model-request.d.ts

@@ -0,0 +1,40 @@
+import type { ExtensionSession } from '../extensions/session.js';
+import type { ExtensionOperationContext } from '../extensions/operation.js';
+import type { SessionModelRequest } from '../session/model-request.js';
+import type { ModelTurnSession } from '../model/contracts.js';
+import type { AgentHost } from '../host/contracts.js';
+import type { ModelRequestUsage } from '../model/usage-observer.js';
+/** Captures Extension rewrites against immutable tool bindings and attributes model usage. */
+export declare function createExecutionModelRequest(ports: {
+    readonly sessionId: string;
+    readonly executionId: string;
+    readonly modelId: string;
+    readonly source: 'user' | 'subagent';
+    readonly compact: boolean;
+    readonly autoPermission: boolean;
+    readonly turn: ModelTurnSession;
+    readonly hooks: Pick<ExtensionSession['hooks'], 'hasInterceptors' | 'invoke'>;
+    readonly host: Pick<AgentHost, 'modelUsage'>;
+    capture(): ReturnType<ExtensionSession['capture']>;
+    operation<T>(run: (call: ExtensionOperationContext) => T): T;
+    usageFailed(): void;
+}): (candidate: SessionModelRequest, bindings?: ReadonlyMap<string, import("../extensions/tools.js").ExtensionToolBinding>, modelId?: string, purpose?: "conversation" | "compact") => Promise<{
+    onModelUsage?: (usage: import("../model/usage.js").ModelRequestUsage) => Promise<void> | void;
+    onModelUsageFailure?: () => void;
+    usageRequestId: `${string}-${string}-${string}-${string}-${string}`;
+    messages: readonly import("../session/model-request.js").SessionModelMessage[];
+    tools: readonly import("../host.js").ClientToolDefinition[];
+    retryState?: import("../model/contracts.js").ModelRetryState;
+    system: string;
+    systemBlocks?: readonly import("../model/contracts.js").ModelTextBlock[];
+    cachePrefixMessages?: number;
+    outputLimit?: number;
+    allowTools?: boolean;
+    allowHostedTools?: boolean;
+    toolChoice?: "auto" | "none";
+    reasoningEffort?: import("../index.js").AgentReasoningEffort;
+    requestReasoningEffort?: import("../index.js").AgentReasoningEffort;
+    promptCacheKey?: string;
+    images?: readonly import("../model/image-contract.js").ModelImage[];
+    onAttemptDiagnostic?: (diagnostic: import("../model/contracts.js").ModelAttemptDiagnostic) => Promise<void> | void;
+}>;