diff --git a/README.md b/README.md index 2722b4106..34a49df3f 100644 --- a/README.md +++ b/README.md @@ -381,7 +381,7 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its | Browser observation | 8 | exact-origin CDP capture, bundle and source-map analysis, WebMCP discovery, session timelines, capture diff, and visual evidence | | Electron analysis | 4 | passive root-confined observation, bounded static application mapping, and evidence-backed static/runtime reconciliation | | Application workflows | 8 | bounded cross-layer traces, unique-only version matching, static export return-shape comparison, approved Linux-isolated extracted-module replay, managed-runtime characterization, and reconstruction coverage closure | -| Workspace and observation | 18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle | +| Workspace and observation | 19 | target lifecycle, Evidence v2 bundles, direct finite replay-machine evaluation, process/artifact/function comparison, evidence-linked residual-unknown lifecycle | The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness implements controlled behavioral capture. @@ -409,6 +409,7 @@ REA is already useful for native application, browser, and Electron investigatio - Export and import evidence bundles across sessions. - Persist automatic cross-version artifact runs as canonical, lock-protected workspaces with tamper-evident revision commitments. - Capture approved PTY scenarios as Process Capture v4 Evidence, including committed run manifests, raw and rendered terminal frames, scripted interactions, descendant settlement, named filesystem checkpoints, deterministic command shims, and loopback HTTP/WebSocket exchanges. +- Validate finite replay machines without launching a target through `run_replay_machine` or `rea run-replay-machine`; ordered events return typed decisions, actions, captured aliases, transition journals, final state, and exact limit use without echoing request or captured values. - Compare complete artifact inventories by stable path, content, metadata, and relations; incomplete evidence never implies equivalence. - Compare explicit function dossiers across text, calls, references, strings, and address-normalized CFG topology with per-facet unknowns. - Compare canonical Evidence bundles by exact membership, explicit observation pairs, and residual-unknown histories without turning omissions into behavioral absence. diff --git a/README_ar.md b/README_ar.md index fb301706b..fa76f7c52 100644 --- a/README_ar.md +++ b/README_ar.md @@ -169,7 +169,7 @@ rea uninstall --purge-data | مراقبة المتصفح | 8 | التقاط CDP محدود الأصل وتحليل الحزم وخرائط المصدر واكتشاف WebMCP والفروق والأدلة المرئية | | تحليل Electron | 4 | مراقبة سلبية ضمن جذور canonical، ورسم ثابت ومحدود للتطبيق، ومطابقة ثابتة/وقت تشغيل قائمة على Evidence | | سير عمل التطبيقات | 8 | تتبع محدود ومقارنة إصدارات فريدة ومقارنة ثابتة لأشكال قيم إرجاع الصادرات وإعادة تشغيل وحدات معزولة ومعتمدة على Linux وتوصيف وقت التشغيل المُدار وإغلاق تغطية إعادة البناء | -| جلسة الملف التنفيذي | 18 | فتح الأهداف وحزم الأدلة ومقارنة العمليات والقطع والدوال وسجل المجهولات المتبقية | +| جلسة الملف التنفيذي | 19 | فتح الأهداف وحزم الأدلة وتشغيل آلة إعادة محدودة ومقارنة العمليات والقطع والدوال وسجل المجهولات المتبقية | ## استخدام REA مع وكلاء برمجة آخرين diff --git a/README_ja.md b/README_ja.md index c27f0c743..fa56cd499 100644 --- a/README_ja.md +++ b/README_ja.md @@ -159,7 +159,7 @@ REA は手順 1〜5 のバイナリ解析を処理し、手順 6 はエージェ | ブラウザ観察 | 8 | origin 限定 CDP 取得、bundle/source map 解析、WebMCP 検出、セッション、capture diff、視覚証拠 | | Electron 解析 | 4 | canonical ファイルルート内の受動観察、有界な静的アプリマッピング、Evidence に基づく静的/実行時の照合 | | アプリケーション | 8 | 有界なクロスレイヤー追跡、一意限定のバージョン比較、静的なエクスポート戻り値形状比較、承認済み Linux 隔離 extracted-module replay、マネージドランタイム特性評価、再構築カバレッジ閉包 | -| バイナリセッション | 18 | `open_binary`、`binary_session`、証拠バンドル、プロセス/成果物/関数比較、残余未知レジストリ | +| バイナリセッション | 19 | `open_binary`、`binary_session`、証拠バンドル、有限リプレイ状態機械、プロセス/成果物/関数比較、残余未知レジストリ | ## 他のコーディングエージェントで使う diff --git a/README_ko.md b/README_ko.md index 275e077e1..73eeb5639 100644 --- a/README_ko.md +++ b/README_ko.md @@ -159,7 +159,7 @@ REA는 1–5단계의 바이너리 분석을 처리합니다. 6단계는 에이 | 브라우저 관찰 | 8 | origin 제한 CDP 캡처, bundle/source map 분석, WebMCP 검색, 세션 타임라인, capture diff 및 시각 증거 | | Electron 분석 | 4 | canonical 파일 루트 내 수동 관찰, 제한된 정적 앱 매핑, Evidence 기반 정적/런타임 조정 | | 애플리케이션 | 8 | 제한된 교차 계층 추적, 고유 일치 버전 비교, 정적 export 반환 형태 비교, 승인된 Linux 격리 extracted-module replay, 관리형 런타임 특성화, 재구성 커버리지 폐쇄 | -| 바이너리 세션 | 18 | `open_binary`, `binary_session`, 증거 번들, 프로세스·아티팩트·함수 비교, 잔여 미지수 레지스트리 | +| 바이너리 세션 | 19 | `open_binary`, `binary_session`, 증거 번들, 유한 replay 상태 머신, 프로세스·아티팩트·함수 비교, 잔여 미지수 레지스트리 | ## 다른 코딩 에이전트에서 사용하기 diff --git a/README_zh.md b/README_zh.md index f230b6fbf..46f5e595a 100644 --- a/README_zh.md +++ b/README_zh.md @@ -159,7 +159,7 @@ REA 负责第 1–5 步中的二进制分析。第 6 步由智能体使用其常 | 浏览器观察 | 8 | 精确来源 CDP 抓取、bundle/source map 分析、WebMCP 发现、会话时间线、capture diff 与视觉证据 | | Electron 分析 | 4 | 限定 canonical 文件根的被动观察、有界静态应用映射,以及基于 Evidence 的静态/运行时对账 | | 应用工作流 | 8 | 有界跨层追踪、唯一匹配跨版本图比较、静态导出返回形状比较、经批准的 Linux 隔离 extracted-module replay、托管运行时表征和重建覆盖闭合 | -| 二进制会话 | 18 | `open_binary`、`binary_session`、证据包、进程、制品与函数比较、残余未知项注册表 | +| 二进制会话 | 19 | `open_binary`、`binary_session`、证据包、有限重放状态机、进程、制品与函数比较、残余未知项注册表 | ## 与其他编程智能体一起使用 diff --git a/docs/process-capture.md b/docs/process-capture.md index 3ef764b29..3d7182951 100644 --- a/docs/process-capture.md +++ b/docs/process-capture.md @@ -129,6 +129,27 @@ Unmatched and exhausted calls are recorded. Shim observations are bounded by the scenario protocol-event limit; exceeding it marks the whole capture truncated while replay continues. +## Run a replay machine directly + +Use `rea run-replay-machine ./run.json` to validate a finite replay machine +against an ordered `events` array without launching a process or opening a +socket. MCP clients use `run_replay_machine` with the same `{ machine, events }` +input. The result retains one decision per offered event, a transition journal +with capture alias metadata, and one redacted action-table entry per used +transition. It never returns request bodies, request headers, or captured +values. It also reports the initial and final states, whether the final state is +terminal, configured limits, and committed usage. + +The direct boundary accepts at most 10,000 events, 4 MiB of declared action +JSON, 1,024 action text fields, and 1,024 possible sensitive-capture operations. +These caps bound both returned content and secret-redaction work. + +Refused events remain data rather than aborting the run. Outcomes distinguish +unmatched events, invalid states, failed guards, exhausted transitions, invalid +captures, unexpected reconnects, and exhausted limits. This direct runner +evaluates the same domain runtime used by loopback Process Capture, but performs +no network or target execution. + ## Compare captures Compare two saved Evidence records with: diff --git a/docs/product-catalog.json b/docs/product-catalog.json index 384767ad8..e98066928 100644 --- a/docs/product-catalog.json +++ b/docs/product-catalog.json @@ -11,7 +11,7 @@ "skill_version": "23" }, "tools": { - "total": 96, + "total": 97, "families": [ { "id": "direct", @@ -147,7 +147,7 @@ { "id": "session", "surface": "session", - "count": 18, + "count": 19, "tools": [ "binary_session", "build_call_path", @@ -164,6 +164,7 @@ "list_unknowns", "open_binary", "record_unknown", + "run_replay_machine", "update_unknown", "verify_reconstruction", "verify_unknown_resolution" @@ -502,7 +503,7 @@ } ], "cli": { - "primary_count": 56, + "primary_count": 57, "commands": [ "analyze", "analyze-javascript-application", @@ -552,6 +553,7 @@ "query-reconstruction-coverage", "reconcile-javascript-runtime", "run-controlled-replay", + "run-replay-machine", "search", "setup", "trace", @@ -570,17 +572,17 @@ }, "runtime_catalog": { "counts": { - "cli_commands": 56, - "mcp_tools": 96, + "cli_commands": 57, + "mcp_tools": 97, "mcp_prompts": 6, "mcp_resources": 2, "mcp_resource_templates": 9 }, "digests": { - "tools_sha256": "937d58e32d18f48970d26219d791838087ae71ac2893950db33bdf2d3bd51bc0", + "tools_sha256": "a41d2a1d614288008bf14486ad4c0a9e0abbb4f9c23790acf6493693afe0221e", "prompts_sha256": "f6da3ad38a1000c11364d1710f122ac4990551f04efd8c53ffb2e819b5cf5707", "resources_sha256": "94bebbab1a1b3cf47644c38d3de6469de568caa7bd7b842f529ead8ad320a912", - "combined_sha256": "92837c2e99c99a2dd087e4fb01d210cce9b5948051c33db1a404348ef90d8bf2" + "combined_sha256": "d9fea48861c281b71d9061a0d8a701bb96726b0ac2afefcbfeda79eff5e8aaaf" } } } diff --git a/docs/verification/managed-conformance-manifest.json b/docs/verification/managed-conformance-manifest.json index e34cc7df7..41f834bb5 100644 --- a/docs/verification/managed-conformance-manifest.json +++ b/docs/verification/managed-conformance-manifest.json @@ -1,6 +1,6 @@ { "schema_version": 1, - "manifest_id": "ecm_87baf2161a85728dd5f8bf3c9d55a4dff6e96b26ccf229363a6cda8ee78c7d24", + "manifest_id": "ecm_1e57c9db54aab5c777eb3efd823329546eef1099747daf49278bfe195dd9f0f6", "verifier": { "id": "rea-managed-conformance", "version": "1" @@ -14,7 +14,7 @@ "skill_digests": [ { "skill_id": "reverse-engineer-anything", - "sha256": "f522ec8b7f29bfdb2c1d8ed9ffe9d550b38474bff6a5cd47f0ddb08882450c11" + "sha256": "09805a16a1bd039540fcf317426f7bc009853978f51745b5f290a3d20679cb1e" } ], "claims": [ diff --git a/skills/reverse-engineer-anything/SKILL.md b/skills/reverse-engineer-anything/SKILL.md index e79907c32..ec2fcd2cf 100644 --- a/skills/reverse-engineer-anything/SKILL.md +++ b/skills/reverse-engineer-anything/SKILL.md @@ -3,8 +3,8 @@ name: reverse-engineer-anything description: Reverse engineer native, managed, Electron/JavaScript, packaged, and browser applications with REA. Use shipped-artifact or approved runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. metadata: version: "23" - tool_count: 96 - catalog_digest: "92837c2e99c99a2dd087e4fb01d210cce9b5948051c33db1a404348ef90d8bf2" + tool_count: 97 + catalog_digest: "d9fea48861c281b71d9061a0d8a701bb96726b0ac2afefcbfeda79eff5e8aaaf" --- # REA diff --git a/src/cliCommandNames.ts b/src/cliCommandNames.ts index 0ee71772c..d06809b15 100644 --- a/src/cliCommandNames.ts +++ b/src/cliCommandNames.ts @@ -51,6 +51,7 @@ export const CLI_COMMANDS = Object.freeze({ traceApplicationFeature: "trace-application-feature", compareApplicationVersions: "compare-application-versions", compareJavaScriptExportShapes: "compare-javascript-export-shapes", + runReplayMachine: "run-replay-machine", runControlledReplay: "run-controlled-replay", prepareNodeCharacterization: "prepare-node-characterization", executeNodeCharacterization: "execute-node-characterization", diff --git a/src/cliProcessCommands.ts b/src/cliProcessCommands.ts index 18cc9d269..7521db103 100644 --- a/src/cliProcessCommands.ts +++ b/src/cliProcessCommands.ts @@ -7,12 +7,20 @@ import { import { logCliCommand } from "./cliLogging.js"; import type { Logger } from "./logger.js"; import { CLI_COMMANDS } from "./cliCommandNames.js"; +import { parseCliJsonInput } from "./cliJsonInput.js"; +import { + replayMachineRunInputSchema, + runReplayMachine, +} from "./domain/replayMachineRun.js"; +import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js"; +import { projectInputIssues } from "./domain/inputIssueProjection.js"; /** Register Process Capture v4 one-shot commands through shared application services. */ export const registerProcessCommands = ( cli: ReturnType, logger: Logger, ): void => { + registerReplayMachineCommand(cli, logger); cli.command(CLI_COMMANDS.captureProcess, { description: "Capture one approved Process Capture v4 JSON scenario", args: z.object({ scenario: z.string().describe("Scenario JSON path") }), @@ -33,3 +41,39 @@ export const registerProcessCommands = ( ), }); }; + +const registerReplayMachineCommand = ( + cli: ReturnType, + logger: Logger, +): void => { + cli.command(CLI_COMMANDS.runReplayMachine, { + description: + "Run ordered protocol events directly through a finite replay machine", + args: z.object({ + inputJson: z.string().describe("Inline replay JSON or JSON file path"), + }), + run: ({ args }) => + logCliCommand(logger, CLI_COMMANDS.runReplayMachine, async () => { + const input = await parseCliJsonInput( + args.inputJson, + CLI_COMMANDS.runReplayMachine, + ); + if (!input.ok) return input.error; + const parsed = replayMachineRunInputSchema.safeParse(input.value); + return parsed.success + ? runReplayMachine(parsed.data) + : { + error: "Process command failed", + ...projectAnalysisError( + new AnalysisInputError( + CLI_COMMANDS.runReplayMachine, + { + cause: parsed.error, + }, + projectInputIssues(parsed.error.issues, input.value), + ), + ), + }; + }), + }); +}; diff --git a/src/contracts/replayMachineExample.ts b/src/contracts/replayMachineExample.ts new file mode 100644 index 000000000..315421ac0 --- /dev/null +++ b/src/contracts/replayMachineExample.ts @@ -0,0 +1,38 @@ +import { jsonObjectSchema } from "../domain/jsonValue.js"; + +/** Minimal login callback accepted by the direct replay-machine contract. */ +export const REPLAY_MACHINE_RUN_EXAMPLE = jsonObjectSchema.parse({ + machine: { + initial_state: "waiting", + states: [{ name: "waiting" }, { name: "complete", terminal: true }], + transitions: [ + { + id: "accept_callback", + from: "waiting", + to: "complete", + trigger: { protocol: "http", method: "POST", path: "/callback" }, + captures: [ + { + variable: "token", + value: { source: "request_json", path: ["token"] }, + sensitive: true, + }, + ], + actions: [{ type: "http_response", status: 204, body: "" }], + max_uses: 1, + }, + ], + max_transitions: 1, + }, + events: [ + { + protocol: "http", + connection: "not_applicable", + at_ms: 0, + method: "POST", + path: "/callback", + headers: {}, + body: '{"token":"opaque"}', + }, + ], +}); diff --git a/src/contracts/toolContractExamples.ts b/src/contracts/toolContractExamples.ts index de4fe5838..f2b388273 100644 --- a/src/contracts/toolContractExamples.ts +++ b/src/contracts/toolContractExamples.ts @@ -3,6 +3,7 @@ import { UNKNOWN_CONTRACT_EXAMPLES } from "./unknownContractExamples.js"; import { ARTIFACT_COMPARISON_EXAMPLE } from "./artifactComparisonExample.js"; import { FUNCTION_COMPARISON_EXAMPLE } from "./functionComparisonExample.js"; import { INVESTIGATION_EXAMPLES } from "./investigationExamples.js"; +import { REPLAY_MACHINE_RUN_EXAMPLE } from "./replayMachineExample.js"; /** Canonical examples for contracts whose required inputs have no defaults. */ export const TOOL_EXAMPLE_OVERRIDES: Readonly< @@ -39,6 +40,7 @@ export const TOOL_EXAMPLE_OVERRIDES: Readonly< executable: "/usr/bin/true", working_directory: "/tmp", }, + run_replay_machine: REPLAY_MACHINE_RUN_EXAMPLE, compare_process_captures: { left_evidence_id: `ev_${"0".repeat(64)}`, right_evidence_id: `ev_${"1".repeat(64)}`, diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.ts index 5994ec64e..fee395cef 100644 --- a/src/contracts/toolContracts.ts +++ b/src/contracts/toolContracts.ts @@ -12,6 +12,7 @@ import { changedBehaviorInputSchema } from "../domain/changedBehavior.js"; import { callPathInputSchema } from "../domain/callPath.js"; import { staticRuntimeCorrelationInputSchema } from "../domain/staticRuntimeCorrelation.js"; import { reconstructionVerificationInputSchema } from "../domain/reconstructionVerification.js"; +import { replayMachineRunInputSchema } from "../domain/replayMachineRun.js"; import { enhancedInputSchemas } from "./enhancedInputs.js"; import { @@ -497,6 +498,11 @@ export const SESSION_TOOL_CONTRACTS = [ "Revalidate the current residual-unknown head against live bundled evidence, exact authority/confidence/environment requirements, and revision integrity. Withdrawn and out-of-scope dispositions are not truth claims.", verifyUnknownResolutionInputSchema, ), + session( + "run_replay_machine", + "Evaluate ordered HTTP and WebSocket events directly against one validated finite replay machine without opening sockets or launching a target. Returns every decision, a capture-value-free transition journal, one redacted action table entry per used transition, captured aliases, final state, and exact configured and consumed limits.", + replayMachineRunInputSchema, + ), ] as const satisfies readonly ToolContract[]; /** Complete ordered public inventory used by registration and verification. */ diff --git a/src/contracts/toolEffects.ts b/src/contracts/toolEffects.ts index 79a295621..5aa624481 100644 --- a/src/contracts/toolEffects.ts +++ b/src/contracts/toolEffects.ts @@ -117,6 +117,7 @@ export const TOOL_EFFECTS: Readonly> = { trace_application_feature: evidence, compare_application_versions: evidence, compare_javascript_export_shapes: evidence, + run_replay_machine: effects(), run_controlled_replay: effects({ mutatesSession: true, writesFilesystem: true, diff --git a/src/contracts/toolOutputSchemaGroups.ts b/src/contracts/toolOutputSchemaGroups.ts index 6e70eac82..00c081e43 100644 --- a/src/contracts/toolOutputSchemaGroups.ts +++ b/src/contracts/toolOutputSchemaGroups.ts @@ -35,6 +35,7 @@ import { changedBehaviorResultSchema } from "../domain/changedBehavior.js"; import { callPathResultSchema } from "../domain/callPath.js"; import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCorrelation.js"; import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js"; +import { replayMachineRunOutputSchema } from "../domain/replayMachineRun.js"; import { analysisErrorProjectionSchema } from "./errorSchemas.js"; import { addressList, @@ -365,4 +366,5 @@ export const sessionOutputSchemas: Readonly> = { unknown: residualUnknownSchema, }), ), + run_replay_machine: lifecycleResultOf(replayMachineRunOutputSchema), }; diff --git a/src/domain/replayMachineRun.ts b/src/domain/replayMachineRun.ts new file mode 100644 index 000000000..0ce63f9db --- /dev/null +++ b/src/domain/replayMachineRun.ts @@ -0,0 +1,279 @@ +import { z } from "zod"; + +import { replayMachineSchema, type ReplayMachine } from "./replayMachine.js"; +import { + replayMachineEventSchema, + ReplayMachineRuntime, +} from "./replayMachineRuntime.js"; + +const refusalOutcomeSchema = z.enum([ + "unmatched", + "invalid_state", + "guard_failed", + "transition_exhausted", + "invalid_capture", + "unexpected_reconnect", + "limit_exhausted", +]); + +const MAX_DIRECT_REPLAY_EVENTS = 10_000; +const MAX_DIRECT_REPLAY_ACTION_BYTES = 4 * 1_024 * 1_024; +const MAX_DIRECT_REPLAY_ACTION_FIELDS = 1_024; +const MAX_DIRECT_REPLAY_SENSITIVE_CAPTURES = 1_024; + +const actionFieldCount = (machine: ReplayMachine): number => + machine.transitions.reduce( + (total, transition) => + total + + transition.actions.reduce( + (fields, action) => + fields + + (action.type === "http_response" + ? Object.keys(action.headers).length + 1 + : action.type === "websocket_send" + ? 1 + : 0), + 0, + ), + 0, + ); + +const maximumSensitiveCapturesPerEvent = (machine: ReplayMachine): number => + Math.max( + 0, + ...machine.transitions.map( + ({ captures }) => captures.filter(({ sensitive }) => sensitive).length, + ), + ); + +/** Complete declarative input for one direct replay-machine run. */ +export const replayMachineRunInputSchema = z + .strictObject({ + machine: replayMachineSchema, + events: z.array(replayMachineEventSchema).max(MAX_DIRECT_REPLAY_EVENTS), + }) + .superRefine(({ machine, events }, context) => { + const actionBytes = Buffer.byteLength( + JSON.stringify( + machine.transitions.map(({ id, actions }) => ({ id, actions })), + ), + ); + if (actionBytes > MAX_DIRECT_REPLAY_ACTION_BYTES) + context.addIssue({ + code: "custom", + path: ["machine", "transitions"], + message: "direct replay actions exceed the 4 MiB output boundary", + input: machine.transitions, + }); + if (actionFieldCount(machine) > MAX_DIRECT_REPLAY_ACTION_FIELDS) + context.addIssue({ + code: "custom", + path: ["machine", "transitions"], + message: "direct replay actions exceed the 1,024-field output boundary", + input: machine.transitions, + }); + if ( + maximumSensitiveCapturesPerEvent(machine) * events.length > + MAX_DIRECT_REPLAY_SENSITIVE_CAPTURES + ) + context.addIssue({ + code: "custom", + path: ["events"], + message: + "direct replay events exceed the 1,024 sensitive-capture operation boundary", + input: events, + }); + }); + +const replayMachineRunDecisionSchema = z.strictObject({ + event_sequence: z.number().int().nonnegative(), + outcome: z.union([z.literal("matched"), refusalOutcomeSchema]), + transition_sequence: z.number().int().nonnegative().nullable(), +}); + +const replayRunActionSchema = z.discriminatedUnion("type", [ + z.strictObject({ + type: z.literal("http_response"), + status: z.number().int().min(100).max(599), + headers: z.record( + z + .string() + .min(1) + .max(256) + .regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u), + z.string().max(8_192), + ), + body: z.string().max(1_000_000), + }), + z.strictObject({ + type: z.literal("websocket_send"), + data: z.string().max(1_000_000), + }), + z.strictObject({ type: z.literal("disconnect") }), + z.strictObject({ + type: z.literal("delay"), + duration_ms: z.number().int().nonnegative().max(30_000), + }), +]); + +const replayRunIdentifierSchema = z + .string() + .regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u); + +const replayMachineRunJournalEntrySchema = z.strictObject({ + sequence: z.number().int().nonnegative(), + at_ms: z.number().int().nonnegative(), + transition_id: replayRunIdentifierSchema, + state_before: replayRunIdentifierSchema, + state_after: replayRunIdentifierSchema, + captured_aliases: z + .array( + z.strictObject({ + name: replayRunIdentifierSchema, + sensitive: z.boolean(), + }), + ) + .max(32), +}); + +/** Capture-value-free result of directly evaluating a finite replay machine. */ +export const replayMachineRunOutputSchema = z.strictObject({ + schema_version: z.literal(1), + initial_state: replayRunIdentifierSchema, + final_state: replayRunIdentifierSchema, + terminal: z.boolean(), + decisions: z + .array(replayMachineRunDecisionSchema) + .max(MAX_DIRECT_REPLAY_EVENTS), + transition_journal: z + .array(replayMachineRunJournalEntrySchema) + .max(MAX_DIRECT_REPLAY_EVENTS), + transition_actions: z + .array( + z.strictObject({ + transition_id: replayRunIdentifierSchema, + actions: z.array(replayRunActionSchema).max(32), + }), + ) + .max(2_000), + limits: z.strictObject({ + configured: z.strictObject({ + transitions: z.number().int().positive(), + connections: z.number().int().positive(), + messages: z.number().int().positive(), + bytes: z.number().int().positive(), + duration_ms: z.number().int().positive(), + }), + usage: z.strictObject({ + offered_events: z.number().int().nonnegative(), + admitted_events: z.number().int().nonnegative(), + transitions: z.number().int().nonnegative(), + connections: z.number().int().nonnegative(), + messages: z.number().int().nonnegative(), + bytes: z.number().int().nonnegative(), + last_at_ms: z.number().int().nonnegative(), + }), + }), +}); + +export type ReplayMachineRunInput = z.infer; +export type ReplayMachineRunOutput = z.infer< + typeof replayMachineRunOutputSchema +>; + +type ReplayAction = ReplayMachine["transitions"][number]["actions"][number]; + +const redactAction = ( + runtime: ReplayMachineRuntime, + action: ReplayAction, +): ReplayAction => { + switch (action.type) { + case "http_response": + return { + ...action, + headers: Object.fromEntries( + Object.entries(action.headers).map(([name, value]) => [ + name, + runtime.redactField(value), + ]), + ), + body: runtime.redactField(action.body), + }; + case "websocket_send": + return { ...action, data: runtime.redactField(action.data) }; + case "delay": + case "disconnect": + return action; + } +}; + +/** Evaluate every supplied event in order without opening sockets or processes. */ +export const runReplayMachine = ( + input: ReplayMachineRunInput, +): ReplayMachineRunOutput => { + const runtime = new ReplayMachineRuntime(input.machine); + const decisions: ReplayMachineRunOutput["decisions"] = []; + const transitionJournal: ReplayMachineRunOutput["transition_journal"] = []; + const usedTransitionIds = new Set(); + + for (const [eventSequence, event] of input.events.entries()) { + const decision = runtime.dispatch(event); + decisions.push({ + event_sequence: eventSequence, + outcome: decision.outcome, + transition_sequence: decision.transition?.sequence ?? null, + }); + if (decision.outcome !== "matched") continue; + usedTransitionIds.add(decision.transition.transition_id); + const definition = input.machine.transitions.find( + ({ id }) => id === decision.transition.transition_id, + ); + if (definition === undefined) + throw new TypeError("Replay runtime selected an unknown transition"); + transitionJournal.push({ + sequence: decision.transition.sequence, + at_ms: decision.transition.at_ms, + transition_id: decision.transition.transition_id, + state_before: decision.transition.state_before, + state_after: decision.transition.state_after, + captured_aliases: definition.captures.map(({ variable, sensitive }) => ({ + name: variable, + sensitive, + })), + }); + } + + const usage = runtime.usage; + const transitionActions = input.machine.transitions + .filter(({ id }) => usedTransitionIds.has(id)) + .map(({ id, actions }) => ({ + transition_id: id, + actions: actions.map((action) => redactAction(runtime, action)), + })); + return replayMachineRunOutputSchema.parse({ + schema_version: 1, + initial_state: input.machine.initial_state, + final_state: runtime.state, + terminal: + input.machine.states.find(({ name }) => name === runtime.state) + ?.terminal ?? false, + decisions, + transition_journal: transitionJournal, + transition_actions: transitionActions, + limits: { + configured: { + transitions: input.machine.max_transitions, + ...input.machine.limits, + }, + usage: { + offered_events: input.events.length, + admitted_events: usage.events, + transitions: usage.transitions, + connections: usage.connections, + messages: usage.messages, + bytes: usage.bytes, + last_at_ms: usage.last_at_ms, + }, + }, + }); +}; diff --git a/src/domain/replayMachineRuntime.ts b/src/domain/replayMachineRuntime.ts index 7331ca8b1..84bf6ab53 100644 --- a/src/domain/replayMachineRuntime.ts +++ b/src/domain/replayMachineRuntime.ts @@ -1,4 +1,5 @@ import canonicalize from "canonicalize"; +import { z } from "zod"; import type { ReplayMachine } from "./replayMachine.js"; @@ -15,6 +16,61 @@ interface TransitionRecordOptions { }[]; } +/** One bounded inbound protocol event offered to a replay machine. */ +const replayEventHeadersSchema = z + .record( + z + .string() + .min(1) + .max(256) + .regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u), + z + .string() + .max(8_192) + .regex(/^[\t\x20-\x7e\x80-\xff]*$/u), + ) + .superRefine((headers, context) => { + const normalized = Object.keys(headers).map((name) => name.toLowerCase()); + if (new Set(normalized).size !== normalized.length) + context.addIssue({ + code: "custom", + message: "replay event headers must be unique ignoring case", + input: headers, + }); + }); + +const replayEventFields = { + at_ms: z.number().int().nonnegative().safe(), + path: z.string().startsWith("/").max(8_192), + headers: replayEventHeadersSchema, + body: z.string().max(1_000_000), +}; + +export const replayMachineEventSchema = z.discriminatedUnion("protocol", [ + z.strictObject({ + protocol: z.literal("http"), + connection: z.literal("not_applicable"), + method: z + .string() + .min(1) + .max(16) + .transform((method) => method.toUpperCase()), + ...replayEventFields, + }), + z.strictObject({ + protocol: z.literal("websocket_connect"), + connection: z.enum(["initial", "reconnect"]), + method: z.null(), + ...replayEventFields, + }), + z.strictObject({ + protocol: z.literal("websocket_message"), + connection: z.enum(["initial", "reconnect"]), + method: z.null(), + ...replayEventFields, + }), +]); + /** One bounded inbound protocol event offered to a replay machine. */ export interface ReplayMachineEvent { readonly protocol: "http" | "websocket_connect" | "websocket_message"; @@ -27,6 +83,16 @@ export interface ReplayMachineEvent { readonly body: string; } +/** Runtime counters committed only for events admitted by all machine limits. */ +export interface ReplayMachineUsage { + readonly events: number; + readonly transitions: number; + readonly connections: number; + readonly messages: number; + readonly bytes: number; + readonly last_at_ms: number; +} + /** Persistable transition journal entry containing aliases, never secrets. */ export interface ReplayTransitionRecord { readonly sequence: number; @@ -183,6 +249,7 @@ export class ReplayMachineRuntime { #messages = 0; #bytes = 0; #lastAtMs = 0; + #events = 0; constructor(readonly machine: ReplayMachine) { this.#state = machine.initial_state; @@ -199,6 +266,18 @@ export class ReplayMachineRuntime { return this.#timeline; } + /** Current committed use of the machine's declared limits. */ + get usage(): ReplayMachineUsage { + return { + events: this.#events, + transitions: this.#timeline.length, + connections: this.#connections, + messages: this.#messages, + bytes: this.#bytes, + last_at_ms: this.#lastAtMs, + }; + } + /** Replace captured secret values with stable aliases before persistence. */ redact(value: string): string { let redacted = value; @@ -216,6 +295,17 @@ export class ReplayMachineRuntime { return redacted; } + /** Replace a field containing captured secrets with one stable alias only. */ + redactField(value: string): string { + const alias = [...this.#sensitiveValues] + .filter(([, values]) => + [...values].some((secret) => value.includes(secret)), + ) + .map(([variable]) => variable) + .sort()[0]; + return alias === undefined ? value : ``; + } + /** Evaluate and, when admitted, commit one protocol event. */ dispatch(event: ReplayMachineEvent): ReplayMachineDecision { const normalizedEvent = { @@ -334,6 +424,7 @@ export class ReplayMachineRuntime { this.#messages = messages; this.#bytes = bytes; this.#lastAtMs = event.at_ms; + this.#events += 1; return true; } diff --git a/src/server/registerReplayMachineTool.ts b/src/server/registerReplayMachineTool.ts new file mode 100644 index 000000000..82e01caa9 --- /dev/null +++ b/src/server/registerReplayMachineTool.ts @@ -0,0 +1,42 @@ +import type { McpServer } from "@modelcontextprotocol/server"; + +import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js"; +import { + replayMachineRunInputSchema, + runReplayMachine, +} from "../domain/replayMachineRun.js"; +import { ok } from "../domain/result.js"; +import type { Logger } from "../logger.js"; +import { safeParseToolInput } from "./toolInputValidation.js"; +import { logToolExecution } from "./toolLogging.js"; +import { toCallToolResult } from "./toolResult.js"; +import { toolRegistrationOptions } from "./toolRegistrationOptions.js"; + +const contract = SESSION_TOOL_CONTRACTS.find( + ({ name }) => name === "run_replay_machine", +); +if (contract === undefined) + throw new TypeError("Missing run_replay_machine tool contract"); + +/** Register direct execution-free finite replay-machine evaluation. */ +export const registerReplayMachineTool = ( + server: McpServer, + logger: Logger, +): void => { + server.registerTool( + contract.name, + toolRegistrationOptions(contract), + async (input) => { + const parsed = safeParseToolInput( + replayMachineRunInputSchema, + input, + contract.name, + ); + if (!parsed.ok) return toCallToolResult(parsed, contract); + const result = await logToolExecution(logger, contract.name, () => + Promise.resolve(ok(runReplayMachine(parsed.value))), + ); + return toCallToolResult(result, contract); + }, + ); +}; diff --git a/src/server/registerSessionTools.ts b/src/server/registerSessionTools.ts index 6d1e300d2..2f81a483b 100644 --- a/src/server/registerSessionTools.ts +++ b/src/server/registerSessionTools.ts @@ -56,6 +56,7 @@ import { registerEvidenceTools, registerUnknownTools, } from "./registerSessionRecordTools.js"; +import { registerReplayMachineTool } from "./registerReplayMachineTool.js"; import { sessionAvailabilityPolicy, type SessionAvailability, @@ -395,6 +396,19 @@ export interface SessionToolOptions { readonly availabilityPolicy?: () => SessionAvailability; } +const registerRecordAndReplayTools = ( + server: McpServer, + session: BinarySessionPort, + logger: Logger, +): void => { + registerUnknownTools({ + server, + session, + contracts: SESSION_TOOL_CONTRACTS, + }); + registerReplayMachineTool(server, logger); +}; + export const registerSessionTools = ( server: McpServer, session: BinarySessionPort, @@ -489,9 +503,5 @@ export const registerSessionTools = ( ? {} : { permissionAuthority: options.permissionAuthority }), }); - registerUnknownTools({ - server, - session, - contracts: SESSION_TOOL_CONTRACTS, - }); + registerRecordAndReplayTools(server, session, logger); }; diff --git a/tests/applicationWorkflowCli.test.ts b/tests/applicationWorkflowCli.test.ts index 1f6e5178d..5d17fd0e5 100644 --- a/tests/applicationWorkflowCli.test.ts +++ b/tests/applicationWorkflowCli.test.ts @@ -19,6 +19,7 @@ import { } from "../src/domain/evidenceBundle.js"; import { analyzeJavaScriptApplication } from "../src/application/JavaScriptApplicationService.js"; import { permissionAuthorityForRoot } from "./fixtures/permissionAuthority.js"; +import { REPLAY_MACHINE_RUN_EXAMPLE } from "../src/contracts/replayMachineExample.js"; const execute = promisify(execFile); @@ -261,6 +262,65 @@ describe("application workflow CLI parity", () => { }, }); }, 20_000); + + it("runs a replay machine from inline and file-backed JSON", async () => { + const input = REPLAY_MACHINE_RUN_EXAMPLE; + const inline = await runCli([ + "run-replay-machine", + JSON.stringify(input), + "--json", + ]); + expect(inline).toMatchObject({ + schema_version: 1, + final_state: "complete", + decisions: [{ outcome: "matched" }], + transition_journal: [ + { captured_aliases: [{ name: "token", sensitive: true }] }, + ], + }); + expect(JSON.stringify(inline)).not.toContain("opaque"); + + const root = await createTestTempDirectory("rea-replay-machine-cli-"); + temporary.push(root); + const inputPath = join(root, "run.json"); + await writeFile(inputPath, JSON.stringify(input)); + const fileBacked = await runCli([ + "run-replay-machine", + inputPath, + "--json", + ]); + expect(fileBacked).toEqual(inline); + + const invalid = await runCli([ + "run-replay-machine", + JSON.stringify({ + machine: input.machine, + events: [ + { + protocol: "http", + connection: "not_applicable", + at_ms: 0, + method: null, + path: "/callback", + headers: {}, + body: "private-cli-body", + }, + ], + }), + "--json", + ]); + expect(invalid).toMatchObject({ + code: "invalid_request", + details: { + issues: expect.arrayContaining([ + expect.objectContaining({ + path: ["events", 0, "method"], + }), + ]), + }, + }); + expect(JSON.stringify(invalid)).not.toContain("private-cli-body"); + }, 20_000); }); const runCli = async ( diff --git a/tests/contractSnapshot.test.ts b/tests/contractSnapshot.test.ts index b1b4c7033..edf57f1d0 100644 --- a/tests/contractSnapshot.test.ts +++ b/tests/contractSnapshot.test.ts @@ -137,7 +137,7 @@ describe("tool contract surface", () => { expect(Object.keys(TOOL_EFFECTS).sort()).toEqual(names.sort()); }); - it("keeps exactly eighteen additive session contracts", () => { + it("keeps exactly nineteen additive session contracts", () => { expect( SESSION_TOOL_CONTRACTS.map(({ name, kind }) => ({ name, kind })), ).toEqual([ @@ -159,6 +159,7 @@ describe("tool contract surface", () => { { name: "record_unknown", kind: "session" }, { name: "update_unknown", kind: "session" }, { name: "verify_unknown_resolution", kind: "session" }, + { name: "run_replay_machine", kind: "session" }, ]); expect( SESSION_TOOL_CONTRACTS.find( diff --git a/tests/replayMachineMcp.test.ts b/tests/replayMachineMcp.test.ts new file mode 100644 index 000000000..caac29ef3 --- /dev/null +++ b/tests/replayMachineMcp.test.ts @@ -0,0 +1,73 @@ +import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; +import { describe, expect, it } from "vitest"; + +import { BinarySession } from "../src/application/BinarySession.js"; +import { REPLAY_MACHINE_RUN_EXAMPLE } from "../src/contracts/replayMachineExample.js"; +import { createServer } from "../src/server/createServer.js"; +import { observed } from "./fixtures/analysisExecution.js"; + +describe("direct replay machine MCP parity", () => { + it("returns typed journal output and safe validation failures", async () => { + const session = new BinarySession(() => ({ + execute: () => Promise.resolve(observed(null)), + close: () => Promise.resolve(), + })); + const server = createServer(session, session); + const client = new Client({ name: "replay-machine-test", version: "1" }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + const example = REPLAY_MACHINE_RUN_EXAMPLE; + try { + await server.connect(serverTransport); + await client.connect(clientTransport); + const result = await client.callTool({ + name: "run_replay_machine", + arguments: example, + }); + expect(result).toMatchObject({ + structuredContent: { + result: { + schema_version: 1, + final_state: "complete", + terminal: true, + decisions: [{ outcome: "matched", transition_sequence: 0 }], + transition_journal: [ + { + transition_id: "accept_callback", + captured_aliases: [{ name: "token", sensitive: true }], + }, + ], + }, + }, + }); + expect(JSON.stringify(result)).not.toContain("opaque"); + + const invalid = await client.callTool({ + name: "run_replay_machine", + arguments: { + ...example, + events: [ + { + protocol: "http", + connection: "not_applicable", + at_ms: 0, + method: null, + path: "/callback", + headers: {}, + body: "private-request-body", + }, + ], + }, + }); + expect(invalid).toMatchObject({ + isError: true, + structuredContent: { error: { code: "invalid_request" } }, + }); + expect(JSON.stringify(invalid)).not.toContain("private-request-body"); + } finally { + await client.close(); + await server.close(); + await session.close(); + } + }); +}); diff --git a/tests/replayMachineRun.test.ts b/tests/replayMachineRun.test.ts new file mode 100644 index 000000000..048c47f63 --- /dev/null +++ b/tests/replayMachineRun.test.ts @@ -0,0 +1,457 @@ +import { describe, expect, it } from "vitest"; + +import { + replayMachineRunInputSchema, + runReplayMachine, +} from "../src/domain/replayMachineRun.js"; + +const loginRun = () => + replayMachineRunInputSchema.parse({ + machine: { + initial_state: "login", + states: [ + { name: "login" }, + { name: "api" }, + { name: "complete", terminal: true }, + ], + transitions: [ + { + id: "capture_token", + from: "login", + to: "api", + priority: 10, + trigger: { protocol: "http", method: "POST", path: "/login" }, + captures: [ + { + variable: "token", + value: { source: "request_json", path: ["token"] }, + sensitive: true, + }, + ], + actions: [ + { + type: "http_response", + status: 204, + headers: { "x-token": "target-secret" }, + body: "target-secret", + }, + ], + max_uses: 1, + }, + { + id: "authorize", + from: "api", + to: "complete", + priority: 10, + trigger: { protocol: "http", method: "GET", path: "/api" }, + guards: [ + { + variable: "token", + value: { source: "request_header", name: "authorization" }, + }, + ], + actions: [ + { + type: "http_response", + status: 200, + headers: {}, + body: "done", + }, + ], + max_uses: 1, + }, + ], + max_transitions: 2, + limits: { + connections: 2, + messages: 4, + bytes: 1_000, + duration_ms: 100, + }, + }, + events: [ + { + protocol: "http", + connection: "not_applicable", + at_ms: 1, + method: "post", + path: "/login", + headers: {}, + body: '{"token":"target-secret"}', + }, + { + protocol: "http", + connection: "not_applicable", + at_ms: 2, + method: "GET", + path: "/api", + headers: { Authorization: "target-secret" }, + body: "", + }, + ], + }); + +const parseMachineRun = (machine: unknown, events: unknown[]) => + replayMachineRunInputSchema.parse({ machine, events }); + +const httpEvent = (path: string, atMs = 0) => ({ + protocol: "http" as const, + connection: "not_applicable" as const, + at_ms: atMs, + method: "GET", + path, + headers: {}, + body: "", +}); + +describe("direct replay machine runner", () => { + it("returns actions, aliases, terminal state, and exact limit use", () => { + const result = runReplayMachine(loginRun()); + + expect(result).toMatchObject({ + schema_version: 1, + initial_state: "login", + final_state: "complete", + terminal: true, + decisions: [ + { event_sequence: 0, outcome: "matched", transition_sequence: 0 }, + { event_sequence: 1, outcome: "matched", transition_sequence: 1 }, + ], + transition_journal: [ + { + transition_id: "capture_token", + captured_aliases: [{ name: "token", sensitive: true }], + }, + { + transition_id: "authorize", + captured_aliases: [], + }, + ], + transition_actions: [ + { + transition_id: "capture_token", + actions: [ + { + type: "http_response", + status: 204, + headers: { "x-token": "" }, + body: "", + }, + ], + }, + { + transition_id: "authorize", + actions: [ + { + type: "http_response", + status: 200, + headers: {}, + body: "done", + }, + ], + }, + ], + limits: { + configured: { + transitions: 2, + connections: 2, + messages: 4, + bytes: 1_000, + duration_ms: 100, + }, + usage: { + offered_events: 2, + admitted_events: 2, + transitions: 2, + connections: 0, + messages: 0, + bytes: 25, + last_at_ms: 2, + }, + }, + }); + expect(JSON.stringify(result)).not.toContain("target-secret"); + }); + + it("classifies unmatched and guard-failed events without aborting", () => { + const input = loginRun(); + const result = runReplayMachine({ + ...input, + events: [httpEvent("/missing"), input.events[0]!, httpEvent("/api", 2)], + }); + + expect(result.decisions.map(({ outcome }) => outcome)).toEqual([ + "unmatched", + "matched", + "guard_failed", + ]); + }); + + it("classifies exhausted transitions", () => { + const input = parseMachineRun( + { + initial_state: "active", + states: [ + { name: "active", max_visits: 3 }, + { name: "done", terminal: true }, + ], + transitions: [ + { + id: "retry_once", + from: "active", + to: "active", + trigger: { protocol: "http", method: "GET", path: "/retry" }, + actions: [{ type: "http_response", status: 200, body: "retry" }], + max_uses: 1, + }, + { + id: "finish", + from: "active", + to: "done", + trigger: { protocol: "http", method: "GET", path: "/done" }, + actions: [{ type: "http_response", status: 200, body: "done" }], + max_uses: 1, + }, + ], + max_transitions: 3, + }, + [httpEvent("/retry"), httpEvent("/retry", 1)], + ); + + expect( + runReplayMachine(input).decisions.map(({ outcome }) => outcome), + ).toEqual(["matched", "transition_exhausted"]); + }); + + it("classifies reconnects that arrive in the wrong state", () => { + const input = parseMachineRun( + { + initial_state: "connected", + states: [ + { name: "connected" }, + { name: "reconnecting" }, + { name: "done", terminal: true }, + ], + transitions: [ + { + id: "disconnect", + from: "connected", + to: "reconnecting", + trigger: { + protocol: "websocket_message", + path: "/socket", + body: "disconnect", + }, + actions: [{ type: "disconnect" }], + max_uses: 1, + }, + { + id: "reconnect", + from: "reconnecting", + to: "done", + trigger: { protocol: "websocket_connect", path: "/socket" }, + actions: [{ type: "websocket_send", data: "ready" }], + max_uses: 1, + }, + ], + max_transitions: 2, + }, + [ + { + protocol: "websocket_connect", + connection: "reconnect", + at_ms: 0, + method: null, + path: "/socket", + headers: {}, + body: "", + }, + ], + ); + + expect(runReplayMachine(input).decisions[0]?.outcome).toBe( + "unexpected_reconnect", + ); + }); + + it("rejects protocol-inconsistent events at the boundary", () => { + const input = loginRun(); + expect( + replayMachineRunInputSchema.safeParse({ + ...input, + events: [{ ...httpEvent("/login"), method: null }], + }).success, + ).toBe(false); + expect( + replayMachineRunInputSchema.safeParse({ + ...input, + events: [ + { + ...httpEvent("/login"), + protocol: "websocket_connect", + connection: "reconnect", + }, + ], + }).success, + ).toBe(false); + expect( + replayMachineRunInputSchema.safeParse({ + ...input, + events: [ + { + ...httpEvent("/login"), + headers: { Authorization: "first", authorization: "second" }, + }, + ], + }).success, + ).toBe(false); + }); + + it("reports limit refusals without committing rejected usage", () => { + const input = loginRun(); + const result = runReplayMachine({ + ...input, + machine: { + ...input.machine, + limits: { ...input.machine.limits, bytes: 1 }, + }, + events: [input.events[0]!], + }); + + expect(result.decisions).toEqual([ + { + event_sequence: 0, + outcome: "limit_exhausted", + transition_sequence: null, + }, + ]); + expect(result.limits.usage).toMatchObject({ + offered_events: 1, + admitted_events: 0, + transitions: 0, + bytes: 0, + }); + }); + + it("records large repeated actions once instead of amplifying each match", () => { + const largeBody = "x".repeat(1_000_000); + const input = parseMachineRun( + { + initial_state: "active", + states: [ + { name: "active", max_visits: 11 }, + { name: "done", terminal: true }, + ], + transitions: [ + { + id: "repeat", + from: "active", + to: "active", + trigger: { protocol: "http", method: "GET", path: "/repeat" }, + actions: [{ type: "http_response", status: 200, body: largeBody }], + max_uses: 10, + }, + { + id: "finish", + from: "active", + to: "done", + trigger: { protocol: "http", method: "GET", path: "/done" }, + actions: [{ type: "http_response", status: 204, body: "" }], + max_uses: 1, + }, + ], + max_transitions: 11, + }, + Array.from({ length: 10 }, (_, index) => httpEvent("/repeat", index)), + ); + + const result = runReplayMachine(input); + expect(result.transition_journal).toHaveLength(10); + expect(result.transition_actions).toHaveLength(1); + expect(JSON.stringify(result).length).toBeLessThan(1_100_000); + }); + + it("rejects aggregate action output above four MiB", () => { + const largeBody = "x".repeat(1_000_000); + const parsed = replayMachineRunInputSchema.safeParse({ + machine: { + initial_state: "waiting", + states: [{ name: "waiting" }, { name: "done", terminal: true }], + transitions: [ + { + id: "send", + from: "waiting", + to: "done", + trigger: { protocol: "websocket_connect", path: "/socket" }, + actions: Array.from({ length: 5 }, () => ({ + type: "websocket_send", + data: largeBody, + })), + max_uses: 1, + }, + ], + max_transitions: 1, + }, + events: [], + }); + + expect(parsed.success).toBe(false); + if (!parsed.success) + expect(parsed.error.issues).toEqual( + expect.arrayContaining([ + expect.objectContaining({ path: ["machine", "transitions"] }), + ]), + ); + }); + + it("bounds action-field and sensitive-redaction work structurally", () => { + const input = loginRun(); + const excessiveCaptures = replayMachineRunInputSchema.safeParse({ + ...input, + events: Array.from({ length: 1_025 }, () => input.events[0]), + }); + expect(excessiveCaptures.success).toBe(false); + if (!excessiveCaptures.success) + expect(excessiveCaptures.error.issues).toEqual( + expect.arrayContaining([expect.objectContaining({ path: ["events"] })]), + ); + + const excessiveFields = replayMachineRunInputSchema.safeParse({ + machine: { + initial_state: "waiting", + states: [{ name: "waiting" }, { name: "done", terminal: true }], + transitions: [ + { + id: "respond", + from: "waiting", + to: "done", + trigger: { protocol: "http", method: "GET", path: "/done" }, + actions: [ + { + type: "http_response", + status: 200, + headers: Object.fromEntries( + Array.from({ length: 1_024 }, (_, index) => [ + `x-field-${String(index)}`, + "", + ]), + ), + body: "", + }, + ], + max_uses: 1, + }, + ], + max_transitions: 1, + }, + events: [], + }); + expect(excessiveFields.success).toBe(false); + if (!excessiveFields.success) + expect(excessiveFields.error.issues).toEqual( + expect.arrayContaining([ + expect.objectContaining({ path: ["machine", "transitions"] }), + ]), + ); + }); +}); diff --git a/tests/serverIdentity.test.ts b/tests/serverIdentity.test.ts index c699dbc91..9b788fecb 100644 --- a/tests/serverIdentity.test.ts +++ b/tests/serverIdentity.test.ts @@ -26,10 +26,10 @@ describe("server and catalog identity", () => { }); expect(PRODUCT_IDENTITY.packageVersion).toBe(packageJson.version); expect(SDK_IDENTITY.server).toBe("2.0.0-beta.4"); - expect(CLI_COMMAND_NAMES).toHaveLength(56); - expect(new Set(CLI_COMMAND_NAMES).size).toBe(56); + expect(CLI_COMMAND_NAMES).toHaveLength(57); + expect(new Set(CLI_COMMAND_NAMES).size).toBe(57); expect(CATALOG_IDENTITY.counts).toEqual({ - cli_commands: 56, + cli_commands: 57, mcp_tools: TOOL_CONTRACTS.length, mcp_prompts: 6, mcp_resources: 2, diff --git a/tests/toolContracts.test.ts b/tests/toolContracts.test.ts index 065db9504..0eb701f72 100644 --- a/tests/toolContracts.test.ts +++ b/tests/toolContracts.test.ts @@ -77,6 +77,7 @@ describe("tool contract inventory", () => { "record_unknown", "update_unknown", "verify_unknown_resolution", + "run_replay_machine", ]); expect(new Set(TOOL_CONTRACTS.map(({ name }) => name)).size).toBe( TOOL_CONTRACTS.length,