@halofy/agent-connect 0.1.0

package/src/install.mjs

@@ -0,0 +1,201 @@
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { chmod, cp, rename, rm, unlink } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { generateInstallationKeyPair } from "./crypto.mjs";
+import { ConnectionStore, defaultRuntimeDirectory, ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
+import { SignedRuntimeTransport } from "./transport.mjs";
+import { INSTALLER_VERSION, RUNTIME_VERSION } from "./version.mjs";
+
+export const CLAUDE_CAPABILITIES = Object.freeze({
+  sessionStart: true,
+  userPromptSubmit: true,
+  stop: true,
+  preCompact: true,
+  sessionEnd: true,
+  subagentStart: true,
+  subagentStop: true,
+  postToolUse: true,
+  postToolUseFailure: true,
+  postToolBatch: true,
+  conversationArchive: true,
+  archiveProtocolV1: true,
+  userMessages: true,
+  assistantMessages: true,
+  toolInputs: true,
+  toolOutputs: true,
+  toolFailures: true,
+  images: false,
+  contextUseEvidence: false,
+  artifactBodies: false,
+  artifactReferences: true,
+  subagents: true,
+  compactionCheckpoints: true,
+  contextRecalled: true,
+});
+
+export async function consumeInstallationClaim({
+  serverUrl,
+  claim,
+  clientKind,
+  publicJwk,
+  installationIdCandidate,
+  proofStorage,
+  installerVersion = INSTALLER_VERSION,
+  pluginVersion = RUNTIME_VERSION,
+  capabilities = CLAUDE_CAPABILITIES,
+  fetchImpl = globalThis.fetch,
+}) {
+  const response = await fetchImpl(`${serverUrl}/v1/agent-installations/claim`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      claim,
+      publicKeyJwk: publicJwk,
+      clientKind,
+      installerVersion,
+      pluginVersion,
+      protocolVersion: "1",
+      capabilities,
+      installationIdCandidate,
+      proofStorage,
+    }),
+  });
+  if (!response.ok) throw new Error(response.status === 429 ? "claim rate limit reached" : "claim unavailable");
+  return response.json();
+}
+
+export async function installLocalConnection({
+  serverUrl,
+  claim,
+  clientKind = "claude-code",
+  root = defaultRuntimeDirectory(),
+  fetchImpl = globalThis.fetch,
+  sendHeartbeat = true,
+}) {
+  if (clientKind !== "claude-code") throw new Error("only the local Claude Code adapter is available");
+  const normalizedServer = new URL(serverUrl);
+  if (normalizedServer.protocol !== "https:" && normalizedServer.hostname !== "localhost" && normalizedServer.hostname !== "127.0.0.1") {
+    throw new Error("installation claims require HTTPS (localhost is allowed for development)");
+  }
+  normalizedServer.pathname = normalizedServer.pathname.replace(/\/+$/, "");
+  const normalizedServerUrl = normalizedServer.toString().replace(/\/$/, "");
+  const store = new ConnectionStore(root);
+  const pendingPath = join(root, `pending-${clientKind}.json`);
+  const priorPending = await readJson(pendingPath);
+  const keyPair = priorPending?.publicJwk && priorPending?.privateJwk
+    ? priorPending
+    : { ...generateInstallationKeyPair(), installationIdCandidate: `local_${randomUUID()}` };
+  const proofStorage = process.platform === "win32" ? "unknown" : "file-0600";
+  if (!priorPending) {
+    // Persist proof material before claim consumption. If the HTTP response is
+    // lost after server commit, retrying the command reuses the same public
+    // thumbprint without ever persisting the claim itself.
+    await writePrivateFile(pendingPath, `${JSON.stringify(keyPair)}\n`);
+  }
+  const consumed = await consumeInstallationClaim({
+    serverUrl: normalizedServerUrl,
+    claim,
+    clientKind,
+    publicJwk: keyPair.publicJwk,
+    installationIdCandidate: keyPair.installationIdCandidate,
+    proofStorage,
+    fetchImpl,
+  });
+  const installationId = consumed.installationId || consumed.installation?.id || consumed.id;
+  if (!installationId) throw new Error("claim response did not contain an installation id");
+  const connection = {
+    version: 1,
+    protocolVersion: "1",
+    installationId,
+    serverUrl: normalizedServerUrl,
+    clientKind,
+    publicJwk: keyPair.publicJwk,
+    privateJwk: keyPair.privateJwk,
+    keyThumbprint: keyPair.thumbprint,
+    capabilities: CLAUDE_CAPABILITIES,
+    installerVersion: INSTALLER_VERSION,
+    pluginVersion: RUNTIME_VERSION,
+    proofStorage,
+    installedAt: new Date().toISOString(),
+  };
+  await store.save(connection);
+  await writePrivateFile(join(root, `active-${clientKind}.json`), `${JSON.stringify({
+    version: 1,
+    installationId,
+    protocolVersion: "1",
+  })}\n`);
+  try { await unlink(pendingPath); } catch (error) { if (error?.code !== "ENOENT") throw error; }
+
+  // A failed heartbeat leaves a valid binding on disk for repair/retry. It is
+  // reported honestly and never converted into an "active" result.
+  let heartbeat = false;
+  if (sendHeartbeat) {
+    try {
+      await new SignedRuntimeTransport(connection, { fetchImpl }).heartbeat(CLAUDE_CAPABILITIES, {
+        pluginVersion: RUNTIME_VERSION,
+        proofStorage,
+        diagnostics: { queueDepth: 0, oldestPendingAt: null, expiredCount: 0 },
+      });
+      heartbeat = true;
+    } catch {
+      heartbeat = false;
+    }
+  }
+  return {
+    installationId,
+    heartbeat,
+    reused: false,
+    proofStorage: connection.proofStorage,
+    connectionPath: store.path(installationId),
+  };
+}
+
+/** Copy the reviewed package out of the transient npx directory. */
+export async function installRuntimeBundle({
+  root = defaultRuntimeDirectory(),
+  sourceRoot = fileURLToPath(new URL("../", import.meta.url)),
+} = {}) {
+  const runtimeRoot = join(root, "runtime", RUNTIME_VERSION);
+  const staging = `${runtimeRoot}.staging-${process.pid}`;
+  await rm(staging, { recursive: true, force: true });
+  await ensurePrivateDirectory(staging);
+  await cp(join(sourceRoot, "src"), join(staging, "src"), { recursive: true, force: false });
+  await cp(join(sourceRoot, "bin"), join(staging, "bin"), { recursive: true, force: false });
+  await rm(runtimeRoot, { recursive: true, force: true });
+  await rename(staging, runtimeRoot);
+  if (process.platform !== "win32") {
+    await chmod(join(runtimeRoot, "bin", "halofy-agent.mjs"), 0o700);
+    await chmod(join(runtimeRoot, "bin", "install.mjs"), 0o700);
+  }
+  return {
+    runtimeRoot,
+    runtimePath: join(runtimeRoot, "bin", "halofy-agent.mjs"),
+  };
+}
+
+export async function heartbeatInstalledConnection({
+  installationId,
+  root = defaultRuntimeDirectory(),
+  fetchImpl = globalThis.fetch,
+}) {
+  const connection = await new ConnectionStore(root).load(installationId);
+  await new SignedRuntimeTransport(connection, { fetchImpl }).heartbeat(connection.capabilities, {
+    pluginVersion: connection.pluginVersion,
+    proofStorage: connection.proofStorage,
+    diagnostics: { queueDepth: 0, oldestPendingAt: null, expiredCount: 0 },
+  });
+  return true;
+}
+
+export function localMcpSnippet({ nodePath = process.execPath, proxyPath, installationId }) {
+  return {
+    mcpServers: {
+      halofy: {
+        type: "stdio",
+        command: resolve(nodePath),
+        args: [resolve(proxyPath), "mcp", "--connection", installationId],
+      },
+    },
+  };
+}

package/src/installer-cli.mjs

@@ -0,0 +1,144 @@
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { resolve } from "node:path";
+import {
+  heartbeatInstalledConnection,
+  installLocalConnection,
+  installRuntimeBundle,
+  localMcpSnippet,
+} from "./install.mjs";
+import { configureClaudeProject } from "./claude-config.mjs";
+import { defaultRuntimeDirectory } from "./storage.mjs";
+import { DISCLOSURE_VERSION, INSTALLER_VERSION } from "./version.mjs";
+
+export function parseInstallerArgs(argv) {
+  const command = argv[0];
+  const clientKind = argv[1];
+  const values = new Map();
+  for (let index = 2; index < argv.length; index += 1) {
+    const name = argv[index];
+    if (!["--server", "--claim", "--claude-project"].includes(name) || values.has(name)) {
+      throw new Error("unsupported or duplicate installer argument");
+    }
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) throw new Error(`${name} requires a value`);
+    values.set(name, value);
+    index += 1;
+  }
+  const serverUrl = values.get("--server");
+  const claim = values.get("--claim");
+  if (command !== "install" || clientKind !== "claude-code" || !serverUrl || !claim ||
+      !/^hsc_[A-Za-z0-9_-]{43}$/.test(claim)) {
+    throw new Error("Usage: agent-connect install claude-code --server <https-url> --claim <one-use-claim>");
+  }
+  return {
+    clientKind,
+    serverUrl,
+    claim,
+    projectRoot: resolve(values.get("--claude-project") || process.cwd()),
+  };
+}
+
+export function detectClaudeCode() {
+  const result = spawnSync("claude", ["--version"], {
+    encoding: "utf8",
+    shell: false,
+    timeout: 10_000,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) throw new Error("Claude Code was not found on PATH");
+  const version = String(result.stdout || result.stderr || "").trim().slice(0, 128);
+  return version || "detected";
+}
+
+export function disclosureText({ serverUrl, projectRoot, claudeVersion }) {
+  return [
+    "Halofy Claude Code lifecycle connection",
+    `Installer: @halofy/agent-connect@${INSTALLER_VERSION}`,
+    `Server: ${new URL(serverUrl).origin}`,
+    `Claude Code: ${claudeVersion}`,
+    `Project: ${projectRoot}`,
+    "",
+    "This single installation replaces an existing Halofy bearer MCP entry in this project and enables:",
+    "- governed memory tools and recall",
+    "- prompts and assistant responses exposed by Claude's transcript hooks,",
+    "- supported tool inputs/results/failures, subagents, compaction, and session end,",
+    "- encrypted local retry queue and governed retained conversations, and",
+    "- canonical learning when the selected badge permits writes.",
+    "",
+    "Images and artifact bodies are recorded as explicit unsupported placeholders; coverage may be Partial.",
+    "Authorized organization managers may review retained conversations and summaries.",
+    "This does not scan historical files, other applications, clipboard, keystrokes, or other agents.",
+    "Disconnecting stops future capture but does not erase retained data.",
+    `Disclosure: ${DISCLOSURE_VERSION}`,
+  ].join("\n");
+}
+
+export async function confirmDisclosure({ input = process.stdin, output = process.stdout } = {}) {
+  if (!input.isTTY || !output.isTTY) throw new Error("interactive terminal confirmation is required");
+  const prompt = createInterface({ input, output });
+  try {
+    const answer = await prompt.question("\nType CONNECT to install conversation capture and memory: ");
+    if (answer.trim() !== "CONNECT") throw new Error("installation was not confirmed");
+  } finally {
+    prompt.close();
+  }
+  return true;
+}
+
+export async function runInstaller(argv, {
+  root = defaultRuntimeDirectory(),
+  output = process.stdout,
+  detectClaude = detectClaudeCode,
+  confirm = confirmDisclosure,
+  fetchImpl = globalThis.fetch,
+  sourceRoot,
+  claudeConfigPath,
+} = {}) {
+  const input = parseInstallerArgs(argv);
+  const claudeVersion = await detectClaude();
+  output.write(`${disclosureText({ ...input, claudeVersion })}\n`);
+  await confirm();
+
+  const installed = await installLocalConnection({
+    serverUrl: input.serverUrl,
+    claim: input.claim,
+    clientKind: input.clientKind,
+    root,
+    fetchImpl,
+    sendHeartbeat: false,
+  });
+  const bundle = await installRuntimeBundle({ root, ...(sourceRoot ? { sourceRoot } : {}) });
+  const configured = await configureClaudeProject({
+    projectRoot: input.projectRoot,
+    installationId: installed.installationId,
+    serverUrl: input.serverUrl,
+    runtimePath: bundle.runtimePath,
+    ...(claudeConfigPath ? { claudeConfigPath } : {}),
+  });
+  let heartbeat = false;
+  try {
+    heartbeat = await heartbeatInstalledConnection({
+      installationId: installed.installationId,
+      root,
+      fetchImpl,
+    });
+  } catch {
+    heartbeat = false;
+  }
+  return {
+    status: heartbeat ? "configured_heartbeat_verified" : "configured_heartbeat_unavailable",
+    installationId: installed.installationId,
+    proofStorage: installed.proofStorage,
+    installerVersion: INSTALLER_VERSION,
+    publishedPackage: true,
+    projectConfigured: true,
+    configuredPaths: [configured.mcpPath, configured.settingsPath],
+    replacedLegacyMcpEntries: configured.replacedLegacyMcpEntries,
+    mcpConfiguration: localMcpSnippet({
+      proxyPath: bundle.runtimePath,
+      installationId: installed.installationId,
+    }),
+    nextStep: "Restart Claude Code in this project, then check the connection in Halofy.",
+  };
+}

package/src/mcp-proxy.mjs

@@ -0,0 +1,94 @@
+import { createInterface } from "node:readline";
+import { SignedRuntimeTransport } from "./transport.mjs";
+
+function sseMessages(text) {
+  return text.split(/\r?\n\r?\n/).flatMap((event) => {
+    const data = event.split(/\r?\n/)
+      .filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice(5).trim())
+      .join("\n");
+    return data ? [data] : [];
+  });
+}
+
+async function relayResponse(response, parsed, output) {
+  if (response.status === 202 || response.status === 204) return;
+  const text = await response.text();
+  const payloads = (response.headers.get("content-type") || "").includes("text/event-stream")
+    ? sseMessages(text)
+    : [text];
+  for (const payload of payloads) if (payload.trim()) output.write(`${payload.trim()}\n`);
+}
+
+export async function runStdioMcpProxy(connection, {
+  input = process.stdin,
+  output = process.stdout,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const transport = new SignedRuntimeTransport(connection, { fetchImpl, timeoutMs: 30_000 });
+  let mcpSessionId = null;
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let parsed;
+    try { parsed = JSON.parse(line); } catch { continue; }
+    try {
+      const response = await transport.request("/mcp", {
+        body: JSON.stringify(parsed),
+        headers: {
+          Accept: "application/json, text/event-stream",
+          ...(mcpSessionId ? { "Mcp-Session-Id": mcpSessionId } : {}),
+        },
+        raw: true,
+      });
+      mcpSessionId = response.headers.get("mcp-session-id") || mcpSessionId;
+      await relayResponse(response, parsed, output);
+    } catch {
+      if (parsed.id !== undefined) {
+        output.write(`${JSON.stringify({
+          jsonrpc: "2.0",
+          id: parsed.id,
+          error: { code: -32000, message: "Halofy MCP transport unavailable" },
+        })}\n`);
+      }
+    }
+  }
+}
+
+
+/** Compatibility bridge for existing HALOMEM_URL + HALOMEM_API_KEY users. */
+export async function runLegacyStdioMcpProxy({ url, key }, {
+  input = process.stdin,
+  output = process.stdout,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  let mcpSessionId = null;
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let parsed;
+    try { parsed = JSON.parse(line); } catch { continue; }
+    try {
+      const response = await fetchImpl(`${url}/mcp`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${key}`,
+          "Content-Type": "application/json",
+          Accept: "application/json, text/event-stream",
+          ...(mcpSessionId ? { "Mcp-Session-Id": mcpSessionId } : {}),
+        },
+        body: JSON.stringify(parsed),
+      });
+      if (!response.ok) throw new Error("legacy MCP transport rejected");
+      mcpSessionId = response.headers.get("mcp-session-id") || mcpSessionId;
+      await relayResponse(response, parsed, output);
+    } catch {
+      if (parsed.id !== undefined) {
+        output.write(`${JSON.stringify({ jsonrpc: "2.0", id: parsed.id, error: {
+          code: -32000,
+          message: "Halofy MCP transport unavailable",
+        } })}\n`);
+      }
+    }
+  }
+}

package/src/queue.mjs

@@ -0,0 +1,183 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { ensurePrivateDirectory, fileExists, withFileLock, writePrivateFile } from "./storage.mjs";
+
+export class QueueOverflowError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QueueOverflowError";
+    this.code = "queue_overflow";
+  }
+}
+
+async function loadOrCreateKey(path) {
+  if (await fileExists(path)) {
+    const key = await readFile(path);
+    if (key.length !== 32) throw new Error("invalid local queue key");
+    return key;
+  }
+  const key = randomBytes(32);
+  try {
+    await writePrivateFile(path, key);
+    return key;
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    return readFile(path);
+  }
+}
+
+function encrypt(key, state) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const ciphertext = Buffer.concat([cipher.update(JSON.stringify(state)), cipher.final()]);
+  return JSON.stringify({
+    version: 1,
+    algorithm: "aes-256-gcm",
+    iv: iv.toString("base64url"),
+    tag: cipher.getAuthTag().toString("base64url"),
+    ciphertext: ciphertext.toString("base64url"),
+  });
+}
+
+function decrypt(key, envelope) {
+  const parsed = JSON.parse(envelope);
+  if (parsed.version !== 1 || parsed.algorithm !== "aes-256-gcm") throw new Error("unsupported queue envelope");
+  const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(parsed.iv, "base64url"));
+  decipher.setAuthTag(Buffer.from(parsed.tag, "base64url"));
+  return JSON.parse(Buffer.concat([
+    decipher.update(Buffer.from(parsed.ciphertext, "base64url")),
+    decipher.final(),
+  ]).toString("utf8"));
+}
+
+export class BoundedEncryptedQueue {
+  constructor(root, {
+    maxEntries = 5_000,
+    maxPlaintextBytes = 8 * 1024 * 1024,
+    maxAgeMs = 7 * 24 * 60 * 60 * 1_000,
+  } = {}) {
+    this.root = root;
+    this.path = join(root, "pending.queue.enc");
+    this.keyPath = join(root, "pending.queue.key");
+    this.lockPath = join(root, "pending.queue.lock");
+    this.maxEntries = maxEntries;
+    this.maxPlaintextBytes = maxPlaintextBytes;
+    this.maxAgeMs = maxAgeMs;
+  }
+
+  async #read() {
+    await ensurePrivateDirectory(dirname(this.path));
+    const key = await loadOrCreateKey(this.keyPath);
+    if (!(await fileExists(this.path))) return { version: 1, items: [], expiredCount: 0 };
+    const state = decrypt(key, await readFile(this.path, "utf8"));
+    return { version: 1, items: state.items || [], expiredCount: state.expiredCount || 0 };
+  }
+
+  #sweep(state) {
+    const cutoff = Date.now() - this.maxAgeMs;
+    const retained = [];
+    let expired = 0;
+    for (const item of state.items) {
+      const created = Date.parse(item.createdAt);
+      if (Number.isFinite(created) && created < cutoff) expired += 1;
+      else retained.push(item);
+    }
+    state.items = retained;
+    state.expiredCount = Number(state.expiredCount || 0) + expired;
+    return expired;
+  }
+
+  async #write(state) {
+    const serialized = JSON.stringify(state);
+    if (state.items.length > this.maxEntries || Buffer.byteLength(serialized) > this.maxPlaintextBytes) {
+      throw new QueueOverflowError("local lifecycle queue is full; no event was discarded");
+    }
+    const key = await loadOrCreateKey(this.keyPath);
+    await writePrivateFile(this.path, encrypt(key, state));
+  }
+
+  async enqueue(item) {
+    return withFileLock(this.lockPath, async () => {
+      const state = await this.#read();
+      if (!item?.id) throw new Error("queue item requires an id");
+      if (!state.items.some((existing) => existing.id === item.id)) state.items.push(item);
+      await this.#write(state);
+      return state.items.length;
+    });
+  }
+
+  async peek() {
+    return withFileLock(this.lockPath, async () => {
+      const state = await this.#read();
+      if (this.#sweep(state) > 0) await this.#write(state);
+      return state.items[0] ?? null;
+    });
+  }
+
+  async replaceHead(item) {
+    return withFileLock(this.lockPath, async () => {
+      const state = await this.#read();
+      if (state.items.length === 0) return;
+      if (item) state.items[0] = item;
+      else state.items.shift();
+      await this.#write(state);
+    });
+  }
+
+  async diagnostics() {
+    return withFileLock(this.lockPath, async () => {
+      const state = await this.#read();
+      if (this.#sweep(state) > 0) await this.#write(state);
+      return {
+        depth: state.items.length,
+        oldestPendingAt: state.items[0]?.createdAt ?? null,
+        expiredCount: state.expiredCount,
+      };
+    });
+  }
+
+  async enqueueSessionEvents(sessionHash, events, {
+    maxBatchEvents = 100,
+    maxBatchBytes = 1024 * 1024,
+    acknowledgedSequence = 0,
+  } = {}) {
+    return withFileLock(this.lockPath, async () => {
+      const state = await this.#read();
+      this.#sweep(state);
+      const pending = state.items.filter((item) => item.sessionHash === sessionHash).flatMap((item) => item.events || []);
+      const existingKeys = new Set(pending.map((event) => event.eventKey));
+      let sequence = pending.reduce(
+        (maximum, event) => Math.max(maximum, Number(event.sequence) || 0),
+        acknowledgedSequence,
+      );
+      const unique = [];
+      for (const event of events) {
+        if (existingKeys.has(event.eventKey)) continue;
+        existingKeys.add(event.eventKey);
+        unique.push({ ...event, sequence: ++sequence });
+      }
+      for (let offset = 0; offset < unique.length;) {
+        const batch = [];
+        let batchBytes = 0;
+        while (offset < unique.length && batch.length < maxBatchEvents) {
+          const event = unique[offset];
+          const eventBytes = Buffer.byteLength(JSON.stringify(event));
+          if (batch.length > 0 && batchBytes + eventBytes > maxBatchBytes) break;
+          if (eventBytes > maxBatchBytes) {
+            throw new QueueOverflowError("one normalized event exceeds the append body limit");
+          }
+          batch.push(event);
+          batchBytes += eventBytes;
+          offset += 1;
+        }
+        const id = createHash("sha256")
+          .update(`${sessionHash}\0${batch.map((event) => event.eventKey).join("\0")}`)
+          .digest("hex");
+        state.items.push({ id, createdAt: new Date().toISOString(), sessionHash, events: batch });
+      }
+      await this.#write(state);
+      return { queued: unique.length, lastSequence: sequence };
+    });
+  }
+}