@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-intercom/cli.ts

@@ -0,0 +1,343 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Minimal CLI for scripted access to the local pi-intercom broker.
+ *
+ * Commands:
+ *   npx --yes tsx ~/.selesai/agent/npm/node_modules/pi-intercom/cli.ts list [--json]
+ *   npx --yes tsx ~/.selesai/agent/npm/node_modules/pi-intercom/cli.ts send --to worker --text "build failed" [--name <bridge-name>] [--json]
+ *   npx --yes tsx ~/.selesai/agent/npm/node_modules/pi-intercom/cli.ts ask --to worker --text "status?" [--timeout-ms N] [--name <bridge-name>] [--json]
+ *
+ * The CLI registers as a regular session, so it shows up in the roster and
+ * replies can be routed back to it while it stays connected (`ask`).
+ *
+ * Exit codes: 0 ok | 1 usage, connection, or delivery failure | 2 ask timeout.
+ *
+ * Because it talks to the same-machine broker only, it can also be run over
+ * ssh on a remote machine to bridge coordination without opening any network
+ * listener:
+ *
+ *   ssh myserver 'npx --yes tsx ~/.selesai/agent/npm/node_modules/pi-intercom/cli.ts list'
+ */
+
+import { pathToFileURL } from "node:url";
+import { IntercomClient } from "./broker/client.ts";
+import { loadConfig } from "./config.ts";
+import {
+  parseRelayEnvelope,
+  relayMessage,
+  relaySenderName,
+  resolveOrigin,
+  type CrossMachineEnvelope,
+} from "./cross-machine-envelope.ts";
+import { sendCrossMachine, type CrossMachineDelivery } from "./cross-machine-transport.ts";
+import { parseCrossMachineTarget } from "./cross-machine-discovery.ts";
+import type { CrossMachineProvenance, Message, SessionInfo, SessionRegistration } from "./types.ts";
+
+export const CLI_USAGE = `usage: pi-intercom <list|send|ask> [--to <name|session-id>] [--text <message>]
+                        [--timeout-ms <n>] [--name <session-name>] [--json]`;
+
+export const DEFAULT_ASK_TIMEOUT_MS = 120_000;
+
+export interface CliOptions {
+  command: "list" | "send" | "ask" | "relay";
+  to: string | null;
+  text: string | null;
+  envelopeStdin: boolean;
+  timeoutMs: number;
+  name: string;
+  json: boolean;
+}
+
+export class CliUsageError extends Error {}
+
+export function parseCliArgs(argv: readonly string[]): CliOptions {
+  const opts: CliOptions = {
+    command: null as unknown as CliOptions["command"],
+    to: null,
+    text: null,
+    envelopeStdin: false,
+    timeoutMs: DEFAULT_ASK_TIMEOUT_MS,
+    name: "pi-intercom-cli",
+    json: false,
+  };
+
+  const [command, ...rest] = argv;
+  if (command !== "list" && command !== "send" && command !== "ask" && command !== "relay") {
+    throw new CliUsageError(`unknown command: ${String(command)}\n${CLI_USAGE}`);
+  }
+  opts.command = command;
+
+  if (command === "relay"
+    && (rest.filter((arg) => arg === "--envelope-stdin").length !== 1
+      || rest.filter((arg) => arg === "--json").length > 1
+      || rest.some((arg) => arg !== "--envelope-stdin" && arg !== "--json"))) {
+    throw new CliUsageError(`relay requires only --envelope-stdin (and optional --json)\n${CLI_USAGE}`);
+  }
+
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--json") {
+      opts.json = true;
+      continue;
+    }
+    if (arg === "--envelope-stdin") {
+      opts.envelopeStdin = true;
+      continue;
+    }
+    const value = rest[i + 1];
+    if (value === undefined) {
+      throw new CliUsageError(`missing value for ${arg}\n${CLI_USAGE}`);
+    }
+    if (arg === "--to") {
+      opts.to = value;
+    } else if (arg === "--text") {
+      opts.text = value;
+    } else if (arg === "--name") {
+      opts.name = value;
+    } else if (arg === "--timeout-ms") {
+      const parsed = Number(value);
+      if (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(parsed) || parsed <= 0) {
+        throw new CliUsageError(`invalid --timeout-ms value: ${value}`);
+      }
+      opts.timeoutMs = parsed;
+    } else {
+      throw new CliUsageError(`unknown option: ${arg}\n${CLI_USAGE}`);
+    }
+    i++;
+  }
+
+  if (opts.command === "relay") {
+    if (!opts.envelopeStdin || opts.to || opts.text || opts.name !== "pi-intercom-cli") {
+      throw new CliUsageError(`relay requires only --envelope-stdin (and optional --json)\n${CLI_USAGE}`);
+    }
+  } else {
+    if (opts.envelopeStdin) throw new CliUsageError(`--envelope-stdin is only valid for relay\n${CLI_USAGE}`);
+    if (opts.command !== "list") {
+      if (!opts.to) throw new CliUsageError(`--to is required for ${opts.command}\n${CLI_USAGE}`);
+      if (!opts.text) throw new CliUsageError(`--text is required for ${opts.command}\n${CLI_USAGE}`);
+    }
+  }
+
+  return opts;
+}
+
+/** The part of IntercomClient the CLI uses; injectable for tests. */
+export interface CliClient {
+  sessionId?: string | null;
+  connect(session: SessionRegistration, sessionId?: string): Promise<void>;
+  listSessions(options?: { timeoutMs?: number }): Promise<SessionInfo[]>;
+  send(to: string, options: { text: string; expectsReply?: boolean; crossMachine?: CrossMachineProvenance }): Promise<{ id: string; delivered: boolean; reason?: string }>;
+  on(event: "message", listener: (from: SessionInfo, message: Message) => void): unknown;
+  disconnect(): Promise<void>;
+}
+
+export interface CliDeps {
+  client: CliClient;
+  out?: { write(chunk: string): unknown };
+  err?: { write(chunk: string): unknown };
+  readStdin?: () => Promise<string>;
+  crossMachineSend?: (target: string, text: string, origin: ReturnType<typeof resolveOrigin>) => Promise<CrossMachineDelivery>;
+  machineName?: string;
+}
+
+export function buildCliRegistration(name: string, now = Date.now(), runtimeFallbackAlias = false): SessionRegistration {
+  return {
+    cwd: process.cwd(),
+    model: "pi-intercom-cli",
+    pid: process.pid,
+    startedAt: now,
+    lastActivity: now,
+    name,
+    ...(runtimeFallbackAlias ? { runtimeFallbackAlias: true } : {}),
+    status: "idle",
+  };
+}
+
+function sessionRow(session: SessionInfo): { name: string; id: string; model: string; status: string; cwd: string } {
+  return {
+    name: session.name ?? "(unnamed)",
+    id: session.id,
+    model: session.model,
+    status: session.status ?? "?",
+    cwd: session.cwd,
+  };
+}
+
+export async function runCli(argv: readonly string[], deps: CliDeps): Promise<number> {
+  const out = deps.out ?? process.stdout;
+  const err = deps.err ?? process.stderr;
+  const reportFailure = (message: string, code = 1, reason?: string): number => {
+    if (argv.includes("--json")) {
+      out.write(`${JSON.stringify({ ok: false, error: message, ...(reason ? { reason } : {}) })}\n`);
+    } else {
+      err.write(`${message}\n`);
+    }
+    return code;
+  };
+  let opts: CliOptions;
+  let relayEnvelope: CrossMachineEnvelope | undefined;
+  try {
+    opts = parseCliArgs(argv);
+    if (opts.command === "relay") {
+      relayEnvelope = parseRelayEnvelope(await (deps.readStdin ?? readProcessStdin)());
+      if (relayEnvelope.target.includes("@")) throw new CliUsageError("relay target must be a local name or session id");
+    }
+    if (opts.command === "ask" && opts.to!.includes("@")) throw new CliUsageError("ask only supports local names or session ids");
+    if (opts.command === "send" && opts.to!.includes("@")) {
+      parseCrossMachineTarget(opts.to!);
+    }
+  } catch (error) {
+    return reportFailure(error instanceof Error ? error.message : String(error));
+  }
+
+  const registrationName = relayEnvelope ? relaySenderName(relayEnvelope.origin) : opts.name;
+  try {
+    await deps.client.connect(buildCliRegistration(registrationName, Date.now(), Boolean(relayEnvelope)));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return reportFailure(`cannot reach the local intercom broker: ${message}\nis a pi session with pi-intercom loaded currently running on this machine?`);
+  }
+
+  try {
+    if (opts.command === "list") {
+      const sessions = await deps.client.listSessions();
+      if (opts.json) {
+        out.write(`${JSON.stringify({ ok: true, sessions: sessions.map(sessionRow) }, null, 2)}\n`);
+      } else {
+        for (const session of sessions) {
+          const row = sessionRow(session);
+          out.write(`${row.name}\t${row.id.slice(0, 8)}\t${row.model}\t${row.status}\t${row.cwd}\n`);
+        }
+      }
+      return 0;
+    }
+
+    if (opts.command === "relay") {
+      const envelope = relayEnvelope!;
+      const result = await deps.client.send(envelope.target, {
+        text: relayMessage(envelope),
+        crossMachine: {
+          type: "ssh-relay",
+          version: 1,
+          origin: envelope.origin,
+          trust: envelope.trust,
+        },
+      });
+      if (!result.delivered) return reportFailure(`relay delivery failed: ${result.reason ?? "unknown reason"}`);
+      if (opts.json) out.write(`${JSON.stringify({ ok: true, delivered: true, id: result.id, origin: relaySenderName(envelope.origin), trust: envelope.trust })}\n`);
+      else out.write(`relayed from ${relaySenderName(envelope.origin)} to ${envelope.target} (${result.id})\n`);
+      return 0;
+    }
+
+    if (opts.command === "send") {
+      if (opts.to!.includes("@")) {
+        if (!deps.crossMachineSend) return reportFailure("cross-machine delivery is unavailable");
+        try {
+          const sessions = await deps.client.listSessions();
+          const remote = await deps.crossMachineSend(opts.to as string, opts.text as string, resolveOrigin(sessions, opts.name, deps.machineName ?? "localhost", deps.client.sessionId));
+          if (opts.json) out.write(`${JSON.stringify({ ok: true, delivered: true, crossMachine: true, machine: remote.machine.label, target: remote.agent.name })}\n`);
+          else out.write(`delivered to ${relaySenderName({ name: remote.agent.name, machine: remote.machine.label })} over SSH\n`);
+          return 0;
+        } catch (error) {
+          return reportFailure(`explicit cross-machine delivery failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+      const result = await deps.client.send(opts.to as string, { text: opts.text as string });
+      if (!result.delivered) {
+        return reportFailure(`delivery failed: ${result.reason ?? "unknown reason"}`);
+      }
+      if (opts.json) {
+        out.write(`${JSON.stringify({ ok: true, delivered: true, id: result.id }, null, 2)}\n`);
+      } else {
+        out.write(`delivered to ${opts.to} (${result.id})\n`);
+      }
+      return 0;
+    }
+
+    // A reply can arrive before send() returns its message id.
+    type AskOutcome =
+      | { kind: "timeout" }
+      | { kind: "delivery-failure"; reason: string }
+      | { kind: "reply"; from: SessionInfo; text: string };
+    let settled = false;
+    const reply = await new Promise<AskOutcome>((resolve) => {
+      let sentId: string | undefined;
+      const earlyReplies = new Map<string, { from: SessionInfo; text: string }>();
+      const settle = (outcome: AskOutcome) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        resolve(outcome);
+      };
+      const timer = setTimeout(() => settle({ kind: "timeout" }), opts.timeoutMs);
+
+      deps.client.on("message", (from, message) => {
+        if (message.replyTo === undefined || settled) return;
+        if (sentId === message.replyTo) {
+          settle({ kind: "reply", from, text: message.content.text });
+        } else if (sentId === undefined) {
+          earlyReplies.set(message.replyTo, { from, text: message.content.text });
+        }
+      });
+
+      deps.client.send(opts.to as string, { text: opts.text as string, expectsReply: true }).then(
+        (result) => {
+          if (!result.delivered) {
+            settle({ kind: "delivery-failure", reason: result.reason ?? "unknown reason" });
+          } else {
+            sentId = result.id;
+            const early = earlyReplies.get(sentId);
+            if (early) settle({ kind: "reply", ...early });
+          }
+        },
+        (error: unknown) => {
+          settle({ kind: "delivery-failure", reason: error instanceof Error ? error.message : String(error) });
+        },
+      );
+    });
+
+    if (reply.kind === "timeout") {
+      return reportFailure(`ask timed out after ${opts.timeoutMs} ms waiting for a reply from ${opts.to}`, 2, "timeout");
+    }
+    if (reply.kind === "delivery-failure") {
+      return reportFailure(`delivery failed: ${reply.reason}`);
+    }
+    if (opts.json) {
+      out.write(`${JSON.stringify({ ok: true, from: reply.from.name ?? reply.from.id, text: reply.text }, null, 2)}\n`);
+    } else {
+      out.write(`${reply.text}\n`);
+    }
+    return 0;
+  } catch (error) {
+    return reportFailure(`intercom request failed: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    await deps.client.disconnect().catch(() => {});
+  }
+}
+
+async function readProcessStdin(): Promise<string> {
+  let value = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) value += chunk;
+  return value;
+}
+
+export async function runMain(argv: readonly string[] = process.argv.slice(2)): Promise<number> {
+  const config = loadConfig();
+  return runCli(argv, {
+    client: new IntercomClient(),
+    machineName: config.crossMachine.machineName,
+    crossMachineSend: (target, text, origin) => sendCrossMachine(target, text, origin, {
+      remoteCommand: config.crossMachine.remoteCommand,
+    }),
+  });
+}
+
+const invokedAsScript = process.argv[1] !== undefined
+  && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedAsScript) {
+  process.exit(await runMain());
+}

package/dist/extensions/pi-intercom/config.test.ts

@@ -41,6 +41,39 @@ test("loadConfig defaults inboundTrigger to current auto-trigger behavior", asyn
   try {
     await withAgentDir(root, () => {
       assert.equal(loadConfig().inboundTrigger, "always");
+      assert.equal(loadConfig().busyDelivery, "steer");
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("loadConfig defaults cross-machine routing", async () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-config-"));
+  try {
+    await withAgentDir(root, () => {
+      const config = loadConfig().crossMachine;
+      assert.equal(config.remoteCommand, "pi-intercom");
+      assert.equal(config.machineName.length > 0, true);
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("loadConfig accepts cross-machine overrides", async () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-config-"));
+  try {
+    mkdirSync(join(root, "intercom"), { recursive: true });
+    writeFileSync(join(root, "intercom", "config.json"), JSON.stringify({ crossMachine: {
+      machineName: "laptop",
+      remoteCommand: "/opt/tools/pi-intercom",
+    } }));
+    await withAgentDir(root, () => {
+      assert.deepEqual(loadConfig().crossMachine, {
+        machineName: "laptop",
+        remoteCommand: "/opt/tools/pi-intercom",
+      });
     });
   } finally {
     rmSync(root, { recursive: true, force: true });
@@ -51,9 +84,10 @@ test("loadConfig accepts inboundTrigger replies policy", async () => {
   const root = mkdtempSync(join(tmpdir(), "pi-intercom-config-"));
   try {
     mkdirSync(join(root, "intercom"), { recursive: true });
-    writeFileSync(join(root, "intercom", "config.json"), JSON.stringify({ inboundTrigger: "replies" }));
+    writeFileSync(join(root, "intercom", "config.json"), JSON.stringify({ inboundTrigger: "replies", busyDelivery: "human-first" }));
     await withAgentDir(root, () => {
       assert.equal(loadConfig().inboundTrigger, "replies");
+      assert.equal(loadConfig().busyDelivery, "human-first");
     });
   } finally {
     rmSync(root, { recursive: true, force: true });
@@ -102,3 +136,29 @@ test("loadConfig rejects invalid inboundTrigger values", async () => {
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+test("loadConfig rejects empty cross-machine strings", async () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-config-"));
+  try {
+    mkdirSync(join(root, "intercom"), { recursive: true });
+    writeFileSync(join(root, "intercom", "config.json"), JSON.stringify({ crossMachine: { remoteCommand: "  " } }));
+    await withAgentDir(root, () => {
+      assert.throws(() => loadConfig(), /"crossMachine.remoteCommand" must be a non-empty string/);
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("loadConfig rejects invalid busyDelivery values", async () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-config-"));
+  try {
+    mkdirSync(join(root, "intercom"), { recursive: true });
+    writeFileSync(join(root, "intercom", "config.json"), JSON.stringify({ busyDelivery: "prompt" }));
+    await withAgentDir(root, () => {
+      assert.throws(() => loadConfig(), /"busyDelivery" must be "steer" or "human-first"/);
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/dist/extensions/pi-intercom/config.ts

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
+import { hostname } from "os";
 import { getIntercomDirPath } from "./broker/paths.ts";
+import { defaultMachineName } from "./cross-machine-envelope.ts";
 
 const DEFAULT_ASK_TIMEOUT_MS = 10 * 60 * 1000;
 const INTERCOM_SCOPE_ID_ENV = "PI_INTERCOM_SCOPE_ID";
@@ -24,6 +26,14 @@ export function getIntercomScopeId(env: NodeJS.ProcessEnv = process.env): string
 }
 
 export type InboundTriggerPolicy = "always" | "replies" | "never";
+export type BusyDeliveryPolicy = "steer" | "human-first";
+
+export interface CrossMachineConfig {
+  /** Name peers use for this host in their Herdr saved-machine lists. */
+  machineName: string;
+  /** Command invoked through SSH on remote machines. */
+  remoteCommand: string;
+}
 
 export interface IntercomConfig {
   /** Broker command used to spawn the broker process (e.g. "npx" or "bun") */
@@ -38,6 +48,9 @@ export interface IntercomConfig {
   /** Controls whether inbound broker messages may automatically trigger a model turn */
   inboundTrigger: InboundTriggerPolicy;
 
+  /** Delivery priority for peers arriving during interactive agent runs */
+  busyDelivery: BusyDeliveryPolicy;
+
   /** Optional custom status suffix shown after automatic lifecycle status */
   status?: string;
 
@@ -49,6 +62,9 @@ export interface IntercomConfig {
   
   /** Show reply hint in incoming messages (default: true) */
   replyHint: boolean;
+
+  /** Cross-machine discovery and SSH relay settings. */
+  crossMachine: CrossMachineConfig;
 }
 
 export function getConfigPath(intercomDir: string = getIntercomDirPath()): string {
@@ -60,14 +76,19 @@ const defaults: IntercomConfig = {
   brokerArgs: ["--no-install", "tsx"],
   confirmSend: false,
   inboundTrigger: "always",
+  busyDelivery: "steer",
   enabled: true,
   replyHint: true,
+  crossMachine: {
+    machineName: defaultMachineName(hostname()),
+    remoteCommand: "pi-intercom",
+  },
 };
 
 export function loadConfig(): IntercomConfig {
   const configPath = getConfigPath();
   if (!existsSync(configPath)) {
-    return { ...defaults };
+    return { ...defaults, crossMachine: { ...defaults.crossMachine } };
   }
   
   try {
@@ -78,7 +99,10 @@ export function loadConfig(): IntercomConfig {
     }
 
     const parsedConfig = parsed as Record<string, unknown>;
-    const config: IntercomConfig = { ...defaults };
+    const config: IntercomConfig = {
+      ...defaults,
+      crossMachine: { ...defaults.crossMachine },
+    };
 
     if (Object.hasOwn(parsedConfig, "brokerCommand")) {
       if (typeof parsedConfig.brokerCommand !== "string") {
@@ -130,6 +154,13 @@ export function loadConfig(): IntercomConfig {
       config.inboundTrigger = parsedConfig.inboundTrigger;
     }
 
+    if (Object.hasOwn(parsedConfig, "busyDelivery")) {
+      if (parsedConfig.busyDelivery !== "steer" && parsedConfig.busyDelivery !== "human-first") {
+        throw new Error(`"busyDelivery" must be "steer" or "human-first"`);
+      }
+      config.busyDelivery = parsedConfig.busyDelivery;
+    }
+
     if (Object.hasOwn(parsedConfig, "replyHint")) {
       if (typeof parsedConfig.replyHint !== "boolean") {
         throw new Error(`"replyHint" must be a boolean`);
@@ -155,6 +186,26 @@ export function loadConfig(): IntercomConfig {
       config.stableId = stableId;
     }
 
+    if (Object.hasOwn(parsedConfig, "crossMachine")) {
+      const value = parsedConfig.crossMachine;
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`"crossMachine" must be an object`);
+      }
+      const crossMachine = value as Record<string, unknown>;
+      if (Object.hasOwn(crossMachine, "machineName")) {
+        if (typeof crossMachine.machineName !== "string" || !crossMachine.machineName.trim()) {
+          throw new Error(`"crossMachine.machineName" must be a non-empty string`);
+        }
+        config.crossMachine.machineName = crossMachine.machineName.trim();
+      }
+      if (Object.hasOwn(crossMachine, "remoteCommand")) {
+        if (typeof crossMachine.remoteCommand !== "string" || !crossMachine.remoteCommand.trim()) {
+          throw new Error(`"crossMachine.remoteCommand" must be a non-empty string`);
+        }
+        config.crossMachine.remoteCommand = crossMachine.remoteCommand.trim();
+      }
+    }
+
     return config;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);