@myagentroam/agent 0.9.159 → 0.9.161

package/dist/agent-core/extensions/model-stream.js

@@ -0,0 +1,101 @@
+import { randomUUID } from 'node:crypto';
+import { MarAgentError } 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 MarAgentError('MAR_AGENT_MODEL_EVENT_INVALID', 'Model event is invalid.');
+            if (event.type === 'opaque') {
+                if (!sourceRef || event.sourceRef !== sourceRef)
+                    throw new MarAgentError('MAR_AGENT_MODEL_EVENT_INVALID', 'Model event reference is invalid.');
+                yield next.value;
+            }
+            else {
+                if (event.type === 'response.item')
+                    throw new MarAgentError('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) {
+            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.delta':
+        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.summary':
+            return typeof event.itemId === 'string' && typeof event.text === 'string';
+        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.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/agent-core/extensions/models.d.ts

@@ -0,0 +1,43 @@
+import type { MarAgentReasoningEffort } from '../model/configuration.js';
+import type { ModelStopReason, ModelUsage, ModelTextBlock } from '../model/contracts.js';
+import type { CoreModelMessage, CoreModelRequest, CoreRequestSnapshot } from './model-request.js';
+import type { CoreOperationContext } from './operation.js';
+import type { CoreModelEvent } from './model-stream.js';
+export interface CoreModelDescription {
+    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 MarAgentReasoningEffort[];
+    readonly isDefault: boolean;
+}
+export type CoreModelTextBlock = ModelTextBlock;
+export interface CoreGenerateInput {
+    readonly signal?: AbortSignal;
+    readonly requestSnapshot?: CoreRequestSnapshot;
+    readonly modelId?: string;
+    readonly system?: string | readonly CoreModelTextBlock[];
+    readonly messages?: readonly CoreModelMessage[];
+    readonly prompt?: string | readonly CoreModelTextBlock[];
+    readonly retainToolCatalog?: boolean;
+    readonly outputLimit?: number;
+    readonly reasoningEffort?: MarAgentReasoningEffort;
+}
+export interface CoreGenerateResult {
+    readonly outcome: 'text' | 'empty' | 'cancelled';
+    readonly text: string;
+    readonly stopReason: ModelStopReason;
+    readonly usage?: Readonly<ModelUsage>;
+}
+export interface CoreModelsApi {
+    list(): readonly CoreModelDescription[];
+    generate(input: CoreGenerateInput): Promise<CoreGenerateResult>;
+}
+/** Application model configuration stays at the SDK boundary, not in plugin bindings or logs. */
+export interface CoreModelsBackend {
+    list(): readonly CoreModelDescription[];
+    generate(input: CoreGenerateInput, call: CoreOperationContext, transform: (request: CoreModelRequest) => Promise<CoreModelRequest>, transformEvent: (event: CoreModelEvent, signal: AbortSignal) => Promise<CoreModelEvent | undefined>, diagnoseCleanup?: (code: string) => void): Promise<CoreGenerateResult>;
+}

package/dist/agent-core/extensions/models.js

@@ -0,0 +1 @@
+export {};

package/dist/agent-core/extensions/network.d.ts

@@ -0,0 +1,32 @@
+import type { CoreDomainFacts, CoreDomainOperations } from './contracts.js';
+import type { ExtensionHooks } from './hooks.js';
+import type { CoreOperationContext } from './operation.js';
+import type { ExtensionResourceScope } from './resources.js';
+export interface CoreHttpRequest {
+    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 CoreHttpResponse {
+    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 CoreNetworkApi {
+    fetch(input: CoreHttpRequest): Promise<CoreHttpResponse>;
+}
+export interface CoreNetworkBackend {
+    fetch(input: CoreHttpRequest, call: CoreOperationContext): Promise<CoreHttpResponse>;
+}
+export interface CoreHttpCompletion {
+    readonly status: number;
+    readonly redirected: boolean;
+}
+export declare function bindCoreNetwork(backend: CoreNetworkBackend, run: <Value>(operation: (call: CoreOperationContext) => Promise<Value>, signal?: AbortSignal) => Promise<Value>, scope: ExtensionResourceScope, hooks: ExtensionHooks<CoreDomainOperations, CoreDomainFacts>, diagnose: () => void): CoreNetworkApi;

package/dist/agent-core/extensions/network.js

@@ -0,0 +1,97 @@
+import { MarAgentError } 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 MarAgentError('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 MarAgentError('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/agent-core/extensions/operation.d.ts

@@ -0,0 +1,29 @@
+export interface CoreOperationContext {
+    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 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 CoreCallbackRunner = <Value>(call: CoreOperationContext, callback: (call: CoreOperationContext) => Value | Promise<Value>, settled?: boolean) => Promise<Value>;
+/** Internal identity propagation. Caller-controlled payloads never select a framework identity. */
+export declare class ExtensionOperations {
+    #private;
+    current(): CoreOperationContext | undefined;
+    /** Bind the effective owner signal before author code can call another facade. */
+    callback<Value>(call: CoreOperationContext, callback: (call: CoreOperationContext) => Value | Promise<Value>, settled?: boolean): Promise<Value>;
+    /** Physical transport ingress starts a new ancestry; native plugin calls cannot choose it. */
+    continue<T>(context: CoreOperationContext, operation: () => Promise<T>, settled?: boolean): Promise<T>;
+    /** Physical transport ingress starts a new ancestry; native plugin calls cannot choose it. */
+    enter<T>(identity: Omit<CoreOperationContext, 'operationId' | 'parentOperationId'>, operation: (context: CoreOperationContext) => T): T;
+    run<T>(identity: Omit<CoreOperationContext, 'operationId' | 'parentOperationId'>, operation: (context: CoreOperationContext) => T): T;
+}

package/dist/agent-core/extensions/operation.js

@@ -0,0 +1,98 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+/** Internal identity propagation. Caller-controlled payloads never select a framework identity. */
+export class ExtensionOperations {
+    #current = new AsyncLocalStorage();
+    current() {
+        const frame = this.#current.getStore();
+        return frame?.active ? frame.context : undefined;
+    }
+    /** Bind the effective owner signal before author code can call another facade. */
+    callback(call, callback, settled = false) {
+        const controller = new AbortController();
+        const effective = Object.freeze({
+            ...call,
+            signal: AbortSignal.any([call.signal, controller.signal])
+        });
+        return this.continue(effective, async () => {
+            try {
+                return await callback(effective);
+            }
+            catch (error) {
+                // Cancel descendants before continue joins them; retain the original callback error.
+                controller.abort(error);
+                throw error;
+            }
+        }, settled);
+    }
+    /** Physical transport ingress starts a new ancestry; native plugin calls cannot choose it. */
+    async continue(context, operation, settled = false) {
+        const frame = { context, active: true, children: new Set() };
+        return this.#current.run(frame, async () => {
+            try {
+                if (!settled)
+                    context.signal.throwIfAborted();
+                return await operation();
+            }
+            finally {
+                while (frame.children.size)
+                    await Promise.all([...frame.children]);
+                frame.active = false;
+            }
+        });
+    }
+    /** Physical transport ingress starts a new ancestry; native plugin calls cannot choose it. */
+    enter(identity, operation) {
+        return this.#current.run(undefined, () => this.run(identity, operation));
+    }
+    run(identity, operation) {
+        const parent = this.current();
+        const context = Object.freeze({
+            ...identity,
+            operationId: randomUUID(),
+            ...(parent
+                ? {
+                    parentOperationId: parent.operationId,
+                    ...((identity.toolCallId ?? parent.toolCallId) === undefined
+                        ? {}
+                        : { toolCallId: identity.toolCallId ?? parent.toolCallId }),
+                    entry: parent.entry,
+                    signal: AbortSignal.any([identity.signal, parent.signal])
+                }
+                : {})
+        });
+        const ancestor = this.#current.getStore();
+        const frame = { context, active: true, children: new Set() };
+        let value;
+        try {
+            value = this.#current.run(frame, () => {
+                context.signal.throwIfAborted();
+                return operation(context);
+            });
+        }
+        catch (error) {
+            frame.active = false;
+            throw error;
+        }
+        if (!value || typeof value.then !== 'function') {
+            frame.active = false;
+            return value;
+        }
+        const result = (async () => {
+            try {
+                return await value;
+            }
+            finally {
+                while (frame.children.size)
+                    await Promise.all([...frame.children]);
+                frame.active = false;
+            }
+        })();
+        if (ancestor?.active) {
+            const settled = result.then(() => undefined, () => undefined);
+            ancestor.children.add(settled);
+            void settled.then(() => ancestor.children.delete(settled));
+        }
+        return result;
+    }
+}

package/dist/agent-core/extensions/processes.d.ts

@@ -0,0 +1,52 @@
+import type { CoreDomainFacts, CoreDomainOperations } from './contracts.js';
+import type { ExtensionHooks } from './hooks.js';
+import type { CoreOperationContext } from './operation.js';
+import type { ExtensionResourceScope } from './resources.js';
+export interface CoreProcessInput {
+    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 CoreProcessRunInput extends CoreProcessInput {
+    readonly timeoutMs?: number;
+    readonly outputLimitBytes?: number;
+}
+export interface CoreProcessExit {
+    readonly code: number | null;
+    readonly signal: string | null;
+}
+export interface CoreProcessHandle {
+    readonly processId: string;
+    readonly stdout: AsyncIterable<Uint8Array>;
+    readonly stderr: AsyncIterable<Uint8Array>;
+    wait(): Promise<CoreProcessExit>;
+    cancel(): Promise<void>;
+}
+export interface CoreProcessResult extends CoreProcessExit {
+    readonly processId: string;
+    readonly stdout: Uint8Array;
+    readonly stderr: Uint8Array;
+    readonly stdoutBytes: number;
+    readonly stderrBytes: number;
+    readonly truncated: boolean;
+    readonly timedOut: boolean;
+}
+export interface CoreProcessesApi {
+    spawn(input: CoreProcessInput): Promise<CoreProcessHandle>;
+    run(input: CoreProcessRunInput): Promise<CoreProcessResult>;
+}
+export interface CoreProcessesBackend {
+    spawn(input: CoreProcessInput, call: CoreOperationContext): Promise<CoreProcessHandle>;
+}
+export interface CoreProcessCompletion extends CoreProcessExit {
+    readonly processId: string;
+    readonly stdoutBytes?: number;
+    readonly stderrBytes?: number;
+    readonly truncated?: boolean;
+    readonly timedOut?: boolean;
+}
+export declare function validateCoreProcessInput(input: CoreProcessInput): void;
+export declare function bindCoreProcesses(backend: CoreProcessesBackend, run: <Value>(operation: (call: CoreOperationContext) => Promise<Value>, signal?: AbortSignal) => Promise<Value>, scope: ExtensionResourceScope, hooks: ExtensionHooks<CoreDomainOperations, CoreDomainFacts>, diagnose: () => void): CoreProcessesApi;