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

package/scripts/verify-packed-runtime.mjs

@@ -0,0 +1,140 @@
+import { gunzipSync } from "node:zlib";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const repositoryRoot = resolve(import.meta.dirname, "..");
+const corePackage = "@ctliz/agent-intercom-core";
+const coreDevSpec = "git+https://github.com/ctliz/agent-intercom-core.git#37e074970e2a9de32a16fc325607c3b476b0bd45";
+const coreConsumers = new Set([
+  "broker.mjs",
+  "cci.mjs",
+  "ccim.mjs",
+  "claude-server.mjs",
+  "worker-daemon.mjs",
+]);
+const bundles = [...coreConsumers, "inbox-monitor.mjs"];
+
+function tarString(buffer, offset, length) {
+  const end = buffer.indexOf(0, offset);
+  return buffer.subarray(offset, end === -1 || end > offset + length ? offset + length : end).toString("utf8");
+}
+
+function readTarEntries(archivePath) {
+  const archive = gunzipSync(readFileSync(archivePath));
+  const entries = new Map();
+  for (let offset = 0; offset + 512 <= archive.length;) {
+    const header = archive.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) break;
+    const name = tarString(header, 0, 100);
+    const prefix = tarString(header, 345, 155);
+    const path = prefix ? `${prefix}/${name}` : name;
+    const sizeText = tarString(header, 124, 12).trim();
+    const size = Number.parseInt(sizeText || "0", 8);
+    if (!Number.isSafeInteger(size)) throw new Error(`Invalid tar size for ${path}`);
+    const contentOffset = offset + 512;
+    entries.set(path, archive.subarray(contentOffset, contentOffset + size));
+    offset = contentOffset + Math.ceil(size / 512) * 512;
+  }
+  return entries;
+}
+
+function createPackageArchive(temp) {
+  const result = spawnSync("npm", [
+    "pack",
+    "--ignore-scripts",
+    "--json",
+    "--pack-destination",
+    temp,
+  ], {
+    cwd: repositoryRoot,
+    env: { ...process.env, npm_config_cache: join(temp, "npm-cache") },
+    encoding: "utf8",
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`npm pack failed: ${result.stderr || result.stdout}`);
+  const packed = JSON.parse(result.stdout);
+  if (!Array.isArray(packed) || packed.length !== 1 || typeof packed[0]?.filename !== "string") {
+    throw new Error("npm pack did not report exactly one package archive");
+  }
+  return join(temp, packed[0].filename);
+}
+
+const archiveArgument = process.argv.indexOf("--archive");
+const suppliedArchive = archiveArgument === -1 ? undefined : process.argv[archiveArgument + 1];
+if (archiveArgument !== -1 && !suppliedArchive) throw new Error("--archive requires a package tarball path");
+const temp = suppliedArchive ? undefined : mkdtempSync(join(tmpdir(), "claude-intercom-pack-check-"));
+
+try {
+  const archivePath = suppliedArchive ? resolve(suppliedArchive) : createPackageArchive(temp);
+  const entries = readTarEntries(archivePath);
+  const manifestEntry = entries.get("package/package.json");
+  if (!manifestEntry) throw new Error("Packed adapter is missing package.json");
+  const manifest = JSON.parse(manifestEntry.toString("utf8"));
+  if (manifest.peerDependencies?.[corePackage] !== "0.1.0") throw new Error("Packed adapter must require Core peer 0.1.0");
+  if (manifest.peerDependenciesMeta?.[corePackage]?.optional === true) throw new Error("Packed Core peer must not be optional");
+  if (manifest.dependencies?.[corePackage] !== undefined) throw new Error("Packed adapter must not install a private Core dependency");
+  if (manifest.devDependencies?.[corePackage] !== coreDevSpec) throw new Error("Packed adapter lost the approved Core build commit");
+  if ([...entries.keys()].some((path) => path.includes("node_modules/@ctliz/agent-intercom-core/"))) {
+    throw new Error("Packed adapter contains a private Core module tree");
+  }
+
+  // 1. Assert Claude Plugin manifest exists and is valid
+  const pluginEntry = entries.get("package/.claude-plugin/plugin.json");
+  if (!pluginEntry) throw new Error("Packed adapter is missing .claude-plugin/plugin.json");
+  const plugin = JSON.parse(pluginEntry.toString("utf8"));
+  if (plugin.name !== "claude-intercom") throw new Error(`Unexpected plugin name: ${plugin.name}`);
+
+  // 2. Assert Plugin -> MCP configuration exists and points to real dist bundle
+  if (typeof plugin.mcpServers !== "string") throw new Error("plugin.json missing mcpServers declaration");
+  const mcpRelPath = plugin.mcpServers.replace(/^\.\//, "");
+  const mcpEntry = entries.get(`package/${mcpRelPath}`);
+  if (!mcpEntry) throw new Error(`Packed adapter missing plugin mcpServers file: ${mcpRelPath}`);
+  const mcpConfig = JSON.parse(mcpEntry.toString("utf8"));
+  const claudeServerArg = mcpConfig.mcpServers?.["claude-intercom"]?.args?.[0];
+  if (!claudeServerArg || !claudeServerArg.includes("/dist/claude-server.mjs")) {
+    throw new Error(`MCP config does not reference dist/claude-server.mjs: ${claudeServerArg}`);
+  }
+
+  // 3. Assert Plugin -> Monitors configuration exists and points to real dist bundle
+  if (typeof plugin.monitors !== "string") throw new Error("plugin.json missing monitors declaration");
+  const monitorsRelPath = plugin.monitors.replace(/^\.\//, "");
+  const monitorsEntry = entries.get(`package/${monitorsRelPath}`);
+  if (!monitorsEntry) throw new Error(`Packed adapter missing plugin monitors file: ${monitorsRelPath}`);
+  const monitorsConfig = JSON.parse(monitorsEntry.toString("utf8"));
+  if (!Array.isArray(monitorsConfig) || monitorsConfig.length === 0) {
+    throw new Error("monitors.json is empty or not an array");
+  }
+  const inboxMonitor = monitorsConfig.find((m) => m.name === "intercom-inbox");
+  if (!inboxMonitor || !inboxMonitor.command?.includes("/dist/inbox-monitor.mjs")) {
+    throw new Error(`monitors.json missing intercom-inbox command referencing dist/inbox-monitor.mjs: ${JSON.stringify(inboxMonitor)}`);
+  }
+
+  // 4. Assert Plugin -> Skills & Commands exist in packed archive
+  if (typeof plugin.skills !== "string") throw new Error("plugin.json missing skills declaration");
+  const skillEntry = entries.get("package/skills/claude-intercom/SKILL.md");
+  if (!skillEntry) throw new Error("Packed adapter missing skills/claude-intercom/SKILL.md");
+
+  if (typeof plugin.commands !== "string") throw new Error("plugin.json missing commands declaration");
+  const commandEntry1 = entries.get("package/commands/intercom.md");
+  const commandEntry2 = entries.get("package/commands/intercom-id.md");
+  if (!commandEntry1 || !commandEntry2) throw new Error("Packed adapter missing commands markdown files");
+
+  // 5. Assert all dist bundles exist and adhere to Core externalization
+  for (const bundle of bundles) {
+    const entry = entries.get(`package/dist/${bundle}`);
+    if (!entry) throw new Error(`Packed adapter is missing dist/${bundle}`);
+    const source = entry.toString("utf8");
+    if (source.includes("node_modules/@ctliz/agent-intercom-core/") || /var POLICY_SEMANTICS_VERSION\s*=/.test(source)) {
+      throw new Error(`Packed dist/${bundle} embeds a private Core copy`);
+    }
+    if (coreConsumers.has(bundle) && !/from ["']@ctliz\/agent-intercom-core(?:\/[A-Za-z/-]+)?["']/.test(source)) {
+      throw new Error(`Packed dist/${bundle} does not retain its Core peer import`);
+    }
+  }
+
+  console.log(`Verified complete plugin+MCP+monitors+dist chain and ${bundles.length} packed bundles using Core peer 0.1.0`);
+} finally {
+  if (temp) rmSync(temp, { recursive: true, force: true });
+}

package/skills/claude-intercom/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: claude-intercom
+description: |
+  Coordinate with local Pi, Codex, or Claude coding-agent sessions through
+  claude-intercom MCP tools. Use for same-machine planner-worker workflows,
+  direct peer questions, cross-session context sharing, and checking or
+  replying to pending asks.
+---
+
+# Claude Intercom
+
+Use this skill when you need to coordinate with another local coding-agent
+session through the `claude-intercom` MCP server. It speaks the same broker
+protocol as `pi-intercom` and `codex-intercom`, so Pi, Codex, and Claude
+sessions can all message each other.
+
+A plain Claude Code MCP session does not receive unsolicited turns. Inbound
+messages are queued by the MCP server while it is running. Check
+`intercom_pending` at natural boundaries: before starting delegated work, and
+when you expect a response.
+
+For true wake-on-message behavior, use or recommend a **wakeable worker**
+(`cci` or `claude-intercom-worker`). Messages to a worker start a fresh
+headless `claude -p` turn that resumes the worker's own conversation, so the
+worker can read files, run commands, and reply on its own. Normal `cci` workers
+automatically load the packaged Intercom MCP server, including under isolated
+proxy-backed Claude profiles; `ccim` safe mode intentionally does not.
+
+## Tools
+
+- `intercom_whoami`: show this session's intercom ID, name, cwd, and model.
+- `intercom_team`: show the current orchestrator manager and live same-manager coworkers.
+- `intercom_status`: connection, active session count, unread messages, pending asks.
+- `intercom_list`: list connected Pi, Codex, and Claude sessions.
+- `intercom_set_summary`: publish a short discoverable status.
+- `intercom_send`: fire-and-forget direct message.
+- `intercom_ask`: send a question and wait for the target's reply (blocking, bounded).
+- `intercom_pending`: read queued inbound messages and pending asks.
+- `intercom_reply`: reply to a pending inbound ask.
+
+## Workflow
+
+1. Call `intercom_status` or `intercom_whoami` to confirm this session is connected.
+2. Call `intercom_set_summary` with a concise status so peers can discover your role.
+3. If this is an orchestrator-owned coworker, call `intercom_team` to get the manager and sibling targets without searching globally. Otherwise use `intercom_list`.
+4. Use `intercom_send` for non-blocking updates and handoffs.
+5. Use `intercom_ask` only when you need the answer before continuing. Assignments, progress/status checkpoints, notifications, and completion reports use `intercom_send`.
+6. Call `intercom_pending` before ending a coordination turn, then answer blocking asks with `intercom_reply`.
+
+## Patterns
+
+Planner delegates to a wakeable worker without blocking:
+
+```typescript
+intercom_send({
+  to: "worker",
+  message: "Task-3: add retry logic in src/api/client.ts. Ask if the retry scope is unclear."
+})
+```
+
+Ask a worker and wait for its answer (the worker's final message comes back as the reply):
+
+```typescript
+intercom_ask({
+  to: "worker",
+  message: "Inspect the failing test in test/auth.test.ts and reply with the most likely cause."
+})
+```
+
+Reply to an inbound ask:
+
+```typescript
+intercom_pending({ mark_read: false })
+intercom_reply({ message: "Use GET/PUT/DELETE only, max 3 retries." })
+```
+
+When multiple asks are pending, select the sender with `to`. If that sender has multiple unresolved asks, select `oldest` or `latest` without using protocol IDs:
+
+```typescript
+intercom_reply({ to: "planner", which: "oldest", message: "Proceed." })
+```
+
+Keep at most one unresolved `intercom_ask` to the same recipient. Use `intercom_send` for non-blocking follow-ups and every progress/status request.
+
+## Boundaries
+
+- Do not assume push delivery into a plain MCP session. Check `intercom_pending`.
+- A plain MCP session cannot wake itself from idle. Use a wakeable worker (`cci`) for wake-on-message.
+- Do not use `intercom_ask` to poll files, ports, or process completion — use normal shell checks.
+- Keep messages concise; include file paths, command-output summaries, and decision options when useful.

package/types.ts

@@ -0,0 +1,212 @@
+import type {
+  BossControlEnvelope,
+  BossParticipantBinding,
+  BossParticipantCredentialEnvelope,
+  BossPrivatePrincipal,
+  BossRunFeatureContract,
+  BossWorkerIdentityV2,
+  BrokerCapabilityAdvertisement,
+  ParticipantState,
+} from "@ctliz/agent-intercom-core/boss";
+
+export interface BossLiveWorkerAuthority {
+  identity: BossWorkerIdentityV2;
+  state: ParticipantState;
+}
+
+export interface BossSessionMetadata {
+  binding: BossParticipantBinding;
+  principal: BossPrivatePrincipal;
+  /** Broker-authenticated live worker identity, independent of the worker registry projection. */
+  liveWorker: BossLiveWorkerAuthority;
+  featureContract: BossRunFeatureContract;
+  policySemanticsHash: string;
+  capabilityDigest: string;
+  brokerIdentityVerified: true;
+}
+
+export interface BossRegistrationRequest {
+  featureContract: BossRunFeatureContract;
+  capabilityDigest: string;
+  credential: BossParticipantCredentialEnvelope;
+}
+
+export interface SessionInfo {
+  id: string;
+  name?: string;
+  cwd: string;
+  model: string;
+  pid: number;
+  startedAt: number;
+  lastActivity: number;
+  status?: string;
+  peerUid?: number;
+  trustedLocal?: boolean;
+  origin?: "local" | "remote";
+  remoteHostId?: string;
+  parentSessionId?: string;
+  rootSessionId?: string;
+  generation?: number;
+  canDelegate?: boolean;
+  depth?: number;
+  maxDepth?: number;
+  maxChildren?: number;
+  /** Broker-authoritative metadata; absent for every ordinary/legacy session. */
+  boss?: BossSessionMetadata;
+}
+
+export interface Message {
+  id: string;
+  timestamp: number;
+  replyTo?: string;
+  expectsReply?: boolean;
+  /** Internal typed control. Model-facing text tools cannot construct this. */
+  control?: BossControlEnvelope;
+  content: {
+    text: string;
+    attachments?: Attachment[];
+  };
+}
+
+export interface Attachment {
+  type: "file" | "snippet" | "context";
+  name: string;
+  content: string;
+  language?: string;
+}
+
+export type SessionRegistration = Omit<
+  SessionInfo,
+  "id" | "peerUid" | "trustedLocal" | "origin" | "remoteHostId" | "parentSessionId" | "rootSessionId" | "generation" | "canDelegate" | "depth" | "maxDepth" | "maxChildren" | "boss"
+> & {
+  /** Ephemeral identity shared only by reconnects from one live runtime. */
+  runtimeInstanceId?: string;
+  /** Requested Boss enrollment. The dormant Stage-B broker rejects it closed. */
+  boss?: BossRegistrationRequest;
+};
+
+export interface RemoteEnrollmentAccess {
+  enrollmentToken: string;
+}
+
+export interface RemoteSessionAccess {
+  sessionCredential: string;
+  sessionId: string;
+  generation: number;
+}
+
+export type RemoteRegistrationAccess = RemoteEnrollmentAccess | RemoteSessionAccess;
+
+export interface RemoteAccessMetadata {
+  origin: "remote";
+  remoteHostId: string;
+  parentSessionId: string;
+  rootSessionId: string;
+  generation: number;
+  canDelegate: boolean;
+  depth: number;
+  maxDepth: number;
+  maxChildren: number;
+  sessionCredential?: string;
+}
+
+export interface RemotePrincipalSummary {
+  id: string;
+  name: string;
+  parentSessionId: string;
+  rootSessionId: string;
+  remoteHostId: string;
+  generation: number;
+  policy: "remote-tree";
+  canDelegate: boolean;
+  depth: number;
+  maxDepth: number;
+  maxChildren: number;
+  state: "active" | "revoked";
+  expiresAt: number;
+  createdAt: number;
+  updatedAt: number;
+  connected: boolean;
+}
+
+export interface RemoteAccessContract {
+  feature: "remote-access-v1";
+  policySemanticsVersion: number;
+  policySemanticsHash: string;
+}
+
+export const DELIVERY_FAILURE_CODES = [
+  "INVALID_MESSAGE",
+  "SESSION_NOT_FOUND",
+  "AMBIGUOUS_TARGET",
+  "SENDER_NOT_FOUND",
+  "INVALID_REPLY_TARGET",
+  "MUTUAL_ASK",
+  "ASK_ALREADY_PENDING",
+  "DUPLICATE_MESSAGE_ID",
+  "CONFLICTING_MESSAGE_ID",
+  "TOO_MANY_PENDING_DELIVERIES",
+  "TOO_MANY_PENDING_ASKS",
+  "RECIPIENT_DISCONNECTED",
+  "SENDER_DISCONNECTED",
+  "DELIVERY_TIMEOUT",
+  "CONTROL_DISPATCH_UNAVAILABLE",
+] as const;
+
+export type DeliveryFailureCode = (typeof DELIVERY_FAILURE_CODES)[number];
+
+export type BrokerErrorCode =
+  | "PROTOCOL_MISMATCH"
+  | "INVALID_REQUEST"
+  | "SESSION_ID_IN_USE"
+  | "ACCESS_DENIED"
+  | "BOSS_FEATURE_UNAVAILABLE"
+  | "REMOTE_ACCESS_INCOMPATIBLE"
+  | "RATE_LIMITED"
+  | "TOO_MANY_SESSIONS";
+
+export type AskCancellationReason =
+  | "cancelled"
+  | "expired"
+  | "delivery_failed"
+  | "session_disconnected"
+  | "authorization_revoked";
+
+export type ClientMessage =
+  | { type: "health"; requestId: string; stateId?: string }
+  | { type: "register"; protocol: string; version: number; session: SessionRegistration; sessionId?: string; stateId?: string; access?: RemoteRegistrationAccess; scopeId?: string }
+  | { type: "access_control"; requestId: string; adminToken: string; action: "issue_enrollment"; enrollment: { name: string; parentSessionId: string; rootSessionId: string; remoteHostId: string; ttlMs?: number; expiresAt?: number; canDelegate?: boolean; maxDepth?: number; maxChildren?: number } }
+  | { type: "access_control"; requestId: string; adminToken: string; action: "revoke_subtree"; principalId: string }
+  | { type: "access_control"; requestId: string; adminToken: string; action: "inspect_tree"; principalId: string }
+  | { type: "access_control"; requestId: string; adminToken: string; action: "adopt_subtree"; principalId: string; newParentSessionId: string }
+  | { type: "access_control"; requestId: string; access: RemoteSessionAccess; action: "issue_child_enrollment"; enrollment: { name: string; ttlMs?: number; expiresAt?: number; canDelegate?: boolean; maxDepth?: number; maxChildren?: number } }
+  | { type: "access_control"; requestId: string; access: RemoteSessionAccess; action: "inspect_tree"; principalId?: string }
+  | { type: "unregister"; preserveAsks?: boolean }
+  | { type: "list"; requestId: string }
+  | { type: "send"; to: string; message: Message }
+  | { type: "message_received"; deliveryId: string }
+  | { type: "message_rejected"; deliveryId: string; code: "CONFLICTING_MESSAGE_ID"; reason: string }
+  | { type: "defer_ask"; requestId: string; messageId: string }
+  | { type: "cancel_ask"; requestId: string; messageId: string }
+  | { type: "presence"; name?: string; status?: string; model?: string };
+
+export type BrokerMessage =
+  | { type: "health_ok"; requestId: string; protocol: string; version: number; endpoint: "local" | "remote"; remoteAccess?: RemoteAccessContract; capabilities?: BrokerCapabilityAdvertisement }
+  | { type: "registered"; sessionId: string; protocol: string; version: number; remoteAccess?: RemoteAccessContract; access?: RemoteAccessMetadata; capabilities?: BrokerCapabilityAdvertisement; boss?: BossSessionMetadata }
+  | { type: "access_control_result"; requestId: string; action: "issue_enrollment"; enrollmentToken: string; expiresAt: number }
+  | { type: "access_control_result"; requestId: string; action: "revoke_subtree"; changedPrincipalIds: string[] }
+  | { type: "access_control_result"; requestId: string; action: "inspect_tree"; principals: RemotePrincipalSummary[] }
+  | { type: "access_control_result"; requestId: string; action: "adopt_subtree"; principals: RemotePrincipalSummary[] }
+  | { type: "access_control_result"; requestId: string; action: "issue_child_enrollment"; enrollmentToken: string; expiresAt: number; parentSessionId: string }
+  | { type: "sessions"; requestId: string; sessions: SessionInfo[] }
+  | { type: "message"; deliveryId: string; from: SessionInfo; message: Message }
+  | { type: "presence_update"; session: SessionInfo }
+  | { type: "session_joined"; session: SessionInfo }
+  | { type: "session_left"; sessionId: string }
+  | { type: "error"; code: BrokerErrorCode; error: string }
+  | { type: "delivery_accepted"; messageId: string; deliveryId: string }
+  | { type: "delivered"; messageId: string; deliveryId: string }
+  | { type: "delivery_failed"; messageId: string; accepted: boolean; code: DeliveryFailureCode; reason: string }
+  | { type: "ask_deferred"; messageId: string; fromSessionId: string }
+  | { type: "ask_cancelled"; messageId: string; fromSessionId: string; reason: AskCancellationReason }
+  | { type: "ask_control_result"; requestId: string; action: "defer" | "cancel"; messageId: string; applied: boolean };