@myagentroam/agent 0.11.33 → 0.11.34

package/dist/tools/permission-contract.d.ts

@@ -0,0 +1,25 @@
+export type PermissionMode = 'auto' | 'full-access';
+export interface ToolPermission {
+    action: 'allow' | 'ask' | 'deny';
+    reason?: string | null;
+}
+export interface PermissionStop {
+    action: 'ask' | 'deny';
+    reason: string;
+    source: {
+        sessionId: string;
+        executionId: string;
+        callId: string;
+        toolName: string;
+        parentCallId?: string;
+    };
+}
+export interface ToolApprovalRequest {
+    readonly approvalId: string;
+    readonly reason: string;
+    readonly source: PermissionStop['source'];
+    readonly input: unknown;
+    readonly expiresAt: number;
+}
+export type ToolApprovalDecision = 'APPROVED' | 'REJECTED';
+export type ToolApprovalHandler = (request: ToolApprovalRequest, signal: AbortSignal) => Promise<ToolApprovalDecision>;

package/dist/tools/permission-contract.js

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

package/dist/tools/permissions.d.ts

@@ -0,0 +1,61 @@
+import { AgentError } from '../error.js';
+import type { ClientToolDefinition, ToolCall } from './contracts.js';
+import type { PermissionMode, PermissionStop, ToolApprovalHandler } from './permission-contract.js';
+export type { PermissionMode, ToolPermission, PermissionStop, ToolApprovalRequest, ToolApprovalDecision, ToolApprovalHandler } from './permission-contract.js';
+type InvocationContext = {
+    sessionId: string;
+    executionId?: string;
+    actor: string;
+    entry?: string;
+    parentToolCallId?: string;
+    signal?: AbortSignal;
+};
+export declare const permissionSchema: {
+    type: string;
+    properties: {
+        action: {
+            type: string;
+            enum: string[];
+        };
+        reason: {
+            type: string;
+            description: string;
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare function resolvePermissionMode(value: unknown): PermissionMode;
+export declare function projectPermissionTool(tool: ClientToolDefinition): ClientToolDefinition;
+export declare class ToolPermissionStopError extends AgentError {
+    readonly permissionStop: PermissionStop;
+    constructor(permissionStop: PermissionStop);
+}
+/** One captured Execution's policy, including its retained tool frames. Not an authorization ledger. */
+export declare class ExecutionToolPermissions {
+    #private;
+    readonly mode: PermissionMode;
+    readonly identity: {
+        sessionId: string;
+        executionId: string;
+    };
+    private readonly approval?;
+    constructor(mode: PermissionMode, identity: {
+        sessionId: string;
+        executionId: string;
+    }, approval?: {
+        readonly request: ToolApprovalHandler;
+        readonly signal: AbortSignal;
+    } | undefined);
+    get stop(): PermissionStop | undefined;
+    assertDispatch(): void;
+    prepare(call: ToolCall, context: InvocationContext, tool: ClientToolDefinition): ToolCall;
+    authorize(call: ToolCall, context: InvocationContext): Promise<ToolCall>;
+}
+export declare function isToolPermissionFailure(error: unknown): boolean;
+export declare function withToolPermissions<T>(policy: ExecutionToolPermissions, run: () => T): T;
+export declare function currentToolPermissions(context?: {
+    sessionId: string;
+    executionId?: string;
+}): ExecutionToolPermissions | undefined;
+export declare function permissionStopFromError(error: unknown): PermissionStop | undefined;

package/dist/tools/permissions.js

@@ -0,0 +1,237 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { AgentError } from '../error.js';
+const permissionContext = new AsyncLocalStorage();
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const schemaKeys = new Set([
+    'type',
+    'properties',
+    'required',
+    'additionalProperties',
+    'description',
+    'title',
+    '$schema',
+    '$comment'
+]);
+export const permissionSchema = {
+    type: 'object',
+    properties: {
+        action: { type: 'string', enum: ['allow', 'ask', 'deny'] },
+        reason: {
+            type: 'string',
+            description: 'Brief public reason, required for ask/deny; never include secrets.'
+        }
+    },
+    required: ['action'],
+    additionalProperties: false
+};
+export function resolvePermissionMode(value) {
+    if (value === undefined)
+        return 'full-access';
+    if (value === 'auto' || value === 'full-access')
+        return value;
+    throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Permission mode must be auto or full-access.');
+}
+function flatInput(tool) {
+    const schema = tool.inputSchema;
+    return (schema.type === 'object' &&
+        schema.additionalProperties === false &&
+        record(schema.properties) &&
+        !Object.hasOwn(schema.properties, 'permission') &&
+        Object.keys(schema).every((key) => schemaKeys.has(key)));
+}
+export function projectPermissionTool(tool) {
+    const flat = flatInput(tool);
+    const parameterless = flat &&
+        Object.keys(tool.inputSchema.properties).length === 0 &&
+        (!Array.isArray(tool.inputSchema.required) || tool.inputSchema.required.length === 0);
+    return {
+        ...tool,
+        inputMode: 'json',
+        ...(parameterless ? { parameterless: true } : {}),
+        description: tool.description +
+            '\nAuto mode: use the declared JSON input. Omit permission (or set null) for routine or already authorized work. Use {action:"ask"|"deny",reason:"brief public reason"} only when required. ' +
+            (flat
+                ? 'Permission is metadata, not a business argument.'
+                : 'Place the unchanged business arguments in input; permission is separate metadata.'),
+        inputSchema: flat
+            ? {
+                ...tool.inputSchema,
+                properties: {
+                    ...tool.inputSchema.properties,
+                    permission: permissionSchema
+                }
+            }
+            : {
+                type: 'object',
+                properties: { input: tool.inputSchema, permission: permissionSchema },
+                required: ['input'],
+                additionalProperties: false
+            }
+    };
+}
+function parsePermission(value) {
+    if (value === undefined || value === null)
+        return;
+    if (!record(value) ||
+        Object.keys(value).some((key) => key !== 'action' && key !== 'reason') ||
+        !['allow', 'ask', 'deny'].includes(String(value.action)) ||
+        typeof value.action !== 'string' ||
+        (value.reason !== undefined && value.reason !== null && typeof value.reason !== 'string'))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Invalid tool permission declaration.');
+    const reason = typeof value.reason === 'string' ? value.reason.trim() : undefined;
+    if ((reason !== undefined && [...reason].length > 240) || (value.action !== 'allow' && !reason))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'ask/deny requires a public reason of 1 to 240 characters.');
+    return {
+        action: value.action,
+        ...(reason === undefined ? {} : { reason })
+    };
+}
+export class ToolPermissionStopError extends AgentError {
+    permissionStop;
+    constructor(permissionStop) {
+        super(permissionStop.action === 'ask' ? 'MAR_AGENT_PERMISSION_ASK' : 'MAR_AGENT_PERMISSION_DENIED', permissionStop.reason);
+        this.permissionStop = permissionStop;
+    }
+}
+/** One captured Execution's policy, including its retained tool frames. Not an authorization ledger. */
+export class ExecutionToolPermissions {
+    mode;
+    identity;
+    approval;
+    #stop;
+    constructor(mode, identity, approval) {
+        this.mode = mode;
+        this.identity = identity;
+        this.approval = approval;
+    }
+    get stop() {
+        return this.#stop;
+    }
+    assertDispatch() {
+        if (this.#stop)
+            throw new AgentError('MAR_AGENT_TOOL_SKIPPED_PERMISSION_STOP', 'Tool was not executed because this execution stopped for permission.');
+    }
+    prepare(call, context, tool) {
+        if (this.mode !== 'auto') {
+            if (call.permission !== undefined && call.permission !== null)
+                throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Framework permission metadata requires an Auto execution.');
+            return call;
+        }
+        this.assertDispatch();
+        let business = call.arguments;
+        let declaration = call.permission;
+        if (context.actor === 'model' || context.actor === 'code-mode') {
+            if (!record(business))
+                throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Auto tool input must be a JSON object.');
+            declaration = business.permission;
+            if (flatInput(tool)) {
+                const { permission: _permission, ...input } = business;
+                business = input;
+            }
+            else {
+                if (Object.keys(business).some((key) => key !== 'input' && key !== 'permission') ||
+                    !Object.hasOwn(business, 'input'))
+                    throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Auto input requires the original business arguments in input.');
+                business = business.input;
+            }
+        }
+        const permission = parsePermission(declaration);
+        const { permission: _permission, ...input } = call;
+        const prepared = { ...input, arguments: business };
+        if (permission?.action === 'ask' && this.approval)
+            return { ...prepared, permission };
+        if (permission && permission.action !== 'allow') {
+            const stop = Object.freeze({
+                action: permission.action,
+                reason: permission.reason,
+                source: Object.freeze({
+                    sessionId: this.identity.sessionId,
+                    executionId: this.identity.executionId,
+                    callId: call.callId ?? randomUUID(),
+                    toolName: call.name,
+                    ...(context.parentToolCallId === undefined
+                        ? {}
+                        : { parentCallId: context.parentToolCallId })
+                })
+            });
+            if (permission.action === 'ask')
+                this.#stop = stop;
+            throw new ToolPermissionStopError(stop);
+        }
+        return prepared;
+    }
+    async authorize(call, context) {
+        if (call.permission?.action !== 'ask' || !this.approval)
+            return call;
+        const { permission, ...captured } = structuredClone(call);
+        const timeout = new AbortController();
+        const signal = AbortSignal.any([
+            this.approval.signal,
+            ...(context.signal ? [context.signal] : []),
+            timeout.signal
+        ]);
+        signal.throwIfAborted();
+        const request = {
+            approvalId: `mar-agent:${randomUUID()}`,
+            reason: permission.reason,
+            source: {
+                ...this.identity,
+                callId: call.callId ?? randomUUID(),
+                toolName: call.name,
+                ...(context.parentToolCallId ? { parentCallId: context.parentToolCallId } : {})
+            },
+            input: structuredClone(captured.arguments),
+            expiresAt: Date.now() + 10 * 60_000
+        };
+        const timer = setTimeout(() => timeout.abort(new AgentError('MAR_AGENT_APPROVAL_EXPIRED', 'Approval expired after 10 minutes without authorizing the tool call.')), 10 * 60_000);
+        timer.unref();
+        let abort = () => { };
+        try {
+            const decision = await new Promise((resolve, reject) => {
+                abort = () => reject(signal.reason);
+                signal.addEventListener('abort', abort, { once: true });
+                Promise.resolve()
+                    .then(() => {
+                    signal.throwIfAborted();
+                    return this.approval.request(request, signal);
+                })
+                    .then(resolve, reject);
+            });
+            signal.throwIfAborted();
+            if (Date.now() >= request.expiresAt)
+                throw new AgentError('MAR_AGENT_APPROVAL_EXPIRED', 'Approval expired after 10 minutes without authorizing the tool call.');
+            if (decision !== 'APPROVED')
+                throw new AgentError('MAR_AGENT_APPROVAL_REJECTED', `User rejected this tool call: ${permission.reason}`);
+            this.assertDispatch();
+            return captured;
+        }
+        finally {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+        }
+    }
+}
+export function isToolPermissionFailure(error) {
+    return (permissionStopFromError(error)?.action === 'deny' ||
+        (error instanceof AgentError &&
+            ['MAR_AGENT_APPROVAL_REJECTED', 'MAR_AGENT_APPROVAL_EXPIRED'].includes(error.code)));
+}
+export function withToolPermissions(policy, run) {
+    return permissionContext.run(policy, run);
+}
+export function currentToolPermissions(context) {
+    const policy = permissionContext.getStore();
+    return policy &&
+        (!context ||
+            (policy.identity.sessionId === context.sessionId &&
+                policy.identity.executionId === context.executionId))
+        ? policy
+        : undefined;
+}
+export function permissionStopFromError(error) {
+    for (let depth = 0; depth < 5 && error instanceof Error; depth++, error = error.cause)
+        if (error instanceof ToolPermissionStopError)
+            return error.permissionStop;
+    return;
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,7 @@
+import type { ClientToolDefinition } from './contracts.js';
+import type { ToolExecutionResult } from './contracts.js';
+import type { ToolRuntimeContext } from './runtime-context.js';
+export declare const BUILTIN_TOOL_DEFINITIONS: readonly ClientToolDefinition[];
+type RuntimeHandler = (arguments_: unknown, context: ToolRuntimeContext, callId: string) => Promise<ToolExecutionResult>;
+export declare const AGENT_TOOL_HANDLERS: ReadonlyMap<string, RuntimeHandler>;
+export {};

package/dist/tools/result-extension-contract.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+export declare const fileChangesExtensionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"file_changes">;
+    version: z.ZodLiteral<1>;
+    entries: z.ZodArray<z.ZodObject<{
+        changeId: z.ZodString;
+        path: z.ZodString;
+        change: z.ZodEnum<{
+            added: "added";
+            modified: "modified";
+            deleted: "deleted";
+        }>;
+        additions: z.ZodNullable<z.ZodNumber>;
+        deletions: z.ZodNullable<z.ZodNumber>;
+        diff: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            status: z.ZodLiteral<"available">;
+            resourceRef: z.ZodString;
+            format: z.ZodLiteral<"unified-diff">;
+            byteSize: z.ZodNumber;
+            sha256: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            status: z.ZodLiteral<"unavailable">;
+            reason: z.ZodEnum<{
+                "unsupported-content": "unsupported-content";
+                "limit-exceeded": "limit-exceeded";
+                "capture-failed": "capture-failed";
+                "storage-failed": "storage-failed";
+            }>;
+        }, z.core.$strip>], "status">;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ToolResultExtension = z.infer<typeof fileChangesExtensionSchema>;
+export type FileChangeEvidence = ToolResultExtension['entries'][number];
+export type AvailableToolResultResource = Extract<FileChangeEvidence['diff'], {
+    status: 'available';
+}>;
+export type ToolResultResourceWriter = (text: string) => Promise<AvailableToolResultResource>;

package/dist/tools/result-extension-contract.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+const diffSchema = z.discriminatedUnion('status', [
+    z.object({
+        status: z.literal('available'),
+        resourceRef: z.string().uuid(),
+        format: z.literal('unified-diff'),
+        byteSize: z
+            .number()
+            .int()
+            .nonnegative()
+            .max(16 * 1024 * 1024),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u)
+    }),
+    z.object({
+        status: z.literal('unavailable'),
+        reason: z.enum(['unsupported-content', 'limit-exceeded', 'capture-failed', 'storage-failed'])
+    })
+]);
+export const fileChangesExtensionSchema = z.object({
+    type: z.literal('file_changes'),
+    version: z.literal(1),
+    entries: z
+        .array(z.object({
+        changeId: z.string().uuid(),
+        path: z.string().min(1).max(8192),
+        change: z.enum(['added', 'modified', 'deleted']),
+        additions: z.number().int().nonnegative().nullable(),
+        deletions: z.number().int().nonnegative().nullable(),
+        diff: diffSchema
+    }))
+        .max(200)
+});

package/dist/tools/result-extensions.d.ts

@@ -0,0 +1,12 @@
+import type { ToolExecutionResult } from './contracts.js';
+import { type ToolResultExtension, type ToolResultResourceWriter } from './result-extension-contract.js';
+export { fileChangesExtensionSchema } from './result-extension-contract.js';
+export type { ToolResultExtension, FileChangeEvidence, AvailableToolResultResource, ToolResultResourceWriter } from './result-extension-contract.js';
+export declare function parseToolResultExtensions(value: unknown): ToolResultExtension[] | undefined;
+export declare function failedToolResultExtensions(error: unknown): ToolResultExtension[] | undefined;
+/** Reserve a complete invocation's descriptors before any leaf commits, including wrapped calls. */
+export declare function reserveFileChangePaths(paths: readonly string[]): void;
+/** Only the SDK's real file commit calls this producer; arbitrary result fields are ignored. */
+export declare function captureFileChange(path: string, before?: Buffer, after?: Buffer): Promise<void>;
+/** Own a physical invocation, including all real leaf effects retained across wrappers. */
+export declare function withToolResultExtensions(write: ToolResultResourceWriter | undefined, run: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>;

package/dist/tools/result-extensions.js

@@ -0,0 +1,104 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { AgentError } from '../error.js';
+import { createFileDiff, FileDiffLimitError } from './file-change-diff.js';
+import { fileChangesExtensionSchema } from './result-extension-contract.js';
+export { fileChangesExtensionSchema } from './result-extension-contract.js';
+export function parseToolResultExtensions(value) {
+    if (!Array.isArray(value) || value.length > 16)
+        return undefined;
+    const extensions = [];
+    const ids = new Set();
+    for (const input of value) {
+        const parsed = fileChangesExtensionSchema.safeParse(input);
+        if (!parsed.success || extensions.some((entry) => entry.type === parsed.data.type))
+            continue;
+        if (new Set(parsed.data.entries.map((entry) => entry.changeId)).size !==
+            parsed.data.entries.length ||
+            parsed.data.entries.some((entry) => ids.has(entry.changeId)))
+            continue;
+        parsed.data.entries.forEach((entry) => ids.add(entry.changeId));
+        extensions.push(parsed.data);
+    }
+    return extensions.length && Buffer.byteLength(JSON.stringify(extensions)) <= 1024 * 1024
+        ? extensions
+        : undefined;
+}
+const capture = new AsyncLocalStorage();
+const failures = new WeakMap();
+export function failedToolResultExtensions(error) {
+    return error !== null && typeof error === 'object' ? failures.get(error) : undefined;
+}
+/** Reserve a complete invocation's descriptors before any leaf commits, including wrapped calls. */
+export function reserveFileChangePaths(paths) {
+    const context = capture.getStore();
+    const entries = (context?.reservedEntries ?? 0) + paths.length;
+    const bytes = (context?.descriptorBytes ?? 256) +
+        paths.reduce((sum, path) => sum + Buffer.byteLength(JSON.stringify(path)) + 512, 0);
+    if (entries > 200 || bytes > 1024 * 1024 || paths.some((path) => path.length > 8192))
+        throw new AgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Patch paths exceed the file evidence descriptor limit.');
+    if (context) {
+        context.reservedEntries = entries;
+        context.descriptorBytes = bytes;
+    }
+}
+/** Only the SDK's real file commit calls this producer; arbitrary result fields are ignored. */
+export async function captureFileChange(path, before, after) {
+    const context = capture.getStore();
+    if (!context)
+        return;
+    const entry = {
+        changeId: randomUUID(),
+        path,
+        change: before === undefined ? 'added' : after === undefined ? 'deleted' : 'modified',
+        additions: null,
+        deletions: null,
+        diff: { status: 'unavailable', reason: 'capture-failed' }
+    };
+    context.entries.push(entry);
+    try {
+        const diff = createFileDiff(path, before, after);
+        if (!diff) {
+            entry.diff = { status: 'unavailable', reason: 'unsupported-content' };
+            return;
+        }
+        entry.additions = diff.additions;
+        entry.deletions = diff.deletions;
+        context.bytes += Buffer.byteLength(diff.text);
+        if (context.bytes > 32 * 1024 * 1024)
+            entry.diff = { status: 'unavailable', reason: 'limit-exceeded' };
+        else if (context.write)
+            entry.diff = await context.write(diff.text);
+        else
+            entry.diff = { status: 'unavailable', reason: 'storage-failed' };
+    }
+    catch (error) {
+        entry.diff = {
+            status: 'unavailable',
+            reason: error instanceof FileDiffLimitError ? 'limit-exceeded' : 'storage-failed'
+        };
+    }
+}
+/** Own a physical invocation, including all real leaf effects retained across wrappers. */
+export async function withToolResultExtensions(write, run) {
+    const context = {
+        entries: [],
+        bytes: 0,
+        reservedEntries: 0,
+        descriptorBytes: 256,
+        ...(write ? { write } : {})
+    };
+    return capture.run(context, async () => {
+        const extensions = () => parseToolResultExtensions([{ type: 'file_changes', version: 1, entries: context.entries }]);
+        try {
+            const { resultExtensions: _ignored, ...result } = await run();
+            const resultExtensions = context.entries.length ? extensions() : undefined;
+            return resultExtensions ? { ...result, resultExtensions } : result;
+        }
+        catch (error) {
+            if (context.entries.length && error !== null && typeof error === 'object')
+                failures.set(error, extensions());
+            throw error;
+        }
+    });
+}

package/dist/tools/runtime-context.d.ts

@@ -0,0 +1,89 @@
+import type { ResourcePublisher, ResourceStore } from '../runtime/resource-publication.js';
+import type { ExecutionMode } from '../runtime/contracts.js';
+import type { AgentSkill } from '../runtime/context/instructions.js';
+import type { SubagentController, SubagentLatestMessage } from '../subagent/contracts.js';
+import type { TodoStore } from './agent/todo.js';
+import type { McpToolCallContext, ToolCall, ToolExecutionContext, ToolExecutionResult } from './contracts.js';
+export interface ToolHost extends ResourcePublisher {
+    executeTool(call: ToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    requestUserInput?(input: {
+        requestId: string;
+        questions: unknown[];
+    }, signal: AbortSignal): Promise<Record<string, unknown>>;
+    callMcpTool?(call: ToolCall, signal: AbortSignal, context?: McpToolCallContext): Promise<ToolExecutionResult>;
+}
+export interface ToolImageStore extends ResourceStore {
+    readResource(sessionId: string, resourceId: string): Promise<{
+        mimeType: string;
+        dataBase64: string;
+    } | undefined>;
+}
+export type ToolRuntimeEvent = {
+    type: 'tool.output';
+    toolName: 'exec' | 'exec_wait';
+    callId: string;
+    parentCallId?: string;
+    output: import('./contracts.js').ExecOutputSnapshot;
+} | {
+    type: 'sleep.started';
+    callId: string;
+    durationMs: number;
+    startedAt: string;
+} | {
+    type: 'todo.updated';
+    revision: number;
+    items: readonly import('./agent/todo.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?: import('../model/configuration.js').AgentReasoningEffort;
+} | {
+    type: 'subagent.completed';
+    agentId: string;
+    description: string;
+    status: string;
+    modelId?: string;
+    modelName?: string;
+    reasoningEffort?: import('../model/configuration.js').AgentReasoningEffort;
+    latestMessage?: SubagentLatestMessage;
+    errorCode?: string;
+    errorMessage?: string;
+};
+export interface ToolRuntimeImage {
+    readonly mimeType: string;
+    readonly data: Buffer;
+}
+export interface ToolRuntimeContext {
+    host: ToolHost;
+    imageStore?: ToolImageStore;
+    todo: TodoStore;
+    requestSmartCompact?: () => void;
+    subagents?: SubagentController;
+    mode: ExecutionMode;
+    sessionId: string;
+    executionId: string;
+    modelId?: string;
+    signal: AbortSignal;
+    waitInterrupt?: import('./wait.js').ToolWaitInterrupt | undefined;
+    subagentMessages?: import('./wait.js').ToolWaitInterrupt;
+    permissionPolicy?: import('./permissions.js').ExecutionToolPermissions;
+    parentCallId?: string;
+    writeToolResultResource?: import('./result-extensions.js').ToolResultResourceWriter;
+    codeMode?: import('./contracts.js').ToolExecutionContext['codeMode'];
+    skills: ReadonlyMap<string, AgentSkill>;
+    recentImages?: readonly ToolRuntimeImage[];
+    searchMcpTools?: (input: unknown, signal: AbortSignal) => Promise<import('./contracts.js').ToolExecutionResult>;
+    expectedMcpTool?: import('./contracts.js').McpToolCallContext['expectedTool'];
+    invokeTool?: (call: import('./contracts.js').ToolCall, context: ToolRuntimeContext, caller: import('./contracts.js').ToolCaller) => Promise<import('./contracts.js').ToolExecutionResult>;
+    emit(event: ToolRuntimeEvent): Promise<void>;
+}

package/dist/tools/runtime-context.js

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

package/dist/tools/runtime-resource-handles.js

@@ -0,0 +1,28 @@
+import { randomBytes } from 'node:crypto';
+import { AgentError } from '../error.js';
+const types = {
+    cell: { prefix: 'c_', field: 'cellId', tool: 'code_exec_wait' },
+    process: { prefix: 'p_', field: 'processId', tool: 'exec_wait' }
+};
+/** Typed runtime handles; resource owners retain registration and lifecycle authority. */
+export class RuntimeResourceHandles {
+    kind;
+    isReserved;
+    constructor(kind, isReserved) {
+        this.kind = kind;
+        this.isReserved = isReserved;
+    }
+    create() {
+        let id;
+        do {
+            id = `${types[this.kind].prefix}${randomBytes(6).toString('hex')}`;
+        } while (this.isReserved(id));
+        return id;
+    }
+    assertType(id) {
+        const expected = types[this.kind];
+        const actual = Object.values(types).find((type) => id.startsWith(type.prefix));
+        if (actual && actual !== expected)
+            throw new AgentError('MAR_AGENT_RESOURCE_HANDLE_TYPE_MISMATCH', `Expected ${expected.field} (${expected.prefix}...). This looks like ${actual.field}; use ${actual.tool} for that resource.`, { details: { expected: expected.field, received: actual.field, tool: actual.tool } });
+    }
+}