@sentropic/h2a-cli 0.24.0 → 0.26.0

package/dist/cli.js

@@ -36,19 +36,20 @@
  * The full machine-readable manifest lives in `./cli-contract.ts`
  * (`H2A_CLI_VERB_CONTRACTS`). Human-readable reference: `docs/cli-contract.md`.
  */
+import { spawnSync } from "node:child_process";
 import { generateKeyPairSync } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
-import { H2A_ATTESTER_COMPREHENSION_RIGHT, H2A_COMPREHENSION_ATTESTATION_BODY_KIND, H2A_DECLARATION_INTERET_BODY_KIND, H2A_ORG_MANIFEST_FILENAME, H2A_ORG_PROPOSAL_BODY_KIND, H2A_ORG_RATIFIED_BODY_KIND, H2A_ROLES, H2A_WORK_STATUSES, auditNhiPosture, buildComprehensionAttestation, canAttestComprehension, computeHash, createEnvelope, diffOrgManifest, effectiveOrgInstances, isComprehensionAttestation, nhiAttestationEnvelope, nhiInventory, nhiTrustBundle, orgAssignmentEnvelope, parseOrgManifest, signCanonical, signEnvelope, subagentAddress, validateOrgManifest, verifyComprehensionAttestation } from "@sentropic/h2a";
+import { H2A_ATTESTER_COMPREHENSION_RIGHT, H2A_COMPREHENSION_ATTESTATION_BODY_KIND, H2A_DECLARATION_INTERET_BODY_KIND, H2A_ORG_MANIFEST_FILENAME, H2A_ORG_PROPOSAL_BODY_KIND, H2A_ORG_RATIFIED_BODY_KIND, H2A_ROLES, H2A_WORK_STATUSES, auditNhiPosture, buildComprehensionAttestation, canAttestComprehension, checkEnvelopeFreshness, computeHash, createEnvelope, diffOrgManifest, effectiveOrgInstances, isComprehensionAttestation, nhiAttestationEnvelope, nhiInventory, nhiTrustBundle, orgAssignmentEnvelope, parseOrgManifest, signCanonical, signEnvelope, subagentAddress, validateOrgManifest, verifyComprehensionAttestation } from "@sentropic/h2a";
 import { H2A_CLAUDE_HOST } from "./hosts/claude.js";
 import { H2A_CODEX_HOST } from "./hosts/codex.js";
 import { H2A_GEMINI_HOST } from "./hosts/gemini.js";
 import { H2A_AGY_HOST } from "./hosts/agy.js";
 import { H2A_CLI_MCP_TOOL_NAMES } from "./mcp.js";
-import { renderStopHook, claudeStopHookEntry, isH2ARecordHook, codexPluginManifest, codexMarketplaceManifest, codexPluginTrustCommands, H2A_CODEX_PLUGIN_NAME, H2A_HOST_PLUGIN_HOSTS } from "./hosts/plugin.js";
-import { H2A_STORE_SCHEMA_VERSION, createLocalStore, listPresence, sanitizeStorePaths } from "./runtime/local-files/index.js";
+import { renderStopHook, claudeStopHookEntry, claudeDriveReceiveHookEntry, isH2ADriveReceiveHook, isH2ARecordHook, codexPluginManifest, codexMarketplaceManifest, codexPluginTrustCommands, H2A_CODEX_PLUGIN_NAME, H2A_HOST_PLUGIN_HOSTS } from "./hosts/plugin.js";
+import { H2A_STORE_SCHEMA_VERSION, createLocalStore, listPresence, safePathSegment, sanitizeStorePaths } from "./runtime/local-files/index.js";
 import { runMcpStdio } from "./runtime/mcp/index.js";
 import { renderK8sSidecar } from "./runtime/deploy/k8s-sidecar.js";
 import { renderK8sTenant } from "./runtime/deploy/k8s-tenant.js";
@@ -57,7 +58,7 @@ import { recordStop, scanDrumbeat, clearDrumbeatEntry, runDrumbeatWatch as runDr
 import { gatherNhiSnapshot } from "./runtime/nhi.js";
 import { raiseBlockage, listBlockages, resolveBlockage } from "./runtime/blockage/index.js";
 import { recordEscalation, listEscalations, clearEscalation } from "./runtime/escalation/index.js";
-import { authorizeDrive, chainDriver, formatSignedDriveInstruction, headlessDriver, localTmuxDriver, loggingDriver, nativeBackchannelDriver } from "./runtime/drive/index.js";
+import { authorizeDrive, chainDriver, formatSignedDriveInstruction, headlessDriver, localTmuxDriver, loggingDriver, nativeBackchannelDriver, remoteDriveServerForStore, verifyDriveOnReceive } from "./runtime/drive/index.js";
 import { verifyEnvelopeSysmlRef } from "./runtime/sysml/index.js";
 import { checkUpgrade, performUpgrade, currentCliVersion, upgradeCachePath, canReexec, reexecSelf, H2A_REEXEC_GUARD_ENV } from "./runtime/upgrade/index.js";
 import { resolveLiveIdentity } from "./runtime/identity/index.js";
@@ -132,6 +133,8 @@ export function renderCliHelp() {
         "  h2a negotiate journal --id <id> [--root <path>]",
         "  h2a declare-interest --negotiation <id> --instance <id> --interets <a,b> [--bindings <scope,...>] [--masque-impact-collectif] [--event-id <id>] [--root <path>]",
         "  h2a conflict-posture --negotiation <id> [--root <path>]",
+        "  h2a dossier --negotiation <id> [--presenter <id>] [--advisory-gate] [--event-id <id>] [--root <path>]",
+        "  h2a confiance --negotiation <id> [--root <path>]",
         "  h2a attest-comprehension --instance <id> --dossier <file|sha256:...> --private-key <pem-path> [--negotiation <id> | --to <instance>] [--role <role>] [--scope <scope>] [--root <path>]",
         "  h2a comprehension list --negotiation <id> [--root <path>]",
         "  h2a comprehension verify --json <event-or-envelope-json> --public-key <pem-file>",
@@ -150,7 +153,9 @@ export function renderCliHelp() {
         "  h2a upgrade [--check]   (--check: report current vs latest; bare: npm i -g @sentropic/h2a-cli@latest)",
         "  h2a remote serve [--port <n>] [--host <h>] [--path </h2a/envelopes>] [--root <path>]",
         "  h2a remote send --url <u> --instance <signer> --private-key <pem> --json <envelope>",
-        "  h2a drive --from <instance> --to <instance> --instruction <text> --private-key <pem> [--driver logging|native|local-tmux|headless|auto] [--root <path>]",
+        "  h2a drive --from <instance> --to <instance> --instruction <text> --private-key <pem> [--driver logging|native|local-tmux|headless|auto] [--host <host>] [--root <path>]",
+        "  h2a drive receive --to <instance> (--line <signed-line> | --stdin) [--ignore-non-drive] [--root <path>]   (verify-before-act gate for host hooks)",
+        "  h2a drive serve --to <instance> --inject-command <command> [--port <n>] [--host <h>] [--path </h2a/drive>] [--root <path>]   (remote verify-before-inject service)",
         "  h2a drumbeat record --instance <id> --status <working|paused|done|blocked|out-of-tokens> [--command <c>] [--resume-command <c>] [--tmux-session <s> --tmux-pane <p>] [--root <path>]",
         "  h2a drumbeat scan [--max-relances <n>] [--root <path>]",
         "  h2a drumbeat clear --instance <id> [--root <path>]",
@@ -776,6 +781,48 @@ function cmdConflictPosture(flags, streams) {
         return classifyStoreError(message);
     }
 }
+function cmdDossier(flags, streams) {
+    if (!flags.negotiation) {
+        streams.stderr.write("h2a dossier: --negotiation <id> required\n");
+        return 1;
+    }
+    const cwd = streams.cwd ?? (() => process.cwd());
+    const root = resolveRoot(flags, cwd);
+    const store = createLocalStore({ root });
+    try {
+        const result = store.deriveDecisionDossier(flags.negotiation, {
+            presenter: flags.presenter,
+            advisoryGate: flags["advisory-gate"] === "true",
+            eventId: flags["event-id"]
+        });
+        streams.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const message = error.message;
+        streams.stderr.write(`h2a dossier: ${message}\n`);
+        return classifyStoreError(message);
+    }
+}
+function cmdConfiance(flags, streams) {
+    if (!flags.negotiation) {
+        streams.stderr.write("h2a confiance: --negotiation <id> required\n");
+        return 1;
+    }
+    const cwd = streams.cwd ?? (() => process.cwd());
+    const root = resolveRoot(flags, cwd);
+    const store = createLocalStore({ root });
+    try {
+        const posture = store.derivePostureConfiance(flags.negotiation);
+        streams.stdout.write(`${JSON.stringify({ negotiationId: flags.negotiation, posture }, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const message = error.message;
+        streams.stderr.write(`h2a confiance: ${message}\n`);
+        return classifyStoreError(message);
+    }
+}
 function cmdAttestComprehension(flags, streams) {
     if (!flags.instance || !flags.dossier || !flags["private-key"]) {
         streams.stderr.write("h2a attest-comprehension: --instance <id> --dossier <file|sha256:...> --private-key <pem-path> required\n");
@@ -1109,6 +1156,82 @@ export async function runRemoteServe(flags, io = { stdout: process.stdout, stder
         server.on("close", () => resolve(0));
     });
 }
+function commandDriveInjector(command, io) {
+    return (payload, signedLine) => {
+        const result = spawnSync(command, {
+            shell: true,
+            input: `${signedLine}\n`,
+            encoding: "utf8",
+            env: {
+                ...process.env,
+                H2A_DRIVE_LINE: signedLine,
+                H2A_DRIVE_FROM: payload.from,
+                H2A_DRIVE_TO: payload.to,
+                H2A_DRIVE_INSTRUCTION: payload.instruction
+            },
+            timeout: 30_000
+        });
+        if (result.error) {
+            io.stderr.write(`h2a drive serve: injector command failed: ${result.error.message}\n`);
+            return false;
+        }
+        if (result.status !== 0) {
+            io.stderr.write(`h2a drive serve: injector command exited ${result.status ?? "unknown"}\n`);
+            return false;
+        }
+        return true;
+    };
+}
+/**
+ * `h2a drive serve` (EVO-1 E1d): long-running HTTP endpoint for remote/sidecar
+ * injection. It verifies signature, target, authority, freshness, and replay
+ * before crossing the remote trust boundary into the caller-provided injector.
+ */
+export async function runDriveServe(flags, io = { stdout: process.stdout, stderr: process.stderr }, options = {}) {
+    if (!flags.to) {
+        io.stderr.write("h2a drive serve: --to is required\n");
+        return 1;
+    }
+    const inject = options.inject ?? (flags["inject-command"] ? commandDriveInjector(flags["inject-command"], io) : undefined);
+    if (!inject) {
+        io.stderr.write("h2a drive serve: --inject-command is required\n");
+        return 1;
+    }
+    const cwd = io.cwd ?? (() => process.cwd());
+    const root = resolveRoot(flags, cwd);
+    const host = flags.host ?? "127.0.0.1";
+    const port = flags.port ? Number.parseInt(flags.port, 10) : 8788;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        io.stderr.write(`h2a drive serve: invalid --port "${flags.port}"\n`);
+        return 1;
+    }
+    let store;
+    try {
+        store = createLocalStore({ root });
+    }
+    catch (error) {
+        io.stderr.write(`h2a drive serve: ${error.message}\n`);
+        return 1;
+    }
+    const server = remoteDriveServerForStore(store, {
+        to: flags.to,
+        path: flags.path,
+        inject
+    });
+    return await new Promise((resolve) => {
+        server.on("error", (err) => {
+            io.stderr.write(`h2a drive serve: ${err.message}\n`);
+            resolve(1);
+        });
+        server.listen(port, host, () => {
+            const addr = server.address();
+            const boundPort = typeof addr === "object" && addr ? addr.port : port;
+            io.stdout.write(`h2a drive serve: listening on http://${host}:${boundPort}${flags.path ?? "/h2a/drive"} (to ${flags.to}, root ${root})\n`);
+            io.onListening?.(server);
+        });
+        server.on("close", () => resolve(0));
+    });
+}
 /**
  * `h2a remote send` (DEC-077): sign an envelope and POST it to a remote h2a
  * endpoint. Async (network), so dispatched from bin.ts. Exit 0 on a 2xx,
@@ -1703,6 +1826,38 @@ function buildDriveDriver(kind, log) {
             };
     }
 }
+function driveReplayGuard(root) {
+    const dir = join(root, "drive-replay");
+    return {
+        accept(envelope, now = Date.now()) {
+            const freshness = checkEnvelopeFreshness(envelope, { now });
+            if (!freshness.ok)
+                return freshness;
+            mkdirSync(dir, { recursive: true });
+            const file = join(dir, `${safePathSegment(envelope.id)}.json`);
+            try {
+                writeFileSync(file, `${JSON.stringify({ id: envelope.id, createdAt: envelope.createdAt })}\n`, { encoding: "utf8", flag: "wx" });
+            }
+            catch (error) {
+                if (error.code === "EEXIST") {
+                    return { ok: false, reason: "replayed" };
+                }
+                throw error;
+            }
+            return { ok: true };
+        },
+        size() {
+            try {
+                return readdirSync(dir).filter((entry) => entry.endsWith(".json")).length;
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return 0;
+                throw error;
+            }
+        }
+    };
+}
 function cmdDrive(flags, streams) {
     const cwd = streams.cwd ?? (() => process.cwd());
     if (!flags.from || !flags.to || !flags.instruction || !flags["private-key"]) {
@@ -1738,6 +1893,7 @@ function cmdDrive(flags, streams) {
     const driver = buildDriveDriver(kind, log);
     const result = driver.drive({
         to: flags.to,
+        host: flags.host ?? flags.to.split(":", 1)[0],
         instructionLine,
         launchContext: latestLaunchContext(root, flags.to)
     });
@@ -1756,6 +1912,59 @@ function cmdDrive(flags, streams) {
     }, null, 2)}\n`);
     return driven ? 0 : 2;
 }
+function stdinText(streams) {
+    if (typeof streams.stdinText === "function")
+        return streams.stdinText();
+    return streams.stdinText ?? readFileSync(0, "utf8");
+}
+function driveLineFromStdin(raw) {
+    return driveLineFromHookInput(raw) ?? "";
+}
+function cmdDriveReceive(flags, streams) {
+    const cwd = streams.cwd ?? (() => process.cwd());
+    const line = flags.line ?? (flags.stdin ? driveLineFromStdin(stdinText(streams) ?? "") : undefined);
+    if (!flags.to) {
+        streams.stderr.write("h2a drive receive: --to is required\n");
+        return 1;
+    }
+    if (!line) {
+        if (flags["ignore-non-drive"]) {
+            streams.stdout.write(`${JSON.stringify({ ok: true, ignored: true, reason: "non-drive" }, null, 2)}\n`);
+            return 0;
+        }
+        streams.stderr.write("h2a drive receive: --line or --stdin is required\n");
+        return 1;
+    }
+    if (flags["ignore-non-drive"] && !line.trim().startsWith("[h2a ")) {
+        streams.stdout.write(`${JSON.stringify({ ok: true, ignored: true, reason: "non-drive" }, null, 2)}\n`);
+        return 0;
+    }
+    const root = resolveRoot(flags, cwd);
+    const store = createLocalStore({ root });
+    const now = flags.now ? Number.parseInt(flags.now, 10) : undefined;
+    if (flags.now && Number.isNaN(now)) {
+        streams.stderr.write(`h2a drive receive: --now must be a millisecond timestamp (got "${flags.now}")\n`);
+        return 1;
+    }
+    let result;
+    try {
+        result = verifyDriveOnReceive(store, line, {
+            to: flags.to,
+            guard: driveReplayGuard(root),
+            ...(now !== undefined ? { now } : {})
+        });
+    }
+    catch (error) {
+        streams.stderr.write(`h2a drive receive: ${error.message}\n`);
+        return 3;
+    }
+    if (!result.ok) {
+        streams.stderr.write(`h2a drive receive: ${result.reason}\n`);
+        return 2;
+    }
+    streams.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+}
 export async function runDrumbeatRelanceInbox(flags, io = {
     stdout: process.stdout,
     stderr: process.stderr
@@ -1964,6 +2173,50 @@ function isPlainObject(value) {
 function configsEqual(a, b) {
     return JSON.stringify(a) === JSON.stringify(b);
 }
+function driveLineFromText(text) {
+    const matchingLine = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.startsWith("[h2a "));
+    return matchingLine ?? (text.trim() ? text.trim() : undefined);
+}
+function hookPromptText(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const text = hookPromptText(item);
+            if (text)
+                return text;
+        }
+        return undefined;
+    }
+    if (!isPlainObject(value))
+        return undefined;
+    for (const key of ["prompt", "line", "message", "text", "input"]) {
+        const text = hookPromptText(value[key]);
+        if (text)
+            return text;
+    }
+    if (isPlainObject(value.params)) {
+        const text = hookPromptText(value.params);
+        if (text)
+            return text;
+    }
+    return undefined;
+}
+function driveLineFromHookInput(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        const promptText = hookPromptText(parsed);
+        if (promptText)
+            return driveLineFromText(promptText);
+    }
+    catch {
+        // Non-JSON hook payloads may already be the prompt text.
+    }
+    return driveLineFromText(raw);
+}
 function cmdHostSetup(flags, streams) {
     const host = flags.host;
     if (!host) {
@@ -2139,7 +2392,7 @@ function cmdHostPlugin(flags, streams) {
         const manifestPath = join(pluginDir, ".codex-plugin", "plugin.json");
         const marketplacePath = join(marketplaceDir, ".agents", "plugins", "marketplace.json");
         // The hooks.json is the same idempotent Claude-format merge as --write.
-        const hooksMerge = mergeStopHooksFile(hooksPath, render.record, flags.force === "true", streams);
+        const hooksMerge = mergeStopHooksFile(hooksPath, render.record, render.receive, flags.force === "true", streams);
         if (typeof hooksMerge === "number")
             return hooksMerge;
         // Manifests are stable identities — rewriting them is idempotent (same bytes).
@@ -2167,7 +2420,7 @@ function cmdHostPlugin(flags, streams) {
             manifest: manifestPath,
             hooks: hooksPath,
             mechanism: render.mechanism,
-            hook: "hooks.Stop",
+            hook: "hooks.Stop + hooks.UserPromptSubmit",
             // The trust step is surfaced, not silently dropped: codex cannot be
             // auto-trusted from outside, so run these to load the plugin.
             trust: codexPluginTrustCommands(marketplaceDir, H2A_CODEX_PLUGIN_NAME)
@@ -2187,7 +2440,7 @@ function cmdHostPlugin(flags, streams) {
             return 1;
         }
         const targetPath = flags.write;
-        const merge = mergeStopHooksFile(targetPath, render.record, flags.force === "true", streams);
+        const merge = mergeStopHooksFile(targetPath, render.record, render.receive, flags.force === "true", streams);
         if (typeof merge === "number")
             return merge;
         streams.stdout.write(`${JSON.stringify({
@@ -2195,7 +2448,7 @@ function cmdHostPlugin(flags, streams) {
             host: flags.host,
             written: targetPath,
             mechanism: render.mechanism,
-            hook: "hooks.Stop",
+            hook: "hooks.Stop + hooks.UserPromptSubmit",
             // codex loads hooks via a plugin (manifest → ./hooks/hooks.json); the
             // file written above is a valid codex hooks.json, but codex still
             // needs the manifest + trust. `--scaffold <dir>` does the full job;
@@ -2214,13 +2467,14 @@ function cmdHostPlugin(flags, streams) {
     return 0;
 }
 /**
- * Idempotently merge the h2a drumbeat-record `Stop` hook into a Claude-format
- * hooks file (claude/gemini `settings.json` or a codex `hooks.json`). Drops any
- * prior h2a Stop hook, appends the freshly-rendered one, preserves unrelated
- * keys/hooks. Returns an exit code on failure, or `undefined` on success.
+ * Idempotently merge the h2a drumbeat-record `Stop` hook and the drive receive
+ * `UserPromptSubmit` gate into a Claude-format hooks file (claude/gemini
+ * `settings.json` or a codex `hooks.json`). Drops prior h2a hooks, appends the
+ * freshly-rendered ones, and preserves unrelated keys/hooks. Returns an exit
+ * code on failure, or `undefined` on success.
  * DEC-102/103/104; reused by `--scaffold` (DEC-113).
  */
-function mergeStopHooksFile(targetPath, record, force, streams) {
+function mergeStopHooksFile(targetPath, record, receive, force, streams) {
     let existing = {};
     if (existsSync(targetPath)) {
         let raw;
@@ -2250,12 +2504,24 @@ function mergeStopHooksFile(targetPath, record, force, streams) {
     }
     const existingHooks = isPlainObject(existing.hooks) ? existing.hooks : {};
     const existingStop = Array.isArray(existingHooks.Stop) ? [...existingHooks.Stop] : [];
+    const existingUserPromptSubmit = Array.isArray(existingHooks.UserPromptSubmit)
+        ? [...existingHooks.UserPromptSubmit]
+        : [];
     // Idempotent: drop any prior h2a drumbeat-record Stop hook, then append ours.
     const withoutH2A = existingStop.filter((e) => !isH2ARecordHook(e));
     const mergedStop = [...withoutH2A, claudeStopHookEntry(record)];
+    const withoutDriveReceive = existingUserPromptSubmit.filter((e) => !isH2ADriveReceiveHook(e));
+    const mergedUserPromptSubmit = [
+        ...withoutDriveReceive,
+        claudeDriveReceiveHookEntry(receive)
+    ];
     const merged = {
         ...existing,
-        hooks: { ...existingHooks, Stop: mergedStop }
+        hooks: {
+            ...existingHooks,
+            Stop: mergedStop,
+            UserPromptSubmit: mergedUserPromptSubmit
+        }
     };
     try {
         const dir = dirname(targetPath);
@@ -3022,6 +3288,10 @@ export function runCli(argv = process.argv.slice(2), streams = {
         return cmdDeclareInteret(flags, streams);
     if (command === "conflict-posture")
         return cmdConflictPosture(flags, streams);
+    if (command === "dossier")
+        return cmdDossier(flags, streams);
+    if (command === "confiance")
+        return cmdConfiance(flags, streams);
     if (command === "attest-comprehension")
         return cmdAttestComprehension(flags, streams);
     if (command === "comprehension")
@@ -3044,8 +3314,16 @@ export function runCli(argv = process.argv.slice(2), streams = {
         return cmdInstallSkills(flags, streams);
     if (command === "deploy")
         return cmdDeploy(argv.slice(1), streams);
-    if (command === "drive")
+    if (command === "drive") {
+        if (argv[1] === "receive") {
+            return cmdDriveReceive(parseFlags(argv.slice(1)).flags, streams);
+        }
+        if (argv[1] === "serve") {
+            streams.stderr.write("h2a drive serve: async verb — run via the h2a binary, not the synchronous API.\n");
+            return 1;
+        }
         return cmdDrive(flags, streams);
+    }
     if (command === "remote") {
         // `remote serve`/`remote send` are async and dispatched from bin.ts; if we
         // reach here it is a misuse (e.g. via the sync runCli) or an unknown sub.