@cello-protocol/cli 0.0.234 → 0.0.235

package/dist/hermes/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../../src/hermes/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BjC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+uC9C,CAAC;AAEF,wEAAwE;AACxE,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqE9B,CAAC"}

package/dist/hermes/install-hermes.d.ts

@@ -0,0 +1,44 @@
+/**
+ * HERMES-001 — `cello bridge hermes`: wire the local CELLO daemon into a Hermes
+ * Agent installation.
+ *
+ * What it does (design: trustless-cello 2026-07-09_1915_hermes-agent-integration-plan.md §5):
+ *   1. Scaffolds the platform-adapter plugin into $HERMES_HOME/plugins/cello/
+ *      (plugin.yaml + __init__.py — a pure-stdlib Python IPC client, no subprocess).
+ *   2. Drops the cello-bridge-setup skill into $HERMES_HOME/skills/.
+ *   3. Binds the agent: writes CELLO_AGENT_NAME=<agent> into $HERMES_HOME/.env
+ *      (replace-or-append; every other line preserved byte-for-byte).
+ *   4. Registers through Hermes' OWN CLI surfaces — `hermes plugins enable cello` and
+ *      `hermes mcp add cello …` — never by hand-editing config.yaml, so Hermes owns
+ *      its config format.
+ *
+ * Never edits anything outside $HERMES_HOME. Idempotent: re-running upgrades the
+ * scaffolded files in place and keeps exactly one CELLO_AGENT_NAME line.
+ */
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export type ExecFn = (cmd: string, args: string[]) => Promise<ExecResult>;
+/** DOD-HERMES-4 — the two per-agent behaviour settings, and their defaults. */
+export declare const DELIVERY_MODES: readonly ["channel", "wake"];
+export declare const SESSION_SCOPES: readonly ["agent", "peer"];
+export declare const DEFAULT_DELIVERY_MODE: (typeof DELIVERY_MODES)[number];
+export declare const DEFAULT_SESSION_SCOPE: (typeof SESSION_SCOPES)[number];
+export interface InstallHermesOptions {
+    agentName: string;
+    /** Defaults to $HERMES_HOME, falling back to ~/.hermes. */
+    hermesHome?: string;
+    /** `channel` (default): CELLO behaves as a normal two-way channel. `wake`: notices only. */
+    deliveryMode?: string;
+    /** `agent` (default): one conversation per agent. `peer`: one per counterparty. */
+    sessionScope?: string;
+    /** Injectable for tests; defaults to a spawn-based runner. */
+    exec?: ExecFn;
+}
+export declare function installHermes(opts: InstallHermesOptions): Promise<{
+    exitCode: number;
+    output: string;
+}>;
+//# sourceMappingURL=install-hermes.d.ts.map

package/dist/hermes/install-hermes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-hermes.d.ts","sourceRoot":"","sources":["../../src/hermes/install-hermes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAE1E,+EAA+E;AAC/E,eAAO,MAAM,cAAc,8BAA+B,CAAC;AAC3D,eAAO,MAAM,cAAc,4BAA6B,CAAC;AACzD,eAAO,MAAM,qBAAqB,EAAE,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAa,CAAC;AAChF,eAAO,MAAM,qBAAqB,EAAE,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAW,CAAC;AAE9E,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAoDD,wBAAsB,aAAa,CACjC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA8H/C"}

package/dist/hermes/install-hermes.js

@@ -0,0 +1,172 @@
+/**
+ * HERMES-001 — `cello bridge hermes`: wire the local CELLO daemon into a Hermes
+ * Agent installation.
+ *
+ * What it does (design: trustless-cello 2026-07-09_1915_hermes-agent-integration-plan.md §5):
+ *   1. Scaffolds the platform-adapter plugin into $HERMES_HOME/plugins/cello/
+ *      (plugin.yaml + __init__.py — a pure-stdlib Python IPC client, no subprocess).
+ *   2. Drops the cello-bridge-setup skill into $HERMES_HOME/skills/.
+ *   3. Binds the agent: writes CELLO_AGENT_NAME=<agent> into $HERMES_HOME/.env
+ *      (replace-or-append; every other line preserved byte-for-byte).
+ *   4. Registers through Hermes' OWN CLI surfaces — `hermes plugins enable cello` and
+ *      `hermes mcp add cello …` — never by hand-editing config.yaml, so Hermes owns
+ *      its config format.
+ *
+ * Never edits anything outside $HERMES_HOME. Idempotent: re-running upgrades the
+ * scaffolded files in place and keeps exactly one CELLO_AGENT_NAME line.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { HERMES_PLUGIN_YAML, HERMES_PLUGIN_INIT_PY, HERMES_SKILL_MD } from "./assets.js";
+/** DOD-HERMES-4 — the two per-agent behaviour settings, and their defaults. */
+export const DELIVERY_MODES = ["channel", "wake"];
+export const SESSION_SCOPES = ["agent", "peer"];
+export const DEFAULT_DELIVERY_MODE = "channel";
+export const DEFAULT_SESSION_SCOPE = "agent";
+/** The two Hermes CLI registrations the installer performs (also printed as the
+ * manual fallback when the `hermes` binary cannot be run). */
+const HERMES_COMMANDS = [
+    ["plugins", "enable", "cello"],
+    ["mcp", "add", "cello", "--command", "npx", "--args", "--yes", "@cello-protocol/connect@latest"],
+];
+const defaultExec = (cmd, args) => new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
+    // `hermes mcp add` is interactive: on a re-run it first asks "... already exists.
+    // Overwrite? [y/N]" (default NO), then "Enable all N tools? [Y/n/select]". Feed a
+    // few "Y" lines so BOTH prompts are answered yes on the fresh AND the re-run path
+    // (extra lines are harmless — the child stops reading once satisfied). A closed
+    // stdin would read as EOF → "Cancelled." with exit 0, which is why installHermes
+    // also VERIFIES the registration against `hermes mcp list` rather than trusting
+    // the exit code.
+    child.stdin.write("Y\nY\nY\n");
+    child.stdin.end();
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d.toString("utf-8")));
+    child.stderr.on("data", (d) => (stderr += d.toString("utf-8")));
+    child.on("error", reject); // e.g. ENOENT — hermes not on PATH
+    child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+});
+/** Replace-or-append KEY=value in an env file, preserving every other line. */
+function upsertEnvLine(envPath, key, value) {
+    const line = `${key}=${value}`;
+    let lines = [];
+    if (existsSync(envPath)) {
+        lines = readFileSync(envPath, "utf-8").split("\n");
+    }
+    let replaced = false;
+    lines = lines.map((l) => {
+        if (l.startsWith(`${key}=`)) {
+            replaced = true;
+            return line;
+        }
+        return l;
+    });
+    if (!replaced) {
+        // Drop a single trailing empty line before appending so we don't grow blank gaps.
+        if (lines.length > 0 && lines[lines.length - 1] === "")
+            lines.pop();
+        lines.push(line);
+    }
+    writeFileSync(envPath, lines.join("\n") + (lines[lines.length - 1] === "" ? "" : "\n"));
+}
+export async function installHermes(opts) {
+    const agentName = (opts.agentName ?? "").trim();
+    if (!agentName) {
+        return {
+            exitCode: 1,
+            output: "Missing agent name. Usage: cello bridge hermes --agent <name> [--hermes-home <path>]\n" +
+                "The agent must be a local CELLO agent (see 'cello status' for the list).",
+        };
+    }
+    // Validate the modes BEFORE touching the filesystem. A typo must not be written into .env and
+    // discovered later as a gateway that refuses to start — reject it here, where the operator is
+    // still looking at the command they just typed.
+    const deliveryMode = (opts.deliveryMode ?? DEFAULT_DELIVERY_MODE).trim().toLowerCase();
+    const sessionScope = (opts.sessionScope ?? DEFAULT_SESSION_SCOPE).trim().toLowerCase();
+    for (const [flag, value, allowed] of [
+        ["--delivery-mode", deliveryMode, DELIVERY_MODES],
+        ["--session-scope", sessionScope, SESSION_SCOPES],
+    ]) {
+        if (!allowed.includes(value)) {
+            return {
+                exitCode: 1,
+                output: `Invalid ${flag} '${value}'. Expected one of: ${allowed.join(", ")}.\n` +
+                    (flag === "--delivery-mode"
+                        ? "  channel — CELLO behaves like a normal chat channel (default)\n" +
+                            "  wake    — content-free notices only; the agent reads and replies via cello_* tools"
+                        : "  agent   — one conversation per CELLO agent (default)\n" +
+                            "  peer    — one conversation per counterparty, for a support desk"),
+            };
+        }
+    }
+    const hermesHome = opts.hermesHome || process.env.HERMES_HOME || join(homedir(), ".hermes");
+    if (!existsSync(hermesHome)) {
+        return {
+            exitCode: 1,
+            output: `Hermes home not found at ${hermesHome}.\n` +
+                "Install Hermes Agent first (https://hermes-agent.nousresearch.com), or pass --hermes-home <path> " +
+                "if it lives elsewhere.",
+        };
+    }
+    const exec = opts.exec ?? defaultExec;
+    const out = [];
+    // 1. Plugin package
+    const pluginDir = join(hermesHome, "plugins", "cello");
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(join(pluginDir, "plugin.yaml"), HERMES_PLUGIN_YAML);
+    writeFileSync(join(pluginDir, "__init__.py"), HERMES_PLUGIN_INIT_PY);
+    out.push(`Wrote plugin: ${pluginDir}/{plugin.yaml,__init__.py}`);
+    // 2. Skill
+    const skillDir = join(hermesHome, "skills", "cello-bridge-setup");
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, "SKILL.md"), HERMES_SKILL_MD);
+    out.push(`Wrote skill:  ${skillDir}/SKILL.md`);
+    // 3. Agent binding + behaviour settings. All three are written on every run, so re-running the
+    //    installer without a flag RESETS that flag to its default rather than silently inheriting
+    //    a value the operator can no longer see in the command they typed.
+    const envPath = join(hermesHome, ".env");
+    upsertEnvLine(envPath, "CELLO_AGENT_NAME", agentName);
+    upsertEnvLine(envPath, "CELLO_DELIVERY_MODE", deliveryMode);
+    upsertEnvLine(envPath, "CELLO_SESSION_SCOPE", sessionScope);
+    out.push(`Bound agent:  CELLO_AGENT_NAME=${agentName} (${envPath})`);
+    out.push(`Delivery:     CELLO_DELIVERY_MODE=${deliveryMode}`);
+    out.push(`Scope:        CELLO_SESSION_SCOPE=${sessionScope}`);
+    // 4. Register through Hermes' own CLI. A failure here is loud: the files are in
+    // place, so we print exactly what remains to be run by hand.
+    for (const args of HERMES_COMMANDS) {
+        let result;
+        try {
+            result = await exec("hermes", [...args]);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            out.push(`\nCould not run the 'hermes' CLI (${msg}).`, "The CELLO files are installed, but Hermes still needs these two commands run manually:", "  hermes plugins enable cello", "  hermes mcp add cello --command npx --args --yes @cello-protocol/connect@latest", "Then restart the gateway: hermes gateway restart");
+            return { exitCode: 1, output: out.join("\n") };
+        }
+        if (result.code !== 0) {
+            out.push(`\n'hermes ${args.join(" ")}' failed (exit ${result.code}):`, (result.stderr || result.stdout).trim(), "Fix the error above and re-run 'cello bridge hermes' (it is idempotent).");
+            return { exitCode: 1, output: out.join("\n") };
+        }
+        out.push(`Ran:          hermes ${args.join(" ")}`);
+    }
+    // Verify the MCP registration actually landed: `hermes mcp add` can print
+    // "Cancelled." and still exit 0 (e.g. when its interactive prompt hits EOF),
+    // so the exit code alone proves nothing.
+    try {
+        const list = await exec("hermes", ["mcp", "list"]);
+        if (!list.stdout.includes("cello")) {
+            out.push("", "'hermes mcp add' reported success but 'hermes mcp list' does not show a 'cello' server.", "Run this manually and answer Y at the tool prompt:", "  hermes mcp add cello --command npx --args --yes @cello-protocol/connect@latest");
+            return { exitCode: 1, output: out.join("\n") };
+        }
+    }
+    catch {
+        // hermes CLI vanished between calls — vanishingly unlikely; the add above succeeded.
+    }
+    out.push("Verified:     'cello' present in hermes mcp list");
+    out.push("", "CELLO bridge installed. Next step: restart the gateway so Hermes loads the plugin:", "  hermes gateway restart", "Then verify from a Hermes chat by calling the cello_status MCP tool.");
+    return { exitCode: 0, output: out.join("\n") };
+}
+//# sourceMappingURL=install-hermes.js.map

package/dist/hermes/install-hermes.js.map

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

package/dist/json-out.d.ts

@@ -0,0 +1,41 @@
+/**
+ * DOD-CLI-PARITY-1 §3 — the bash-adapter contract.
+ *
+ * This is what makes `cello` a real programmatic interface rather than a human-only UI: any
+ * bash-capable agent can drive a CELLO node with `cello <cmd> | jq` + `$?`, with no MCP dependency.
+ *
+ * The contract, applied identically by every parity command:
+ *  - stdout = the daemon's IPC response as JSON, one object per invocation (compact by default —
+ *    scripts and agents are the first-class consumer; `--pretty` for humans).
+ *  - exit 0 when the response is ok:true; non-zero otherwise.
+ *  - a FAILED response goes to stderr, VERBATIM — every field the daemon sent (reason, guidance,
+ *    and extras like the read-before-write cursor) survives untouched, and stdout stays EMPTY so a
+ *    piping script can never mistake an error body for a result.
+ *
+ * The verbatim rule is the DOD-SENDRAW-1 / DOD-LOGOUT-WAIT-1 lesson at the CLI surface: report the
+ * outcome, never the intent. A command that reports success for a failed IPC call is a lie, and
+ * absence of ok:true is NOT evidence of success — an unrecognized shape fails loud rather than
+ * being optimistically passed off as a result.
+ */
+export interface EmittedOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface EmitOptions {
+    /** Human-readable indented JSON. JSON stays the default so scripts come first. */
+    pretty?: boolean;
+}
+/**
+ * Turn a daemon IPC response into the (stdout, stderr, exitCode) triple the contract demands.
+ * The response is passed through UNMODIFIED in both directions — this function decides the stream
+ * and the exit code, and is never allowed to rewrite, summarize, or invent the body.
+ */
+export declare function emitIpcResult(result: Record<string, unknown>, opts?: EmitOptions): EmittedOutput;
+/**
+ * A transport/daemon-level failure (socket unreachable, daemon not running, thrown error) — still
+ * a structured, machine-parseable JSON error on stderr, so a bash agent branches on the same shape
+ * whether the daemon rejected the call or never received it.
+ */
+export declare function emitTransportError(reason: string, guidance: string, opts?: EmitOptions): EmittedOutput;
+//# sourceMappingURL=json-out.d.ts.map

package/dist/json-out.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-out.d.ts","sourceRoot":"","sources":["../src/json-out.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,GAAE,WAAgB,GACrB,aAAa,CAkBf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,aAAa,CAM1G"}

package/dist/json-out.js

@@ -0,0 +1,59 @@
+/**
+ * DOD-CLI-PARITY-1 §3 — the bash-adapter contract.
+ *
+ * This is what makes `cello` a real programmatic interface rather than a human-only UI: any
+ * bash-capable agent can drive a CELLO node with `cello <cmd> | jq` + `$?`, with no MCP dependency.
+ *
+ * The contract, applied identically by every parity command:
+ *  - stdout = the daemon's IPC response as JSON, one object per invocation (compact by default —
+ *    scripts and agents are the first-class consumer; `--pretty` for humans).
+ *  - exit 0 when the response is ok:true; non-zero otherwise.
+ *  - a FAILED response goes to stderr, VERBATIM — every field the daemon sent (reason, guidance,
+ *    and extras like the read-before-write cursor) survives untouched, and stdout stays EMPTY so a
+ *    piping script can never mistake an error body for a result.
+ *
+ * The verbatim rule is the DOD-SENDRAW-1 / DOD-LOGOUT-WAIT-1 lesson at the CLI surface: report the
+ * outcome, never the intent. A command that reports success for a failed IPC call is a lie, and
+ * absence of ok:true is NOT evidence of success — an unrecognized shape fails loud rather than
+ * being optimistically passed off as a result.
+ */
+function render(value, pretty) {
+    return pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+}
+/**
+ * Turn a daemon IPC response into the (stdout, stderr, exitCode) triple the contract demands.
+ * The response is passed through UNMODIFIED in both directions — this function decides the stream
+ * and the exit code, and is never allowed to rewrite, summarize, or invent the body.
+ */
+export function emitIpcResult(result, opts = {}) {
+    // The exit code keys on `ok === false`, not on `ok === true`, because the daemon has TWO response
+    // conventions and only one of them carries `ok`:
+    //   (a) ok-bearing  — { ok: true, … } / { ok: false, reason, guidance }
+    //   (b) payload-only — a bare result with NO `ok` at all: cello_list_agents returns { agents: [] },
+    //       cello_await_session returns { type: "timeout" | … }.
+    // `ok: false` is the daemon's ONE failure convention; a genuine transport/daemon failure THROWS
+    // and is handled by the caller as a transport error. So a payload without `ok` is a result, and
+    // routing it to stderr would report working commands as broken — `cello agents` would exit 1 on
+    // success.
+    //
+    // This does NOT weaken the no-fabricated-success rule: we never synthesize an ok:true, never
+    // rewrite a body, and never swallow an ok:false. We report exactly what the daemon said.
+    const failed = result.ok === false;
+    if (failed) {
+        return { stdout: "", stderr: render(result, opts.pretty), exitCode: 1 };
+    }
+    return { stdout: render(result, opts.pretty), stderr: "", exitCode: 0 };
+}
+/**
+ * A transport/daemon-level failure (socket unreachable, daemon not running, thrown error) — still
+ * a structured, machine-parseable JSON error on stderr, so a bash agent branches on the same shape
+ * whether the daemon rejected the call or never received it.
+ */
+export function emitTransportError(reason, guidance, opts = {}) {
+    return {
+        stdout: "",
+        stderr: render({ ok: false, reason, guidance }, opts.pretty),
+        exitCode: 1,
+    };
+}
+//# sourceMappingURL=json-out.js.map

package/dist/json-out.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-out.js","sourceRoot":"","sources":["../src/json-out.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAaH,SAAS,MAAM,CAAC,KAAc,EAAE,MAA2B;IACzD,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,MAA+B,EAC/B,OAAoB,EAAE;IAEtB,kGAAkG;IAClG,iDAAiD;IACjD,wEAAwE;IACxE,oGAAoG;IACpG,6DAA6D;IAC7D,gGAAgG;IAChG,gGAAgG;IAChG,gGAAgG;IAChG,WAAW;IACX,EAAE;IACF,6FAA6F;IAC7F,yFAAyF;IACzF,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,KAAK,KAAK,CAAC;IACnC,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AAC1E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,QAAgB,EAAE,OAAoB,EAAE;IACzF,OAAO;QACL,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC;QAC5D,QAAQ,EAAE,CAAC;KACZ,CAAC;AACJ,CAAC"}