@myagentroam/agent 0.10.7 → 0.10.9

package/dist/agent-core/model/usage-observer.d.ts

@@ -0,0 +1,31 @@
+import type { MarAgentModelConfiguration } from './configuration.js';
+import type { ModelEvent, ModelRequest } from './contracts.js';
+/** Safe request facts, independent of conversation events and provider payloads. */
+export interface ModelRequestUsage {
+    readonly recordId: string;
+    readonly requestId: string;
+    readonly revision: number;
+    readonly modelConfigurationId: string;
+    readonly modelName: string;
+    readonly provider: string;
+    readonly requestedModel: string;
+    readonly actualModel?: string;
+    readonly responseId?: string;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly state: 'running' | 'succeeded' | 'failed' | 'cancelled' | 'interrupted';
+    readonly inputTokens?: string;
+    readonly outputTokens?: string;
+    readonly cacheReadTokens?: string;
+    readonly cacheWriteTokens?: string;
+    readonly reasoningTokens?: string;
+}
+export interface ModelUsageObservation extends ModelRequestUsage {
+    readonly sessionId: string;
+    readonly executionId?: string;
+    readonly purpose: 'conversation' | 'compact' | 'title' | 'other';
+    readonly agentRole: 'root' | 'subagent';
+}
+export type ModelUsageObserver = (usage: ModelUsageObservation) => Promise<void> | void;
+/** Observe before retry prelude buffering so failed attempts retain reported usage. */
+export declare function observeModelRequestUsage(start: () => AsyncIterable<ModelEvent>, request: ModelRequest, configuration: MarAgentModelConfiguration, signal: AbortSignal, now?: () => number): AsyncIterable<ModelEvent>;

package/dist/agent-core/model/usage-observer.js

@@ -0,0 +1,82 @@
+import { randomUUID } from 'node:crypto';
+function count(value) {
+    return value !== undefined && Number.isSafeInteger(value) && value >= 0
+        ? String(value)
+        : undefined;
+}
+/** Observe before retry prelude buffering so failed attempts retain reported usage. */
+export async function* observeModelRequestUsage(start, request, configuration, signal, now = Date.now) {
+    if (!request.onModelUsage) {
+        yield* start();
+        return;
+    }
+    const base = {
+        recordId: randomUUID(),
+        requestId: request.usageRequestId ?? randomUUID(),
+        modelConfigurationId: configuration.id,
+        modelName: configuration.name,
+        provider: configuration.protocol,
+        requestedModel: configuration.modelId,
+        startedAt: now()
+    };
+    let usage = {};
+    let responseId;
+    let actualModel;
+    let state = 'interrupted';
+    const publish = async (value) => {
+        try {
+            await request.onModelUsage(value);
+        }
+        catch {
+            // Metering must not break the model stream or expose callback error details.
+            try {
+                request.onModelUsageFailure?.();
+            }
+            catch {
+                // Host diagnostics are also best effort.
+            }
+        }
+    };
+    await publish({ ...base, revision: 1, state: 'running' });
+    try {
+        for await (const event of start()) {
+            if (event.type === 'response.started') {
+                responseId = event.responseId;
+                actualModel = event.modelId;
+            }
+            else if (event.type === 'usage') {
+                for (const [key, value] of Object.entries(event.usage)) {
+                    if (value !== undefined)
+                        usage = { ...usage, [key]: value };
+                }
+            }
+            else if (event.type === 'completed') {
+                state = event.reason === 'cancelled' ? 'cancelled' : 'succeeded';
+            }
+            yield event;
+        }
+    }
+    catch (error) {
+        state = signal.aborted ? 'cancelled' : 'failed';
+        throw error;
+    }
+    finally {
+        await publish({
+            ...base,
+            revision: 2,
+            state: signal.aborted && state !== 'succeeded' ? 'cancelled' : state,
+            endedAt: now(),
+            ...(responseId === undefined ? {} : { responseId }),
+            ...(actualModel === undefined ? {} : { actualModel }),
+            ...optionalCount('inputTokens', usage.totalInputTokens),
+            ...optionalCount('outputTokens', usage.outputTokens),
+            ...optionalCount('cacheReadTokens', usage.cacheReadTokens),
+            ...optionalCount('cacheWriteTokens', usage.cacheWriteTokens),
+            ...optionalCount('reasoningTokens', usage.reasoningTokens)
+        });
+    }
+}
+function optionalCount(key, value) {
+    const normalized = count(value);
+    return normalized === undefined ? {} : { [key]: normalized };
+}

package/dist/agent-core/runtime/events.d.ts

@@ -75,6 +75,7 @@ export type MarAgentEvent = MarAgentEventBase & ({
     truncated?: boolean;
 } | {
     type: 'tool.completed';
+    resultExtensions?: readonly import('../tools/result-extensions.js').ToolResultExtension[];
     toolName: string;
     callId: string;
     parentCallId?: string;
@@ -84,6 +85,7 @@ export type MarAgentEvent = MarAgentEventBase & ({
     data?: CodeCellEventData | import('../tools/contracts.js').ExecResult | Omit<import('../tools/contracts.js').ExecResult, 'stdout' | 'stderr'> | import('../tools/contracts.js').ApplyPatchResult | import('../tools/contracts.js').ReadEventData | import('../tools/contracts.js').ViewImageResult | import('../subagent/contracts.js').SubagentTaskSnapshot;
 } | {
     type: 'tool.failed';
+    resultExtensions?: readonly import('../tools/result-extensions.js').ToolResultExtension[];
     data?: CodeCellEventData | import('../tools/contracts.js').ApplyPatchPartialResult;
     toolName: string;
     callId: string;

package/dist/agent-core/sdk/agent.js

@@ -84,7 +84,15 @@ export async function createMarAgentWithAdapter(options) {
             if (!snapshots)
                 throw new MarAgentError('MAR_AGENT_MODEL_SNAPSHOT_INVALID', 'Request snapshot is unavailable.');
             return snapshots.resolve(snapshot);
-        }),
+        }, options.host.modelUsage === undefined
+            ? undefined
+            : (usage, call) => options.host.modelUsage({
+                ...usage,
+                sessionId: call.sessionId,
+                ...(call.executionId === undefined ? {} : { executionId: call.executionId }),
+                purpose: 'other',
+                agentRole: sessionRuntimes.get(call.sessionId)?.sourceType === 'subagent' ? 'subagent' : 'root'
+            })),
         sessionBackend: (id) => sessionRuntimes.get(id)?.sessionBackend,
         agentsBackend: (id) => sessionRuntimes.get(id)?.agentsBackend,
         scheduleTool: (id) => (definition, run) => {

package/dist/agent-core/sdk/extension-models.d.ts

@@ -10,4 +10,4 @@ export declare function createExtensionModels(state: () => {
     modelId: string;
     request: ModelRequest;
     view: CoreModelRequest;
-}): CoreModelsBackend;
+}, observeUsage?: (usage: import('../model/usage-observer.js').ModelRequestUsage, call: CoreOperationContext) => Promise<void> | void): CoreModelsBackend;

package/dist/agent-core/sdk/extension-models.js

@@ -1,8 +1,9 @@
+import { randomUUID } from 'node:crypto';
 import { MarAgentError } from '../error.js';
 import { ExtensionRequestBridge } from '../extensions/model-request.js';
 import { transformCoreModelStream } from '../extensions/model-stream.js';
 import { modelTextInput } from '../model/text-blocks.js';
-export function createExtensionModels(state, createAdapter, resolveSnapshot) {
+export function createExtensionModels(state, createAdapter, resolveSnapshot, observeUsage) {
     return {
         list: () => {
             const { models, defaultModelId } = state();
@@ -67,6 +68,13 @@ export function createExtensionModels(state, createAdapter, resolveSnapshot) {
                 throw new MarAgentError('MAR_AGENT_MODEL_REQUEST_INVALID', 'Independent generation does not execute tools.');
             const request = {
                 ...lowered,
+                usageRequestId: randomUUID(),
+                ...(observeUsage === undefined
+                    ? {}
+                    : {
+                        onModelUsage: (usage) => observeUsage(usage, call),
+                        onModelUsageFailure: () => diagnoseCleanup?.('MAR_AGENT_MODEL_USAGE_FAILED')
+                    }),
                 ...(input.retainToolCatalog &&
                     snapshot.request.systemBlocks === undefined &&
                     snapshot.request.messages.every((message) => message.textBlocks === undefined)

package/dist/agent-core/sdk/session.js

@@ -667,7 +667,7 @@ export function createSessionOpener(services) {
                         code: 'MAR_AGENT_MODEL_STREAM_CLEANUP_FAILED',
                         sessionId
                     }));
-                    const transformModelRequest = async (candidate, bindings = captureTools(), modelId = selectedModel.id) => {
+                    const transformModelRequest = async (candidate, bindings = captureTools(), modelId = selectedModel.id, purpose = mode === 'compact' ? 'compact' : 'conversation') => {
                         let lowered = candidate;
                         if (coreExtensions.hooks.hasInterceptors('model.request')) {
                             const bridge = new ExtensionRequestBridge(modelId, candidate);
@@ -681,7 +681,25 @@ export function createSessionOpener(services) {
                             if (!binding || !isDeepStrictEqual(contract, capturedContract))
                                 throw new MarAgentError('MAR_AGENT_EXTENSION_MODEL_REQUEST_INVALID', 'Request tools do not match captured sources.');
                         }
-                        return lowered;
+                        return {
+                            ...lowered,
+                            usageRequestId: randomUUID(),
+                            ...(host.modelUsage === undefined
+                                ? {}
+                                : {
+                                    onModelUsage: (usage) => host.modelUsage({
+                                        ...usage,
+                                        sessionId,
+                                        executionId,
+                                        purpose,
+                                        agentRole: sessionSource.type === 'subagent' ? 'subagent' : 'root'
+                                    }),
+                                    onModelUsageFailure: () => coreExtensions.diagnose({
+                                        code: 'MAR_AGENT_MODEL_USAGE_FAILED',
+                                        sessionId
+                                    })
+                                })
+                        };
                     };
                     const toolEligible = (tool) => {
                         toolCallers(tool);
@@ -825,6 +843,7 @@ export function createSessionOpener(services) {
                             : subagents.captureParentFrame(executionId);
                         const toolContext = {
                             host: host,
+                            writeToolResultResource: (text) => store.writeToolResultResource(sessionId, text),
                             todo,
                             ...(subagents === undefined || mode === 'compact'
                                 ? {}
@@ -1038,6 +1057,15 @@ export function createSessionOpener(services) {
                                     ...(focus === undefined ? {} : { focus }),
                                     summaryTokenBudget,
                                     getPrompt: () => buildCompactionMessages('')[1].content,
+                                    reportModelUsage: host.modelUsage === undefined
+                                        ? undefined
+                                        : (usage) => host.modelUsage({
+                                            ...usage,
+                                            sessionId,
+                                            executionId,
+                                            purpose: 'compact',
+                                            agentRole: sessionSource.type === 'subagent' ? 'subagent' : 'root'
+                                        }),
                                     reportDiagnostic: async (value) => {
                                         if (!acceptsDiagnostics || ++diagnosticReports > 8)
                                             return;
@@ -1179,7 +1207,7 @@ export function createSessionOpener(services) {
                                             promptCacheKey: sessionId,
                                             reasoningEffort: requestReasoningEffort ?? reasoningEffort,
                                             onAttemptDiagnostic: recordModelAttempt('COMPACTION')
-                                        });
+                                        }, undefined, selectedModel.id, 'compact');
                                         for await (const event of streamModel((signal) => compaction.start({ start: (request) => selected.start(request, signal) }, request), compaction.signal)) {
                                             if (event.type === 'text.completed' &&
                                                 (event.phase ?? 'final_answer') === 'final_answer')

package/dist/agent-core/session/catalog.d.ts

@@ -71,6 +71,7 @@ export interface MarAgentSessionCatalog {
         readonly imageIndex: number;
     }): Promise<MarAgentSessionImage | undefined>;
     contextUsage(sessionId: string): Promise<MarAgentContextUsage | undefined>;
+    readToolResultResource(sessionId: string, input: import('./tool-result-resources.js').ToolResultResourceInput): Promise<import('./tool-result-resources.js').ToolResultResourcePage>;
     fork(sessionId: string, input: {
         readonly boundaryTurnId: string | null;
         readonly title: string;

package/dist/agent-core/session/catalog.js

@@ -79,6 +79,7 @@ export async function openMarAgentSessionCatalog(input) {
                     dataBase64: image.dataBase64
                 };
         },
+        readToolResultResource: (sessionId, input) => store.readToolResultResource(sessionId, input),
         contextUsage: async (sessionId) => {
             const page = await store.readPage(sessionId, { limit: 1000 });
             for (const record of page.records.toReversed()) {

package/dist/agent-core/session/jsonl-store.d.ts

@@ -1,3 +1,4 @@
+import { type ToolResultResourceInput } from './tool-result-resources.js';
 import { type CoreCheckpoint, type CoreJsonValue } from '../extensions/data.js';
 import type { ModelInputMetadata, ModelMessage, ModelUsage } from '../model/contracts.js';
 import type { EnvironmentContextState } from '../runtime/context/contracts.js';
@@ -104,6 +105,14 @@ export declare class JsonlSessionStore {
     writeContextualWorldState(sessionId: string, state: unknown): Promise<void>;
     /** Mark each image pending before publication; turn.user or lease recovery resolves ownership. */
     persistInputImages(sessionId: string, images: readonly SessionInputImage[]): Promise<SessionInputImageMetadata[]>;
+    writeToolResultResource(sessionId: string, text: string): Promise<{
+        status: "available";
+        resourceRef: string;
+        format: "unified-diff";
+        byteSize: number;
+        sha256: string;
+    }>;
+    readToolResultResource(sessionId: string, input: ToolResultResourceInput): Promise<import("./tool-result-resources.js").ToolResultResourcePage>;
     readInputImages(sessionId: string, value: unknown): Promise<RestoredSessionInputImage[]>;
     readInputImage(sessionId: string, input: {
         readonly sequence: number;

package/dist/agent-core/session/jsonl-store.js

@@ -4,6 +4,7 @@ import { copyFile, lstat, mkdir, open, readFile, readdir, rename, rm, stat, writ
 import { basename, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { MarAgentError } from '../error.js';
+import { completeToolResultResources, cleanupUnreferencedToolResources, bindToolResultResources, copyToolResultResources, readToolResultResource, toolResultResourceFiles, writeToolResultResource } from './tool-result-resources.js';
 import { acquireFileLock } from '../storage/file-lock.js';
 import { cloneCoreJson } from '../extensions/data.js';
 import { applyCodeModeStateMutations, parseCodeModeStateMutations, restoreCodeModeState } from '../tools/code-mode/state.js';
@@ -484,6 +485,22 @@ export class JsonlSessionStore {
             throw error;
         }
     }
+    async writeToolResultResource(sessionId, text) {
+        this.#assertOpen();
+        if (!this.#shared.index.sessions.some((item) => item.id === sessionId))
+            throw new MarAgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
+        return writeToolResultResource(this.sessionDirectory(sessionId), text);
+    }
+    async readToolResultResource(sessionId, input) {
+        this.#assertOpen();
+        await this.#refreshIndex();
+        if (!this.#shared.index.sessions.some((item) => item.id === sessionId))
+            throw new MarAgentError('MAR_AGENT_SESSION_NOT_FOUND', 'Session was not found.');
+        return readToolResultResource(this.sessionDirectory(sessionId), sessionId, input, async (sequence) => {
+            await this.#refreshIndex();
+            return (await this.readPage(sessionId, { beforeSequence: sequence + 1, limit: 1 })).records.find((record) => record.sequence === sequence);
+        });
+    }
     async readInputImages(sessionId, value) {
         this.#assertOpen();
         const references = inputImageReferences(value);
@@ -606,6 +623,7 @@ export class JsonlSessionStore {
                 this.#shared.segments.set(target.id, staged.segments.length);
                 for (const record of copied)
                     this.#applyRecordToResumeIndex(target, record);
+                await copyToolResultResources(this.sessionDirectory(sourceSessionId), this.sessionDirectory(target.id), copied);
                 await copyGeneratedImages(this.sessionDirectory(sourceSessionId), this.sessionDirectory(target.id), generatedImageFileNames(retained));
                 await copyInputImages(this.sessionDirectory(sourceSessionId), this.sessionDirectory(target.id), inputImageReferencesFromRecords(retained));
                 target.lastActivityAt = target.createdAt;
@@ -719,6 +737,7 @@ export class JsonlSessionStore {
                 contextualWorldStateStaged = await renameIfExists(contextualWorldStatePath, contextualWorldStateBackup);
                 generatedTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'generated_images', new Set(generatedImageFileNames(retained)), transactionId);
                 inputTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'input_images', new Set(inputImageReferencesFromRecords(retained).map((image) => image.fileName)), transactionId);
+                inputTrash.push(...(await stageUnreferencedImages(this.sessionDirectory(sessionId), 'tool_results', toolResultResourceFiles(retained), transactionId)));
                 for (const item of backups)
                     await rename(item.path, item.backup);
                 for (const item of staged.files) {
@@ -880,6 +899,7 @@ export class JsonlSessionStore {
                 contextualWorldStateStaged = await renameIfExists(contextualWorldStatePath, contextualWorldStateBackup);
                 generatedTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'generated_images', new Set(), transactionId);
                 inputTrash = await stageUnreferencedImages(this.sessionDirectory(sessionId), 'input_images', new Set(), transactionId);
+                inputTrash.push(...(await stageUnreferencedImages(this.sessionDirectory(sessionId), 'tool_results', new Set(), transactionId)));
                 for (const item of backups)
                     await rename(item.path, item.backup);
                 for (const item of staged.files) {
@@ -998,6 +1018,8 @@ export class JsonlSessionStore {
             type: input.type,
             payload: input.payload
         };
+        JSON.stringify(record); // Reject malformed payloads before binding resources.
+        await bindToolResultResources(this.sessionDirectory(sessionId), record, (sequence) => this.#readRecordAtSequence(meta, sequence), true);
         const serialized = `${JSON.stringify(record)}\n`;
         let segment = await this.#currentSegment(sessionId);
         let path = this.#segmentPath(sessionId, segment);
@@ -1028,6 +1050,7 @@ export class JsonlSessionStore {
             await handle.close();
         }
         meta.nextSequence++;
+        await completeToolResultResources(this.sessionDirectory(sessionId), record);
         if (record.type === 'turn.user' &&
             isObject(record.payload) &&
             Array.isArray(record.payload.images))
@@ -1798,6 +1821,7 @@ export class JsonlSessionStore {
         await repairSegmentTail(latestPath);
         const records = await readRecords(latestPath);
         await recoverPendingInputImages(this.sessionDirectory(sessionId), () => this.#readRecords(sessionId));
+        await cleanupUnreferencedToolResources(this.sessionDirectory(sessionId), () => this.#readRecords(sessionId));
         const last = records.at(-1);
         const match = /events-(\d{6})\.jsonl$/.exec(latestPath);
         const segment = Number(match?.[1] ?? 1);

package/dist/agent-core/session/tool-result-resources.d.ts

@@ -0,0 +1,26 @@
+import { type AvailableToolResultResource } from '../tools/result-extensions.js';
+import type { SessionRecord } from './jsonl-store.js';
+export interface ToolResultResourceInput {
+    resourceRef: string;
+    cursor?: string;
+    maxBytes?: number;
+}
+export interface ToolResultResourcePage {
+    type: 'file_changes';
+    version: 1;
+    format: 'unified-diff';
+    resourceRef: string;
+    byteSize: number;
+    sha256: string;
+    content: string;
+    nextCursor?: string;
+}
+export declare function writeToolResultResource(directory: string, text: string): Promise<AvailableToolResultResource>;
+export declare function recordToolResources(record: Pick<SessionRecord, 'type' | 'payload'>): AvailableToolResultResource[];
+/** A locator is only a hint: reads must verify its exact committed record identity. */
+export declare function bindToolResultResources(directory: string, record: SessionRecord, readRecord?: (sequence: number) => Promise<SessionRecord | undefined>, degrade?: boolean): Promise<void>;
+export declare function toolResultResourceFiles(records: readonly SessionRecord[]): Set<string>;
+export declare function copyToolResultResources(source: string, target: string, records: readonly SessionRecord[]): Promise<void>;
+export declare function completeToolResultResources(directory: string, record: SessionRecord): Promise<void>;
+export declare function cleanupUnreferencedToolResources(directory: string, readRecords: () => Promise<readonly SessionRecord[]>): Promise<void>;
+export declare function readToolResultResource(directory: string, sessionId: string, input: ToolResultResourceInput, readRecord: (sequence: number) => Promise<SessionRecord | undefined>): Promise<ToolResultResourcePage>;