@myagentroam/agent 0.11.39 → 0.11.41

package/dist/cli/catalog-file.d.ts

@@ -12,6 +12,7 @@ export declare function writeModelCatalog(home: string, catalog: CliModelCatalog
 export declare function serializeModel(model: CliModelConfiguration): {
     apiKey: string;
     conversationModel?: boolean;
+    subagentModel?: boolean;
     useResourceUrl?: boolean;
     responsesConfigurationUpdates?: boolean;
     responsesTransport?: import("../index.js").ResponsesTransport;
@@ -46,6 +47,7 @@ export declare function serializeModel(model: CliModelConfiguration): {
         type: "CODEX_AUTH_FILE";
     };
     conversationModel?: boolean;
+    subagentModel?: boolean;
     useResourceUrl?: boolean;
     responsesConfigurationUpdates?: boolean;
     responsesTransport?: import("../index.js").ResponsesTransport;

package/dist/cli/main.js

@@ -16,7 +16,7 @@ Usage:
   maragent run <prompt> [--permission-mode auto|full-access] [--reasoning-effort EFFORT] [--format text|json|stream-json] [--codex-auth-file PATH]
   maragent resume [sessionId] [--reasoning-effort EFFORT] [--codex-auth-file PATH]
   maragent sessions list|delete <sessionId>
-  maragent models list|add|edit|remove|test [id] [--default-reasoning-effort EFFORT] [--code-mode|--no-code-mode] [--fast-mode|--no-fast-mode] [--codex-auth-file PATH]
+  maragent models list|add|edit|remove|test [id] [--default-reasoning-effort EFFORT] [--conversation-model|--no-conversation-model] [--subagent-model|--no-subagent-model] [--code-mode|--no-code-mode] [--fast-mode|--no-fast-mode] [--codex-auth-file PATH]
 `;
 function takeOption(arguments_, name) {
     const index = arguments_.indexOf(name);
@@ -68,7 +68,7 @@ async function modelsCommand(home, arguments_, codexAuthFile) {
     const catalog = await loadCatalog(home);
     if (action === 'list') {
         for (const model of catalog.models)
-            stdout.write(`${model.id}\t${model.name}\t${model.protocol}\t${model.modelId}\tcredential=${model.apiKey === undefined ? 'codex-auth-file' : 'api-key'}\n`);
+            stdout.write(`${model.id}\t${model.name}\t${model.protocol}\t${model.modelId}\tcredential=${model.apiKey === undefined ? 'codex-auth-file' : 'api-key'}\tconversation=${model.conversationModel !== false}\tsubagent=${model.subagentModel === true}\n`);
         return;
     }
     const id = arguments_[2];
@@ -171,7 +171,8 @@ async function modelsCommand(home, arguments_, codexAuthFile) {
                 defaultReasoningEffort: existing?.defaultReasoningEffort
             })
             : parseReasoningEffort(defaultReasoningEffortOption, '--default-reasoning-effort'),
-        conversationModel: existing?.conversationModel ?? true,
+        conversationModel: booleanFlag(arguments_, '--conversation-model', '--no-conversation-model', existing?.conversationModel ?? true),
+        subagentModel: booleanFlag(arguments_, '--subagent-model', '--no-subagent-model', existing?.subagentModel ?? false),
         titleGeneration: existing?.titleGeneration ?? false,
         codeMode: booleanFlag(arguments_, '--code-mode', '--no-code-mode', existing?.codeMode ?? false),
         ...(credential === 'codex-auth-file' && fastMode ? { fastMode: true } : {}),
@@ -278,10 +279,16 @@ async function main() {
         }
     });
     const runtime = runtimeModels(catalog.models, codexAuthFile);
-    const agent = await createAgent({
+    // The CLI-only build contains the independently published extension's same source.
+    const extensionPath = './subagent/index.js';
+    const extensionModule = (await import(extensionPath));
+    let agent;
+    const subagent = extensionModule.createSubagentExtension({ agent: () => agent });
+    agent = await createAgent({
         mode: 'normal',
         host,
         models: runtime.models,
+        extensions: [subagent],
         ...(modelId === undefined ? {} : { defaultModelId: modelId })
     });
     try {

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

@@ -0,0 +1,56 @@
+import { type Agent, type AgentSession, type ExecutionResult } from '@myagentroam/agent';
+import type { ExtensionOperationContext, SessionExtensionContext } from '@myagentroam/agent/extensions';
+import type { SessionObservations } from './observations.js';
+import type { StartAdmission } from './start.js';
+export declare function target(agent: Agent, actorId: string, id: string): Promise<{
+    session: AgentSession;
+    summary: import("@myagentroam/agent").AgentSessionSummary & {
+        automaticTitlePending: boolean;
+    };
+    child: boolean;
+    parent: boolean;
+}>;
+/** Local operations use the Session owner for all execution and input transitions. */
+export declare function registerControlTools(context: SessionExtensionContext, agent: Agent, observations: SessionObservations, warmObservations: ReadonlyMap<string, SessionObservations>, admission: StartAdmission): void;
+export declare function sendChild(context: SessionExtensionContext, agent: Agent, observations: SessionObservations, warmObservations: ReadonlyMap<string, SessionObservations>, admission: StartAdmission, input: {
+    agentId: string;
+    content: string;
+    delivery?: 'append' | 'replace';
+}, call: ExtensionOperationContext, mode: 'model' | 'native'): Promise<{
+    agentId: string;
+    delivery: string;
+    clientMessageId: `${string}-${string}-${string}-${string}-${string}`;
+}>;
+/** Stop through the Session owner; native callers use their own observation cursor. */
+export declare function stopChild(context: SessionExtensionContext, agent: Agent, observations: SessionObservations, input: {
+    agentId: string;
+    executionId?: string;
+}, call: ExtensionOperationContext): Promise<{
+    updates?: {
+        permissionStop?: import("@myagentroam/agent").PermissionStop;
+        errorMessage?: string;
+        errorCode?: string;
+        truncated?: boolean;
+        final?: boolean;
+        kind: "message" | "terminal";
+        value: string;
+    }[];
+    changedFilesTruncated?: boolean;
+    changedFiles?: string[];
+    turnId?: string;
+    summaryTruncated?: boolean;
+    summary?: string;
+    permissionStop?: import("@myagentroam/agent").PermissionStop;
+    errorCode?: string;
+    agentId: string;
+    executionId: string;
+    status: "completed" | "failed" | "cancelled";
+} | {
+    status: "idle" | "running" | "interrupted" | "completed" | "failed" | "cancelled";
+    executionId?: string;
+    details?: ReturnType<typeof import("./snapshot.js").nativeChildSnapshot>;
+    errorCode?: string;
+    errorMessage?: string;
+    permissionStop?: ExecutionResult["permissionStop"];
+    agentId: string;
+}>;

package/dist/cli/subagent/control.js

@@ -0,0 +1,219 @@
+import { randomUUID } from 'node:crypto';
+import { AgentError } from '@myagentroam/agent';
+import { publicChildSnapshot } from './snapshot.js';
+import { historicalExecutionStatus } from './history.js';
+async function relation(agent, actorId, id) {
+    const [actor, other] = await Promise.all([agent.getSession(actorId), agent.getSession(id)]);
+    if (actor.workspace !== other.workspace || actorId === id)
+        throw new AgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Session is not available.');
+    const child = other.source.parentSessionId === actorId;
+    const parent = actor.source.parentSessionId === id;
+    if (!child && !parent)
+        throw new AgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Session is not available.');
+    return { summary: other, child, parent };
+}
+export async function target(agent, actorId, id) {
+    const resolved = await relation(agent, actorId, id);
+    if (!resolved.child)
+        throw new AgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Session is not available.');
+    return { ...resolved, session: await agent.openSession(id) };
+}
+function active(session) {
+    const snapshot = session.subscribe(() => { });
+    snapshot.unsubscribe();
+    return snapshot;
+}
+async function join(promise, signal) {
+    signal.throwIfAborted();
+    let abort;
+    const cancelled = new Promise((_, reject) => {
+        abort = () => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
+    try {
+        return await Promise.race([promise, cancelled]);
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+    }
+}
+function origin(id, parent, message) {
+    const relation = parent ? 'other session' : 'parent session';
+    return `<mar_session_origin sessionId="${id}" relation="${parent ? 'other' : 'parent'}">\n  <instruction>Message from the ${relation}.</instruction>\n</mar_session_origin>\n\n${message}`;
+}
+/** Local operations use the Session owner for all execution and input transitions. */
+export function registerControlTools(context, agent, observations, warmObservations, admission) {
+    context.tools.register({
+        name: 'agent_send',
+        description: 'Send a message to a direct child or report to the direct parent.',
+        allowedCallers: ['direct', 'programmatic'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', minLength: 1 },
+                content: { type: 'string', minLength: 1 },
+                delivery: { type: 'string', enum: ['append', 'replace'] }
+            },
+            required: ['agentId', 'content'],
+            additionalProperties: false
+        },
+        async execute(value, call) {
+            const input = value;
+            const data = await sendChild(context, agent, observations, warmObservations, admission, input, call, 'model');
+            return { data, content: JSON.stringify(data) };
+        }
+    });
+    context.tools.register({
+        name: 'agent_stop',
+        description: 'Stop a direct child execution and wait for its cleanup.',
+        allowedCallers: ['direct', 'programmatic'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', minLength: 1 },
+                executionId: { type: 'string', minLength: 1 }
+            },
+            required: ['agentId'],
+            additionalProperties: false
+        },
+        async execute(value, call) {
+            const input = value;
+            const data = await stopChild(context, agent, observations, input, call);
+            return { data, content: JSON.stringify(data) };
+        }
+    });
+}
+export async function sendChild(context, agent, observations, warmObservations, admission, input, call, mode) {
+    if (!input.content.trim() || (mode === 'model' && Buffer.byteLength(input.content) > 131072))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Message is invalid.');
+    const { summary, child, parent } = await relation(agent, context.sessionId, input.agentId);
+    if (parent && input.delivery === 'replace')
+        throw new AgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Session is not available.');
+    call.signal.throwIfAborted();
+    if (parent) {
+        const receiver = warmObservations.get(input.agentId);
+        if (!call.executionId ||
+            !receiver?.report(context.sessionId, call.executionId, origin(context.sessionId, true, input.content)))
+            throw new AgentError('MAR_AGENT_SUBAGENT_PARENT_IDLE', 'Parent Session is not available for reports.');
+        const data = { agentId: input.agentId, delivery: 'reported', clientMessageId: randomUUID() };
+        return data;
+    }
+    const session = await agent.openSession(input.agentId);
+    call.signal.throwIfAborted();
+    const current = active(session);
+    const acknowledgePrevious = observations.acknowledgement(session.id);
+    const content = origin(context.sessionId, parent, input.content);
+    const clientMessageId = randomUUID();
+    if (current.activeExecutionId && !current.terminalEvent && input.delivery !== 'replace') {
+        const receipt = await session.steer({
+            expectedExecutionId: current.activeExecutionId,
+            prompt: content,
+            clientMessageId
+        });
+        if (receipt.status !== 'notAccepted') {
+            acknowledgePrevious();
+            if (receipt.status === 'accepted')
+                (mode === 'native'
+                    ? observations
+                    : (warmObservations.get(context.sessionId) ?? observations)).rememberReceipt(session.id, { clientMessageId, executionId: current.activeExecutionId });
+            const data = {
+                agentId: session.id,
+                executionId: current.activeExecutionId,
+                delivery: receipt.status,
+                clientMessageId,
+                ...(receipt.status === 'accepted'
+                    ? { messageId: clientMessageId, turnId: receipt.entry.turnId, deliveryStatus: 'accepted' }
+                    : {})
+            };
+            return data;
+        }
+        const after = active(session);
+        if (after.activeExecutionId && !after.terminalEvent)
+            throw new AgentError('MAR_AGENT_SUBAGENT_INPUT_NOT_ACCEPTED', 'Target did not accept the message.');
+    }
+    if (!child)
+        throw new AgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Session is not available.');
+    if (current.activeExecutionId) {
+        const completion = session.joinExecution(current.activeExecutionId);
+        if (!current.terminalEvent && input.delivery === 'replace')
+            await session.cancel(current.activeExecutionId);
+        if (completion)
+            await join(completion, call.signal);
+    }
+    const models = context.models.list();
+    const model = models.find((item) => item.id === (summary.modelId ?? models.find((item) => item.isDefault)?.id));
+    if (!model?.conversationModel || !model.subagentModel)
+        throw new AgentError('MAR_AGENT_SUBAGENT_MODEL_INVALID', 'Target model is not available for child Sessions.');
+    const effort = summary.reasoningEffort &&
+        model.reasoningEfforts.includes(summary.reasoningEffort)
+        ? summary.reasoningEffort
+        : model.defaultReasoningEffort;
+    call.signal.throwIfAborted();
+    const executionInput = {
+        prompt: content,
+        clientMessageId,
+        modelId: model.id,
+        reasoningEffort: effort,
+        permissionMode: call.permissionMode ?? 'auto'
+    };
+    const release = admission.reserveResume(agent, context.sessionId);
+    let execution;
+    try {
+        execution =
+            summary.source.type === 'subagent' && summary.source.role === 'explore'
+                ? session.plan(executionInput)
+                : session.run(executionInput);
+    }
+    finally {
+        release();
+    }
+    acknowledgePrevious();
+    (mode === 'native'
+        ? observations
+        : (warmObservations.get(context.sessionId) ?? observations)).rememberReceipt(session.id, { clientMessageId, executionId: execution.executionId });
+    const data = {
+        agentId: session.id,
+        executionId: execution.executionId,
+        delivery: 'started',
+        clientMessageId,
+        messageId: clientMessageId,
+        deliveryStatus: 'accepted',
+        ...(execution.turnId === undefined ? {} : { turnId: execution.turnId })
+    };
+    return data;
+}
+/** Stop through the Session owner; native callers use their own observation cursor. */
+export async function stopChild(context, agent, observations, input, call) {
+    const { child, session } = await target(agent, context.sessionId, input.agentId);
+    if (!child)
+        throw new AgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Session is not available.');
+    const current = active(session);
+    if (!current.activeExecutionId && !input.executionId) {
+        const state = await historicalExecutionStatus(agent, session.id, call.signal);
+        return { agentId: session.id, ...state };
+    }
+    if (!current.activeExecutionId ||
+        (input.executionId && input.executionId !== current.activeExecutionId))
+        throw new AgentError('MAR_AGENT_SUBAGENT_EXECUTION_STALE', 'Execution is not active.');
+    const completion = session.joinExecution(current.activeExecutionId);
+    if (!completion)
+        throw new AgentError('MAR_AGENT_SUBAGENT_EXECUTION_STALE', 'Execution is not active.');
+    if (!current.terminalEvent)
+        await session.cancel(current.activeExecutionId);
+    const result = await join(completion, call.signal);
+    call.signal.throwIfAborted();
+    const observation = observations.capture(session.id, current.activeExecutionId);
+    const data = {
+        agentId: session.id,
+        executionId: current.activeExecutionId,
+        status: result.status,
+        ...(result.errorCode ? { errorCode: result.errorCode } : {}),
+        ...(result.permissionStop ? { permissionStop: result.permissionStop } : {}),
+        ...publicChildSnapshot(observations.snapshot(session.id, current.activeExecutionId)),
+        ...(observation?.updates.length ? { updates: observation.updates } : {})
+    };
+    observation?.acknowledge();
+    return data;
+}

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

@@ -0,0 +1,17 @@
+import { type Agent, type ExecutionResult } from '@myagentroam/agent';
+import { nativeChildSnapshot } from './snapshot.js';
+/** Share only in-flight history pages within one parent scope; completed reads are never cached. */
+export declare function sharedSessionHistory(agent: Pick<Agent, 'sessionHistory'>): Pick<Agent, 'sessionHistory'>;
+/** Read the latest historical Execution without opening the Session. */
+export declare function historicalExecutionStatus(agent: Agent, sessionId: string, signal: AbortSignal, options?: {
+    details?: boolean;
+    activeExecutionId?: string;
+    history?: Pick<Agent, 'sessionHistory'>;
+}): Promise<{
+    status: 'idle' | 'running' | 'interrupted' | 'completed' | 'failed' | 'cancelled';
+    executionId?: string;
+    details?: ReturnType<typeof nativeChildSnapshot>;
+    errorCode?: string;
+    errorMessage?: string;
+    permissionStop?: ExecutionResult['permissionStop'];
+}>;

package/dist/cli/subagent/history.js

@@ -0,0 +1,85 @@
+import { AgentError } from '@myagentroam/agent';
+import { nativeChildSnapshot, projectChildEvent } from './snapshot.js';
+/** Share only in-flight history pages within one parent scope; completed reads are never cached. */
+export function sharedSessionHistory(agent) {
+    const pending = new Map();
+    return {
+        sessionHistory(sessionId, options) {
+            const key = JSON.stringify([sessionId, options?.limit ?? null, options?.cursor ?? null]);
+            const existing = pending.get(key);
+            if (existing)
+                return existing;
+            const request = agent.sessionHistory(sessionId, options);
+            pending.set(key, request);
+            void request
+                .finally(() => {
+                if (pending.get(key) === request)
+                    pending.delete(key);
+            })
+                .catch(() => { });
+            return request;
+        }
+    };
+}
+/** Read the latest historical Execution without opening the Session. */
+export async function historicalExecutionStatus(agent, sessionId, signal, options = {}) {
+    let cursor;
+    let latest;
+    const pages = [];
+    do {
+        signal.throwIfAborted();
+        const page = await (options.history ?? agent).sessionHistory(sessionId, {
+            limit: 100,
+            ...(cursor === undefined ? {} : { cursor })
+        });
+        signal.throwIfAborted();
+        const events = page.entries.flatMap((entry) => (entry.kind === 'event' ? [entry.event] : []));
+        latest ??= events.findLast((event) => event.type === 'execution.started' ||
+            event.type === 'execution.completed' ||
+            event.type === 'execution.failed' ||
+            event.type === 'execution.cancelled');
+        if (latest && !options.details)
+            break;
+        if (latest) {
+            const matching = events.filter((event) => event.executionId === latest.executionId);
+            pages.push(matching);
+            if (matching.some((event) => event.type === 'execution.started'))
+                break;
+        }
+        cursor = page.nextCursor;
+    } while (cursor);
+    if (!latest)
+        return { status: 'idle' };
+    let status;
+    if (latest.type === 'execution.started') {
+        if (latest.executionId === options.activeExecutionId)
+            status = 'running';
+        else {
+            const interrupted = await agent.sessionExecutionWasInterrupted(sessionId, latest.executionId, { signal });
+            signal.throwIfAborted();
+            if (!interrupted)
+                throw new AgentError('MAR_AGENT_SESSION_EXECUTION_CHANGED', 'Session Execution changed during inspection.');
+            status = 'interrupted';
+        }
+    }
+    else
+        status = latest.type.slice('execution.'.length);
+    const projection = { changedFiles: [] };
+    for (const events of pages.reverse())
+        for (const event of events)
+            projectChildEvent(projection, event, true);
+    return {
+        status,
+        executionId: latest.executionId,
+        ...(options.details ? { details: nativeChildSnapshot(projection) } : {}),
+        ...(latest.type === 'execution.completed' && latest.permissionStop
+            ? { permissionStop: latest.permissionStop }
+            : {}),
+        ...(latest.type === 'execution.failed'
+            ? {
+                errorCode: latest.code,
+                ...(latest.message === undefined ? {} : { errorMessage: latest.message })
+            }
+            : {})
+    };
+}

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

@@ -0,0 +1,10 @@
+import type { Agent } from '@myagentroam/agent';
+import { type AgentExtension } from '@myagentroam/agent/extensions';
+export { SUBAGENT_NATIVE_SERVICE } from './native.js';
+export type { NativeAgentGroup, NativeAgentSnapshot, NativeSpawnInput, NativeWaitInput, NativeSubagentClient, NativeSubagentService, ExtensionAgentSnapshot, ExtensionAgentManySnapshot, ExtensionAgentSpawnInput, ExtensionAgentWaitInput, ExtensionAgentsApi } from './native.js';
+export interface SubagentExtensionOptions {
+    /** Resolve the Agent after Host composition; it owns all Session execution. */
+    readonly agent: () => Agent;
+}
+/** Optional local consumer of Core Session lifecycle and observation APIs. */
+export declare function createSubagentExtension(options: SubagentExtensionOptions): AgentExtension;

package/dist/cli/subagent/index.js

@@ -0,0 +1,94 @@
+import { SESSION_CONTEXT_PROVIDER } from '@myagentroam/agent/extensions';
+import { SessionObservations } from './observations.js';
+import { registerStart, StartAdmission } from './start.js';
+import { registerControlTools } from './control.js';
+import { registerWait } from './wait.js';
+import { registerQueryTools } from './query.js';
+import { nativeSubagentService, SUBAGENT_NATIVE_SERVICE } from './native.js';
+import { childResources } from './resources.js';
+import { sharedSessionHistory } from './history.js';
+export { SUBAGENT_NATIVE_SERVICE } from './native.js';
+/** Optional local consumer of Core Session lifecycle and observation APIs. */
+export function createSubagentExtension(options) {
+    const admission = new StartAdmission();
+    const warmObservations = new Map();
+    return {
+        id: 'subagent',
+        apiVersion: '1.0',
+        provides: [{ key: SUBAGENT_NATIVE_SERVICE }],
+        async attachSession(context) {
+            const agent = options.agent();
+            const parent = await agent.getSession(context.sessionId);
+            const history = sharedSessionHistory(agent);
+            const observations = new SessionObservations(false, history);
+            const native = nativeSubagentService(context, agent, admission, warmObservations, parent.workspace, history);
+            if (warmObservations.has(context.sessionId))
+                throw new Error('SUBAGENT_SESSION_ALREADY_ATTACHED');
+            warmObservations.set(context.sessionId, observations);
+            let disposed = false;
+            let parentUnsubscribe;
+            const observe = (session) => {
+                if (disposed)
+                    return;
+                if (session.id === context.sessionId) {
+                    parentUnsubscribe?.();
+                    const subscription = session.subscribe((event) => {
+                        if (event.type !== 'execution.completed' &&
+                            event.type !== 'execution.failed' &&
+                            event.type !== 'execution.cancelled')
+                            return;
+                        admission.finish(event.executionId);
+                        parentUnsubscribe?.();
+                        parentUnsubscribe = undefined;
+                    });
+                    parentUnsubscribe = subscription.unsubscribe;
+                    if (subscription.terminalEvent) {
+                        admission.finish(subscription.terminalEvent.executionId);
+                        parentUnsubscribe();
+                        parentUnsubscribe = undefined;
+                    }
+                    return;
+                }
+                if (session.source.parentSessionId === context.sessionId &&
+                    session.workspace === parent.workspace)
+                    observations.observe(session);
+            };
+            const registration = agent.observeSessionExecutions(observe);
+            try {
+                for (const session of registration.sessions)
+                    observe(session);
+                context.services.provide(SUBAGENT_NATIVE_SERVICE, native.service);
+                context.services.provide(SESSION_CONTEXT_PROVIDER, {
+                    collect: (signal) => observations.collect(signal),
+                    wake: observations.wake,
+                    async resources(signal) {
+                        const resources = await childResources(agent, context.sessionId, signal, () => disposed, history);
+                        return disposed ? [] : resources;
+                    }
+                });
+                registerStart(context, agent, admission);
+                registerControlTools(context, agent, observations, warmObservations, admission);
+                registerWait(context, agent, observations, history);
+                registerQueryTools(context, agent);
+            }
+            catch (error) {
+                disposed = true;
+                void native.close().catch(() => { });
+                registration.unsubscribe();
+                parentUnsubscribe?.();
+                warmObservations.delete(context.sessionId);
+                observations.close();
+                throw error;
+            }
+            return async () => {
+                disposed = true;
+                const closing = native.close();
+                registration.unsubscribe();
+                parentUnsubscribe?.();
+                warmObservations.delete(context.sessionId);
+                observations.close();
+                await closing;
+            };
+        }
+    };
+}

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

@@ -0,0 +1,91 @@
+import { type Agent, type AgentReasoningEffort, type AgentSessionInputReceipt, type ExecutionResult } from '@myagentroam/agent';
+import type { ExtensionServiceKey, SessionExtensionContext } from '@myagentroam/agent/extensions';
+import { SessionObservations } from './observations.js';
+import { type StartAdmission } from './start.js';
+import { type WaitInput } from './wait.js';
+import { type ChildSnapshot } from './snapshot.js';
+export interface NativeSpawnInput {
+    readonly prompt: string;
+    readonly description?: string;
+    readonly role?: 'general-purpose' | 'explore';
+    readonly modelId?: string;
+    readonly reasoningEffort?: AgentReasoningEffort;
+    readonly background?: boolean;
+    readonly waitFor?: 'start' | 'completion';
+    readonly signal?: AbortSignal;
+    readonly turnSignal?: AbortSignal;
+}
+export interface NativeWaitInput extends WaitInput {
+    readonly signal?: AbortSignal;
+}
+export interface NativeAgentSnapshot extends Record<string, unknown> {
+    readonly agentId: string;
+    readonly description: string;
+    readonly status: 'idle' | 'not-started' | 'running' | 'completed' | 'failed' | 'cancelled' | 'interrupted';
+    readonly executionId?: string;
+    readonly role?: 'general-purpose' | 'explore';
+    readonly extensionId?: string;
+    readonly modelId?: string;
+    readonly modelName?: string;
+    readonly reasoningEffort?: string;
+    readonly summary?: string;
+    readonly turnId?: string;
+    readonly receipt?: AgentSessionInputReceipt;
+    readonly changedFiles?: readonly string[];
+    readonly latestMessage?: ChildSnapshot['latestMessage'];
+    readonly latestActivity?: ChildSnapshot['latestActivity'];
+    readonly verification?: readonly string[];
+    readonly evidence?: readonly {
+        path: string;
+        startLine?: number;
+        endLine?: number;
+    }[];
+    readonly errorCode?: string;
+    readonly errorMessage?: string;
+    readonly permissionStop?: ExecutionResult['permissionStop'];
+    readonly waitOutcome?: 'snapshot' | 'message' | 'completion' | 'timeout' | 'interrupted';
+}
+export interface NativeAgentGroup extends Record<string, unknown> {
+    readonly mode: 'any' | 'all';
+    readonly waitFor: 'message' | 'completion';
+    readonly waitOutcome: 'snapshot' | 'message' | 'completion' | 'timeout' | 'interrupted';
+    readonly agents: readonly NativeAgentSnapshot[];
+    readonly pendingAgentIds: readonly string[];
+}
+export interface NativeSubagentClient {
+    spawn(input: NativeSpawnInput): Promise<NativeAgentSnapshot>;
+    wait(input: NativeWaitInput): Promise<NativeAgentSnapshot | NativeAgentGroup>;
+    list(input?: {
+        signal?: AbortSignal;
+    }): Promise<readonly NativeAgentSnapshot[]>;
+    inspect(input: {
+        agentId: string;
+        signal?: AbortSignal;
+    }): Promise<NativeAgentSnapshot>;
+    message(input: {
+        agentId: string;
+        message: string;
+        delivery?: 'append' | 'replace';
+        signal?: AbortSignal;
+    }): Promise<Record<string, unknown>>;
+    cancel(input: {
+        agentId: string;
+        executionId?: string;
+        signal?: AbortSignal;
+    }): Promise<NativeAgentSnapshot>;
+    close(): Promise<void>;
+}
+export interface NativeSubagentService {
+    open(): NativeSubagentClient;
+}
+export type ExtensionAgentSnapshot = NativeAgentSnapshot;
+export type ExtensionAgentManySnapshot = NativeAgentGroup;
+export type ExtensionAgentSpawnInput = NativeSpawnInput;
+export type ExtensionAgentWaitInput = NativeWaitInput;
+export type ExtensionAgentsApi = NativeSubagentClient;
+export declare const SUBAGENT_NATIVE_SERVICE: ExtensionServiceKey<NativeSubagentService>;
+/** Each native client owns an independent observation cursor, never a Session Execution. */
+export declare function nativeSubagentService(context: SessionExtensionContext, agent: Agent, admission: StartAdmission, warmObservations: ReadonlyMap<string, SessionObservations>, parentWorkspace: string, historyReader?: Pick<Agent, 'sessionHistory'>): {
+    service: NativeSubagentService;
+    close(): Promise<void>;
+};