@myagentroam/agent 0.11.32 → 0.11.34

package/dist/session/tool-result-resources.js

@@ -0,0 +1,255 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AgentError } from '../error.js';
+import { parseToolResultExtensions } from '../tools/result-extensions.js';
+const REF = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u;
+const MAX_BYTES = 16 * 1024 * 1024;
+export async function writeToolResultResource(directory, text) {
+    const bytes = Buffer.from(text);
+    if (bytes.length > MAX_BYTES)
+        throw resourceError('LIMIT', 'Tool result resource exceeds its limit.');
+    const resourceRef = randomUUID();
+    const folder = join(directory, 'tool_results');
+    await mkdir(folder, { recursive: true, mode: 0o700 });
+    const temporary = join(folder, `.${resourceRef}.tmp`);
+    await writeFile(join(folder, `.${resourceRef}.pending`), '', {
+        flag: 'wx',
+        mode: 0o600,
+        flush: true
+    });
+    try {
+        await writeFile(temporary, bytes, { flag: 'wx', mode: 0o600, flush: true });
+        await rename(temporary, join(folder, `${resourceRef}.diff`));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return {
+        status: 'available',
+        resourceRef,
+        format: 'unified-diff',
+        byteSize: bytes.length,
+        sha256: createHash('sha256').update(bytes).digest('hex')
+    };
+}
+export function recordToolResources(record) {
+    if (!['tool.completed', 'tool.failed'].includes(record.type))
+        return [];
+    const payload = record.payload;
+    const sources = [
+        payload?.resultExtensions,
+        ...(Array.isArray(payload?.data?.calls)
+            ? payload.data.calls.map((call) => call.resultExtensions)
+            : [])
+    ];
+    return sources.flatMap((source) => (parseToolResultExtensions(source) ?? []).flatMap((extension) => extension.entries.flatMap((entry) => (entry.diff.status === 'available' ? [entry.diff] : []))));
+}
+/** A locator is only a hint: reads must verify its exact committed record identity. */
+export async function bindToolResultResources(directory, record, readRecord, degrade = false) {
+    for (const resource of recordToolResources(record)) {
+        try {
+            await bindToolResultResource(directory, record, resource, readRecord);
+        }
+        catch (error) {
+            if (!degrade)
+                throw error;
+            // Shared descriptors are downgraded before persistence and live publication, never the tool outcome.
+            const payload = record.payload;
+            for (const extensions of [
+                payload.resultExtensions,
+                ...(payload.data?.calls ?? []).map((call) => call.resultExtensions)
+            ]) {
+                for (const extension of extensions ?? [])
+                    for (const entry of extension.entries) {
+                        if (entry.diff.status === 'available' &&
+                            entry.diff.resourceRef === resource.resourceRef)
+                            entry.diff = { status: 'unavailable', reason: 'storage-failed' };
+                    }
+            }
+        }
+    }
+}
+async function bindToolResultResource(directory, record, resource, readRecord) {
+    const path = join(directory, 'tool_results', `${resource.resourceRef}.json`);
+    try {
+        await writeFile(path, JSON.stringify({ sequence: record.sequence, recordId: record.recordId }), { flag: 'wx', mode: 0o600, flush: true });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        try {
+            const locator = JSON.parse(await readFile(path, 'utf8'));
+            const existing = locator.sequence === record.sequence && locator.recordId === record.recordId
+                ? record
+                : Number.isSafeInteger(locator.sequence)
+                    ? await readRecord?.(locator.sequence)
+                    : undefined;
+            if (!existing ||
+                existing.recordId !== locator.recordId ||
+                !recordToolResources(existing).some((entry) => entry.resourceRef === resource.resourceRef && entry.sha256 === resource.sha256))
+                throw resourceError('CORRUPT', 'Tool resource locator conflicts with committed history.');
+        }
+        catch (cause) {
+            throw normalizedResourceError(cause);
+        }
+    }
+}
+export function toolResultResourceFiles(records) {
+    return new Set(records.flatMap((record) => recordToolResources(record).flatMap((resource) => [
+        `${resource.resourceRef}.diff`,
+        `${resource.resourceRef}.json`
+    ])));
+}
+export async function copyToolResultResources(source, target, records) {
+    const copied = new Set();
+    for (const record of records) {
+        for (const resource of recordToolResources(record)) {
+            if (copied.has(resource.resourceRef))
+                continue;
+            copied.add(resource.resourceRef);
+            try {
+                const bytes = await readResourceBytes(source, resource);
+                const directory = join(target, 'tool_results');
+                await mkdir(directory, { recursive: true, mode: 0o700 });
+                await writeFile(join(directory, `${resource.resourceRef}.diff`), bytes, {
+                    flag: 'wx',
+                    mode: 0o600,
+                    flush: true
+                });
+            }
+            catch (error) {
+                if (error instanceof AgentError && error.code === 'MAR_AGENT_TOOL_RESOURCE_NOT_FOUND')
+                    continue;
+                throw error;
+            }
+        }
+        if (recordToolResources(record).length) {
+            await mkdir(join(target, 'tool_results'), { recursive: true, mode: 0o700 });
+            await bindToolResultResources(target, record, async (sequence) => records.find((item) => item.sequence === sequence));
+        }
+    }
+}
+export async function completeToolResultResources(directory, record) {
+    await Promise.all(recordToolResources(record).map((resource) => rm(join(directory, 'tool_results', `.${resource.resourceRef}.pending`), {
+        force: true
+    }).catch(() => undefined)));
+}
+export async function cleanupUnreferencedToolResources(directory, readRecords) {
+    const folder = join(directory, 'tool_results');
+    let names;
+    try {
+        names = await readdir(folder);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const pending = names.filter((name) => name.startsWith('.') && name.endsWith('.pending') && REF.test(name.slice(1, -8)));
+    if (!pending.length)
+        return;
+    const retained = toolResultResourceFiles(await readRecords());
+    for (const marker of pending) {
+        const ref = marker.slice(1, -8);
+        for (const name of [`${ref}.diff`, `${ref}.json`, `.${ref}.tmp`]) {
+            if (retained.has(name))
+                continue;
+            const path = join(folder, name);
+            try {
+                if ((await lstat(path)).isFile())
+                    await rm(path);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        await rm(join(folder, marker), { force: true });
+    }
+}
+/** Caller must hold a stable history and resource generation for the entire read. */
+export async function readToolResultResource(directory, sessionId, input, readRecord) {
+    if (!REF.test(input.resourceRef) ||
+        (input.maxBytes !== undefined &&
+            (!Number.isSafeInteger(input.maxBytes) || input.maxBytes < 4 || input.maxBytes > 256 * 1024)))
+        throw resourceError('INPUT_INVALID', 'Invalid tool resource request.');
+    let locator;
+    try {
+        const file = join(directory, 'tool_results', `${input.resourceRef}.json`);
+        locator = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        throw normalizedResourceError(error);
+    }
+    if (!Number.isSafeInteger(locator.sequence) ||
+        locator.sequence < 1 ||
+        typeof locator.recordId !== 'string')
+        throw resourceError('CORRUPT', 'Invalid tool resource locator.');
+    const record = await readRecord(locator.sequence);
+    const resource = record?.recordId === locator.recordId
+        ? recordToolResources(record).find((entry) => entry.resourceRef === input.resourceRef)
+        : undefined;
+    if (!resource)
+        throw resourceError('NOT_FOUND', 'Tool resource is not part of this session history.');
+    const bytes = await readResourceBytes(directory, resource);
+    let offset = 0;
+    if (input.cursor !== undefined) {
+        try {
+            if (input.cursor.length > 1024)
+                throw new Error('cursor');
+            const cursor = JSON.parse(Buffer.from(input.cursor, 'base64url').toString('utf8'));
+            if (cursor.sessionId !== sessionId ||
+                cursor.ref !== resource.resourceRef ||
+                cursor.sha256 !== resource.sha256 ||
+                !Number.isSafeInteger(cursor.offset) ||
+                cursor.offset < 0 ||
+                cursor.offset >= bytes.length)
+                throw new Error('cursor');
+            offset = cursor.offset;
+        }
+        catch {
+            throw resourceError('INPUT_INVALID', 'Invalid tool resource cursor.');
+        }
+    }
+    if (offset > 0 && (bytes[offset] & 0xc0) === 0x80)
+        throw resourceError('INPUT_INVALID', 'Invalid tool resource cursor boundary.');
+    let end = Math.min(bytes.length, offset + (input.maxBytes ?? 256 * 1024));
+    while (end < bytes.length && (bytes[end] & 0xc0) === 0x80)
+        end--;
+    return {
+        type: 'file_changes',
+        version: 1,
+        format: resource.format,
+        resourceRef: resource.resourceRef,
+        byteSize: resource.byteSize,
+        sha256: resource.sha256,
+        content: bytes.subarray(offset, end).toString('utf8'),
+        ...(end < bytes.length
+            ? {
+                nextCursor: Buffer.from(JSON.stringify({
+                    sessionId,
+                    ref: resource.resourceRef,
+                    sha256: resource.sha256,
+                    offset: end
+                })).toString('base64url')
+            }
+            : {})
+    };
+}
+async function readResourceBytes(directory, resource) {
+    try {
+        return await readFile(join(directory, 'tool_results', `${resource.resourceRef}.diff`));
+    }
+    catch (error) {
+        throw normalizedResourceError(error);
+    }
+}
+function resourceError(suffix, message) {
+    return new AgentError(`MAR_AGENT_TOOL_RESOURCE_${suffix}`, message);
+}
+function normalizedResourceError(error) {
+    if (error instanceof AgentError)
+        return error;
+    return resourceError(error?.code === 'ENOENT' ? 'NOT_FOUND' : 'CORRUPT', 'Tool result resource is unavailable.');
+}

package/dist/session/types.js

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

package/dist/session/user-history.d.ts

@@ -0,0 +1,17 @@
+import type { AgentImageMetadata } from '../runtime/contracts.js';
+export interface AgentSessionHistoryImageMetadata extends AgentImageMetadata {
+    readable: boolean;
+}
+export type AgentUserHistoryEntry = {
+    kind: 'user';
+    recordId?: string;
+    sequence: number;
+    timestamp: string;
+    sessionId: string;
+    executionId: string;
+    turnId: string;
+    text: string;
+    clientMessageId?: string;
+    inputSource?: 'user' | 'parent_agent';
+    images?: readonly AgentSessionHistoryImageMetadata[];
+};

package/dist/session/user-history.js

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

package/dist/session-store.d.ts

@@ -0,0 +1,2 @@
+export type { ExtensionCheckpoint, ExtensionJsonValue } from './session/extension-checkpoint.js';
+export type { AvailableToolResultResource, CodeModeStateEntry, CodeObservation, CodeToolCallRecord, CompactHistoryMessage, CompactUserInput, ContextGcBase, ContextGcCheckpointDraft, ContextGcEconomicsPolicy, ContextGcMetrics, ContextGcPlatform, ContextGcReadItemReplacement, ContextGcReplacement, ContextGcSubagentToolName, ContextGcTarget, ContextGcWebToolName, EnvironmentContextState, ModelContextualBlock, ModelInputMetadata, ModelMessage, ModelTextBlock, ModelUsage, RestoredSessionInputImage, SessionExecutionState, SessionInputImage, SessionInputImageData, SessionInputImageMetadata, SessionRecord, SessionRecordInput, SessionResource, SessionStore, SessionStoreCompactInput, SessionStoreMaintenance, SessionStoreSession, TodoItem, TodoSnapshot } from './session/store/contracts.js';

package/dist/session-store.js

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

package/dist/shared/auto-title.d.ts

@@ -1,8 +1,8 @@
-import { type MarAgentModelConfiguration } from '../agent-core/model/configuration.js';
+import { type AgentModelConfiguration } from '../model/configuration.js';
 export interface GenerateSessionTitleInput {
-    readonly onModelUsage?: (usage: import('../agent-core/model/usage-observer.js').ModelRequestUsage) => Promise<void> | void;
+    readonly onModelUsage?: (usage: import('../model/usage-observer.js').ModelRequestUsage) => Promise<void> | void;
     readonly onModelUsageFailure?: () => void;
-    readonly models: readonly MarAgentModelConfiguration[];
+    readonly models: readonly AgentModelConfiguration[];
     readonly currentModelId: string;
     readonly prompt: string;
     /** Used only when the user message does not establish a language. */

package/dist/shared/auto-title.js

@@ -1,8 +1,8 @@
 import { randomUUID } from 'node:crypto';
-import { MarAgentError } from '../agent-core/error.js';
-import { AnthropicMessagesAdapter } from '../agent-core/model/anthropic-messages.js';
-import { resolveModelDefaultReasoningEffort } from '../agent-core/model/configuration.js';
-import { OpenAiResponsesAdapter } from '../agent-core/model/openai-responses.js';
+import { AgentError } from '../error.js';
+import { AnthropicMessagesAdapter } from '../model/anthropic-messages.js';
+import { resolveModelDefaultReasoningEffort } from '../model/configuration.js';
+import { OpenAiResponsesAdapter } from '../model/openai-responses.js';
 const sessionTitlePrompt = `You are a session title generator. Output only one title and nothing else.
 
 Create a brief title that helps the user find this conversation later.
@@ -16,12 +16,12 @@ Create a brief title that helps the user find this conversation later.
 export async function generateSessionTitle(input) {
     const defaultLanguage = input.defaultLanguage?.trim();
     if (input.defaultLanguage !== undefined && (!defaultLanguage || defaultLanguage.length > 128))
-        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Default title language is invalid.');
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Default title language is invalid.');
     const models = input.models.filter((model) => model.enabled);
     const model = models.find((candidate) => candidate.titleGeneration) ??
         models.find((candidate) => candidate.id === input.currentModelId);
     if (!model)
-        throw new MarAgentError('MAR_AGENT_MODEL_DISABLED', 'Selected title model is unavailable.');
+        throw new AgentError('MAR_AGENT_MODEL_DISABLED', 'Selected title model is unavailable.');
     const signal = AbortSignal.any([input.signal, AbortSignal.timeout(30_000)]);
     signal.throwIfAborted();
     const adapter = model.protocol === 'OPENAI_RESPONSES'

package/dist/shared/model-text.d.ts

@@ -1,18 +1,18 @@
-import { type MarAgentModelConfiguration, type MarAgentReasoningEffort } from '../agent-core/model/configuration.js';
-import type { ModelAttemptDiagnostic, ModelUsage } from '../agent-core/model/contracts.js';
-import type { CoreCompactMessage } from '../agent-core/extensions/compaction.js';
-import type { ClientToolDefinition, ToolCall } from '../agent-core/tools/contracts.js';
+import { type AgentModelConfiguration, type AgentReasoningEffort } from '../model/configuration.js';
+import type { ModelAttemptDiagnostic, ModelUsage } from '../model/contracts.js';
+import type { ExtensionCompactMessage } from '../extensions/compaction.js';
+import type { ClientToolDefinition, ToolCall } from '../tools/contracts.js';
 export interface GenerateModelTextInput {
-    readonly onModelUsage?: (usage: import('../agent-core/model/usage-observer.js').ModelRequestUsage) => Promise<void> | void;
+    readonly onModelUsage?: (usage: import('../model/usage-observer.js').ModelRequestUsage) => Promise<void> | void;
     readonly onModelUsageFailure?: () => void;
-    readonly model: MarAgentModelConfiguration;
+    readonly model: AgentModelConfiguration;
     readonly system: string;
-    readonly messages: readonly CoreCompactMessage[];
+    readonly messages: readonly ExtensionCompactMessage[];
     /** Declarative client tools only. Returned calls are never executed or continued here. */
     readonly tools?: readonly ClientToolDefinition[];
     readonly promptCacheKey?: string;
     readonly cachePrefixMessages?: number;
-    readonly reasoningEffort?: MarAgentReasoningEffort;
+    readonly reasoningEffort?: AgentReasoningEffort;
     readonly outputLimit?: number;
     readonly signal: AbortSignal;
     readonly onAttemptDiagnostic?: (diagnostic: ModelAttemptDiagnostic) => Promise<void> | void;

package/dist/shared/model-text.js

@@ -1,8 +1,9 @@
 import { randomUUID } from 'node:crypto';
-import { MarAgentError } from '../agent-core/error.js';
-import { AnthropicMessagesAdapter } from '../agent-core/model/anthropic-messages.js';
-import { OpenAiResponsesAdapter } from '../agent-core/model/openai-responses.js';
-import { resolveModelDefaultReasoningEffort } from '../agent-core/model/configuration.js';
+import { AgentError } from '../error.js';
+import { AnthropicMessagesAdapter } from '../model/anthropic-messages.js';
+import { OpenAiResponsesAdapter } from '../model/openai-responses.js';
+import { projectModelRequest } from '../sdk/model-input-projection.js';
+import { resolveModelDefaultReasoningEffort } from '../model/configuration.js';
 /** One request using the SDK transports, without tool execution or a Session. */
 export async function generateModelText(input) {
     input.signal.throwIfAborted();
@@ -19,7 +20,7 @@ export async function generateModelText(input) {
     const toolCalls = [];
     let usage;
     try {
-        for await (const event of adapter.start({
+        for await (const event of adapter.start(projectModelRequest({
             retryState: { attempts: 0, maxAttempts: 1 },
             usageRequestId: randomUUID(),
             ...(input.onModelUsage === undefined ? {} : { onModelUsage: input.onModelUsage }),
@@ -38,7 +39,7 @@ export async function generateModelText(input) {
             ...(input.promptCacheKey === undefined ? {} : { promptCacheKey: input.promptCacheKey }),
             ...(input.onAttemptDiagnostic ? { onAttemptDiagnostic: input.onAttemptDiagnostic } : {}),
             ...(input.outputLimit === undefined ? {} : { outputLimit: input.outputLimit })
-        }, input.signal)) {
+        }), input.signal)) {
             input.signal.throwIfAborted();
             if (event.type === 'text.completed' && (event.phase ?? 'final_answer') === 'final_answer')
                 text = event.text.trim();
@@ -49,7 +50,7 @@ export async function generateModelText(input) {
                     event.reason === 'completed' || (event.reason === 'tool_use' && toolCalls.length > 0);
             else if (event.type === 'client_tool.call') {
                 if (!tools.some((tool) => tool.name === event.name) || event.argumentError !== undefined)
-                    throw new MarAgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Standalone generation returned an undeclared tool or invalid tool arguments.');
+                    throw new AgentError('MAR_AGENT_MODEL_PROTOCOL_ERROR', 'Standalone generation returned an undeclared tool or invalid tool arguments.');
                 toolCalls.push({ name: event.name, callId: event.callId, arguments: event.arguments });
             }
         }

package/dist/storage/file-lock.js

@@ -0,0 +1,83 @@
+import { open, readFile, rm } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { AgentError } from '../error.js';
+export async function acquireFileLock(path, message = 'Session index is busy.', waitMs = 5000, options = {}) {
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        options.signal?.throwIfAborted();
+        let handle;
+        try {
+            handle = await open(path, 'wx', 0o600);
+        }
+        catch (cause) {
+            if (cause.code !== 'EEXIST')
+                throw cause;
+            if (await removeDeadOwner(path))
+                continue;
+            if (Date.now() >= deadline)
+                throw new AgentError(options.code ?? 'MAR_AGENT_SESSION_LOCKED', message, { cause });
+            await delay(25 + Math.floor(Math.random() * 25), undefined, options.signal ? { signal: options.signal } : {});
+            continue;
+        }
+        try {
+            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+            options.signal?.throwIfAborted();
+        }
+        catch (error) {
+            try {
+                await handle.close();
+            }
+            finally {
+                await rm(path, { force: true });
+            }
+            throw error;
+        }
+        let released = false;
+        return async () => {
+            if (released)
+                return;
+            released = true;
+            await handle.close();
+            await rm(path, { force: true });
+        };
+    }
+}
+async function removeDeadOwner(path) {
+    const reclaimerPath = `${path}.reclaim`;
+    let reclaimer;
+    try {
+        // Only one process may unlink a dead owner's path; all other contenders wait.
+        reclaimer = await open(reclaimerPath, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    try {
+        const owner = JSON.parse(await readFile(path, 'utf8'));
+        if (typeof owner.pid !== 'number' || !Number.isSafeInteger(owner.pid))
+            return false;
+        try {
+            process.kill(owner.pid, 0);
+            return false;
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                return false;
+            await rm(path, { force: true });
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            await reclaimer.close();
+        }
+        finally {
+            await rm(reclaimerPath, { force: true });
+        }
+    }
+}

package/dist/subagent/contracts.d.ts

@@ -0,0 +1,107 @@
+import type { AgentReasoningEffort } from '../model/configuration.js';
+import type { ExecutionResult } from '../runtime/contracts.js';
+export interface SubagentTaskInput {
+    description: string;
+    prompt: string;
+    role: 'general-purpose' | 'explore';
+    modelId?: string;
+    reasoningEffort?: AgentReasoningEffort;
+    background?: boolean;
+    parentSubagentId?: string;
+}
+export interface SubagentLatestMessage {
+    itemId: string;
+    turnId: string;
+    phase: 'commentary' | 'final_answer';
+    text: string;
+    timestamp: string;
+    truncated: boolean;
+}
+export type SubagentLatestActivity = {
+    kind: 'message';
+    timestamp: string;
+    phase: 'commentary' | 'final_answer';
+} | {
+    kind: 'tool';
+    timestamp: string;
+    toolName: string;
+    status: 'started' | 'completed' | 'failed';
+};
+export interface SubagentTaskSnapshot extends Record<string, unknown> {
+    permissionStop?: ExecutionResult['permissionStop'];
+    agentId: string;
+    description: string;
+    role?: SubagentTaskInput['role'];
+    extensionId?: string;
+    status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled' | 'interrupted';
+    modelId?: string;
+    modelName?: string;
+    reasoningEffort?: AgentReasoningEffort;
+    latestMessage?: SubagentLatestMessage;
+    latestActivity?: SubagentLatestActivity;
+    summary?: string;
+    changedFiles?: string[];
+    verification?: string[];
+    evidence?: Array<{
+        path: string;
+        startLine?: number;
+        endLine?: number;
+    }>;
+    errorCode?: string;
+    errorMessage?: string;
+    messageId?: string;
+    turnId?: string;
+    deliveryStatus?: 'accepted' | 'applied' | 'cancelled' | 'failed';
+    waitOutcome?: SubagentWaitOutcome;
+    reason?: 'steer';
+}
+export type SubagentWaitFor = 'completion' | 'message';
+export type SubagentWaitOutcome = Exclude<import('../runtime/wait.js').ToolWaitOutcome, 'yield'>;
+export interface SubagentMessageOptions {
+    delivery?: 'append' | 'replace';
+    signal?: AbortSignal;
+}
+export interface SubagentRunOptions {
+    turnSignal?: AbortSignal;
+    waitFor?: 'start' | 'completion';
+    signal?: AbortSignal;
+    onCreated?: (task: SubagentTaskSnapshot) => Promise<void> | void;
+}
+export interface SubagentOutputOptions {
+    waitInterrupt?: import('../runtime/wait.js').ToolWaitInterrupt | undefined;
+    untilSettled?: true;
+    waitMs?: number;
+    waitFor?: SubagentWaitFor;
+    signal?: AbortSignal;
+}
+export type SubagentWaitMode = 'any' | 'all';
+export interface SubagentManyOutputOptions extends Omit<SubagentOutputOptions, 'untilSettled'> {
+    mode?: SubagentWaitMode;
+}
+export interface SubagentManyOutput {
+    mode: SubagentWaitMode;
+    waitFor: SubagentWaitFor;
+    waitOutcome: SubagentWaitOutcome;
+    reason?: 'steer';
+    agents: SubagentTaskSnapshot[];
+    pendingAgentIds: string[];
+}
+export interface SubagentHandledResult {
+    readonly outcome: 'handled';
+    readonly value?: unknown;
+}
+export type SubagentRunResult = SubagentTaskSnapshot | SubagentHandledResult;
+export interface SubagentController {
+    run(input: SubagentTaskInput, options?: SubagentRunOptions): Promise<SubagentRunResult>;
+    output(agentId: string, options?: SubagentOutputOptions): Promise<SubagentTaskSnapshot>;
+    outputAny(options?: SubagentOutputOptions): Promise<SubagentTaskSnapshot>;
+    outputMany(agentIds: readonly string[], options?: SubagentManyOutputOptions): Promise<SubagentManyOutput>;
+    message(agentId: string, message: string, options?: SubagentMessageOptions): Promise<SubagentTaskSnapshot>;
+    cancel(agentId: string): Promise<SubagentTaskSnapshot>;
+    listSessionResources(): readonly {
+        agentId: string;
+        status: SubagentTaskSnapshot['status'];
+        description: string;
+    }[];
+    dispose(): Promise<void>;
+}

package/dist/subagent/contracts.js

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

package/dist/subagent/limits.d.ts

@@ -0,0 +1,17 @@
+export declare const SUBAGENT_LIMITS: Readonly<{
+    agentWaitMinWaitMs: 0;
+    agentWaitWaitFloorMs: 10000;
+    agentWaitDefaultWaitMs: 30000;
+    agentWaitMaxWaitMs: 300000;
+    agentWaitMaxAgents: 8;
+    subagentDescriptionMaxCharacters: 80;
+    subagentPromptMaxBytes: 131072;
+    subagentMessageMaxBytes: 131072;
+    subagentReasoningEffortMaxCharacters: 64;
+    subagentSummaryMaxBytes: 16384;
+    subagentUpdateMaxBytes: 32768;
+    subagentRunningLatestMessageMaxCharacters: 2000;
+    subagentEvidenceMaxItems: 64;
+    subagentVerificationMaxItems: 16;
+    subagentChangedFilesMaxItems: 200;
+}>;

package/dist/subagent/limits.js

@@ -0,0 +1,17 @@
+export const SUBAGENT_LIMITS = Object.freeze({
+    agentWaitMinWaitMs: 0,
+    agentWaitWaitFloorMs: 10_000,
+    agentWaitDefaultWaitMs: 30_000,
+    agentWaitMaxWaitMs: 300_000,
+    agentWaitMaxAgents: 8,
+    subagentDescriptionMaxCharacters: 80,
+    subagentPromptMaxBytes: 131_072,
+    subagentMessageMaxBytes: 131_072,
+    subagentReasoningEffortMaxCharacters: 64,
+    subagentSummaryMaxBytes: 16_384,
+    subagentUpdateMaxBytes: 32_768,
+    subagentRunningLatestMessageMaxCharacters: 2_000,
+    subagentEvidenceMaxItems: 64,
+    subagentVerificationMaxItems: 16,
+    subagentChangedFilesMaxItems: 200
+});