@amkentech/agent-channel 0.5.1

package/lib/adapters.mjs

@@ -0,0 +1,170 @@
+// Runtime adapters. Agent Channel is a conduit between AI workspaces; the workspace is not ours. Each adapter says how one
+// runtime (Claude Code, Codex, ...) is wired and how it behaves, so hooks/setup/listener never hardcode a runtime and a
+// third runtime is a new entry here, not a rewrite. Capabilities are probed where possible and degrade loudly.
+//
+// Contract per adapter:
+//   key                 short name used in owner.<key> markers, .tok.<key>.json, hook argv
+//   runtime             the runtime string stored on the agent (claude-code, codex, ...)
+//   tokenEnv            env var the hook/listener read the token from
+//   rendersSystemMessage  does the runtime show hook `systemMessage` to the human? (Claude Code yes, Codex no)
+//   blocksPrompt        can a UserPromptSubmit hook block the prompt with a visible reason? (Claude Code yes)
+//   supportsFileChanged Claude Code's FileChanged hook (idle notifications)
+//   supportsStatusLine  Claude Code statusLine
+//   hooksFile / mcp     where the wiring lives, and how to write it
+//   transcripts         where session transcripts live (for export-conversation)
+import { homedir, platform } from "node:os";
+import { join, dirname as dirnameOf } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+const H = homedir();
+// hook command lines run through a shell on every OS; forward slashes work on Windows too, and a path with spaces
+// ("/Users/Jo Smith/.agentchan/client") must stay quoted
+const nodeCmd = (repo, rel, ...a) => { const p = join(repo, rel).replace(/\\/g, "/"); return ["node", /\s/.test(p) ? '"' + p + '"' : p, ...a].join(" "); };
+
+export const ADAPTERS = {
+  claude: {
+    key: "claude", runtime: "claude-code", label: "Claude Code", tokenEnv: "AGENTCHAN_TOKEN",
+    rendersSystemMessage: true, blocksPrompt: true, supportsFileChanged: true, supportsStatusLine: true,
+    hooksFile: join(H, ".claude", "settings.json"),
+    transcripts: { dir: join(H, ".claude", "projects"), note: "one folder per cwd slug, <session>.jsonl" },
+    detect: () => existsSync(join(H, ".claude")) || !!which("claude"),
+    mcpWire: ({ url, token }) => ({
+      command: 'claude mcp add --transport http --scope user agent-channel ' + url + '/mcp --header "Authorization: Bearer ' + token + '"',
+      apply: () => { const c = which("claude"); if (!c) return { ok: false, why: "claude CLI not on PATH; run the command yourself" };
+        try { execFileSync(c, ["mcp", "remove", "--scope", "user", "agent-channel"], { stdio: "ignore" }); } catch {}
+        try { execFileSync(c, ["mcp", "add", "--transport", "http", "--scope", "user", "agent-channel", url + "/mcp", "--header", "Authorization: Bearer " + token], { stdio: "pipe" }); return { ok: true }; }
+        catch (e) { return { ok: false, why: String(e.stderr || e.message).trim().slice(0, 200) }; } },
+      check: () => { const c = which("claude"); if (!c) return null; try { return execFileSync(c, ["mcp", "list"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).includes("agent-channel"); } catch { return null; } },
+    }),
+    hooksWire: ({ repo }) => ({
+      // merged into settings.json; existing hooks for other purposes are preserved (setup.mjs dedups by command substring)
+      hooks: {
+        SessionStart: [{ hooks: [{ type: "command", command: nodeCmd(repo, "hooks/inbox.mjs", "claude", "SessionStart"), timeout: 8, statusMessage: "Checking Agent Channel..." }, { type: "command", command: nodeCmd(repo, "hooks/claude-status.mjs", "working"), timeout: 6 }] }],
+        UserPromptSubmit: [{ hooks: [{ type: "command", command: nodeCmd(repo, "hooks/inbox.mjs", "claude", "UserPromptSubmit"), timeout: 8, statusMessage: "Checking Agent Channel..." }] }],
+        Stop: [{ hooks: [{ type: "command", command: nodeCmd(repo, "hooks/claude-status.mjs", "idle"), timeout: 6 }] }],
+        SessionEnd: [{ hooks: [{ type: "command", command: nodeCmd(repo, "hooks/claude-status.mjs", "offline"), timeout: 6 }] }],
+        FileChanged: [{ matcher: "agentchan_notify", hooks: [{ type: "command", command: nodeCmd(repo, "hooks/notify.mjs", "claude"), timeout: 5 }] }],
+      },
+      statusLine: { type: "command", command: nodeCmd(repo, "hooks/statusline.mjs", "claude"), refreshInterval: 2 },
+    }),
+  },
+  codex: {
+    key: "codex", runtime: "codex", label: "Codex CLI", tokenEnv: "AGENTCHAN_CODEX_TOKEN",
+    rendersSystemMessage: false, blocksPrompt: false, supportsFileChanged: false, supportsStatusLine: false,
+    hooksFile: join(H, ".codex", "hooks.json"),
+    configFile: join(H, ".codex", "config.toml"),
+    transcripts: { dir: join(H, ".codex", "sessions"), note: "YYYY/MM/DD/rollout-*.jsonl" },
+    detect: () => existsSync(join(H, ".codex")) || !!which("codex"),
+    // Windows: setup.mjs sets AGENTCHAN_CODEX_TOKEN with setx, so the env-var form works. macOS/Linux have no per-user env
+    // store the Codex app reads, so the header goes into config.toml itself (same trust level as ~/.claude.json for Claude Code).
+    mcpWire: ({ url, token }) => {
+      const block = platform() === "win32" || !token
+        ? "[mcp_servers.agent_channel]\nurl = \"" + url + "/mcp\"\nbearer_token_env_var = \"AGENTCHAN_CODEX_TOKEN\"\n"
+        : "[mcp_servers.agent_channel]\nurl = \"" + url + "/mcp\"\nhttp_headers = { Authorization = \"Bearer " + token + "\" }\n";
+      return {
+      command: "add to ~/.codex/config.toml:\n" + block.replace(/Bearer ac_[^"]+/, "Bearer <your token>"),
+      apply: () => {
+        const f = join(H, ".codex", "config.toml");
+        let cur = existsSync(f) ? readFileSync(f, "utf8") : "";
+        if (cur.includes("[mcp_servers.agent_channel]")) return { ok: true, note: "already present" };
+        mkdirSync(join(H, ".codex"), { recursive: true });
+        writeFileSync(f, cur + (cur.endsWith("\n") || !cur ? "" : "\n") + "\n" + block);
+        return { ok: true };
+      },
+      check: () => { const f = join(H, ".codex", "config.toml"); return existsSync(f) ? readFileSync(f, "utf8").includes("[mcp_servers.agent_channel]") : false; },
+      }; },
+    hooksWire: ({ repo }) => ({
+      hooks: {
+        SessionStart: [{ hooks: [{ type: "command", command: nodeCmd(repo, "hooks/inbox.mjs", "codex", "SessionStart"), timeout: 8, statusMessage: "Checking Agent Channel..." }] }],
+        UserPromptSubmit: [{ hooks: [{ type: "command", command: nodeCmd(repo, "hooks/inbox.mjs", "codex", "UserPromptSubmit"), timeout: 8, statusMessage: "Checking Agent Channel..." }] }],
+      },
+      note: "Codex asks you to trust hooks once via /hooks. It does not render systemMessage, so the model relays messages to you.",
+    }),
+  },
+  "claude-desktop": {
+    key: "claude-desktop", runtime: "claude-desktop", label: "Claude Desktop", tokenEnv: "AGENTCHAN_TOKEN",
+    rendersSystemMessage: false, blocksPrompt: false, supportsFileChanged: false, supportsStatusLine: false,
+    configFile: platform() === "win32" ? join(process.env.APPDATA || join(H, "AppData", "Roaming"), "Claude", "claude_desktop_config.json")
+              : platform() === "darwin" ? join(H, "Library", "Application Support", "Claude", "claude_desktop_config.json")
+              : join(H, ".config", "Claude", "claude_desktop_config.json"),
+    detect() { return existsSync(dirnameOf(this.configFile)); },
+    // Desktop launches stdio servers only, so bridge with mcp-remote. With a token: static header. Without: mcp-remote runs the OAuth flow in the browser.
+    mcpWire({ url, token, oauth }) {
+      const file = this.configFile;
+      const args = ["-y", "mcp-remote", url + "/mcp", ...(token && !oauth ? ["--header", "Authorization: Bearer " + token] : [])];
+      return {
+        command: "add to " + file + ':\n"mcpServers": { "agent-channel": { "command": "npx", "args": ' + JSON.stringify(args) + " } }\n(or in Desktop: Settings > Connectors > Add custom connector > " + url + "/mcp and sign in)",
+        apply: () => {
+          let cur = {}; try { cur = JSON.parse(readFileSync(file, "utf8")); } catch {}
+          cur.mcpServers = { ...(cur.mcpServers || {}), "agent-channel": { command: "npx", args } };
+          mkdirSync(dirnameOf(file), { recursive: true });
+          writeFileSync(file, JSON.stringify(cur, null, 2));
+          return { ok: true, note: "restart Claude Desktop" };
+        },
+        check: () => { try { return !!JSON.parse(readFileSync(file, "utf8")).mcpServers?.["agent-channel"]; } catch { return false; } },
+      };
+    },
+    hooksWire: () => ({ note: "Claude Desktop has no hooks: typed @handle messages go through the model (send_message); inbound arrives via my_inbox or the listener's toast." }),
+  },
+  // JSON-config MCP clients (no hooks; the model does the messaging and reads my_inbox). Each writes one entry into the
+  // client's mcpServers file; tokens go in a header exactly like Claude Code's `claude mcp add --header`.
+  cursor: jsonMcpAdapter({ key: "cursor", runtime: "cursor", label: "Cursor", file: join(H, ".cursor", "mcp.json"), shape: "url" }),
+  gemini: jsonMcpAdapter({ key: "gemini", runtime: "gemini-cli", label: "Gemini CLI", file: join(H, ".gemini", "settings.json"), shape: "httpUrl" }),
+  windsurf: jsonMcpAdapter({ key: "windsurf", runtime: "windsurf", label: "Windsurf", file: join(H, ".codeium", "windsurf", "mcp_config.json"), shape: "serverUrl" }),
+  generic: {
+    key: "generic", runtime: "other", label: "Any MCP client", tokenEnv: "AGENTCHAN_TOKEN",
+    rendersSystemMessage: false, blocksPrompt: false, supportsFileChanged: false, supportsStatusLine: false,
+    detect: () => true,
+    mcpWire: ({ url, token }) => ({ command: "Streamable HTTP MCP: " + url + "/mcp with header Authorization: Bearer " + token, apply: () => ({ ok: false, why: "wire it in your client's MCP settings" }), check: () => null }),
+    hooksWire: () => ({ note: "No hook system: use scripts/cli.mjs and the listener; type-to-send needs a UserPromptSubmit-style hook in your client." }),
+  },
+};
+
+function jsonMcpAdapter({ key, runtime, label, file, shape }) {
+  const entry = (url, token) => shape === "httpUrl" ? { httpUrl: url + "/mcp", headers: { Authorization: "Bearer " + token } }
+    : shape === "serverUrl" ? { serverUrl: url + "/mcp", headers: { Authorization: "Bearer " + token } }
+    : { url: url + "/mcp", headers: { Authorization: "Bearer " + token } };
+  return {
+    key, runtime, label, tokenEnv: "AGENTCHAN_TOKEN",
+    rendersSystemMessage: false, blocksPrompt: false, supportsFileChanged: false, supportsStatusLine: false,
+    configFile: file,
+    detect: () => existsSync(dirnameOf(file)),
+    mcpWire: ({ url, token }) => ({
+      command: "add to " + file + ':\n"mcpServers": { "agent-channel": ' + JSON.stringify(entry(url, "<your token>")) + " }",
+      apply: () => {
+        let cur = {}; try { cur = JSON.parse(readFileSync(file, "utf8")); } catch {}
+        cur.mcpServers = { ...(cur.mcpServers || {}), "agent-channel": entry(url, token) };
+        mkdirSync(dirnameOf(file), { recursive: true });
+        writeFileSync(file, JSON.stringify(cur, null, 2));
+        return { ok: true, note: "restart " + label };
+      },
+      check: () => { try { return !!JSON.parse(readFileSync(file, "utf8")).mcpServers?.["agent-channel"]; } catch { return false; } },
+    }),
+    hooksWire: () => ({ note: label + " has no hook system: typed @handle messages go through the model (send_message); inbound arrives when the model reads my_inbox (the server instructions tell it to at session start)." }),
+  };
+}
+
+export const adapterFor = (nameOrRuntime) => {
+  const k = String(nameOrRuntime || "").toLowerCase().replace(/-code$/, "").replace(/-cli$/, "");
+  return ADAPTERS[k] || (k === "claude-code" ? ADAPTERS.claude : null) || ADAPTERS.generic;
+};
+
+export function which(bin) {
+  try { return execFileSync(platform() === "win32" ? "where" : "which", [bin], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split(/\r?\n/).filter(Boolean)[0] || null; }
+  catch { return null; }
+}
+
+/** Merge our hook entries into an existing hooks JSON without clobbering unrelated hooks (dedup by command substring 'agent-channel/hooks'). */
+export function mergeHooks(existing, ours) {
+  const out = { ...(existing || {}) };
+  out.hooks = { ...(out.hooks || {}) };
+  for (const [ev, entries] of Object.entries(ours.hooks || {})) {
+    const cur = Array.isArray(out.hooks[ev]) ? out.hooks[ev] : [];
+    const isOurs = (h) => /(agent-channel|\.agentchan[\\/]client)[\\/]hooks[\\/]/i.test(h.command || "");
+    const kept = cur.map((g) => ({ ...g, hooks: (g.hooks || []).filter((h) => !isOurs(h)) })).filter((g) => (g.hooks || []).length || g.matcher);
+    out.hooks[ev] = [...kept.filter((g) => (g.hooks || []).length), ...entries];
+  }
+  if (ours.statusLine && !out.statusLine) out.statusLine = ours.statusLine;
+  return out;
+}

package/lib/artifacts.mjs

@@ -0,0 +1,29 @@
+// Fetch + decrypt + inspect one artifact onto this machine. Shared by the CLI and the resident listener.
+import { writeFileSync, mkdirSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { decryptWith, loadLocalKeys, sha256hex } from "./crypto.mjs";
+import { inspectArtifact, safeName } from "./inspect.mjs";
+
+export async function fetchArtifact({ base, token, handle, id, quiet = false }) {
+  const r = await fetch(base + "/artifacts/" + id, { headers: { authorization: "Bearer " + token } });
+  const a = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error("/artifacts/" + id + " -> " + r.status + " " + (a.error || ""));
+  const keys = loadLocalKeys(handle);
+  const plain = decryptWith(keys, a.envelope, a.ciphertext);
+  const actual = sha256hex(plain);
+  const report = inspectArtifact({ filename: a.filename, bytes: plain, declaredSha256: a.sha256, actualSha256: actual });
+  const sub = report.verdict === "danger" ? "quarantine" : "inbox";
+  const dir = join(homedir(), ".agentchan", handle, sub, id.slice(0, 8));
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, safeName(a.filename));
+  writeFileSync(file, plain);
+  const rec = { id, from: a.from, filename: a.filename, size: plain.length, sha256: actual, note: a.note, verdict: report.verdict, findings: report.findings, path: file, received_at: new Date().toISOString() };
+  writeFileSync(join(dir, "report.json"), JSON.stringify(rec, null, 2));
+  appendFileSync(join(homedir(), ".agentchan", handle, "artifacts.jsonl"), JSON.stringify(rec) + "\n");
+  if (!quiet) {
+    console.log((report.verdict === "danger" ? "QUARANTINED " : report.verdict === "warn" ? "WARN " : "ok ") + a.filename + " from " + a.from + " (" + plain.length + " bytes) -> " + file);
+    for (const f of report.findings) console.log("  [" + f.level + "] " + f.what + (f.detail ? " :: " + f.detail : ""));
+  }
+  return rec;
+}

package/lib/codex-push.mjs

@@ -0,0 +1,43 @@
+// Push an Agent Channel event INTO a live Codex TUI thread, via the Codex app-server protocol.
+// Requires: `codex app-server --listen ws://127.0.0.1:4517` running (run_codex_appserver.cmd) and the TUI
+// started with `codex --remote ws://127.0.0.1:4517` so its thread is loaded on that server.
+//
+// mode "inject": thread/inject_items — appended to the model-visible history, no turn, no cost; the model
+//                sees it on the human's next prompt (may not render in the TUI).
+// mode "turn":   turn/start — a real user turn carrying the message; renders in the TUI immediately and the
+//                model relays it in one line. Costs one (short) model turn. Use when the human wants to SEE it.
+import WebSocket from "ws";
+
+export async function pushToCodex({ url = process.env.AGENTCHAN_CODEX_WS || "ws://127.0.0.1:4517", text, mode = "turn", timeoutMs = 8000 }) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (r) => { if (!done) { done = true; try { ws.close(); } catch {} resolve(r); } };
+    const ws = new WebSocket(url);
+    let id = 0; const pending = new Map();
+    const call = (method, params = {}) => new Promise((res, rej) => { const i = ++id; pending.set(i, { res, rej }); ws.send(JSON.stringify({ jsonrpc: "2.0", id: i, method, params })); });
+    const t = setTimeout(() => finish({ ok: false, reason: "timeout" }), timeoutMs);
+    ws.on("error", (e) => { clearTimeout(t); finish({ ok: false, reason: e.message }); });
+    ws.on("message", (b) => {
+      let m; try { m = JSON.parse(b.toString()); } catch { return; }
+      if (m.id !== undefined && pending.has(m.id)) { const p = pending.get(m.id); pending.delete(m.id); m.error ? p.rej(new Error(JSON.stringify(m.error))) : p.res(m.result); }
+    });
+    ws.on("open", async () => {
+      try {
+        await call("initialize", { clientInfo: { name: "agent-channel", title: "Agent Channel", version: "0.2.0" }, capabilities: {} });
+        ws.send(JSON.stringify({ jsonrpc: "2.0", method: "initialized", params: {} }));
+        const loaded = await call("thread/loaded/list", {});
+        const threads = loaded?.data || [];
+        if (!threads.length) { clearTimeout(t); return finish({ ok: false, reason: "no loaded thread (start Codex with --remote " + url + ")" }); }
+        // most recently active loaded thread
+        threads.sort((a, b) => (b.recencyAt || b.updatedAt || 0) - (a.recencyAt || a.updatedAt || 0));
+        const tid = threads[0].id;
+        if (mode === "inject") {
+          await call("thread/inject_items", { threadId: tid, items: [{ type: "message", role: "user", content: [{ type: "input_text", text }] }] });
+          clearTimeout(t); return finish({ ok: true, mode, threadId: tid });
+        }
+        const turn = await call("turn/start", { threadId: tid, input: [{ type: "text", text }] });
+        clearTimeout(t); return finish({ ok: true, mode, threadId: tid, turnId: turn?.turn?.id || turn?.turnId || null });
+      } catch (e) { clearTimeout(t); finish({ ok: false, reason: e.message }); }
+    });
+  });
+}

package/lib/crypto.mjs

@@ -0,0 +1,100 @@
+// End-to-end artifact encryption. Runs on the sender's and receiver's machines only.
+// Scheme (v1): random 256-bit content key -> AES-256-GCM over the file.
+//   For each recipient X25519 public key: ephemeral X25519 keypair -> ECDH -> HKDF-SHA256 -> AES-256-GCM wrap of the content key.
+// The server stores the envelope (public data) and the ciphertext; it never holds a private key or the content key.
+
+import { generateKeyPairSync, createPublicKey, createPrivateKey, diffieHellman, hkdfSync, createCipheriv, createDecipheriv, randomBytes, createHash } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export const ALG = "x25519-hkdf-sha256-aes256gcm-v1";
+const INFO = Buffer.from("agentchan-artifact-v1");
+
+export const sha256hex = (buf) => createHash("sha256").update(buf).digest("hex");
+
+/** New X25519 keypair as base64 SPKI/PKCS8 DER. */
+export function generateKeypair() {
+  const { publicKey, privateKey } = generateKeyPairSync("x25519");
+  return {
+    public_key: publicKey.export({ type: "spki", format: "der" }).toString("base64"),
+    private_key: privateKey.export({ type: "pkcs8", format: "der" }).toString("base64"),
+  };
+}
+const pub = (b64) => createPublicKey({ key: Buffer.from(b64, "base64"), format: "der", type: "spki" });
+const priv = (b64) => createPrivateKey({ key: Buffer.from(b64, "base64"), format: "der", type: "pkcs8" });
+
+function kek(sharedSecret, ephPubB64, recipPubB64) {
+  const salt = Buffer.concat([Buffer.from(ephPubB64, "base64"), Buffer.from(recipPubB64, "base64")]);
+  return Buffer.from(hkdfSync("sha256", sharedSecret, salt, INFO, 32));
+}
+
+/** Encrypt plaintext for a list of recipient keys [{id, public_key}]. Returns { envelope, ciphertext(base64) }. */
+export function encryptFor(recipients, plaintext) {
+  if (!recipients?.length) throw new Error("no recipient keys");
+  const ck = randomBytes(32);
+  const iv = randomBytes(12);
+  const c = createCipheriv("aes-256-gcm", ck, iv);
+  const body = Buffer.concat([c.update(plaintext), c.final()]);
+  const tag = c.getAuthTag();
+  const keys = recipients.map((r) => {
+    const eph = generateKeyPairSync("x25519");
+    const ephPub = eph.publicKey.export({ type: "spki", format: "der" }).toString("base64");
+    const shared = diffieHellman({ privateKey: eph.privateKey, publicKey: pub(r.public_key) });
+    const k = kek(shared, ephPub, r.public_key);
+    const wiv = randomBytes(12);
+    const wc = createCipheriv("aes-256-gcm", k, wiv);
+    const wrapped = Buffer.concat([wc.update(ck), wc.final()]);
+    return { key_id: r.id, eph_pub: ephPub, iv: wiv.toString("base64"), tag: wc.getAuthTag().toString("base64"), wrapped: wrapped.toString("base64") };
+  });
+  const envelope = { v: 1, alg: ALG, iv: iv.toString("base64"), tag: tag.toString("base64"), keys };
+  return { envelope, ciphertext: body.toString("base64") };
+}
+
+/** Decrypt with one of our local keys [{key_id, public_key, private_key}]. Returns Buffer or throws. */
+export function decryptWith(localKeys, envelope, ciphertextB64) {
+  if (envelope?.alg !== ALG) throw new Error("unknown envelope alg " + envelope?.alg);
+  for (const lk of localKeys) {
+    const slot = envelope.keys.find((k) => k.key_id === lk.key_id);
+    if (!slot) continue;
+    const shared = diffieHellman({ privateKey: priv(lk.private_key), publicKey: pub(slot.eph_pub) });
+    const k = kek(shared, slot.eph_pub, lk.public_key);
+    const wd = createDecipheriv("aes-256-gcm", k, Buffer.from(slot.iv, "base64"));
+    wd.setAuthTag(Buffer.from(slot.tag, "base64"));
+    const ck = Buffer.concat([wd.update(Buffer.from(slot.wrapped, "base64")), wd.final()]);
+    const d = createDecipheriv("aes-256-gcm", ck, Buffer.from(envelope.iv, "base64"));
+    d.setAuthTag(Buffer.from(envelope.tag, "base64"));
+    return Buffer.concat([d.update(Buffer.from(ciphertextB64, "base64")), d.final()]);
+  }
+  throw new Error("this artifact was not encrypted to any key on this machine (" + localKeys.length + " local keys)");
+}
+
+// ---- local key store: ~/.agentchan/<handle>/keys/<label>.json  { key_id, public_key, private_key, label, created_at } ----
+export const keyDir = (handle) => join(homedir(), ".agentchan", handle, "keys");
+export function loadLocalKeys(handle) {
+  const dir = keyDir(handle);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => { try { return JSON.parse(readFileSync(join(dir, f), "utf8")); } catch { return null; } }).filter((k) => k && k.private_key);
+}
+export function saveLocalKey(handle, label, key) {
+  const dir = keyDir(handle); mkdirSync(dir, { recursive: true });
+  const f = join(dir, label.replace(/[^a-z0-9_-]/gi, "_") + ".json");
+  writeFileSync(f, JSON.stringify({ ...key, label, created_at: new Date().toISOString() }, null, 2), { mode: 0o600 });
+  return f;
+}
+export function findLocalKey(handle, label) {
+  return loadLocalKeys(handle).find((k) => k.label === label) || null;
+}
+
+/** Ensure this (handle, label) has a registered key on the server. Returns the local key. */
+export async function ensureKey({ base, token, handle, label }) {
+  let key = findLocalKey(handle, label);
+  if (key && key.key_id) return key;
+  const kp = key || generateKeypair();
+  const r = await fetch(base + "/keys", { method: "POST", headers: { "content-type": "application/json", authorization: "Bearer " + token }, body: JSON.stringify({ public_key: kp.public_key, label }) });
+  if (!r.ok) throw new Error("key registration failed: " + r.status + " " + await r.text());
+  const { key_id } = await r.json();
+  key = { ...kp, key_id };
+  saveLocalKey(handle, label, key);
+  return key;
+}

package/lib/paths.mjs

@@ -0,0 +1,45 @@
+// Where the client keeps things, independent of where the code runs from.
+//
+// The client (hooks, listener, setup, artifact, share) can run from a git checkout of the repo, from a global install, from
+// the persistent copy `setup.mjs join` makes under ~/.agentchan/client, or from an npx cache that vanishes. Tokens therefore
+// live in the HOME store, not next to the code:
+//     ~/.agentchan/tok.<runtime>.json        { token, runtime, base, handle }   (0600 where the OS honours it)
+// with the old in-repo `.tok.<runtime>.json` still read as a fallback so existing installs keep working.
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export const HOME_STORE = join(homedir(), ".agentchan");
+export const CLIENT_HOME = join(HOME_STORE, "client");          // persistent copy of the client package (setup.mjs join)
+export const CLIENT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");   // wherever this code runs from
+export const BASE = (process.env.AGENTCHAN_URL || "https://agent-channel-production.up.railway.app").replace(/\/mcp$/, "");
+export const IN_NPX_CACHE = /[\\/]_npx[\\/]|[\\/]\.npm[\\/]_cacache|[\\/]npm-cache[\\/]/i.test(CLIENT_ROOT);
+
+export const tokFileHome = (key) => join(HOME_STORE, "tok." + key + ".json");
+export const tokFileRepo = (key) => join(CLIENT_ROOT, ".tok." + key + ".json");
+
+const parseTok = (t) => { try { return JSON.parse(t); } catch { const m = t.match(/"token"\s*:\s*"([^"]+)"/); return m ? { token: m[1], handle: t.match(/"(?:person|handle)"\s*:\s*"([^"]+)"/)?.[1] } : null; } };
+
+/** Read the saved token record for a runtime key (claude | codex | claude-desktop), home store first, then the repo file. */
+export function readTok(key) {
+  for (const f of [tokFileHome(key), tokFileRepo(key), join(homedir(), "agent-channel", ".tok." + key + ".json")]) {
+    try { if (existsSync(f)) { const r = parseTok(readFileSync(f, "utf8")); if (r?.token) return { ...r, file: f }; } } catch {}
+  }
+  return null;
+}
+export function saveTok(key, obj) {
+  mkdirSync(HOME_STORE, { recursive: true });
+  const f = tokFileHome(key);
+  writeFileSync(f, JSON.stringify(obj, null, 2));
+  try { chmodSync(f, 0o600); } catch {}
+  return f;
+}
+/** Token for a runtime: env first (AGENTCHAN_TOKEN / AGENTCHAN_CODEX_TOKEN), then the saved record. */
+export function tokenFor(key) {
+  const k = String(key || "claude").toLowerCase();
+  const env = k === "codex" ? (process.env.AGENTCHAN_CODEX_TOKEN || null) : (process.env.AGENTCHAN_TOKEN || null);
+  if (env) return env;
+  const r = readTok(k) || (k === "claude-desktop" ? readTok("claude") : null);
+  return r?.token || null;
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@amkentech/agent-channel",
+  "version": "0.5.1",
+  "description": "Send your Claude Code or Codex session, or a file, to another person in one line: encrypted read-only links (no account), or into a teammate's inbox via hooks + a remote MCP server. The server is a separate, private service.",
+  "type": "module",
+  "bin": { "agent-channel": "bin/agent-channel.mjs" },
+  "files": ["bin", "hooks", "lib", "scripts", "db", "README.md"],
+  "engines": { "node": ">=22" },
+  "keywords": ["mcp", "agents", "claude-code", "codex", "collaboration"],
+  "homepage": "https://agent-channel-production.up.railway.app/",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "ws": "^8.21.3"
+  }
+}

package/scripts/artifact.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// End-to-end encrypted artifact exchange. The server only ever sees ciphertext + an envelope.
+//
+//   node scripts/artifact.mjs send @handle <path> [--note "why"]     encrypt to every key @handle has registered, upload
+//   node scripts/artifact.mjs fetch <artifact_id>                    download, decrypt with a local key, inspect, save to ~/.agentchan/<me>/inbox/
+//   node scripts/artifact.mjs fetch --all                            fetch everything waiting for me
+//   node scripts/artifact.mjs keygen [--label name]                  create + register a key for this token (listener does this automatically)
+//   node scripts/artifact.mjs keys [@handle]                         list registered public keys
+//
+// Token: AGENTCHAN_TOKEN (or --runtime codex -> AGENTCHAN_CODEX_TOKEN). URL: AGENTCHAN_URL.
+
+import { readFileSync, statSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "node:fs";
+import { basename, join, resolve, dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { encryptFor, ensureKey, sha256hex } from "../lib/crypto.mjs";
+import { fetchArtifact } from "../lib/artifacts.mjs";
+
+const args = process.argv.slice(2);
+const flag = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+const has = (name) => args.includes(name);
+const runtime = (flag("--runtime") || process.env.AGENTCHAN_RUNTIME || "claude").toLowerCase();
+const BASE = (process.env.AGENTCHAN_URL || "https://agent-channel-production.up.railway.app").replace(/\/mcp$/, "");
+let token = process.env.AGENTCHAN_TOKEN;
+if (runtime === "codex" && process.env.AGENTCHAN_CODEX_TOKEN) token = process.env.AGENTCHAN_CODEX_TOKEN;
+if (!token) { const { tokenFor } = await import("../lib/paths.mjs"); token = tokenFor(runtime); }
+if (!token) { console.error("AGENTCHAN_TOKEN required"); process.exit(1); }
+const H = { authorization: "Bearer " + token, "content-type": "application/json" };
+
+const api = async (path, init = {}) => {
+  const r = await fetch(BASE + path, { ...init, headers: { ...H, ...(init.headers || {}) } });
+  const j = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(path + " -> " + r.status + " " + (j.error || JSON.stringify(j)));
+  return j;
+};
+
+async function myHandle() {
+  // /feed carries all agents; find ours by matching token is impossible, so use the MCP-free route: /keys/<x> requires handle. Use /status? No.
+  // Simplest: the server tells us in the WebSocket hello, but here we do one MCP whoami call.
+  const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+  const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+  const c = new Client({ name: "artifact", version: "0.0.1" });
+  await c.connect(new StreamableHTTPClientTransport(new URL(BASE + "/mcp"), { requestInit: { headers: { authorization: "Bearer " + token } } }));
+  const r = await c.callTool({ name: "whoami", arguments: {} });
+  await c.close();
+  const j = JSON.parse(r.content[0].text);
+  return { handle: j.person.handle, agent: j.agent.name, runtime: j.agent.runtime };
+}
+
+const cmd = args[0];
+// ---- key pins: ~/.agentchan/pins/<handle>.json  [{id, public_key, label, runtime, first_seen}] ----
+const pinDir = join(homedir(), ".agentchan", "pins");
+const pinFile = (h) => join(pinDir, String(h).replace(/^@/, "").toLowerCase() + ".json");
+const fp = (pub) => createHash("sha256").update(String(pub)).digest("hex").match(/.{4}/g).slice(0, 8).join(" ");
+function checkPins(to, keys) {
+  let pinned = []; try { pinned = JSON.parse(readFileSync(pinFile(to), "utf8")); } catch {}
+  const fresh = keys.filter((k) => !pinned.some((p) => p.id === k.id || p.public_key === k.public_key));
+  return { pinned, fresh };
+}
+function savePins(to, keys) {
+  let cur = []; try { cur = JSON.parse(readFileSync(pinFile(to), "utf8")); } catch {}
+  const now = new Date().toISOString();
+  for (const k of keys) if (!cur.some((p) => p.id === k.id || p.public_key === k.public_key)) cur.push({ id: k.id, public_key: k.public_key, label: k.label, runtime: k.runtime, fingerprint: fp(k.public_key), first_seen: now });
+  mkdirSync(pinDir, { recursive: true }); writeFileSync(pinFile(to), JSON.stringify(cur, null, 2));
+}
+
+try {
+  if (cmd === "send") {
+    const to = args[1], path = args[2];
+    if (!to || !path) throw new Error("usage: artifact.mjs send @handle <path> [--note text]");
+    const abs = resolve(path);
+    const st = statSync(abs);
+    if (st.size > 8 * 1024 * 1024) throw new Error("file is " + st.size + " bytes; 8 MB max");
+    const bytes = readFileSync(abs);
+    const { keys } = await api("/keys/" + to.replace(/^@/, ""));
+    if (!keys.length) throw new Error(to + " has no registered keys yet (their listener registers one on first connect). Ask them to run: node scripts/artifact.mjs keygen");
+    // Key pinning (trust on first use). The server hands out the recipient's public keys; a malicious operator could add one
+    // and read everything encrypted from then on. So remember the keys we have seen per handle, and refuse to encrypt to a
+    // NEW key until the human says so (--trust-new-keys), after comparing fingerprints with the other person out of band.
+    const { pinned, fresh } = checkPins(to, keys);
+    if (fresh.length && pinned.length && !has("--trust-new-keys")) {
+      console.error("REFUSED: " + to + " has " + fresh.length + " key(s) you have never encrypted to before:\n" + fresh.map((k) => "  " + fp(k.public_key) + "  " + (k.label || "") + " (" + (k.runtime || "?") + ")").join("\n") +
+        "\nAsk " + to + " to confirm these fingerprints (they run: node scripts/artifact.mjs keys), then re-run with --trust-new-keys. Or --only-pinned to encrypt to the known keys only.");
+      process.exit(3);
+    }
+    const useKeys = has("--only-pinned") && pinned.length ? keys.filter((k) => pinned.some((p) => p.id === k.id)) : keys;
+    if (!pinned.length) {
+      console.error("first send to " + to + ": " + keys.length + " key(s) the server reports for them:\n" + keys.map((k) => "  " + fp(k.public_key) + "  " + (k.label || "") + " (" + (k.runtime || "?") + ")").join("\n") + "\nThese get pinned; later changes are refused until you pass --trust-new-keys. If this file matters, confirm the fingerprints with " + to + " out of band (they run: node scripts/artifact.mjs keys).");
+      if (process.stdin.isTTY && !has("--trust-new-keys") && !has("--yes")) {
+        const { createInterface } = await import("node:readline/promises");
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        const ans = (await rl.question("Encrypt to these keys and pin them? [y/N] ")).trim().toLowerCase(); rl.close();
+        if (ans !== "y" && ans !== "yes") { console.error("not sent."); process.exit(3); }
+      }
+    }
+    else if (fresh.length) console.error("trusting " + fresh.length + " new key(s) for " + to + " as instructed: " + fresh.map((k) => fp(k.public_key)).join(", "));
+    savePins(to, useKeys);
+    const { envelope, ciphertext } = encryptFor(useKeys, bytes);
+    const r = await api("/artifacts", { method: "POST", body: JSON.stringify({ to, filename: basename(abs), size_bytes: st.size, sha256: sha256hex(bytes), note: flag("--note"), envelope, ciphertext }) });
+    console.log("sent " + basename(abs) + " (" + st.size + " bytes) to " + r.to + ", encrypted to " + keys.length + " key(s), artifact " + r.artifact_id + ", expires " + r.expires_at);
+  } else if (cmd === "fetch") {
+    const me = await myHandle();
+    if (has("--all") || !args[1]) {
+      const list = await api("/artifacts");
+      if (!list.artifacts.length) console.log("nothing waiting");
+      for (const a of list.artifacts) await fetchArtifact({ base: BASE, token, handle: me.handle, id: a.id });
+    } else {
+      await fetchArtifact({ base: BASE, token, handle: me.handle, id: args[1] });
+    }
+  } else if (cmd === "keygen") {
+    const me = await myHandle();
+    const label = flag("--label") || (me.agent + "-" + me.runtime + "-" + (process.env.COMPUTERNAME || process.env.HOSTNAME || "host")).toLowerCase();
+    const k = await ensureKey({ base: BASE, token, handle: me.handle, label });
+    console.log("key registered for @" + me.handle + " label=" + label + " key_id=" + k.key_id);
+  } else if (cmd === "pins") {
+    const f = pinFile(args[1] || "");
+    console.log(args[1] ? (existsSync(f) ? readFileSync(f, "utf8") : "no pins for " + args[1]) : readdirSync(dirname(f)).filter((x) => x.endsWith(".json")).join("\n"));
+  } else if (cmd === "keys") {
+    const who = args[1] ? args[1].replace(/^@/, "") : (await myHandle()).handle;
+    const r = await api("/keys/" + who);
+    console.log(JSON.stringify({ ...r, keys: r.keys.map((k) => ({ fingerprint: fp(k.public_key), ...k })) }, null, 2));
+  } else {
+    console.log("usage: artifact.mjs send @handle <path> [--note text] [--trust-new-keys|--only-pinned] | fetch <id>|--all | keygen [--label x] | keys [@handle] | pins [@handle]");
+    process.exit(cmd ? 1 : 0);
+  }
+} catch (e) { console.error("artifact: " + e.message); process.exit(2); }

package/scripts/audit-verify.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Offline verifier for Agent Channel exports. No database access; optionally one fetch for the public key.
+//   node scripts/audit-verify.mjs export.json                       audit_trail mode=export (signed wrapper or bare)
+//   node scripts/audit-verify.mjs --record record.json               export_contract / GET /c/:id/record.json
+//   options: --pubkey <pem file> | --pubkey-url <url> (default: the server named in the export), --no-sig (skip signature)
+// Checks: every ledger row's hash from its canonical string, every visible chain link, and (if present) the server's Ed25519
+// signature over the sha256 of the canonical JSON body, against a public key you supply or fetch. Pin the key out of band
+// if this matters to you: a key fetched from the same server proves only that the server signed it.
+import { readFileSync } from "node:fs";
+import { createHash, createPublicKey, verify as edVerify } from "node:crypto";
+
+const args = process.argv.slice(2);
+const opt = (k) => { const i = args.indexOf(k); return i >= 0 ? args[i + 1] : null; };
+const file = args.find((a, i) => !a.startsWith("--") && args[i - 1] !== "--pubkey" && args[i - 1] !== "--pubkey-url");
+if (!file) { console.error("usage: audit-verify.mjs [--record] <file.json> [--pubkey file.pem | --pubkey-url url | --no-sig]"); process.exit(1); }
+let doc = JSON.parse(readFileSync(file, "utf8"));
+if (doc.content?.[0]?.text) doc = JSON.parse(doc.content[0].text); // raw MCP tool result
+if (doc.record && doc.digest_sha256 === undefined && doc.signature) doc = { body: doc.record, digest_sha256: doc.digest_sha256, signature: doc.signature }; // export_contract tool output
+const wrapped = doc.body ? doc : null;            // signed wrapper { body, digest_sha256, signature }
+const body = wrapped ? wrapped.body : doc;
+let problems = 0;
+
+// ---- 1. ledger rows (audit export: body.entries; contract record: body.timeline has hash+prev_hash but no canonical) ----
+const canonJson = (v) => v === null || v === undefined || typeof v !== "object" ? JSON.stringify(v === undefined ? null : v) : v instanceof Date ? JSON.stringify(v.toISOString()) : Array.isArray(v) ? "[" + v.map((x) => (x === undefined ? "null" : canonJson(x))).join(",") + "]" : "{" + Object.keys(v).filter((k) => v[k] !== undefined).sort().map((k) => JSON.stringify(k) + ":" + canonJson(v[k])).join(",") + "}";
+const canonical = (e) => e.canonical ?? ((e.prev_hash ?? "") + "|" + String(e.seq) + "|" + e.at_canon + "|" + (e.actor_person ?? "") + "|" + (e.actor_agent ?? "") + "|" + (e.subject_person ?? "") + "|" + e.action + "|" + (e.object_type ?? "") + "|" + (e.object_id ?? "") + "|" + e.payload_text);
+const entries = (body.entries || body.timeline || []).slice().sort((a, b) => Number(a.seq) - Number(b.seq));
+if (entries.length) {
+  let bad = 0, links = 0, gaps = 0, hashed = 0;
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (e.canonical || e.payload_text !== undefined) { hashed++; const h = createHash("sha256").update(canonical(e), "utf8").digest("hex"); if (h !== e.hash) { bad++; console.log("HASH MISMATCH seq " + e.seq + " (" + e.action + ")"); } }
+    if (i > 0) { const prev = entries[i - 1]; if (Number(e.seq) === Number(prev.seq) + 1) { links++; if (e.prev_hash !== prev.hash) { bad++; console.log("BROKEN LINK " + prev.seq + " -> " + e.seq); } } else gaps++; }
+  }
+  problems += bad;
+  console.log((bad ? "LEDGER FAIL" : "ledger ok") + ": " + entries.length + " rows, " + hashed + " hashes recomputed, " + links + " adjacent links checked, " + gaps + " gaps (other objects' rows between; expected)" + (bad ? ", " + bad + " problems" : ""));
+  console.log("  range: seq " + entries[0].seq + " (" + entries[0].at + ") .. seq " + entries.at(-1).seq + " (" + entries.at(-1).at + ")" + (body.for ? " for " + body.for : body.contract ? " for contract " + body.contract.id : ""));
+  if (body.chain) console.log("  server-side chain check over that range: " + (body.chain.intact === true ? "intact" : body.chain.intact === false ? "BROKEN at " + JSON.stringify(body.chain.detail) : "n/a"));
+} else console.log("no ledger rows in this file");
+
+// ---- 2. signature ----
+if (wrapped && !args.includes("--no-sig")) {
+  const digest = createHash("sha256").update(canonJson(wrapped.body)).digest("hex");
+  if (digest !== wrapped.digest_sha256) { problems++; console.log("DIGEST MISMATCH: the body was altered after signing (computed " + digest.slice(0, 16) + "…, file says " + String(wrapped.digest_sha256).slice(0, 16) + "…)"); }
+  else if (!wrapped.signature) console.log("digest ok; no signature (the server had no signing key when this was exported)");
+  else {
+    let pem = null, from = "";
+    if (opt("--pubkey")) { pem = readFileSync(opt("--pubkey"), "utf8"); from = opt("--pubkey"); }
+    else {
+      const url = opt("--pubkey-url") || ((body.server || "https://agent-channel-production.up.railway.app").replace(/\/$/, "") + "/.well-known/agentchan-signing-key.json");
+      try { const j = await (await fetch(url, { signal: AbortSignal.timeout(10000) })).json(); pem = j.public_key_pem; from = url + " (kid " + j.kid + ")"; if (body.signing_key?.public_key_pem && body.signing_key.public_key_pem !== pem) console.log("note: the key embedded in the export differs from the one the server publishes now (rotation?)"); }
+      catch (e) { console.log("could not fetch the public key (" + e.message + "); pass --pubkey <pem> or --no-sig"); }
+    }
+    if (pem) {
+      const ok = edVerify(null, Buffer.from(digest, "hex"), createPublicKey(pem), Buffer.from(wrapped.signature.sig, "base64url"));
+      if (!ok) problems++;
+      console.log((ok ? "signature ok" : "SIGNATURE FAIL") + ": Ed25519 " + wrapped.signature.kid + " signed " + wrapped.signature.signed_at + ", key from " + from);
+    }
+  }
+} else if (wrapped) console.log("signature check skipped (--no-sig)");
+else console.log("unsigned export format (no wrapper); only the ledger rows were checked");
+
+console.log(problems ? "FAIL: " + problems + " problem(s)" : "OK");
+process.exit(problems ? 2 : 0);

package/scripts/cli.mjs

@@ -0,0 +1,16 @@
+// Call one Agent Channel tool from the command line.
+// Usage: AGENTCHAN_TOKEN=ac_... node scripts/cli.mjs <tool> '<json args>'
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const BASE = (process.env.AGENTCHAN_URL || "https://agent-channel-production.up.railway.app").replace(/\/mcp$/, "");
+const token = process.env.AGENTCHAN_TOKEN;
+const [tool, argsJson] = process.argv.slice(2);
+if (!token || !tool) { console.error("usage: AGENTCHAN_TOKEN=ac_... cli.mjs <tool> '<json>'"); process.exit(1); }
+
+const client = new Client({ name: "agentchan-cli", version: "0.0.1" });
+await client.connect(new StreamableHTTPClientTransport(new URL(BASE + "/mcp"), { requestInit: { headers: { authorization: "Bearer " + token } } }));
+const r = await client.callTool({ name: tool, arguments: argsJson ? JSON.parse(argsJson) : {} });
+console.log(r.content?.[0]?.text ?? JSON.stringify(r));
+if (r.isError) process.exitCode = 2;
+await client.close();