@halofy/agent-connect 0.1.0

package/src/session.mjs

@@ -0,0 +1,465 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readJson, withFileLock, writePrivateFile } from "./storage.mjs";
+
+// This is the complete serialized payload limit, not merely the body limit.
+// It leaves the event envelope inside the server's 64 KiB inline-event bound.
+export const MAX_CLAUDE_EVENT_PAYLOAD_BYTES = 64 * 1024;
+const MAX_TOOL_NAME_CHARS = 300;
+const MAX_RECENT_EVENT_KEYS = 4_096;
+
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function boundedIdentifier(value, limit = MAX_TOOL_NAME_CHARS) {
+  return String(value ?? "").slice(0, limit);
+}
+
+function reasonCode(value) {
+  return String(value ?? "capture_unavailable")
+    .toLowerCase()
+    .replace(/[^a-z0-9_.-]/g, "_")
+    .slice(0, 64) || "capture_unavailable";
+}
+
+function boundedEventKey(value) {
+  const key = String(value);
+  return key.length <= 256 ? key : `claude-key:${digest(key)}`;
+}
+
+function stableClone(value) {
+  if (Array.isArray(value)) return value.map(stableClone);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableClone(value[key])]));
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableClone(value)) ?? "null";
+}
+
+function containsInlineArtifactBody(value) {
+  if (Array.isArray(value)) return value.some(containsInlineArtifactBody);
+  if (!value || typeof value !== "object") return false;
+  if (["image", "document", "artifact", "file"].includes(value.type)) {
+    const source = value.source && typeof value.source === "object" ? value.source : {};
+    if (typeof source.data === "string" || typeof value.data === "string") return true;
+  }
+  return Object.values(value).some(containsInlineArtifactBody);
+}
+
+function bodyBytes(value, format) {
+  if (format === "utf8") return Buffer.from(String(value), "utf8");
+  return Buffer.from(stableJson(value), "utf8");
+}
+
+function digestOnlyPayload({
+  role = null,
+  body,
+  format = "json",
+  status = "unsupported",
+  reason,
+  extra = {},
+}) {
+  const bytes = Buffer.isBuffer(body) ? body : bodyBytes(body, format);
+  return {
+    ...(role ? { role } : {}),
+    contentFormat: "digest_only",
+    captureStatus: status,
+    captureReasonCode: reasonCode(reason),
+    bodySha256: digest(bytes),
+    originalBytes: bytes.length,
+    ...extra,
+  };
+}
+
+function boundedCompletePayload(payload, { role, body, format = "json", extra = {} } = {}) {
+  if (Buffer.byteLength(JSON.stringify(payload)) <= MAX_CLAUDE_EVENT_PAYLOAD_BYTES) return payload;
+  return digestOnlyPayload({
+    role,
+    body: body ?? payload,
+    format,
+    status: "truncated",
+    reason: "inline_body_too_large",
+    extra,
+  });
+}
+
+function normalizedEvent({ eventKey, type, occurredAt, payload, sourceEndOffset }) {
+  const {
+    role,
+    contentFormat = "json",
+    captureStatus = "complete",
+    captureReasonCode,
+    text,
+    ...structuredPayload
+  } = payload;
+  const wirePayload = contentFormat === "utf8" ? text : structuredPayload;
+  return {
+    eventKey: boundedEventKey(eventKey),
+    type,
+    occurredAt,
+    ...(role ? { role } : {}),
+    contentFormat,
+    captureStatus,
+    ...(captureReasonCode ? { captureReasonCode } : {}),
+    payload: wirePayload,
+    payloadSha256: digest(contentFormat === "utf8" ? wirePayload : JSON.stringify(wirePayload)),
+    ...(sourceEndOffset ? { sourceEndOffset } : {}),
+  };
+}
+
+function nativeEntryId(entry, evidence) {
+  return entry?.uuid || entry?.message_id || entry?.message?.id ||
+    `offset-${evidence.byteOffset}-${digest(evidence.rawBytes ?? stableJson(entry)).slice(0, 16)}`;
+}
+
+function textEvent({ nativeId, index, role, text, occurredAt, sourceEndOffset }) {
+  const payload = boundedCompletePayload({
+    role,
+    contentFormat: "utf8",
+    captureStatus: "complete",
+    text,
+  }, { role, body: text, format: "utf8" });
+  return normalizedEvent({
+    eventKey: `claude:${nativeId}:message:${index}`,
+    type: "message",
+    occurredAt,
+    payload,
+    sourceEndOffset,
+  });
+}
+
+function toolEvent({ nativeId, index, type, role = "tool", toolName, toolUseId, body, occurredAt, sourceEndOffset, failed = false }) {
+  const field = type === "tool_call" ? "input" : "result";
+  const stableBody = stableClone(body ?? null);
+  const toolMetadata = {
+    toolName: boundedIdentifier(toolName),
+    toolUseId: boundedIdentifier(toolUseId),
+    ...(type === "tool_result" ? { failed: Boolean(failed) } : {}),
+  };
+  const completePayload = {
+    role,
+    contentFormat: "json",
+    captureStatus: "complete",
+    ...toolMetadata,
+    [field]: stableBody,
+  };
+  const payload = containsInlineArtifactBody(stableBody)
+    ? digestOnlyPayload({
+      role,
+      body: stableBody,
+      status: "unsupported",
+      reason: "unsupported_artifact_body",
+      extra: toolMetadata,
+    })
+    : boundedCompletePayload(completePayload, {
+      role,
+      body: stableBody,
+      format: "json",
+      extra: toolMetadata,
+    });
+  const stableToolId = boundedIdentifier(toolUseId, 256);
+  return normalizedEvent({
+    eventKey: stableToolId
+      ? `claude-tool:${stableToolId}:${type === "tool_call" ? "call" : "result"}`
+      : `claude:${nativeId}:${type}:${index}`,
+    type,
+    occurredAt,
+    payload,
+    sourceEndOffset,
+  });
+}
+
+function base64Bytes(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length % 4 === 1 ||
+      !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) return null;
+  try { return Buffer.from(value, "base64"); } catch { return null; }
+}
+
+function artifactEvent({ nativeId, index, role, block, occurredAt, sourceEndOffset }) {
+  const source = block?.source && typeof block.source === "object" ? block.source : {};
+  const mediaType = boundedIdentifier(source.media_type || block.media_type, 256);
+  const reference = source.path || source.url || source.file_id || block.path || block.url || block.file_id;
+  if (typeof reference === "string" && reference.length > 0 && source.data === undefined && block.data === undefined) {
+    const payload = boundedCompletePayload({
+      role,
+      contentFormat: "artifact_ref",
+      captureStatus: "complete",
+      artifactKind: boundedIdentifier(block.type || "artifact", 100),
+      mediaType,
+      referenceType: boundedIdentifier(source.type || "host", 100),
+      reference,
+    }, { role, body: reference, format: "utf8", extra: { artifactKind: "artifact", mediaType } });
+    return normalizedEvent({
+      eventKey: `claude:${nativeId}:artifact:${index}`,
+      type: "artifact",
+      occurredAt,
+      payload,
+      sourceEndOffset,
+    });
+  }
+  const encoded = source.data ?? block.data;
+  const decoded = base64Bytes(encoded);
+  const body = decoded ?? Buffer.from(typeof encoded === "string" ? encoded : stableJson(block), "utf8");
+  const payload = digestOnlyPayload({
+    role,
+    body,
+    status: "unsupported",
+    reason: decoded ? "artifact_upload_unavailable" : "unsupported_artifact_body",
+    extra: {
+      artifactKind: boundedIdentifier(block.type || "artifact", 100),
+      mediaType,
+      referenceType: boundedIdentifier(source.type || "unknown", 100),
+    },
+  });
+  return normalizedEvent({
+    eventKey: `claude:${nativeId}:artifact:${index}`,
+    type: "artifact",
+    occurredAt,
+    payload,
+    sourceEndOffset,
+  });
+}
+
+function unsupportedBlockEvent({ nativeId, index, role, block, occurredAt, sourceEndOffset }) {
+  return normalizedEvent({
+    eventKey: `claude:${nativeId}:unsupported:${index}`,
+    type: "message",
+    occurredAt,
+    payload: digestOnlyPayload({
+      role,
+      body: block,
+      status: "unsupported",
+      reason: `unsupported_claude_content_${boundedIdentifier(block?.type || "unknown", 80)}`,
+    }),
+    sourceEndOffset,
+  });
+}
+
+export function deriveSessionHash({ installationId, clientKind, hostSessionId }) {
+  if (!installationId || !clientKind || !hostSessionId) throw new Error("session identity is incomplete");
+  return digest(`halofy-session-v1\0${installationId}\0${clientKind}\0${hostSessionId}`);
+}
+
+export function stripInjectedContext(value) {
+  // Content delimiters are forgeable by the user and by recalled text. Claude
+  // delivers hook `additionalContext` outside the user message, while this
+  // normalizer admits only native transcript records, so loop filtering is
+  // structural and must never delete delimiter-shaped user text.
+  return String(value);
+}
+
+/**
+ * Normalize one current Claude transcript record into zero or more archive
+ * events. Text is never trimmed or prefix-truncated. Unsupported/oversized
+ * bodies become explicit digest-only events, so advancing the byte cursor
+ * cannot silently turn a capture gap into success.
+ */
+export function normalizeClaudeTranscriptEntry(entry, evidence) {
+  const message = entry?.message;
+  if (!message || !["user", "assistant"].includes(message.role)) return [];
+  const role = message.role;
+  const occurredAt = entry.timestamp || evidence.occurredAt;
+  const sourceEndOffset = evidence.endOffset;
+  const nativeId = nativeEntryId(entry, evidence);
+  if (typeof message.content === "string") {
+    return [textEvent({ nativeId, index: 0, role, text: message.content, occurredAt, sourceEndOffset })];
+  }
+  if (!Array.isArray(message.content)) {
+    return [unsupportedBlockEvent({
+      nativeId,
+      index: 0,
+      role,
+      block: message.content,
+      occurredAt,
+      sourceEndOffset,
+    })];
+  }
+  if (message.content.length === 0) {
+    return [textEvent({ nativeId, index: 0, role, text: "", occurredAt, sourceEndOffset })];
+  }
+  return message.content.map((block, index) => {
+    if (!block || typeof block !== "object") {
+      return unsupportedBlockEvent({ nativeId, index, role, block, occurredAt, sourceEndOffset });
+    }
+    if (block.type === "text" && typeof block.text === "string") {
+      return textEvent({ nativeId, index, role, text: block.text, occurredAt, sourceEndOffset });
+    }
+    if (block.type === "tool_use") {
+      return toolEvent({
+        nativeId,
+        index,
+        type: "tool_call",
+        toolName: block.name,
+        toolUseId: block.id,
+        body: block.input,
+        occurredAt,
+        sourceEndOffset,
+      });
+    }
+    if (block.type === "tool_result") {
+      return toolEvent({
+        nativeId,
+        index,
+        type: "tool_result",
+        toolName: block.name,
+        toolUseId: block.tool_use_id,
+        body: block.content,
+        occurredAt,
+        sourceEndOffset,
+        failed: block.is_error,
+      });
+    }
+    if (["image", "document", "artifact", "file"].includes(block.type)) {
+      return artifactEvent({ nativeId, index, role, block, occurredAt, sourceEndOffset });
+    }
+    return unsupportedBlockEvent({ nativeId, index, role, block, occurredAt, sourceEndOffset });
+  });
+}
+
+export function normalizeMalformedClaudeTranscriptLine(rawBytes, evidence) {
+  const bytes = Buffer.isBuffer(rawBytes) ? rawBytes : Buffer.from(rawBytes, "utf8");
+  const payload = digestOnlyPayload({
+    body: bytes,
+    status: "missing",
+    reason: "malformed_transcript_record",
+  });
+  return normalizedEvent({
+    eventKey: `claude-malformed:${evidence.byteOffset}:${payload.bodySha256}`,
+    type: "checkpoint",
+    occurredAt: evidence.occurredAt,
+    payload,
+    sourceEndOffset: evidence.endOffset,
+  });
+}
+
+export function normalizeClaudeHookEvent(type, input, { sessionHash, sequence }) {
+  const occurredAt = new Date().toISOString();
+  const nativeId = input.event_id || `${sessionHash}:${sequence}`;
+  let event;
+  switch (type) {
+    case "tool_call":
+      event = toolEvent({
+        nativeId,
+        index: 0,
+        type,
+        toolName: input.tool_name ?? input.name,
+        toolUseId: input.tool_use_id ?? input.id,
+        body: input.tool_input ?? input.input,
+        occurredAt,
+      });
+      break;
+    case "tool_result":
+      event = toolEvent({
+        nativeId,
+        index: 0,
+        type,
+        toolName: input.tool_name ?? input.name,
+        toolUseId: input.tool_use_id ?? input.id,
+        body: input.tool_response ?? input.tool_result ?? input.output ?? input.error,
+        occurredAt,
+        failed: Boolean(input.tool_error || input.error || input.is_error),
+      });
+      break;
+    case "compaction": {
+      const payload = {
+        contentFormat: "json",
+        captureStatus: "complete",
+        trigger: boundedIdentifier(input.trigger, 100) || "host",
+      };
+      event = normalizedEvent({ eventKey: `claude-hook:compaction:${nativeId}`, type, occurredAt, payload });
+      break;
+    }
+    case "checkpoint": {
+      const payload = {
+        contentFormat: "json",
+        captureStatus: "complete",
+        boundary: boundedIdentifier(input.hook_event_name, 100) || "host",
+      };
+      event = normalizedEvent({ eventKey: `claude-hook:checkpoint:${nativeId}`, type, occurredAt, payload });
+      break;
+    }
+    default:
+      throw new Error(`unsupported normalized hook event: ${type}`);
+  }
+  return { ...event, sequence };
+}
+
+export async function readClaudeTranscriptSuffix(path, cursor, sessionHash) {
+  const bytes = await readFile(path);
+  const start = Number.isSafeInteger(cursor?.byteOffset) && cursor.byteOffset <= bytes.length ? cursor.byteOffset : 0;
+  const suffix = bytes.subarray(start);
+  const events = [];
+  let position = 0;
+  while (position < suffix.length) {
+    const newline = suffix.indexOf(0x0a, position);
+    if (newline === -1) break; // keep an incomplete JSONL record for the next hook
+    const endOffset = start + newline + 1;
+    const rawBytes = suffix.subarray(position, newline);
+    const raw = rawBytes.toString("utf8");
+    const byteOffset = start + position;
+    position = newline + 1;
+    if (!raw.trim()) continue;
+    const evidence = {
+      sessionHash,
+      byteOffset,
+      endOffset,
+      rawBytes,
+      occurredAt: new Date().toISOString(),
+    };
+    try {
+      events.push(...normalizeClaudeTranscriptEntry(JSON.parse(raw), evidence));
+    } catch {
+      events.push(normalizeMalformedClaudeTranscriptLine(rawBytes, evidence));
+    }
+  }
+  return { events, observedEndOffset: start + position };
+}
+
+export class CursorStore {
+  constructor(root) {
+    this.path = join(root, "cursors.json");
+    this.lockPath = join(root, "cursors.lock");
+  }
+
+  async get(sessionHash) {
+    const state = await readJson(this.path, { version: 1, sessions: {} });
+    return {
+      byteOffset: 0,
+      sequence: 0,
+      committedSequence: 0,
+      recentEventKeys: [],
+      ...(state.sessions[sessionHash] ?? {}),
+    };
+  }
+
+  async update(sessionHash, patch) {
+    return withFileLock(this.lockPath, async () => {
+      const state = await readJson(this.path, { version: 1, sessions: {} });
+      state.sessions[sessionHash] = { ...(state.sessions[sessionHash] ?? {}), ...patch };
+      await writePrivateFile(this.path, `${JSON.stringify(state)}\n`);
+      return state.sessions[sessionHash];
+    });
+  }
+
+  async rememberEventKeys(sessionHash, eventKeys) {
+    if (!Array.isArray(eventKeys) || eventKeys.length === 0) return this.get(sessionHash);
+    return withFileLock(this.lockPath, async () => {
+      const state = await readJson(this.path, { version: 1, sessions: {} });
+      const current = {
+        byteOffset: 0,
+        sequence: 0,
+        committedSequence: 0,
+        recentEventKeys: [],
+        ...(state.sessions[sessionHash] ?? {}),
+      };
+      const recent = [...(Array.isArray(current.recentEventKeys) ? current.recentEventKeys : []), ...eventKeys];
+      current.recentEventKeys = [...new Set(recent)].slice(-MAX_RECENT_EVENT_KEYS);
+      state.sessions[sessionHash] = current;
+      await writePrivateFile(this.path, `${JSON.stringify(state)}\n`);
+      return current;
+    });
+  }
+}

package/src/storage.mjs

@@ -0,0 +1,108 @@
+import { constants } from "node:fs";
+import { access, chmod, mkdir, open, readFile, rename, stat, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir, platform } from "node:os";
+import { randomBytes } from "node:crypto";
+
+export function defaultRuntimeDirectory() {
+  if (process.env.HALOFY_AGENT_HOME) return process.env.HALOFY_AGENT_HOME;
+  if (platform() === "win32") {
+    return join(process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local"), "Halofy", "agent-runtime");
+  }
+  return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "halofy", "agent-runtime");
+}
+
+export async function ensurePrivateDirectory(path) {
+  await mkdir(path, { recursive: true, mode: 0o700 });
+  if (platform() !== "win32") await chmod(path, 0o700);
+}
+
+export async function writePrivateFile(path, value) {
+  await ensurePrivateDirectory(dirname(path));
+  const temporary = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(value);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await rename(temporary, path);
+  if (platform() !== "win32") await chmod(path, 0o600);
+}
+
+export async function withFileLock(path, action, { timeoutMs = 3_000, staleMs = 30_000 } = {}) {
+  await ensurePrivateDirectory(dirname(path));
+  const started = Date.now();
+  while (true) {
+    let handle;
+    try {
+      handle = await open(path, "wx", 0o600);
+      await handle.writeFile(`${process.pid}\n`);
+      return await action();
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      try {
+        const lock = await stat(path);
+        if (Date.now() - lock.mtimeMs > staleMs) await unlink(path);
+      } catch (statError) {
+        if (statError?.code !== "ENOENT") throw statError;
+      }
+      if (Date.now() - started >= timeoutMs) throw new Error("local runtime storage is busy");
+      await new Promise((resolve) => setTimeout(resolve, 15));
+    } finally {
+      if (handle) {
+        await handle.close();
+        try { await unlink(path); } catch (error) { if (error?.code !== "ENOENT") throw error; }
+      }
+    }
+  }
+}
+
+export async function readJson(path, fallback = null) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return fallback;
+    throw error;
+  }
+}
+
+export async function fileExists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export class ConnectionStore {
+  constructor(root = defaultRuntimeDirectory()) {
+    this.root = root;
+  }
+
+  path(id) {
+    if (!/^[A-Za-z0-9_-]{1,160}$/.test(id)) throw new Error("invalid installation id");
+    return join(this.root, "connections", `${id}.json`);
+  }
+
+  async save(connection) {
+    if (!connection?.installationId || !connection?.privateJwk) throw new Error("incomplete connection");
+    await writePrivateFile(this.path(connection.installationId), `${JSON.stringify(connection, null, 2)}\n`);
+  }
+
+  async load(id) {
+    const connection = await readJson(this.path(id));
+    if (!connection) throw new Error(`connection ${id} is not installed`);
+    return connection;
+  }
+
+  async remove(id) {
+    try {
+      await unlink(this.path(id));
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+  }
+}

package/src/transport.mjs

@@ -0,0 +1,78 @@
+import { signInstallationRequest } from "./crypto.mjs";
+
+function contentType(response) {
+  return response.headers.get("content-type") || "";
+}
+
+export class RuntimeHttpError extends Error {
+  constructor(status, code, detail = null) {
+    super(`Halofy runtime request failed (${status}${code ? `: ${code}` : ""})`);
+    this.name = "RuntimeHttpError";
+    this.status = status;
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+export class SignedRuntimeTransport {
+  constructor(connection, { fetchImpl = globalThis.fetch, timeoutMs = 8_000 } = {}) {
+    this.connection = connection;
+    this.fetch = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async request(path, { method = "POST", body, headers = {}, raw = false } = {}) {
+    const bodyBytes = body === undefined
+      ? Buffer.alloc(0)
+      : Buffer.from(typeof body === "string" || Buffer.isBuffer(body) ? body : JSON.stringify(body));
+    const proof = signInstallationRequest({
+      installationId: this.connection.installationId,
+      privateJwk: this.connection.privateJwk,
+      method,
+      path,
+      bodyBytes,
+    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await this.fetch(`${this.connection.serverUrl}${path}`, {
+        method,
+        headers: {
+          ...proof.headers,
+          ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+          ...headers,
+        },
+        body: body === undefined ? undefined : bodyBytes,
+        signal: controller.signal,
+      });
+      if (!response.ok) {
+        let detail = null;
+        try { detail = await response.json(); } catch { /* content-free fallback */ }
+        throw new RuntimeHttpError(response.status, detail?.code || "request_rejected", detail);
+      }
+      if (raw) return response;
+      if (response.status === 204 || !contentType(response).includes("json")) return null;
+      return response.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  heartbeat(capabilities, { pluginVersion, proofStorage, diagnostics }) {
+    return this.request("/v1/agent-runtime/heartbeat", {
+      body: { pluginVersion, capabilities, proofStorage, ...(diagnostics ? { diagnostics } : {}) },
+    });
+  }
+
+  openSession(body) { return this.request("/v1/agent-sessions/open", { body }); }
+  appendEvents(sessionId, events) { return this.request(`/v1/agent-sessions/${encodeURIComponent(sessionId)}/events`, { body: { events } }); }
+  recall(sessionId, body) { return this.request(`/v1/agent-sessions/${encodeURIComponent(sessionId)}/recall`, { body }); }
+  contextUsed(sessionId, body) { return this.request(`/v1/agent-sessions/${encodeURIComponent(sessionId)}/context-used`, { body }); }
+  commit(sessionId, throughSequence, reason) {
+    return this.request(`/v1/agent-sessions/${encodeURIComponent(sessionId)}/commits`, { body: { throughSequence, reason } });
+  }
+  commitStatus(commitId) { return this.request(`/v1/agent-session-commits/${encodeURIComponent(commitId)}`, { method: "GET" }); }
+  close(sessionId, body = {}) {
+    return this.request(`/v1/agent-sessions/${encodeURIComponent(sessionId)}/close`, { body });
+  }
+}

package/src/version.mjs

@@ -0,0 +1,4 @@
+export const PACKAGE_NAME = "@halofy/agent-connect";
+export const INSTALLER_VERSION = "0.1.0";
+export const RUNTIME_VERSION = "0.1.0";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-28";