@myagentroam/agent 0.11.32 → 0.11.34

package/dist/tools/agent/sleep.d.ts

@@ -0,0 +1,9 @@
+import type { ClientToolDefinition } from '../contracts.js';
+import type { ToolRuntimeContext } from '../runtime-context.js';
+import type { SleepResult } from '../contracts.js';
+export type { SleepResult } from '../contracts.js';
+export declare const sleepToolDefinition: ClientToolDefinition;
+export declare function executeSleep(arguments_: unknown, context: ToolRuntimeContext, callId: string): Promise<{
+    content: string;
+    data: SleepResult;
+}>;

package/dist/tools/agent/sleep.js

@@ -0,0 +1,54 @@
+import { AgentError } from '../../error.js';
+import { TOOL_EXECUTION_LIMITS } from '../execution-limits.js';
+import { waitForToolCondition } from '../wait.js';
+export const sleepToolDefinition = {
+    name: 'sleep',
+    allowedCallers: ['direct'],
+    parallelSafety: 'serial',
+    description: 'Pause for up to durationMs milliseconds. Returns early when user input or a new public subagent message is available. Returns elapsed time and the wake reason.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            durationMs: {
+                type: 'integer',
+                minimum: 1,
+                maximum: TOOL_EXECUTION_LIMITS.sleepMaxDurationMs
+            }
+        },
+        required: ['durationMs'],
+        additionalProperties: false
+    }
+};
+export async function executeSleep(arguments_, context, callId) {
+    const durationMs = arguments_ && typeof arguments_ === 'object' && !Array.isArray(arguments_)
+        ? arguments_.durationMs
+        : undefined;
+    if (typeof durationMs !== 'number' ||
+        !Number.isInteger(durationMs) ||
+        durationMs < 1 ||
+        durationMs > TOOL_EXECUTION_LIMITS.sleepMaxDurationMs)
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Sleep duration is out of range.');
+    context.signal.throwIfAborted();
+    const started = performance.now();
+    await context.emit({
+        type: 'sleep.started',
+        callId,
+        durationMs,
+        startedAt: new Date().toISOString()
+    });
+    const messages = context.subagentMessages;
+    const outcome = await waitForToolCondition({
+        ready: () => messages?.pending() ?? false,
+        subscribe: (notify) => messages?.subscribe(notify) ?? (() => { }),
+        waitMs: Math.max(0, durationMs - (performance.now() - started)),
+        signal: context.signal,
+        interrupt: context.waitInterrupt
+    });
+    context.signal.throwIfAborted();
+    const data = {
+        durationMs,
+        elapsedMs: Math.round(performance.now() - started),
+        wakeReason: outcome === 'ready' ? 'subagent_message' : outcome === 'interrupted' ? 'steer' : 'elapsed'
+    };
+    return { content: JSON.stringify(data), data };
+}

package/dist/tools/agent/smart-compact.d.ts

@@ -0,0 +1,9 @@
+import type { ClientToolDefinition } from '../contracts.js';
+import type { ToolRuntimeContext } from '../runtime-context.js';
+export declare const smartCompactToolDefinition: ClientToolDefinition;
+export declare function executeSmartCompact(arguments_: unknown, context: ToolRuntimeContext): Promise<{
+    content: string;
+    data: {
+        status: string;
+    };
+}>;

package/dist/tools/agent/smart-compact.js

@@ -0,0 +1,23 @@
+import { AgentError } from '../../error.js';
+import { SMART_COMPACTION_MARKER } from '../../runtime/compaction/smart.js';
+export const smartCompactToolDefinition = {
+    name: 'smart_compact',
+    allowedCallers: ['direct', 'programmatic'],
+    parallelSafety: 'safe',
+    description: 'Request background context compaction only when the current real user message includes this runtime note: ' +
+        SMART_COMPACTION_MARKER +
+        ' The note indicates capacity eligibility, not a recommendation; historical notes do not qualify the current input. Judge the phase transition from the conversation; call only if key state can be retained in a summary. Do not call merely because context is long, for a one-off question, or while continuing unresolved work that still needs prior evidence. A new user message or completed reply alone is not a phase transition. If uncertain, skip. Prefer calling alongside the first necessary tools. Acceptance does not wait for generation or installation.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false }
+};
+export function executeSmartCompact(arguments_, context) {
+    if (!arguments_ ||
+        typeof arguments_ !== 'object' ||
+        Array.isArray(arguments_) ||
+        Object.keys(arguments_).length)
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Smart Compaction input must be an empty object.');
+    if (!context.requestSmartCompact)
+        throw new AgentError('MAR_AGENT_SMART_COMPACT_DENIED', 'The current user input is not eligible for Smart Compaction.');
+    context.requestSmartCompact();
+    const data = { status: 'accepted' };
+    return Promise.resolve({ content: JSON.stringify(data), data });
+}

package/dist/tools/agent/todo-read.d.ts

@@ -0,0 +1,14 @@
+import type { ClientToolDefinition } from '../contracts.js';
+import type { ToolRuntimeContext } from '../runtime-context.js';
+export declare const todoReadToolDefinition: ClientToolDefinition;
+export declare function executeTodoRead(context: ToolRuntimeContext): Promise<{
+    content: string;
+    data: {
+        revision: number;
+        items: {
+            id: string;
+            step: string;
+            status: "pending" | "in_progress" | "completed";
+        }[];
+    };
+}>;

package/dist/tools/agent/todo-write.d.ts

@@ -0,0 +1,14 @@
+import type { ClientToolDefinition } from '../contracts.js';
+import type { ToolRuntimeContext } from '../runtime-context.js';
+export declare const todoWriteToolDefinition: ClientToolDefinition;
+export declare function executeTodoWrite(arguments_: unknown, context: ToolRuntimeContext): Promise<{
+    content: string;
+    data: {
+        revision: number;
+        items: {
+            id: string;
+            step: string;
+            status: "pending" | "in_progress" | "completed";
+        }[];
+    };
+}>;

package/dist/tools/agent/todo-write.js

@@ -0,0 +1,66 @@
+import { AgentError } from '../../error.js';
+import { TOOL_EXECUTION_LIMITS } from '../execution-limits.js';
+export const todoWriteToolDefinition = {
+    name: 'todo_write',
+    allowedCallers: ['direct', 'programmatic'],
+    parallelSafety: 'serial',
+    description: 'Replace this session’s entire Todo list with the supplied items; no prior read is required. Preserve stable IDs and statuses only when extending the same objective. For a materially different objective, include only the new objective’s items. Do not retain completed items from an earlier objective; when all current items are completed, default a substantive new request to replacement unless the user explicitly asks to continue, extend, verify, or follow up. Use only after Todo has been chosen for coordination-heavy work; straightforward bounded work does not need it. Keep at most one in_progress item and update statuses after meaningful stage changes. When another substantive tool call is already ready and does not depend on the Todo result, include both in the same model response instead of spending a response only for Todo bookkeeping.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            items: {
+                type: 'array',
+                maxItems: TOOL_EXECUTION_LIMITS.todoMaxItems,
+                items: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        step: { type: 'string', maxLength: TOOL_EXECUTION_LIMITS.todoMaxTextCharacters },
+                        status: { enum: ['pending', 'in_progress', 'completed'] }
+                    },
+                    required: ['id', 'step', 'status'],
+                    additionalProperties: false
+                }
+            }
+        },
+        required: ['items'],
+        additionalProperties: false
+    }
+};
+export async function executeTodoWrite(arguments_, context) {
+    const value = parseTodoWriteInput(arguments_);
+    const todo = context.todo.write(value);
+    await context.emit({ type: 'todo.updated', revision: todo.revision, items: todo.items });
+    return {
+        content: JSON.stringify({ revision: todo.revision, count: todo.items.length }),
+        data: todo
+    };
+}
+function parseTodoWriteInput(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return invalid();
+    const input = value;
+    if (Object.keys(input).some((key) => key !== 'items') ||
+        !Array.isArray(input.items) ||
+        input.items.length > TOOL_EXECUTION_LIMITS.todoMaxItems)
+        return invalid();
+    const items = input.items.map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return invalid();
+        const record = item;
+        if (Object.keys(record).some((key) => !['id', 'step', 'status'].includes(key)) ||
+            typeof record.id !== 'string' ||
+            record.id.trim().length === 0 ||
+            record.id.length > 128 ||
+            typeof record.step !== 'string' ||
+            record.step.trim().length === 0 ||
+            record.step.length > TOOL_EXECUTION_LIMITS.todoMaxTextCharacters ||
+            !['pending', 'in_progress', 'completed'].includes(String(record.status)))
+            return invalid();
+        return { id: record.id, step: record.step, status: record.status };
+    });
+    return { items };
+}
+function invalid() {
+    throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Todo input is invalid.');
+}

package/dist/tools/agent/todo.d.ts

@@ -0,0 +1,25 @@
+import { type TodoItem, type TodoSnapshot } from '../../session/todo.js';
+export type { TodoItem, TodoSnapshot } from '../../session/todo.js';
+export declare class TodoStore {
+    #private;
+    static restore(snapshot: TodoSnapshot): TodoStore;
+    read(): {
+        revision: number;
+        items: {
+            id: string;
+            step: string;
+            status: "pending" | "in_progress" | "completed";
+        }[];
+    };
+    write(input: {
+        items: readonly TodoItem[];
+    }): {
+        revision: number;
+        items: {
+            id: string;
+            step: string;
+            status: "pending" | "in_progress" | "completed";
+        }[];
+    };
+}
+export declare function restoreTodoStore(snapshots: readonly unknown[]): TodoStore;

package/dist/tools/agent/todo.js

@@ -0,0 +1,32 @@
+import { AgentError } from '../../error.js';
+import { normalizeTodoItems, todoItemsFromSnapshot } from '../../session/todo.js';
+export class TodoStore {
+    #revision = 0;
+    #items = [];
+    static restore(snapshot) {
+        if (!Number.isSafeInteger(snapshot.revision) || snapshot.revision < 0)
+            throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Todo revision is invalid.');
+        const todo = new TodoStore();
+        todo.#revision = snapshot.revision;
+        todo.#items = normalizeTodoItems(snapshot.items);
+        return todo;
+    }
+    read() {
+        return { revision: this.#revision, items: this.#items.map((item) => ({ ...item })) };
+    }
+    write(input) {
+        this.#items = normalizeTodoItems(input.items);
+        this.#revision++;
+        return this.read();
+    }
+}
+export function restoreTodoStore(snapshots) {
+    const todo = new TodoStore();
+    for (const snapshot of snapshots) {
+        const items = todoItemsFromSnapshot(snapshot);
+        if (!items)
+            continue;
+        todo.write({ items });
+    }
+    return todo;
+}

package/dist/tools/callers.d.ts

@@ -0,0 +1,7 @@
+import type { ClientToolDefinition } from './contracts.js';
+import type { ToolCaller } from './contracts.js';
+/** Normalize trusted Host policy independently of discovery, Agent scope and parallel safety. */
+export declare function toolCallers(tool: ClientToolDefinition): readonly ToolCaller[];
+export declare function allowsToolCaller(tool: ClientToolDefinition, caller: ToolCaller): boolean;
+/** Code Mode Only changes model exposure, never the Host's underlying caller permissions. */
+export declare function allowsDirectTool(tool: ClientToolDefinition, codeModeEnabled: boolean): boolean;

package/dist/tools/callers.js

@@ -0,0 +1,39 @@
+import { AgentError } from '../error.js';
+/** Normalize trusted Host policy independently of discovery, Agent scope and parallel safety. */
+export function toolCallers(tool) {
+    if (tool.codeModeExposure !== undefined && tool.codeModeExposure !== 'both')
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Code Mode exposure is invalid.');
+    const value = tool.allowedCallers;
+    if (value === undefined)
+        return tool.name.startsWith('mcp__') ? ['direct', 'programmatic'] : ['direct'];
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.some((caller) => caller !== 'direct' && caller !== 'programmatic'))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Tool caller policy is invalid.');
+    return ['direct', 'programmatic'].filter((caller) => value.includes(caller));
+}
+export function allowsToolCaller(tool, caller) {
+    // Control tools cannot be widened by a Host override or historical definition.
+    if (caller === 'programmatic' &&
+        [
+            'code_exec',
+            'code_exec_wait',
+            'tool_search',
+            'question',
+            'skill',
+            'sleep',
+            'agent_start',
+            'agent_wait',
+            'agent_message',
+            'agent_cancel'
+        ].includes(tool.name))
+        return false;
+    return toolCallers(tool).includes(caller);
+}
+/** Code Mode Only changes model exposure, never the Host's underlying caller permissions. */
+export function allowsDirectTool(tool, codeModeEnabled) {
+    return (allowsToolCaller(tool, 'direct') &&
+        (!codeModeEnabled ||
+            tool.codeModeExposure === 'both' ||
+            !allowsToolCaller(tool, 'programmatic')));
+}

package/dist/tools/code-mode/cells.d.ts

@@ -0,0 +1,29 @@
+import { AgentError } from '../../error.js';
+import type { ToolExecutionContext, ToolExecutionResult } from '../contracts.js';
+import type { CodeObservation, CodeToolCallRecord } from '../../session/code-observation-contract.js';
+export interface CellOutput {
+    call(value: CodeToolCallRecord): void;
+    observe(value: CodeObservation): void;
+    text(value: string, originalBytes?: number): void;
+    image(value: NonNullable<ToolExecutionResult['images']>[number]): void;
+    yield(): void;
+}
+/** Keeps a failed tool call observable without discarding earlier explicit output. */
+export declare class CodeCellExecutionError extends AgentError {
+    readonly result: ToolExecutionResult;
+    constructor(error: unknown, result: ToolExecutionResult);
+}
+type Status = 'running' | 'completed' | 'failed' | 'cancelled';
+/** Session-owned execution, separate from the cancellable model-tool wait. */
+export declare class CodeCells {
+    #private;
+    start(value: unknown, context: ToolExecutionContext, run: (code: string, context: ToolExecutionContext, output: CellOutput) => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>;
+    wait(value: unknown, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    snapshot(sessionId: string): {
+        cellId: string;
+        status: Status;
+        executionId: string;
+    }[];
+    dispose(sessionId?: string): Promise<void>;
+}
+export {};