@myagentroam/agent 0.10.7 → 0.10.8

package/dist/agent-core/tools/result-extensions.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import type { ToolExecutionResult } from './contracts.js';
+export declare const fileChangesExtensionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"file_changes">;
+    version: z.ZodLiteral<1>;
+    entries: z.ZodArray<z.ZodObject<{
+        changeId: z.ZodString;
+        path: z.ZodString;
+        change: z.ZodEnum<{
+            added: "added";
+            modified: "modified";
+            deleted: "deleted";
+        }>;
+        additions: z.ZodNullable<z.ZodNumber>;
+        deletions: z.ZodNullable<z.ZodNumber>;
+        diff: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            status: z.ZodLiteral<"available">;
+            resourceRef: z.ZodString;
+            format: z.ZodLiteral<"unified-diff">;
+            byteSize: z.ZodNumber;
+            sha256: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            status: z.ZodLiteral<"unavailable">;
+            reason: z.ZodEnum<{
+                "unsupported-content": "unsupported-content";
+                "limit-exceeded": "limit-exceeded";
+                "capture-failed": "capture-failed";
+                "storage-failed": "storage-failed";
+            }>;
+        }, z.core.$strip>], "status">;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ToolResultExtension = z.infer<typeof fileChangesExtensionSchema>;
+export type FileChangeEvidence = ToolResultExtension['entries'][number];
+export type AvailableToolResultResource = Extract<FileChangeEvidence['diff'], {
+    status: 'available';
+}>;
+export type ToolResultResourceWriter = (text: string) => Promise<AvailableToolResultResource>;
+export declare function parseToolResultExtensions(value: unknown): ToolResultExtension[] | undefined;
+export declare function failedToolResultExtensions(error: unknown): ToolResultExtension[] | undefined;
+/** Reserve a complete invocation's descriptors before any leaf commits, including wrapped calls. */
+export declare function reserveFileChangePaths(paths: readonly string[]): void;
+/** Only the SDK's real file commit calls this producer; arbitrary result fields are ignored. */
+export declare function captureFileChange(path: string, before?: Buffer, after?: Buffer): Promise<void>;
+/** Own a physical invocation, including all real leaf effects retained across wrappers. */
+export declare function withToolResultExtensions(write: ToolResultResourceWriter | undefined, run: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>;

package/dist/agent-core/tools/result-extensions.js

@@ -0,0 +1,134 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { MarAgentError } from '../error.js';
+import { z } from 'zod';
+import { createFileDiff, FileDiffLimitError } from './file-change-diff.js';
+const diffSchema = z.discriminatedUnion('status', [
+    z.object({
+        status: z.literal('available'),
+        resourceRef: z.string().uuid(),
+        format: z.literal('unified-diff'),
+        byteSize: z
+            .number()
+            .int()
+            .nonnegative()
+            .max(16 * 1024 * 1024),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u)
+    }),
+    z.object({
+        status: z.literal('unavailable'),
+        reason: z.enum(['unsupported-content', 'limit-exceeded', 'capture-failed', 'storage-failed'])
+    })
+]);
+export const fileChangesExtensionSchema = z.object({
+    type: z.literal('file_changes'),
+    version: z.literal(1),
+    entries: z
+        .array(z.object({
+        changeId: z.string().uuid(),
+        path: z.string().min(1).max(8192),
+        change: z.enum(['added', 'modified', 'deleted']),
+        additions: z.number().int().nonnegative().nullable(),
+        deletions: z.number().int().nonnegative().nullable(),
+        diff: diffSchema
+    }))
+        .max(200)
+});
+export function parseToolResultExtensions(value) {
+    if (!Array.isArray(value) || value.length > 16)
+        return undefined;
+    const extensions = [];
+    const ids = new Set();
+    for (const input of value) {
+        const parsed = fileChangesExtensionSchema.safeParse(input);
+        if (!parsed.success || extensions.some((entry) => entry.type === parsed.data.type))
+            continue;
+        if (new Set(parsed.data.entries.map((entry) => entry.changeId)).size !==
+            parsed.data.entries.length ||
+            parsed.data.entries.some((entry) => ids.has(entry.changeId)))
+            continue;
+        parsed.data.entries.forEach((entry) => ids.add(entry.changeId));
+        extensions.push(parsed.data);
+    }
+    return extensions.length && Buffer.byteLength(JSON.stringify(extensions)) <= 1024 * 1024
+        ? extensions
+        : undefined;
+}
+const capture = new AsyncLocalStorage();
+const failures = new WeakMap();
+export function failedToolResultExtensions(error) {
+    return error !== null && typeof error === 'object' ? failures.get(error) : undefined;
+}
+/** Reserve a complete invocation's descriptors before any leaf commits, including wrapped calls. */
+export function reserveFileChangePaths(paths) {
+    const context = capture.getStore();
+    const entries = (context?.reservedEntries ?? 0) + paths.length;
+    const bytes = (context?.descriptorBytes ?? 256) +
+        paths.reduce((sum, path) => sum + Buffer.byteLength(JSON.stringify(path)) + 512, 0);
+    if (entries > 200 || bytes > 1024 * 1024 || paths.some((path) => path.length > 8192))
+        throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Patch paths exceed the file evidence descriptor limit.');
+    if (context) {
+        context.reservedEntries = entries;
+        context.descriptorBytes = bytes;
+    }
+}
+/** Only the SDK's real file commit calls this producer; arbitrary result fields are ignored. */
+export async function captureFileChange(path, before, after) {
+    const context = capture.getStore();
+    if (!context)
+        return;
+    const entry = {
+        changeId: randomUUID(),
+        path,
+        change: before === undefined ? 'added' : after === undefined ? 'deleted' : 'modified',
+        additions: null,
+        deletions: null,
+        diff: { status: 'unavailable', reason: 'capture-failed' }
+    };
+    context.entries.push(entry);
+    try {
+        const diff = createFileDiff(path, before, after);
+        if (!diff) {
+            entry.diff = { status: 'unavailable', reason: 'unsupported-content' };
+            return;
+        }
+        entry.additions = diff.additions;
+        entry.deletions = diff.deletions;
+        context.bytes += Buffer.byteLength(diff.text);
+        if (context.bytes > 32 * 1024 * 1024)
+            entry.diff = { status: 'unavailable', reason: 'limit-exceeded' };
+        else if (context.write)
+            entry.diff = await context.write(diff.text);
+        else
+            entry.diff = { status: 'unavailable', reason: 'storage-failed' };
+    }
+    catch (error) {
+        entry.diff = {
+            status: 'unavailable',
+            reason: error instanceof FileDiffLimitError ? 'limit-exceeded' : 'storage-failed'
+        };
+    }
+}
+/** Own a physical invocation, including all real leaf effects retained across wrappers. */
+export async function withToolResultExtensions(write, run) {
+    const context = {
+        entries: [],
+        bytes: 0,
+        reservedEntries: 0,
+        descriptorBytes: 256,
+        ...(write ? { write } : {})
+    };
+    return capture.run(context, async () => {
+        const extensions = () => parseToolResultExtensions([{ type: 'file_changes', version: 1, entries: context.entries }]);
+        try {
+            const { resultExtensions: _ignored, ...result } = await run();
+            const resultExtensions = context.entries.length ? extensions() : undefined;
+            return resultExtensions ? { ...result, resultExtensions } : result;
+        }
+        catch (error) {
+            if (context.entries.length && error !== null && typeof error === 'object')
+                failures.set(error, extensions());
+            throw error;
+        }
+    });
+}

package/dist/agent-core/tools/runtime-context.d.ts

@@ -46,6 +46,7 @@ export interface ToolRuntimeContext {
     executionId: string;
     modelId?: string;
     signal: AbortSignal;
+    writeToolResultResource?: import('./result-extensions.js').ToolResultResourceWriter;
     codeMode?: import('./contracts.js').ToolExecutionContext['codeMode'];
     skills: ReadonlyMap<string, AgentSkill>;
     recentImages?: readonly ToolRuntimeImage[];

package/dist/agent-core/tools/runtime.js

@@ -3,10 +3,13 @@ import { randomUUID } from 'node:crypto';
 import { AGENT_TOOL_HANDLERS, BUILTIN_TOOL_DEFINITIONS } from './registry.js';
 import { normalizeToolInput } from './input.js';
 import { validateToolResult } from './output-projection.js';
+import { withToolResultExtensions } from './result-extensions.js';
 export async function executeRegisteredTool(name, arguments_, callId, context, caller = 'direct') {
-    if (context.invokeTool)
-        return validateToolResult(await context.invokeTool({ name, arguments: arguments_, callId }, context, caller));
-    return validateToolResult(await executeCapturedTool(AGENT_TOOL_HANDLERS.has(name) ? 'builtin' : name.startsWith('mcp__') ? 'mcp' : 'host', { name, arguments: arguments_, callId }, context));
+    return withToolResultExtensions(context.writeToolResultResource, async () => {
+        if (context.invokeTool)
+            return validateToolResult(await context.invokeTool({ name, arguments: arguments_, callId }, context, caller));
+        return validateToolResult(await executeCapturedTool(AGENT_TOOL_HANDLERS.has(name) ? 'builtin' : name.startsWith('mcp__') ? 'mcp' : 'host', { name, arguments: arguments_, callId }, context));
+    });
 }
 /** Invoke an already captured source; names never reselect a different backend. */
 export async function executeCapturedTool(kind, call, context) {

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { MarAgentError } from './agent-core/error.js';
 export { MAR_AGENT_HOST_API_VERSION, negotiateHost, type HostDescription, type MarAgentHostCapability } from './agent-core/host/contracts.js';
+export type { ToolResultExtension, FileChangeEvidence } from './agent-core/tools/result-extensions.js';
+export { parseToolResultExtensions } from './agent-core/tools/result-extensions.js';
+export type { ToolResultResourceInput, ToolResultResourcePage } from './agent-core/session/tool-result-resources.js';
 export type { HostExecutionExtensions, HostSessionResourceSnapshot, HostSkill, MarAgentHost } from './agent-core/host/contracts.js';
 export { LocalAgentHost, selectExecutionShell, type LocalAgentExecutionExtensions, type LocalAgentExecutionMcpBinding, type LocalAgentMcpBinding } from './agent-core/host/local-agent-host.js';
 export type { LocalProcessExecutor, LocalProcessSpawnRequest } from './agent-core/host/local-process-executor.js';
@@ -41,3 +44,4 @@ export type { ApplyPatchFileResult, ApplyPatchResult, ApplyPatchPartialResult, C
 export { MCP_DEFINITION_LIMITS, assertMcpToolCatalog, assertMcpToolDefinition } from './agent-core/tools/mcp/catalog.js';
 export type { WorkspacePathMount } from './agent-core/tools/shared/path-resolver.js';
 export type { CodeModeEngine, CodeModeEngineFactory, CreateCodeModeEngine } from './agent-core/tools/code-mode/engine.js';
+export type { ModelRequestUsage, ModelUsageObservation, ModelUsageObserver } from './agent-core/model/usage-observer.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { MarAgentError } from './agent-core/error.js';
 export { MAR_AGENT_HOST_API_VERSION, negotiateHost } from './agent-core/host/contracts.js';
+export { parseToolResultExtensions } from './agent-core/tools/result-extensions.js';
 export { LocalAgentHost, selectExecutionShell } from './agent-core/host/local-agent-host.js';
 export { SecretValue, marAgentReasoningEffortSchema, parseModelCatalog, resolveModelDefaultReasoningEffort } from './agent-core/model/configuration.js';
 export { testMarAgentModelTransport } from './agent-core/model/transport-test.js';

package/dist/shared/auto-title.d.ts

@@ -1,5 +1,7 @@
 import { type MarAgentModelConfiguration } from '../agent-core/model/configuration.js';
 export interface GenerateSessionTitleInput {
+    readonly onModelUsage?: (usage: import('../agent-core/model/usage-observer.js').ModelRequestUsage) => Promise<void> | void;
+    readonly onModelUsageFailure?: () => void;
     readonly models: readonly MarAgentModelConfiguration[];
     readonly currentModelId: string;
     readonly prompt: string;

package/dist/shared/auto-title.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { MarAgentError } from '../agent-core/error.js';
 import { AnthropicMessagesAdapter } from '../agent-core/model/anthropic-messages.js';
 import { resolveModelDefaultReasoningEffort } from '../agent-core/model/configuration.js';
@@ -38,6 +39,11 @@ export async function generateSessionTitle(input) {
     try {
         for await (const event of adapter.start({
             retryState: { attempts: 0, maxAttempts: 1 },
+            usageRequestId: randomUUID(),
+            ...(input.onModelUsage === undefined ? {} : { onModelUsage: input.onModelUsage }),
+            ...(input.onModelUsageFailure === undefined
+                ? {}
+                : { onModelUsageFailure: input.onModelUsageFailure }),
             system: defaultLanguage
                 ? `${sessionTitlePrompt}\n- If the user message does not establish a language, use ${JSON.stringify(defaultLanguage)} as the default language.`
                 : sessionTitlePrompt,

package/dist/shared/model-text.d.ts

@@ -2,6 +2,8 @@ import { type MarAgentModelConfiguration, type MarAgentReasoningEffort } from '.
 import type { ModelAttemptDiagnostic, ModelUsage } from '../agent-core/model/contracts.js';
 import type { CoreCompactMessage } from '../agent-core/extensions/compaction.js';
 export interface GenerateModelTextInput {
+    readonly onModelUsage?: (usage: import('../agent-core/model/usage-observer.js').ModelRequestUsage) => Promise<void> | void;
+    readonly onModelUsageFailure?: () => void;
     readonly model: MarAgentModelConfiguration;
     readonly system: string;
     readonly messages: readonly CoreCompactMessage[];

package/dist/shared/model-text.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { MarAgentError } from '../agent-core/error.js';
 import { AnthropicMessagesAdapter } from '../agent-core/model/anthropic-messages.js';
 import { OpenAiResponsesAdapter } from '../agent-core/model/openai-responses.js';
@@ -16,6 +17,11 @@ export async function generateModelText(input) {
     try {
         for await (const event of adapter.start({
             retryState: { attempts: 0, maxAttempts: 1 },
+            usageRequestId: randomUUID(),
+            ...(input.onModelUsage === undefined ? {} : { onModelUsage: input.onModelUsage }),
+            ...(input.onModelUsageFailure === undefined
+                ? {}
+                : { onModelUsageFailure: input.onModelUsageFailure }),
             system: input.system,
             messages: input.messages,
             tools: [],

package/package.json

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