maka-agent 0.2.0-dev.24.20260907 → 0.2.0-dev.25.20260908

package/node_modules/@maka/eval/dist/experiment-directory.js

@@ -19,13 +19,14 @@
 import { randomUUID } from 'node:crypto';
 import { link, mkdir, open, readFile, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
+import { stableJsonStringify } from '@maka/core/canonical-json';
 import { FileAttemptStore } from './attempt-store.js';
 import { parseExperimentSpec } from './spec.js';
 export async function openExperimentDirectory(root, spec) {
     await mkdir(root, { recursive: true });
     const specPath = join(root, 'experiment.json');
     const temporaryPath = join(root, `.experiment-${randomUUID()}.tmp`);
-    const canonical = `${canonicalJson(spec)}\n`;
+    const canonical = `${stableJsonStringify(spec)}\n`;
     const temporary = await open(temporaryPath, 'wx', 0o600);
     try {
         await temporary.writeFile(canonical);
@@ -37,8 +38,9 @@ export async function openExperimentDirectory(root, spec) {
         if (error.code !== 'EEXIST')
             throw error;
         const existing = parseExperimentSpec(JSON.parse(await readFile(specPath, 'utf8')));
-        if (canonicalJson(existing) !== canonicalJson(spec))
+        if (stableJsonStringify(existing) !== stableJsonStringify(spec)) {
             throw new Error('experiment spec differs');
+        }
     }
     finally {
         await temporary.close().catch(() => undefined);
@@ -46,14 +48,3 @@ export async function openExperimentDirectory(root, spec) {
     }
     return { root, specPath, attempts: new FileAttemptStore(join(root, 'attempts')) };
 }
-function canonicalJson(value) {
-    if (Array.isArray(value))
-        return `[${value.map(canonicalJson).join(',')}]`;
-    if (value && typeof value === 'object') {
-        return `{${Object.entries(value)
-            .sort(([left], [right]) => left.localeCompare(right))
-            .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
-            .join(',')}}`;
-    }
-    return JSON.stringify(value);
-}

package/node_modules/@maka/runtime/dist/agent-run-inspect.js

@@ -61,19 +61,6 @@ export async function inspectAgentRunReadModel(runStore, runtimeEventStore, opti
         diagnostics,
     };
 }
-export async function inspectSessionRunReadModels(runStore, runtimeEventStore, sessionId, options = {}) {
-    const invocations = await runtimeEventStore.listSessionInvocations(sessionId);
-    const models = [];
-    for (const invocation of invocations) {
-        models.push(await inspectAgentRunReadModel(runStore, runtimeEventStore, {
-            sessionId,
-            runId: invocation.runId,
-            invocation,
-            ...(options.isFatalReadError ? { isFatalReadError: options.isFatalReadError } : {}),
-        }));
-    }
-    return models;
-}
 // A run is not its invocation: a continuation is a new run on the invocation it
 // resumes. This reader is addressed by run, so it looks the invocation up by the
 // id it was actually given.

package/node_modules/@maka/runtime/dist/agent-run.js

@@ -20,12 +20,13 @@ import { RUN_COMPOSITION_RECORDED_EVENT_TYPE } from '@maka/core/agent-run';
 import { isRuntimeHandoffPause } from '@maka/core/runtime-handoff';
 import { RunHandoffGate } from './run-handoff-gate.js';
 import { preserveHandoffOpening } from './runtime-resume.js';
-import { decodeRunCompositionSnapshot } from '@maka/core/run-composition';
+import { createRequestCompositionSnapshot, decodeRequestCompositionSnapshot, decodeRunCompositionSnapshot, } from '@maka/core/run-composition';
 import { DurableStoreWriteError, RunSealedError } from '@maka/core/runtime-event-store';
 import { buildInvocationOpenedEvent, buildSyntheticTerminalRuntimeEvent, isSessionInlineInvocation, } from '@maka/core/runtime-invocation';
 import { MODEL_PROJECTION_TRANSITION_EVENT_TYPE, } from '@maka/core/model-projection-transition';
 import { isTerminalRuntimeEvent } from '@maka/core/runtime-event';
 import { ToolLedgerCorruptionError, ToolLedgerRejectionError, } from '@maka/core/tool-ledger-scanner';
+import { stableHash } from './request-shape.js';
 import { Buffer } from 'node:buffer';
 import { isDeepStrictEqual } from 'node:util';
 import { redactSecrets } from '@maka/core/redaction';
@@ -79,6 +80,9 @@ export class AgentRun {
     runComposition;
     runCompositionWrite;
     runCompositionCommitted = false;
+    requestComposition;
+    requestCompositionIndex;
+    requestCompositionIndexRead;
     failureClass;
     failureMessage;
     lastTs = 0;
@@ -418,6 +422,72 @@ export class AgentRun {
             throw new Error('Cooperative handoff requires a durably committed Run Composition');
         }
     }
+    /**
+     * Durably binds one logical model step to its effective request surface.
+     * Unchanged steps reuse the latest snapshot; a changed surface appends a full
+     * replacement before provider dispatch, matching DSH request/header epochs.
+     */
+    async recordRequestComposition(input) {
+        if (!this.input.runStore) {
+            throw new Error('AgentRun store is not configured');
+        }
+        await this.loadRequestCompositionIndex();
+        const snapshot = createRequestCompositionSnapshot(input, this.requestCompositionIndex?.size ? 'change' : 'initial');
+        const surfaceHash = requestCompositionSurfaceHash(snapshot);
+        const existing = this.requestCompositionIndex?.get(surfaceHash);
+        if (existing) {
+            if (!sameRequestCompositionSurface(existing, snapshot)) {
+                throw new Error(`Request Composition surface hash collision: ${surfaceHash}`);
+            }
+            this.requestComposition = existing;
+            return existing.compositionId;
+        }
+        await this.enqueueRequiredRunStoreWrite('append request composition', async () => {
+            await this.input.runStore?.appendEvent(this.sessionId, this.runId, {
+                type: 'request_composition_resolved',
+                id: snapshot.compositionId,
+                runId: this.runId,
+                sessionId: this.sessionId,
+                turnId: this.turnId,
+                ts: this.input.now(),
+                data: { snapshot },
+            }, { durable: true });
+        });
+        this.requestComposition = snapshot;
+        this.requestCompositionIndex?.set(surfaceHash, snapshot);
+        return snapshot.compositionId;
+    }
+    async loadRequestCompositionIndex() {
+        if (this.requestCompositionIndex)
+            return;
+        if (this.requestCompositionIndexRead)
+            return await this.requestCompositionIndexRead;
+        const read = (async () => {
+            const index = new Map();
+            const events = await this.input.runStore?.readEvents(this.sessionId, this.runId);
+            for (const event of events ?? []) {
+                if (event.type !== 'request_composition_resolved')
+                    continue;
+                const snapshot = decodeRequestCompositionSnapshot(event.data?.snapshot);
+                const surfaceHash = requestCompositionSurfaceHash(snapshot);
+                const existing = index.get(surfaceHash);
+                if (existing && !sameRequestCompositionSurface(existing, snapshot)) {
+                    throw new Error(`Request Composition surface hash collision: ${surfaceHash}`);
+                }
+                index.set(surfaceHash, existing ?? snapshot);
+                this.requestComposition = snapshot;
+            }
+            this.requestCompositionIndex = index;
+        })();
+        this.requestCompositionIndexRead = read;
+        try {
+            await read;
+        }
+        finally {
+            if (this.requestCompositionIndexRead === read)
+                this.requestCompositionIndexRead = undefined;
+        }
+    }
     /**
      * Canonical accounting record for one physical provider request (#1679).
      *
@@ -1573,6 +1643,15 @@ function redactTraceString(value) {
 function errorMessage(error) {
     return redactTraceString(error instanceof Error ? error.message : String(error));
 }
+function sameRequestCompositionSurface(current, candidate) {
+    const { schemaVersion: _schemaVersion, compositionId: _compositionId, step: _step, reason: _reason, ...currentSurface } = current;
+    const { schemaVersion: _candidateSchemaVersion, compositionId: _candidateCompositionId, step: _candidateStep, reason: _candidateReason, ...candidateSurface } = candidate;
+    return isDeepStrictEqual(currentSurface, candidateSurface);
+}
+function requestCompositionSurfaceHash(snapshot) {
+    const { schemaVersion: _schemaVersion, compositionId: _compositionId, step: _step, reason: _reason, ...surface } = snapshot;
+    return stableHash(surface);
+}
 function isInteractionResumeAck(event) {
     return (event.type === 'sandbox_boundary_decision_ack' ||
         event.type === 'user_question_answer_ack' ||

package/node_modules/@maka/runtime/dist/ai-sdk-backend.js

@@ -71,7 +71,8 @@ export class AiSdkBackend {
     messageProjection;
     providerTelemetry;
     resolvedProviderOptions;
-    toolAvailabilityRuntime;
+    memoryTools;
+    applyPatchProfile;
     /** Bounds outstanding Code Mode cells on this backend. */
     codeCellAdmission = new AdmissionLimiter(MAX_ACTIVE_CODE_MODE_CELLS);
     /**
@@ -147,6 +148,7 @@ export class AiSdkBackend {
             beforeRunProviderDispatch: input.beforeRunProviderDispatch,
         });
         const applyPatchProfile = runtime.applyPatchProfile;
+        this.applyPatchProfile = applyPatchProfile;
         this.messageProjection = new AiSdkMessageProjection({
             modelAdapter: this.modelAdapter,
             applyPatchProfile,
@@ -168,7 +170,7 @@ export class AiSdkBackend {
         if (input.tools.some((tool) => tool.name === MEMORY_REMEMBER_TOOL_NAME || tool.name === MEMORY_EXTRACT_TOOL_NAME)) {
             throw new Error('Long-term Memory trigger tool names are reserved by Runtime');
         }
-        const memoryTools = input.memoryExtraction
+        this.memoryTools = input.memoryExtraction
             ? buildMemoryExtractionTriggerTools({
                 capabilities: input.memoryExtraction,
                 snapshot: (trigger, context) => this.memorySourceSnapshot(trigger, context),
@@ -182,11 +184,17 @@ export class AiSdkBackend {
                     : {}),
             })
             : [];
-        const modelTools = routeApplyPatchTools(input.tools, applyPatchProfile);
-        this.toolAvailabilityRuntime = new ToolAvailabilityRuntime(
-        // The archive decoder is a runtime protocol tool, not a host binding:
-        // this session's placeholders name it, so this session advertises it.
-        bindToolResultArchiveDecoder([...modelTools, ...memoryTools], input.toolResultArchive), input.toolAvailability, buildInvalidMakaTool());
+    }
+    snapshotToolAvailability() {
+        const hostTools = Object.freeze([...(this.input.resolveTools?.() ?? this.input.tools)]);
+        if (hostTools.some((tool) => tool.name === MEMORY_REMEMBER_TOOL_NAME || tool.name === MEMORY_EXTRACT_TOOL_NAME)) {
+            throw new Error('Long-term Memory trigger tool names are reserved by Runtime');
+        }
+        const modelTools = routeApplyPatchTools(hostTools, this.applyPatchProfile);
+        return {
+            hostTools,
+            runtime: new ToolAvailabilityRuntime(bindToolResultArchiveDecoder([...modelTools, ...this.memoryTools], this.input.toolResultArchive), this.input.toolAvailability, buildInvalidMakaTool()),
+        };
     }
     memorySourceSnapshot(trigger, context) {
         if (trigger !== 'remember')
@@ -255,7 +263,7 @@ export class AiSdkBackend {
             messageProjection: this.messageProjection,
             providerTelemetry: this.providerTelemetry,
             compaction: this.compaction,
-            toolAvailabilityRuntime: this.toolAvailabilityRuntime,
+            snapshotToolAvailability: () => this.snapshotToolAvailability(),
             codeCellAdmission: this.codeCellAdmission,
             resolvedProviderOptions: this.resolvedProviderOptions,
             session: this.turnSessionState,

package/node_modules/@maka/runtime/dist/ai-sdk-turn.js

@@ -37,7 +37,8 @@ import { hasActiveToolResultPruneDiagnosticPatch, hasBlockingReplayDiagnostics,
 import { RunTrace } from './run-trace.js';
 import { REQUEST_SANDBOX_BOUNDARY_TOOL_NAME, SANDBOX_BOUNDARY_DENIED_FOR_TURN, SANDBOX_BOUNDARY_FINALIZATION_PROMPT, } from './sandbox-boundary-tool.js';
 import { buildRuntimeEventModelReplayPlan, buildSteeringEnvelope, collectToolActivityTurnIds, compatibleProviderReasoningReplayEventIds, formatTextWithInlineRefs, steeringMessagesMissingFromBase, steeringModelMessage, } from './model-history.js';
-import { toolSchemaCharsForDiagnostics } from './request-shape.js';
+import { toolSchemaCharsForDiagnostics, requestCompositionToolSchemas, stableHash, toolCatalogHash, } from './request-shape.js';
+import { toolAvailabilityHash } from './tool-availability.js';
 import { renderSwarmModePrompt } from './swarm-mode.js';
 import { renderGraphModePrompt } from './graph-mode.js';
 import { modelUsesNativeOpenAiResponses } from './model-runtime.js';
@@ -800,8 +801,8 @@ export class AiSdkTurn {
             return;
         }
         // --- Build the provider-visible schema set. Tool execution stays in Runtime. ---
-        // One immutable runtime owns the bound search catalog and cached index.
-        // Mutable activation belongs to this turn.
+        // Each logical step freezes its own scoped catalog and search projection.
+        // Mutable activation belongs to this turn and follows contribution identity.
         const requiredOrchestrationTools = this.orchestration.mode === 'swarm'
             ? new Set([
                 'agent_list',
@@ -825,11 +826,22 @@ export class AiSdkTurn {
             throw new Error(`Invalid tool mode: ${String(requestedToolMode)}`);
         }
         const toolMode = requestedToolMode;
-        if (toolMode === 'code_mode' && this.deps.backend.tools.some((tool) => tool.name === 'exec')) {
-            throw new Error('Tool name "exec" is reserved for Code Mode.');
-        }
-        const plan = projectToolModePlan(this.deps.toolAvailabilityRuntime.prepare(this.activeTools, requiredOrchestrationTools), toolMode, codeModeExecTool);
-        const providerTools = plan.providerTools;
+        const snapshotStepTools = () => {
+            const snapshot = this.deps.snapshotToolAvailability();
+            if (toolMode === 'code_mode' && snapshot.hostTools.some((tool) => tool.name === 'exec')) {
+                throw new Error('Tool name "exec" is reserved for Code Mode.');
+            }
+            const plan = projectToolModePlan(snapshot.runtime.prepare(this.activeTools, requiredOrchestrationTools), toolMode, codeModeExecTool);
+            const modelTools = {};
+            for (const tool of plan.providerTools) {
+                modelTools[tool.name] = tool.providerTool
+                    ? { kind: 'provider', providerTool: tool.providerTool }
+                    : { kind: 'function', description: tool.description, inputSchema: tool.parameters };
+            }
+            toolRuntime.setGating(plan.gating);
+            return { plan, providerTools: plan.providerTools, modelTools };
+        };
+        let { plan, providerTools, modelTools } = snapshotStepTools();
         let activeToolResultPruneDiagnosticPatch = {};
         let midTurnCompactDiagnosticPatch;
         // Tool names the repair path matches a mis-cased call against — follows the
@@ -843,44 +855,8 @@ export class AiSdkTurn {
                 : [...names];
         };
         const currentRepairToolNames = () => boundaryAwareToolNames(plan.currentRepairToolNames());
-        if (plan.gating) {
-            toolRuntime.setGating(plan.gating);
-        }
-        const modelTools = {};
-        for (const t of providerTools) {
-            modelTools[t.name] = t.providerTool
-                ? { kind: 'provider', providerTool: t.providerTool }
-                : {
-                    kind: 'function',
-                    description: t.description,
-                    inputSchema: t.parameters,
-                };
-        }
-        // Resolve the stable Provider envelope before automatic Compaction freezes
-        // its source. The same value is reused by the primary request; Memory does
-        // not resolve or mutate Agent configuration after the checkpoint commits.
+        let resolvedSystemPrompt = { sourceRevisions: [] };
         let systemPrompt;
-        try {
-            systemPrompt = joinPromptFragments([
-                await this.resolveSystemPrompt(),
-                this.orchestration?.mode === 'swarm' ? renderSwarmModePrompt() : undefined,
-                this.orchestration?.mode === 'graph' ? renderGraphModePrompt() : undefined,
-            ]);
-        }
-        catch (err) {
-            trace.modelStreamFailed(this.deps.modelAdapter.classifyError(err), err);
-            queue.push(this.makeErrorEvent(turnId, err));
-            queue.push({
-                type: 'complete',
-                id: this.deps.newId(),
-                turnId,
-                ts: this.deps.now(),
-                stopReason: 'error',
-            });
-            queue.close();
-            yield* this.drain(queue);
-            return;
-        }
         // --- Build messages from RuntimeEvent history and its compatibility projection. ---
         const priorReplayResult = await this.buildPriorMessages(input);
         if (this.aborted) {
@@ -1083,7 +1059,8 @@ export class AiSdkTurn {
                 const onMidTurnDiagnosticPatch = (patch) => {
                     midTurnCompactDiagnosticPatch = mergeContextBudgetDiagnosticPatches(midTurnCompactDiagnosticPatch, patch);
                 };
-                const midTurnCapacityHook = this.deps.compaction.buildMidTurnCapacityCompactProjection(turnId, midTurnState, queue, providerTools, onMidTurnDiagnosticPatch, this, this.automaticMemoryCompactionSupported()
+                const capacityProviderTools = [...providerTools];
+                const midTurnCapacityHook = this.deps.compaction.buildMidTurnCapacityCompactProjection(turnId, midTurnState, queue, capacityProviderTools, onMidTurnDiagnosticPatch, this, this.automaticMemoryCompactionSupported()
                     ? () => this.automaticMemoryCompactionDecision()
                     : undefined, this.automaticMemoryCompactionSupported()
                     ? (dispatch) => this.dispatchAutomaticMemoryCompaction(dispatch)
@@ -1095,7 +1072,8 @@ export class AiSdkTurn {
                     pruneAppliedAtStep = runtimeSteps;
                     activeToolResultPruneDiagnosticPatch = mergeActiveToolResultPruneDiagnosticPatches(activeToolResultPruneDiagnosticPatch, patch);
                 });
-                const shapedProjection = composeRequestProjection(plan.projectActiveTools, midTurnCapacityHook, activeToolResultPruneHook);
+                const projectCurrentToolAvailability = (options) => plan.projectActiveTools?.(options);
+                const shapedProjection = composeRequestProjection(projectCurrentToolAvailability, midTurnCapacityHook, activeToolResultPruneHook);
                 // Hooks shape; nothing measures the final payload. Whether it fits is
                 // the provider's answer (#4559).
                 const requestProjection = shapedProjection;
@@ -1111,6 +1089,14 @@ export class AiSdkTurn {
                 let finishReason = 'stop';
                 let terminalProviderError;
                 agentLoop: for (;;) {
+                    ({ plan, providerTools, modelTools } = snapshotStepTools());
+                    resolvedSystemPrompt = await this.resolveSystemPrompt();
+                    systemPrompt = joinPromptFragments([
+                        resolvedSystemPrompt.text,
+                        this.orchestration.mode === 'swarm' ? renderSwarmModePrompt() : undefined,
+                        this.orchestration.mode === 'graph' ? renderGraphModePrompt() : undefined,
+                    ]);
+                    capacityProviderTools.splice(0, capacityProviderTools.length, ...providerTools);
                     await this.drainSteeringInto(input, queue);
                     if (this.deps.backend.loadTurnRuntimeEvents) {
                         requestMessages = await loadDurableTurnProjection();
@@ -1159,7 +1145,20 @@ export class AiSdkTurn {
                         : undefined;
                     const projectedMessages = shaped?.messages ?? requestMessages;
                     const activeToolsForRequest = resolveDispatch(shaped?.activeTools).activeTools;
-                    providerRequestTracker?.setStep(runtimeSteps);
+                    const requestCompositionId = this.runId && this.deps.backend.recordRequestComposition
+                        ? await this.deps.backend.recordRequestComposition(this.runId, {
+                            compositionId: this.deps.newId(),
+                            step: runtimeSteps,
+                            sourceRevisions: resolvedSystemPrompt.sourceRevisions,
+                            systemPromptHash: stableHash(requestSystemPrompt ?? ''),
+                            toolCatalogHash: toolCatalogHash(providerTools),
+                            toolAvailabilityHash: toolAvailabilityHash(this.deps.backend.toolAvailability),
+                            providerOptionsHash: stableHash(this.deps.resolvedProviderOptions),
+                            toolNames: activeToolsForRequest,
+                            toolSchemas: requestCompositionToolSchemas(providerTools, activeToolsForRequest),
+                        })
+                        : undefined;
+                    providerRequestTracker?.setStep(runtimeSteps, requestCompositionId);
                     let attemptMessages = projectedMessages;
                     let providerAttempt = 1;
                     let idleWatchdogRetryCount = 0;
@@ -2488,14 +2487,22 @@ export class AiSdkTurn {
     async resolveSystemPrompt() {
         const turnId = this.turnId;
         if (typeof this.deps.backend.systemPrompt === 'function') {
-            return await this.deps.backend.systemPrompt({
+            const resolved = await this.deps.backend.systemPrompt({
                 sessionId: this.deps.backend.sessionId,
                 turnId,
                 cwd: this.deps.backend.header.cwd,
                 emitSkillCatalogTrace: (message, data) => this.runTrace?.emit('skill', 'skill_catalog_built', message, data),
             });
+            return typeof resolved === 'string' || resolved === undefined
+                ? { ...(resolved === undefined ? {} : { text: resolved }), sourceRevisions: [] }
+                : resolved;
         }
-        return this.deps.backend.systemPrompt;
+        return {
+            ...(this.deps.backend.systemPrompt === undefined
+                ? {}
+                : { text: this.deps.backend.systemPrompt }),
+            sourceRevisions: [],
+        };
     }
     async *drain(queue) {
         try {

package/node_modules/@maka/runtime/dist/archive-read-tool.js

@@ -25,7 +25,7 @@ export function buildArchiveReadTool(reader) {
         .object({
         ref: z
             .string()
-            .describe('A maka://archive/... ref returned in an archived tool-result placeholder'),
+            .describe('The exact resourceRef returned in an archived tool-result placeholder (ledger or legacy archive)'),
         operation: z
             .enum(['inspect', 'read', 'query', 'search'])
             .default('inspect')
@@ -82,7 +82,7 @@ export function buildArchiveReadTool(reader) {
         name: ARCHIVE_READ_TOOL_NAME,
         displayName: 'Read archived result',
         activityKind: 'read',
-        description: 'Inspect, search, or page through a tool-result archive returned as a maka://archive/... ref. Start with inspect for a preview and the char/line coordinate space. Use operation "search" with a pattern to locate text, operation "read" with unit "line" for line-oriented terminal output, or operation "query" with an itemId for one agent_swarm item. Results are strictly bounded so reading an archive cannot immediately trigger another archive.',
+        description: 'Inspect, search, or page through a tool-result archive using its exact resourceRef. Both ledger and legacy archive references are supported. Start with inspect for a preview and the char/line coordinate space. Use operation "search" with a pattern to locate text, operation "read" with unit "line" for line-oriented terminal output, or operation "query" with an itemId for one agent_swarm item. Results are strictly bounded so reading an archive cannot immediately trigger another archive.',
         parameters: jsonSchema(async () => await providerSchema.jsonSchema, {
             validate: async (value) => {
                 const result = await parameters.safeParseAsync(value);

package/node_modules/@maka/runtime/dist/context-budget-helpers.js

@@ -46,22 +46,9 @@ export function stableJsonLength(value) {
 export function turnKey(event) {
     return event.turnId || '<unknown-turn>';
 }
-export function uniqueSorted(values) {
-    return [...new Set(values.filter((value) => value.length > 0))].sort();
-}
 export function sha256(text) {
     return createHash('sha256').update(text).digest('hex');
 }
-export function stableStringify(value) {
-    if (value === undefined)
-        return '';
-    try {
-        return JSON.stringify(value) ?? '';
-    }
-    catch {
-        return String(value);
-    }
-}
 export function finitePositive(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0
         ? Math.floor(value)
@@ -70,6 +57,3 @@ export function finitePositive(value) {
 export function utf8ByteLength(text) {
     return Buffer.byteLength(text, 'utf8');
 }
-export function optionalNonNegativeFiniteNumber(value) {
-    return value === undefined || (typeof value === 'number' && Number.isFinite(value) && value >= 0);
-}