@myagentroam/agent 0.11.32 → 0.11.34

package/dist/runtime/context/restore.js

@@ -0,0 +1,186 @@
+import { AgentError } from '../../error.js';
+import { appliedInputRecord, pendingDeferredInputs } from '../../session/deferred-input.js';
+import { compactSummaryFromCheckpoint, replacementHistoryFromCheckpoint, inputMetadataFromRecord } from '../../session/record-projection.js';
+import { compactedHistoryMessages, continuationMessage } from '../compaction/history.js';
+import { restoreCompactTail } from '../compaction/retained-context.js';
+import { environmentContextUpdate, restoreEnvironmentState } from './environment.js';
+import { buildContextProjection } from './projection.js';
+export async function readResourceImages(store, sessionId, images) {
+    return Promise.all(images.map(async (image) => {
+        const resource = image.resourceId === undefined
+            ? undefined
+            : await store.readResource(sessionId, image.resourceId);
+        if (!resource)
+            throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session input images cannot be fully restored.');
+        return { ...image, dataBase64: resource.dataBase64 };
+    }));
+}
+export async function restoreMessages(store, sessionId, records, options) {
+    const messages = [];
+    const outcomes = new Map();
+    const toolOutcomes = new WeakMap();
+    const modelProjection = new Map((options.projection ?? buildContextProjection(records)).entries.map((entry) => [entry.record.recordId, entry.message]));
+    let userMessages = [];
+    let ignoredImages = 0;
+    let currentTurnUserIndex;
+    let environmentState;
+    const pendingInputs = pendingDeferredInputs(records);
+    for (const record of records) {
+        const messageStart = messages.length;
+        const applied = appliedInputRecord(record);
+        const inputRecord = applied ?? record;
+        const payload = inputRecord.payload;
+        if ((record.type === 'tool.completed' || record.type === 'tool.failed') &&
+            typeof payload.callId === 'string') {
+            const result = record.type === 'tool.failed' ? payload.message : payload.data;
+            outcomes.set(JSON.stringify([record.executionId, payload.callId]), {
+                isError: record.type === 'tool.failed',
+                ...(result === undefined ? {} : { result: structuredClone(result) })
+            });
+        }
+        const compactSummary = compactSummaryFromCheckpoint(record);
+        if ((applied ||
+            ((record.type === 'turn.user' || record.type === 'extension.input') &&
+                payload.deferred !== true)) &&
+            typeof payload.prompt === 'string') {
+            const content = typeof payload.modelText === 'string' ? payload.modelText : payload.prompt;
+            const metadata = inputMetadataFromRecord(inputRecord);
+            userMessages.push({ content, metadata });
+            let images = [];
+            if (options.includeImages)
+                try {
+                    images = await store.readInputImages(sessionId, payload.images);
+                    if (options.strictImages &&
+                        Array.isArray(payload.images) &&
+                        images.length !==
+                            payload.images.filter((image) => image?.resourceInputVersion === 1).length)
+                        throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session input images cannot be fully restored.');
+                }
+                catch (error) {
+                    if (options.strictImages)
+                        throw error;
+                    if (!(error instanceof AgentError) || error.code !== 'MAR_AGENT_SESSION_CORRUPT')
+                        throw error;
+                    ignoredImages += Array.isArray(payload.images) ? payload.images.length : 1;
+                }
+            if (record.turnId === options.currentTurnId && currentTurnUserIndex === undefined)
+                currentTurnUserIndex = messages.length;
+            messages.push({
+                role: 'user',
+                content,
+                metadata,
+                ...(images.length ? { images } : {})
+            });
+            const context = payload.modelContext ?? payload.context;
+            if (payload.contextRecords !== true && Array.isArray(context))
+                for (const text of context)
+                    if (typeof text === 'string')
+                        messages.push({ role: 'user', content: text, contextKind: 'contextual' });
+        }
+        else if (record.type === 'input.context') {
+            if (Array.isArray(payload.modelContext))
+                for (const text of payload.modelContext)
+                    if (typeof text === 'string')
+                        messages.push({ role: 'user', content: text, contextKind: 'contextual' });
+        }
+        else if ((record.type === 'message.completed' || record.type === 'plan.completed') &&
+            typeof payload.text === 'string')
+            messages.push({ role: 'assistant', content: payload.text });
+        else if (compactSummary !== undefined) {
+            environmentState = restoreEnvironmentState({ version: 1, state: payload.environment });
+            if (environmentState)
+                messages.push(environmentContextUpdate(environmentState));
+            const history = replacementHistoryFromCheckpoint(record);
+            userMessages =
+                history
+                    ?.filter((message) => message.kind !== 'summary')
+                    .map((message) => ({
+                    content: message.content,
+                    ...(message.metadata
+                        ? { metadata: { ...message.metadata } }
+                        : message.kind === 'extension_input'
+                            ? { metadata: { source: 'extension' } }
+                            : {})
+                })) ?? [];
+            messages.push(...(history
+                ? compactedHistoryMessages(history)
+                : [
+                    {
+                        role: 'user',
+                        content: continuationMessage(compactSummary),
+                        contextKind: 'summary'
+                    }
+                ]));
+            if (Array.isArray(payload.retainedModelContext))
+                for (const item of payload.retainedModelContext) {
+                    if (!item || typeof item !== 'object')
+                        continue;
+                    const message = restoreCompactTail(item);
+                    if (message) {
+                        if (options.includeImages && item.inputRef !== undefined) {
+                            const input = appliedInputRecord({
+                                ...record,
+                                type: 'model.context',
+                                payload: item
+                            });
+                            const images = await store.readInputImages(sessionId, input.payload.images);
+                            if (images.length)
+                                message.images = images;
+                        }
+                        messages.push(message);
+                        if (message.role === 'user' && message.contextKind === undefined)
+                            userMessages.push({
+                                content: message.content,
+                                ...(message.metadata ? { metadata: message.metadata } : {})
+                            });
+                    }
+                }
+        }
+        else if (record.type === 'context.environment') {
+            const current = restoreEnvironmentState(payload);
+            if (current) {
+                const message = environmentContextUpdate(current, environmentState);
+                if (message)
+                    messages.push(message);
+                environmentState = current;
+            }
+        }
+        else if (record.type === 'model.context') {
+            const message = modelProjection.get(record.recordId);
+            if (message) {
+                messages.push(message);
+                if (message.role === 'tool' && message.callId !== undefined) {
+                    const outcome = outcomes.get(JSON.stringify([record.executionId, message.callId]));
+                    if (outcome)
+                        toolOutcomes.set(message, outcome);
+                }
+            }
+        }
+        for (const message of messages.slice(messageStart)) {
+            if (!options.includeImages)
+                delete message.images;
+            else if (options.strictImages && message.images?.length)
+                message.images = await readResourceImages(store, sessionId, message.images);
+            options.messageSources?.set(message, record);
+        }
+    }
+    const completedToolCalls = new Set(messages.filter((message) => message.role === 'tool').map((message) => message.callId));
+    return {
+        toolOutcomes,
+        pendingInputs,
+        environmentState,
+        userMessages,
+        messages: messages.filter((message) => {
+            if (message.role === 'tool_call')
+                return completedToolCalls.has(message.callId);
+            if (message.role !== 'provider' || message.provider !== 'OPENAI_RESPONSES')
+                return true;
+            const item = message.item;
+            if (item.type !== 'function_call' && item.type !== 'custom_tool_call')
+                return true;
+            return typeof item.call_id !== 'string' || completedToolCalls.has(item.call_id);
+        }),
+        ignoredImages,
+        currentTurnUserIndex
+    };
+}

package/dist/runtime/context/usage.d.ts

@@ -0,0 +1,17 @@
+import type { SessionModelMessage as ModelMessage } from '../../session/model-request.js';
+import { type AgentReasoningEffort } from '../../model/configuration.js';
+export interface AuthoritativeModelUsage {
+    readonly contextInputTokens: number;
+    readonly outputTokens: number | undefined;
+    readonly historyMessages?: readonly ModelMessage[];
+    readonly appendedMessages?: readonly ModelMessage[];
+}
+export declare function latestModelUsage(records: readonly import('../../session/record-contract.js').SessionRecord[], selectedModelId: string): AuthoritativeModelUsage | undefined;
+export declare function reasoningEffortBaseline(records: readonly import('../../session/record-contract.js').SessionRecord[], modelId: string): AgentReasoningEffort | undefined;
+export declare function shouldUseNativeCompaction(input: {
+    readonly estimatedRequestTokens: number;
+    readonly contextWindowTokens: number;
+    readonly latestUsage: AuthoritativeModelUsage | undefined;
+    readonly historyMessages: readonly ModelMessage[];
+    readonly appendedMessages: readonly ModelMessage[];
+}): boolean;

package/dist/runtime/context/usage.js

@@ -0,0 +1,124 @@
+import { isDeepStrictEqual } from 'node:util';
+import { agentReasoningEffortSchema } from '../../model/configuration.js';
+import { compactSummaryFromCheckpoint } from '../../session/record-projection.js';
+import { estimatedRequestTokens } from './request-budget.js';
+export function latestModelUsage(records, selectedModelId) {
+    let usage;
+    const toolCallIds = new Set();
+    // readContext starts at compact.completed, whose execution header is before the boundary.
+    let activeModelId = selectedModelId;
+    for (const record of records) {
+        const payload = record.payload;
+        if (compactSummaryFromCheckpoint(record) !== undefined) {
+            usage = undefined;
+            toolCallIds.clear();
+            activeModelId = modelIdFromPayload(payload);
+            continue;
+        }
+        if (record.type === 'execution.header') {
+            activeModelId = modelIdFromPayload(payload);
+            usage = undefined;
+            toolCallIds.clear();
+            continue;
+        }
+        if (record.type === 'model.context' && payload.role === 'tool_call') {
+            if (typeof payload.callId === 'string' && payload.callId.length > 0)
+                toolCallIds.add(payload.callId);
+            else
+                usage = undefined;
+        }
+        if (usage !== undefined) {
+            if (record.type === 'model.context') {
+                const role = payload.role;
+                if (role === 'tool') {
+                    if (typeof payload.callId !== 'string' || !toolCallIds.has(payload.callId))
+                        usage = undefined;
+                    else
+                        usage = {
+                            ...usage,
+                            appendedMessages: [
+                                ...(usage.appendedMessages ?? []),
+                                payload
+                            ]
+                        };
+                }
+                else if (role !== 'tool_call' && role !== 'assistant' && role !== 'provider')
+                    usage = undefined;
+            }
+            else if (invalidatesUsageCalibration(record.type, payload.type))
+                usage = undefined;
+        }
+        if (payload.type === 'usage.updated' &&
+            payload.purpose !== 'compact' &&
+            activeModelId === selectedModelId) {
+            const value = payload.contextInputTokens ?? payload.inputTokens;
+            if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
+                usage = {
+                    contextInputTokens: value,
+                    outputTokens: typeof payload.outputTokens === 'number' &&
+                        Number.isSafeInteger(payload.outputTokens) &&
+                        payload.outputTokens >= 0
+                        ? payload.outputTokens
+                        : undefined
+                };
+        }
+    }
+    return usage;
+}
+export function reasoningEffortBaseline(records, modelId) {
+    let baseline;
+    for (let index = records.length - 1; index >= 0; index--) {
+        const record = records[index];
+        if (compactSummaryFromCheckpoint(record) !== undefined)
+            break;
+        if (record.type !== 'execution.header')
+            continue;
+        const payload = record.payload;
+        if (payload.modelId !== modelId)
+            break;
+        const effort = agentReasoningEffortSchema.safeParse(payload.reasoningEffort);
+        if (effort.success)
+            baseline = effort.data;
+    }
+    return baseline;
+}
+export function shouldUseNativeCompaction(input) {
+    if (input.estimatedRequestTokens <= input.contextWindowTokens)
+        return true;
+    if (input.latestUsage === undefined || input.latestUsage.outputTokens === undefined)
+        return false;
+    const historyDelta = appendOnlyUsageDelta(input.latestUsage, input.historyMessages);
+    if (historyDelta === undefined)
+        return false;
+    const appendedTokens = estimatedRequestTokens('', [...historyDelta, ...input.appendedMessages], []);
+    return (input.latestUsage.contextInputTokens + input.latestUsage.outputTokens + appendedTokens <=
+        input.contextWindowTokens);
+}
+function appendOnlyUsageDelta(usage, historyMessages) {
+    if (usage.historyMessages === undefined)
+        return usage.appendedMessages ?? [];
+    if (historyMessages.length < usage.historyMessages.length)
+        return undefined;
+    for (let index = 0; index < usage.historyMessages.length; index++)
+        if (!isDeepStrictEqual(usage.historyMessages[index], historyMessages[index]))
+            return undefined;
+    const appended = historyMessages.slice(usage.historyMessages.length);
+    const toolCallIds = new Set(usage.historyMessages
+        .filter((message) => message.role === 'tool_call')
+        .map((message) => message.callId));
+    return appended.every((message) => (message.role === 'tool' && toolCallIds.has(message.callId)) ||
+        (message.role === 'user' && message.contextKind === 'environment'))
+        ? appended
+        : undefined;
+}
+function invalidatesUsageCalibration(recordType, payloadType) {
+    if (recordType === 'turn.user' ||
+        recordType === 'context.environment' ||
+        recordType === 'context.gc.completed')
+        return true;
+    return payloadType === 'message.completed';
+}
+function modelIdFromPayload(payload, key = 'modelId') {
+    const value = payload[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/dist/runtime/context/world-state.d.ts

@@ -0,0 +1,34 @@
+import type { SessionModelMessage as ModelMessage } from '../../session/model-request.js';
+import { type ContextualPart } from './contextual-blocks.js';
+import type { ModelContextualBlock, ModelTextBlock } from '../../model/contracts.js';
+export interface ContextualWorldState {
+    generation: string | undefined;
+    initialized: boolean;
+    instructionSnapshot: string | undefined;
+    resourceSnapshot: string | undefined;
+    mcpSnapshot?: string | undefined;
+    promptSnapshot?: readonly ContextualPart[];
+    entries: Array<{
+        index: number;
+        kind: 'instructions' | 'resources' | 'mcp' | 'prompt';
+        content: string;
+        block?: ModelContextualBlock;
+        textBlocks?: readonly ModelTextBlock[];
+    }>;
+}
+export declare function insertContextualWorldState(messages: readonly ModelMessage[], entries: Readonly<ContextualWorldState['entries']>): ModelMessage[];
+export declare function latestContextualWorldStateGeneration(records: readonly import('../../session/record-contract.js').SessionRecord[]): string | undefined;
+export declare function updatePromptWorldState(state: ContextualWorldState, index: number, parts: readonly ContextualPart[]): ContextualWorldState;
+export declare function parsePersistedContextualWorldState(payload: unknown): ContextualWorldState | undefined;
+export declare function persistContextualWorldState(store: Pick<import('../../session/store/contracts.js').SessionStore, 'writeContextualWorldState'>, sessionId: string, state: ContextualWorldState): Promise<void>;
+export declare function updateContextualWorldState(state: ContextualWorldState, index: number, current: {
+    instructionSnapshot: string | undefined;
+    instructionContent: string | undefined;
+}): ContextualWorldState;
+export declare function resetContextualWorldState(generation: string | undefined, index: number, current: {
+    instructionSnapshot: string | undefined;
+    instructionContent: string | undefined;
+    /** Only a committed Compact may supply a new dynamic-resource snapshot. */
+    resourceSnapshot?: string | undefined;
+}): ContextualWorldState;
+export declare function contextualInstructionInsertIndex(messages: readonly ModelMessage[]): number;

package/dist/runtime/context/world-state.js

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+import { AgentError } from '../../error.js';
+import { contextualBlock, contextualChanges } from './contextual-blocks.js';
+import { compactSummaryFromCheckpoint } from '../../session/record-projection.js';
+export function insertContextualWorldState(messages, entries) {
+    const result = [...messages];
+    // Entries can be restored before the latest user after Compact. Sort anchors,
+    // retaining insertion order at the same anchor rather than using a global offset.
+    const ordered = entries
+        .map((entry, order) => ({ entry, order }))
+        .sort((left, right) => left.entry.index - right.entry.index || left.order - right.order);
+    let offset = 0;
+    for (const { entry } of ordered) {
+        const insertionIndex = Math.max(0, Math.min(entry.index + offset, result.length));
+        result.splice(insertionIndex, 0, {
+            role: 'user',
+            content: entry.content,
+            contextKind: 'contextual',
+            contextualBlock: entry.block ??
+                contextualBlock({
+                    id: `runtime:${entry.kind}`,
+                    source: 'runtime',
+                    authority: 'context',
+                    content: entry.content
+                }, entry.kind),
+            ...(entry.textBlocks === undefined ? {} : { textBlocks: entry.textBlocks })
+        });
+        offset++;
+    }
+    return result;
+}
+export function latestContextualWorldStateGeneration(records) {
+    let generation;
+    for (const record of records)
+        if (record.type === 'context.gc.completed' ||
+            compactSummaryFromCheckpoint(record) !== undefined)
+            generation = record.recordId;
+    return generation;
+}
+const textBlocksSchema = z
+    .array(z.object({ text: z.string(), cache: z.literal(true).optional() }).strict())
+    .transform((blocks) => blocks.map((block) => ({
+    text: block.text,
+    ...(block.cache === true ? { cache: true } : {})
+})));
+const partSchema = z
+    .object({
+    id: z.string().min(1).max(256),
+    source: z.enum(['sdk', 'host', 'extension', 'runtime']),
+    authority: z.enum(['instruction', 'context']),
+    content: z.string(),
+    textBlocks: textBlocksSchema.optional()
+})
+    .strict()
+    .transform(({ textBlocks, ...part }) => ({
+    ...part,
+    ...(textBlocks === undefined ? {} : { textBlocks })
+}));
+const blockSchema = z
+    .object({
+    id: z.string().min(1).max(256),
+    source: z.enum(['sdk', 'host', 'extension', 'runtime']),
+    authority: z.enum(['instruction', 'context']),
+    kind: z.string().min(1).max(128),
+    revision: z.string().regex(/^[a-f0-9]{64}$/u),
+    operation: z.enum(['replace', 'remove'])
+})
+    .strict();
+export function updatePromptWorldState(state, index, parts) {
+    const parsed = z.array(partSchema).max(MAX_CONTEXTUAL_WORLD_STATE_ENTRIES).safeParse(parts);
+    if (!parsed.success)
+        throw new AgentError('MAR_AGENT_EXTENSION_PROMPT_INVALID', 'Contextual prompt state is invalid.');
+    const selected = parsed.data;
+    if (new Set(selected.map((part) => part.id)).size !== selected.length)
+        throw new AgentError('MAR_AGENT_EXTENSION_PROMPT_CONFLICT', 'Contextual block ids conflict.');
+    const changes = contextualChanges(state.promptSnapshot ?? [], selected);
+    if (!changes.length && state.promptSnapshot !== undefined)
+        return state;
+    return {
+        ...state,
+        promptSnapshot: selected,
+        entries: [
+            ...state.entries,
+            ...changes.map(({ block, content, textBlocks }) => ({
+                index,
+                kind: 'prompt',
+                content,
+                block,
+                ...(textBlocks === undefined ? {} : { textBlocks })
+            }))
+        ]
+    };
+}
+const MAX_CONTEXTUAL_WORLD_STATE_ENTRIES = 1_024;
+const MAX_CONTEXTUAL_WORLD_STATE_CONTENT_BYTES = 8 * 1024 * 1024;
+export function parsePersistedContextualWorldState(payload) {
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const record = payload;
+    if (record.version !== 1 && record.version !== 2)
+        return undefined;
+    const generation = record.generation === null
+        ? undefined
+        : typeof record.generation === 'string' && record.generation.length <= 128
+            ? record.generation
+            : null;
+    if (generation === null)
+        return undefined;
+    const instructionSnapshot = nullableWorldStateString(record.instructionSnapshot);
+    const resourceSnapshot = nullableWorldStateString(record.resourceSnapshot);
+    if (instructionSnapshot === null || resourceSnapshot === null || !Array.isArray(record.entries))
+        return undefined;
+    if (record.entries.length > MAX_CONTEXTUAL_WORLD_STATE_ENTRIES)
+        return undefined;
+    const entries = [];
+    let contentBytes = 0;
+    for (const value of record.entries) {
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const entry = value;
+        if (!Number.isSafeInteger(entry.index) ||
+            entry.index < 0 ||
+            (entry.kind !== 'instructions' &&
+                entry.kind !== 'resources' &&
+                entry.kind !== 'mcp' &&
+                entry.kind !== 'prompt') ||
+            typeof entry.content !== 'string' ||
+            entry.content.length === 0)
+            return undefined;
+        contentBytes += Buffer.byteLength(entry.content);
+        if (contentBytes > MAX_CONTEXTUAL_WORLD_STATE_CONTENT_BYTES)
+            return undefined;
+        const block = entry.block === undefined ? undefined : blockSchema.safeParse(entry.block);
+        const textBlocks = entry.textBlocks === undefined ? undefined : textBlocksSchema.safeParse(entry.textBlocks);
+        if ((block && !block.success) ||
+            (textBlocks && !textBlocks.success) ||
+            (entry.kind === 'prompt' && !block?.success))
+            return undefined;
+        entries.push({
+            index: entry.index,
+            kind: entry.kind,
+            content: entry.content,
+            ...(block?.success ? { block: block.data } : {}),
+            ...(textBlocks?.success ? { textBlocks: textBlocks.data } : {})
+        });
+    }
+    const promptSnapshot = record.promptSnapshot === undefined
+        ? undefined
+        : z
+            .array(partSchema)
+            .max(MAX_CONTEXTUAL_WORLD_STATE_ENTRIES)
+            .safeParse(record.promptSnapshot);
+    if (promptSnapshot && !promptSnapshot.success)
+        return undefined;
+    if (entries.some((entry) => entry.kind === 'prompt') && !promptSnapshot?.success)
+        return undefined;
+    if (promptSnapshot?.success &&
+        new Set(promptSnapshot.data.map((part) => part.id)).size !== promptSnapshot.data.length)
+        return undefined;
+    return {
+        ...(promptSnapshot?.success ? { promptSnapshot: promptSnapshot.data } : {}),
+        generation,
+        initialized: true,
+        instructionSnapshot,
+        resourceSnapshot,
+        mcpSnapshot: typeof record.mcpSnapshot === 'string' ? record.mcpSnapshot : undefined,
+        entries
+    };
+}
+function nullableWorldStateString(value) {
+    if (value === null)
+        return undefined;
+    return typeof value === 'string' &&
+        Buffer.byteLength(value) <= MAX_CONTEXTUAL_WORLD_STATE_CONTENT_BYTES
+        ? value
+        : null;
+}
+export async function persistContextualWorldState(store, sessionId, state) {
+    if (state.entries.length > MAX_CONTEXTUAL_WORLD_STATE_ENTRIES)
+        throw new AgentError('MAR_AGENT_HOST_LIMIT_EXCEEDED', 'Contextual world state exceeds the entry limit.');
+    await store.writeContextualWorldState(sessionId, {
+        version: 2,
+        ...(state.promptSnapshot === undefined ? {} : { promptSnapshot: state.promptSnapshot }),
+        generation: state.generation ?? null,
+        instructionSnapshot: state.instructionSnapshot ?? null,
+        resourceSnapshot: state.resourceSnapshot ?? null,
+        mcpSnapshot: state.mcpSnapshot ?? null,
+        entries: state.entries
+    });
+}
+export function updateContextualWorldState(state, index, current) {
+    const entries = [...state.entries];
+    if (!state.initialized || state.instructionSnapshot !== current.instructionSnapshot) {
+        if (current.instructionContent !== undefined)
+            entries.push({ index, kind: 'instructions', content: current.instructionContent });
+    }
+    return {
+        ...state,
+        generation: state.generation,
+        mcpSnapshot: state.mcpSnapshot,
+        initialized: true,
+        instructionSnapshot: current.instructionSnapshot,
+        resourceSnapshot: state.resourceSnapshot,
+        entries
+    };
+}
+export function resetContextualWorldState(generation, index, current) {
+    const entries = [];
+    if (current.instructionContent !== undefined)
+        entries.push({ index, kind: 'instructions', content: current.instructionContent });
+    if (current.resourceSnapshot !== undefined)
+        entries.push({ index, kind: 'resources', content: current.resourceSnapshot });
+    return {
+        generation,
+        initialized: true,
+        instructionSnapshot: current.instructionSnapshot,
+        resourceSnapshot: current.resourceSnapshot,
+        entries
+    };
+}
+export function contextualInstructionInsertIndex(messages) {
+    let index = messages.findLastIndex((message) => message.role === 'user' &&
+        message.contextKind === undefined &&
+        message.metadata?.source !== 'extension');
+    if (index < 0)
+        index = messages.findLastIndex((message) => message.contextKind === 'summary');
+    if (index < 0)
+        return messages.length;
+    if (index > 0 && messages[index - 1]?.contextKind === 'environment')
+        index--;
+    return index;
+}

package/dist/runtime/contracts.d.ts

@@ -0,0 +1,29 @@
+import type { AgentReasoningEffort } from '../model/configuration.js';
+import type { ModelImage } from '../model/image-contract.js';
+export type ExecutionMode = 'run' | 'plan' | 'compact';
+export interface RunInputImage extends ModelImage {
+    name: string;
+}
+export interface AgentImageMetadata {
+    name: string;
+    mimeType: string;
+    byteSize: number;
+}
+export interface RunInput {
+    prompt: string;
+    clientMessageId?: string;
+    modelId?: string;
+    reasoningEffort?: AgentReasoningEffort;
+    permissionMode?: import('../tools/permission-contract.js').PermissionMode;
+    images?: readonly RunInputImage[];
+}
+export interface ExecutionResult {
+    executionId: string;
+    status: 'completed' | 'failed' | 'cancelled';
+    finalAnswer: string;
+    permissionStop?: import('../tools/permission-contract.js').PermissionStop;
+    /** The input hook answered without admitting input; no model Turn was requested. */
+    inputHandled?: boolean;
+    errorCode?: string;
+    errorMessage?: string;
+}

package/dist/runtime/event-projection.d.ts

@@ -0,0 +1,14 @@
+import type { ModelEvent, ModelUsage } from '../model/contracts.js';
+import type { EventPayload, AgentEvent } from './events.js';
+/** Mark display-only clipping without changing tool output or model context. */
+export declare function toolEventSummary(text: string): {
+    summary: string;
+    truncated: boolean;
+};
+/** Keep streaming deltas live-only; exec output has one durable copy in model context records. */
+export declare function eventForPersistence(event: AgentEvent): AgentEvent | undefined;
+export declare function publicModelUsage(usage: ModelUsage): Omit<ModelUsage, 'rolloutBudgetUnits'>;
+/** Provider-hosted calls are ordinary public tools, never local execution requests. */
+export declare function publicHostedToolEvents(event: Extract<ModelEvent, {
+    type: 'hosted_tool';
+}>): readonly EventPayload[];