@ctliz/agent-intercom-pi 0.12.0-connect.9 → 0.13.0

package/README.md

@@ -17,6 +17,35 @@
 | AGY | [`agent-intercom-agy`](https://github.com/ctliz/agent-intercom-agy) |
 | Fleet lifecycle | [`agent-intercom-orchestrator`](https://github.com/ctliz/agent-intercom-orchestrator) |
 
+## Pi 0.99 and codemode
+
+Version 0.13.0 requires Pi 0.99.1 or newer in the 0.99 release line. It keeps the existing protocol v4 broker, durable queues, acknowledgements, and cross-harness routing unchanged.
+
+All Intercom tools remain directly callable and are also available through Pi's built-in codemode when active. Scripts receive `{ ok, text, data }` rather than a display string. `data` contains the tool's structured details: delivery flags and message ID, session lists, team roster, pending asks, or connection status. Returned failures set `isError: true` and retain structured data; a deferred ask is successful with `data.pending === true`. Always check `ok` before continuing with dependent actions. Blocked calls, invalid arguments, and thrown exceptions can still reject, so use `try/catch` or `Promise.allSettled()` when appropriate.
+
+```javascript
+const sessions = await tools.intercom_list({});
+if (!sessions.ok) throw new Error(sessions.text);
+const target = sessions.data.sessions.find(s => s.name === "worker");
+if (!target) throw new Error("Worker is offline");
+const result = await tools.intercom_send({ to: target.id, message: "Tests passed." });
+return { ok: result.ok, accepted: result.data.accepted, delivered: result.data.delivered };
+```
+
+Concurrent sends and independent asks are supported; do not create two unresolved asks to the same recipient. Team joins execute sequentially because they change the caller's routing scope. Receiving a delivery acknowledgement means the message is durably queued, not that the recipient finished its task. Busy sessions wait until `ctx.isIdle()`; `agent_settled` updates final idle status after automatic retries and compaction.
+
+### Send from a shell or release script
+
+The package includes an `intercom-send` executable. Install the alias globally for a shell command, or run it without relying on Pi's private installation path:
+
+```bash
+npm exec --yes --package=@ctliz/pi-intercom@0.13.0 -- intercom-send worker 'Tests passed.'
+```
+
+It prints one JSON result with `accepted`, `delivered`, `messageId`, and optional failure `code`/`reason`. Exit status is zero only for acknowledged delivery. It inherits the routing scope, but never inherits `PI_INTERCOM_SESSION_ID` or `AGENT_INTERCOM_SESSION_ID`: every invocation registers an independent sender, leaves running Pi sessions intact, and disconnects after sending. It is send-only; use the session tools for reply-tracked asks.
+
+When a second runtime claims the same stable session ID, Intercom reports `SESSION_ID_IN_USE`, pauses automatic reconnect, and preserves the original owner. Switch to a different session, or release the duplicate owner and `/reload`. `intercom_status` exposes the conflict as structured data rather than silently treating it as a temporary outage. Updating this adapter does not require restarting a compatible v4 broker.
+
 ## Grok Build and AGY support
 
 Grok Build and AGY are supported as first-class protocol peers through two dedicated npm packages:
@@ -93,7 +122,7 @@ Each pi session that has `pi-intercom` loaded and enabled connects to a tiny loc
 ## Install
 
 ```bash
-pi install git:github.com/ctliz/agent-intercom-pi@v0.12.0-connect.9
+pi install git:github.com/ctliz/agent-intercom-pi@v0.12.2
 ```
 
 If you are coming from `connect.1`, read [Upgrading from `connect.1`](#upgrading-from-connect1-to-connect2) first — the package namespace changed and the two versions must not be installed side by side.
@@ -141,7 +170,7 @@ A session becomes intercom-connected when all of these are true:
 
 The session list only shows intercom-connected sessions, not every open Pi process on the machine.
 
-If you upgrade pi-intercom or the orchestrator while sessions are already open, run `/reload` in each open Pi session (and restart any companion `coi`, `cci`, or OpenCode adapter). Update the packages by reinstalling the exact release tags with `pi install git:github.com/ctliz/agent-intercom-pi@v0.12.0-connect.9` and, only where Orchestrator is actually installed, `pi install git:github.com/ctliz/agent-intercom-orchestrator@v0.12.0-connect.5`. Extensions are loaded into the running host process, so an existing session cannot adopt new broker/discovery code until it reloads. This is especially important when upgrading from a release that allowed multiple broker processes to form separate session-list "islands": the broker ownership fix prevents new splits, but it cannot move clients that are still running the old code. After every host has reloaded once, they converge on the same broker automatically.
+If you upgrade pi-intercom or the orchestrator while sessions are already open, run `/reload` in each open Pi session (and restart any companion `coi`, `cci`, or OpenCode adapter). Update the packages by reinstalling the exact release tags with `pi install git:github.com/ctliz/agent-intercom-pi@v0.12.2` and, only where Orchestrator is actually installed, `pi install git:github.com/ctliz/agent-intercom-orchestrator@v0.12.0-connect.5`. Extensions are loaded into the running host process, so an existing session cannot adopt new broker/discovery code until it reloads. This is especially important when upgrading from a release that allowed multiple broker processes to form separate session-list "islands": the broker ownership fix prevents new splits, but it cannot move clients that are still running the old code. After every host has reloaded once, they converge on the same broker automatically.
 
 If `/intercom` still reports no peers, first confirm the other Pi windows have pi-intercom loaded and have also been reloaded. Open Pi processes without the extension, disabled sessions, and sessions using a different `PI_CODING_AGENT_DIR` intentionally do not appear in the same list.
 

package/bin/intercom-send.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { register } from "tsx/esm/api";
+register();
+await import("../cli-send.ts");

package/broker/client.ts

@@ -376,7 +376,9 @@ export class IntercomClient extends EventEmitter {
       };
 
       const onReaderError = (error: Error) => {
-        const protocolError = new Error(`Intercom protocol error: ${error.message}`, { cause: error });
+        const protocolError = new Error(`Intercom protocol error: ${error.message}`, { cause: error }) as Error & { code?: string };
+        const code = (error as Error & { code?: string }).code;
+        if (code) protocolError.code = code;
         if (!connectionEstablished) {
           onError(protocolError);
           return;

package/broker/framing.ts

@@ -41,7 +41,10 @@ export function createMessageReader(
       return true;
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      onError(new Error(`Failed to handle intercom message: ${message}`, { cause: error }));
+      const handlerError = new Error(`Failed to handle intercom message: ${message}`, { cause: error }) as Error & { code?: string };
+      const code = (error as { code?: unknown } | null)?.code;
+      if (typeof code === "string") handlerError.code = code;
+      onError(handlerError);
       return false;
     }
   }

package/cli-send.ts

@@ -0,0 +1,39 @@
+import { randomUUID } from "node:crypto";
+import { IntercomClient } from "./broker/client.ts";
+import { spawnBrokerIfNeeded } from "./broker/spawn.ts";
+import { loadConfig } from "./config.ts";
+
+async function main(): Promise<void> {
+  const [to, ...parts] = process.argv.slice(2);
+  const message = parts.join(" ");
+  if (!to?.trim() || !message.trim()) {
+    throw new Error("Usage: intercom-send <session-name-or-id> <message>");
+  }
+  const config = loadConfig();
+  if (!config.enabled) throw new Error("Intercom disabled");
+  await spawnBrokerIfNeeded(config.brokerCommand, config.brokerArgs);
+  const client = new IntercomClient();
+  const now = Date.now();
+  try {
+    // Never inherit the calling Pi's session ID or take over its mailbox.
+    await client.connect({
+      name: `intercom-cli-${randomUUID()}`,
+      cwd: process.cwd(),
+      model: "cli-sender",
+      pid: process.pid,
+      startedAt: now,
+      lastActivity: now,
+      runtimeInstanceId: randomUUID(),
+    });
+    const result = await client.send(to, { text: message });
+    console.log(JSON.stringify({ messageId: result.id, ...result }));
+    if (!result.delivered) process.exitCode = 1;
+  } finally {
+    await client.disconnect();
+  }
+}
+
+main().catch((error: Error & { code?: string }) => {
+  console.log(JSON.stringify({ accepted: false, delivered: false, reason: error.message, ...(error.code ? { code: error.code } : {}) }));
+  process.exitCode = 1;
+});

package/index.ts

@@ -1,4 +1,5 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { intercomOutputSchema, structuredIntercomResult } from "./tool-result.ts";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { randomUUID } from "crypto";
 import { spawn, spawnSync } from "child_process";
@@ -147,9 +148,8 @@ function toError(error: unknown): Error {
 }
 
 function toolErrorDetails(error: unknown): { error: true; code?: string } {
-  return error instanceof BossTeamScopeError
-    ? { error: true, code: error.code }
-    : { error: true };
+  const code = (error as { code?: unknown } | null)?.code;
+  return { error: true, ...(typeof code === "string" ? { code } : {}) };
 }
 
 class AskWaitElapsedError extends Error {
@@ -680,6 +680,15 @@ function getNamePollMs(): number {
   return 1000;
 }
 export default function piIntercomExtension(pi: ExtensionAPI) {
+  function registerIntercomTool(tool: ToolDefinition<any, any>): void {
+    pi.registerTool({
+      ...tool,
+      outputSchema: intercomOutputSchema,
+      async execute(...args) {
+        return structuredIntercomResult(await tool.execute(...args));
+      },
+    });
+  }
   let runtimeScopeId = intercomScopeIdFromEnvForRegistration();
   const initialHarnessSessionId = process.env[INTERCOM_SESSION_ID_ENV]?.trim();
   const initialGenericSessionId = process.env.AGENT_INTERCOM_SESSION_ID?.trim();
@@ -706,6 +715,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
   let reconnectPromiseGeneration: number | null = null;
   let startupConnectTimer: NodeJS.Timeout | null = null;
   let reconnectAttempt = 0;
+  let registrationConflict: Error | null = null;
   let shuttingDown = false;
   let disposed = true;
   let runtimeStarted = false;
@@ -835,7 +845,8 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
   }
   function currentStatus(): string {
     const activeToolName = activeTools.values().next().value;
-    const lifecycleStatus = activeToolName ? `tool:${activeToolName}` : agentRunning ? "thinking" : "idle";
+    const busy = agentRunning || getLiveContext()?.isIdle() === false;
+    const lifecycleStatus = activeToolName ? `tool:${activeToolName}` : busy ? "thinking" : "idle";
     const queueStatus = inboundInbox?.size ? ` · inbox:${inboundInbox.size}` : "";
     const outboxStatus = client?.outboxSize ? ` · outbox:${client.outboxSize}` : "";
     return config.status ? `${lifecycleStatus}${queueStatus}${outboxStatus} · ${config.status}` : `${lifecycleStatus}${queueStatus}${outboxStatus}`;
@@ -1079,6 +1090,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     inboundFlushTimer.unref?.();
   }
   function flushIdleMessages(generation = runtimeGeneration): void {
+    if (registrationConflict) return;
     if (!inboundInbox || inboundInbox.size === 0) {
       return;
     }
@@ -1086,6 +1098,10 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     if (!ctx) {
       return;
     }
+    if (!client?.isConnected()) {
+      scheduleInboundFlush(INBOUND_IDLE_RETRY_MS);
+      return;
+    }
 
     let isIdle: boolean;
     try {
@@ -1305,7 +1321,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     });
   }
   function scheduleReconnect(): void {
-    if (disposed || shuttingDown || reconnectTimer || reconnectPromise || !getLiveContext()) {
+    if (disposed || shuttingDown || registrationConflict || reconnectTimer || reconnectPromise || !getLiveContext()) {
       return;
     }
     const scheduledGeneration = runtimeGeneration;
@@ -1327,6 +1343,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     if (disposed || shuttingDown) {
       throw new Error("Intercom shutting down");
     }
+    if (registrationConflict) throw registrationConflict;
     if (bossTeamScope.present) {
       const selfError = currentSessionId ? bossSelfSessionError(bossTeamScope, currentSessionId) : "Boss session identity is unavailable";
       if (selfError) throw new BossTeamScopeError("BOSS_TEAM_METADATA_INVALID", selfError);
@@ -1359,19 +1376,24 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
         }
         client = nextClient;
         reconnectAttempt = 0;
+        scheduleInboundFlush(0);
         return nextClient;
       } catch (error) {
         if (client === nextClient) {
           client = null;
         }
-        if (reason === "background" && getLiveContext(contextAtStart, generationAtStart)) {
-          scheduleReconnect();
+        if ((error as { code?: string })?.code === "SESSION_ID_IN_USE" && getLiveContext(contextAtStart, generationAtStart)) {
+          registrationConflict = toError(error);
+          clearReconnectTimer();
+          pi.appendEntry("intercom_registration_conflict", { sessionId: currentSessionId, code: "SESSION_ID_IN_USE", timestamp: Date.now() });
+          notifyIfLive(contextAtStart, "Intercom session is owned by another runtime. Switch to a different session, or release the duplicate owner and /reload. The existing owner was not changed.", "warning", generationAtStart);
         }
         throw toError(error);
       } finally {
         if (reconnectPromise === nextReconnectPromise) {
           reconnectPromise = null;
           reconnectPromiseGeneration = null;
+          if (reason === "background" && !client) scheduleReconnect();
         }
       }
     })();
@@ -1490,6 +1512,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     runtimeStarted = true;
     runtimeGeneration += 1;
     reconnectAttempt = 0;
+    registrationConflict = null;
     clearReconnectTimer();
     clearStartupConnectTimer();
     clearNamePollTimer();
@@ -1810,11 +1833,16 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     activeTools.delete(event.toolCallId);
     syncPresenceStatus();
   });
-  pi.on("agent_end", () => {
-    if (!getLiveContext()) {
-      return;
-    }
+  pi.on("agent_end", (_event, ctx) => {
+    if (!getLiveContext(ctx)) return;
     replyTracker.endTurn();
+    agentRunning = !ctx.isIdle();
+    activeTools.clear();
+    syncPresenceStatus();
+    scheduleInboundFlush(0);
+  });
+  pi.on("agent_settled", (_event, ctx) => {
+    if (!getLiveContext(ctx)) return;
     agentRunning = false;
     activeTools.clear();
     syncPresenceStatus();
@@ -1895,7 +1923,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
 
   const childOrchestratorMetadata = readChildOrchestratorMetadata();
   if (childOrchestratorMetadata) {
-    pi.registerTool({
+    registerIntercomTool({
       name: "contact_supervisor",
       label: "Contact Supervisor",
       description: "Subagent-only tool for contacting the supervisor agent that delegated this task. Use need_decision when blocked, uncertain, needing approval, or facing a product/API/scope decision before continuing; this waits up to 30 seconds, then continues asynchronously if unanswered. Use interview_request when multiple structured questions need supervisor answers; it has the same soft wait. Use progress_update only for meaningful progress or unexpected discoveries that change the plan; this does not wait for a reply. Do not use for routine completion handoffs.",
@@ -2219,6 +2247,12 @@ Usage:
     }),
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      if (params.action === "status" && registrationConflict) {
+        return {
+          content: [{ type: "text", text: `**Intercom Status:**\nConnected: No\nSession ID: ${currentSessionId}\nState: SESSION_ID_IN_USE\nAnother runtime owns this session; automatic reconnect is paused. Release the duplicate owner and /reload, or switch to a different session.` }],
+          details: { connected: false, sessionId: currentSessionId, code: "SESSION_ID_IN_USE", error: true },
+        };
+      }
       let connectedClient: IntercomClient;
       try {
         connectedClient = await ensureConnected("tool");
@@ -2272,7 +2306,7 @@ Usage:
 
             return {
               content: [{ type: "text", text: `${currentSection}\n\n${otherSection}` }],
-              details: {},
+              details: { sessionId: mySessionId, sessions },
             };
           } catch (error) {
             return {
@@ -2632,7 +2666,7 @@ Usage:
                 type: "text",
                 text: `**Intercom Status:**\nConnected: Yes\nSession ID: ${mySessionId}\nActive sessions: ${sessions.length}\nQueued inbound messages: ${inboundInbox?.size ?? 0}\nQueued outbound messages: ${connectedClient.outboxSize}\nPending inbound asks: ${replyTracker.listPending().length}`,
               }],
-              details: {},
+              details: { connected: true, sessionId: mySessionId, activeSessions: sessions.length, inboundMessages: inboundInbox?.size ?? 0, outboundMessages: connectedClient.outboxSize, pendingAsks: replyTracker.listPending().length },
             };
           } catch (error) {
             return {
@@ -2705,7 +2739,7 @@ Usage:
       legacyIntercomTool.renderCall({ ...args, action }, theme, context);
   const renderSplitResult = legacyIntercomTool.renderResult;
 
-  pi.registerTool({
+  registerIntercomTool({
     name: "intercom_send",
     label: "Intercom Send",
     description: "Send a message to another local Pi session. Both the recipient and message are required.",
@@ -2721,7 +2755,7 @@ Usage:
     renderResult: renderSplitResult,
   } as any);
 
-  pi.registerTool({
+  registerIntercomTool({
     name: "intercom_ask",
     label: "Intercom Ask",
     description: "Ask another local Pi session a blocking question, waiting briefly before continuing asynchronously. Do not use this for progress or status checkpoints.",
@@ -2737,7 +2771,7 @@ Usage:
     renderResult: renderSplitResult,
   } as any);
 
-  pi.registerTool({
+  registerIntercomTool({
     name: "intercom_reply",
     label: "Intercom Reply",
     description: "Reply to an inbound intercom message or ask. Exact protocol threading is resolved internally.",
@@ -2754,7 +2788,7 @@ Usage:
     renderResult: renderSplitResult,
   } as any);
 
-  pi.registerTool({
+  registerIntercomTool({
     name: "intercom_team",
     label: "Intercom Team",
     description: "Show your current manager and the live coworkers owned by that manager. No arguments are required.",
@@ -2789,8 +2823,9 @@ Usage:
     },
   } as any);
 
-  pi.registerTool({
+  registerIntercomTool({
     name: "intercom_join",
+    executionMode: "sequential",
     label: "Intercom Join",
     description: "List, join, or create a named intercom team without tmux. Omit name to list joinable teams. Set create=true to create a team and join as manager.",
     promptSnippet: "Join or create a named intercom team so intercom_team works without tmux.",
@@ -2838,7 +2873,7 @@ Usage:
     { name: "intercom_status", label: "Intercom Status", action: "status", description: "Show this session's intercom connection status.", promptSnippet: "Show intercom connection status." },
   ] as const) {
     if (definition.name === "intercom_list" && bossTeamScope.restricted) continue;
-    pi.registerTool({
+    registerIntercomTool({
       name: definition.name,
       label: definition.label,
       description: definition.description,
@@ -2856,7 +2891,7 @@ Usage:
   }
 
   if (config.legacyTool) {
-    pi.registerTool(legacyIntercomTool);
+    registerIntercomTool(legacyIntercomTool);
   }
 
   async function resolveCurrentContact(ctx: ExtensionContext, generation = runtimeGeneration): Promise<{ target: string; name?: string; id: string; duplicateName: boolean } | undefined> {

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@ctliz/agent-intercom-pi",
-  "version": "0.12.0-connect.9",
+  "version": "0.13.0",
   "description": "Pi coding-agent intercom for local messaging with Codex, Claude Code, OpenCode, Grok Build, and AGY agents.",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "main": "index.ts",
+  "bin": {
+    "intercom-send": "./bin/intercom-send.mjs"
+  },
   "exports": {
     ".": "./index.ts"
   },
   "files": [
     "banner.png",
+    "bin/*.mjs",
     "*.ts",
     "!*.test.ts",
     "broker/**/*.ts",
@@ -54,9 +58,9 @@
   },
   "dependencies": {
     "@ctliz/agent-intercom-core": "0.2.0",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": "^0.99.1",
+    "@earendil-works/pi-coding-agent": "^0.99.1",
+    "@earendil-works/pi-tui": "^0.99.1",
     "tsx": "^4.20.0",
     "typebox": "*"
   },

package/skills/pi-intercom/SKILL.md

@@ -24,6 +24,19 @@ This skill covers how to handle those orchestrator-side escalations.
 - **Clarification loops**: Worker asks questions, planner answers, work continues
 - **Multi-session workflows**: Coordinate between specialized sessions (frontend/backend, research/implementation)
 
+## Codemode (Pi 0.99.1+)
+
+Active Intercom tools can be called from codemode as `await tools.intercom_send({...})`, `await tools.intercom_team({})`, and so on. Every result is `{ ok, text, data }`: check `ok`, then read structured delivery flags, session lists, team roster, or pending asks from `data`. Returned errors retain this object; invalid arguments, blocked calls, and thrown exceptions can still reject. Use `try/catch` or `Promise.allSettled()` for independent operations.
+
+```javascript
+const result = await tools.intercom_send({ to: "worker", message: "Tests passed." });
+return { ok: result.ok, delivered: result.data.delivered };
+```
+
+A deferred ask has `ok: true` and `data.pending: true`; it is not a failure. Do not proceed with dependent work until the actual answer arrives. Different recipients may be asked concurrently; never create a second unresolved ask to the same recipient. Delivery means durable queue acknowledgement, not task completion.
+
+For shell notifications, use `intercom-send <session-name-or-id> <message>`. It registers an independent send-only identity and prints JSON; it does not take over the current Pi session or track replies.
+
 ## Core Patterns
 
 ### Pattern 1: Planner-Worker Delegation
@@ -467,7 +480,7 @@ if (result.details?.pending) {
 
 ### Session name flips or registration reports `SESSION_ID_IN_USE`
 
-The same Pi session is open in more than one live runtime, such as a desktop terminal and a mobile/RPC host. Intercom keeps the first runtime authoritative instead of allowing the two clients to evict each other. Close or switch away from the duplicate runtime; one transcript/session ID must have only one live owner.
+The same Pi session is open in more than one live runtime, such as a desktop terminal and a mobile/RPC host. Intercom keeps the first runtime authoritative instead of allowing the two clients to evict each other. The conflicting runtime pauses automatic reconnect; `intercom_status` returns `ok: false` with `data.code: "SESSION_ID_IN_USE"`. Switch to a different session, or release the duplicate owner and `/reload`. One transcript/session ID must have only one live owner; do not auto-generate a replacement identity for a running session.
 
 ### Message not delivered
 

package/tool-result.ts

@@ -0,0 +1,26 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export const intercomOutputSchema = Type.Object({
+  ok: Type.Boolean(),
+  text: Type.String(),
+  data: Type.Record(Type.String(), Type.Unknown()),
+});
+
+type ToolResult = Awaited<ReturnType<ToolDefinition<any, any>["execute"]>>;
+
+/** Keep model/TUI content unchanged while giving codemode callers JSON data. */
+export function structuredIntercomResult(result: ToolResult): ToolResult {
+  const details = result.details ?? {};
+  const isError = result.isError === true || details.error === true || details.delivered === false;
+  return {
+    ...result,
+    details,
+    isError,
+    structuredContent: {
+      ok: !isError,
+      text: result.content.filter((item) => item.type === "text").map((item) => item.text).join("\n"),
+      data: JSON.parse(JSON.stringify(details)),
+    },
+  };
+}