@myagentroam/agent 0.11.38 → 0.11.40

package/dist/cli/subagent/snapshot.js

@@ -0,0 +1,127 @@
+export function boundedUtf8(value, maxBytes) {
+    const bytes = Buffer.from(value, 'utf8');
+    if (bytes.length <= maxBytes)
+        return { value, truncated: false };
+    let end = maxBytes;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end--;
+    return { value: bytes.subarray(0, end).toString('utf8'), truncated: true };
+}
+export function projectChildEvent(snapshot, event, full = false) {
+    if (event.type === 'execution.failed' || event.type === 'execution.cancelled') {
+        delete snapshot.summary;
+        delete snapshot.summaryTruncated;
+    }
+    if (full && event.type === 'message.completed') {
+        snapshot.latestMessage = {
+            itemId: event.itemId,
+            turnId: event.turnId ?? '',
+            phase: event.phase,
+            text: event.text,
+            timestamp: event.timestamp,
+            truncated: false
+        };
+        snapshot.latestActivity = { kind: 'message', timestamp: event.timestamp, phase: event.phase };
+    }
+    else if (full &&
+        (event.type === 'tool.started' ||
+            event.type === 'tool.completed' ||
+            event.type === 'tool.failed')) {
+        snapshot.latestActivity = {
+            kind: 'tool',
+            timestamp: event.timestamp,
+            toolName: event.toolName,
+            status: event.type === 'tool.started'
+                ? 'started'
+                : event.type === 'tool.completed'
+                    ? 'completed'
+                    : 'failed'
+        };
+        if (event.type === 'tool.completed' && event.toolName === 'exec') {
+            (snapshot.verification ??= []).push(event.summary);
+        }
+        else if (event.type === 'tool.completed' &&
+            event.toolName === 'read' &&
+            event.data &&
+            'results' in event.data &&
+            Array.isArray(event.data.results)) {
+            for (const result of event.data.results) {
+                if (!result ||
+                    typeof result !== 'object' ||
+                    typeof result.path !== 'string' ||
+                    result.error !== undefined)
+                    continue;
+                const positive = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 1;
+                const evidence = {
+                    path: result.path,
+                    ...(positive(result.startLine) ? { startLine: result.startLine } : {}),
+                    ...(positive(result.endLine) ? { endLine: result.endLine } : {})
+                };
+                const entries = (snapshot.evidence ??= []);
+                if (!entries.some((item) => item.path === evidence.path &&
+                    item.startLine === evidence.startLine &&
+                    item.endLine === evidence.endLine))
+                    entries.push(evidence);
+            }
+        }
+    }
+    if (event.type === 'message.completed' && event.phase === 'final_answer') {
+        const summary = full
+            ? { value: event.text, truncated: false }
+            : boundedUtf8(event.text, 16_384);
+        snapshot.summary = summary.value;
+        if (summary.truncated)
+            snapshot.summaryTruncated = true;
+        else
+            delete snapshot.summaryTruncated;
+        if (event.turnId)
+            snapshot.turnId = event.turnId;
+        else
+            delete snapshot.turnId;
+    }
+    if (event.type !== 'tool.completed' ||
+        event.toolName !== 'apply_patch' ||
+        !event.data ||
+        !('files' in event.data) ||
+        !Array.isArray(event.data.files))
+        return;
+    for (const file of event.data.files) {
+        if (typeof file !== 'object' || file === null)
+            continue;
+        for (const candidate of [
+            file.path,
+            file.targetPath
+        ]) {
+            if (typeof candidate !== 'string' || !candidate || snapshot.changedFiles.includes(candidate))
+                continue;
+            if (!full && snapshot.changedFiles.length >= 200) {
+                snapshot.changedFilesTruncated = true;
+                continue;
+            }
+            snapshot.changedFiles.push(candidate);
+        }
+    }
+}
+export function publicChildSnapshot(snapshot) {
+    if (!snapshot)
+        return {};
+    return {
+        ...(snapshot.summary === undefined ? {} : { summary: snapshot.summary }),
+        ...(snapshot.summaryTruncated ? { summaryTruncated: true } : {}),
+        ...(snapshot.turnId ? { turnId: snapshot.turnId } : {}),
+        ...(snapshot.changedFiles.length ? { changedFiles: [...snapshot.changedFiles] } : {}),
+        ...(snapshot.changedFilesTruncated ? { changedFilesTruncated: true } : {})
+    };
+}
+/** Full native details are never included in model-facing projections. */
+export function nativeChildSnapshot(snapshot) {
+    return {
+        ...publicChildSnapshot(snapshot),
+        ...(snapshot?.latestMessage ? { latestMessage: { ...snapshot.latestMessage } } : {}),
+        ...(snapshot?.latestActivity ? { latestActivity: { ...snapshot.latestActivity } } : {}),
+        ...(snapshot?.verification?.length ? { verification: [...snapshot.verification] } : {}),
+        ...(snapshot?.evidence?.length
+            ? { evidence: snapshot.evidence.map((item) => ({ ...item })) }
+            : {})
+    };
+}

package/dist/cli/subagent/start.d.ts

@@ -0,0 +1,24 @@
+import { type Agent, type AgentReasoningEffort, type ExecutionHandle } from '@myagentroam/agent';
+import type { ExtensionOperationContext, SessionExtensionContext } from '@myagentroam/agent/extensions';
+export interface StartInput {
+    readonly description: string;
+    readonly title?: string;
+    readonly prompt: string;
+    readonly role: 'general-purpose' | 'explore';
+    readonly modelId?: string;
+    readonly reasoningEffort?: AgentReasoningEffort;
+    readonly turnSignal?: AbortSignal;
+}
+/** Admission reservations are bounded quota accounting, not Execution state. */
+export declare class StartAdmission {
+    #private;
+    finish(executionId: string): void;
+    reserve(agent: Agent, parentSessionId: string, executionId: string): (created: boolean) => void;
+    reserveResume(agent: Agent, parentSessionId: string): () => void;
+}
+export declare function registerStart(context: SessionExtensionContext, agent: Agent, admission: StartAdmission): void;
+/** Both adapters enter this Session-owned creation path with their actual Core operation. */
+export declare function startChild(context: SessionExtensionContext, agent: Agent, admission: StartAdmission, input: StartInput, call: ExtensionOperationContext, mode: 'model' | 'native'): Promise<{
+    data: Record<string, unknown>;
+    execution?: ExecutionHandle;
+}>;

package/dist/cli/subagent/start.js

@@ -0,0 +1,201 @@
+import { AgentError } from '@myagentroam/agent';
+/** Admission reservations are bounded quota accounting, not Execution state. */
+export class StartAdmission {
+    #pending = new Map();
+    #perExecution = new Map();
+    finish(executionId) {
+        this.#perExecution.delete(executionId);
+    }
+    reserve(agent, parentSessionId, executionId) {
+        return this.#reserve(agent, parentSessionId, executionId);
+    }
+    reserveResume(agent, parentSessionId) {
+        const release = this.#reserve(agent, parentSessionId);
+        return () => release(false);
+    }
+    #reserve(agent, parentSessionId, executionId) {
+        const registration = agent.observeSessionExecutions(() => { });
+        const active = registration.sessions.filter((session) => session.source.parentSessionId === parentSessionId).length;
+        registration.unsubscribe();
+        const used = executionId === undefined ? 0 : (this.#perExecution.get(executionId) ?? 0);
+        const pending = this.#pending.get(parentSessionId) ?? 0;
+        if (used >= 16 || active + pending >= 16)
+            throw new AgentError('MAR_AGENT_SUBAGENT_LIMIT', 'Subagent admission limit was reached.');
+        this.#pending.set(parentSessionId, pending + 1);
+        if (executionId !== undefined)
+            this.#perExecution.set(executionId, used + 1);
+        let released = false;
+        return (created) => {
+            if (released)
+                return;
+            released = true;
+            const remaining = (this.#pending.get(parentSessionId) ?? 1) - 1;
+            if (remaining === 0)
+                this.#pending.delete(parentSessionId);
+            else
+                this.#pending.set(parentSessionId, remaining);
+            if (!created && executionId !== undefined)
+                this.#perExecution.set(executionId, (this.#perExecution.get(executionId) ?? 1) - 1);
+        };
+    }
+}
+export function registerStart(context, agent, admission) {
+    context.tools.register({
+        name: 'agent_start',
+        description: 'Start a child Session and return its identity without waiting for completion.',
+        allowedCallers: ['direct', 'programmatic'],
+        parallelSafety: 'serial',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', minLength: 1, maxLength: 80 },
+                description: { type: 'string', minLength: 1, maxLength: 80 },
+                prompt: { type: 'string', minLength: 1 },
+                role: { type: 'string', enum: ['general-purpose', 'explore'] },
+                modelId: { type: 'string', minLength: 1 },
+                reasoningEffort: {
+                    type: 'string',
+                    enum: ['low', 'medium', 'high', 'xhigh', 'max', 'ultra']
+                }
+            },
+            required: ['title', 'prompt', 'role'],
+            additionalProperties: false
+        },
+        async execute(raw, call) {
+            const input = raw;
+            const { data } = await startChild(context, agent, admission, { ...input, description: input.description ?? input.title ?? '' }, call, 'model');
+            return { content: JSON.stringify(data), data, eventData: { agentId: data.agentId } };
+        }
+    });
+}
+/** Both adapters enter this Session-owned creation path with their actual Core operation. */
+export async function startChild(context, agent, admission, input, call, mode) {
+    if ((mode === 'model' && !call.executionId) || !context.session || !context.models)
+        throw new AgentError('MAR_AGENT_SUBAGENT_LIMIT', 'An active parent Execution is required.');
+    if (mode === 'model' && (typeof input.title !== 'string' || !input.title.trim()))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Child title is required.');
+    if (!input.description.trim() ||
+        !input.prompt.trim() ||
+        (mode === 'model' && Buffer.byteLength(input.prompt) > 131_072))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Child description or prompt is invalid.');
+    const parent = await agent.getSession(context.sessionId);
+    let root = parent;
+    let depth = 1;
+    const visited = new Set([root.id]);
+    while (root.source.parentSessionId !== undefined) {
+        if (depth >= 3 || visited.has(root.source.parentSessionId))
+            throw new AgentError('MAR_AGENT_SUBAGENT_LIMIT', 'Child Session depth limit was reached.');
+        root = await agent.getSession(root.source.parentSessionId);
+        if (root.workspace !== parent.workspace)
+            throw new AgentError('MAR_AGENT_SUBAGENT_LIMIT', 'Child ancestry is invalid.');
+        visited.add(root.id);
+        depth++;
+    }
+    if (depth >= 3)
+        throw new AgentError('MAR_AGENT_SUBAGENT_LIMIT', 'Child Session depth limit was reached.');
+    const request = mode === 'model' ? await context.session.captureRequest() : undefined;
+    const selected = input.modelId ??
+        request?.request.modelId ??
+        (mode === 'native'
+            ? (parent.modelId ?? context.models.list().find((candidate) => candidate.isDefault)?.id)
+            : undefined);
+    if (!selected)
+        throw new AgentError('MAR_AGENT_MODEL_CONFIG_INVALID', 'Child model is unavailable.');
+    const effort = input.reasoningEffort ??
+        request?.request.reasoningEffort ??
+        (mode === 'native' ? parent.reasoningEffort : undefined);
+    const validate = () => {
+        const model = context.models.list().find((candidate) => candidate.id === selected);
+        if (!model?.conversationModel || !model.subagentModel)
+            throw new AgentError('MAR_AGENT_MODEL_DISABLED', 'The selected child model is not eligible.');
+        if (input.reasoningEffort && !model.reasoningEfforts.includes(input.reasoningEffort))
+            throw new AgentError('MAR_AGENT_SUBAGENT_REASONING_EFFORT_UNAVAILABLE', 'The selected child effort is unavailable.');
+        const effectiveEffort = input.reasoningEffort ??
+            model.reasoningEfforts.find((candidate) => candidate === effort) ??
+            model.defaultReasoningEffort;
+        return { model, effectiveEffort };
+    };
+    validate();
+    call.signal.throwIfAborted();
+    input.turnSignal?.throwIfAborted();
+    const nativeRelease = mode === 'native' ? admission.reserveResume(agent, parent.id) : undefined;
+    const release = nativeRelease
+        ? (_created) => nativeRelease()
+        : admission.reserve(agent, parent.id, call.executionId);
+    let childId;
+    try {
+        const child = await agent.createSession({
+            workspace: parent.workspace,
+            ...(mode === 'model' ? { title: input.title.trim() } : {}),
+            source: {
+                type: 'subagent',
+                parentSessionId: parent.id,
+                rootSessionId: root.id,
+                ...(call.executionId ? { parentExecutionId: call.executionId } : {}),
+                parentOperationId: call.operationId,
+                ...(call.ownerInstanceId ? { ownerInstanceId: call.ownerInstanceId } : {}),
+                ...(call.extensionId ? { extensionId: call.extensionId } : {}),
+                role: input.role,
+                description: input.description.trim()
+            }
+        });
+        childId = child.id;
+        call.signal.throwIfAborted();
+        input.turnSignal?.throwIfAborted();
+        const { model, effectiveEffort } = validate();
+        const originId = parent.id.replace(/[&<>"']/g, (character) => ({
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&quot;',
+            "'": '&apos;'
+        })[character]);
+        const prompt = `<mar_session_origin sessionId="${originId}" relation="parent">\n  <instruction>Message from the parent session.</instruction>\n</mar_session_origin>\n${input.prompt}`;
+        const executionInput = {
+            prompt,
+            modelId: model.id,
+            reasoningEffort: effectiveEffort,
+            permissionMode: call.permissionMode ?? 'auto'
+        };
+        const execution = input.role === 'explore' ? child.plan(executionInput) : child.run(executionInput);
+        if (input.turnSignal) {
+            const turnSignal = input.turnSignal;
+            const cancel = () => execution.cancel();
+            turnSignal.addEventListener('abort', cancel, { once: true });
+            if (turnSignal.aborted)
+                cancel();
+            void execution
+                .result()
+                .finally(() => turnSignal.removeEventListener('abort', cancel))
+                .catch(() => { });
+        }
+        else
+            void execution.result().catch(() => { });
+        const result = {
+            agentId: child.id,
+            executionId: execution.executionId,
+            status: 'running',
+            modelId: model.id,
+            modelName: model.name,
+            reasoningEffort: effectiveEffort,
+            description: input.description.trim(),
+            role: input.role
+        };
+        return { data: result, execution };
+    }
+    catch (error) {
+        if (childId === undefined)
+            throw error;
+        const result = {
+            agentId: childId,
+            status: 'not-started',
+            description: input.description.trim(),
+            role: input.role,
+            errorCode: error instanceof AgentError ? error.code : 'MAR_AGENT_SUBAGENT_START_FAILED'
+        };
+        return { data: result };
+    }
+    finally {
+        release(childId !== undefined);
+    }
+}

package/dist/cli/subagent/wait-output.d.ts

@@ -0,0 +1,19 @@
+type WaitAgent = {
+    agentId: string;
+    executionId?: string;
+    status: string;
+    waitOutcome: string;
+    summary?: string;
+    summaryTruncated?: boolean;
+    changedFiles?: string[];
+    changedFilesTruncated?: boolean;
+    updates?: Array<{
+        value: string;
+        truncated?: boolean;
+    }>;
+};
+/** Keep the model's JSON parseable without modifying the native result. */
+export declare function modelWaitAgent<T extends WaitAgent>(agent: T, maximumBytes: number): T & {
+    detailsTruncated?: boolean;
+};
+export {};

package/dist/cli/subagent/wait-output.js

@@ -0,0 +1,56 @@
+import { boundedUtf8 } from './snapshot.js';
+/** Keep the model's JSON parseable without modifying the native result. */
+export function modelWaitAgent(agent, maximumBytes) {
+    const result = {
+        ...agent,
+        ...(agent.changedFiles ? { changedFiles: [...agent.changedFiles] } : {}),
+        ...(agent.updates ? { updates: agent.updates.map((update) => ({ ...update })) } : {})
+    };
+    const size = () => Buffer.byteLength(JSON.stringify(result), 'utf8');
+    while (size() > maximumBytes && result.changedFiles?.length) {
+        result.changedFiles.pop();
+        result.changedFilesTruncated = true;
+    }
+    if (size() > maximumBytes && result.summary !== undefined) {
+        const summary = result.summary;
+        let low = 0;
+        let high = Buffer.byteLength(summary, 'utf8');
+        result.summaryTruncated = true;
+        while (low < high) {
+            const middle = Math.ceil((low + high) / 2);
+            result.summary = boundedUtf8(summary, middle).value;
+            if (size() <= maximumBytes)
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        result.summary = boundedUtf8(summary, low).value;
+    }
+    for (const update of result.updates ?? []) {
+        if (size() <= maximumBytes)
+            break;
+        const value = update.value;
+        let low = 0;
+        let high = Buffer.byteLength(value, 'utf8');
+        update.truncated = true;
+        while (low < high) {
+            const middle = Math.ceil((low + high) / 2);
+            update.value = boundedUtf8(value, middle).value;
+            if (size() <= maximumBytes)
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        update.value = boundedUtf8(value, low).value;
+    }
+    if (size() <= maximumBytes)
+        return result;
+    // Preserve the identity and outcome even if unusual metadata itself exceeds the budget.
+    return {
+        agentId: agent.agentId,
+        ...(agent.executionId ? { executionId: agent.executionId } : {}),
+        status: agent.status,
+        waitOutcome: agent.waitOutcome,
+        detailsTruncated: true
+    };
+}

package/dist/cli/subagent/wait.d.ts

@@ -0,0 +1,175 @@
+import { type Agent } from '@myagentroam/agent';
+import { type ExtensionOperationContext, type SessionExtensionContext } from '@myagentroam/agent/extensions';
+import type { SessionObservations } from './observations.js';
+export type WaitInput = {
+    agentId?: string | undefined;
+    agentIds?: string[] | undefined;
+    mode?: 'any' | 'all' | undefined;
+    waitFor?: 'message' | 'completion' | undefined;
+    waitMs?: number | undefined;
+    untilSettled?: true | undefined;
+};
+/** A foreground wait observes fixed Execution identities, never owning or cancelling them. */
+export declare function registerWait(context: SessionExtensionContext, agent: Agent, observations: SessionObservations, history?: Pick<Agent, 'sessionHistory'>): void;
+/** Model and native callers share target capture and acknowledgement, not their limits or cursors. */
+export declare function waitForChild(context: SessionExtensionContext, agent: Agent, observations: SessionObservations, input: WaitInput, call: ExtensionOperationContext, mode: 'model' | 'native', receipts?: SessionObservations, history?: Pick<Agent, 'sessionHistory'>): Promise<{
+    data: {
+        waitOutcome?: string;
+        reason?: string;
+        waitFor: "message" | "completion";
+    } | {
+        waitOutcome: string;
+        reason?: string;
+        waitFor: "message" | "completion";
+        updates?: {
+            permissionStop?: import("@myagentroam/agent").PermissionStop;
+            errorMessage?: string;
+            errorCode?: string;
+            truncated?: boolean;
+            final?: boolean;
+            kind: "message" | "terminal";
+            value: string;
+        }[];
+        receipt?: import("@myagentroam/agent").AgentSessionInputReceipt;
+        changedFilesTruncated?: boolean;
+        changedFiles?: string[];
+        turnId?: string;
+        summaryTruncated?: boolean;
+        summary?: string;
+        permissionStop?: import("@myagentroam/agent").PermissionStop;
+        errorMessage?: string;
+        errorCode?: string;
+        status: string;
+        description?: string;
+        role?: "general-purpose" | "explore";
+        modelId?: string;
+        modelName?: string;
+        reasoningEffort?: string;
+        extensionId?: string;
+        executionId?: string;
+        agentId: string;
+    } | {
+        waitOutcome: string;
+        reason?: string;
+        waitFor: "message" | "completion";
+        updates?: {
+            permissionStop?: import("@myagentroam/agent").PermissionStop;
+            errorMessage?: string;
+            errorCode?: string;
+            truncated?: boolean;
+            final?: boolean;
+            kind: "message" | "terminal";
+            value: string;
+        }[];
+        receipt?: import("@myagentroam/agent").AgentSessionInputReceipt;
+        latestActivity?: {
+            kind: "message";
+            timestamp: string;
+            phase: "commentary" | "final_answer";
+        } | {
+            kind: "tool";
+            timestamp: string;
+            toolName: string;
+            status: "started" | "completed" | "failed";
+        };
+        latestMessage?: {
+            itemId: string;
+            turnId: string;
+            phase: "commentary" | "final_answer";
+            text: string;
+            timestamp: string;
+            truncated: boolean;
+        };
+        permissionStop?: import("@myagentroam/agent").PermissionStop;
+        errorMessage?: string;
+        errorCode?: string;
+        status: string;
+        description?: string;
+        role?: "general-purpose" | "explore";
+        modelId?: string;
+        modelName?: string;
+        reasoningEffort?: string;
+        extensionId?: string;
+        executionId?: string;
+        agentId: string;
+    } | {
+        agents: ({
+            updates?: {
+                permissionStop?: import("@myagentroam/agent").PermissionStop;
+                errorMessage?: string;
+                errorCode?: string;
+                truncated?: boolean;
+                final?: boolean;
+                kind: "message" | "terminal";
+                value: string;
+            }[];
+            receipt?: import("@myagentroam/agent").AgentSessionInputReceipt;
+            changedFilesTruncated?: boolean;
+            changedFiles?: string[];
+            turnId?: string;
+            summaryTruncated?: boolean;
+            summary?: string;
+            permissionStop?: import("@myagentroam/agent").PermissionStop;
+            errorMessage?: string;
+            errorCode?: string;
+            status: string;
+            waitOutcome: string;
+            description?: string;
+            role?: "general-purpose" | "explore";
+            modelId?: string;
+            modelName?: string;
+            reasoningEffort?: string;
+            extensionId?: string;
+            executionId?: string;
+            agentId: string;
+        } | {
+            updates?: {
+                permissionStop?: import("@myagentroam/agent").PermissionStop;
+                errorMessage?: string;
+                errorCode?: string;
+                truncated?: boolean;
+                final?: boolean;
+                kind: "message" | "terminal";
+                value: string;
+            }[];
+            receipt?: import("@myagentroam/agent").AgentSessionInputReceipt;
+            latestActivity?: {
+                kind: "message";
+                timestamp: string;
+                phase: "commentary" | "final_answer";
+            } | {
+                kind: "tool";
+                timestamp: string;
+                toolName: string;
+                status: "started" | "completed" | "failed";
+            };
+            latestMessage?: {
+                itemId: string;
+                turnId: string;
+                phase: "commentary" | "final_answer";
+                text: string;
+                timestamp: string;
+                truncated: boolean;
+            };
+            permissionStop?: import("@myagentroam/agent").PermissionStop;
+            errorMessage?: string;
+            errorCode?: string;
+            status: string;
+            waitOutcome: string;
+            description?: string;
+            role?: "general-purpose" | "explore";
+            modelId?: string;
+            modelName?: string;
+            reasoningEffort?: string;
+            extensionId?: string;
+            executionId?: string;
+            agentId: string;
+        })[];
+        pendingAgentIds: string[];
+        reason?: string;
+        mode: "any" | "all";
+        waitFor: "message" | "completion";
+        waitOutcome: string;
+    };
+    content: string;
+}>;