orbit-agent-runtime 0.8.0 → 0.11.0

package/dist/test/report_signing.test.js

@@ -0,0 +1,87 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * W35 — compliance report signing (ED25519, audit-grade).
+ *
+ * A signed report is verifiable by any third party holding the public key —
+ * no shared secret, no access to the original system. That is what makes a
+ * compliance report acceptable to an external auditor.
+ */
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const index_1 = require("../src/index");
+const SEED = "a1b2c3d4e5f60718293a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f8091";
+const OTHER_SEED = "00000000000000000000000000000000000000000000000000000000000000ff";
+function sampleReport() {
+    return {
+        meta: { product: "Orbit Agent Runtime", version: "0.11.0", generatedAt: "2026-09-02T00:00:00.000Z" },
+        governance: {
+            tier: "Strict（合规）", profile: "strict", compression: "aggressive",
+            limiter: "60/60", trip: "3 次 / 5000ms", paeAdmission: "关闭",
+            traceDurability: "required", maxIsolationLevel: "L1", schemaMode: "required"
+        },
+        audit: { entries: 7, signed: true, consistent: true, status: "PASS", text: "链一致" },
+        interventions: { 限流: 1 },
+        determinism: { calls: 4, flagged: 1 },
+        summary: "审计链完整且已签名"
+    };
+}
+(0, node_test_1.test)("report signing: seed deterministically derives a stable key pair", () => {
+    const a = (0, index_1.deriveReportKeyPair)(SEED);
+    const b = (0, index_1.deriveReportKeyPair)(SEED);
+    strict_1.default.equal(a.privateKeyPem, b.privateKeyPem, "same seed -> same private key");
+    strict_1.default.equal(a.publicKeyPem, b.publicKeyPem, "same seed -> same public key");
+    const c = (0, index_1.deriveReportKeyPair)(OTHER_SEED);
+    strict_1.default.notEqual(a.publicKeyPem, c.publicKeyPem, "different seed -> different key");
+    strict_1.default.equal((0, index_1.publicKeyFingerprint)(a.publicKeyPem), (0, index_1.publicKeyFingerprint)(b.publicKeyPem));
+});
+(0, node_test_1.test)("report signing: a valid seed must be 32 bytes of hex", () => {
+    strict_1.default.throws(() => (0, index_1.deriveReportKeyPair)("short"), /32 bytes/);
+    strict_1.default.throws(() => (0, index_1.deriveReportKeyPair)("zz".repeat(32)), /32 bytes/);
+});
+(0, node_test_1.test)("report signing: sign then verify round-trips", () => {
+    const report = sampleReport();
+    const signed = (0, index_1.signComplianceReport)(report, SEED);
+    strict_1.default.ok(signed.sig, "report carries a signature");
+    strict_1.default.equal(signed.sig.algorithm, "ed25519");
+    strict_1.default.equal(signed.sig.publicKeyFingerprint, (0, index_1.publicKeyFingerprint)((0, index_1.deriveReportKeyPair)(SEED).publicKeyPem));
+    const verified = (0, index_1.verifyComplianceReport)(signed, (0, index_1.deriveReportKeyPair)(SEED).publicKeyPem);
+    strict_1.default.equal(verified.ok, true, "a genuine signed report verifies");
+});
+(0, node_test_1.test)("report signing: signing is deterministic", () => {
+    const s1 = (0, index_1.signComplianceReport)(sampleReport(), SEED);
+    const s2 = (0, index_1.signComplianceReport)(sampleReport(), SEED);
+    strict_1.default.equal(s1.sig.signature, s2.sig.signature, "same report + seed -> same signature");
+});
+(0, node_test_1.test)("report signing: tampering with the report body breaks verification", () => {
+    const signed = (0, index_1.signComplianceReport)(sampleReport(), SEED);
+    const tampered = {
+        ...signed,
+        meta: { ...signed.meta, version: "0.99.0-evil" }
+    };
+    const verified = (0, index_1.verifyComplianceReport)(tampered, (0, index_1.deriveReportKeyPair)(SEED).publicKeyPem);
+    strict_1.default.equal(verified.ok, false);
+    strict_1.default.match(verified.reason ?? "", /digest/);
+});
+(0, node_test_1.test)("report signing: the wrong key (or an unsigned report) fails", () => {
+    const signed = (0, index_1.signComplianceReport)(sampleReport(), SEED);
+    const wrongKey = (0, index_1.verifyComplianceReport)(signed, (0, index_1.deriveReportKeyPair)(OTHER_SEED).publicKeyPem);
+    strict_1.default.equal(wrongKey.ok, false);
+    strict_1.default.match(wrongKey.reason ?? "", /signer mismatch/);
+    const unsigned = (0, index_1.verifyComplianceReport)(sampleReport(), (0, index_1.deriveReportKeyPair)(SEED).publicKeyPem);
+    strict_1.default.equal(unsigned.ok, false);
+    strict_1.default.match(unsigned.reason ?? "", /no ed25519 signature/);
+});
+(0, node_test_1.test)("report signing: a mutated signature fails", () => {
+    const signed = (0, index_1.signComplianceReport)(sampleReport(), SEED);
+    const broken = {
+        ...signed,
+        sig: { ...signed.sig, signature: signed.sig.signature.replace(/^./, "A") }
+    };
+    const verified = (0, index_1.verifyComplianceReport)(broken, (0, index_1.deriveReportKeyPair)(SEED).publicKeyPem);
+    strict_1.default.equal(verified.ok, false);
+});
+//# sourceMappingURL=report_signing.test.js.map

package/dist/test/report_signing.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report_signing.test.js","sourceRoot":"","sources":["../../test/report_signing.test.ts"],"names":[],"mappings":"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"}

package/examples/README.md

@@ -1,34 +1,38 @@
-# Examples
-
-Run each example with a plain `node` — no build step, no extra dependencies:
-
-```bash
-# 1. a custom deterministic channel: wire it in, record, replay byte-identically
-node examples/custom-channel.mjs
-
-# 2. a JS plugin adapter (PAE, L0): foreign in-process tools through the gateway
-node examples/js-pae-plugin.mjs
-
-# 3. an MCP adapter (PAE, L2): a real stdio child process, handshake-discovered
-node examples/mcp-adapter.mjs
-
-# 4. the orbit CLI record → replay → diff loop, driven exactly as a user would
-node examples/cli-record-replay.mjs
-```
-
-| Example | Shows |
-|---|---|
-| `custom-channel.mjs` | Implementing `IChannelProvider`, registering it, and proving the record → replay loop is byte-identical — plus drift detection when a call is tampered with |
-| `js-pae-plugin.mjs` | Mapping plain JS functions onto the capability contract via `JsPaeAdapter`; the adapter surface becomes a governed channel whose output replays verbatim |
-| `mcp-adapter.mjs` | Spawning a real MCP server child, `initialize` → `tools/list` handshake, recorded call, then replay **after the peer is dead** (the frozen output is injected, the child is never re-entered) |
-| `cli-record-replay.mjs` | The three-command reproducibility story: `orbit record` → `orbit replay` (zero channel calls) → `orbit diff` (digest-chain reconciliation) |
-
-The imports use relative paths so the examples run inside the repository;
-after `npm i orbit-agent-runtime` they become plain package imports:
-
-```js
-import { OrbitRuntimeHost, ChannelKind } from "orbit-agent-runtime";
-```
-
-Every example exits non-zero on any failed assertion, so they can be used as
-smoke checks in CI (`node examples/custom-channel.mjs && ...`).
+# Examples
+
+Run each example with a plain `node` — no build step, no extra dependencies:
+
+```bash
+# 1. a custom deterministic channel: wire it in, record, replay byte-identically
+node examples/custom-channel.mjs
+
+# 2. a JS plugin adapter (PAE, L0): foreign in-process tools through the gateway
+node examples/js-pae-plugin.mjs
+
+# 3. an MCP adapter (PAE, L2): a real stdio child process, handshake-discovered
+node examples/mcp-adapter.mjs
+
+# 4. the orbit CLI record → replay → diff loop, driven exactly as a user would
+node examples/cli-record-replay.mjs
+
+# 5. LangGraph-style orchestration on a provable runtime (P1.2)
+node examples/langgraph-orchestration.mjs
+```
+
+| Example | Shows |
+|---|---|
+| `custom-channel.mjs` | Implementing `IChannelProvider`, registering it, and proving the record → replay loop is byte-identical — plus drift detection when a call is tampered with |
+| `js-pae-plugin.mjs` | Mapping plain JS functions onto the capability contract via `JsPaeAdapter`; the adapter surface becomes a governed channel whose output replays verbatim |
+| `mcp-adapter.mjs` | Spawning a real MCP server child, `initialize` → `tools/list` handshake, recorded call, then replay **after the peer is dead** (the frozen output is injected, the child is never re-entered) |
+| `cli-record-replay.mjs` | The three-command reproducibility story: `orbit record` → `orbit replay` (zero channel calls) → `orbit diff` (digest-chain reconciliation) |
+| `langgraph-orchestration.mjs` | P1.2 — a minimal LangGraph-style StateGraph whose agent nodes call tools through the Orbit gateway: the SAME graph runs twice, record (real tool side effects) then replay (frozen outputs, zero re-execution), and the final answer is byte-identical while the signed audit chain verifies PASS |
+
+The imports use relative paths so the examples run inside the repository;
+after `npm i orbit-agent-runtime` they become plain package imports:
+
+```js
+import { OrbitRuntimeHost, ChannelKind } from "orbit-agent-runtime";
+```
+
+Every example exits non-zero on any failed assertion, so they can be used as
+smoke checks in CI (`node examples/custom-channel.mjs && ...`).

package/examples/langgraph-orchestration.mjs

@@ -0,0 +1,245 @@
+/**
+ * Example 5 — LangGraph-style orchestration on a provable runtime.
+ *
+ * PRODUCT_PLAN P1.2 (ecosystem embedding) first deliverable. LangGraph is the
+ * orchestrator's home turf — a StateGraph of nodes and edges that passes a
+ * state object around. What LangGraph does NOT do is make the *tool calls*
+ * inside its nodes reproducible, auditable or provable. That is the runtime
+ * layer beneath the orchestrator, and that is what Orbit provides.
+ *
+ * This example runs a minimal, self-contained LangGraph-style engine
+ * (`MiniStateGraph`: nodes, edges, conditional routing, state reduction —
+ * the semantics a LangGraph user would recognise) whose agent nodes call
+ * tools through the Orbit gateway. It then proves the product promise at the
+ * GRAPH level, not just the single-call level:
+ *
+ *   1. record — run the graph once with real tool execution (KV writes);
+ *   2. replay — run the SAME graph again with a replay engine attached: every
+ *      tool call is served frozen output, ZERO real side effects occur, and
+ *      the final answer is byte-identical to the recorded run;
+ *   3. audit  — the signed audit chain verifies PASS, so the graph run is
+ *      tamper-evident and reportable.
+ *
+ * In a real deployment the MiniStateGraph below is replaced by LangGraph (or
+ * any orchestrator); nothing else changes — tools stay behind the gateway.
+ *
+ * Run: node examples/langgraph-orchestration.mjs
+ *
+ * For npm consumers the imports below become
+ *   import { OrbitRuntimeHost, ChannelKind, ... } from "orbit-agent-runtime";
+ * The relative paths are only for running inside this repository.
+ */
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { OrbitRuntimeHost, ChannelKind } from "../dist/src/index.js";
+import { SeededRng, PersistedRecordJournal, ReplayEngine, makeUniqueMark } from "../dist/src/index.js";
+
+/* ---------------------------------------------------------------------------
+ * MiniStateGraph — a minimal LangGraph-style engine.
+ *
+ * Node: (state) => partial state (reduced into the running state); may be
+ *       async. Edge: unconditional (from -> to) or conditional
+ *       (router(state) -> next). invoke() walks from START until END,
+ *       awaiting each node and reducing state at every step.
+ * The engine itself is deterministic; tool side effects live behind the
+ * Orbit gateway and are what record/replay governs.
+ * ------------------------------------------------------------------------- */
+
+const START = Symbol("START");
+const END = Symbol("END");
+
+class MiniStateGraph {
+  constructor() {
+    this.nodes = new Map();
+    this.edges = new Map(); // node -> next | router(state) -> next
+  }
+
+  addNode(name, fn) {
+    this.nodes.set(name, fn);
+    return this;
+  }
+
+  addEdge(from, to) {
+    this.edges.set(from, to);
+    return this;
+  }
+
+  addConditionalEdges(from, router) {
+    this.edges.set(from, router);
+    return this;
+  }
+
+  /** Run the graph from START until END; returns the final state. */
+  async invoke(initialState, onCall = () => {}) {
+    let state = { ...initialState };
+    let node = START;
+    const visits = new Map();
+    while (node !== END) {
+      if (node === START) {
+        node = this.edges.get(START);
+        continue;
+      }
+      visits.set(node, (visits.get(node) ?? 0) + 1);
+      if (visits.get(node) > 50) throw new Error(`graph loop detected at node '${node}'`);
+      const fn = this.nodes.get(node);
+      if (!fn) throw new Error(`node '${node}' not registered`);
+      const patch = (await fn(state, onCall)) ?? {};
+      state = { ...state, ...patch };
+      const edge = this.edges.get(node);
+      node = typeof edge === "function" ? edge(state) : edge;
+    }
+    return state;
+  }
+}
+
+/* ---------------------------------------------------------------------------
+ * The agent graph — research: plan (model) -> tools -> answer.
+ * Tools: mem.writeEntry (side effect), mem.readEntry (read).
+ * ------------------------------------------------------------------------- */
+
+/** A fake model: turns the question into a deterministic tool plan. */
+function planTools(rng, question) {
+  // The "model" consults the question and a seeded rng, so the SAME graph run
+  // is reproducible without calling a real model — the record/replay contrast
+  // stays about tool-call determinism, not model reproducibility.
+  const roll = rng.next();
+  const plan = [];
+  if (roll < 0.6) {
+    plan.push({ tool: "writeEntry", args: ["notes", `observed: ${question}`, 0] });
+  }
+  plan.push({ tool: "readEntry", args: ["notes"] });
+  plan.push({ tool: "readEntry", args: ["facts"] });
+  return plan;
+}
+
+function buildResearchGraph(host, pluginId, seed) {
+  const rng = new SeededRng(seed);
+  const ctxFor = () => ({ traceMarkId: makeUniqueMark(), maxWaitMs: 5000, pluginUnitId: pluginId });
+  const graph = new MiniStateGraph();
+
+  graph.addEdge(START, "planner");
+  graph.addNode("planner", (state) => {
+    const plan = planTools(rng, state.question);
+    return { plan, model: "simulated", seed };
+  });
+  graph.addConditionalEdges("planner", (state) => (state.plan.length > 0 ? "tools" : END));
+
+  graph.addNode("tools", async (state) => {
+    const results = [];
+    for (const item of state.plan) {
+      const out = await host.capabilityInvoke({
+        kind: ChannelKind.MEM_KV_STORE,
+        pluginId,
+        funcName: item.tool,
+        args: item.args,
+        mode: state.mode,
+        ctx: ctxFor()
+      });
+      results.push({ tool: item.tool, key: item.args[0], out });
+    }
+    return { results };
+  });
+  graph.addEdge("tools", "answer");
+
+  graph.addNode("answer", (state) => {
+    const note = state.results?.find((r) => r.tool === "readEntry" && r.key === "notes")?.out;
+    const fact = state.results?.find((r) => r.tool === "readEntry" && r.key === "facts")?.out;
+    return { answer: `research[${state.question}]: note=${note ?? "none"} fact=${fact ?? "none"}` };
+  });
+  graph.addEdge("answer", END);
+  return graph;
+}
+
+/* ---------------------------------------------------------------------------
+ * Assertions & run
+ * ------------------------------------------------------------------------- */
+
+function assert(cond, msg) {
+  if (!cond) {
+    console.error(`✗ ${msg}`);
+    process.exit(1);
+  }
+  console.log(`✓ ${msg}`);
+}
+
+async function main() {
+  const root = await mkdtemp(join(tmpdir(), "orbit-langgraph-"));
+  const walFile = join(root, "record.wal.jsonl");
+  const tracePath = join(root, "trace.wal.jsonl");
+  const seed = 20260902;
+  const pluginId = "research";
+  const question = "what is the capital of france?";
+
+  /* ---- Phase 1 · record: real tool execution ---- */
+  const recordHost = new OrbitRuntimeHost({
+    auditSigningKey: "example-key",
+    recordJournalPath: walFile,
+    traceJournalPath: tracePath
+  });
+  await recordHost.bootHost();
+  recordHost.registerPlugin({
+    id: pluginId,
+    displayName: "Research",
+    edition: "1.0.0",
+    requireHostMinEdition: "1.0.0",
+    allowCapabilities: ["channel:read", "channel:write"]
+  });
+  const recordJournal = recordHost.beginRecording();
+  const recordGraph = buildResearchGraph(recordHost, pluginId, seed);
+  const recorded = await recordGraph.invoke({ question, pluginId, mode: "record" });
+  // A completed graph run is itself an audit event (signed into the chain).
+  recordHost.traceJournal.append({
+    entryClass: "GRAPH_RUN",
+    traceMarkId: "graph-record",
+    factPayload: { graph: "research", calls: recordJournal.size(), answer: recorded.answer }
+  });
+  console.log(`record : ${recordJournal.size()} tool calls | answer=${recorded.answer}`);
+  await recordHost.shutdownHost();
+
+  /* ---- Phase 2 · replay: the SAME graph, zero real side effects ---- */
+  const replayHost = new OrbitRuntimeHost({
+    auditSigningKey: "example-key",
+    recordJournalPath: walFile,
+    traceJournalPath: tracePath
+  });
+  await replayHost.bootHost();
+  replayHost.registerPlugin({
+    id: pluginId,
+    displayName: "Research",
+    edition: "1.0.0",
+    requireHostMinEdition: "1.0.0",
+    allowCapabilities: ["channel:read", "channel:write"]
+  });
+  const recovered = await PersistedRecordJournal.recover(walFile);
+  const replayJournal = replayHost.beginRecording();
+  replayJournal.restoreSnapshot(recovered.snapshot());
+  replayHost.attachReplayEngine(replayJournal);
+  // The KV store on this host is EMPTY and writes never reach it: replay
+  // serves frozen outputs from the recorded window. If replay really
+  // re-executed, readEntry("notes") would return null and the answer would
+  // differ — the byte-identical assertion below is therefore meaningful.
+  const replayGraph = buildResearchGraph(replayHost, pluginId, seed);
+  const replayed = await replayGraph.invoke({ question, pluginId, mode: "replay" });
+
+  /* ---- Phase 3 · assertions ---- */
+  console.log(`replay : ${recovered.size()} calls injected | answer=${replayed.answer}`);
+  assert(recorded.answer === replayed.answer, "graph-level answer is byte-identical across record and replay");
+  assert(
+    JSON.stringify(recorded.results) === JSON.stringify(replayed.results),
+    "every tool result is byte-identical (frozen outputs, zero re-execution)"
+  );
+  assert(recovered.size() === recordJournal.size(), `all ${recordJournal.size()} tool calls were recorded`);
+  const chain = replayHost.verifyAuditChain();
+  assert(chain.consistent === true && chain.signed === true, `audit chain PASS (${chain.total} entries)`);
+  console.log("\nLangGraph-style orchestration on a provable runtime: record → replay → audit, all green.");
+
+  await replayHost.shutdownHost();
+  await rm(root, { recursive: true, force: true });
+}
+
+main().catch((err) => {
+  console.error(`✗ ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orbit-agent-runtime",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "description": "Deterministic · Provable · Governable — a plugin-based agent runtime kernel with hot plugin registration, provable fault isolation, full-chain traceability and sandboxed execution.",
   "keywords": [
     "agent",
@@ -38,6 +38,8 @@
     "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && node -e \"for (const p of ['infra-common','core-hub','sandbox-runtime','pae-engine']) fs.rmSync('packages/'+p+'/dist',{recursive:true,force:true})\"",
     "test": "npm run build && node --test \"dist/test/*.test.js\"",
     "test:console": "node --test web/test/*.test.mjs",
+    "test:docsite": "node --test tools/render-md.test.mjs",
+    "docsite": "node tools/build-site.mjs",
     "start:web": "node web/bridge-server.mjs",
     "test:web": "node --test web/test/*.test.mjs",
     "demo": "npm run build && node dist/demo-host.js",
@@ -47,6 +49,7 @@
     "example:pae": "npm run build && node examples/js-pae-plugin.mjs",
     "example:mcp": "npm run build && node examples/mcp-adapter.mjs",
     "example:cli": "npm run build && node examples/cli-record-replay.mjs",
+    "example:langgraph": "npm run build && node examples/langgraph-orchestration.mjs",
     "benchmark": "npm run build && node benchmarks/run-all.mjs",
     "prepublishOnly": "npm run clean && npm run build && npm test && npm run test:console"
   },

package/src/index.ts

@@ -49,7 +49,11 @@ export {
   auditChainHash,
   chainTailOf,
   stableJson,
-  AUDIT_GENESIS_HASH
+  AUDIT_GENESIS_HASH,
+  deriveReportKeyPair,
+  signComplianceReport,
+  verifyComplianceReport,
+  publicKeyFingerprint
 } from "@orbit/core-hub";
 export type { AuditChainReport } from "@orbit/core-hub";