@ctliz/agent-intercom-claude 0.12.0-connect.3

package/claude/native-bridge.ts

@@ -0,0 +1,219 @@
+import type { Server } from "node:net";
+import { join } from "node:path";
+import { IntercomClient } from "../broker/client.ts";
+import { spawnBrokerIfNeeded } from "../broker/spawn.ts";
+import { INTERCOM_SCOPE_ENV, intercomScopeIdFromEnvForRegistration, parseIntercomScopeIdForRegistration } from "../protocol-v4/contract.ts";
+import { loadConfig } from "../config.ts";
+import type { Message, SessionInfo } from "../types.ts";
+import { formatAttachments, formatSessionDisplay } from "./runtime.ts";
+import {
+  bindNativeClaudeSocket,
+  buildNativeReceipt,
+  claudeNativeSocketDir,
+  deregisterNativeClaudePeer,
+  nativePeerNameBySocket,
+  registerNativeClaudePeer,
+  sendNativeClaudeMessage,
+  sendNativeFrame,
+  stripNativeEnvelope,
+  updateNativeClaudePeer,
+  type NativeProtocolPaths,
+} from "./native-protocol.ts";
+
+interface NativeBridgeClient {
+  sessionId: string | null;
+  on(event: "message", listener: (from: SessionInfo, message: Message, deliveryId: string) => void): unknown;
+  on(event: "disconnected", listener: (error: Error) => void): unknown;
+  connect(registration: {
+    name: string;
+    cwd: string;
+    model: string;
+    pid: number;
+    startedAt: number;
+    lastActivity: number;
+    status: string;
+  }, sessionId?: string): Promise<void>;
+  disconnect(): Promise<void>;
+  acknowledgeMessage(deliveryId: string): void;
+  send(to: string, message: { text: string; replyTo?: string }): Promise<{ delivered: boolean; reason?: string }>;
+  updatePresence(update: { status?: string }): void;
+}
+
+export interface NativeClaudeBridgeIdentity {
+  id: string;
+  name: string;
+  cwd: string;
+  model?: string;
+  pid?: number;
+}
+
+export interface NativeClaudeBrokerBridgeOptions extends NativeProtocolPaths {
+  client?: NativeBridgeClient;
+  prepareConnection?: () => Promise<void>;
+  socketPath?: string;
+  sendNative?: typeof sendNativeClaudeMessage;
+  sendFrame?: typeof sendNativeFrame;
+  scopeId?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+interface PendingRelay {
+  from: SessionInfo;
+  message: Message;
+}
+
+function closeServer(server: Server): Promise<void> {
+  return new Promise((resolve) => server.close(() => resolve()));
+}
+
+function nativePrompt(from: SessionInfo, message: Message): string {
+  const reply = message.expectsReply
+    ? "\n\nThe sender is blocking. After acting, use Claude's built-in SendMessage tool to reply to this same native peer. A normal assistant response stays local and will not unblock the sender."
+    : "\n\nAct if needed. To acknowledge or report a result, use Claude's built-in SendMessage tool to reply to this same native peer; a normal assistant response stays local.";
+  return [
+    `[Intercom message from ${formatSessionDisplay(from)} (${from.id})]`,
+    message.content.text,
+    formatAttachments(message.content.attachments),
+    reply,
+  ].join("\n");
+}
+
+/**
+ * Broker identity for one live Claude Code process. Broker messages are injected
+ * through Claude's native cross-session socket; native replies are relayed back
+ * through the broker while preserving blocking ask correlation.
+ */
+export class NativeClaudeBrokerBridge {
+  private readonly client: NativeBridgeClient;
+  private readonly prepareConnection: () => Promise<void>;
+  private readonly sendNative: typeof sendNativeClaudeMessage;
+  private readonly sendFrame: typeof sendNativeFrame;
+  private readonly pid: number;
+  private readonly socketPath: string;
+  private server?: Server;
+  private targetSocket = "";
+  private pending: PendingRelay[] = [];
+  private started = false;
+
+  constructor(
+    private readonly identity: NativeClaudeBridgeIdentity,
+    private readonly options: NativeClaudeBrokerBridgeOptions = {},
+  ) {
+    const scopeId = options.scopeId === undefined
+      ? intercomScopeIdFromEnvForRegistration(options.env ?? process.env)
+      : parseIntercomScopeIdForRegistration(options.scopeId);
+    const scopeEnv = scopeId === undefined ? {} : { [INTERCOM_SCOPE_ENV]: scopeId };
+    this.client = options.client ?? new IntercomClient({ env: scopeEnv });
+    this.prepareConnection = options.prepareConnection ?? (async () => {
+      const config = loadConfig();
+      await spawnBrokerIfNeeded(config.brokerCommand, config.brokerArgs);
+    });
+    this.sendNative = options.sendNative ?? sendNativeClaudeMessage;
+    this.sendFrame = options.sendFrame ?? sendNativeFrame;
+    this.pid = identity.pid ?? process.pid;
+    this.socketPath = options.socketPath ?? join(claudeNativeSocketDir(options), `agent-intercom-${this.pid}.sock`);
+  }
+
+  get nativeSocketPath(): string {
+    return this.socketPath;
+  }
+
+  async start(targetSocket: string): Promise<void> {
+    if (this.started) {
+      this.targetSocket = targetSocket;
+      return;
+    }
+    this.targetSocket = targetSocket;
+    this.server = await bindNativeClaudeSocket(this.socketPath, (frame) => this.handleNativeFrame(frame));
+    await registerNativeClaudePeer({
+      pid: this.pid,
+      sessionId: this.identity.id,
+      name: `${this.identity.name} bridge`,
+      cwd: this.identity.cwd,
+      socketPath: this.socketPath,
+      status: "idle",
+      registryDir: this.options.registryDir,
+    });
+    await this.prepareConnection();
+    this.client.on("message", (from, message, deliveryId) => {
+      void this.handleBrokerMessage(from, message, deliveryId);
+    });
+    this.client.on("disconnected", () => {
+      void updateNativeClaudePeer(this.pid, { status: "broker disconnected" }, this.options.registryDir);
+    });
+    await this.client.connect({
+      name: this.identity.name,
+      cwd: this.identity.cwd,
+      model: this.identity.model ?? "claude",
+      pid: this.pid,
+      startedAt: Date.now(),
+      lastActivity: Date.now(),
+      status: "idle",
+    }, this.identity.id);
+    this.started = true;
+  }
+
+  private async handleBrokerMessage(from: SessionInfo, message: Message, deliveryId: string): Promise<void> {
+    try {
+      this.client.updatePresence({ status: "active" });
+      await this.sendNative({
+        socketPath: this.targetSocket,
+        body: nativePrompt(from, message),
+        from: `uds:${this.socketPath}`,
+        fromName: this.identity.name,
+      });
+      this.pending.push({ from, message });
+      this.client.acknowledgeMessage(deliveryId);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      this.client.updatePresence({ status: `native delivery error: ${reason}` });
+      if (message.expectsReply) {
+        await this.client.send(from.id, { text: `Native Claude delivery failed: ${reason}`, replyTo: message.id }).catch(() => undefined);
+      }
+    }
+  }
+
+  private handleNativeFrame(frame: Record<string, unknown>): void {
+    if (frame.type !== "user") return;
+    const message = frame.message;
+    if (typeof message !== "object" || message === null || !("content" in message)) return;
+    const envelope = stripNativeEnvelope((message as { content?: unknown }).content);
+    if (!envelope.body) return;
+    const relay = this.pending.shift();
+    const fromAddress = typeof frame.from === "string" ? frame.from : envelope.from;
+    if (fromAddress?.startsWith("uds:")) {
+      void this.sendFrame(fromAddress.slice(4), buildNativeReceipt({
+        status: "delivered",
+        from: `uds:${this.socketPath}`,
+        originalMessageId: typeof frame.msg_id === "string" ? frame.msg_id : undefined,
+        reason: "Relayed to Agent Intercom.",
+      })).catch(() => undefined);
+    }
+    if (!relay) return;
+    void this.client.send(relay.from.id, {
+      text: envelope.body,
+      ...(relay.message.expectsReply ? { replyTo: relay.message.id } : {}),
+    }).then(() => {
+      this.client.updatePresence({ status: "idle" });
+    }).catch(() => undefined);
+  }
+
+  async stop(): Promise<void> {
+    this.started = false;
+    this.pending = [];
+    await this.client.disconnect().catch(() => undefined);
+    if (this.server) await closeServer(this.server).catch(() => undefined);
+    this.server = undefined;
+    await deregisterNativeClaudePeer(this.pid, this.socketPath, this.options.registryDir);
+  }
+}
+
+export function nativeClaudeSenderName(frame: Record<string, unknown>, registryDir?: string): string | undefined {
+  const message = frame.message;
+  const content = typeof message === "object" && message !== null && "content" in message
+    ? (message as { content?: unknown }).content
+    : undefined;
+  const envelope = stripNativeEnvelope(content);
+  const from = typeof frame.from === "string" ? frame.from : envelope.from;
+  return from?.startsWith("uds:") ? nativePeerNameBySocket(from.slice(4), registryDir) ?? envelope.fromName : envelope.fromName;
+}

package/claude/native-protocol.ts

@@ -0,0 +1,346 @@
+// Native Claude Code cross-session protocol, adapted from pi-claude-link's MIT implementation.
+// The protocol is intentionally isolated from the broker so compatibility can be version-gated.
+import { randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { chmod, mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import { readFileSync, readdirSync } from "node:fs";
+import { connect, createServer, type Server, type Socket } from "node:net";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+export function claudeNativeRegistryDir(
+  env: NodeJS.ProcessEnv = process.env,
+  home = homedir(),
+): string {
+  return join(env.CLAUDE_CONFIG_DIR || join(home, ".claude"), "sessions");
+}
+
+export const DEFAULT_CLAUDE_SESSION_REGISTRY = claudeNativeRegistryDir();
+export const MAX_NATIVE_FRAME_LINE = 1024 * 1024;
+
+export interface NativeClaudePeer {
+  pid?: number;
+  sessionId?: string;
+  name: string;
+  cwd: string;
+  status: string;
+  kind?: string;
+  startedAt?: number;
+  socketPath: string;
+  live?: boolean;
+}
+
+export interface NativeClaudeUserFrame {
+  msgV: 1;
+  msg_id: string;
+  type: "user";
+  priority: string;
+  from?: string;
+  session_id?: string;
+  message: { role: "user"; content: string };
+  [key: string]: unknown;
+}
+
+export interface NativeProtocolPaths {
+  registryDir?: string;
+  socketDir?: string;
+}
+
+export function claudeNativeSocketDir(paths: NativeProtocolPaths = {}): string {
+  if (paths.socketDir) return paths.socketDir;
+  const registryDir = paths.registryDir ?? DEFAULT_CLAUDE_SESSION_REGISTRY;
+  try {
+    for (const file of readdirSync(registryDir)) {
+      if (!/^\d+\.json$/.test(file)) continue;
+      let entry: Record<string, unknown>;
+      try {
+        entry = JSON.parse(readFileSync(join(registryDir, file), "utf8")) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (typeof entry.messagingSocketPath === "string" && entry.messagingSocketPath.endsWith(".sock")) {
+        return dirname(entry.messagingSocketPath);
+      }
+    }
+  } catch {
+    // Registry may not exist before the first Claude process starts.
+  }
+  return join(process.env.XDG_RUNTIME_DIR || "/tmp", "cc-socks");
+}
+
+export function nativeSocketLive(socketPath: string, timeoutMs = 250): Promise<boolean> {
+  return new Promise((resolve) => {
+    if (!socketPath) return resolve(false);
+    const socket = connect({ path: socketPath });
+    let settled = false;
+    const done = (live: boolean) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(live);
+    };
+    socket.setTimeout(timeoutMs, () => done(false));
+    socket.on("connect", () => done(true));
+    socket.on("error", () => done(false));
+  });
+}
+
+export async function listNativeClaudeSessions(options: NativeProtocolPaths & { excludeSocket?: string } = {}): Promise<NativeClaudePeer[]> {
+  const registryDir = options.registryDir ?? DEFAULT_CLAUDE_SESSION_REGISTRY;
+  let files: string[];
+  try {
+    files = await readdir(registryDir);
+  } catch {
+    return [];
+  }
+  const peers: NativeClaudePeer[] = [];
+  for (const file of files) {
+    if (!/^\d+\.json$/.test(file)) continue;
+    let entry: Record<string, unknown>;
+    try {
+      entry = JSON.parse(await readFile(join(registryDir, file), "utf8")) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    const socketPath = typeof entry.messagingSocketPath === "string" ? entry.messagingSocketPath : "";
+    if (!socketPath || socketPath === options.excludeSocket) continue;
+    peers.push({
+      pid: typeof entry.pid === "number" ? entry.pid : undefined,
+      sessionId: typeof entry.sessionId === "string" ? entry.sessionId : undefined,
+      name: typeof entry.name === "string" ? entry.name : `pid ${String(entry.pid ?? "unknown")}`,
+      cwd: typeof entry.cwd === "string" ? entry.cwd : "?",
+      status: typeof entry.status === "string" ? entry.status : "unknown",
+      kind: typeof entry.kind === "string" ? entry.kind : undefined,
+      startedAt: typeof entry.startedAt === "number" ? entry.startedAt : undefined,
+      socketPath,
+    });
+  }
+  await Promise.all(peers.map(async (peer) => { peer.live = await nativeSocketLive(peer.socketPath); }));
+  return peers.filter((peer) => peer.live).sort((left, right) => (right.startedAt ?? 0) - (left.startedAt ?? 0));
+}
+
+export async function waitForNativeClaudePeer(
+  pid: number,
+  options: NativeProtocolPaths & { timeoutMs?: number; intervalMs?: number } = {},
+): Promise<NativeClaudePeer> {
+  const timeoutMs = options.timeoutMs ?? 5000;
+  const intervalMs = options.intervalMs ?? 50;
+  const deadline = Date.now() + timeoutMs;
+  do {
+    const peer = (await listNativeClaudeSessions(options)).find((candidate) => candidate.pid === pid);
+    if (peer) return peer;
+    if (Date.now() >= deadline) break;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  } while (true);
+  throw new Error(`Claude process ${pid} did not publish a live native messaging socket within ${timeoutMs}ms`);
+}
+
+export async function resolveNativeClaudeTarget(
+  nameOrId: string,
+  options: NativeProtocolPaths & { excludeSocket?: string } = {},
+): Promise<{ target?: NativeClaudePeer; error?: string; candidates?: string[] }> {
+  const peers = await listNativeClaudeSessions(options);
+  let target = peers.find((peer) => peer.sessionId === nameOrId) ?? peers.find((peer) => peer.name === nameOrId);
+  if (!target) {
+    const prefixMatches = peers.filter((peer) => peer.name.startsWith(nameOrId));
+    if (prefixMatches.length === 1) target = prefixMatches[0];
+    else if (prefixMatches.length > 1) return { error: `ambiguous: ${prefixMatches.map((peer) => peer.name).join(", ")}` };
+  }
+  if (!target) return { error: `no live Claude session matches "${nameOrId}"`, candidates: peers.map((peer) => peer.name) };
+  return { target };
+}
+
+const ENVELOPE_TAG = "cross-session-message";
+const escapeEnvelopeBody = (body: string) => body.replace(new RegExp(`</(?=${ENVELOPE_TAG}(?:[>\\s/]|$))`, "gi"), "<\\/");
+const unescapeEnvelopeBody = (body: string) => body.replace(new RegExp(`<\\\\/(?=${ENVELOPE_TAG}(?:[>\\s/]|$))`, "gi"), "</");
+
+export function buildNativeEnvelope(options: { from?: string; fromName?: string; fromMode?: string; body: string }): string {
+  const attributes: string[] = [];
+  if (options.from) attributes.push(`from="${options.from}"`);
+  if (options.fromName) attributes.push(`from-name="${options.fromName.replace(/["<>]/g, "")}"`);
+  if (options.fromMode) attributes.push(`from-mode="${options.fromMode}"`);
+  return `<${ENVELOPE_TAG}${attributes.length ? ` ${attributes.join(" ")}` : ""}>\n${escapeEnvelopeBody(options.body)}\n</${ENVELOPE_TAG}>`;
+}
+
+export function stripNativeEnvelope(content: unknown): { body: string; from?: string; fromName?: string; fromMode?: string } {
+  if (typeof content !== "string") return { body: "" };
+  const match = content.match(new RegExp(`^<${ENVELOPE_TAG}((?:\\s+[a-z-]+="[^"]*")*)>\\n([\\s\\S]*)\\n</${ENVELOPE_TAG}>$`));
+  if (!match) return { body: content };
+  const attributes: Record<string, string> = {};
+  for (const attribute of match[1]!.matchAll(/([a-z-]+)="([^"]*)"/g)) attributes[attribute[1]!] = attribute[2]!;
+  return {
+    body: unescapeEnvelopeBody(match[2]!),
+    from: attributes.from,
+    fromName: attributes["from-name"],
+    fromMode: attributes["from-mode"],
+  };
+}
+
+export function buildNativeUserFrame(options: { content: string; from?: string; priority?: string; sessionId?: string }): NativeClaudeUserFrame {
+  return {
+    msgV: 1,
+    msg_id: randomUUID(),
+    type: "user",
+    priority: options.priority || "next",
+    ...(options.from ? { from: options.from } : {}),
+    ...(options.sessionId ? { session_id: options.sessionId } : {}),
+    message: { role: "user", content: options.content },
+  };
+}
+
+export function sendNativeFrame(socketPath: string, frame: unknown, timeoutMs = 5000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const socket = connect({ path: socketPath });
+    socket.setTimeout(timeoutMs, () => {
+      socket.destroy();
+      reject(new Error(`timed out connecting to ${socketPath}`));
+    });
+    socket.once("error", reject);
+    socket.once("connect", () => socket.end(`${JSON.stringify(frame)}\n`, () => {
+      const id = typeof frame === "object" && frame !== null && "msg_id" in frame ? String(frame.msg_id) : "";
+      resolve(id);
+    }));
+  });
+}
+
+export function sendNativeClaudeMessage(options: {
+  socketPath: string;
+  body: string;
+  from?: string;
+  fromName?: string;
+  priority?: string;
+}): Promise<string> {
+  const content = buildNativeEnvelope({ from: options.from, fromName: options.fromName, body: options.body });
+  return sendNativeFrame(options.socketPath, buildNativeUserFrame({ content, from: options.from, priority: options.priority }));
+}
+
+export function buildNativeReceipt(options: { status: string; from?: string; originalMessageId?: string; reason?: string }): Record<string, unknown> {
+  return {
+    msgV: 1,
+    msg_id: randomUUID(),
+    type: "control",
+    action: "peer_message_status",
+    status: options.status,
+    ...(options.reason ? { reason: options.reason } : {}),
+    ...(options.from ? { from: options.from } : {}),
+    ...(options.originalMessageId ? { orig_msg_id: options.originalMessageId } : {}),
+  };
+}
+
+export async function bindNativeClaudeSocket(socketPath: string, onFrame: (frame: Record<string, unknown>, connection: Socket) => void): Promise<Server> {
+  const directory = dirname(socketPath);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700).catch(() => undefined);
+  await unlink(socketPath).catch(() => undefined);
+  const server = createServer((connection) => {
+    connection.setEncoding("utf8");
+    let buffer = "";
+    connection.on("data", (chunk: string) => {
+      buffer += chunk;
+      if (buffer.length > MAX_NATIVE_FRAME_LINE) {
+        buffer = "";
+        connection.destroy();
+        return;
+      }
+      let newline: number;
+      while ((newline = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        if (!line.trim()) continue;
+        try {
+          const frame = JSON.parse(line) as Record<string, unknown>;
+          onFrame(frame, connection);
+        } catch {
+          // Ignore malformed or handler-failing frames, matching Claude's peer behavior.
+        }
+      }
+    });
+    connection.on("end", () => connection.end());
+    connection.on("error", () => undefined);
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => {
+      server.removeListener("error", reject);
+      resolve();
+    });
+  });
+  await chmod(socketPath, 0o600).catch(() => undefined);
+  return server;
+}
+
+function processStart(pid: number): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    execFile("ps", ["-o", "lstart=", "-p", String(pid)], (error, stdout) => resolve(error ? undefined : stdout.trim() || undefined));
+  });
+}
+
+export async function registerNativeClaudePeer(options: {
+  pid: number;
+  sessionId?: string;
+  name: string;
+  cwd: string;
+  socketPath: string;
+  status?: string;
+  registryDir?: string;
+}): Promise<string> {
+  const registryDir = options.registryDir ?? DEFAULT_CLAUDE_SESSION_REGISTRY;
+  await mkdir(registryDir, { recursive: true, mode: 0o700 });
+  const sessionId = options.sessionId || randomUUID();
+  const entry = {
+    pid: options.pid,
+    sessionId,
+    cwd: options.cwd || process.cwd(),
+    startedAt: Date.now(),
+    procStart: await processStart(options.pid),
+    version: "agent-intercom-claude",
+    peerProtocol: 1,
+    kind: "interactive",
+    entrypoint: "agent-intercom",
+    messagingSocketPath: options.socketPath,
+    name: options.name,
+    nameSource: "explicit",
+    status: options.status || "idle",
+  };
+  await writeFile(join(registryDir, `${options.pid}.json`), `${JSON.stringify(entry, null, 2)}\n`, { mode: 0o600 });
+  return sessionId;
+}
+
+export async function updateNativeClaudePeer(pid: number, patch: Record<string, unknown>, registryDir = DEFAULT_CLAUDE_SESSION_REGISTRY): Promise<void> {
+  const path = join(registryDir, `${pid}.json`);
+  let current: Record<string, unknown>;
+  try {
+    current = JSON.parse(await readFile(path, "utf8")) as Record<string, unknown>;
+  } catch {
+    return;
+  }
+  await writeFile(path, `${JSON.stringify({ ...current, ...patch }, null, 2)}\n`, { mode: 0o600 });
+}
+
+export async function deregisterNativeClaudePeer(pid: number, socketPath?: string, registryDir = DEFAULT_CLAUDE_SESSION_REGISTRY): Promise<void> {
+  await unlink(join(registryDir, `${pid}.json`)).catch(() => undefined);
+  if (socketPath) await unlink(socketPath).catch(() => undefined);
+}
+
+export function nativePeerNameBySocket(socketPath: string, registryDir = DEFAULT_CLAUDE_SESSION_REGISTRY): string | undefined {
+  if (!socketPath) return undefined;
+  try {
+    for (const file of readdirSync(registryDir)) {
+      if (!/^\d+\.json$/.test(file)) continue;
+      let entry: Record<string, unknown>;
+      try {
+        entry = JSON.parse(readFileSync(join(registryDir, file), "utf8")) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (entry.messagingSocketPath === socketPath && typeof entry.name === "string") return entry.name;
+    }
+  } catch {
+    // Missing registry has no matching peer.
+  }
+  return undefined;
+}
+
+export function nativeSlugFromCwd(cwd: string): string {
+  return (basename(cwd || "claude") || "claude").replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 32);
+}