@myagentroam/agent 0.11.38 → 0.11.40

package/dist/cli/subagent/observations.js

@@ -0,0 +1,351 @@
+import { boundedUtf8, projectChildEvent, publicChildSnapshot } from './snapshot.js';
+/** One warm parent Session's live observations; Execution remains owned by Core. */
+export class SessionObservations {
+    full;
+    agent;
+    constructor(full = false, agent) {
+        this.full = full;
+        this.agent = agent;
+    }
+    #subscriptions = new Map();
+    #items = new Map();
+    #snapshots = new Map();
+    #terminals = new Map();
+    #latestTerminal = new Map();
+    #consumedTerminals = new Set();
+    #receipts = new Map();
+    #listeners = new Set();
+    #revision = 0;
+    #closed = false;
+    wake = {
+        pending: () => [...this.#items.values()].some((item) => item.wakes),
+        subscribe: (listener) => {
+            if (!this.#closed)
+                this.#listeners.add(listener);
+            return () => this.#listeners.delete(listener);
+        }
+    };
+    observe(session) {
+        if (this.#closed || this.#subscriptions.has(session.id))
+            return;
+        const subscription = session.subscribe((event) => {
+            this.#publish(session.id, event);
+            if (isTerminal(event))
+                this.#unobserve(session.id);
+        });
+        this.#subscriptions.set(session.id, subscription.unsubscribe);
+        if (subscription.terminalEvent) {
+            this.#publish(session.id, subscription.terminalEvent);
+            this.#unobserve(session.id);
+        }
+    }
+    #unobserve(sessionId) {
+        this.#subscriptions.get(sessionId)?.();
+        this.#subscriptions.delete(sessionId);
+    }
+    #publish(sessionId, event) {
+        if (this.#closed)
+            return;
+        const snapshotKey = JSON.stringify([sessionId, event.executionId]);
+        if ((event.type === 'message.completed' && (this.full || event.phase === 'final_answer')) ||
+            (event.type === 'tool.completed' && (this.full || event.toolName === 'apply_patch')) ||
+            (this.full && (event.type === 'tool.started' || event.type === 'tool.failed')) ||
+            event.type === 'execution.failed' ||
+            event.type === 'execution.cancelled') {
+            const snapshot = this.#snapshots.get(snapshotKey) ?? { changedFiles: [] };
+            projectChildEvent(snapshot, event, this.full);
+            this.#snapshots.set(snapshotKey, snapshot);
+        }
+        const item = event.type === 'message.completed'
+            ? { kind: 'message', value: event.text }
+            : event.type === 'execution.completed' ||
+                event.type === 'execution.cancelled' ||
+                event.type === 'execution.failed'
+                ? { kind: 'terminal', value: event.type }
+                : undefined;
+        if (!item)
+            return;
+        if (item.kind === 'terminal' && this.agent) {
+            this.#terminals.set(snapshotKey, event);
+            this.#latestTerminal.set(sessionId, snapshotKey);
+        }
+        const key = JSON.stringify([sessionId, event.executionId, item.kind]);
+        const bounded = this.full
+            ? { value: item.value, truncated: false }
+            : boundedUtf8(item.value, 2000);
+        this.#items.set(key, {
+            sessionId,
+            executionId: event.executionId,
+            ...item,
+            value: bounded.value,
+            ...(bounded.truncated ? { truncated: true } : {}),
+            ...(event.type === 'execution.failed'
+                ? {
+                    errorCode: event.code,
+                    ...(event.message === undefined
+                        ? {}
+                        : {
+                            errorMessage: this.full ? event.message : boundedUtf8(event.message, 1000).value
+                        })
+                }
+                : {}),
+            ...(event.type === 'execution.completed' && event.permissionStop !== undefined
+                ? {
+                    permissionStop: {
+                        ...event.permissionStop,
+                        reason: this.full
+                            ? event.permissionStop.reason
+                            : boundedUtf8(event.permissionStop.reason, 1000).value
+                    }
+                }
+                : {}),
+            ...(event.type === 'message.completed' && event.phase === 'final_answer'
+                ? { final: true }
+                : {}),
+            revision: ++this.#revision,
+            wakes: item.kind === 'message'
+        });
+        if (item.kind === 'message')
+            for (const listener of [...this.#listeners]) {
+                try {
+                    listener();
+                }
+                catch {
+                    /* Listener failures cannot affect Core event delivery. */
+                }
+            }
+    }
+    /** Upward reports are collected at the parent's next natural round, without waking it. */
+    report(sessionId, executionId, value) {
+        if (this.#closed)
+            return false;
+        const key = JSON.stringify([sessionId, executionId, 'report']);
+        const bounded = boundedUtf8(value, 2000);
+        this.#items.set(key, {
+            sessionId,
+            executionId,
+            kind: 'message',
+            value: bounded.value,
+            ...(bounded.truncated ? { truncated: true } : {}),
+            revision: ++this.#revision,
+            wakes: false
+        });
+        return true;
+    }
+    snapshot(sessionId, executionId) {
+        const stored = this.#snapshots.get(JSON.stringify([sessionId, executionId]));
+        return stored
+            ? {
+                ...stored,
+                changedFiles: [...stored.changedFiles],
+                ...(stored.latestMessage ? { latestMessage: { ...stored.latestMessage } } : {}),
+                ...(stored.latestActivity ? { latestActivity: { ...stored.latestActivity } } : {}),
+                ...(stored.verification ? { verification: [...stored.verification] } : {}),
+                ...(stored.evidence ? { evidence: stored.evidence.map((item) => ({ ...item })) } : {})
+            }
+            : { changedFiles: [] };
+    }
+    terminal(sessionId) {
+        const key = this.#latestTerminal.get(sessionId);
+        return key === undefined ? undefined : this.#terminals.get(key);
+    }
+    #releaseSnapshot(sessionId, executionId) {
+        if (this.#terminals.has(JSON.stringify([sessionId, executionId])) ||
+            [...this.#items.values()].some((item) => item.sessionId === sessionId && item.executionId === executionId))
+            return;
+        this.#snapshots.delete(JSON.stringify([sessionId, executionId]));
+    }
+    /** A consumed observation may be discarded only after its terminal is present in Session history. */
+    #verifyTerminal(sessionId, executionId) {
+        const key = JSON.stringify([sessionId, executionId]);
+        const terminal = this.#terminals.get(key);
+        if (!this.agent || !terminal) {
+            this.#releaseSnapshot(sessionId, executionId);
+            return;
+        }
+        void this.agent
+            .sessionHistory(sessionId, { limit: 100 })
+            .then((page) => {
+            if (this.#closed || this.#terminals.get(key) !== terminal)
+                return;
+            if (!page.entries.some((entry) => entry.kind === 'event' && entry.event.eventId === terminal.eventId))
+                return;
+            this.#terminals.delete(key);
+            if (this.#latestTerminal.get(sessionId) === key)
+                this.#latestTerminal.delete(sessionId);
+            this.#releaseSnapshot(sessionId, executionId);
+        })
+            .catch(() => {
+            /* Retain the observation if persistence cannot be confirmed. */
+        });
+    }
+    rememberReceipt(sessionId, receipt) {
+        if (!this.#closed)
+            this.#receipts.set(sessionId, receipt);
+    }
+    receipt(sessionId) {
+        return this.#receipts.get(sessionId);
+    }
+    capture(sessionId, executionId) {
+        const items = [...this.#items.entries()].filter(([, item]) => item.sessionId === sessionId &&
+            (executionId === undefined || item.executionId === executionId));
+        const first = items[0]?.[1];
+        if (!first)
+            return undefined;
+        const captured = items.filter(([, item]) => item.executionId === first.executionId);
+        const snapshotKey = JSON.stringify([sessionId, first.executionId]);
+        const snapshot = captured.some(([, item]) => item.kind === 'terminal')
+            ? publicChildSnapshot(this.#snapshots.get(snapshotKey))
+            : {};
+        return {
+            sessionId,
+            executionId: first.executionId,
+            snapshot,
+            updates: captured.map(([, item]) => ({
+                kind: item.kind,
+                value: item.value,
+                ...(item.final ? { final: true } : {}),
+                ...(item.truncated ? { truncated: true } : {}),
+                ...(item.errorCode === undefined ? {} : { errorCode: item.errorCode }),
+                ...(item.errorMessage === undefined ? {} : { errorMessage: item.errorMessage }),
+                ...(item.permissionStop === undefined ? {} : { permissionStop: item.permissionStop })
+            })),
+            acknowledge: () => {
+                for (const [key, item] of captured) {
+                    if (this.#items.get(key)?.revision !== item.revision)
+                        continue;
+                    this.#items.delete(key);
+                    if (item.kind === 'terminal')
+                        this.claimTerminal(item.sessionId, item.executionId);
+                }
+                if (captured.some(([, item]) => item.kind === 'terminal'))
+                    this.#verifyTerminal(sessionId, first.executionId);
+            }
+        };
+    }
+    /** Capture the currently unread versions without consuming later events. */
+    acknowledgement(sessionId) {
+        const captured = [...this.#items.entries()].filter(([, item]) => item.sessionId === sessionId);
+        return () => {
+            for (const [key, item] of captured) {
+                if (this.#items.get(key)?.revision !== item.revision)
+                    continue;
+                this.#items.delete(key);
+                if (item.kind === 'terminal')
+                    this.claimTerminal(item.sessionId, item.executionId);
+            }
+            for (const [, item] of captured) {
+                if (item.kind !== 'terminal' ||
+                    [...this.#items.values()].some((remaining) => remaining.sessionId === item.sessionId && remaining.executionId === item.executionId))
+                    continue;
+                this.#verifyTerminal(item.sessionId, item.executionId);
+            }
+        };
+    }
+    /** Claim a terminal projection once per warm parent, including restored history. */
+    claimTerminal(sessionId, executionId) {
+        const key = JSON.stringify([sessionId, executionId]);
+        if (this.#consumedTerminals.has(key))
+            return false;
+        this.#consumedTerminals.add(key);
+        return true;
+    }
+    collect(signal) {
+        signal.throwIfAborted();
+        const ids = [...new Set([...this.#items.values()].map((item) => item.sessionId))].slice(0, 8);
+        return ids.flatMap((id) => {
+            const item = this.capture(id);
+            if (!item)
+                return [];
+            const updates = item.snapshot.summary && !item.snapshot.summaryTruncated
+                ? item.updates.filter((update) => !('final' in update && update.final))
+                : item.updates;
+            const content = boundedObservation({
+                agentId: id,
+                executionId: item.executionId,
+                ...item.snapshot,
+                updates
+            });
+            return [{ content, acknowledge: item.acknowledge }];
+        });
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const unsubscribe of this.#subscriptions.values())
+            unsubscribe();
+        this.#subscriptions.clear();
+        this.#listeners.clear();
+        this.#items.clear();
+        this.#snapshots.clear();
+        this.#terminals.clear();
+        this.#latestTerminal.clear();
+        this.#consumedTerminals.clear();
+        this.#receipts.clear();
+    }
+}
+function isTerminal(event) {
+    return (event.type === 'execution.completed' ||
+        event.type === 'execution.cancelled' ||
+        event.type === 'execution.failed');
+}
+function boundedObservation(input) {
+    const data = {
+        ...input,
+        ...(input.changedFiles ? { changedFiles: [...input.changedFiles] } : {}),
+        updates: input.updates.map((update) => ({ ...update }))
+    };
+    let updatesTruncated = false;
+    const render = () => `<mar_subagent_update>\n${JSON.stringify({
+        ...data,
+        ...(updatesTruncated ? { updatesTruncated: true } : {})
+    }).replace(/[<>&]/g, (character) => character === '<' ? '\\u003c' : character === '>' ? '\\u003e' : '\\u0026')}\n</mar_subagent_update>`;
+    const tooLarge = () => Buffer.byteLength(render(), 'utf8') > 32768;
+    while (tooLarge() && data.changedFiles?.length) {
+        data.changedFiles.pop();
+        data.changedFilesTruncated = true;
+    }
+    const shorten = (value, set) => {
+        let low = 0;
+        let high = Buffer.byteLength(value, 'utf8');
+        while (low < high) {
+            const middle = Math.ceil((low + high) / 2);
+            set(boundedUtf8(value, middle).value);
+            if (tooLarge())
+                high = middle - 1;
+            else
+                low = middle;
+        }
+        set(boundedUtf8(value, low).value);
+    };
+    if (tooLarge() && data.summary !== undefined) {
+        const summary = data.summary;
+        data.summaryTruncated = true;
+        shorten(summary, (value) => {
+            data.summary = value;
+        });
+    }
+    for (const update of data.updates) {
+        if (!tooLarge())
+            break;
+        const value = update.value;
+        update.truncated = true;
+        shorten(value, (text) => {
+            update.value = text;
+        });
+    }
+    while (tooLarge() && data.updates.length) {
+        data.updates.pop();
+        updatesTruncated = true;
+    }
+    if (tooLarge()) {
+        const fallback = {
+            agentId: boundedUtf8(data.agentId, 512).value,
+            executionId: boundedUtf8(data.executionId, 512).value,
+            detailsTruncated: true
+        };
+        return `<mar_subagent_update>\n${JSON.stringify(fallback).replace(/[<>&]/g, (character) => character === '<' ? '\\u003c' : character === '>' ? '\\u003e' : '\\u0026')}\n</mar_subagent_update>`;
+    }
+    return render();
+}

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

@@ -0,0 +1,4 @@
+import { type Agent } from '@myagentroam/agent';
+import type { SessionExtensionContext } from '@myagentroam/agent/extensions';
+/** Read-only local discovery uses the Core catalog and never opens historical Sessions. */
+export declare function registerQueryTools(context: SessionExtensionContext, agent: Agent): void;

package/dist/cli/subagent/query.js

@@ -0,0 +1,114 @@
+import { AgentError } from '@myagentroam/agent';
+/** Read-only local discovery uses the Core catalog and never opens historical Sessions. */
+export function registerQueryTools(context, agent) {
+    context.tools.register({
+        name: 'agent_list',
+        description: 'List direct child Sessions or eligible local models.',
+        allowedCallers: ['direct', 'programmatic'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: { type: 'string', enum: ['children', 'profile'] },
+                limit: { type: 'integer', minimum: 1, maximum: 100 },
+                cursor: { type: 'string', minLength: 1 }
+            },
+            additionalProperties: false
+        },
+        async execute(raw) {
+            const input = raw;
+            const current = await agent.getSession(context.sessionId);
+            const data = input.scope === 'profile'
+                ? {
+                    models: (context.models?.list() ?? []).filter((model) => model.conversationModel && model.subagentModel)
+                }
+                : await agent
+                    .listSessions({
+                    parentSessionId: context.sessionId,
+                    ...(input.limit === undefined ? {} : { limit: input.limit }),
+                    ...(input.cursor === undefined ? {} : { cursor: input.cursor })
+                })
+                    .then((page) => ({
+                    current: {
+                        agentId: current.id,
+                        parentSessionId: current.source.parentSessionId ?? null
+                    },
+                    agents: page.sessions
+                        .filter((session) => session.workspace === current.workspace)
+                        .map((session) => ({
+                        agentId: session.id,
+                        title: session.title,
+                        parentSessionId: session.source.parentSessionId,
+                        modelId: session.modelId,
+                        lastActivityAt: session.lastActivityAt
+                    })),
+                    ...(page.nextCursor ? { nextCursor: page.nextCursor } : {})
+                }));
+            return { data, content: JSON.stringify(data) };
+        }
+    });
+    context.tools.register({
+        name: 'agent_view',
+        description: 'View a direct child or parent Session and its public history.',
+        allowedCallers: ['direct', 'programmatic'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: { type: 'string', minLength: 1 },
+                includeHistory: { type: 'boolean' },
+                limit: { type: 'integer', minimum: 1, maximum: 100 },
+                cursor: { type: 'string', minLength: 1 }
+            },
+            required: ['agentId'],
+            additionalProperties: false
+        },
+        async execute(raw) {
+            const input = raw;
+            const [actor, session] = await Promise.all([
+                agent.getSession(context.sessionId),
+                agent.getSession(input.agentId)
+            ]);
+            if (actor.workspace !== session.workspace ||
+                (session.id !== actor.id &&
+                    session.source.parentSessionId !== actor.id &&
+                    actor.source.parentSessionId !== session.id))
+                throw new AgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Session is not available.');
+            const history = input.includeHistory
+                ? await agent.sessionHistory(session.id, {
+                    ...(input.limit === undefined ? {} : { limit: input.limit }),
+                    ...(input.cursor === undefined ? {} : { cursor: input.cursor })
+                })
+                : undefined;
+            const data = {
+                agentId: session.id,
+                title: session.title,
+                parentSessionId: session.source.parentSessionId ?? null,
+                modelId: session.modelId,
+                reasoningEffort: session.reasoningEffort,
+                lastActivityAt: session.lastActivityAt,
+                ...(history
+                    ? {
+                        history: {
+                            entries: history.entries.flatMap((entry) => {
+                                if (entry.kind === 'user')
+                                    return [{ kind: 'user', sequence: entry.sequence, text: entry.text }];
+                                if (entry.event.type === 'message.completed')
+                                    return [
+                                        {
+                                            kind: 'message',
+                                            sequence: entry.sequence,
+                                            text: entry.event.text,
+                                            phase: entry.event.phase,
+                                            executionId: entry.event.executionId
+                                        }
+                                    ];
+                                return [];
+                            }),
+                            ...(history.nextCursor ? { nextCursor: history.nextCursor } : {})
+                        }
+                    }
+                    : {})
+            };
+            return { data, content: JSON.stringify(data) };
+        }
+    });
+}

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

@@ -0,0 +1,3 @@
+import { type Agent } from '@myagentroam/agent';
+/** Project live direct children first, followed by the sixteen most recently active terminals. */
+export declare function childResources(agent: Agent, parentId: string, signal: AbortSignal, disposed: () => boolean, history?: Pick<Agent, 'sessionHistory'>): Promise<string[]>;

package/dist/cli/subagent/resources.js

@@ -0,0 +1,112 @@
+import { AgentError } from '@myagentroam/agent';
+import { historicalExecutionStatus } from './history.js';
+/** Project live direct children first, followed by the sixteen most recently active terminals. */
+export async function childResources(agent, parentId, signal, disposed, history = agent) {
+    signal.throwIfAborted();
+    const parent = await agent.getSession(parentId);
+    signal.throwIfAborted();
+    if (disposed())
+        return [];
+    const live = new Map();
+    const registration = agent.observeSessionExecutions((session) => {
+        if (session.source.parentSessionId === parentId && session.workspace === parent.workspace)
+            live.set(session.id, session);
+    });
+    try {
+        for (const session of registration.sessions)
+            if (session.source.parentSessionId === parentId && session.workspace === parent.workspace)
+                live.set(session.id, session);
+        const terminals = [];
+        let cursor;
+        let truncated = false;
+        do {
+            const page = await agent.listSessions({
+                parentSessionId: parentId,
+                limit: 100,
+                ...(cursor === undefined ? {} : { cursor })
+            });
+            signal.throwIfAborted();
+            if (disposed())
+                return [];
+            for (const [index, session] of page.sessions.entries()) {
+                if (session.workspace !== parent.workspace)
+                    continue;
+                const knownLive = live.get(session.id);
+                if (knownLive) {
+                    const snapshot = knownLive.subscribe(() => { });
+                    snapshot.unsubscribe();
+                    if (snapshot.activeExecutionId && !snapshot.terminalEvent)
+                        continue;
+                }
+                let state;
+                try {
+                    state = await historicalExecutionStatus(agent, session.id, signal, { history });
+                }
+                catch (error) {
+                    if (error instanceof AgentError && error.code === 'MAR_AGENT_SESSION_NOT_FOUND')
+                        continue;
+                    // A concurrent or foreign owner is not evidence of an interrupted Execution.
+                    // Leave its state to an explicit query instead of breaking the parent context.
+                    if (!(error instanceof AgentError) || error.code !== 'MAR_AGENT_SESSION_LOCKED')
+                        throw error;
+                    truncated = true;
+                    continue;
+                }
+                if (disposed())
+                    return [];
+                if (state.status === 'idle')
+                    continue;
+                terminals.push({
+                    agentId: session.id,
+                    status: state.status,
+                    description: session.source.type === 'subagent' ? session.source.description : session.title
+                });
+                if (terminals.length === 16) {
+                    truncated ||= index + 1 < page.sessions.length || !!page.nextCursor;
+                    break;
+                }
+            }
+            cursor = terminals.length === 16 ? undefined : page.nextCursor;
+        } while (cursor);
+        const active = [];
+        for (const session of live.values()) {
+            signal.throwIfAborted();
+            if (disposed())
+                return [];
+            const snapshot = session.subscribe(() => { });
+            snapshot.unsubscribe();
+            if (!snapshot.activeExecutionId || snapshot.terminalEvent)
+                continue;
+            let summary;
+            try {
+                summary = await agent.getSession(session.id);
+            }
+            catch (error) {
+                if (error instanceof AgentError && error.code === 'MAR_AGENT_SESSION_NOT_FOUND')
+                    continue;
+                throw error;
+            }
+            signal.throwIfAborted();
+            if (disposed())
+                return [];
+            active.push({
+                agentId: session.id,
+                status: 'running',
+                description: summary.source.type === 'subagent' ? summary.source.description : summary.title
+            });
+        }
+        const activeIds = new Set(active.map((child) => child.agentId));
+        const children = [...active, ...terminals.filter((child) => !activeIds.has(child.agentId))];
+        return children.length || truncated
+            ? [
+                `Child Sessions (use agent_list for details): ${JSON.stringify({
+                    children,
+                    truncated
+                }).replace(/[<>&]/g, (c) => (c === '<' ? '\\u003c' : c === '>' ? '\\u003e' : '\\u0026'))}`
+            ]
+            : [];
+    }
+    finally {
+        registration.unsubscribe();
+    }
+}

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

@@ -0,0 +1,77 @@
+import type { AgentEvent } from '@myagentroam/agent';
+/** A bounded projection of one execution's public events, not an execution owner. */
+export type ChildSnapshot = {
+    summary?: string;
+    summaryTruncated?: boolean;
+    turnId?: string;
+    changedFiles: string[];
+    changedFilesTruncated?: boolean;
+    latestMessage?: {
+        itemId: string;
+        turnId: string;
+        phase: 'commentary' | 'final_answer';
+        text: string;
+        timestamp: string;
+        truncated: boolean;
+    };
+    latestActivity?: {
+        kind: 'message';
+        timestamp: string;
+        phase: 'commentary' | 'final_answer';
+    } | {
+        kind: 'tool';
+        timestamp: string;
+        toolName: string;
+        status: 'started' | 'completed' | 'failed';
+    };
+    verification?: string[];
+    evidence?: Array<{
+        path: string;
+        startLine?: number;
+        endLine?: number;
+    }>;
+};
+export declare function boundedUtf8(value: string, maxBytes: number): {
+    value: string;
+    truncated: boolean;
+};
+export declare function projectChildEvent(snapshot: ChildSnapshot, event: AgentEvent, full?: boolean): void;
+export declare function publicChildSnapshot(snapshot: ChildSnapshot | undefined): {
+    changedFilesTruncated?: boolean;
+    changedFiles?: string[];
+    turnId?: string;
+    summaryTruncated?: boolean;
+    summary?: string;
+};
+/** Full native details are never included in model-facing projections. */
+export declare function nativeChildSnapshot(snapshot: ChildSnapshot | undefined): {
+    evidence?: {
+        path: string;
+        startLine?: number;
+        endLine?: number;
+    }[];
+    verification?: string[];
+    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;
+    };
+    changedFilesTruncated?: boolean;
+    changedFiles?: string[];
+    turnId?: string;
+    summaryTruncated?: boolean;
+    summary?: string;
+};