@cello-protocol/cli 0.0.306 → 0.0.308

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (234) hide show
  1. package/.claude-plugin/marketplace.json +15 -0
  2. package/README.md +107 -0
  3. package/dist/cli.d.ts +2 -0
  4. package/dist/cli.js +602 -0
  5. package/dist/daemon/account-page-assets.d.ts +4 -0
  6. package/dist/daemon/account-page-assets.js +160 -0
  7. package/dist/daemon/account-page.d.ts +14 -0
  8. package/dist/daemon/account-page.js +104 -0
  9. package/dist/daemon/address.d.ts +10 -0
  10. package/dist/daemon/address.js +34 -0
  11. package/dist/daemon/away.d.ts +31 -0
  12. package/dist/daemon/away.js +65 -0
  13. package/dist/daemon/channel-store.d.ts +112 -0
  14. package/dist/daemon/channel-store.js +284 -0
  15. package/dist/daemon/channels.d.ts +46 -0
  16. package/dist/daemon/channels.js +1049 -0
  17. package/dist/daemon/contacts.d.ts +26 -0
  18. package/dist/daemon/contacts.js +74 -0
  19. package/dist/daemon/engine.d.ts +82 -0
  20. package/dist/daemon/engine.js +2882 -0
  21. package/dist/daemon/errors.d.ts +5 -0
  22. package/dist/daemon/errors.js +16 -0
  23. package/dist/daemon/governance.d.ts +66 -0
  24. package/dist/daemon/governance.js +514 -0
  25. package/dist/daemon/guards.d.ts +36 -0
  26. package/dist/daemon/guards.js +140 -0
  27. package/dist/daemon/issuer-client.d.ts +56 -0
  28. package/dist/daemon/issuer-client.js +143 -0
  29. package/dist/daemon/link.d.ts +30 -0
  30. package/dist/daemon/link.js +191 -0
  31. package/dist/daemon/log.d.ts +1 -0
  32. package/dist/daemon/log.js +4 -0
  33. package/dist/daemon/main.d.ts +1 -0
  34. package/dist/daemon/main.js +513 -0
  35. package/dist/daemon/paths.d.ts +6 -0
  36. package/dist/daemon/paths.js +21 -0
  37. package/dist/daemon/pii.d.ts +24 -0
  38. package/dist/daemon/pii.js +147 -0
  39. package/dist/daemon/policy-cadence.d.ts +33 -0
  40. package/dist/daemon/policy-cadence.js +59 -0
  41. package/dist/daemon/policy-proposals.d.ts +41 -0
  42. package/dist/daemon/policy-proposals.js +83 -0
  43. package/dist/daemon/policy-store.d.ts +47 -0
  44. package/dist/daemon/policy-store.js +144 -0
  45. package/dist/daemon/presented.d.ts +36 -0
  46. package/dist/daemon/presented.js +94 -0
  47. package/dist/daemon/rate-limit.d.ts +17 -0
  48. package/dist/daemon/rate-limit.js +44 -0
  49. package/dist/daemon/reach.d.ts +62 -0
  50. package/dist/daemon/reach.js +204 -0
  51. package/dist/daemon/screening.d.ts +97 -0
  52. package/dist/daemon/screening.js +362 -0
  53. package/dist/daemon/settings.d.ts +125 -0
  54. package/dist/daemon/settings.js +73 -0
  55. package/dist/daemon/signal-rules.d.ts +55 -0
  56. package/dist/daemon/signal-rules.js +127 -0
  57. package/dist/daemon/signal-store.d.ts +53 -0
  58. package/dist/daemon/signal-store.js +114 -0
  59. package/dist/daemon/store.d.ts +189 -0
  60. package/dist/daemon/store.js +477 -0
  61. package/dist/daemon/tiers.d.ts +14 -0
  62. package/dist/daemon/tiers.js +9 -0
  63. package/dist/daemon/wallet.d.ts +73 -0
  64. package/dist/daemon/wallet.js +429 -0
  65. package/dist/daemon/who-label.d.ts +3 -0
  66. package/dist/daemon/who-label.js +11 -0
  67. package/dist/guidance.d.ts +39 -0
  68. package/dist/guidance.js +98 -0
  69. package/dist/hermes-bridge.d.ts +34 -0
  70. package/dist/hermes-bridge.js +223 -0
  71. package/dist/install-mcp.d.ts +6 -0
  72. package/dist/install-mcp.js +77 -0
  73. package/dist/ipc/client.d.ts +18 -0
  74. package/dist/ipc/client.js +107 -0
  75. package/dist/ipc/operations.d.ts +30 -0
  76. package/dist/ipc/operations.js +846 -0
  77. package/dist/ipc/protocol.d.ts +21 -0
  78. package/dist/ipc/protocol.js +1 -0
  79. package/dist/issuer-list-sign.d.ts +12 -0
  80. package/dist/issuer-list-sign.js +43 -0
  81. package/dist/local-operations.d.ts +2 -0
  82. package/dist/local-operations.js +73 -0
  83. package/dist/mcp-tools.d.ts +14 -0
  84. package/dist/mcp-tools.js +45 -0
  85. package/dist/mcp.d.ts +2 -0
  86. package/dist/mcp.js +160 -0
  87. package/dist/protocol/aead.d.ts +4 -0
  88. package/dist/protocol/aead.js +35 -0
  89. package/dist/protocol/cbor.d.ts +40 -0
  90. package/dist/protocol/cbor.js +106 -0
  91. package/dist/protocol/chain.d.ts +44 -0
  92. package/dist/protocol/chain.js +126 -0
  93. package/dist/protocol/channel.d.ts +153 -0
  94. package/dist/protocol/channel.js +298 -0
  95. package/dist/protocol/encode.d.ts +6 -0
  96. package/dist/protocol/encode.js +21 -0
  97. package/dist/protocol/identity.d.ts +27 -0
  98. package/dist/protocol/identity.js +94 -0
  99. package/dist/protocol/issuer-list.d.ts +56 -0
  100. package/dist/protocol/issuer-list.js +193 -0
  101. package/dist/protocol/issuer-roots.d.ts +6 -0
  102. package/dist/protocol/issuer-roots.js +10 -0
  103. package/dist/protocol/key-agreement.d.ts +20 -0
  104. package/dist/protocol/key-agreement.js +88 -0
  105. package/dist/protocol/merkle.d.ts +16 -0
  106. package/dist/protocol/merkle.js +166 -0
  107. package/dist/protocol/ml-dsa.d.ts +28 -0
  108. package/dist/protocol/ml-dsa.js +58 -0
  109. package/dist/protocol/ml-kem.d.ts +14 -0
  110. package/dist/protocol/ml-kem.js +57 -0
  111. package/dist/protocol/pq-errors.d.ts +9 -0
  112. package/dist/protocol/pq-errors.js +23 -0
  113. package/dist/protocol/pq-warnings.d.ts +1 -0
  114. package/dist/protocol/pq-warnings.js +18 -0
  115. package/dist/protocol/presented-signals.d.ts +17 -0
  116. package/dist/protocol/presented-signals.js +92 -0
  117. package/dist/protocol/salt.d.ts +5 -0
  118. package/dist/protocol/salt.js +47 -0
  119. package/dist/protocol/seal.d.ts +58 -0
  120. package/dist/protocol/seal.js +220 -0
  121. package/dist/protocol/signal.d.ts +54 -0
  122. package/dist/protocol/signal.js +266 -0
  123. package/dist/protocol/status.d.ts +41 -0
  124. package/dist/protocol/status.js +64 -0
  125. package/dist/protocol/structures.d.ts +359 -0
  126. package/dist/protocol/structures.js +296 -0
  127. package/dist/protocol/transcript.d.ts +61 -0
  128. package/dist/protocol/transcript.js +319 -0
  129. package/dist/protocol/wire.d.ts +212 -0
  130. package/dist/protocol/wire.js +161 -0
  131. package/dist/require-node.d.ts +1 -0
  132. package/dist/require-node.js +10 -0
  133. package/dist/screener/affordance.d.ts +1 -0
  134. package/dist/screener/affordance.js +2 -0
  135. package/dist/screener/classifier-selfcheck.d.ts +29 -0
  136. package/dist/screener/classifier-selfcheck.js +56 -0
  137. package/dist/screener/exfil.d.ts +11 -0
  138. package/dist/screener/exfil.js +45 -0
  139. package/dist/screener/gitleaks-rules.d.ts +9 -0
  140. package/dist/screener/gitleaks-rules.js +226 -0
  141. package/dist/screener/inbound.d.ts +25 -0
  142. package/dist/screener/inbound.js +102 -0
  143. package/dist/screener/injection-classifier-onnx.d.ts +20 -0
  144. package/dist/screener/injection-classifier-onnx.js +89 -0
  145. package/dist/screener/injection-classifier-wasm.d.ts +2 -0
  146. package/dist/screener/injection-classifier-wasm.js +97 -0
  147. package/dist/screener/injection-patterns.d.ts +8 -0
  148. package/dist/screener/injection-patterns.js +48 -0
  149. package/dist/screener/injection-windows.d.ts +9 -0
  150. package/dist/screener/injection-windows.js +37 -0
  151. package/dist/screener/language.d.ts +15 -0
  152. package/dist/screener/language.js +71 -0
  153. package/dist/screener/linear-regex.d.ts +8 -0
  154. package/dist/screener/linear-regex.js +27 -0
  155. package/dist/screener/model-installer.d.ts +14 -0
  156. package/dist/screener/model-installer.js +61 -0
  157. package/dist/screener/outbound.d.ts +19 -0
  158. package/dist/screener/outbound.js +62 -0
  159. package/dist/screener/sanitize.d.ts +44 -0
  160. package/dist/screener/sanitize.js +361 -0
  161. package/dist/screener/scan-variants.d.ts +5 -0
  162. package/dist/screener/scan-variants.js +146 -0
  163. package/dist/screener/screener-model-manifest.d.ts +16 -0
  164. package/dist/screener/screener-model-manifest.js +20 -0
  165. package/dist/screener/screener-state.d.ts +29 -0
  166. package/dist/screener/screener-state.js +119 -0
  167. package/dist/screener/secrets.d.ts +18 -0
  168. package/dist/screener/secrets.js +84 -0
  169. package/dist/screener/worker.d.ts +6 -0
  170. package/dist/screener/worker.js +83 -0
  171. package/dist/setup.d.ts +9 -0
  172. package/dist/setup.js +259 -0
  173. package/dist/shipped-issuer-list.d.ts +1 -0
  174. package/dist/shipped-issuer-list.js +3 -0
  175. package/dist/signals-text.d.ts +46 -0
  176. package/dist/signals-text.js +81 -0
  177. package/dist/verify-seal.d.ts +9 -0
  178. package/dist/verify-seal.js +30 -0
  179. package/hermes/plugin/__init__.py +1066 -0
  180. package/hermes/plugin/plugin.yaml +30 -0
  181. package/hermes/skills/cello-bridge-setup/SKILL.md +48 -0
  182. package/hermes/skills/cello-policy/SKILL.md +44 -0
  183. package/package.json +48 -16
  184. package/plugins/cello/.claude-plugin/plugin.json +19 -0
  185. package/plugins/cello/.mcp.json +7 -0
  186. package/plugins/cello/skills/cello/SKILL.md +117 -0
  187. package/dist/arg-parse.d.ts +0 -19
  188. package/dist/arg-parse.d.ts.map +0 -1
  189. package/dist/arg-parse.js +0 -29
  190. package/dist/arg-parse.js.map +0 -1
  191. package/dist/bin/cello.d.ts +0 -15
  192. package/dist/bin/cello.d.ts.map +0 -1
  193. package/dist/bin/cello.js +0 -110
  194. package/dist/bin/cello.js.map +0 -1
  195. package/dist/cli-args.d.ts +0 -62
  196. package/dist/cli-args.d.ts.map +0 -1
  197. package/dist/cli-args.js +0 -129
  198. package/dist/cli-args.js.map +0 -1
  199. package/dist/commands.d.ts +0 -196
  200. package/dist/commands.d.ts.map +0 -1
  201. package/dist/commands.js +0 -1544
  202. package/dist/commands.js.map +0 -1
  203. package/dist/hermes/assets.d.ts +0 -41
  204. package/dist/hermes/assets.d.ts.map +0 -1
  205. package/dist/hermes/assets.js +0 -2281
  206. package/dist/hermes/assets.js.map +0 -1
  207. package/dist/hermes/install-hermes.d.ts +0 -50
  208. package/dist/hermes/install-hermes.d.ts.map +0 -1
  209. package/dist/hermes/install-hermes.js +0 -232
  210. package/dist/hermes/install-hermes.js.map +0 -1
  211. package/dist/json-out.d.ts +0 -41
  212. package/dist/json-out.d.ts.map +0 -1
  213. package/dist/json-out.js +0 -59
  214. package/dist/json-out.js.map +0 -1
  215. package/dist/node-runtime-guard-init.d.ts +0 -6
  216. package/dist/node-runtime-guard-init.d.ts.map +0 -1
  217. package/dist/node-runtime-guard-init.js +0 -7
  218. package/dist/node-runtime-guard-init.js.map +0 -1
  219. package/dist/node-runtime-guard.d.ts +0 -48
  220. package/dist/node-runtime-guard.d.ts.map +0 -1
  221. package/dist/node-runtime-guard.js +0 -79
  222. package/dist/node-runtime-guard.js.map +0 -1
  223. package/dist/parity-commands.d.ts +0 -427
  224. package/dist/parity-commands.d.ts.map +0 -1
  225. package/dist/parity-commands.js +0 -953
  226. package/dist/parity-commands.js.map +0 -1
  227. package/dist/registry.d.ts +0 -120
  228. package/dist/registry.d.ts.map +0 -1
  229. package/dist/registry.js +0 -2169
  230. package/dist/registry.js.map +0 -1
  231. package/dist/screener-commands.d.ts +0 -85
  232. package/dist/screener-commands.d.ts.map +0 -1
  233. package/dist/screener-commands.js +0 -313
  234. package/dist/screener-commands.js.map +0 -1
@@ -0,0 +1,223 @@
1
+ // cello bridge: wires this machine's daemon into a Hermes home, through Hermes' own commands. A person runs it at a terminal.
2
+ // It's safe to run again, and it has to be after an upgrade, because Hermes keeps a copy of the plugin.
3
+ import { spawn } from "node:child_process";
4
+ import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
5
+ import { homedir } from "node:os";
6
+ import { extname, join } from "node:path";
7
+ import { fileURLToPath } from "node:url";
8
+ import { celloHome, logPath } from "./daemon/paths.js";
9
+ // Both doors to an agent use this name. A hold is per agent, so a whole machine can share it.
10
+ export const BRIDGE_CALLER = "hermes";
11
+ export const SESSION_SCOPES = ["agent", "peer"];
12
+ const CHANNEL_NOTIFICATIONS = ["on", "off"];
13
+ const SAFE_SESSION_ID = /^[A-Za-z0-9+/=_.:@-]{1,120}$/;
14
+ // All a public agent's model can reach. It talks to strangers, so it can't change settings or make agents.
15
+ export const PUBLIC_TOOLS = ["cello_receive", "cello_send", "cello_sessions", "cello_inbox", "cello_close_session", "cello_contacts", "cello_channel_read", "cello_channels", "cello_status"];
16
+ const SKILLS = ["cello-bridge-setup", "cello-policy"];
17
+ // What v1's install wrote, which this one no longer reads.
18
+ const RETIRED_ENV = ["CELLO_DELIVERY_MODE", "CELLO_DIR"];
19
+ const runHermes = (command, args, hermesHome) => new Promise((resolve, reject) => {
20
+ const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"], env: { ...process.env, HERMES_HOME: hermesHome } });
21
+ // hermes mcp add asks to overwrite on a re-run, then asks about its tools. A closed stdin reads as "Cancelled." with exit 0.
22
+ child.stdin.end("Y\nY\nY\n");
23
+ let stdout = "";
24
+ let stderr = "";
25
+ child.stdout.on("data", (d) => { stdout += d.toString(); });
26
+ child.stderr.on("data", (d) => { stderr += d.toString(); });
27
+ child.on("error", reject);
28
+ child.on("close", (code) => { resolve({ code: code ?? 1, stdout, stderr }); });
29
+ });
30
+ // This file is one folder below hermes/ whether it's running from src or dist.
31
+ const assetDir = () => fileURLToPath(new URL("../hermes/", import.meta.url));
32
+ const mcpEntry = () => fileURLToPath(new URL(`./mcp${extname(fileURLToPath(import.meta.url))}`, import.meta.url));
33
+ const daemonEntry = () => fileURLToPath(new URL(`./daemon/main${extname(fileURLToPath(import.meta.url))}`, import.meta.url));
34
+ function withEnv(existing, set, drop) {
35
+ const keyOf = (line) => line.split("=", 1)[0];
36
+ const lines = existing.split("\n").filter((line) => !drop.includes(keyOf(line)));
37
+ while (lines.at(-1) === "")
38
+ lines.pop();
39
+ for (const [key, value] of Object.entries(set)) {
40
+ const at = lines.findIndex((line) => keyOf(line) === key);
41
+ if (at >= 0)
42
+ lines[at] = `${key}=${value}`;
43
+ else
44
+ lines.push(`${key}=${value}`);
45
+ }
46
+ return `${lines.join("\n")}\n`;
47
+ }
48
+ // --landing-session takes a session id, or one of these words, as v1's did.
49
+ // current: the Hermes session this command runs in, so an agent can say "send my notifications here".
50
+ // default: back to the agent's own CELLO session.
51
+ function resolveLanding(value) {
52
+ const raw = value?.trim();
53
+ if (raw === undefined || raw === "")
54
+ return { landing: undefined };
55
+ if (raw.toLowerCase() === "default")
56
+ return { landing: null };
57
+ if (raw.toLowerCase() === "current") {
58
+ const current = (process.env["HERMES_SESSION_ID"] ?? "").trim();
59
+ if (!current)
60
+ return { landing: undefined, error: "--landing-session current needs HERMES_SESSION_ID, which Hermes sets in a session's commands. Run it from inside the Hermes session you mean, or pass that session's id." };
61
+ return SAFE_SESSION_ID.test(current) ? { landing: current } : { landing: undefined, error: `HERMES_SESSION_ID '${current}' isn't a session id.` };
62
+ }
63
+ return SAFE_SESSION_ID.test(raw) ? { landing: raw } : { landing: undefined, error: `--landing-session '${raw}' isn't a session id.` };
64
+ }
65
+ const landingFileOf = (hermesHome) => join(hermesHome, "cello", "landing-session.json");
66
+ // The one bridge setting an agent may change itself: where its own notifications land. It writes only the landing file, which the
67
+ // plugin reads on every notification, so nothing restarts. Everything else about the bridge still takes a person.
68
+ export function setLanding(options) {
69
+ const hermesHome = options.hermesHome || process.env["HERMES_HOME"] || join(homedir(), ".hermes");
70
+ const envPath = join(hermesHome, ".env");
71
+ if (!existsSync(envPath))
72
+ return { ok: false, output: `There's no bridge in ${hermesHome} yet. A person sets it up first with cello bridge hermes.` };
73
+ const bridged = readFileSync(envPath, "utf8").split("\n").find((line) => line.startsWith("CELLO_AGENT_NAME="))?.slice("CELLO_AGENT_NAME=".length);
74
+ // An agent moves its own notifications, never another profile's.
75
+ if (bridged !== options.agent.trim())
76
+ return { ok: false, output: `${hermesHome} is bridged to ${bridged ?? "no agent"}, not ${options.agent}. Nothing changed.` };
77
+ if (readFileSync(envPath, "utf8").split("\n").includes("CELLO_SESSION_SCOPE=peer"))
78
+ return { ok: false, output: "This agent gives each caller their own session, so there's no one landing session to move. Nothing changed." };
79
+ const { landing, error } = resolveLanding(options.landingSession);
80
+ if (error)
81
+ return { ok: false, output: error };
82
+ const file = landingFileOf(hermesHome);
83
+ mkdirSync(join(hermesHome, "cello"), { recursive: true });
84
+ // A null says default on purpose, so an older CELLO_LANDING_SESSION in .env doesn't take over.
85
+ writeFileSync(file, `${JSON.stringify({ session_id: landing ?? null })}\n`);
86
+ return { ok: true, output: landing ? `${options.agent}'s notifications now land in session ${landing}, from the next one.` : `${options.agent}'s notifications go back to its own CELLO session, from the next one.` };
87
+ }
88
+ export async function installBridge(options) {
89
+ const refuse = (output) => ({ ok: false, output });
90
+ const agent = options.agent.trim();
91
+ if (!/^[^\s=]+$/.test(agent))
92
+ return refuse(`'${agent}' can't be an agent's name here.`);
93
+ const hermesHome = options.hermesHome || process.env["HERMES_HOME"] || join(homedir(), ".hermes");
94
+ if (!existsSync(hermesHome))
95
+ return refuse(`There's no Hermes home at ${hermesHome}. Install Hermes first, or pass --hermes-home.`);
96
+ const envPath = join(hermesHome, ".env");
97
+ const hermesEnv = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
98
+ // This has to be re-run after every upgrade, and forgetting a flag then mustn't open a public agent to strangers. Only --not-public ends it.
99
+ const wasPublic = hermesEnv.split("\n").includes("CELLO_PUBLIC=1");
100
+ if (options.public && options.notPublic)
101
+ return refuse("--public and --not-public can't go together.");
102
+ const isPublic = options.public || (wasPublic && !options.notPublic);
103
+ const allowInitiate = options.allowInitiate || (isPublic && !options.notPublic && hermesEnv.split("\n").includes("CELLO_ALLOW_INITIATE=1"));
104
+ const scope = options.sessionScope ?? (isPublic ? "peer" : "agent");
105
+ if (!SESSION_SCOPES.includes(scope))
106
+ return refuse(`--session-scope must be one of ${SESSION_SCOPES.join(", ")}, not '${scope}'.`);
107
+ if (isPublic && scope !== "peer")
108
+ return refuse("A public agent needs --session-scope peer, or callers would share one conversation.");
109
+ const channels = options.channelNotifications ?? "on";
110
+ if (!CHANNEL_NOTIFICATIONS.includes(channels))
111
+ return refuse(`--channel-notifications must be one of ${CHANNEL_NOTIFICATIONS.join(", ")}, not '${channels}'.`);
112
+ if (options.allowInitiate && !isPublic)
113
+ return refuse("--allow-initiate only means something with --public.");
114
+ const resolved = resolveLanding(options.landingSession);
115
+ if (resolved.error)
116
+ return refuse(resolved.error);
117
+ if (resolved.landing && scope === "peer")
118
+ return refuse("--landing-session only means something with --session-scope agent: under peer each caller has their own session.");
119
+ const landing = resolved.landing ?? undefined;
120
+ // Strangers' text goes straight to this agent's model, so a public agent doesn't start on the rules alone.
121
+ if (isPublic && !await options.modelReady())
122
+ return refuse("Nothing was changed. A public agent needs the screening model, and it isn't installed here. Run: cello screener install");
123
+ const tools = isPublic ? [...PUBLIC_TOOLS, ...(allowInitiate ? ["cello_initiate_session"] : [])] : undefined;
124
+ const settings = {
125
+ ...(isPublic ? { CELLO_PUBLIC: "1" } : {}),
126
+ ...(allowInitiate ? { CELLO_ALLOW_INITIATE: "1" } : {}),
127
+ ...(tools ? { CELLO_TOOLS: tools.join(",") } : {}),
128
+ CELLO_AGENT_NAME: agent,
129
+ CELLO_CALLER: BRIDGE_CALLER,
130
+ CELLO_SESSION_SCOPE: scope,
131
+ CELLO_CHANNEL_NOTIFICATIONS: channels,
132
+ ...(process.env["CELLO_HOME"] ? { CELLO_HOME: celloHome() } : {}),
133
+ ...(landing ? { CELLO_LANDING_SESSION: landing } : {}),
134
+ };
135
+ const wanted = withEnv(hermesEnv, settings, [...RETIRED_ENV, ...(landing ? [] : ["CELLO_LANDING_SESSION"]), ...(isPublic ? [] : ["CELLO_PUBLIC", "CELLO_TOOLS"]), ...(allowInitiate ? [] : ["CELLO_ALLOW_INITIATE"])]);
136
+ const envNeedsWriting = wanted !== hermesEnv;
137
+ if (envNeedsWriting) {
138
+ // Checked before anything is written. A hardened host keeps this file read-only, and half an install looks like a failed one.
139
+ try {
140
+ accessSync(existsSync(envPath) ? envPath : hermesHome, constants.W_OK);
141
+ }
142
+ catch {
143
+ return refuse(`Nothing was changed. ${envPath} is read-only, and it needs these lines:\n${Object.entries(settings).map(([k, v]) => ` ${k}=${v}`).join("\n")}\nUnlock it, run this again, then lock it.`);
144
+ }
145
+ }
146
+ const out = [];
147
+ const pluginDir = join(hermesHome, "plugins", "cello");
148
+ mkdirSync(pluginDir, { recursive: true });
149
+ for (const file of ["plugin.yaml", "__init__.py"])
150
+ copyFileSync(join(assetDir(), "plugin", file), join(pluginDir, file));
151
+ out.push(`Plugin: ${pluginDir}`);
152
+ for (const skill of SKILLS) {
153
+ const dir = join(hermesHome, "skills", skill);
154
+ mkdirSync(dir, { recursive: true });
155
+ copyFileSync(join(assetDir(), "skills", skill, "SKILL.md"), join(dir, "SKILL.md"));
156
+ out.push(`Skill: ${dir}`);
157
+ }
158
+ if (envNeedsWriting)
159
+ writeFileSync(envPath, wanted, { mode: 0o600 });
160
+ out.push(`Agent: ${agent}, scope ${scope}, caller ${BRIDGE_CALLER}${landing ? `, landing session ${landing}` : ""}`);
161
+ const landingFile = landingFileOf(hermesHome);
162
+ if (landing) {
163
+ mkdirSync(join(hermesHome, "cello"), { recursive: true });
164
+ writeFileSync(landingFile, `${JSON.stringify({ session_id: landing })}\n`);
165
+ }
166
+ else {
167
+ rmSync(landingFile, { force: true });
168
+ }
169
+ // By full path, so a gateway started by a service manager with a short PATH still finds it.
170
+ // The limit is enforced by the tool process itself. 'hermes config set' can only write a string, which Hermes would read as one tool's name.
171
+ const mcpEnv = [`CELLO_CALLER=${BRIDGE_CALLER}`, ...(process.env["CELLO_HOME"] ? [`CELLO_HOME=${celloHome()}`] : []), ...(tools ? [`CELLO_TOOLS=${tools.join(",")}`] : [])];
172
+ const mcpAdd = ["mcp", "add", "cello", "--env", ...mcpEnv, "--command", process.execPath, "--args", mcpEntry()];
173
+ // The tools first: an enabled plugin with no tools reads messages and can never answer them.
174
+ const steps = [mcpAdd, ["plugins", "enable", "cello"]];
175
+ const byHand = steps.map((step) => ` hermes ${step.join(" ")}`).join("\n");
176
+ const hermes = (args) => (options.exec ?? runHermes)("hermes", args, hermesHome);
177
+ for (const step of steps) {
178
+ let result;
179
+ try {
180
+ result = await hermes(step);
181
+ }
182
+ catch (err) {
183
+ return refuse(`${out.join("\n")}\n\nThe files are in place, but the 'hermes' command couldn't run (${err instanceof Error ? err.message : String(err)}). Run these by hand, then restart the gateway:\n${byHand}`);
184
+ }
185
+ if (result.code !== 0)
186
+ return refuse(`${out.join("\n")}\n\n'hermes ${step.join(" ")}' failed (exit ${result.code}):\n${(result.stderr || result.stdout).trim()}\nFix that and run this again.`);
187
+ out.push(`Ran: hermes ${step.slice(0, 3).join(" ")}`);
188
+ if (step === mcpAdd) {
189
+ // hermes mcp add can say "Cancelled." and still exit 0.
190
+ const listed = await hermes(["mcp", "list"]);
191
+ if (!listed.stdout.includes("cello"))
192
+ return refuse(`${out.join("\n")}\n\n'hermes mcp add' reported success, but 'hermes mcp list' has no cello server. Run this by hand and answer Y, then run this command again:\n hermes ${mcpAdd.join(" ")}`);
193
+ out.push("Checked: cello is in hermes mcp list");
194
+ }
195
+ }
196
+ if (tools)
197
+ out.push(`Tools the model can reach: ${tools.join(", ")}`);
198
+ out.push("", "Now restart the gateway, so Hermes loads the plugin: hermes gateway restart", "The daemon must stay up by itself on a server: cello bridge daemon-unit");
199
+ return { ok: true, output: out.join("\n") };
200
+ }
201
+ // A systemd user unit that runs the daemon in the foreground. Not 'cello login', which starts it and exits, so a plain unit would call that a failure.
202
+ export function daemonUnit() {
203
+ return `# ~/.config/systemd/user/cello-daemon.service
204
+ # Then: systemctl --user daemon-reload && systemctl --user enable --now cello-daemon
205
+ # And once, so it starts at boot with nobody logged in: loginctl enable-linger $USER
206
+ # Run 'cello login --server <url>' once first, then 'cello logout', because the server's address lives in the database.
207
+ [Unit]
208
+ Description=CELLO daemon
209
+ After=network-online.target
210
+ Wants=network-online.target
211
+
212
+ [Service]
213
+ ExecStart=${process.execPath} ${daemonEntry()}
214
+ Environment=CELLO_HOME=${celloHome()}
215
+ Restart=always
216
+ RestartSec=2
217
+ StandardOutput=append:${logPath()}
218
+ StandardError=append:${logPath()}
219
+
220
+ [Install]
221
+ WantedBy=default.target
222
+ `;
223
+ }
@@ -0,0 +1,6 @@
1
+ export interface McpInstallLine {
2
+ app: string;
3
+ outcome: "installed" | "unchanged" | "not_found" | "failed";
4
+ detail: string;
5
+ }
6
+ export declare function installMcp(home?: string): McpInstallLine[];
@@ -0,0 +1,77 @@
1
+ // cello setup --install-mcp: connects the apps on this machine, and says exactly what it changed. Nothing here leaves the machine.
2
+ import { spawnSync } from "node:child_process";
3
+ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
4
+ import { homedir } from "node:os";
5
+ import { dirname, extname, join } from "node:path";
6
+ import { fileURLToPath } from "node:url";
7
+ const CLAUDE_WAIT_MS = 120_000;
8
+ function writeAtomically(path, text) {
9
+ mkdirSync(dirname(path), { recursive: true });
10
+ writeFileSync(`${path}.cello-tmp`, text, { mode: 0o600 });
11
+ renameSync(`${path}.cello-tmp`, path);
12
+ }
13
+ function claudeCode(packageRoot) {
14
+ const app = "Claude Code";
15
+ const onPath = spawnSync("sh", ["-c", "command -v claude"], { encoding: "utf8" }).stdout.trim();
16
+ if (!onPath)
17
+ return { app, outcome: "not_found", detail: "no claude command on this PATH" };
18
+ const claude = (args) => {
19
+ const run = spawnSync(onPath, args, { encoding: "utf8", timeout: CLAUDE_WAIT_MS });
20
+ return { ok: run.status === 0, said: `${run.stdout ?? ""}${run.stderr ?? ""}`.trim() };
21
+ };
22
+ const listed = claude(["plugin", "list"]);
23
+ if (listed.ok && /cello@cello-protocol/.test(listed.said))
24
+ return { app, outcome: "unchanged", detail: "the plugin cello@cello-protocol is already installed. If it came from the old version, remove it with: claude plugin uninstall cello@cello-protocol" };
25
+ const market = claude(["plugin", "marketplace", "add", packageRoot]);
26
+ if (!market.ok)
27
+ return { app, outcome: "failed", detail: `adding the marketplace failed: ${market.said}` };
28
+ const plugin = claude(["plugin", "install", "cello@cello-protocol"]);
29
+ if (!plugin.ok)
30
+ return { app, outcome: "failed", detail: `installing the plugin failed: ${plugin.said}` };
31
+ return { app, outcome: "installed", detail: `added the plugin cello@cello-protocol, from ${packageRoot}. To be woken by messages, start it with: claude --dangerously-load-development-channels plugin:cello@cello-protocol` };
32
+ }
33
+ function claudeDesktop(home, command, args) {
34
+ const app = "Claude Desktop";
35
+ const folder = process.platform === "darwin" ? join(home, "Library", "Application Support", "Claude") : join(home, ".config", "Claude");
36
+ if (!existsSync(folder))
37
+ return { app, outcome: "not_found", detail: `no ${folder}` };
38
+ const path = join(folder, "claude_desktop_config.json");
39
+ let config = {};
40
+ if (existsSync(path)) {
41
+ try {
42
+ config = JSON.parse(readFileSync(path, "utf8"));
43
+ }
44
+ catch {
45
+ return { app, outcome: "failed", detail: `${path} isn't valid JSON, so it was left alone` };
46
+ }
47
+ }
48
+ const entry = { command, args };
49
+ const before = config.mcpServers?.["cello"];
50
+ if (JSON.stringify(before) === JSON.stringify(entry))
51
+ return { app, outcome: "unchanged", detail: `${path} already has it` };
52
+ writeAtomically(path, `${JSON.stringify({ ...config, mcpServers: { ...config.mcpServers, cello: entry } }, null, 2)}\n`);
53
+ return { app, outcome: "installed", detail: `${before ? "replaced" : "added"} the cello server in ${path}${before ? `, which was ${JSON.stringify(before)}` : ""}. Restart the app. Messages wait for your next turn there, because nothing wakes it.` };
54
+ }
55
+ const toml = (value) => JSON.stringify(value);
56
+ function chatGptDesktop(home, command, args) {
57
+ const app = "ChatGPT Desktop";
58
+ const folder = join(home, ".codex");
59
+ if (!existsSync(folder) && !existsSync(join(home, "Library", "Application Support", "com.openai.chat")))
60
+ return { app, outcome: "not_found", detail: "neither ~/.codex nor its app folder is here" };
61
+ const path = join(folder, "config.toml");
62
+ const held = existsSync(path) ? readFileSync(path, "utf8") : "";
63
+ const block = `[mcp_servers.cello]\ncommand = ${toml(command)}\nargs = [${args.map(toml).join(", ")}]\n`;
64
+ if (held.includes(block))
65
+ return { app, outcome: "unchanged", detail: `${path} already has it` };
66
+ if (/^\[mcp_servers\.cello\]/m.test(held))
67
+ return { app, outcome: "failed", detail: `${path} already has a different [mcp_servers.cello], so it was left alone. Remove that section, then run this again.` };
68
+ writeAtomically(path, `${held}${held === "" || held.endsWith("\n") ? "" : "\n"}\n${block}`);
69
+ return { app, outcome: "installed", detail: `added [mcp_servers.cello] to ${path}. Restart the app. Messages wait for your next turn there, because nothing wakes it.` };
70
+ }
71
+ export function installMcp(home = homedir()) {
72
+ const here = fileURLToPath(import.meta.url);
73
+ const packageRoot = join(dirname(here), "..");
74
+ // By full path: a desktop app doesn't start with the shell's PATH, so it wouldn't find node or cello-mcp.
75
+ const args = [join(dirname(here), `mcp${extname(here)}`)];
76
+ return [claudeCode(packageRoot), claudeDesktop(home, process.execPath, args), chatGptDesktop(home, process.execPath, args)];
77
+ }
@@ -0,0 +1,18 @@
1
+ import type { IpcNotification } from "./protocol.ts";
2
+ export declare class DaemonRefused extends Error {
3
+ readonly code: string;
4
+ constructor(code: string, message: string);
5
+ }
6
+ export declare class DaemonGone extends Error {
7
+ readonly code = "daemon_not_running";
8
+ constructor();
9
+ }
10
+ export declare class IpcClient {
11
+ #private;
12
+ onNotification: (frame: IpcNotification) => void;
13
+ onClose: () => void;
14
+ private constructor();
15
+ static connect(path: string): Promise<IpcClient>;
16
+ call(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
17
+ close(): void;
18
+ }
@@ -0,0 +1,107 @@
1
+ import { createConnection } from "node:net";
2
+ import { createInterface } from "node:readline";
3
+ export class DaemonRefused extends Error {
4
+ code;
5
+ constructor(code, message) {
6
+ super(message);
7
+ this.name = "DaemonRefused";
8
+ this.code = code;
9
+ }
10
+ }
11
+ export class DaemonGone extends Error {
12
+ code = "daemon_not_running";
13
+ constructor() {
14
+ super("the daemon isn't running. Run: cello login");
15
+ this.name = "DaemonGone";
16
+ }
17
+ }
18
+ // A wedged daemon mustn't hang a tool forever. It outlasts every wait the daemon has of its own.
19
+ const CALL_TIMEOUT_MS = 90_000;
20
+ // The daemon may have saved a call before it stopped, so what a caller should do next depends on the call.
21
+ function afterCutOff(method) {
22
+ switch (method) {
23
+ case "send":
24
+ return "The message may still go out by itself after the next login: check the transcript before sending it again.";
25
+ case "close_session":
26
+ return "The close may still go out by itself after the next login: check sessions before closing again.";
27
+ case "initiate_session":
28
+ return "A session may have started: check sessions after the next login before starting another.";
29
+ case "create_agent":
30
+ return "The agent may have been created: check agents after the next login before creating it again.";
31
+ case "receive":
32
+ return "Whatever you didn't get still counts as unread, so call receive again after the next login.";
33
+ default:
34
+ return "Its outcome is unknown: check after the next login before repeating it.";
35
+ }
36
+ }
37
+ export class IpcClient {
38
+ #socket;
39
+ #waiting = new Map();
40
+ #nextId = 1;
41
+ onNotification = () => undefined;
42
+ onClose = () => undefined;
43
+ constructor(socket) {
44
+ this.#socket = socket;
45
+ createInterface({ input: socket }).on("line", (line) => {
46
+ let frame;
47
+ try {
48
+ frame = JSON.parse(line);
49
+ }
50
+ catch {
51
+ // A daemon killed part way through a line. This is the call being cut off, so the close below reports it.
52
+ socket.destroy();
53
+ return;
54
+ }
55
+ if ("notification" in frame) {
56
+ this.onNotification(frame);
57
+ return;
58
+ }
59
+ const waiter = this.#waiting.get(frame.id);
60
+ this.#waiting.delete(frame.id);
61
+ if (frame.ok)
62
+ waiter?.resolve(frame.result);
63
+ else
64
+ waiter?.reject(new DaemonRefused(frame.error.code, frame.error.message));
65
+ });
66
+ socket.on("close", () => {
67
+ for (const waiter of this.#waiting.values())
68
+ waiter.reject(new DaemonRefused("daemon_stopped_during_call", `the daemon stopped during this call. ${afterCutOff(waiter.method)}`));
69
+ this.#waiting.clear();
70
+ this.onClose();
71
+ });
72
+ socket.on("error", () => undefined);
73
+ }
74
+ static connect(path) {
75
+ return new Promise((resolve, reject) => {
76
+ const socket = createConnection(path);
77
+ socket.once("connect", () => {
78
+ socket.removeAllListeners("error");
79
+ resolve(new IpcClient(socket));
80
+ });
81
+ socket.once("error", () => reject(new DaemonGone()));
82
+ });
83
+ }
84
+ call(method, params = {}, timeoutMs = CALL_TIMEOUT_MS) {
85
+ const id = this.#nextId++;
86
+ const request = { id, method, params };
87
+ return new Promise((resolve, reject) => {
88
+ if (this.#socket.destroyed) {
89
+ reject(new DaemonGone());
90
+ return;
91
+ }
92
+ const timer = setTimeout(() => {
93
+ this.#waiting.delete(id);
94
+ reject(new DaemonRefused("daemon_no_answer", `the daemon didn't answer ${method} within ${timeoutMs / 1000} seconds, so its outcome is unknown`));
95
+ }, timeoutMs);
96
+ this.#waiting.set(id, {
97
+ method,
98
+ resolve(value) { clearTimeout(timer); resolve(value); },
99
+ reject(err) { clearTimeout(timer); reject(err); },
100
+ });
101
+ this.#socket.write(`${JSON.stringify(request)}\n`);
102
+ });
103
+ }
104
+ close() {
105
+ this.#socket.destroy();
106
+ }
107
+ }
@@ -0,0 +1,30 @@
1
+ export interface Param {
2
+ name: string;
3
+ kind: "string" | "number" | "boolean";
4
+ description: string;
5
+ required?: boolean;
6
+ positional?: boolean;
7
+ allowed?: readonly string[];
8
+ programOnly?: boolean;
9
+ daemonEnforced?: boolean;
10
+ }
11
+ interface Definition {
12
+ command: string;
13
+ group: string;
14
+ summary: string;
15
+ description: string;
16
+ scoped: boolean;
17
+ acts: boolean;
18
+ local?: boolean;
19
+ personOnly?: boolean;
20
+ programOnly?: boolean;
21
+ plain?: (result: never) => string;
22
+ params: readonly Param[];
23
+ }
24
+ export interface Operation extends Definition {
25
+ tool: string;
26
+ method: string;
27
+ }
28
+ export declare const OPERATIONS: readonly Operation[];
29
+ export declare const DEFAULT_WAIT_SECONDS = 300;
30
+ export {};