@myagentroam/agent 0.11.32 → 0.11.34

package/dist/extensions/model-request.js

@@ -0,0 +1,197 @@
+import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { resolveModelTextBlocks } from '../model/text-blocks.js';
+import { orderToolDefinitions, stableToolDefinition } from '../model/tool-definition-projection.js';
+import { AgentError } from '../error.js';
+/** Only actual SDK model dispatch records snapshots; public views carry no raw payload authority. */
+export class ExtensionRequestSnapshots {
+    #requests = new WeakMap();
+    #current;
+    #completed;
+    record(modelId, request) {
+        const { onAttemptDiagnostic: _diagnostic, onModelUsage: _usage, onModelUsageFailure: _usageFailure, usageRequestId: _usageRequestId, ...serializable } = request;
+        const retained = structuredClone(serializable);
+        let view;
+        // Preserve dispatch-time isolation without projecting unused public views.
+        const snapshot = Object.freeze({
+            id: randomUUID(),
+            get request() {
+                return (view ??= freezeSnapshot(new ExtensionRequestBridge(modelId, retained).view));
+            }
+        });
+        this.#requests.set(snapshot, { modelId, request: retained });
+        this.#current = snapshot;
+        return snapshot;
+    }
+    complete(snapshot) {
+        if (!this.#requests.has(snapshot))
+            throw new AgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'Request snapshot is unavailable.');
+        this.#completed = snapshot;
+    }
+    capture(input = {}) {
+        if (!input ||
+            typeof input !== 'object' ||
+            Array.isArray(input) ||
+            (input.completed !== undefined && typeof input.completed !== 'boolean'))
+            throw new AgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'Request snapshot selection is invalid.');
+        return input.completed === true ? this.#completed : this.#current;
+    }
+    resolve(snapshot) {
+        const entry = this.#requests.get(snapshot);
+        if (!entry)
+            throw new AgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'Request snapshot does not belong to the current Session.');
+        return {
+            modelId: entry.modelId,
+            request: structuredClone(entry.request),
+            view: snapshot.request
+        };
+    }
+}
+function freezeSnapshot(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            freezeSnapshot(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+/** One conversion per actual request; references are valid only for this candidate. */
+export class ExtensionRequestBridge {
+    modelId;
+    original;
+    committedPrefix;
+    #messages = new Map();
+    rewroteCommittedInput = false;
+    view;
+    constructor(modelId, original, sourceMessages, committedPrefix = 0) {
+        this.modelId = modelId;
+        this.original = original;
+        this.committedPrefix = committedPrefix;
+        const messages = original.messages.map((original, index) => {
+            const sourceRef = sourceMessages?.[index]?.sourceRef ?? randomUUID();
+            const view = original.role === 'provider'
+                ? { role: 'opaque', sourceRef }
+                : {
+                    role: original.role,
+                    content: original.content,
+                    ...(original.textBlocks === undefined
+                        ? {}
+                        : { textBlocks: structuredClone(original.textBlocks) }),
+                    sourceRef,
+                    ...(original.callId !== undefined ? { callId: original.callId } : {}),
+                    ...(original.name !== undefined ? { name: original.name } : {}),
+                    ...(original.arguments !== undefined
+                        ? { arguments: structuredClone(original.arguments) }
+                        : {}),
+                    ...(original.images !== undefined ? { images: structuredClone(original.images) } : {})
+                };
+            this.#messages.set(sourceRef, { original, view: structuredClone(view), index });
+            return view;
+        });
+        this.view = {
+            modelId,
+            system: original.system,
+            ...(original.systemBlocks === undefined
+                ? {}
+                : { systemBlocks: structuredClone(original.systemBlocks) }),
+            messages,
+            tools: structuredClone(original.tools),
+            ...(original.toolChoice ? { toolChoice: original.toolChoice } : {}),
+            ...(original.reasoningEffort ? { reasoningEffort: original.reasoningEffort } : {}),
+            ...(original.images ? { images: structuredClone(original.images) } : {})
+        };
+    }
+    lower(view) {
+        if (!view ||
+            view.modelId !== this.modelId ||
+            typeof view.system !== 'string' ||
+            !Array.isArray(view.messages) ||
+            !Array.isArray(view.tools) ||
+            view.tools.some((tool) => !tool ||
+                typeof tool !== 'object' ||
+                typeof tool.name !== 'string' ||
+                typeof tool.description !== 'string' ||
+                !tool.inputSchema ||
+                typeof tool.inputSchema !== 'object' ||
+                Array.isArray(tool.inputSchema)))
+            throw new AgentError('MAR_AGENT_EXTENSION_MODEL_REQUEST_INVALID', 'Model request view is invalid.');
+        const seen = new Set();
+        if (view.messages.length < this.committedPrefix ||
+            view.system !== this.original.system ||
+            !isDeepStrictEqual(view.systemBlocks, this.original.systemBlocks))
+            this.rewroteCommittedInput = true;
+        const messages = view.messages.map((message, index) => {
+            if (!message || typeof message !== 'object')
+                throw new AgentError('MAR_AGENT_EXTENSION_MODEL_REQUEST_INVALID', 'Message view is invalid.');
+            const source = message.sourceRef ? this.#messages.get(message.sourceRef) : undefined;
+            if (message.sourceRef) {
+                if (!source || seen.has(message.sourceRef))
+                    throw new AgentError('MAR_AGENT_EXTENSION_MODEL_REQUEST_INVALID', 'Message source reference is invalid.');
+                seen.add(message.sourceRef);
+            }
+            if (index < this.committedPrefix && source?.index !== index)
+                this.rewroteCommittedInput = true;
+            if (source && isDeepStrictEqual(message, source.view))
+                return source.original;
+            if (index < this.committedPrefix)
+                this.rewroteCommittedInput = true;
+            if (message.role === 'opaque' ||
+                typeof message.content !== 'string' ||
+                !['user', 'assistant', 'tool', 'tool_call'].includes(message.role))
+                throw new AgentError('MAR_AGENT_EXTENSION_MODEL_REQUEST_INVALID', 'Message view is invalid.');
+            if (message.textBlocks !== undefined && message.role === 'tool_call')
+                throw new AgentError('MAR_AGENT_MODEL_CAPABILITY_UNAVAILABLE', 'Text blocks cannot replace structured tool-call arguments.');
+            return {
+                role: message.role,
+                content: message.content,
+                ...(source && message.role === source.original.role
+                    ? {
+                        ...(source.original.contextKind === undefined
+                            ? {}
+                            : { contextKind: source.original.contextKind }),
+                        ...(source.original.contextualBlock === undefined
+                            ? {}
+                            : { contextualBlock: source.original.contextualBlock }),
+                        ...(source.original.metadata === undefined
+                            ? {}
+                            : { metadata: source.original.metadata })
+                    }
+                    : {}),
+                ...(message.textBlocks === undefined
+                    ? {}
+                    : { textBlocks: resolveModelTextBlocks(message.content, message.textBlocks) }),
+                ...(message.callId !== undefined ? { callId: message.callId } : {}),
+                ...(message.name !== undefined ? { name: message.name } : {}),
+                ...(message.role === 'tool' &&
+                    source?.original.role === 'tool' &&
+                    message.callId === source.original.callId &&
+                    message.name === source.original.name &&
+                    source.original.isError !== undefined
+                    ? { isError: source.original.isError }
+                    : {}),
+                ...(message.arguments !== undefined
+                    ? { arguments: structuredClone(message.arguments) }
+                    : {}),
+                ...(message.images !== undefined ? { images: structuredClone(message.images) } : {})
+            };
+        });
+        const { toolChoice: _toolChoice, reasoningEffort: _reasoningEffort, images: _images, systemBlocks: _systemBlocks, ...retained } = this.original;
+        // Middleware selects declarations; it must not reorder a retained discovery prefix.
+        const order = new Map(this.original.tools.map((tool, index) => [tool.name, index]));
+        const tools = orderToolDefinitions(structuredClone(view.tools))
+            .sort((left, right) => (order.get(left.name) ?? order.size) - (order.get(right.name) ?? order.size))
+            .map(stableToolDefinition);
+        return {
+            ...retained,
+            system: view.system,
+            ...(view.systemBlocks === undefined
+                ? {}
+                : { systemBlocks: resolveModelTextBlocks(view.system, view.systemBlocks) }),
+            messages,
+            tools,
+            ...(view.toolChoice ? { toolChoice: view.toolChoice } : {}),
+            ...(view.reasoningEffort ? { reasoningEffort: view.reasoningEffort } : {}),
+            ...(view.images ? { images: structuredClone(view.images) } : {})
+        };
+    }
+}

package/dist/extensions/model-stream.d.ts

@@ -0,0 +1,18 @@
+import type { ModelEvent } from '../model/contracts.js';
+export type ExtensionModelEvent = Exclude<ModelEvent, {
+    type: 'response.item';
+}> | {
+    readonly type: 'opaque';
+    readonly sourceRef: string;
+};
+/** Pull-through transformation: no speculative reads, background producer, or stream replay. */
+export declare function transformCoreModelStream(start: (signal: AbortSignal) => AsyncIterable<ModelEvent>, parent: AbortSignal, transform: (event: ExtensionModelEvent, signal: AbortSignal) => Promise<ExtensionModelEvent | undefined>, diagnoseCleanup?: () => void): AsyncIterable<ModelEvent>;
+export interface DomainModelStreamOperations {
+    'model.event': {
+        input: ExtensionModelEvent;
+        output: ExtensionModelEvent | undefined;
+    };
+}
+export interface DomainModelStreamFacts {
+    'model.event': ExtensionModelEvent;
+}

package/dist/extensions/model-stream.js

@@ -0,0 +1,108 @@
+import { randomUUID } from 'node:crypto';
+import { AgentError } from '../error.js';
+import { modelStreamEventObservedAt, observeModelStreamEvent } from '../model/sse.js';
+/** Pull-through transformation: no speculative reads, background producer, or stream replay. */
+export async function* transformCoreModelStream(start, parent, transform, diagnoseCleanup) {
+    const controller = new AbortController();
+    const signal = AbortSignal.any([parent, controller.signal]);
+    signal.throwIfAborted();
+    const iterator = start(signal)[Symbol.asyncIterator]();
+    let failed = false;
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const next = await iterator.next();
+            if (next.done)
+                return;
+            signal.throwIfAborted();
+            const sourceRef = next.value.type === 'response.item' ? randomUUID() : undefined;
+            const view = sourceRef
+                ? { type: 'opaque', sourceRef }
+                : structuredClone(next.value);
+            const event = await transform(view, signal);
+            signal.throwIfAborted();
+            if (event === undefined)
+                continue;
+            if (!event || typeof event !== 'object' || !validEvent(event))
+                throw new AgentError('MAR_AGENT_MODEL_EVENT_INVALID', 'Model event is invalid.');
+            if (event.type === 'opaque') {
+                if (!sourceRef || event.sourceRef !== sourceRef)
+                    throw new AgentError('MAR_AGENT_MODEL_EVENT_INVALID', 'Model event reference is invalid.');
+                yield next.value;
+            }
+            else {
+                if (event.type === 'response.item')
+                    throw new AgentError('MAR_AGENT_MODEL_EVENT_INVALID', 'Provider-private model events require their opaque reference.');
+                yield observeModelStreamEvent(structuredClone(event), modelStreamEventObservedAt(next.value));
+            }
+        }
+    }
+    catch (error) {
+        failed = true;
+        throw error;
+    }
+    finally {
+        controller.abort();
+        try {
+            await iterator.return?.();
+        }
+        catch (error) {
+            // eslint-disable-next-line no-unsafe-finally -- Preserve a primary failure; surface cleanup failures after success.
+            if (!failed)
+                throw error;
+            diagnoseCleanup?.();
+        }
+    }
+}
+function validEvent(event) {
+    switch (event.type) {
+        case 'opaque':
+            return typeof event.sourceRef === 'string';
+        case 'response.started':
+            return typeof event.responseId === 'string';
+        case 'output.started':
+        case 'output.delta':
+        case 'output.paused':
+        case 'output.completed':
+        case 'output.reset':
+            return true;
+        case 'text.delta':
+            return (typeof event.itemId === 'string' &&
+                typeof event.delta === 'string' &&
+                ['commentary', 'final_answer'].includes(event.phase));
+        case 'text.completed':
+            return (typeof event.itemId === 'string' &&
+                typeof event.text === 'string' &&
+                (event.phase === undefined || ['commentary', 'final_answer'].includes(event.phase)));
+        case 'reasoning.completed':
+            return (typeof event.itemId === 'string' &&
+                typeof event.text === 'string' &&
+                ['summary', 'visible_thinking', 'unspecified'].includes(String(event.representation)));
+        case 'client_tool.call':
+            return (typeof event.callId === 'string' &&
+                typeof event.name === 'string' &&
+                (event.inputMode === undefined || ['json', 'freeform'].includes(event.inputMode)));
+        case 'hosted_tool':
+            return (typeof event.itemId === 'string' &&
+                ['WEB_SEARCH', 'WEB_FETCH'].includes(event.kind) &&
+                ['RUNNING', 'COMPLETED', 'FAILED'].includes(event.status) &&
+                !!event.summary &&
+                typeof event.summary === 'object');
+        case 'citation':
+            return (!!event.citation &&
+                typeof event.citation.id === 'string' &&
+                typeof event.citation.url === 'string');
+        case 'usage':
+            return ((event.final === undefined || typeof event.final === 'boolean') &&
+                !!event.usage &&
+                typeof event.usage === 'object' &&
+                Object.values(event.usage).every((value) => value === undefined ||
+                    (typeof value === 'number' && Number.isFinite(value) && value >= 0)));
+        case 'unknown':
+            return typeof event.nativeType === 'string';
+        case 'completed':
+            return ['completed', 'tool_use', 'max_output', 'pause', 'cancelled'].includes(event.reason);
+        default:
+            return false;
+    }
+}

package/dist/extensions/models.d.ts

@@ -0,0 +1,46 @@
+import type { AgentReasoningEffort } from '../model/configuration.js';
+import type { ModelStopReason, ModelUsage, ModelTextBlock } from '../model/contracts.js';
+import type { ExtensionModelMessage, ExtensionModelRequest, ExtensionRequestSnapshot, DomainModelRequestOperations, DomainModelRequestFacts } from './model-request.js';
+import type { ExtensionOperationContext, ExtensionOperationRunner } from './operation.js';
+import type { ExtensionModelEvent } from './model-stream.js';
+import type { ExtensionHooks } from './hooks.js';
+export interface ExtensionModelDescription {
+    readonly id: string;
+    readonly name: string;
+    /** Actual model service ID, distinct from the configuration ID and display name. */
+    readonly modelId?: string;
+    readonly contextWindowTokens: number;
+    readonly maxOutputTokens: number;
+    readonly inputCapabilities: readonly string[];
+    readonly reasoningEfforts: readonly AgentReasoningEffort[];
+    readonly isDefault: boolean;
+}
+export type ExtensionModelTextBlock = ModelTextBlock;
+export interface ExtensionGenerateInput {
+    readonly signal?: AbortSignal;
+    readonly requestSnapshot?: ExtensionRequestSnapshot;
+    readonly modelId?: string;
+    readonly system?: string | readonly ExtensionModelTextBlock[];
+    readonly messages?: readonly ExtensionModelMessage[];
+    readonly prompt?: string | readonly ExtensionModelTextBlock[];
+    readonly retainToolCatalog?: boolean;
+    readonly outputLimit?: number;
+    readonly reasoningEffort?: AgentReasoningEffort;
+}
+export interface ExtensionGenerateResult {
+    readonly outcome: 'text' | 'empty' | 'cancelled';
+    readonly text: string;
+    readonly stopReason: ModelStopReason;
+    readonly usage?: Readonly<ModelUsage>;
+}
+export interface ExtensionModelsApi {
+    list(): readonly ExtensionModelDescription[];
+    generate(input: ExtensionGenerateInput): Promise<ExtensionGenerateResult>;
+}
+/** Application model configuration stays at the SDK boundary, not in plugin bindings or logs. */
+export interface ExtensionModelsBackend {
+    list(): readonly ExtensionModelDescription[];
+    generate(input: ExtensionGenerateInput, call: ExtensionOperationContext, transform: (request: ExtensionModelRequest) => Promise<ExtensionModelRequest>, transformEvent: (event: ExtensionModelEvent, signal: AbortSignal) => Promise<ExtensionModelEvent | undefined>, diagnoseCleanup?: (code: string) => void): Promise<ExtensionGenerateResult>;
+}
+/** Binds model requests to the owning Extension operation and its hook lane. */
+export declare function bindCoreModels(backend: ExtensionModelsBackend, run: ExtensionOperationRunner, hooks: Pick<ExtensionHooks<DomainModelRequestOperations, DomainModelRequestFacts>, 'invoke'>, modelEvent: (event: ExtensionModelEvent, call: ExtensionOperationContext) => Promise<ExtensionModelEvent | undefined>, diagnose: (code: string, call: ExtensionOperationContext) => void): ExtensionModelsApi;

package/dist/extensions/models.js

@@ -0,0 +1,7 @@
+/** Binds model requests to the owning Extension operation and its hook lane. */
+export function bindCoreModels(backend, run, hooks, modelEvent, diagnose) {
+    return {
+        list: () => backend.list(),
+        generate: (input) => run((call) => backend.generate(input, call, (request) => hooks.invoke('model.request', request, call, async (view) => view), (event, signal) => modelEvent(event, Object.freeze({ ...call, signal })), (code) => diagnose(code, call)), input.signal)
+    };
+}

package/dist/extensions/network.d.ts

@@ -0,0 +1,40 @@
+import type { ExtensionHooks } from './hooks.js';
+import type { ExtensionOperationContext } from './operation.js';
+import type { ExtensionResourceScope } from './resources.js';
+export interface ExtensionHttpRequest {
+    readonly url: string;
+    readonly method?: string;
+    readonly headers?: readonly (readonly [string, string])[];
+    readonly body?: string | Uint8Array;
+    readonly redirect?: 'follow' | 'manual' | 'error';
+    readonly signal?: AbortSignal;
+}
+export interface ExtensionHttpResponse {
+    readonly url: string;
+    readonly status: number;
+    readonly statusText: string;
+    readonly redirected: boolean;
+    readonly headers: readonly (readonly [string, string])[];
+    readonly body: AsyncIterable<Uint8Array>;
+    close(): Promise<void>;
+}
+export interface ExtensionNetworkApi {
+    fetch(input: ExtensionHttpRequest): Promise<ExtensionHttpResponse>;
+}
+export interface ExtensionNetworkBackend {
+    fetch(input: ExtensionHttpRequest, call: ExtensionOperationContext): Promise<ExtensionHttpResponse>;
+}
+export interface ExtensionHttpCompletion {
+    readonly status: number;
+    readonly redirected: boolean;
+}
+export declare function bindCoreNetwork(backend: ExtensionNetworkBackend, run: <Value>(operation: (call: ExtensionOperationContext) => Promise<Value>, signal?: AbortSignal) => Promise<Value>, scope: ExtensionResourceScope, hooks: Pick<ExtensionHooks<DomainNetworkOperations, DomainNetworkFacts>, 'invoke' | 'emit'>, diagnose: () => void): ExtensionNetworkApi;
+export interface DomainNetworkOperations {
+    'network.fetch': {
+        input: ExtensionHttpRequest;
+        output: ExtensionHttpResponse;
+    };
+}
+export interface DomainNetworkFacts {
+    'network.completed': ExtensionHttpCompletion;
+}

package/dist/extensions/network.js

@@ -0,0 +1,97 @@
+import { AgentError } from '../error.js';
+export function bindCoreNetwork(backend, run, scope, hooks, diagnose) {
+    return {
+        fetch: (input) => run((call) => hooks.invoke('network.fetch', input, call, async (input, effective) => {
+            if (typeof backend.fetch !== 'function')
+                throw new AgentError('MAR_AGENT_HOST_PORT_UNAVAILABLE', 'Native HTTP port is unavailable.');
+            const response = await backend.fetch(input, effective);
+            let iterator;
+            const close = async () => {
+                // Close the transport first so an in-flight pull is released before iterator cleanup.
+                const results = await Promise.allSettled([
+                    Promise.resolve().then(() => response.close()),
+                    Promise.resolve().then(() => iterator?.return?.())
+                ]);
+                const failure = results.find((result) => result.status === 'rejected');
+                if (failure?.status === 'rejected')
+                    throw failure.reason;
+            };
+            let registration;
+            try {
+                registration = scope.effect(() => close);
+                await registration.ready;
+                iterator = response.body[Symbol.asyncIterator]();
+                await hooks.emit('network.completed', { status: response.status, redirected: response.redirected }, effective);
+            }
+            catch (error) {
+                try {
+                    await close();
+                }
+                catch {
+                    diagnose();
+                }
+                throw error;
+            }
+            const resource = registration;
+            let done = false;
+            let nextTail = Promise.resolve();
+            const body = {
+                [Symbol.asyncIterator]() {
+                    return this;
+                },
+                next() {
+                    const pending = nextTail.then(pull);
+                    nextTail = pending.catch(() => undefined);
+                    return pending;
+                },
+                async return() {
+                    done = true;
+                    await resource.dispose();
+                    return { done: true, value: undefined };
+                }
+            };
+            async function pull() {
+                if (done)
+                    return { done: true, value: undefined };
+                try {
+                    const next = await scope.run(async (signal) => {
+                        signal.throwIfAborted();
+                        const next = await iterator.next();
+                        signal.throwIfAborted();
+                        return next;
+                    }, effective.signal);
+                    if (next.done) {
+                        done = true;
+                        await resource.dispose();
+                        return { done: true, value: undefined };
+                    }
+                    if (!(next.value instanceof Uint8Array))
+                        throw new AgentError('MAR_AGENT_NETWORK_RESPONSE_INVALID', 'HTTP body must yield raw bytes.');
+                    return { done: false, value: new Uint8Array(next.value) };
+                }
+                catch (error) {
+                    done = true;
+                    try {
+                        await resource.dispose();
+                    }
+                    catch {
+                        diagnose();
+                    }
+                    throw error;
+                }
+            }
+            return {
+                url: response.url,
+                status: response.status,
+                statusText: response.statusText,
+                redirected: response.redirected,
+                headers: Object.freeze(response.headers.map((pair) => Object.freeze([...pair]))),
+                body,
+                close: async () => {
+                    done = true;
+                    await resource.dispose();
+                }
+            };
+        }), input.signal)
+    };
+}

package/dist/extensions/operation.d.ts

@@ -0,0 +1,32 @@
+export interface ExtensionOperationContext {
+    readonly operationId: string;
+    readonly sessionId: string;
+    readonly sessionEpoch: number;
+    readonly ownerInstanceId?: string;
+    readonly extensionId?: string;
+    readonly parentOperationId?: string;
+    readonly executionId?: string;
+    readonly turnId?: string;
+    /** Correlation with the actual enclosing tool call; not an authority token. */
+    readonly toolCallId?: string;
+    readonly parentToolCallId?: string;
+    readonly actor: 'model' | 'sdk' | 'extension' | 'code-mode';
+    readonly entry: 'direct' | 'programmatic' | 'native-api';
+    readonly signal: AbortSignal;
+}
+/** Internal callback binding shared by the typed hooks and contribution handlers. */
+export type ExtensionCallbackRunner = <Value>(call: ExtensionOperationContext, callback: (call: ExtensionOperationContext) => Value | Promise<Value>, settled?: boolean) => Promise<Value>;
+/** Runs a native Extension operation with its captured owner and cancellation context. */
+export type ExtensionOperationRunner = <Value>(operation: (call: ExtensionOperationContext) => Promise<Value>, signal?: AbortSignal) => Promise<Value>;
+/** Internal identity propagation. Caller-controlled payloads never select a framework identity. */
+export declare class ExtensionOperations {
+    #private;
+    current(): ExtensionOperationContext | undefined;
+    /** Bind the effective owner signal before author code can call another facade. */
+    callback<Value>(call: ExtensionOperationContext, callback: (call: ExtensionOperationContext) => Value | Promise<Value>, settled?: boolean): Promise<Value>;
+    /** Physical transport ingress starts a new ancestry; native plugin calls cannot choose it. */
+    continue<T>(context: ExtensionOperationContext, operation: () => Promise<T>, settled?: boolean): Promise<T>;
+    /** Physical transport ingress starts a new ancestry; native plugin calls cannot choose it. */
+    enter<T>(identity: Omit<ExtensionOperationContext, 'operationId' | 'parentOperationId'>, operation: (context: ExtensionOperationContext) => T): T;
+    run<T>(identity: Omit<ExtensionOperationContext, 'operationId' | 'parentOperationId'>, operation: (context: ExtensionOperationContext) => T): T;
+}

package/dist/extensions/processes.d.ts

@@ -0,0 +1,64 @@
+import type { ExtensionHooks } from './hooks.js';
+import type { ExtensionOperationContext } from './operation.js';
+import type { ExtensionResourceScope } from './resources.js';
+export interface ExtensionProcessInput {
+    readonly executable: string;
+    readonly argv?: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly input?: string | Uint8Array;
+    readonly signal?: AbortSignal;
+}
+export interface ExtensionProcessRunInput extends ExtensionProcessInput {
+    readonly timeoutMs?: number;
+    readonly outputLimitBytes?: number;
+}
+export interface ExtensionProcessExit {
+    readonly code: number | null;
+    readonly signal: string | null;
+}
+export interface ExtensionProcessHandle {
+    readonly processId: string;
+    readonly stdout: AsyncIterable<Uint8Array>;
+    readonly stderr: AsyncIterable<Uint8Array>;
+    wait(): Promise<ExtensionProcessExit>;
+    cancel(): Promise<void>;
+}
+export interface ExtensionProcessResult extends ExtensionProcessExit {
+    readonly processId: string;
+    readonly stdout: Uint8Array;
+    readonly stderr: Uint8Array;
+    readonly stdoutBytes: number;
+    readonly stderrBytes: number;
+    readonly truncated: boolean;
+    readonly timedOut: boolean;
+}
+export interface ExtensionProcessesApi {
+    spawn(input: ExtensionProcessInput): Promise<ExtensionProcessHandle>;
+    run(input: ExtensionProcessRunInput): Promise<ExtensionProcessResult>;
+}
+export interface ExtensionProcessesBackend {
+    spawn(input: ExtensionProcessInput, call: ExtensionOperationContext): Promise<ExtensionProcessHandle>;
+}
+export interface ExtensionProcessCompletion extends ExtensionProcessExit {
+    readonly processId: string;
+    readonly stdoutBytes?: number;
+    readonly stderrBytes?: number;
+    readonly truncated?: boolean;
+    readonly timedOut?: boolean;
+}
+export declare function validateCoreProcessInput(input: ExtensionProcessInput): void;
+export declare function bindCoreProcesses(backend: ExtensionProcessesBackend, run: <Value>(operation: (call: ExtensionOperationContext) => Promise<Value>, signal?: AbortSignal) => Promise<Value>, scope: ExtensionResourceScope, hooks: Pick<ExtensionHooks<DomainProcessOperations, DomainProcessFacts>, 'invoke' | 'emit'>, diagnose: () => void): ExtensionProcessesApi;
+export interface DomainProcessOperations {
+    'process.spawn': {
+        input: ExtensionProcessInput;
+        output: ExtensionProcessHandle;
+    };
+    'process.run': {
+        input: ExtensionProcessRunInput;
+        output: ExtensionProcessResult;
+    };
+}
+export interface DomainProcessFacts {
+    'process.completed': ExtensionProcessCompletion;
+}