@myagentroam/agent 0.11.39 → 0.11.40

package/dist/cli/subagent/native.js

@@ -0,0 +1,359 @@
+import { AgentError } from '@myagentroam/agent';
+import { SessionObservations } from './observations.js';
+import { startChild } from './start.js';
+import { sendChild, stopChild } from './control.js';
+import { waitForChild } from './wait.js';
+import { nativeChildSnapshot, projectChildEvent } from './snapshot.js';
+import { historicalExecutionStatus } from './history.js';
+export const SUBAGENT_NATIVE_SERVICE = {
+    id: 'subagent.native',
+    scope: 'session',
+    bindConsumer: (service, consumer) => service.bind(consumer)
+};
+/** Each native client owns an independent observation cursor, never a Session Execution. */
+export function nativeSubagentService(context, agent, admission, warmObservations, parentWorkspace, historyReader = agent) {
+    const clients = new Set();
+    let closed = false;
+    return {
+        service: {
+            open() {
+                throw new AgentError('MAR_AGENT_EXTENSION_SERVICE_SCOPE', 'A consumer scope is required.');
+            },
+            bind(consumer) {
+                return {
+                    open() {
+                        if (closed)
+                            throw new AgentError('MAR_AGENT_EXTENSION_DISPOSED', 'Subagent service is closed.');
+                        const observations = new SessionObservations(true, historyReader);
+                        const pending = new Set();
+                        const closingSignal = new AbortController();
+                        let clientClosed = false;
+                        const observe = (session) => {
+                            if (!clientClosed &&
+                                session.source.parentSessionId === context.sessionId &&
+                                session.workspace === parentWorkspace)
+                                observations.observe(session);
+                        };
+                        const registration = agent.observeSessionExecutions(observe);
+                        for (const session of registration.sessions)
+                            observe(session);
+                        let closing;
+                        const close = () => (closing ??= (async () => {
+                            clientClosed = true;
+                            closingSignal.abort();
+                            registration.unsubscribe();
+                            await Promise.allSettled([...pending]);
+                            observations.close();
+                            clients.delete(close);
+                        })());
+                        clients.add(close);
+                        try {
+                            consumer.onDispose(close);
+                        }
+                        catch (error) {
+                            void close().catch(() => { });
+                            throw error;
+                        }
+                        const run = (action, signal) => {
+                            if (clientClosed)
+                                throw new AgentError('MAR_AGENT_EXTENSION_DISPOSED', 'Subagent client is closed.');
+                            const effectiveSignal = signal
+                                ? AbortSignal.any([signal, closingSignal.signal])
+                                : closingSignal.signal;
+                            const operation = consumer.run(action, effectiveSignal);
+                            pending.add(operation);
+                            void operation.finally(() => pending.delete(operation)).catch(() => { });
+                            return operation;
+                        };
+                        return {
+                            async spawn(input) {
+                                if (!input ||
+                                    typeof input.prompt !== 'string' ||
+                                    !input.prompt.trim() ||
+                                    (input.description !== undefined && !input.description.trim()) ||
+                                    (input.role !== undefined &&
+                                        !['general-purpose', 'explore'].includes(input.role)) ||
+                                    (input.waitFor !== undefined &&
+                                        !['start', 'completion'].includes(input.waitFor)) ||
+                                    (input.background !== undefined && typeof input.background !== 'boolean'))
+                                    throw new AgentError('MAR_AGENT_EXTENSION_AGENT_INPUT_INVALID', 'Agent spawn input is invalid.');
+                                return run(async (call) => {
+                                    const started = await startChild(context, agent, admission, {
+                                        prompt: input.prompt,
+                                        description: input.description ?? 'Extension agent',
+                                        role: input.role ?? 'general-purpose',
+                                        ...(input.turnSignal === undefined ? {} : { turnSignal: input.turnSignal }),
+                                        ...(input.modelId === undefined ? {} : { modelId: input.modelId }),
+                                        ...(input.reasoningEffort === undefined
+                                            ? {}
+                                            : { reasoningEffort: input.reasoningEffort })
+                                    }, call, 'native');
+                                    if (!started.execution ||
+                                        !(input.waitFor === 'completion' ||
+                                            (input.waitFor === undefined && input.background === false)))
+                                        return started.data;
+                                    const result = await waitForChild(context, agent, observations, { agentId: String(started.data.agentId), untilSettled: true }, call, 'native', observations, historyReader);
+                                    return { ...started.data, ...result.data };
+                                }, input.signal);
+                            },
+                            async wait(input) {
+                                if (!input || typeof input !== 'object')
+                                    throw new AgentError('MAR_AGENT_EXTENSION_AGENT_INPUT_INVALID', 'Agent wait input is invalid.');
+                                return run(async (call) => (await waitForChild(context, agent, observations, input, call, 'native', observations, historyReader)).data, input.signal);
+                            },
+                            async list(input = {}) {
+                                return run(async (call) => {
+                                    const parent = await agent.getSession(context.sessionId);
+                                    const children = [];
+                                    const live = new Map();
+                                    const registration = agent.observeSessionExecutions((session) => {
+                                        live.set(session.id, session);
+                                    });
+                                    for (const session of registration.sessions)
+                                        live.set(session.id, session);
+                                    let cursor;
+                                    try {
+                                        do {
+                                            call.signal.throwIfAborted();
+                                            const page = await agent.listSessions({
+                                                parentSessionId: context.sessionId,
+                                                limit: 100,
+                                                ...(cursor ? { cursor } : {})
+                                            });
+                                            for (const session of page.sessions)
+                                                if (session.workspace === parent.workspace) {
+                                                    call.signal.throwIfAborted();
+                                                    const subscription = live.get(session.id)?.subscribe(() => { });
+                                                    const terminalEvent = subscription?.terminalEvent;
+                                                    const active = subscription?.activeExecutionId;
+                                                    subscription?.unsubscribe();
+                                                    let history;
+                                                    try {
+                                                        history = await historicalExecutionStatus(agent, session.id, call.signal, {
+                                                            details: true,
+                                                            history: historyReader,
+                                                            ...(active ? { activeExecutionId: active } : {})
+                                                        });
+                                                    }
+                                                    catch (error) {
+                                                        if (error instanceof Error &&
+                                                            'code' in error &&
+                                                            error.code === 'MAR_AGENT_SESSION_NOT_FOUND')
+                                                            continue;
+                                                        throw error;
+                                                    }
+                                                    let status = active
+                                                        ? 'running'
+                                                        : history.status;
+                                                    let currentExecutionId = active ?? history.executionId;
+                                                    if (terminalEvent)
+                                                        status = terminalEvent.type.slice('execution.'.length);
+                                                    else if (!active) {
+                                                        const latest = live.get(session.id)?.subscribe(() => { });
+                                                        if (latest?.activeExecutionId && !latest.terminalEvent) {
+                                                            status = 'running';
+                                                            currentExecutionId = latest.activeExecutionId;
+                                                        }
+                                                        else if (latest?.terminalEvent) {
+                                                            status = latest.terminalEvent.type.slice('execution.'.length);
+                                                            currentExecutionId = latest.activeExecutionId;
+                                                        }
+                                                        latest?.unsubscribe();
+                                                    }
+                                                    const observed = observations.terminal(session.id);
+                                                    if (status !== 'running' &&
+                                                        !terminalEvent &&
+                                                        observed &&
+                                                        observed.executionId !== history.executionId) {
+                                                        status = observed.type.slice('execution.'.length);
+                                                        currentExecutionId = observed.executionId;
+                                                    }
+                                                    const details = history.executionId === currentExecutionId
+                                                        ? history.details
+                                                        : currentExecutionId
+                                                            ? nativeChildSnapshot(observations.snapshot(session.id, currentExecutionId))
+                                                            : undefined;
+                                                    const visibleDetails = status === 'running' && details
+                                                        ? {
+                                                            ...(details.latestMessage
+                                                                ? { latestMessage: details.latestMessage }
+                                                                : {}),
+                                                            ...(details.latestActivity
+                                                                ? { latestActivity: details.latestActivity }
+                                                                : {})
+                                                        }
+                                                        : details;
+                                                    children.push({
+                                                        createdAt: session.createdAt,
+                                                        snapshot: {
+                                                            agentId: session.id,
+                                                            status,
+                                                            description: session.source.type === 'subagent'
+                                                                ? session.source.description
+                                                                : session.title,
+                                                            ...(currentExecutionId === undefined
+                                                                ? {}
+                                                                : { executionId: currentExecutionId }),
+                                                            ...visibleDetails,
+                                                            ...(history.executionId === currentExecutionId &&
+                                                                history.errorCode !== undefined
+                                                                ? {
+                                                                    errorCode: history.errorCode,
+                                                                    ...(history.errorMessage === undefined
+                                                                        ? {}
+                                                                        : { errorMessage: history.errorMessage })
+                                                                }
+                                                                : {}),
+                                                            ...(history.executionId === currentExecutionId &&
+                                                                history.permissionStop
+                                                                ? { permissionStop: history.permissionStop }
+                                                                : {}),
+                                                            ...(observed?.type === 'execution.failed' &&
+                                                                observed.executionId === currentExecutionId
+                                                                ? {
+                                                                    errorCode: observed.code,
+                                                                    ...(observed.message === undefined
+                                                                        ? {}
+                                                                        : { errorMessage: observed.message })
+                                                                }
+                                                                : {}),
+                                                            ...(session.modelId === undefined
+                                                                ? {}
+                                                                : { modelId: session.modelId }),
+                                                            ...(session.modelName === undefined
+                                                                ? {}
+                                                                : { modelName: session.modelName }),
+                                                            ...(session.reasoningEffort === undefined
+                                                                ? {}
+                                                                : { reasoningEffort: session.reasoningEffort }),
+                                                            ...(session.source.type === 'subagent'
+                                                                ? {
+                                                                    role: session.source.role,
+                                                                    ...(session.source.extensionId === undefined
+                                                                        ? {}
+                                                                        : { extensionId: session.source.extensionId })
+                                                                }
+                                                                : {})
+                                                        }
+                                                    });
+                                                }
+                                            cursor = page.nextCursor;
+                                        } while (cursor);
+                                    }
+                                    finally {
+                                        registration.unsubscribe();
+                                    }
+                                    return children
+                                        .sort((left, right) => left.createdAt.localeCompare(right.createdAt))
+                                        .map(({ snapshot }) => snapshot);
+                                }, input.signal);
+                            },
+                            async inspect(input) {
+                                if (!input || typeof input.agentId !== 'string' || !input.agentId)
+                                    throw new AgentError('MAR_AGENT_EXTENSION_AGENT_INPUT_INVALID', 'Agent target is invalid.');
+                                return run(async (call) => {
+                                    const parent = await agent.getSession(context.sessionId);
+                                    const child = await agent.getSession(input.agentId);
+                                    if (child.workspace !== parent.workspace ||
+                                        child.source.parentSessionId !== parent.id)
+                                        throw new AgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Session is not available.');
+                                    call.signal.throwIfAborted();
+                                    try {
+                                        const state = (await waitForChild(context, agent, observations, { agentId: child.id, waitMs: 0 }, call, 'native', observations, historyReader)).data;
+                                        const pages = [];
+                                        let cursor;
+                                        if (state.executionId)
+                                            do {
+                                                call.signal.throwIfAborted();
+                                                const page = await historyReader.sessionHistory(child.id, {
+                                                    limit: 100,
+                                                    ...(cursor === undefined ? {} : { cursor })
+                                                });
+                                                call.signal.throwIfAborted();
+                                                const events = page.entries.flatMap((entry) => entry.kind === 'event' && entry.event.executionId === state.executionId
+                                                    ? [entry.event]
+                                                    : []);
+                                                pages.push(events);
+                                                cursor = events.some((event) => event.type === 'execution.started')
+                                                    ? undefined
+                                                    : page.nextCursor;
+                                            } while (cursor);
+                                        const full = { changedFiles: [] };
+                                        for (const events of pages.reverse())
+                                            for (const event of events)
+                                                projectChildEvent(full, event, true);
+                                        if (state.executionId) {
+                                            const live = observations.snapshot(child.id, state.executionId);
+                                            if (live.summary !== undefined) {
+                                                full.summary = live.summary;
+                                                if (live.turnId === undefined)
+                                                    delete full.turnId;
+                                                else
+                                                    full.turnId = live.turnId;
+                                            }
+                                            for (const file of live.changedFiles)
+                                                if (!full.changedFiles.includes(file))
+                                                    full.changedFiles.push(file);
+                                        }
+                                        return {
+                                            ...state,
+                                            ...nativeChildSnapshot(full),
+                                            modelId: child.modelId,
+                                            description: child.source.type === 'subagent' ? child.source.description : child.title
+                                        };
+                                    }
+                                    catch (error) {
+                                        if (!(error instanceof AgentError) ||
+                                            error.code !== 'MAR_AGENT_SUBAGENT_EXECUTION_NOT_FOUND')
+                                            throw error;
+                                        return {
+                                            agentId: child.id,
+                                            status: 'idle',
+                                            modelId: child.modelId,
+                                            description: child.source.type === 'subagent' ? child.source.description : child.title
+                                        };
+                                    }
+                                }, input.signal);
+                            },
+                            async message(input) {
+                                if (!input ||
+                                    typeof input.agentId !== 'string' ||
+                                    !input.agentId ||
+                                    typeof input.message !== 'string' ||
+                                    !input.message.trim() ||
+                                    (input.delivery !== undefined && !['append', 'replace'].includes(input.delivery)))
+                                    throw new AgentError('MAR_AGENT_EXTENSION_AGENT_INPUT_INVALID', 'Agent message input is invalid.');
+                                return run(async (call) => {
+                                    const result = await sendChild(context, agent, observations, warmObservations, admission, {
+                                        agentId: input.agentId,
+                                        content: input.message,
+                                        ...(input.delivery ? { delivery: input.delivery } : {})
+                                    }, call, 'native');
+                                    return result;
+                                }, input.signal);
+                            },
+                            async cancel(input) {
+                                if (!input || typeof input.agentId !== 'string' || !input.agentId)
+                                    throw new AgentError('MAR_AGENT_EXTENSION_AGENT_INPUT_INVALID', 'Agent target is invalid.');
+                                return run(async (call) => {
+                                    const result = await stopChild(context, agent, observations, input, call);
+                                    const child = await agent.getSession(input.agentId);
+                                    return {
+                                        ...result,
+                                        description: child.source.type === 'subagent' ? child.source.description : child.title,
+                                        modelId: child.modelId
+                                    };
+                                }, input.signal);
+                            },
+                            close
+                        };
+                    }
+                };
+            }
+        },
+        async close() {
+            closed = true;
+            await Promise.all([...clients].map((close) => close()));
+        }
+    };
+}

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

@@ -0,0 +1,57 @@
+import type { Agent, AgentEvent, AgentSession } from '@myagentroam/agent';
+import type { ExtensionSessionContextProvider } from '@myagentroam/agent/extensions';
+import { type ChildSnapshot } from './snapshot.js';
+/** One warm parent Session's live observations; Execution remains owned by Core. */
+export declare class SessionObservations implements ExtensionSessionContextProvider {
+    #private;
+    readonly full: boolean;
+    private readonly agent?;
+    constructor(full?: boolean, agent?: Pick<Agent, "sessionHistory"> | undefined);
+    readonly wake: {
+        pending: () => boolean;
+        subscribe: (listener: () => void) => () => boolean;
+    };
+    observe(session: Pick<AgentSession, 'id' | 'subscribe'>): void;
+    /** Upward reports are collected at the parent's next natural round, without waking it. */
+    report(sessionId: string, executionId: string, value: string): boolean;
+    snapshot(sessionId: string, executionId: string): ChildSnapshot;
+    terminal(sessionId: string): AgentEvent | undefined;
+    rememberReceipt(sessionId: string, receipt: {
+        clientMessageId: string;
+        executionId: string;
+    }): void;
+    receipt(sessionId: string): {
+        clientMessageId: string;
+        executionId: string;
+    } | undefined;
+    capture(sessionId: string, executionId?: string): {
+        sessionId: string;
+        executionId: string;
+        snapshot: {
+            changedFilesTruncated?: boolean;
+            changedFiles?: string[];
+            turnId?: string;
+            summaryTruncated?: boolean;
+            summary?: string;
+        };
+        updates: {
+            permissionStop?: import("@myagentroam/agent").PermissionStop;
+            errorMessage?: string;
+            errorCode?: string;
+            truncated?: boolean;
+            final?: boolean;
+            kind: "message" | "terminal";
+            value: string;
+        }[];
+        acknowledge: () => void;
+    } | undefined;
+    /** Capture the currently unread versions without consuming later events. */
+    acknowledgement(sessionId: string): () => void;
+    /** Claim a terminal projection once per warm parent, including restored history. */
+    claimTerminal(sessionId: string, executionId: string): boolean;
+    collect(signal: AbortSignal): {
+        content: string;
+        acknowledge: () => void;
+    }[];
+    close(): void;
+}