fix(plugins): persist dynamic tool request epochs

Author: xxhZs

packages/core/src/__tests__/run-composition.test.ts

@@ -20,41 +20,59 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import {
+  createRequestCompositionSnapshot,
+  decodeRequestCompositionSnapshot,
   decodeRunCompositionSnapshot,
+  REQUEST_COMPOSITION_SCHEMA_VERSION,
   RUN_COMPOSITION_SCHEMA_VERSION,
 } from '../run-composition.js';
 
-test('Run Composition snapshots reject ambiguous toolsets and malformed hashes', () => {
+test('Run Composition snapshots contain only immutable bootstrap facts', () => {
   const valid = {
     schemaVersion: RUN_COMPOSITION_SCHEMA_VERSION,
     composerId: 'maka.interactive',
     composerRevision: '1',
-    sourceRevisions: [{ id: 'skill-catalog', revision: 'skills-0' }],
-    baseSystemPromptHash: hash('1'),
-    toolCatalogHash: hash('2'),
-    toolAvailabilityHash: hash('3'),
     baseProviderOptionsHash: hash('4'),
-    toolNames: ['Read'],
     contextWindow: null,
   };
 
   for (const candidate of [
-    { ...valid, baseSystemPromptHash: 'sha256:short' },
-    { ...valid, toolNames: ['Write', 'Read'] },
-    { ...valid, toolNames: ['Read', 'Read'] },
-    {
-      ...valid,
-      sourceRevisions: [
-        { id: 'skill-catalog', revision: 'skills-0' },
-        { id: 'runtime-policy', revision: '1' },
-      ],
-    },
-    { ...valid, sourceRevisions: [{ id: 'skill-catalog', revision: '' }] },
+    { ...valid, baseProviderOptionsHash: 'sha256:short' },
+    { ...valid, toolNames: ['Read'] },
   ]) {
     assert.throws(() => decodeRunCompositionSnapshot(candidate));
   }
 });
 
+test('Request Composition snapshots canonicalize complete model-visible tool surfaces', () => {
+  const snapshot = createRequestCompositionSnapshot(
+    {
+      compositionId: 'composition-1',
+      step: 1,
+      sourceRevisions: [{ id: 'skill-catalog', revision: 'skills-1' }],
+      systemPromptHash: hash('1'),
+      toolCatalogHash: hash('2'),
+      toolAvailabilityHash: hash('3'),
+      providerOptionsHash: hash('4'),
+      toolNames: ['Write', 'Read'],
+      toolSchemas: [
+        { name: 'Write', description: 'write', inputSchema: { type: 'object' } },
+        { name: 'Read', description: 'read', inputSchema: { type: 'object' } },
+      ],
+    },
+    'change',
+  );
+  assert.equal(snapshot.schemaVersion, REQUEST_COMPOSITION_SCHEMA_VERSION);
+  assert.deepEqual(snapshot.toolNames, ['Read', 'Write']);
+  assert.deepEqual(
+    snapshot.toolSchemas.map((schema) => schema.name),
+    ['Read', 'Write'],
+  );
+  assert.throws(() =>
+    decodeRequestCompositionSnapshot({ ...snapshot, toolNames: ['Read', 'Read'] }),
+  );
+});
+
 function hash(seed: string): `sha256:${string}` {
   return `sha256:${seed.repeat(64)}`;
 }

packages/core/src/agent-run.ts

@@ -183,7 +183,7 @@ export interface AgentRunHeader {
   agentSwarmAuthorization?: AgentSwarmAuthorizationSource;
   /** Effective tool protocol for this run. Optional on legacy runs. */
   toolMode?: ToolMode;
-  /** Immutable composer-owned prompt and tool-surface snapshot committed before provider dispatch. */
+  /** Immutable composer and provider bootstrap baseline committed before provider dispatch. */
   runComposition?: RunCompositionSnapshot;
   createdAt: number;
   updatedAt: number;
@@ -424,6 +424,7 @@ export const AGENT_RUN_EVENT_TYPES = [
   'sandbox_denial_detected',
   'provider_request_captured',
   'provider_request_attempt_recorded',
+  'request_composition_resolved',
   'model_call_attempt_recorded',
   'history_compact_checkpoint_recorded',
   'model_projection_transition_recorded',

packages/core/src/model-call-attempt.ts

@@ -155,6 +155,8 @@ export interface ModelCallAttempt {
 
   /** Runtime tool-loop step index within the turn. */
   step: number;
+  /** Logical request-composition snapshot used by this step and all of its retries. */
+  requestCompositionId?: string;
   /** Retry ordinal within the logical call; 0 is the first dispatch. */
   attempt: number;
 
@@ -224,6 +226,7 @@ const MODEL_CALL_ATTEMPT_SHAPE = defineObjectShape<ModelCallAttempt>()(
   [
     'connectionSlug',
     'historyCompactRoute',
+    'requestCompositionId',
     'contextWindow',
     'captureArtifactId',
     'requestObservation',
@@ -410,6 +413,7 @@ export function decodeModelCallAttempt(value: unknown): ModelCallAttempt {
     isNonEmptyString(value.runId) &&
     isNonEmptyString(value.turnId) &&
     isNonNegativeInteger(value.step) &&
+    isOptionalString(value.requestCompositionId) &&
     isNonNegativeInteger(value.attempt) &&
     (MODEL_CALL_KINDS as readonly unknown[]).includes(value.callKind) &&
     (value.historyCompactRoute === undefined ||

packages/core/src/run-composition.ts

@@ -19,7 +19,8 @@
 
 import { defineObjectShape, hasExactShape, isRecord } from './record-schema.js';
 
-export const RUN_COMPOSITION_SCHEMA_VERSION = 1 as const;
+export const RUN_COMPOSITION_SCHEMA_VERSION = 2 as const;
+export const REQUEST_COMPOSITION_SCHEMA_VERSION = 1 as const;
 
 export interface RunCompositionSourceRevision {
   readonly id: string;
@@ -30,30 +31,60 @@ export interface RunCompositionSnapshot {
   readonly schemaVersion: typeof RUN_COMPOSITION_SCHEMA_VERSION;
   readonly composerId: string;
   readonly composerRevision: string;
+  readonly baseProviderOptionsHash: `sha256:${string}`;
+  readonly contextWindow: number | null;
+}
+
+export interface RequestCompositionToolSchema {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: Record<string, unknown>;
+  readonly providerTool?: Record<string, unknown>;
+}
+
+/**
+ * One model-visible request surface, frozen at a logical model-step boundary.
+ * A later step appends a new snapshot only when one of these effective fields
+ * changes; physical retries of the same step keep referring to this snapshot.
+ */
+export interface RequestCompositionSnapshot {
+  readonly schemaVersion: typeof REQUEST_COMPOSITION_SCHEMA_VERSION;
+  readonly compositionId: string;
+  readonly step: number;
+  readonly reason: 'initial' | 'change';
   readonly sourceRevisions: readonly RunCompositionSourceRevision[];
-  readonly baseSystemPromptHash: `sha256:${string}`;
+  readonly systemPromptHash: `sha256:${string}`;
   readonly toolCatalogHash: `sha256:${string}`;
   readonly toolAvailabilityHash: `sha256:${string}`;
-  readonly baseProviderOptionsHash: `sha256:${string}`;
+  readonly providerOptionsHash: `sha256:${string}`;
   readonly toolNames: readonly string[];
-  readonly contextWindow: number | null;
+  readonly toolSchemas: readonly RequestCompositionToolSchema[];
 }
 
 const RUN_COMPOSITION_SHAPE = defineObjectShape<RunCompositionSnapshot>()(
+  ['schemaVersion', 'composerId', 'composerRevision', 'baseProviderOptionsHash', 'contextWindow'],
+  [],
+);
+const REQUEST_COMPOSITION_SHAPE = defineObjectShape<RequestCompositionSnapshot>()(
   [
     'schemaVersion',
-    'composerId',
-    'composerRevision',
+    'compositionId',
+    'step',
+    'reason',
     'sourceRevisions',
-    'baseSystemPromptHash',
+    'systemPromptHash',
     'toolCatalogHash',
     'toolAvailabilityHash',
-    'baseProviderOptionsHash',
+    'providerOptionsHash',
     'toolNames',
-    'contextWindow',
+    'toolSchemas',
   ],
   [],
 );
+const REQUEST_COMPOSITION_TOOL_SCHEMA_SHAPE = defineObjectShape<RequestCompositionToolSchema>()(
+  ['name', 'description', 'inputSchema'],
+  ['providerTool'],
+);
 
 const ID_PATTERN = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
 const HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
@@ -70,23 +101,12 @@ export function decodeRunCompositionSnapshot(value: unknown): RunCompositionSnap
     value.schemaVersion === RUN_COMPOSITION_SCHEMA_VERSION &&
     boundedMatchingString(value.composerId, ID_PATTERN, 128) &&
     boundedString(value.composerRevision, 128) &&
-    canonicalSourceRevisions(value.sourceRevisions) &&
-    hash(value.baseSystemPromptHash) &&
-    hash(value.toolCatalogHash) &&
-    hash(value.toolAvailabilityHash) &&
     hash(value.baseProviderOptionsHash) &&
-    canonicalToolNames(value.toolNames) &&
     (value.contextWindow === null ||
       (Number.isSafeInteger(value.contextWindow) && (value.contextWindow as number) > 0));
   if (!valid) throw new Error('Invalid Run Composition snapshot schema');
   return Object.freeze({
     ...(value as unknown as RunCompositionSnapshot),
-    sourceRevisions: Object.freeze(
-      (value.sourceRevisions as RunCompositionSourceRevision[]).map((source) =>
-        Object.freeze({ ...source }),
-      ),
-    ),
-    toolNames: Object.freeze([...(value.toolNames as string[])]),
   });
 }
 
@@ -98,10 +118,63 @@ export function createRunCompositionSnapshot(
   return decodeRunCompositionSnapshot({
     schemaVersion: RUN_COMPOSITION_SCHEMA_VERSION,
     ...input,
+  });
+}
+
+export type RequestCompositionSnapshotInput = Omit<
+  RequestCompositionSnapshot,
+  'schemaVersion' | 'reason'
+>;
+
+export function createRequestCompositionSnapshot(
+  input: RequestCompositionSnapshotInput,
+  reason: RequestCompositionSnapshot['reason'],
+): RequestCompositionSnapshot {
+  return decodeRequestCompositionSnapshot({
+    schemaVersion: REQUEST_COMPOSITION_SCHEMA_VERSION,
+    ...input,
+    reason,
     sourceRevisions: [...input.sourceRevisions].sort((left, right) =>
       compareExactString(left.id, right.id),
     ),
     toolNames: [...input.toolNames].sort(compareExactString),
+    toolSchemas: [...input.toolSchemas].sort((left, right) =>
+      compareExactString(left.name, right.name),
+    ),
+  });
+}
+
+export function decodeRequestCompositionSnapshot(value: unknown): RequestCompositionSnapshot {
+  if (!isRecord(value) || !hasExactShape(value, REQUEST_COMPOSITION_SHAPE)) {
+    throw new Error('Invalid Request Composition snapshot schema');
+  }
+  const valid =
+    value.schemaVersion === REQUEST_COMPOSITION_SCHEMA_VERSION &&
+    boundedString(value.compositionId, 128) &&
+    Number.isSafeInteger(value.step) &&
+    (value.step as number) >= 0 &&
+    (value.reason === 'initial' || value.reason === 'change') &&
+    canonicalSourceRevisions(value.sourceRevisions) &&
+    hash(value.systemPromptHash) &&
+    hash(value.toolCatalogHash) &&
+    hash(value.toolAvailabilityHash) &&
+    hash(value.providerOptionsHash) &&
+    canonicalToolNames(value.toolNames) &&
+    canonicalToolSchemas(value.toolSchemas);
+  if (!valid) throw new Error('Invalid Request Composition snapshot schema');
+  return Object.freeze({
+    ...(value as unknown as RequestCompositionSnapshot),
+    sourceRevisions: Object.freeze(
+      (value.sourceRevisions as RunCompositionSourceRevision[]).map((source) =>
+        Object.freeze({ ...source }),
+      ),
+    ),
+    toolNames: Object.freeze([...(value.toolNames as string[])]),
+    toolSchemas: Object.freeze(
+      (value.toolSchemas as RequestCompositionToolSchema[]).map((schema) =>
+        Object.freeze(structuredClone(schema)),
+      ),
+    ),
   });
 }
 
@@ -137,6 +210,26 @@ function canonicalToolNames(value: unknown): value is string[] {
   return true;
 }
 
+function canonicalToolSchemas(value: unknown): value is RequestCompositionToolSchema[] {
+  if (!Array.isArray(value) || value.length > 512) return false;
+  let previous: string | undefined;
+  for (const schema of value) {
+    if (
+      !isRecord(schema) ||
+      !hasExactShape(schema, REQUEST_COMPOSITION_TOOL_SCHEMA_SHAPE) ||
+      !boundedString(schema.name, 256) ||
+      !boundedString(schema.description, 16_384) ||
+      !isRecord(schema.inputSchema) ||
+      (schema.providerTool !== undefined && !isRecord(schema.providerTool)) ||
+      (previous !== undefined && previous >= schema.name)
+    ) {
+      return false;
+    }
+    previous = schema.name;
+  }
+  return true;
+}
+
 function hash(value: unknown): value is `sha256:${string}` {
   return typeof value === 'string' && HASH_PATTERN.test(value);
 }