@myagentroam/agent 0.11.59 → 0.11.61

package/dist/cli/subagent/control.js

@@ -49,6 +49,7 @@ export function registerControlTools(context, agent, observations, warmObservati
         name: 'agent_send',
         description: 'Send a message to a direct child or report to the direct parent.',
         allowedCallers: ['direct', 'programmatic'],
+        parallelSafety: 'serial',
         inputSchema: {
             type: 'object',
             properties: {
@@ -69,6 +70,7 @@ export function registerControlTools(context, agent, observations, warmObservati
         name: 'agent_stop',
         description: 'Stop a direct child execution and wait for its cleanup.',
         allowedCallers: ['direct', 'programmatic'],
+        parallelSafety: 'serial',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/cli/subagent/query.js

@@ -5,6 +5,7 @@ export function registerQueryTools(context, agent) {
         name: 'agent_list',
         description: 'List direct child Sessions or eligible model configurations.',
         allowedCallers: ['direct', 'programmatic'],
+        parallelSafety: 'safe',
         inputSchema: {
             type: 'object',
             properties: {
@@ -50,6 +51,7 @@ export function registerQueryTools(context, agent) {
         name: 'agent_view',
         description: 'View a direct child or parent Session and its public history.',
         allowedCallers: ['direct', 'programmatic'],
+        parallelSafety: 'safe',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/cli/subagent/wait.js

@@ -139,6 +139,7 @@ export function registerWait(context, agent, observations, history = agent) {
         name: 'agent_wait',
         description: 'Wait for direct child completion or a message.',
         allowedCallers: ['direct', 'programmatic'],
+        parallelSafety: 'safe',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/session/catalog.d.ts

@@ -2,6 +2,7 @@ import type { AgentEvent } from '../runtime/events.js';
 import type { SessionStore } from './store/contracts.js';
 import type { SessionListInput } from './types.js';
 import type { AgentSessionRollbackInput } from './rollback.js';
+import { type AgentSessionContextUsage } from './context-usage.js';
 import type { AgentSessionSummary, AgentSessionPage } from './summary.js';
 export type { AgentSessionSummary, AgentSessionPage } from './summary.js';
 import type { AgentSessionHistoryImageMetadata, AgentUserHistoryEntry } from './user-history.js';
@@ -23,12 +24,7 @@ export interface AgentSessionInputReceipt {
     readonly appliedExecutionId?: string;
     readonly appliedTurnId?: string;
 }
-export interface AgentSessionContextUsage {
-    inputTokens: number;
-    gcCount: number;
-    /** Measured input decreases since Compact; undefined when GC usage is not yet paired. */
-    gcReclaimedTokens?: number;
-}
+export type { AgentSessionContextUsage } from './context-usage.js';
 export interface AgentSessionDeleteResult {
     readonly deleted: boolean;
 }

package/dist/session/catalog.js

@@ -1,10 +1,12 @@
 import { AgentError } from '../error.js';
 import { publicHostedToolEvents } from '../runtime/event-projection.js';
 import { appliedInputRecord } from './deferred-input.js';
-import { compactSummaryFromCheckpoint } from './record-projection.js';
+import { isAgentEvent } from './record-projection.js';
+import { SessionContextUsageReader } from './context-usage.js';
 const MAX_INPUT_IMAGE_BYTES = 5 * 1024 * 1024;
 const INPUT_IMAGE_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
 export function createSessionCatalog(store, borrowed) {
+    const contextUsage = new SessionContextUsageReader(store);
     let closure;
     const assertOpen = () => {
         if (closure)
@@ -182,103 +184,7 @@ export function createSessionCatalog(store, borrowed) {
         },
         contextUsage: async (sessionId) => {
             assertOpen();
-            const page = await store.readPage(sessionId, { limit: 1000 });
-            let inputTokens;
-            for (const record of page.records.toReversed()) {
-                if (!isAgentEvent(record.payload))
-                    continue;
-                if (record.payload.type === 'context.compacted') {
-                    if (record.payload.retainedContext === true)
-                        return undefined;
-                    inputTokens = 0;
-                    break;
-                }
-                if (record.payload.type === 'usage.updated' && record.payload.purpose !== 'compact') {
-                    const tokens = record.payload.contextInputTokens ?? record.payload.inputTokens;
-                    if (typeof tokens === 'number' && Number.isSafeInteger(tokens) && tokens >= 0) {
-                        inputTokens = tokens;
-                        break;
-                    }
-                }
-            }
-            if (inputTokens === undefined)
-                return undefined;
-            const usage = { inputTokens };
-            let gcCount = 0;
-            let gcReclaimedTokens = 0;
-            let tokensKnown = true;
-            let nextInputTokens;
-            let nextModelId;
-            let nextExecutionId;
-            let requestInputTokens;
-            const statistics = () => ({
-                ...usage,
-                gcCount,
-                ...(tokensKnown ? { gcReclaimedTokens } : {})
-            });
-            let countPage = page;
-            for (;;) {
-                for (const record of countPage.records.toReversed()) {
-                    if (compactSummaryFromCheckpoint(record) !== undefined)
-                        return statistics();
-                    if (record.type === 'execution.header' &&
-                        record.executionId === nextExecutionId &&
-                        isRecord(record.payload))
-                        nextModelId =
-                            typeof record.payload.modelId === 'string' ? record.payload.modelId : undefined;
-                    if (isAgentEvent(record.payload) &&
-                        record.payload.type === 'usage.updated' &&
-                        record.payload.purpose !== 'compact') {
-                        const tokens = record.payload.contextInputTokens ?? record.payload.inputTokens;
-                        if (typeof tokens === 'number' && Number.isSafeInteger(tokens) && tokens >= 0) {
-                            requestInputTokens ??= tokens;
-                            nextInputTokens = tokens;
-                            nextModelId = undefined;
-                            nextExecutionId = record.executionId;
-                        }
-                    }
-                    if (record.type === 'model.attempt' &&
-                        isRecord(record.payload) &&
-                        record.payload.state === 'STARTED' &&
-                        record.payload.purpose === 'EXECUTION') {
-                        // Reverse traversal preserves the last usage update within each request.
-                        if (requestInputTokens !== undefined)
-                            nextInputTokens = requestInputTokens;
-                        requestInputTokens = undefined;
-                    }
-                    if (record.type === 'context.gc.completed' &&
-                        isRecord(record.payload) &&
-                        typeof record.payload.generation === 'number' &&
-                        Number.isSafeInteger(record.payload.generation) &&
-                        record.payload.generation > 0) {
-                        gcCount ||= record.payload.generation;
-                        const trigger = isRecord(record.payload.trigger) ? record.payload.trigger : undefined;
-                        const before = trigger?.contextInputTokens;
-                        if (typeof trigger?.usageSequence === 'number' &&
-                            trigger.usageSequence > 0 &&
-                            typeof before === 'number' &&
-                            Number.isSafeInteger(before) &&
-                            before >= 0 &&
-                            nextInputTokens !== undefined &&
-                            (nextModelId === undefined || nextModelId === trigger.modelId))
-                            gcReclaimedTokens += Math.max(0, before - nextInputTokens);
-                        else
-                            tokensKnown = false;
-                        nextInputTokens = undefined;
-                        nextModelId = undefined;
-                        nextExecutionId = undefined;
-                        requestInputTokens = undefined;
-                        if (record.payload.generation === 1)
-                            return statistics();
-                    }
-                }
-                if (countPage.previousBeforeSequence === undefined)
-                    return statistics();
-                countPage = await store.readPage(sessionId, {
-                    limit: 1000,
-                    beforeSequence: countPage.previousBeforeSequence
-                });
-            }
+            return contextUsage.read(sessionId);
         },
         fork: async (sessionId, options) => {
             assertOpen();
@@ -325,7 +231,11 @@ export function createSessionCatalog(store, borrowed) {
             }
         },
         close: () => {
-            closure ??= Promise.resolve().then(() => (borrowed ? undefined : store.close()));
+            closure ??= Promise.resolve().then(async () => {
+                await contextUsage.close();
+                if (!borrowed)
+                    await store.close();
+            });
             return closure;
         }
     };
@@ -367,13 +277,3 @@ export function imageMetadata(value) {
         ]
         : []);
 }
-function isAgentEvent(value) {
-    return (isRecord(value) &&
-        typeof value.type === 'string' &&
-        value.type !== 'reasoning.summary' &&
-        typeof value.eventId === 'string' &&
-        typeof value.sequence === 'number' &&
-        typeof value.timestamp === 'string' &&
-        typeof value.sessionId === 'string' &&
-        typeof value.executionId === 'string');
-}

package/dist/session/context-usage.d.ts

@@ -0,0 +1,19 @@
+import type { SessionStore } from './store/contracts.js';
+export interface AgentSessionContextUsage {
+    inputTokens: number;
+    gcCount: number;
+    /** Measured input decreases since Compact; undefined when GC usage is not yet paired. */
+    gcReclaimedTokens?: number;
+}
+/** Rebuild GC totals only when GC, its measured request, or retained history changes. */
+export declare class SessionContextUsageReader {
+    private readonly store;
+    private readonly cache;
+    private readonly reading;
+    constructor(store: Pick<SessionStore, 'readPage'>);
+    read(sessionId: string): Promise<AgentSessionContextUsage | undefined>;
+    close(): Promise<void>;
+    private remember;
+    private reusable;
+    private readOnce;
+}

package/dist/session/context-usage.js

@@ -0,0 +1,202 @@
+import { compactSummaryFromCheckpoint, isAgentEvent } from './record-projection.js';
+const MAX_CACHED_SESSIONS = 256;
+/** Rebuild GC totals only when GC, its measured request, or retained history changes. */
+export class SessionContextUsageReader {
+    store;
+    cache = new Map();
+    reading = new Map();
+    constructor(store) {
+        this.store = store;
+    }
+    async read(sessionId) {
+        let pending = this.reading.get(sessionId);
+        if (!pending) {
+            pending = this.readOnce(sessionId);
+            this.reading.set(sessionId, pending);
+        }
+        try {
+            const result = await pending;
+            return result === undefined ? undefined : { ...result };
+        }
+        finally {
+            if (this.reading.get(sessionId) === pending)
+                this.reading.delete(sessionId);
+        }
+    }
+    async close() {
+        await Promise.allSettled(this.reading.values());
+        this.cache.clear();
+    }
+    remember(sessionId, entry) {
+        this.cache.delete(sessionId);
+        this.cache.set(sessionId, entry);
+        if (this.cache.size > MAX_CACHED_SESSIONS)
+            this.cache.delete(this.cache.keys().next().value);
+    }
+    async reusable(sessionId, page, cached) {
+        for (;;) {
+            for (const record of page.records.toReversed()) {
+                if (record.sequence <= cached.cursor.sequence)
+                    return (record.sequence === cached.cursor.sequence && record.recordId === cached.cursor.recordId);
+                if (compactSummaryFromCheckpoint(record) !== undefined ||
+                    record.type === 'context.gc.completed')
+                    return false;
+                if (cached.refreshOnUsage &&
+                    ((isAgentEvent(record.payload) &&
+                        record.payload.type === 'usage.updated' &&
+                        record.payload.purpose !== 'compact') ||
+                        (record.type === 'model.attempt' &&
+                            isRecord(record.payload) &&
+                            record.payload.purpose === 'EXECUTION')))
+                    return false;
+            }
+            if (page.previousBeforeSequence === undefined)
+                return false;
+            page = await this.store.readPage(sessionId, {
+                limit: 1000,
+                beforeSequence: page.previousBeforeSequence
+            });
+        }
+    }
+    async readOnce(sessionId) {
+        const page = await this.store.readPage(sessionId, { limit: 1000 });
+        let inputTokens;
+        for (const record of page.records.toReversed()) {
+            if (!isAgentEvent(record.payload))
+                continue;
+            if (record.payload.type === 'context.compacted') {
+                if (record.payload.retainedContext === true)
+                    return undefined;
+                inputTokens = 0;
+                break;
+            }
+            if (record.payload.type === 'usage.updated' && record.payload.purpose !== 'compact') {
+                const tokens = record.payload.contextInputTokens ?? record.payload.inputTokens;
+                if (typeof tokens === 'number' && Number.isSafeInteger(tokens) && tokens >= 0) {
+                    inputTokens = tokens;
+                    break;
+                }
+            }
+        }
+        if (inputTokens === undefined)
+            return undefined;
+        const usage = { inputTokens };
+        const tail = page.records.at(-1);
+        const cursor = { sequence: tail.sequence, recordId: tail.recordId };
+        const cached = this.cache.get(sessionId);
+        if (cached && (await this.reusable(sessionId, page, cached))) {
+            this.remember(sessionId, { ...cached, cursor });
+            return { ...usage, ...cached.statistics };
+        }
+        let gcCount = 0;
+        let gcReclaimedTokens = 0;
+        let tokensKnown = true;
+        let nextInputTokens;
+        let nextModelId;
+        let nextExecutionId;
+        let requestInputTokens;
+        let requestEnded = false;
+        let newerRequestStarted = false;
+        let nextInputMutable = false;
+        let refreshOnUsage = false;
+        let permanentlyUnavailable = false;
+        const statistics = () => {
+            const statistics = { gcCount, ...(tokensKnown ? { gcReclaimedTokens } : {}) };
+            this.remember(sessionId, {
+                cursor,
+                statistics,
+                refreshOnUsage: refreshOnUsage && !permanentlyUnavailable
+            });
+            return { ...usage, ...statistics };
+        };
+        let countPage = page;
+        for (;;) {
+            for (const record of countPage.records.toReversed()) {
+                if (compactSummaryFromCheckpoint(record) !== undefined)
+                    return statistics();
+                if (record.type === 'execution.header' &&
+                    record.executionId === nextExecutionId &&
+                    isRecord(record.payload))
+                    nextModelId =
+                        typeof record.payload.modelId === 'string' ? record.payload.modelId : undefined;
+                if (isAgentEvent(record.payload) &&
+                    record.payload.type === 'usage.updated' &&
+                    record.payload.purpose !== 'compact') {
+                    const tokens = record.payload.contextInputTokens ?? record.payload.inputTokens;
+                    if (typeof tokens === 'number' && Number.isSafeInteger(tokens) && tokens >= 0) {
+                        requestInputTokens ??= tokens;
+                        nextInputTokens = tokens;
+                        nextModelId = undefined;
+                        nextExecutionId = record.executionId;
+                        nextInputMutable = false;
+                    }
+                }
+                if (record.type === 'model.attempt' &&
+                    isRecord(record.payload) &&
+                    record.payload.purpose === 'EXECUTION' &&
+                    (record.payload.state === 'SUCCEEDED' || record.payload.state === 'FAILED'))
+                    requestEnded = true;
+                if (record.type === 'model.attempt' &&
+                    isRecord(record.payload) &&
+                    record.payload.state === 'STARTED' &&
+                    record.payload.purpose === 'EXECUTION') {
+                    // Reverse traversal preserves the last usage update within each request.
+                    if (requestInputTokens !== undefined) {
+                        nextInputTokens = requestInputTokens;
+                        nextInputMutable = !requestEnded && !newerRequestStarted;
+                    }
+                    requestInputTokens = undefined;
+                    requestEnded = false;
+                    newerRequestStarted = true;
+                }
+                if (record.type === 'context.gc.completed' &&
+                    isRecord(record.payload) &&
+                    typeof record.payload.generation === 'number' &&
+                    Number.isSafeInteger(record.payload.generation) &&
+                    record.payload.generation > 0) {
+                    const latest = gcCount === 0;
+                    gcCount ||= record.payload.generation;
+                    const trigger = isRecord(record.payload.trigger) ? record.payload.trigger : undefined;
+                    const before = trigger?.contextInputTokens;
+                    const measuredBefore = typeof trigger?.usageSequence === 'number' &&
+                        trigger.usageSequence > 0 &&
+                        typeof before === 'number' &&
+                        Number.isSafeInteger(before) &&
+                        before >= 0;
+                    if (measuredBefore &&
+                        nextInputTokens !== undefined &&
+                        (nextModelId === undefined || nextModelId === trigger.modelId))
+                        gcReclaimedTokens += Math.max(0, before - nextInputTokens);
+                    else
+                        tokensKnown = false;
+                    if (!measuredBefore ||
+                        (!latest && nextInputTokens === undefined) ||
+                        (nextInputTokens !== undefined &&
+                            nextModelId !== undefined &&
+                            nextModelId !== trigger?.modelId))
+                        permanentlyUnavailable = true;
+                    if (latest)
+                        refreshOnUsage = nextInputTokens === undefined || nextInputMutable;
+                    nextInputTokens = undefined;
+                    nextModelId = undefined;
+                    nextExecutionId = undefined;
+                    requestInputTokens = undefined;
+                    requestEnded = false;
+                    newerRequestStarted = false;
+                    nextInputMutable = false;
+                    if (record.payload.generation === 1)
+                        return statistics();
+                }
+            }
+            if (countPage.previousBeforeSequence === undefined)
+                return statistics();
+            countPage = await this.store.readPage(sessionId, {
+                limit: 1000,
+                beforeSequence: countPage.previousBeforeSequence
+            });
+        }
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/session/record-projection.d.ts

@@ -1,5 +1,7 @@
 import type { ModelInputMetadata } from '../model/contracts.js';
+import type { AgentEvent } from '../runtime/events.js';
 import type { CompactHistoryMessage, SessionRecord } from './record-contract.js';
+export declare function isAgentEvent(value: unknown): value is AgentEvent;
 export declare function compactSummaryFromCheckpoint(record: SessionRecord | undefined): string | undefined;
 export declare function replacementHistoryFromCheckpoint(record: SessionRecord): CompactHistoryMessage[] | undefined;
 export declare function parseModelInputMetadata(value: unknown): ModelInputMetadata | undefined;

package/dist/session/record-projection.js

@@ -1,3 +1,15 @@
+export function isAgentEvent(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const event = value;
+    return (typeof event.type === 'string' &&
+        event.type !== 'reasoning.summary' &&
+        typeof event.eventId === 'string' &&
+        typeof event.sequence === 'number' &&
+        typeof event.timestamp === 'string' &&
+        typeof event.sessionId === 'string' &&
+        typeof event.executionId === 'string');
+}
 export function compactSummaryFromCheckpoint(record) {
     if (record?.type !== 'compact.completed')
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.11.59",
+  "version": "0.11.61",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",