orbit-agent-runtime 0.8.0

package/examples/custom-channel.mjs

@@ -0,0 +1,102 @@
+/**
+ * Example 1 — a custom deterministic channel.
+ *
+ * Shows how a plugin-extendable capability channel is implemented and wired
+ * into the host, then how the record → replay loop proves it byte-identical.
+ *
+ * The channel uppercases text ("shout"). It is trivially deterministic: no
+ * random, no clock, no I/O — so a recorded call replays to exactly the same
+ * output, and the digest-chain reconciliation reports no drift.
+ *
+ * Run: node examples/custom-channel.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 { OrbitRuntimeHost, ChannelKind } from "../dist/src/index.js";
+import { makeUniqueMark, DeterminismLevel, RecordJournal, ReplayEngine } from "../dist/src/index.js";
+
+class ShoutChannel {
+  determinismMeta = {
+    determinism: DeterminismLevel.DETERMINISTIC,
+    replayPolicy: "inject"
+  };
+
+  async setup() {}
+  async teardown() {}
+
+  /** Uppercase the input. The only surface of the channel. */
+  async shout(text) {
+    return String(text).toUpperCase();
+  }
+}
+
+async function main() {
+  console.log("=== example 1 · custom deterministic channel ===");
+
+  const host = new OrbitRuntimeHost();
+  await host.bootHost();
+  console.log("[boot] host started");
+
+  // Register the channel as a plugin-extension of a real ChannelKind. Channel
+  // kinds are the fixed capability vocabulary; plugins provide providers.
+  host.channelHub.registerPluginExtChannel(ChannelKind.LLM_ACCESS, new ShoutChannel());
+  console.log("[channel] ShoutChannel registered on LLM_ACCESS");
+
+  // Every plugin must declare the capabilities it may use (capability gate).
+  host.registerPlugin({
+    id: "example.shout",
+    displayName: "Shout Example",
+    edition: "1.0.0",
+    requireHostMinEdition: "1.0.0",
+    allowCapabilities: ["channel:read"]
+  });
+
+  const ctx = { traceMarkId: makeUniqueMark(), pluginUnitId: "example.shout", maxWaitMs: 5000 };
+  const call = (mode, text) =>
+    host.capabilityInvoke({
+      kind: ChannelKind.LLM_ACCESS,
+      pluginId: "example.shout",
+      funcName: "shout",
+      args: [text],
+      mode,
+      ctx
+    });
+
+  const out = await call("live", "hello orbit");
+  console.log(`[live]   shout("hello orbit") -> "${out}"`);
+
+  // record mode: real channel calls, journaled verbatim through the gateway.
+  const recordJournal = host.beginRecording();
+  await call("record", "first");
+  await call("record", "second");
+  await call("record", "third");
+  console.log(`[record] journal holds ${recordJournal.snapshot().length} call(s)`);
+
+  // replay mode: attach the recorded journal as the injection source, then
+  // re-run the SAME sequence. The gateway injects frozen outputs (zero channel
+  // calls) and every call is signature-checked against the recorded chain —
+  // a mismatch is a ReplayDriftError, so "no error" IS the byte-identical proof.
+  host.attachReplayEngine(new ReplayEngine(recordJournal));
+  const r1 = await call("replay", "first");
+  const r2 = await call("replay", "second");
+  const r3 = await call("replay", "third");
+  console.log(`[replay] first/second/third -> "${r1}" / "${r2}" / "${r3}" (injected)`);
+
+  // Drift detection: changing the input of the next call must be rejected.
+  try {
+    await call("replay", "tampered");
+    console.error("FAIL: a drifted call was not rejected");
+    process.exit(1);
+  } catch (err) {
+    console.log(`[drift]  tampered input rejected: ${err.constructor.name}`);
+  }
+
+  console.log("OK — custom channel records and replays byte-identically");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/js-pae-plugin.mjs

@@ -0,0 +1,128 @@
+/**
+ * Example 2 — a JS plugin adapter (PAE, L0).
+ *
+ * External plain-JavaScript functions are mapped onto the kernel capability
+ * contract through a JsPaeAdapter and published as tools on the single PAE
+ * channel. Every call through the adapter is a gateway transaction: recorded,
+ * replayed byte-identically, and the adapter surface is hashed into the run
+ * fingerprint for drift detection.
+ *
+ * Run: node examples/js-pae-plugin.mjs
+ *
+ * The "plugin" here is an in-process function bundle (a foreign runtime in
+ * embryo). See examples/mcp-adapter.mjs for a true out-of-process peer.
+ */
+import { OrbitRuntimeHost, ChannelKind } from "../dist/src/index.js";
+import { JsPaeAdapter, SeededRng, DeterminismLevel } from "../dist/src/index.js";
+import { makeUniqueMark } from "../dist/src/index.js";
+
+/** The foreign tool bundle — deterministic by contract: no Math.random,
+ *  no Date.now; randomness arrives via the injected SeededRng. */
+function makeToolBundle() {
+  const rng = new SeededRng(42);
+  return {
+    rollDie: () => {
+      // Deterministic "die roll" for the given seed — replay reproduces it.
+      const value = 1 + Math.floor(rng.next() * 6);
+      return { face: value, seeded: true };
+    },
+    greet: (ctx, name) => `Hello, ${String(name)}!`,
+    add: (ctx, a, b) => Number(a) + Number(b)
+  };
+}
+
+async function main() {
+  console.log("=== example 2 · JS plugin adapter (PAE L0) ===");
+
+  const host = new OrbitRuntimeHost();
+  await host.bootHost();
+  console.log("[boot] host started");
+
+  const bundle = makeToolBundle();
+  const adapter = new JsPaeAdapter({
+    adapterId: "example.dice",
+    sourceEdition: "1.0.0",
+    isolation: "L0",
+    tools: [
+      {
+        name: "rollDie",
+        capability: "channel:read",
+        determinism: DeterminismLevel.DETERMINISTIC,
+        fidelity: "full",
+        description: "Roll a deterministic die (seeded)",
+        handler: () => bundle.rollDie()
+      },
+      {
+        name: "greet",
+        capability: "channel:read",
+        determinism: DeterminismLevel.DETERMINISTIC,
+        fidelity: "full",
+        description: "Greet someone",
+        handler: (_ctx, name) => bundle.greet(_ctx, name)
+      }
+    ]
+  });
+
+  const pact = host.registerPaeToolAdapter(adapter);
+  console.log(`[adapter] registered "${adapter.meta.adapterId}" -> pact "${pact.id}"`);
+  console.log(`[adapter] tools: ${adapter.describe().map((t) => t.name).join(", ")}`);
+
+  // The adapter surface is now a capability channel: foreign calls travel the
+  // same gateway → hub path as any native channel call.
+  const ctx = { traceMarkId: makeUniqueMark(), pluginUnitId: pact.id, maxWaitMs: 5000 };
+  const roll = await host.capabilityInvoke({
+    kind: ChannelKind.PAE_TOOL,
+    pluginId: pact.id,
+    funcName: "rollDie",
+    args: [],
+    mode: "live",
+    ctx
+  });
+  console.log(`[live]   rollDie() -> ${JSON.stringify(roll)}`);
+
+  // Record the same call, then replay it: the frozen output is injected and
+  // the signature check guarantees the recorded run reproduces verbatim.
+  const recordJournal = host.beginRecording();
+  await host.capabilityInvoke({
+    kind: ChannelKind.PAE_TOOL,
+    pluginId: pact.id,
+    funcName: "rollDie",
+    args: [],
+    mode: "record",
+    ctx
+  });
+  const first = recordJournal.get(0).outputSnapshot;
+  console.log(`[record] rollDie() journaled output -> ${JSON.stringify(first)}`);
+
+  host.attachReplayEngine(
+    new (await import("../dist/src/index.js")).ReplayEngine(recordJournal)
+  );
+  const replayed = await host.capabilityInvoke({
+    kind: ChannelKind.PAE_TOOL,
+    pluginId: pact.id,
+    funcName: "rollDie",
+    args: [],
+    mode: "replay",
+    ctx
+  });
+  console.log(`[replay] rollDie() injected output -> ${JSON.stringify(replayed)}`);
+  if (JSON.stringify(replayed) !== JSON.stringify(first)) {
+    console.error("FAIL: replayed output differs from the recorded one");
+    process.exit(1);
+  }
+
+  // Drift surface: registering a different tool bundle changes the surface
+  // hash, so a trace recorded under the old bundle no longer replays cleanly.
+  console.log("[drift]  adapter surface is part of the run fingerprint");
+  const fp = host.runFingerprint();
+  console.log(`[drift]  paeAdaptersHash = ${fp.paeAdaptersHash ? "present" : "absent"}`);
+
+  await host.shutdownHost();
+  console.log("[shutdown] clean teardown");
+  console.log("OK — foreign JS tools are governed, recorded and replayed verbatim");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/mcp-adapter.mjs

@@ -0,0 +1,102 @@
+/**
+ * Example 3 — an MCP adapter (PAE, L2, out-of-process).
+ *
+ * A real MCP server child process is spawned over stdio, passed through the
+ * `initialize` handshake and `tools/list` discovery, and only then registered —
+ * the console never advertises a tool the peer did not announce. Every call is
+ * an IO_BOUND gateway transaction: recorded and replayed byte-identically even
+ * after the peer is gone (replay injects the frozen output and never re-enters
+ * the child).
+ *
+ * The peer is a tiny MCP server bundled with the repo:
+ *   web/test/fixtures/mcp-stdio-server.mjs   (tools: greet, total)
+ *
+ * Run: node examples/mcp-adapter.mjs
+ */
+import { fileURLToPath } from "node:url";
+import { OrbitRuntimeHost, ChannelKind } from "../dist/src/index.js";
+import { McpPaeAdapter, StdioMcpTransport, ReplayEngine } from "../dist/src/index.js";
+import { makeUniqueMark } from "../dist/src/index.js";
+
+const PEER = fileURLToPath(new URL("../web/test/fixtures/mcp-stdio-server.mjs", import.meta.url));
+
+async function main() {
+  console.log("=== example 3 · MCP adapter (PAE L2) ===");
+  console.log(`[peer]  spawning ${PEER}`);
+
+  const host = new OrbitRuntimeHost();
+  await host.bootHost();
+
+  const transport = new StdioMcpTransport({ command: process.execPath, args: [PEER] });
+  const adapter = new McpPaeAdapter({
+    adapterId: "example.mcp",
+    sourceEdition: "0.1.0",
+    transport
+  });
+
+  // connect = handshake first, then register the *discovered* surface.
+  const pact = await host.connectPaeToolAdapter(adapter, { maxWaitMs: 10_000 });
+  const tools = adapter.describe().map((t) => t.name);
+  console.log(`[adapter] connected; discovered tools: ${tools.join(", ")}`);
+  if (!tools.includes("greet") || !tools.includes("total")) {
+    console.error("FAIL: expected tools greet + total from the peer");
+    process.exit(1);
+  }
+
+  const ctx = { traceMarkId: makeUniqueMark(), pluginUnitId: pact.id, maxWaitMs: 10_000 };
+
+  // Live call: real child process, real JSON-RPC round trip.
+  const live = await host.capabilityInvoke({
+    kind: ChannelKind.PAE_TOOL,
+    pluginId: pact.id,
+    funcName: "greet",
+    args: [{ name: "Orbit" }],
+    mode: "live",
+    ctx
+  });
+  console.log(`[live]   greet({name:"Orbit"}) -> ${JSON.stringify(live)}`);
+
+  // Record a call, then kill the peer: replay must still reproduce verbatim,
+  // because the frozen output is injected — the child is never re-entered.
+  const recordJournal = host.beginRecording();
+  await host.capabilityInvoke({
+    kind: ChannelKind.PAE_TOOL,
+    pluginId: pact.id,
+    funcName: "total",
+    args: [{ values: [1, 2, 3] }],
+    mode: "record",
+    ctx
+  });
+  const recorded = recordJournal.get(0).outputSnapshot;
+  console.log(`[record] total([1,2,3]) journaled -> ${JSON.stringify(recorded)}`);
+
+  // Kill the peer process but keep the registration: the surface stays part of
+  // the fingerprint, so the trace still replays — with the frozen output
+  // injected, the dead child is never re-entered.
+  await adapter.teardown();
+  console.log("[peer]   child process closed; adapter surface retained");
+
+  host.attachReplayEngine(new ReplayEngine(recordJournal));
+  const replayed = await host.capabilityInvoke({
+    kind: ChannelKind.PAE_TOOL,
+    pluginId: pact.id,
+    funcName: "total",
+    args: [{ values: [1, 2, 3] }],
+    mode: "replay",
+    ctx
+  });
+  console.log(`[replay] total([1,2,3]) injected -> ${JSON.stringify(replayed)}`);
+  if (JSON.stringify(replayed) !== JSON.stringify(recorded)) {
+    console.error("FAIL: replay after peer death differs from the recording");
+    process.exit(1);
+  }
+
+  await host.shutdownHost();
+  console.log("[shutdown] clean teardown");
+  console.log("OK — MCP tools are governed, recorded and replayable after peer death");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "orbit-agent-runtime",
+  "version": "0.8.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",
+    "runtime",
+    "plugin",
+    "sandbox",
+    "circuit-breaker",
+    "traceability",
+    "deterministic-replay"
+  ],
+  "license": "Apache-2.0",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "bin": {
+    "orbit": "bin/orbit.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "examples",
+    "benchmarks",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "workspaces": [
+    "packages/*",
+    "web"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "build:packages": "tsc -b packages/infra-common packages/core-hub packages/sandbox-runtime packages/pae-engine",
+    "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",
+    "start:web": "node web/bridge-server.mjs",
+    "test:web": "node --test web/test/*.test.mjs",
+    "demo": "npm run build && node dist/demo-host.js",
+    "demo:replay": "npm run build && node dist/demo-replay.js",
+    "demo:deepseek": "npm run build && node dist/demo-deepseek.js",
+    "example:channel": "npm run build && node examples/custom-channel.mjs",
+    "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",
+    "benchmark": "npm run build && node benchmarks/run-all.mjs",
+    "prepublishOnly": "npm run clean && npm run build && npm test && npm run test:console"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "typescript": "^5.9.3"
+  }
+}