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

package/claude/cli-runner.ts

@@ -0,0 +1,220 @@
+import { spawn } from "node:child_process";
+import {
+  assertNoPermissionOverrides,
+  bindHardenedClaudePaths,
+  resolveClaudePermissionPolicy,
+  type ClaudePermissionCeiling,
+  type ClaudePermissionMode,
+} from "./permission-policy.ts";
+
+export interface ClaudeTurnOptions {
+  prompt: string;
+  cwd: string;
+  sessionId?: string;
+  model?: string;
+  appendSystemPrompt?: string;
+  permissionMode?: ClaudePermissionMode;
+  dangerouslySkipPermissions?: boolean;
+  permissionCeiling?: ClaudePermissionCeiling;
+  addDirs?: string[];
+  mcpConfig?: string;
+  claudeCommand?: string;
+  extraArgs?: string[];
+  env?: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export interface ClaudeTurnResult {
+  sessionId: string | null;
+  result: string;
+  isError: boolean;
+  raw: unknown;
+}
+
+interface PreparedClaudeLaunch {
+  args: string[];
+  cwd: string;
+  release(): void;
+}
+
+function prepareClaudeLaunch(options: ClaudeTurnOptions): PreparedClaudeLaunch {
+  const args: string[] = ["-p", "--output-format", "json"];
+  const permission = resolveClaudePermissionPolicy({
+    permissionMode: options.permissionMode,
+    dangerouslySkipPermissions: options.dangerouslySkipPermissions,
+    ceiling: options.permissionCeiling,
+  });
+  assertNoPermissionOverrides(options.extraArgs ?? [], "extraArgs", permission.ceiling);
+
+  let cwd = options.cwd;
+  let addDirs = options.addDirs ?? [];
+  let release = () => {};
+  if (permission.ceiling === "read-only") {
+    if (options.mcpConfig !== undefined) {
+      throw new Error("mcpConfig cannot add an arbitrary MCP capability to a hardened Claude role");
+    }
+    const binding = bindHardenedClaudePaths(options.cwd, addDirs);
+    cwd = binding.cwd;
+    addDirs = binding.addDirs;
+    release = binding.release;
+    // --bare prevents ambient project/user customizations and hooks from
+    // widening a hardened launch. Explicit broker-owned inputs are appended
+    // below after the permission boundary has been fixed.
+    args.push("--bare");
+  }
+
+  if (options.sessionId) {
+    args.push("--resume", options.sessionId);
+  }
+  if (options.model) {
+    args.push("--model", options.model);
+  }
+  if (options.appendSystemPrompt) {
+    args.push("--append-system-prompt", options.appendSystemPrompt);
+  }
+  if (permission.dangerouslySkipPermissions) {
+    args.push("--dangerously-skip-permissions");
+  } else if (permission.permissionMode && (
+    permission.ceiling === "read-only" || options.permissionMode !== undefined
+  )) {
+    args.push("--permission-mode", permission.permissionMode);
+  }
+  for (const dir of addDirs) {
+    args.push("--add-dir", dir);
+  }
+  if (options.mcpConfig) {
+    args.push("--mcp-config", options.mcpConfig);
+  }
+  if (options.extraArgs?.length) {
+    args.push(...options.extraArgs);
+  }
+
+  return { args, cwd, release };
+}
+
+export function buildClaudeArgs(options: ClaudeTurnOptions): string[] {
+  const launch = prepareClaudeLaunch(options);
+  try {
+    return launch.args;
+  } finally {
+    launch.release();
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function runClaudeTurn(options: ClaudeTurnOptions): Promise<ClaudeTurnResult> {
+  return new Promise((resolve, reject) => {
+    const command = options.claudeCommand ?? "claude";
+    const launch = prepareClaudeLaunch(options);
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(command, launch.args, {
+        cwd: launch.cwd,
+        env: { ...process.env, ...options.env },
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } finally {
+      // Directory descriptors remain open across the synchronous spawn setup,
+      // narrowing replacement races without leaking them for the turn.
+      launch.release();
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timeoutHandle: NodeJS.Timeout | undefined;
+
+    const cleanup = () => {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
+      options.signal?.removeEventListener("abort", onAbort);
+    };
+
+    const finishReject = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+
+    const finishResolve = (result: ClaudeTurnResult) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(result);
+    };
+
+    const onAbort = () => {
+      child.kill("SIGTERM");
+      finishReject(new Error("Claude turn aborted"));
+    };
+
+    if (options.signal) {
+      if (options.signal.aborted) {
+        child.kill("SIGTERM");
+        finishReject(new Error("Claude turn aborted"));
+        return;
+      }
+      options.signal.addEventListener("abort", onAbort, { once: true });
+    }
+
+    if (options.timeoutMs) {
+      timeoutHandle = setTimeout(() => {
+        child.kill("SIGTERM");
+        finishReject(new Error(`Claude turn timed out after ${options.timeoutMs}ms`));
+      }, options.timeoutMs);
+    }
+
+    child.on("error", (error) => {
+      finishReject(new Error(`Failed to spawn "${command}": ${error.message}`, { cause: error }));
+    });
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+
+    child.on("close", (exitCode) => {
+      if (settled) return;
+
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(stdout.trim());
+      } catch {
+        const fallback = stdout.trim() || stderr.trim();
+        finishResolve({
+          sessionId: options.sessionId ?? null,
+          result: fallback,
+          isError: exitCode !== 0,
+          raw: stdout,
+        });
+        return;
+      }
+
+      if (isRecord(parsed) && typeof parsed.result === "string") {
+        finishResolve({
+          sessionId: typeof parsed.session_id === "string" ? parsed.session_id : null,
+          result: parsed.result,
+          isError: Boolean(parsed.is_error),
+          raw: parsed,
+        });
+        return;
+      }
+
+      finishResolve({
+        sessionId: options.sessionId ?? null,
+        result: stdout.trim(),
+        isError: exitCode !== 0,
+        raw: parsed,
+      });
+    });
+
+    child.stdin?.write(options.prompt);
+    child.stdin?.end();
+  });
+}

package/claude/contact.ts

@@ -0,0 +1,33 @@
+import { spawn, spawnSync } from "node:child_process";
+import type { SessionInfo } from "../types.ts";
+
+export function formatContactInstruction(current: SessionInfo, sessions: SessionInfo[]): string {
+  const name = current.name?.trim();
+  const duplicate = Boolean(name && sessions.some((session) => session.id !== current.id && session.name?.trim().toLowerCase() === name.toLowerCase()));
+  return name && !duplicate
+    ? `Intercom target: ${name}\nStable session ID: ${current.id}`
+    : `Intercom target: ${current.id}`;
+}
+
+export function copyTextToClipboard(text: string): boolean {
+  const candidates: Array<[string, string[]]> = process.platform === "darwin"
+    ? [["pbcopy", []]]
+    : process.platform === "win32"
+      ? [["clip.exe", []]]
+      : [
+          ...(process.env.WAYLAND_DISPLAY ? [["wl-copy", []] as [string, string[]]] : []),
+          ...(process.env.DISPLAY ? [["xclip", ["-selection", "clipboard"]] as [string, string[]], ["xsel", ["--clipboard", "--input"]] as [string, string[]]] : []),
+          ["clip.exe", []],
+        ];
+  for (const [command, args] of candidates) {
+    if (spawnSync("which", [command], { stdio: "ignore" }).status !== 0) continue;
+    if (command === "wl-copy") {
+      const child = spawn(command, args, { stdio: ["pipe", "ignore", "ignore"] });
+      child.stdin.end(text);
+      child.unref();
+      return true;
+    }
+    if (spawnSync(command, args, { input: text, stdio: ["pipe", "ignore", "ignore"] }).status === 0) return true;
+  }
+  return false;
+}

package/claude/inbox-monitor.ts

@@ -0,0 +1,49 @@
+// Plugin monitor entry point (auto-armed by monitors/monitors.json in TUI mode).
+// Tails the session's intercom inbox and prints one line per NEW inbound
+// message. Claude Code's Monitor machinery injects each stdout line into the
+// live session as an event the model acts on. Pre-existing backlog is skipped
+// so only messages that arrive after the session starts wake it.
+import { existsSync, readFileSync } from "node:fs";
+import { setTimeout as delay } from "node:timers/promises";
+import { basename } from "node:path";
+import { formatInboxLine, inboxBatchFrom } from "./inbox.ts";
+
+const POLL_MS = 1000;
+
+function readContent(path: string): string {
+  try {
+    return existsSync(path) ? readFileSync(path, "utf-8") : "";
+  } catch {
+    return "";
+  }
+}
+
+export async function runInboxMonitor(path: string, signal?: { aborted: boolean }): Promise<void> {
+  // Start after the current backlog so only new messages are surfaced.
+  let emitted = inboxBatchFrom(readContent(path), 0).total;
+  for (;;) {
+    if (signal?.aborted) return;
+    const { entries, total } = inboxBatchFrom(readContent(path), emitted);
+    for (const entry of entries) {
+      process.stdout.write(`${formatInboxLine(entry)}\n`);
+    }
+    emitted = total;
+    await delay(POLL_MS);
+  }
+}
+
+async function main(): Promise<void> {
+  const path = process.env.CLAUDE_INTERCOM_INBOX || process.argv[2];
+  if (!path) {
+    process.stderr.write("inbox-monitor: no inbox path (set CLAUDE_INTERCOM_INBOX or pass a path)\n");
+    process.exit(1);
+  }
+  await runInboxMonitor(path);
+}
+
+if (process.argv[1] && (basename(process.argv[1]) === "inbox-monitor.ts" || basename(process.argv[1]) === "inbox-monitor.mjs")) {
+  void main().catch((error) => {
+    process.stderr.write(`inbox-monitor: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  });
+}

package/claude/inbox.ts

@@ -0,0 +1,77 @@
+// Durable per-session inbox used by the live TUI mode (`cci --tui`).
+//
+// In TUI mode a single live `claude` session owns the broker identity (via the
+// intercom MCP server). That MCP server appends each inbound message to this
+// JSONL inbox file, and a plugin monitor tails the file and injects new lines
+// into the live session. This keeps one broker connection per identity while
+// still delivering unprompted wakes into an interactive session.
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getIntercomDirPath, INTERCOM_RUNTIME_FILE_MODE } from "../broker/paths.ts";
+import type { Message, SessionInfo } from "../types.ts";
+
+export interface InboxEntry {
+  ts: number;
+  fromId: string;
+  fromName?: string;
+  messageId: string;
+  replyTo?: string;
+  expectsReply: boolean;
+  text: string;
+}
+
+export function sanitizeInboxSegment(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase() || "session";
+}
+
+export function defaultInboxPath(sessionId: string, intercomDir: string = getIntercomDirPath()): string {
+  return join(intercomDir, `inbox-${sanitizeInboxSegment(sessionId)}.jsonl`);
+}
+
+export function toInboxEntry(from: SessionInfo, message: Message, now: number = Date.now()): InboxEntry {
+  return {
+    ts: now,
+    fromId: from.id,
+    ...(from.name ? { fromName: from.name } : {}),
+    messageId: message.id,
+    ...(message.replyTo ? { replyTo: message.replyTo } : {}),
+    expectsReply: Boolean(message.expectsReply),
+    text: message.content.text,
+  };
+}
+
+export function appendInboxMessage(path: string, from: SessionInfo, message: Message): void {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(toInboxEntry(from, message))}\n`, {
+    encoding: "utf-8",
+    mode: INTERCOM_RUNTIME_FILE_MODE,
+  });
+}
+
+/** Human/Claude-facing single line the monitor emits for a new inbound message. */
+export function formatInboxLine(entry: InboxEntry): string {
+  const who = entry.fromName ? `${entry.fromName} (${entry.fromId.slice(0, 8)})` : entry.fromId;
+  const kind = entry.expectsReply ? " [asking — awaiting your reply]" : "";
+  const oneLine = entry.text.replace(/\s+/g, " ").trim();
+  return `Intercom message from ${who}${kind}: ${oneLine}`;
+}
+
+/**
+ * Pure monitor helper: given full inbox file contents and how many lines were
+ * already emitted, return the new entries plus the updated line count. Resets
+ * when the file shrank (truncation/rotation).
+ */
+export function inboxBatchFrom(content: string, alreadyEmitted: number): { entries: InboxEntry[]; total: number } {
+  const lines = content.split("\n").map((line) => line.trim()).filter(Boolean);
+  const total = lines.length;
+  const start = alreadyEmitted <= total ? alreadyEmitted : 0;
+  const entries: InboxEntry[] = [];
+  for (let index = start; index < total; index += 1) {
+    try {
+      entries.push(JSON.parse(lines[index]) as InboxEntry);
+    } catch {
+      // Skip a torn/partial line; it will be complete on the next poll.
+    }
+  }
+  return { entries, total };
+}

package/claude/mcp-protocol.ts

@@ -0,0 +1,253 @@
+import type { ClaudeIntercomRuntime, ToolResult } from "./runtime.ts";
+import { validateAskTimeoutMs } from "../config.ts";
+import type { Attachment } from "../types.ts";
+import { hasExactDataKeys, isDenseArrayOf } from "../broker/validation.ts";
+
+interface JsonRpcRequest {
+  jsonrpc?: string;
+  id?: string | number | null;
+  method?: string;
+  params?: Record<string, unknown>;
+}
+
+type RequestId = string | number;
+type ToolHandler = (args: Record<string, unknown>, signal?: AbortSignal) => Promise<ToolResult>;
+
+interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: ToolHandler;
+}
+
+const inflightToolCalls = new Map<RequestId, AbortController>();
+
+function asString(value: unknown, name: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+function asBoolean(value: unknown, defaultValue: boolean): boolean {
+  return typeof value === "boolean" ? value : defaultValue;
+}
+
+function asOptionalPositiveInteger(value: unknown, name: string): number | undefined {
+  if (value === undefined) return undefined;
+  return validateAskTimeoutMs(value, name);
+}
+
+function asAttachmentArray(value: unknown): Attachment[] | undefined {
+  if (value === undefined) return undefined;
+  if (!isDenseArrayOf<unknown>(value, (_entry): _entry is unknown => true)) {
+    throw new Error("attachments must be an exact dense array");
+  }
+  return value.map((item, index) => {
+    if (!hasExactDataKeys(item, ["type", "name", "content"], ["language"])) {
+      throw new Error(`attachments[${index}] must be an exact object`);
+    }
+    const raw = item as Record<string, unknown>;
+    const type = raw.type;
+    if (type !== "file" && type !== "snippet" && type !== "context") throw new Error(`attachments[${index}].type must be file, snippet, or context`);
+    const name = asString(raw.name, `attachments[${index}].name`);
+    const content = asString(raw.content, `attachments[${index}].content`);
+    if (raw.language !== undefined && typeof raw.language !== "string") throw new Error(`attachments[${index}].language must be a string`);
+    return { type, name, content, ...(raw.language ? { language: raw.language } : {}) };
+  });
+}
+
+const attachmentsSchema = {
+  type: "array",
+  items: {
+    type: "object",
+    properties: {
+      type: { type: "string", enum: ["file", "snippet", "context"] },
+      name: { type: "string" },
+      content: { type: "string" },
+      language: { type: "string" },
+    },
+    required: ["type", "name", "content"],
+    additionalProperties: false,
+  },
+};
+
+export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefinition[] {
+  const tools: ToolDefinition[] = [
+    {
+      name: "intercom_whoami",
+      description: "Return this Claude session's intercom identity for reliable targeting.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      handler: async () => runtime.whoami(),
+    },
+    {
+      name: "intercom_team",
+      description: "Show your current manager and the live coworkers owned by that manager. No arguments are required.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      handler: async () => runtime.team(),
+    },
+    {
+      name: "intercom_status",
+      description: "Show intercom connection status, active sessions, unread messages, and pending asks.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      handler: async () => runtime.status(),
+    },
+    {
+      name: "intercom_list",
+      description: "List intercom-connected Pi or Claude sessions on this machine.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          scope: { type: "string", enum: ["machine", "directory", "repo"], default: "machine" },
+          include_self: { type: "boolean", default: false },
+        },
+        additionalProperties: false,
+      },
+      handler: async (args) => runtime.list(
+        args.scope === "directory" || args.scope === "repo" ? args.scope : "machine",
+        asBoolean(args.include_self, false),
+      ),
+    },
+    {
+      name: "intercom_set_summary",
+      description: "Publish a short status summary so other sessions can discover what this Claude session is doing.",
+      inputSchema: {
+        type: "object",
+        properties: { summary: { type: "string", maxLength: 400 } },
+        required: ["summary"],
+        additionalProperties: false,
+      },
+      handler: async (args) => runtime.setSummary(asString(args.summary, "summary")),
+    },
+    {
+      name: "intercom_send",
+      description: "Send a non-blocking direct message to another intercom session by name, full ID, or unique ID prefix.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          to: { type: "string" },
+          message: { type: "string" },
+          attachments: attachmentsSchema,
+        },
+        required: ["to", "message"],
+        additionalProperties: false,
+      },
+      handler: async (args) => runtime.send(asString(args.to, "to"), asString(args.message, "message"), asAttachmentArray(args.attachments)),
+    },
+    {
+      name: "intercom_ask",
+      description: "Ask another intercom session a question only when the next step depends on its reply. Use intercom_send for assignments, progress/status checkpoints, and notifications.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          to: { type: "string" },
+          message: { type: "string" },
+          attachments: attachmentsSchema,
+          timeout_ms: { type: "integer", minimum: 1, maximum: 120000, description: "Maximum time to wait for a reply before returning an error. Use intercom_send plus intercom_pending for longer work." },
+        },
+        required: ["to", "message"],
+        additionalProperties: false,
+      },
+      handler: async (args, signal) => runtime.ask(
+        asString(args.to, "to"),
+        asString(args.message, "message"),
+        asAttachmentArray(args.attachments),
+        asOptionalPositiveInteger(args.timeout_ms, "timeout_ms"),
+        signal,
+      ),
+    },
+    {
+      name: "intercom_pending",
+      description: "Read unread inbound messages and unresolved asks for this Claude session.",
+      inputSchema: {
+        type: "object",
+        properties: { mark_read: { type: "boolean", default: false } },
+        additionalProperties: false,
+      },
+      handler: async (args) => runtime.pending(asBoolean(args.mark_read, false)),
+    },
+    {
+      name: "intercom_reply",
+      description: "Reply to a pending inbound ask. Use to plus which=oldest/latest when one sender has multiple unresolved asks.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          message: { type: "string" },
+          to: { type: "string", description: "Optional sender/session selector; never a message or thread ID." },
+          which: { type: "string", enum: ["oldest", "latest"], description: "Select the oldest or latest ask from the chosen sender." },
+        },
+        required: ["message"],
+        additionalProperties: false,
+      },
+      handler: async (args) => runtime.reply(asString(args.message, "message"), typeof args.to === "string" ? args.to : undefined, args.which === "oldest" || args.which === "latest" ? args.which : undefined),
+    },
+  ];
+  return tools;
+}
+
+function ok(id: JsonRpcRequest["id"], result: unknown) {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function error(id: JsonRpcRequest["id"], code: number, message: string) {
+  return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+}
+
+export async function handleMcpRequest(request: JsonRpcRequest, runtime: ClaudeIntercomRuntime): Promise<Record<string, unknown> | undefined> {
+  if (!request.method) {
+    return error(request.id, -32600, "Invalid request");
+  }
+
+  if (request.method === "notifications/cancelled") {
+    const requestId = request.params?.requestId;
+    if (typeof requestId === "string" || typeof requestId === "number") {
+      inflightToolCalls.get(requestId)?.abort();
+    }
+    return undefined;
+  }
+
+  if (request.id === undefined && request.method.startsWith("notifications/")) {
+    return undefined;
+  }
+
+  const tools = buildToolDefinitions(runtime);
+  switch (request.method) {
+    case "initialize":
+      return ok(request.id, {
+        protocolVersion: "2025-06-18",
+        capabilities: { tools: {} },
+        serverInfo: { name: "claude-intercom", version: "0.1.0" },
+      });
+    case "ping":
+      return ok(request.id, {});
+    case "tools/list":
+      return ok(request.id, {
+        tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+      });
+    case "tools/call": {
+      const name = request.params?.name;
+      const args = request.params?.arguments;
+      if (typeof name !== "string") return error(request.id, -32602, "tools/call requires params.name");
+      if (args !== undefined && (!args || typeof args !== "object" || Array.isArray(args))) {
+        return error(request.id, -32602, "tools/call params.arguments must be an object");
+      }
+      const tool = tools.find((candidate) => candidate.name === name);
+      if (!tool) return error(request.id, -32602, `Unknown tool: ${name}`);
+      const requestId = request.id;
+      const abortController = typeof requestId === "string" || typeof requestId === "number"
+        ? new AbortController()
+        : null;
+      if (abortController && requestId !== undefined && requestId !== null) inflightToolCalls.set(requestId, abortController);
+      try {
+        return ok(request.id, await tool.handler((args ?? {}) as Record<string, unknown>, abortController?.signal));
+      } catch (caught) {
+        const message = caught instanceof Error ? caught.message : String(caught);
+        return ok(request.id, { content: [{ type: "text", text: message }], isError: true });
+      } finally {
+        if (abortController && requestId !== undefined && requestId !== null) inflightToolCalls.delete(requestId);
+      }
+    }
+    default:
+      return error(request.id, -32601, `Method not found: ${request.method}`);
+  }
+}