@ctliz/agent-intercom-pi 0.14.1 → 0.14.4

package/README.md

@@ -19,7 +19,7 @@
 
 ## Pi 1.1 compatibility and codemode
 
-Version 0.14.1 is tested with Pi 1.1.0. Version 0.14.0 was tested with Pi 1.0.0, and 0.13.0 with Pi 0.99.1. The development test baseline now uses Pi 1.1.0; host-provided Pi modules remain peer dependencies, not runtime dependencies. The existing protocol v4 broker, durable queues, acknowledgements, and cross-harness routing are unchanged.
+Version 0.14.3 is tested with Pi 1.1.0. Version 0.14.0 was tested with Pi 1.0.0, and 0.13.0 with Pi 0.99.1. The development test baseline now uses Pi 1.1.0; host-provided Pi modules remain peer dependencies, not runtime dependencies. The existing protocol v4 broker, durable queues, acknowledgements, and cross-harness routing are unchanged.
 
 Pi 1.0 defaults to fullscreen; set `tuiMode` to `"regular"` or launch with `--tui-mode regular` to retain terminal scrollback. Codemode's shorter declarations preserve Intercom's structured `{ ok, text, data }` results and team guidelines. To check tool existence in a script, use `"intercom_send" in tools`, not `typeof tools.intercom_send`, because unknown members now throw. Restart existing Pi processes to use a newly installed Pi version; `/reload` only reloads resources inside the running version.
 
@@ -41,9 +41,11 @@ Concurrent sends and independent asks are supported; do not create two unresolve
 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.14.0 -- intercom-send worker 'Tests passed.'
+npm exec --yes --package=@ctliz/agent-intercom-pi@0.14.3 -- intercom-send worker 'Tests passed.'
 ```
 
+The default command disconnects after delivery and cannot receive a later reply. For a shell handoff requiring an acknowledgement, use `intercom-send --wait-reply 60 worker 'Please acknowledge this task.'`. It keeps its independent identity connected until the first message from that recipient or the timeout, prints delivery and reply as separate JSON lines, and exits with code 2 if no reply arrives. The recipient can use either `send` or a correlated reply. For ongoing delegation, use a persistent Codex MCP/`coi` session so questions and completion reports remain reachable after the acknowledgement. Do not send a task from a temporary `IntercomClient` and immediately disconnect when you expect responses.
+
 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.
@@ -163,7 +165,18 @@ Each pi session that has `pi-intercom` loaded and enabled connects to a tiny loc
 ## Install
 
 ```bash
-pi install npm:@ctliz/pi-intercom@0.14.0
+pi install npm:@ctliz/agent-intercom-pi
+```
+
+Starting with 0.14.3, `@ctliz/agent-intercom-pi` is the only npm release name. The legacy `@ctliz/pi-intercom` alias receives no new versions; its published history remains available. The 0.14.2 rename candidate was not published to npm. The GitHub repository and existing Git sources remain unchanged.
+
+Existing `@ctliz/agent-intercom-pi` users do not need to switch packages. Update with `pi update npm:@ctliz/agent-intercom-pi`, then run `/reload` in open Pi sessions. If the configured source is pinned to a version, reinstall the unpinned source above to receive future update notifications.
+
+If you installed the legacy alias, remove it before installing the supported name to avoid loading the same extension twice:
+
+```bash
+pi remove npm:@ctliz/pi-intercom
+pi install npm:@ctliz/agent-intercom-pi
 ```
 
 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.
@@ -916,7 +929,7 @@ Use pi-messenger for multi-agent swarms working on a shared task. Use pi-interco
 
 The `connect.1` tags, source commits, and published release assets are immutable and are not modified by this migration. Release notes may carry an explicit erratum, which corrects the description only and never moves a tag or replaces an asset.
 
-These packages are not published on the npm registry yet; install from the GitHub tags shown above.
+The historical `connect.*` Git tags shown above remain available. For current Pi installations, use the npm package in [Install](#install).
 
 ## Limitations
 
@@ -939,10 +952,9 @@ git tag -a vX.Y.Z -m "vX.Y.Z"
 git push origin vX.Y.Z
 ```
 
-The release workflow verifies that the tag points into `main`, runs typecheck and
-tests, publishes the public npm package with trusted OIDC provenance, and creates
-the GitHub Release. Existing npm versions and GitHub Releases are skipped safely
-when a workflow is rerun.
+The release workflow verifies that the tag points into `main` and the manifest name is `@ctliz/agent-intercom-pi`, runs typecheck and tests, publishes that one npm package with trusted OIDC provenance, and creates the GitHub Release. It does not publish or rewrite a second alias. Existing npm versions and GitHub Releases are skipped safely when a workflow is rerun.
+
+The npm trusted publisher is configured on **`@ctliz/agent-intercom-pi`** for GitHub owner `ctliz`, repository `agent-intercom-pi`, workflow filename `release.yml`, with no environment name (this workflow does not use one). Authorization is package-specific. Changing this account-side setting requires npm package-owner access; a repository commit alone cannot grant it. The workflow uses OIDC without a placeholder registry token.
 
 ## License
 

package/cli-send.ts

@@ -2,18 +2,31 @@ import { randomUUID } from "node:crypto";
 import { IntercomClient } from "./broker/client.ts";
 import { spawnBrokerIfNeeded } from "./broker/spawn.ts";
 import { loadConfig } from "./config.ts";
+import type { Message, SessionInfo } from "./types.ts";
 
 async function main(): Promise<void> {
-  const [to, ...parts] = process.argv.slice(2);
+  const args = process.argv.slice(2);
+  let waitMs = 0;
+  if (args[0] === "--wait-reply") {
+    args.shift();
+    const seconds = Number(args.shift());
+    if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 86400) {
+      throw new Error("--wait-reply requires a timeout in seconds (0 < seconds <= 86400)");
+    }
+    waitMs = seconds * 1000;
+  }
+  const [to, ...parts] = args;
   const message = parts.join(" ");
   if (!to?.trim() || !message.trim()) {
-    throw new Error("Usage: intercom-send <session-name-or-id> <message>");
+    throw new Error("Usage: intercom-send [--wait-reply <seconds>] <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 messageId = randomUUID();
   const now = Date.now();
+  let timer: NodeJS.Timeout | undefined;
   try {
     // Never inherit the calling Pi's session ID or take over its mailbox.
     await client.connect({
@@ -25,10 +38,35 @@ async function main(): Promise<void> {
       lastActivity: now,
       runtimeInstanceId: randomUUID(),
     });
-    const result = await client.send(to, { text: message });
+    let reply: Promise<{ from: SessionInfo; message: Message } | null> | undefined;
+    let target = to;
+    if (waitMs) {
+      const sessions = await client.listSessions();
+      const matches = sessions.filter((session) => session.id === to || session.name?.toLowerCase() === to.toLowerCase());
+      if (matches.length !== 1) throw new Error(matches.length ? "Ambiguous target; use the session ID" : "Session not found");
+      target = matches[0]!.id;
+      reply = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), waitMs);
+        client.on("message", (from: SessionInfo, incoming: Message, deliveryId: string) => {
+          if (from.id !== target || (incoming.replyTo && incoming.replyTo !== messageId)) return;
+          client.acknowledgeMessage(deliveryId);
+          resolve({ from, message: incoming });
+        });
+        client.once("disconnected", () => resolve(null));
+      });
+    }
+    const result = await client.send(target, { text: message, messageId, ...(waitMs ? { expectsReply: true } : {}) });
     console.log(JSON.stringify({ messageId: result.id, ...result }));
     if (!result.delivered) process.exitCode = 1;
+    else if (reply) {
+      const response = await reply;
+      console.log(JSON.stringify(response
+        ? { type: "reply", ...response }
+        : { type: "reply_wait_failed", code: client.isConnected() ? "REPLY_TIMEOUT" : "DISCONNECTED", messageId: result.id }));
+      if (!response) process.exitCode = 2;
+    }
   } finally {
+    clearTimeout(timer);
     await client.disconnect();
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctliz/agent-intercom-pi",
-  "version": "0.14.1",
+  "version": "0.14.4",
   "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",

package/skills/pi-intercom/SKILL.md

@@ -91,6 +91,8 @@ A deferred ask has `ok: true` and `data.pending: true`; it is not a failure. Do
 
 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.
 
+For a shell handoff requiring an acknowledgement, use `intercom-send --wait-reply 60 <recipient> <message>` to keep the sender connected until the first response or timeout. Use a persistent agent session for ongoing questions and completion reports. A temporary sender that disconnects after delivery cannot receive replies; `Session not found` on the return path does not mean the original task was undelivered.
+
 ## Core Patterns
 
 ### Pattern 1: Planner-Worker Delegation