@myagentroam/agent 0.11.33 → 0.11.34

package/dist/model/sse.js

@@ -0,0 +1,281 @@
+import { AgentError } from '../error.js';
+import { isRetryableModelHttpStatus } from './http.js';
+const DEFAULT_MODEL_STREAM_IDLE_TIMEOUT_MS = 300_000;
+const streamEventObservedAt = new WeakMap();
+export function observeModelStreamEvent(value, observedAt) {
+    if (typeof value === 'object' && value !== null && observedAt !== undefined)
+        streamEventObservedAt.set(value, observedAt);
+    return value;
+}
+export function modelStreamEventObservedAt(value) {
+    return typeof value === 'object' && value !== null ? streamEventObservedAt.get(value) : undefined;
+}
+export async function* parseSse(response, signal, maxBytes = 16 * 1024 * 1024, idleTimeoutMs = DEFAULT_MODEL_STREAM_IDLE_TIMEOUT_MS, sensitiveValues = []) {
+    if (!response.ok) {
+        const redact = responseRedactor(sensitiveValues);
+        const body = redact(await readResponseText(response, signal, maxBytes, idleTimeoutMs));
+        const header = (name, limit) => {
+            const value = response.headers.get(name);
+            return value === null ? null : redact(value).slice(0, limit);
+        };
+        const upstream = upstreamError(body);
+        const code = upstream?.code ??
+            (response.status === 401 || response.status === 403
+                ? 'MAR_AGENT_MODEL_AUTH_FAILED'
+                : response.status === 429
+                    ? 'MAR_AGENT_MODEL_RATE_LIMITED'
+                    : response.status === 408 || response.status === 504
+                        ? 'MAR_AGENT_MODEL_TIMEOUT'
+                        : 'MAR_AGENT_MODEL_PROTOCOL_ERROR');
+        throw new AgentError(code, upstream?.message ?? `Model endpoint returned HTTP ${response.status}.`, {
+            details: {
+                status: response.status,
+                body: body.slice(0, 4096),
+                bodyTruncated: body.length > 4096,
+                contentType: header('content-type', 256),
+                requestId: header('x-request-id', 256) ?? header('request-id', 256),
+                retryAfter: header('retry-after', 128)
+            },
+            retryable: isRetryableModelHttpStatus(response.status)
+        });
+    }
+    if (response.body === null)
+        throw new AgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Model response has no body.');
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let total = 0;
+    let streamCompleted = false;
+    const receiverAbort = new AbortController();
+    const receiverSignal = AbortSignal.any([signal, receiverAbort.signal]);
+    const chunks = [];
+    let nextChunk = 0;
+    let receivedAll = false;
+    let receiverFailure;
+    let wake;
+    const notify = () => {
+        wake?.();
+        wake = undefined;
+    };
+    // Keep transport receipt independent of async SDK publication and persistence.
+    // The cumulative response byte limit also bounds the pending raw chunk queue.
+    const receive = (async () => {
+        try {
+            while (true) {
+                const { value, done } = await readStreamChunk(reader, receiverSignal, idleTimeoutMs);
+                const observedAt = performance.now();
+                if (done) {
+                    streamCompleted = true;
+                    break;
+                }
+                total += value.byteLength;
+                enforceResponseSize(total, maxBytes);
+                if (value.byteLength === 0)
+                    continue;
+                chunks.push({ value, observedAt });
+                notify();
+            }
+        }
+        catch (error) {
+            receiverFailure = { error };
+            await reader.cancel(error).catch(() => undefined);
+        }
+        finally {
+            receivedAll = true;
+            notify();
+        }
+    })();
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const chunk = chunks[nextChunk];
+            if (chunk === undefined) {
+                if (receivedAll) {
+                    if (receiverFailure !== undefined)
+                        throw receiverFailure.error;
+                    break;
+                }
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+                continue;
+            }
+            chunks[nextChunk++] = undefined;
+            if (nextChunk >= 1_024 && nextChunk * 2 >= chunks.length) {
+                chunks.splice(0, nextChunk);
+                nextChunk = 0;
+            }
+            const { value, observedAt } = chunk;
+            const text = decoder.decode(value, { stream: true });
+            // Normalize CRLF across transport chunks as well as within each chunk.
+            if (buffer.endsWith('\r') && text.startsWith('\n'))
+                buffer = buffer.slice(0, -1);
+            buffer += text.replaceAll('\r\n', '\n');
+            let boundary;
+            while ((boundary = buffer.indexOf('\n\n')) >= 0) {
+                const frame = buffer.slice(0, boundary);
+                buffer = buffer.slice(boundary + 2);
+                const data = frame
+                    .split('\n')
+                    .filter((line) => line.startsWith('data:'))
+                    .map((line) => line.slice(5).trimStart())
+                    .join('\n');
+                if (data.length === 0 || data === '[DONE]')
+                    continue;
+                try {
+                    yield observeModelStreamEvent(JSON.parse(data), observedAt);
+                }
+                catch (cause) {
+                    throw new AgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Model SSE contained invalid JSON.', { cause });
+                }
+            }
+        }
+        buffer += decoder.decode();
+        if (buffer.trim().length > 0)
+            throw new AgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Model SSE ended with an incomplete frame.');
+    }
+    finally {
+        receiverAbort.abort();
+        await receive;
+        await closeReader(reader, streamCompleted);
+    }
+}
+async function readResponseText(response, signal, maxBytes, idleTimeoutMs) {
+    if (response.body === null)
+        return '';
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let body = '';
+    let total = 0;
+    let streamCompleted = false;
+    try {
+        while (true) {
+            const { value, done } = await readStreamChunk(reader, signal, idleTimeoutMs);
+            if (done) {
+                streamCompleted = true;
+                break;
+            }
+            total += value.byteLength;
+            enforceResponseSize(total, maxBytes);
+            body += decoder.decode(value, { stream: true });
+        }
+        return body + decoder.decode();
+    }
+    finally {
+        await closeReader(reader, streamCompleted);
+    }
+}
+function enforceResponseSize(total, maxBytes) {
+    if (total > maxBytes)
+        throw new AgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Model response exceeded the size limit.');
+}
+async function closeReader(reader, streamCompleted) {
+    if (!streamCompleted)
+        await reader.cancel().catch(() => undefined);
+    try {
+        reader.releaseLock();
+    }
+    catch {
+        // Preserve the original read failure if cancellation could not settle the reader.
+    }
+}
+async function readStreamChunk(reader, signal, idleTimeoutMs) {
+    if (signal.aborted) {
+        void reader.cancel(signal.reason).catch(() => undefined);
+        throw signal.reason;
+    }
+    const timeoutError = new AgentError('MAR_AGENT_MODEL_TIMEOUT', 'Model stream was idle for too long.', {
+        details: { reason: 'MODEL_STREAM_IDLE_TIMEOUT' },
+        retryable: true
+    });
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            clearTimeout(timeout);
+            signal.removeEventListener('abort', abortFromCaller);
+        };
+        const resolveOnce = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(result);
+        };
+        const rejectOnce = (reason) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(reason);
+        };
+        const interrupt = (reason) => {
+            void reader.cancel(reason).catch(() => undefined);
+            rejectOnce(reason);
+        };
+        const abortFromCaller = () => interrupt(signal.reason);
+        signal.addEventListener('abort', abortFromCaller, { once: true });
+        const timeout = setTimeout(() => interrupt(timeoutError), Math.max(1, idleTimeoutMs));
+        reader.read().then(resolveOnce, (error) => {
+            rejectOnce(signal.aborted ? (signal.reason ?? error) : error);
+        });
+    });
+}
+function responseRedactor(sensitiveValues) {
+    const secrets = [
+        ...new Set(sensitiveValues.flatMap((value) => value ? [value, JSON.stringify(value).slice(1, -1), encodeURIComponent(value)] : []))
+    ].sort((left, right) => right.length - left.length);
+    return (value) => secrets.reduce((text, secret) => text.replaceAll(secret, '[REDACTED]'), value);
+}
+function upstreamError(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    const root = record(parsed);
+    if (typeof root.error === 'string') {
+        const message = bounded(root.error, 1_000);
+        return message === undefined ? undefined : { message };
+    }
+    const error = record(root.error);
+    // K3-compatible gateways can put the error discriminator in `type` and omit `code`.
+    const code = bounded(text(error.code) ?? text(error.type), 80);
+    const message = bounded(text(error.message), 1_000);
+    return message === undefined ? undefined : { ...(code === undefined ? {} : { code }), message };
+}
+const RETRYABLE_UPSTREAM_OVERLOAD_CODES = new Set([
+    'rate_limit_error',
+    'overloaded_error',
+    'api_overloaded',
+    'server_is_overloaded',
+    'system_cpu_overloaded',
+    'resource_exhausted',
+    'temporarily_unavailable',
+    'service_unavailable'
+]);
+// Closed set of transient upstream capacity/overload error codes; never grows into a
+// vendor-specific or free-text error classification table.
+export function isRetryableUpstreamOverloadCode(code) {
+    return code !== undefined && RETRYABLE_UPSTREAM_OVERLOAD_CODES.has(code.toLowerCase());
+}
+function bounded(value, maximum) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        return undefined;
+    return [...normalized].slice(0, maximum).join('');
+}
+export function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function text(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+export function number(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}

package/dist/model/text-blocks.js

@@ -0,0 +1,40 @@
+import { AgentError } from '../error.js';
+/** Preserve explicit blocks only while their complete texts still match the actual prefix. */
+export function resolveModelTextBlocks(text, blocks) {
+    if (typeof text !== 'string' || !Array.isArray(blocks))
+        throw invalid();
+    const copied = blocks.map((block) => {
+        if (!block ||
+            typeof block !== 'object' ||
+            typeof block.text !== 'string' ||
+            (block.cache !== undefined && block.cache !== true))
+            throw invalid();
+        return { text: block.text, ...(block.cache === true ? { cache: true } : {}) };
+    });
+    let offset = 0;
+    const result = [];
+    for (const block of copied) {
+        if (!text.startsWith(block.text, offset))
+            break;
+        result.push(block);
+        offset += block.text.length;
+    }
+    if (offset < text.length)
+        result.push({ text: text.slice(offset) });
+    return result;
+}
+export function modelTextInput(value) {
+    if (typeof value === 'string')
+        return { text: value };
+    if (!Array.isArray(value))
+        throw invalid();
+    for (const block of value) {
+        if (!block || typeof block !== 'object' || typeof block.text !== 'string')
+            throw invalid();
+    }
+    const text = value.map((block) => block.text).join('');
+    return { text, blocks: resolveModelTextBlocks(text, value) };
+}
+function invalid() {
+    return new AgentError('MAR_AGENT_MODEL_TEXT_BLOCK_INVALID', 'Model text blocks are invalid.');
+}

package/dist/model/tool-declarations.d.ts

@@ -0,0 +1,4 @@
+import type { AgentModelConfiguration } from './configuration.js';
+import type { ModelToolDefinition } from './contracts.js';
+/** Native Responses discovery carries deferred definitions in history, not the top-level catalog. */
+export declare function projectModelRequestTools(model: Pick<AgentModelConfiguration, 'protocol'>, tools: readonly ModelToolDefinition[], residentNames: ReadonlySet<string>): readonly ModelToolDefinition[];

package/dist/model/tool-definition-projection.d.ts

@@ -0,0 +1,6 @@
+import type { ModelToolDefinition } from './contracts.js';
+export { stableToolSchema } from './tool-schema.js';
+export declare function stableToolDefinition<T extends ModelToolDefinition>(definition: T): T;
+export declare function orderToolDefinitions<T extends {
+    readonly name: string;
+}>(definitions: readonly T[]): T[];

package/dist/model/tool-definition-projection.js

@@ -0,0 +1,11 @@
+import { stableToolSchema } from './tool-schema.js';
+export { stableToolSchema } from './tool-schema.js';
+export function stableToolDefinition(definition) {
+    return {
+        ...definition,
+        inputSchema: stableToolSchema(definition.inputSchema)
+    };
+}
+export function orderToolDefinitions(definitions) {
+    return [...definitions].sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+}

package/dist/model/tool-schema.d.ts

@@ -0,0 +1,2 @@
+/** Stable model declarations, not a serializer for historical messages or tool results. */
+export declare function stableToolSchema<T>(schema: T): T;

package/dist/model/tool-schema.js

@@ -0,0 +1,17 @@
+/** Stable model declarations, not a serializer for historical messages or tool results. */
+export function stableToolSchema(schema) {
+    return stableSchemaValue(schema);
+}
+function stableSchemaValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableSchemaValue);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return value;
+    const fields = value;
+    return Object.fromEntries(Object.keys(fields)
+        .sort()
+        .map((key) => [key, stableSchemaValue(fields[key])]));
+}

package/dist/model/transport-test.d.ts

@@ -0,0 +1,10 @@
+import type { AgentModelConfiguration } from './configuration.js';
+export interface AgentModelTransportTestResult {
+    readonly completed: boolean;
+    readonly response: string;
+}
+/** Probe a configured protocol without exposing its adapter or wire events. */
+export declare function testAgentModelTransport(configuration: AgentModelConfiguration, signal: AbortSignal, request?: {
+    readonly system?: string;
+    readonly prompt?: string;
+}): Promise<AgentModelTransportTestResult>;

package/dist/model/transport-test.js

@@ -0,0 +1,27 @@
+import { AnthropicMessagesAdapter } from './anthropic-messages.js';
+import { OpenAiResponsesAdapter } from './openai-responses.js';
+/** Probe a configured protocol without exposing its adapter or wire events. */
+export async function testAgentModelTransport(configuration, signal, request) {
+    const adapter = configuration.protocol === 'OPENAI_RESPONSES'
+        ? new OpenAiResponsesAdapter(configuration)
+        : new AnthropicMessagesAdapter(configuration);
+    try {
+        let completed = false;
+        let response = '';
+        for await (const event of adapter.start({
+            system: request?.system ?? 'You are performing a model transport connectivity test.',
+            messages: [{ role: 'user', content: request?.prompt ?? 'Reply with OK.' }],
+            tools: [],
+            allowTools: false
+        }, signal)) {
+            if (event.type === 'completed')
+                completed = true;
+            if (event.type === 'text.completed')
+                response = event.text;
+        }
+        return { completed, response };
+    }
+    finally {
+        await adapter.close?.();
+    }
+}

package/dist/model/usage-observer.d.ts

@@ -0,0 +1,5 @@
+import type { AgentModelConfiguration } from './configuration.js';
+import type { ModelEvent, ModelRequest } from './contracts.js';
+export type { ModelRequestUsage, ModelUsageObservation, ModelUsageObserver } from './usage.js';
+/** Observe before retry prelude buffering so failed attempts retain reported usage. */
+export declare function observeModelRequestUsage(start: () => AsyncIterable<ModelEvent>, request: ModelRequest, configuration: AgentModelConfiguration, signal: AbortSignal, now?: () => number): AsyncIterable<ModelEvent>;

package/dist/model/usage.d.ts

@@ -0,0 +1,40 @@
+export interface ModelUsage {
+    /** Normalized total input including cache; distinct from protocol-native inputTokens. */
+    totalInputTokens?: number | undefined;
+    reasoningTokens?: number | undefined;
+    inputTokens?: number | undefined;
+    contextInputTokens?: number | undefined;
+    outputTokens?: number | undefined;
+    cacheReadTokens?: number | undefined;
+    cacheWriteTokens?: number | undefined;
+    rolloutBudgetUnits?: number | undefined;
+    hostedSearches?: number | undefined;
+    hostedFetches?: number | undefined;
+}
+/** Safe request facts, independent of conversation events and provider payloads. */
+export interface ModelRequestUsage {
+    readonly recordId: string;
+    readonly requestId: string;
+    readonly revision: number;
+    readonly modelConfigurationId: string;
+    readonly modelName: string;
+    readonly provider: string;
+    readonly requestedModel: string;
+    readonly actualModel?: string;
+    readonly responseId?: string;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly state: 'running' | 'succeeded' | 'failed' | 'cancelled' | 'interrupted';
+    readonly inputTokens?: string;
+    readonly outputTokens?: string;
+    readonly cacheReadTokens?: string;
+    readonly cacheWriteTokens?: string;
+    readonly reasoningTokens?: string;
+}
+export interface ModelUsageObservation extends ModelRequestUsage {
+    readonly sessionId: string;
+    readonly executionId?: string;
+    readonly purpose: 'conversation' | 'compact' | 'title' | 'other';
+    readonly agentRole: 'root' | 'subagent';
+}
+export type ModelUsageObserver = (usage: ModelUsageObservation) => Promise<void> | void;

package/dist/network/credential-runtime.d.ts

@@ -0,0 +1,8 @@
+import { SecretValue, type ModelCredentialProvider, type ModelCredential, type ModelCredentialAcquireReason } from './credentials.js';
+export declare function acquireModelCredential(configuration: {
+    readonly apiKey?: SecretValue;
+    readonly credentialProvider?: ModelCredentialProvider;
+}, reason: ModelCredentialAcquireReason, missingCredentialMessage: string, signal?: AbortSignal): Promise<ModelCredential>;
+export declare function appendModelCredentialHeaders(headers: Headers, credential: ModelCredential, reservedHeaders: ReadonlySet<string>): Headers;
+/** Values known to be credentials, used only when producing public HTTP error diagnostics. */
+export declare function modelCredentialSensitiveValues(credential: ModelCredential): readonly string[];

package/dist/network/credential-runtime.js

@@ -0,0 +1,72 @@
+import { AgentError } from '../error.js';
+import { SecretValue } from './credentials.js';
+export async function acquireModelCredential(configuration, reason, missingCredentialMessage, signal) {
+    signal?.throwIfAborted();
+    if (configuration.credentialProvider !== undefined) {
+        if (configuration.apiKey !== undefined)
+            throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Model credential sources are ambiguous.');
+        const credential = await waitForModelCredential(configuration.credentialProvider, reason, signal);
+        signal?.throwIfAborted();
+        if (!Number.isSafeInteger(credential.revision) ||
+            credential.revision < 0 ||
+            !Number.isFinite(credential.expiresAt) ||
+            !(credential.bearer instanceof SecretValue) ||
+            credential.headers === null ||
+            typeof credential.headers !== 'object' ||
+            Array.isArray(credential.headers) ||
+            (credential.socks5Url !== undefined && !(credential.socks5Url instanceof SecretValue)))
+            throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Dynamic model credential is invalid.');
+        return credential;
+    }
+    if (configuration.apiKey === undefined)
+        throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', missingCredentialMessage);
+    return {
+        revision: 0,
+        expiresAt: Number.MAX_SAFE_INTEGER,
+        bearer: configuration.apiKey,
+        headers: {}
+    };
+}
+async function waitForModelCredential(provider, reason, signal) {
+    if (signal === undefined)
+        return provider.acquire(reason);
+    let abort = () => { };
+    try {
+        return await new Promise((resolve, reject) => {
+            // Cancel only this request's wait; the shared provider remains caller-owned.
+            abort = () => reject(signal.reason);
+            signal.addEventListener('abort', abort, { once: true });
+            if (signal.aborted) {
+                abort();
+                return;
+            }
+            provider.acquire(reason).then(resolve, reject);
+        });
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+    }
+}
+export function appendModelCredentialHeaders(headers, credential, reservedHeaders) {
+    for (const [name, value] of Object.entries(credential.headers)) {
+        if (reservedHeaders.has(name.toLowerCase()))
+            throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Dynamic model credential contains a reserved header.');
+        headers.set(name, value instanceof SecretValue ? value.reveal() : value);
+    }
+    return headers;
+}
+/** Values known to be credentials, used only when producing public HTTP error diagnostics. */
+export function modelCredentialSensitiveValues(credential) {
+    const values = [
+        credential.bearer.reveal(),
+        ...Object.values(credential.headers)
+            .filter((value) => value instanceof SecretValue)
+            .map((value) => value.reveal())
+    ];
+    if (credential.socks5Url !== undefined) {
+        const proxy = credential.socks5Url.reveal();
+        const url = new URL(proxy);
+        values.push(proxy, decodeURIComponent(url.username), decodeURIComponent(url.password));
+    }
+    return values;
+}

package/dist/network/credentials.d.ts

@@ -0,0 +1,20 @@
+export declare class SecretValue {
+    #private;
+    constructor(value: string);
+    reveal(): string;
+    toJSON(): string;
+    toString(): string;
+}
+export type ModelCredentialAcquireReason = 'REQUEST' | 'UNAUTHORIZED' | 'RECONNECT';
+export interface ModelCredential {
+    readonly revision: number;
+    readonly expiresAt: number;
+    readonly bearer: SecretValue;
+    readonly headers: Readonly<Record<string, SecretValue | string>>;
+    readonly socks5Url?: SecretValue;
+}
+export interface ModelCredentialProvider {
+    acquire(reason: ModelCredentialAcquireReason): Promise<ModelCredential>;
+    invalidate(revision: number): void | Promise<void>;
+    close(): Promise<void>;
+}

package/dist/network/credentials.js

@@ -0,0 +1,18 @@
+import { AgentError } from '../error.js';
+export class SecretValue {
+    #value;
+    constructor(value) {
+        if (value.length === 0)
+            throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'API key is required.');
+        this.#value = value;
+    }
+    reveal() {
+        return this.#value;
+    }
+    toJSON() {
+        return '[REDACTED]';
+    }
+    toString() {
+        return '[REDACTED]';
+    }
+}

package/dist/network/http.d.ts

@@ -0,0 +1,20 @@
+import { type Socket } from 'node:net';
+export interface HttpAttempt {
+    readonly request: RequestInit;
+    readonly httpVersion: '1.1' | '2';
+    readonly socks5Url?: string;
+}
+export type HttpRequestInit = RequestInit | HttpAttempt | (() => Promise<RequestInit | HttpAttempt>);
+export declare function fetchWithConnectionTimeout(url: string, attempt: HttpAttempt, signal: AbortSignal, connectionTimeoutMs: number): Promise<Response>;
+export declare function connectSocks5Target(input: {
+    readonly socks5Url: string;
+    readonly targetHost: string;
+    readonly targetPort: number;
+    readonly tls: boolean;
+    readonly servername?: string;
+    readonly alpnProtocols?: readonly string[];
+    readonly requiredAlpnProtocol?: string;
+    readonly signal?: AbortSignal;
+}): Promise<Socket>;
+export declare function isModelHttpAttempt(value: RequestInit | HttpAttempt): value is HttpAttempt;
+export declare function hasErrorCode(error: unknown, code: string): boolean;