feat(tools): carry trusted agent provenance sidecars [SAP-3020]

.changeset/calm-agents-carry.md

@@ -0,0 +1,15 @@
+---
+"@sapiom/tools": minor
+---
+
+Add a private v1 runtime-provenance carrier for agent invocations. Instrumented
+calls send opaque callsite evidence out of band, terminal results retain an
+SDK-only server receipt, and only exact direct result-to-input handoffs forward
+that receipt through a trusted, one-shot build callsite. Private receipt state is
+not package-exported; reflected values are redacted from errors. Request/result
+JSON and calls without metadata remain unchanged. CJS and ESM imports share one
+bundled lexical store, including mixed-format direct handoffs, without exposing
+private extraction or rebinding helpers through the module cache. Build tooling
+uses the unsupported implementation subpath
+`@sapiom/tools/_internal/agent-runtime-provenance`; that subpath may change in
+any release.

.github/workflows/test.yml

@@ -2,7 +2,6 @@ name: Test
 
 on:
   pull_request:
-    branches: [main]
   push:
     branches: [main]
 
@@ -42,6 +41,9 @@ jobs:
       - name: Build
         run: pnpm build
 
+      - name: Verify tools runtime provenance package
+        run: pnpm --filter @sapiom/tools test:runtime-provenance-package
+
       - name: Type check
         run: pnpm typecheck
 

packages/tools/package.json

@@ -87,6 +87,11 @@
       "types": "./dist/cjs/stub/index.d.ts",
       "import": "./dist/esm/stub/index.js",
       "require": "./dist/cjs/stub/index.js"
+    },
+    "./_internal/agent-runtime-provenance": {
+      "types": "./dist/cjs/_internal/agent-runtime-provenance.d.ts",
+      "import": "./dist/esm/_internal/agent-runtime-provenance.js",
+      "require": "./dist/cjs/_internal/agent-runtime-provenance.js"
     }
   },
   "files": [
@@ -100,15 +105,17 @@
     "@sapiom/analytics-core": "workspace:^"
   },
   "scripts": {
-    "build": "npm run gen:version && npm run build:cjs && npm run build:esm && npm run build:esm-pkg",
+    "build": "npm run gen:version && npm run build:cjs && npm run build:esm && npm run build:canonical-exports && npm run build:esm-pkg",
     "build:cjs": "tsc --project tsconfig.cjs.json",
+    "build:canonical-exports": "node scripts/canonicalize-runtime-provenance-exports.mjs",
     "build:esm": "tsc --project tsconfig.esm.json",
     "build:esm-pkg": "node -e \"require('fs').writeFileSync('dist/esm/package.json',JSON.stringify({type:'module'}))\"",
     "clean": "rm -rf dist *.tsbuildinfo",
     "dev": "npm run gen:version && tsc --watch --project tsconfig.cjs.json",
     "gen:version": "node scripts/generate-version.mjs",
     "test": "npm run gen:version && jest",
     "test:coverage": "npm run gen:version && jest --coverage",
+    "test:runtime-provenance-package": "node scripts/test-runtime-provenance-package.mjs",
     "test:watch": "npm run gen:version && jest --watch",
     "typecheck": "npm run gen:version && tsc --noEmit",
     "lint": "eslint src --ext .ts",
@@ -120,6 +127,7 @@
     "@types/node": "^20.11.30",
     "@typescript-eslint/eslint-plugin": "^7.3.1",
     "@typescript-eslint/parser": "^7.3.1",
+    "esbuild": "^0.28.1",
     "eslint": "^8.57.0",
     "jest": "^29.7.0",
     "prettier": "^3.2.5",

packages/tools/scripts/agent-runtime-provenance-entry.ts

@@ -0,0 +1,5 @@
+export * as agents from "../src/agents/index.js";
+export {
+  AGENT_RUNTIME_PROVENANCE_VERSION,
+  carryAgentRuntimeProvenance,
+} from "../src/_internal/agent-runtime-provenance.js";

packages/tools/scripts/canonicalize-runtime-provenance-exports.mjs

@@ -0,0 +1,193 @@
+import assert from "node:assert/strict";
+import { rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { build } from "esbuild";
+
+const require = createRequire(import.meta.url);
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const cjsCarrierPath = resolve(
+  packageRoot,
+  "dist/cjs/_internal/agent-runtime-provenance.js",
+);
+const cjsAgentsPath = resolve(packageRoot, "dist/cjs/agents/index.js");
+const bundlePath = resolve(
+  packageRoot,
+  "dist/cjs/agents/runtime-provenance.cjs",
+);
+
+function runtimeExportNames(modulePath) {
+  const names = Object.keys(require(modulePath)).sort();
+  assert(names.length > 0, `no runtime exports found in ${modulePath}`);
+  for (const name of names) {
+    assert.match(name, /^[A-Z_$][0-9A-Z_$]*$/i, `unsupported export: ${name}`);
+  }
+  return names;
+}
+
+const carrierExportNames = runtimeExportNames(cjsCarrierPath);
+const agentExportNames = runtimeExportNames(cjsAgentsPath);
+
+const canonicalBuild = await build({
+  entryPoints: [
+    resolve(packageRoot, "scripts/agent-runtime-provenance-entry.ts"),
+  ],
+  outfile: bundlePath,
+  bundle: true,
+  format: "cjs",
+  platform: "node",
+  target: "node18",
+  packages: "external",
+  plugins: [
+    {
+      name: "native-agent-transport-boundary",
+      setup(builder) {
+        builder.onResolve({ filter: /^\.\.\/_client\/index\.js$/ }, () => ({
+          path: "agent-runtime-provenance-transport-shim",
+          namespace: "agent-runtime-provenance",
+        }));
+        builder.onLoad(
+          {
+            filter: /^agent-runtime-provenance-transport-shim$/,
+            namespace: "agent-runtime-provenance",
+          },
+          () => ({
+            contents:
+              'export function defaultTransport() { throw new Error("agent transport must be supplied by the format-native facade"); }',
+            loader: "js",
+          }),
+        );
+      },
+    },
+  ],
+  metafile: true,
+  sourcemap: false,
+  logLevel: "warning",
+});
+
+assert.equal(
+  Object.keys(canonicalBuild.metafile.inputs).some((input) =>
+    input.includes("src/_client/"),
+  ),
+  false,
+  "canonical provenance artifact must not bundle a real client graph",
+);
+
+assert.deepEqual(runtimeExportNames(bundlePath), [
+  "AGENT_RUNTIME_PROVENANCE_VERSION",
+  "agents",
+  "carryAgentRuntimeProvenance",
+]);
+assert.deepEqual(
+  Object.keys(require(bundlePath).agents).sort(),
+  agentExportNames,
+);
+assert(
+  agentExportNames.length > 0,
+  "canonical agents namespace has no exports",
+);
+
+function moduleSpecifier(fromPath, toPath) {
+  const path = relative(dirname(fromPath), toPath).replaceAll("\\", "/");
+  return path.startsWith(".") ? path : `./${path}`;
+}
+
+async function writeCjsFacade(outputPath, exportNames, namespace) {
+  const bundleSpecifier = moduleSpecifier(outputPath, bundlePath);
+  const canonical = namespace ? `canonical.${namespace}` : "canonical";
+  const source = [
+    '"use strict";',
+    "// Generated by scripts/canonicalize-runtime-provenance-exports.mjs.",
+    "// Private provenance state is lexical inside the canonical bundle.",
+    `const canonical = require(${JSON.stringify(bundleSpecifier)});`,
+    'Object.defineProperty(exports, "__esModule", { value: true });',
+    ...exportNames.map((name) => `exports.${name} = ${canonical}.${name};`),
+    "",
+  ].join("\n");
+  await writeFile(outputPath, source);
+  await rm(`${outputPath}.map`, { force: true });
+}
+
+async function writeEsmFacade(outputPath, cjsPath, exportNames) {
+  const cjsSpecifier = moduleSpecifier(outputPath, cjsPath);
+  const source = [
+    "// Generated by scripts/canonicalize-runtime-provenance-exports.mjs.",
+    "// Import and require share the canonical closure-backed implementation.",
+    `import canonical from ${JSON.stringify(cjsSpecifier)};`,
+    ...exportNames.map((name) => `export const ${name} = canonical.${name};`),
+    "",
+  ].join("\n");
+  await writeFile(outputPath, source);
+  await rm(`${outputPath}.map`, { force: true });
+}
+
+async function writeCjsAgentsFacade(outputPath, exportNames) {
+  const bundleSpecifier = moduleSpecifier(outputPath, bundlePath);
+  const source = [
+    '"use strict";',
+    "// Generated by scripts/canonicalize-runtime-provenance-exports.mjs.",
+    "// The facade supplies this format's native default transport.",
+    `const canonical = require(${JSON.stringify(bundleSpecifier)}).agents;`,
+    'const { defaultTransport } = require("../_client/index.js");',
+    'Object.defineProperty(exports, "__esModule", { value: true });',
+    ...exportNames
+      .filter((name) => name !== "launch" && name !== "run")
+      .map((name) => `exports.${name} = canonical.${name};`),
+    "exports.launch = async function launch(spec, transport = defaultTransport(), baseUrl) {",
+    "  return canonical.launch(spec, transport, baseUrl);",
+    "};",
+    "exports.run = async function run(spec, transport = defaultTransport(), baseUrl) {",
+    "  return canonical.run(spec, transport, baseUrl);",
+    "};",
+    "",
+  ].join("\n");
+  await writeFile(outputPath, source);
+  await rm(`${outputPath}.map`, { force: true });
+}
+
+async function writeEsmAgentsFacade(outputPath, exportNames) {
+  const bundleSpecifier = moduleSpecifier(outputPath, bundlePath);
+  const source = [
+    "// Generated by scripts/canonicalize-runtime-provenance-exports.mjs.",
+    "// The facade supplies this format's native default transport.",
+    `import canonicalModule from ${JSON.stringify(bundleSpecifier)};`,
+    'import { defaultTransport } from "../_client/index.js";',
+    "const canonical = canonicalModule.agents;",
+    ...exportNames
+      .filter((name) => name !== "launch" && name !== "run")
+      .map((name) => `export const ${name} = canonical.${name};`),
+    "export async function launch(spec, transport = defaultTransport(), baseUrl) {",
+    "  return canonical.launch(spec, transport, baseUrl);",
+    "}",
+    "export async function run(spec, transport = defaultTransport(), baseUrl) {",
+    "  return canonical.run(spec, transport, baseUrl);",
+    "}",
+    "",
+  ].join("\n");
+  await writeFile(outputPath, source);
+  await rm(`${outputPath}.map`, { force: true });
+}
+
+await writeCjsFacade(cjsCarrierPath, carrierExportNames);
+await writeCjsAgentsFacade(cjsAgentsPath, agentExportNames);
+await writeEsmFacade(
+  resolve(packageRoot, "dist/esm/_internal/agent-runtime-provenance.js"),
+  cjsCarrierPath,
+  carrierExportNames,
+);
+await writeEsmAgentsFacade(
+  resolve(packageRoot, "dist/esm/agents/index.js"),
+  agentExportNames,
+);
+
+for (const format of ["cjs", "esm"]) {
+  const storeBase = resolve(
+    packageRoot,
+    `dist/${format}/agents/runtime-callsite-store`,
+  );
+  for (const extension of [".js", ".js.map", ".d.ts", ".d.ts.map"]) {
+    await rm(`${storeBase}${extension}`, { force: true });
+  }
+}