@myagentroam/agent 0.11.33 → 0.11.34

package/dist/runtime/event-projection.js

@@ -0,0 +1,87 @@
+import { AGENT_EXECUTION_POLICY } from './execution-policy.js';
+import { publicToolMetadata } from './public-tool-metadata.js';
+/** Mark display-only clipping without changing tool output or model context. */
+export function toolEventSummary(text) {
+    const limit = AGENT_EXECUTION_POLICY.toolEventSummaryCharacters;
+    if (text.length <= limit)
+        return { summary: text, truncated: false };
+    const marker = '... [tool event summary truncated]';
+    const prefix = text.slice(0, limit - marker.length).replace(/[\uD800-\uDBFF]$/u, '');
+    return { summary: prefix + marker, truncated: true };
+}
+/** Keep streaming deltas live-only; exec output has one durable copy in model context records. */
+export function eventForPersistence(event) {
+    if (event.type === 'message.delta' ||
+        event.type === 'tool.output' ||
+        event.type === 'input.received' ||
+        (event.type === 'context.compacting' && event.async !== true && event.stage === undefined) ||
+        event.type === 'model.performance' ||
+        event.type === 'message.performance')
+        return undefined;
+    if (event.type !== 'tool.completed' || event.toolName !== 'exec' || !event.data)
+        return event;
+    const metadata = Object.fromEntries(Object.entries(event.data).filter(([key]) => key !== 'stdout' && key !== 'stderr'));
+    return { ...event, data: metadata };
+}
+export function publicModelUsage(usage) {
+    const { rolloutBudgetUnits, ...publicUsage } = usage;
+    void rolloutBudgetUnits;
+    return publicUsage;
+}
+/** Provider-hosted calls are ordinary public tools, never local execution requests. */
+export function publicHostedToolEvents(event) {
+    const toolName = event.toolName ?? (event.kind === 'WEB_SEARCH' ? 'web_search' : 'web_fetch');
+    const legacyInput = {
+        ...(event.summary.query === undefined ? {} : { query: event.summary.query }),
+        ...(event.summary.url === undefined ? {} : { url: event.summary.url })
+    };
+    const input = event.input ?? (Object.keys(legacyInput).length ? legacyInput : undefined);
+    const legacyOutput = {
+        ...(event.summary.title === undefined ? {} : { title: event.summary.title }),
+        ...(event.summary.sources?.length ? { sources: event.summary.sources.slice(0, 20) } : {}),
+        ...(event.summary.sourcesTruncated === true || (event.summary.sources?.length ?? 0) > 20
+            ? { sourcesTruncated: true }
+            : {})
+    };
+    const output = event.output ?? (Object.keys(legacyOutput).length ? legacyOutput : undefined);
+    const text = typeof output === 'string' ? output : output === undefined ? '' : JSON.stringify(output);
+    const preview = toolEventSummary(text);
+    const summary = preview.summary;
+    const truncated = event.truncated === true || legacyOutput.sourcesTruncated === true || preview.truncated;
+    const started = {
+        type: 'tool.started',
+        toolName,
+        callId: event.itemId,
+        data: {
+            ...publicToolMetadata(event.kind === 'WEB_SEARCH' ? 'web_search' : 'web_fetch', event.summary),
+            hostedToolKind: event.kind
+        },
+        ...(input === undefined ? {} : { input }),
+        ...(truncated ? { truncated: true } : {})
+    };
+    if (event.status === 'RUNNING')
+        return [started];
+    if (event.status === 'FAILED')
+        return [
+            started,
+            {
+                type: 'tool.failed',
+                toolName,
+                callId: event.itemId,
+                code: 'HOSTED_TOOL_FAILED',
+                message: summary || 'Hosted tool failed.',
+                truncated
+            }
+        ];
+    return [
+        started,
+        {
+            type: 'tool.completed',
+            toolName,
+            callId: event.itemId,
+            summary,
+            truncated,
+            data: started.data
+        }
+    ];
+}

package/dist/runtime/events.d.ts

@@ -0,0 +1,195 @@
+import type { AgentReasoningEffort } from '../model/configuration.js';
+import type { CodeCellEventData, AgentToolArtifact } from '../tools/contracts.js';
+import type { ExecutionMode } from './contracts.js';
+export interface AgentEventBase {
+    eventId: string;
+    sequence: number;
+    timestamp: string;
+    sessionId: string;
+    executionId: string;
+    turnId?: string;
+}
+export interface CompactSnapshotAnchor {
+    readonly kind: 'message' | 'tool';
+    readonly id: string;
+}
+export type AgentEvent = AgentEventBase & ({
+    type: 'input.received';
+    entry: import('../session/user-history.js').AgentUserHistoryEntry;
+} | {
+    type: 'execution.started';
+    mode: ExecutionMode;
+    permissionMode?: import('../tools/permission-contract.js').PermissionMode;
+} | {
+    type: 'message.started';
+    itemId: string;
+    phase: 'commentary' | 'final_answer';
+} | {
+    type: 'message.delta';
+    itemId: string;
+    phase: 'commentary' | 'final_answer';
+    delta: string;
+} | {
+    type: 'message.completed';
+    itemId: string;
+    phase: 'commentary' | 'final_answer';
+    text: string;
+    modelId: string;
+    modelName: string;
+} | {
+    type: 'model.performance';
+    latencyMs?: number | undefined;
+    outputTokens?: number | undefined;
+    outputDurationMs?: number | undefined;
+    tokensPerSecond?: number | undefined;
+} | {
+    /** Legacy history event; new executions publish model.performance instead. */
+    type: 'message.performance';
+    itemId: string;
+    ttftMs: number;
+    outputTokens?: number | undefined;
+    outputDurationMs?: number | undefined;
+    tokensPerSecond?: number | undefined;
+} | {
+    type: 'plan.completed';
+    itemId: string;
+    text: string;
+} | {
+    type: 'reasoning.completed';
+    itemId: string;
+    representation: 'summary' | 'visible_thinking' | 'unspecified';
+    text: string;
+} | {
+    /** Legacy persisted event; the Catalog exposes standard tool events instead. */
+    type: 'hosted_tool.updated';
+    itemId: string;
+    kind: 'WEB_SEARCH' | 'WEB_FETCH';
+    status: 'RUNNING' | 'COMPLETED' | 'FAILED';
+    summary: {
+        query?: string | undefined;
+        url?: string | undefined;
+        title?: string | undefined;
+        sources?: readonly {
+            url: string;
+            title?: string | undefined;
+            snippet?: string | undefined;
+        }[] | undefined;
+        sourcesTruncated?: boolean | undefined;
+    };
+} | {
+    type: 'citation.added';
+    id: string;
+    url: string;
+    title?: string;
+} | {
+    type: 'tool.started';
+    toolName: string;
+    callId: string;
+    parentCallId?: string;
+    input?: unknown;
+    data?: import('./public-tool-metadata.js').PublicToolMetadata;
+    truncated?: boolean;
+} | {
+    type: 'tool.output';
+    toolName: 'exec' | 'exec_wait';
+    callId: string;
+    parentCallId?: string;
+    output: import('../tools/contracts.js').ExecOutputSnapshot;
+} | {
+    type: 'tool.completed';
+    resultExtensions?: readonly import('../tools/result-extension-contract.js').ToolResultExtension[];
+    toolName: string;
+    callId: string;
+    parentCallId?: string;
+    summary: string;
+    truncated?: boolean;
+    artifacts?: readonly AgentToolArtifact[];
+    data?: CodeCellEventData | import('../tools/contracts.js').ExecResult | Omit<import('../tools/contracts.js').ExecResult, 'stdout' | 'stderr'> | import('../tools/contracts.js').ApplyPatchResult | import('../tools/contracts.js').ReadEventData | import('../tools/contracts.js').ViewImageResult | import('../subagent/contracts.js').SubagentTaskSnapshot | import('../subagent/contracts.js').SubagentManyOutput | import('../tools/contracts.js').SleepResult | import('./public-tool-metadata.js').PublicToolMetadata;
+} | {
+    type: 'tool.failed';
+    resultExtensions?: readonly import('../tools/result-extension-contract.js').ToolResultExtension[];
+    data?: CodeCellEventData | import('../tools/contracts.js').ApplyPatchPartialResult;
+    toolName: string;
+    callId: string;
+    parentCallId?: string;
+    code: string;
+    message?: string;
+    permissionStop?: import('../tools/permission-contract.js').PermissionStop;
+    truncated?: boolean;
+} | {
+    type: 'sleep.started';
+    callId: string;
+    durationMs: number;
+    startedAt: string;
+} | {
+    type: 'usage.updated';
+    purpose?: 'compact';
+    inputTokens?: number | undefined;
+    contextInputTokens?: number | undefined;
+    outputTokens?: number | undefined;
+    cacheReadTokens?: number | undefined;
+    cacheWriteTokens?: number | undefined;
+} | {
+    type: 'todo.updated';
+    revision: number;
+    items: readonly import('../tools/contracts.js').TodoItem[];
+} | {
+    type: 'user_input.requested';
+    requestId: string;
+    questions: unknown[];
+} | {
+    type: 'user_input.resolved';
+    requestId: string;
+} | {
+    type: 'subagent.started';
+    agentId: string;
+    description: string;
+    modelId?: string;
+    modelName?: string;
+    reasoningEffort?: AgentReasoningEffort;
+} | {
+    type: 'subagent.completed';
+    permissionStop?: import('../tools/permission-contract.js').PermissionStop;
+    agentId: string;
+    description?: string;
+    status: string;
+    modelId?: string;
+    modelName?: string;
+    reasoningEffort?: AgentReasoningEffort;
+    latestMessage?: import('../subagent/contracts.js').SubagentLatestMessage;
+    latestActivity?: import('../subagent/contracts.js').SubagentLatestActivity;
+    errorCode?: string;
+    errorMessage?: string;
+} | {
+    type: 'execution.completed';
+    permissionStop?: import('../tools/permission-contract.js').PermissionStop;
+} | {
+    type: 'execution.failed';
+    code: string;
+    message?: string;
+} | {
+    type: 'execution.cancelled';
+} | {
+    type: 'context.compacting';
+    compactionId: string;
+    async?: boolean;
+    stage?: 'GENERATING' | 'READY' | 'WAITING';
+    anchorRecordId?: string;
+    anchor?: CompactSnapshotAnchor;
+} | {
+    type: 'context.compacted';
+    compactionId: string;
+    async?: boolean;
+    retainedContext?: boolean;
+    anchorRecordId?: string;
+    anchor?: CompactSnapshotAnchor;
+} | {
+    type: 'context.compact_failed';
+    compactionId: string;
+    code: string;
+    async?: boolean;
+    cancelled?: boolean;
+    anchorRecordId?: string;
+    anchor?: CompactSnapshotAnchor;
+});
+export type EventPayload<T = AgentEvent> = T extends AgentEvent ? Omit<T, 'eventId' | 'sequence' | 'timestamp' | 'sessionId' | 'executionId' | 'turnId'> : never;

package/dist/runtime/execution-handle.d.ts

@@ -0,0 +1,12 @@
+import type { ExecutionResult, RunInput } from './contracts.js';
+import type { AgentEvent } from './events.js';
+/** A live execution exposes streamed events separately from its terminal result. */
+export interface ExecutionHandle extends AsyncIterable<AgentEvent> {
+    readonly executionId: string;
+    result(): Promise<ExecutionResult>;
+    /** Signals abort; await result() to observe the terminal status and cleanup. */
+    cancel(): void;
+}
+export type CompactInput = Partial<RunInput> & {
+    readonly async?: boolean;
+};

package/dist/runtime/execution-handle.js

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

package/dist/runtime/execution.d.ts

@@ -0,0 +1,55 @@
+import type { SessionModelMessage as ModelMessage } from '../session/model-request.js';
+import type { SessionModelRequest as ModelRequest } from '../session/model-request.js';
+import type { AgentModelConfiguration } from '../model/configuration.js';
+import type { ModelEvent, ModelUsage } from '../model/contracts.js';
+import type { ClientToolCall, ExecutedToolCall } from './tool-round-contract.js';
+import type { AuthoritativeModelUsage } from './context/usage.js';
+import type { ExecutionMode } from './contracts.js';
+import type { EventPayload } from './events.js';
+export interface PreparedExecutionRound<TScope = unknown> {
+    readonly request: ModelRequest;
+    readonly toolScope: TScope;
+}
+/** Internal execution-local ports. No Session/Agent object, OS handles or terminal publisher. */
+export interface ExecutionLoopInput<TScope = unknown> {
+    readonly permissionStop?: () => import('../tools/permission-contract.js').PermissionStop | undefined;
+    readonly mode: ExecutionMode;
+    readonly sourceType: 'user' | 'subagent';
+    readonly signal: AbortSignal;
+    readonly model: Pick<AgentModelConfiguration, 'id' | 'name'>;
+    readonly messages: ModelMessage[];
+    readonly toolImages: {
+        readonly mimeType: string;
+        readonly data: Buffer;
+    }[];
+    readonly publish: (event: EventPayload) => Promise<void>;
+    readonly appendContext: (message: ModelMessage) => Promise<void>;
+    readonly prepareRound: (continuation: ModelMessage | undefined) => Promise<PreparedExecutionRound<TScope>>;
+    readonly runTools: (calls: readonly ClientToolCall[], scope: TScope) => Promise<ExecutedToolCall[]>;
+    readonly startModel: (request: ModelRequest) => AsyncIterable<ModelEvent>;
+    readonly recoverySignal: () => AbortSignal;
+    readonly compactContext: () => Promise<boolean>;
+    readonly compactionFallback?: (() => boolean) | undefined;
+    readonly observeUsage: (usage: Omit<AuthoritativeModelUsage, 'historyMessages'> | undefined) => void;
+    readonly observeContextTokens: (tokens: number) => void;
+    readonly afterModel?: (closedPrefixLength: number, acceptedRequest?: ModelRequest) => Promise<void>;
+    readonly checkpoint: (round: PreparedExecutionRound<TScope>, usage: ModelUsage | undefined) => Promise<void>;
+    readonly mailbox: {
+        hasPending(): boolean;
+        append(): Promise<boolean>;
+        close(): void;
+    };
+}
+/** Own the single model/tool loop; the SDK owns its handle, terminal events and cleanup. */
+export declare class ExecutionLoop<TScope = unknown> {
+    #private;
+    private readonly input;
+    private readonly planOutputPrefixes;
+    get finalAnswer(): string;
+    private set finalAnswer(value);
+    constructor(input: ExecutionLoopInput<TScope>);
+    run(): Promise<{
+        finalAnswer: string;
+        usage?: ModelUsage;
+    }>;
+}