@selesai/code 0.8.2 → 0.8.4

package/dist/extensions/pi-intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-intercom",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "license": "MIT",
   "type": "module",
   "main": "index.ts",
@@ -11,13 +11,14 @@
     "cwd.ts",
     "extension-api.ts",
     "format-context.ts",
+    "project-agent.ts",
     "reply-tracker.ts",
     "broker/**/*.ts",
     "ui/**/*.ts",
     "skills/**/*"
   ],
   "scripts": {
-    "test": "tsx --test broker/client.test.ts broker/extension.test.ts broker/framing.test.ts broker/paths.test.ts broker/runtime-claim.test.ts broker/spawn.test.ts config.test.ts cwd.test.ts format-context.test.ts reply-tracker.test.ts intercom.integration.test.ts test/inline-message.test.ts test/overlay-width.test.ts"
+    "test": "tsx --test broker/client.test.ts broker/client-liveness.test.ts broker/extension.test.ts broker/framing.test.ts broker/paths.test.ts broker/runtime-claim.test.ts broker/spawn.test.ts config.test.ts cwd.test.ts format-context.test.ts project-agent.test.ts reply-tracker.test.ts intercom.integration.test.ts test/inline-message.test.ts test/overlay-width.test.ts"
   },
   "keywords": [
     "pi-package"

package/dist/extensions/pi-intercom/project-agent.test.ts

@@ -0,0 +1,145 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  openProjectPane,
+  resolveTargetInCwd,
+  waitForProjectSession,
+  type HerdrClient,
+} from "./project-agent.ts";
+import type { SessionInfo } from "./types.ts";
+
+function session(id: string, name: string | undefined, cwd: string): SessionInfo {
+  return {
+    id,
+    ...(name ? { name } : {}),
+    cwd,
+    model: "test-model",
+    pid: process.pid,
+    startedAt: 1,
+    lastActivity: 1,
+  };
+}
+
+test("resolveTargetInCwd selects the sole peer in the requested cwd", () => {
+  const resolved = resolveTargetInCwd({
+    sessions: [
+      session("self", "self", "/repo-a"),
+      session("worker-a", "worker", "/repo-b"),
+      session("worker-other", "worker", "/repo-c"),
+    ],
+    currentSessionId: "self",
+    targetCwd: "/repo-b",
+  });
+
+  assert.equal(resolved.kind, "found");
+  assert.equal(resolved.session?.id, "worker-a");
+});
+
+test("resolveTargetInCwd fails when a cwd has multiple possible peers and no target", () => {
+  assert.throws(
+    () => resolveTargetInCwd({
+      sessions: [
+        session("self", "self", "/repo-a"),
+        session("worker-a", "worker-a", "/repo-b"),
+        session("worker-b", "worker-b", "/repo-b"),
+      ],
+      currentSessionId: "self",
+      targetCwd: "/repo-b",
+    }),
+    /Multiple intercom sessions are connected in \/repo-b/,
+  );
+});
+
+test("resolveTargetInCwd scopes names to the requested cwd", () => {
+  const resolved = resolveTargetInCwd({
+    sessions: [
+      session("self", "self", "/repo-a"),
+      session("worker-a", "worker", "/repo-b"),
+      session("worker-other", "worker", "/repo-c"),
+    ],
+    currentSessionId: "self",
+    targetCwd: "/repo-b",
+    to: "worker",
+  });
+
+  assert.equal(resolved.kind, "found");
+  assert.equal(resolved.session?.id, "worker-a");
+});
+
+test("openProjectPane opens a Herdr pane and runs pi in the project", async () => {
+  const root = mkdtempSync(join(tmpdir(), "pi-intercom-project-pane-"));
+  const project = join(root, "project");
+  mkdirSync(project);
+  const calls: string[][] = [];
+  const client: HerdrClient = {
+    async run(args) {
+      calls.push(args);
+      if (args[0] === "--version") return { ok: true, data: "herdr 0.7.5" };
+      if (args[0] === "pane" && args[1] === "split") return { ok: true, data: { pane: { id: "pane-1" } } };
+      if (args[0] === "pane" && args[1] === "run") return { ok: true, data: {} };
+      return { ok: false, error: { code: "VALIDATION_ERROR", message: `unexpected ${args.join(" ")}` } };
+    },
+  };
+
+  try {
+    const launched = await openProjectPane({ cwd: project, focus: false, client });
+
+    assert.equal(launched.paneId, "pane-1");
+    assert.equal(launched.herdrVersion, "herdr 0.7.5");
+    assert.deepEqual(calls[1], ["pane", "split", "--current", "--direction", "right", "--cwd", launched.projectRoot]);
+    assert.deepEqual(calls[2], ["pane", "run", "pane-1", "'pi'"]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("waitForProjectSession returns the new project-pane session when no target is named", async () => {
+  const before = [session("self", "self", "/repo-a")];
+  const after = [...before, session("pane-peer", "subagent-chat-pane", "/repo-b")];
+  let calls = 0;
+  const client = {
+    async listSessions() {
+      calls += 1;
+      return calls === 1 ? before : after;
+    },
+  };
+
+  const resolved = await waitForProjectSession(client, {
+    projectRoot: "/repo-b",
+    currentSessionId: "self",
+    beforeSessionIds: new Set(before.map((item) => item.id)),
+    pollMs: 1,
+    timeoutMs: 100,
+  });
+
+  assert.equal(resolved.id, "pane-peer");
+});
+
+test("waitForProjectSession honors the target guard after opening a project pane", async () => {
+  const before = [session("self", "self", "/repo-a")];
+  const afterUnnamed = [...before, session("pane-peer", "subagent-chat-pane", "/repo-b")];
+  const afterNamed = [...afterUnnamed, session("worker-id", "worker", "/repo-b")];
+  let calls = 0;
+  const client = {
+    async listSessions() {
+      calls += 1;
+      if (calls === 1) return before;
+      if (calls === 2) return afterUnnamed;
+      return afterNamed;
+    },
+  };
+
+  const resolved = await waitForProjectSession(client, {
+    projectRoot: "/repo-b",
+    currentSessionId: "self",
+    beforeSessionIds: new Set(before.map((item) => item.id)),
+    to: "worker",
+    pollMs: 1,
+    timeoutMs: 100,
+  });
+
+  assert.equal(resolved.id, "worker-id");
+});

package/dist/extensions/pi-intercom/project-agent.ts

@@ -0,0 +1,324 @@
+import { spawn, type ChildProcess } from "child_process";
+import { realpathSync, statSync } from "fs";
+import { resolve } from "path";
+import { sameCwd } from "./cwd.ts";
+import type { SessionInfo } from "./types.ts";
+
+const DEFAULT_PROJECT_AGENT_TIMEOUT_MS = 20_000;
+const DEFAULT_PROJECT_AGENT_POLL_MS = 250;
+
+export type HerdrErrorCode =
+  | "HERDR_UNAVAILABLE"
+  | "HERDR_UNSUPPORTED_VERSION"
+  | "PANE_GONE"
+  | "NOT_FOUND"
+  | "TIMEOUT"
+  | "VALIDATION_ERROR";
+
+export type HerdrResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; error: { code: HerdrErrorCode; message: string; details?: unknown } };
+
+export interface HerdrClient {
+  run<T = unknown>(args: string[], options?: { timeoutMs?: number; signal?: AbortSignal; textOk?: boolean }): Promise<HerdrResult<T>>;
+}
+
+type SpawnHerdr = (command: string, args: readonly string[], options: { shell: false; windowsHide: true; env: NodeJS.ProcessEnv }) => ChildProcess;
+
+export interface ProjectPaneLaunch {
+  paneId: string;
+  projectRoot: string;
+  command: string;
+  herdrVersion: string;
+}
+
+export interface ProjectTargetResolution {
+  kind: "found" | "missing";
+  session?: SessionInfo;
+  targetCwd: string;
+  reason?: string;
+}
+
+export interface ListSessionsClient {
+  listSessions(options?: { timeoutMs?: number }): Promise<SessionInfo[]>;
+}
+
+function error(code: HerdrErrorCode, message: string, details?: unknown): HerdrResult<never> {
+  return { ok: false, error: { code, message, ...(details !== undefined ? { details } : {}) } };
+}
+
+function parseLastJson(value: string): unknown | undefined {
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  try { return JSON.parse(trimmed) as unknown; } catch {}
+  for (const line of trimmed.split(/\r?\n/).reverse()) {
+    try { return JSON.parse(line) as unknown; } catch {}
+  }
+  return undefined;
+}
+
+function normalizeCode(raw: unknown): HerdrErrorCode {
+  const code = String(raw ?? "").toLowerCase();
+  if (code.includes("timeout") || code.includes("timed_out")) return "TIMEOUT";
+  if (code.includes("gone")) return "PANE_GONE";
+  if (code.includes("not_found") || code.includes("not-found") || code === "no_such_pane") return "NOT_FOUND";
+  return "VALIDATION_ERROR";
+}
+
+function createHerdrClient(options: { bin?: string; spawn?: SpawnHerdr } = {}): HerdrClient {
+  const bin = options.bin ?? process.env.HERDR_BIN ?? "herdr";
+  const spawnImpl = options.spawn ?? spawn;
+  return {
+    run<T>(args: string[], runOptions: { timeoutMs?: number; signal?: AbortSignal; textOk?: boolean } = {}): Promise<HerdrResult<T>> {
+      return new Promise((resolveResult) => {
+        let child: ChildProcess;
+        try {
+          child = spawnImpl(bin, args, { shell: false, windowsHide: true, env: process.env });
+        } catch (cause) {
+          const code = (cause as NodeJS.ErrnoException | undefined)?.code;
+          resolveResult(error("HERDR_UNAVAILABLE", code === "ENOENT"
+            ? "Herdr is not installed or is not on PATH. Install Herdr 0.7.5+ or set HERDR_BIN."
+            : `Failed to start Herdr: ${cause instanceof Error ? cause.message : String(cause)}`));
+          return;
+        }
+
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (result: HerdrResult<T>) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          runOptions.signal?.removeEventListener("abort", abort);
+          resolveResult(result);
+        };
+        const abort = () => {
+          child.kill();
+          finish(error("TIMEOUT", `Herdr command '${args.join(" ")}' was aborted.`));
+        };
+        const timer = setTimeout(() => {
+          child.kill();
+          finish(error("TIMEOUT", `Herdr command '${args.join(" ")}' timed out after ${runOptions.timeoutMs ?? 15_000}ms.`));
+        }, runOptions.timeoutMs ?? 15_000);
+        timer.unref?.();
+
+        if (runOptions.signal?.aborted) abort();
+        else runOptions.signal?.addEventListener("abort", abort, { once: true });
+        child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
+        child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+        child.on("error", (cause) => {
+          const code = (cause as NodeJS.ErrnoException).code;
+          finish(error("HERDR_UNAVAILABLE", code === "ENOENT"
+            ? "Herdr is not installed or is not on PATH. Install Herdr 0.7.5+ or set HERDR_BIN."
+            : `Failed to run Herdr: ${cause.message}`));
+        });
+        child.on("close", (exitCode) => {
+          const parsed = parseLastJson(stdout) ?? (exitCode === 0 ? undefined : parseLastJson(stderr));
+          if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && "error" in parsed) {
+            const raw = (parsed as { error?: { code?: unknown; message?: unknown } }).error;
+            finish(error(normalizeCode(raw?.code), String(raw?.message ?? "Herdr command failed."), raw));
+            return;
+          }
+          if (exitCode === 0) {
+            if (parsed !== undefined) {
+              const envelope = parsed as { result?: unknown };
+              finish({ ok: true, data: (envelope.result ?? parsed) as T });
+            } else if (runOptions.textOk) {
+              finish({ ok: true, data: stdout.trim() as T });
+            } else {
+              finish({ ok: true, data: {} as T });
+            }
+            return;
+          }
+          const message = stderr.split(/\r?\n/).find((line) => line.trim())?.trim() ?? `Herdr exited with code ${exitCode}.`;
+          finish(error("VALIDATION_ERROR", message, { exitCode }));
+        });
+      });
+    },
+  };
+}
+
+function formatHerdrError(input: { code: HerdrErrorCode; message: string }): string {
+  return `Herdr project pane error (${input.code}): ${input.message}`;
+}
+
+function parseHerdrVersion(value: string): { major: number; minor: number; patch: number } | undefined {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(value);
+  return match ? { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) } : undefined;
+}
+
+function supportsRawPanes(version: { major: number; minor: number; patch: number }): boolean {
+  return version.major > 0 || version.minor > 7 || (version.minor === 7 && version.patch >= 5);
+}
+
+async function detectHerdr(client: HerdrClient, signal?: AbortSignal): Promise<HerdrResult<{ versionText: string }>> {
+  const result = await client.run<string>(["--version"], { timeoutMs: 3_000, signal, textOk: true });
+  if (result.ok === false) return result;
+  const versionText = typeof result.data === "string" ? result.data : JSON.stringify(result.data);
+  const version = parseHerdrVersion(versionText);
+  if (!version) return error("VALIDATION_ERROR", `Could not parse the Herdr version from '${versionText}'.`);
+  if (!supportsRawPanes(version)) return error("HERDR_UNSUPPORTED_VERSION", `Herdr ${versionText} does not support raw panes. Upgrade to Herdr 0.7.5 or newer.`);
+  return { ok: true, data: { versionText } };
+}
+
+function extractPaneId(value: unknown): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  const pane = record.pane && typeof record.pane === "object" && !Array.isArray(record.pane) ? record.pane as Record<string, unknown> : record;
+  for (const key of ["pane_id", "paneId", "id"]) {
+    if (typeof pane[key] === "string") return pane[key];
+  }
+  return undefined;
+}
+
+function shellQuote(value: string): string {
+  if (process.platform === "win32") return `"${value.replaceAll('"', '\\"')}"`;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function resolveProjectRoot(cwd: string): string {
+  const resolved = resolve(cwd);
+  const stat = statSync(resolved);
+  if (!stat.isDirectory()) {
+    throw new Error(`Project target '${resolved}' is not a directory.`);
+  }
+  return realpathSync(resolved);
+}
+
+export function resolveTargetInCwd(input: {
+  sessions: SessionInfo[];
+  currentSessionId: string;
+  targetCwd: string;
+  to?: string;
+}): ProjectTargetResolution {
+  const inCwd = input.sessions.filter((session) => sameCwd(session.cwd, input.targetCwd));
+  const target = input.to?.trim();
+
+  if (!target) {
+    const candidates = inCwd.filter((session) => session.id !== input.currentSessionId);
+    if (candidates.length === 1) {
+      return { kind: "found", session: candidates[0], targetCwd: input.targetCwd };
+    }
+    if (candidates.length === 0) {
+      return { kind: "missing", targetCwd: input.targetCwd, reason: `No other intercom sessions are connected in ${input.targetCwd}.` };
+    }
+    throw new Error(`Multiple intercom sessions are connected in ${input.targetCwd}: ${formatSessionRefs(candidates)}. Specify 'to'.`);
+  }
+
+  const byId = inCwd.find((session) => session.id === target);
+  if (byId) return { kind: "found", session: byId, targetCwd: input.targetCwd };
+
+  const lowerName = target.toLowerCase();
+  const byName = inCwd.filter((session) => session.name?.toLowerCase() === lowerName);
+  if (byName.length === 1) return { kind: "found", session: byName[0], targetCwd: input.targetCwd };
+  if (byName.length > 1) {
+    throw new Error(`Multiple intercom sessions named "${target}" are connected in ${input.targetCwd}: ${formatSessionRefs(byName)}. Address one by session ID.`);
+  }
+
+  const byIdPrefix = inCwd.filter((session) => session.id.startsWith(target));
+  if (byIdPrefix.length === 1) return { kind: "found", session: byIdPrefix[0], targetCwd: input.targetCwd };
+  if (byIdPrefix.length > 1) {
+    throw new Error(`Multiple intercom sessions in ${input.targetCwd} match ID prefix "${target}". Use a longer session ID prefix.`);
+  }
+
+  return { kind: "missing", targetCwd: input.targetCwd, reason: `No intercom session matching "${target}" is connected in ${input.targetCwd}.` };
+}
+
+export async function openProjectPane(input: {
+  cwd: string;
+  focus?: boolean;
+  client?: HerdrClient;
+  signal?: AbortSignal;
+}): Promise<ProjectPaneLaunch> {
+  const projectRoot = resolveProjectRoot(input.cwd);
+  const client = input.client ?? createHerdrClient();
+  const detected = await detectHerdr(client, input.signal);
+  if (detected.ok === false) throw new Error(formatHerdrError(detected.error));
+
+  const splitArgs = ["pane", "split", "--current", "--direction", "right", "--cwd", projectRoot];
+  if (input.focus !== false) splitArgs.push("--focus");
+  const split = await client.run(splitArgs, { timeoutMs: 15_000, signal: input.signal });
+  if (split.ok === false) throw new Error(formatHerdrError(split.error));
+  const paneId = extractPaneId(split.data);
+  if (!paneId) throw new Error("Herdr project pane error (PANE_GONE): pane split returned no pane id.");
+
+  const command = shellQuote(process.env.PI_INTERCOM_PI_BIN?.trim() || process.env.PI_BIN?.trim() || "pi");
+  const started = await client.run(["pane", "run", paneId, command], { timeoutMs: 15_000, signal: input.signal });
+  if (started.ok === false) {
+    await client.run(["pane", "close", paneId], { timeoutMs: 5_000 });
+    throw new Error(formatHerdrError(started.error));
+  }
+
+  return { paneId, projectRoot, command, herdrVersion: detected.data.versionText };
+}
+
+export async function waitForProjectSession(client: ListSessionsClient, input: {
+  projectRoot: string;
+  currentSessionId: string;
+  beforeSessionIds: ReadonlySet<string>;
+  to?: string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  pollMs?: number;
+}): Promise<SessionInfo> {
+  const startedAt = Date.now();
+  const timeoutMs = input.timeoutMs ?? DEFAULT_PROJECT_AGENT_TIMEOUT_MS;
+  const pollMs = input.pollMs ?? DEFAULT_PROJECT_AGENT_POLL_MS;
+
+  while (Date.now() - startedAt < timeoutMs) {
+    if (input.signal?.aborted) throw new Error("Cancelled");
+    const sessions = await client.listSessions({ timeoutMs: Math.min(5_000, timeoutMs) });
+
+    if (input.to?.trim()) {
+      const resolved = resolveTargetInCwd({
+        sessions,
+        currentSessionId: input.currentSessionId,
+        targetCwd: input.projectRoot,
+        to: input.to,
+      });
+      if (resolved.kind === "found" && resolved.session) return resolved.session;
+      await sleep(pollMs, input.signal);
+      continue;
+    }
+
+    const newInProject = sessions.filter(
+      (session) => !input.beforeSessionIds.has(session.id) && sameCwd(session.cwd, input.projectRoot),
+    );
+    if (newInProject.length === 1) return newInProject[0]!;
+    if (newInProject.length > 1) {
+      throw new Error(`Multiple new intercom sessions registered in ${input.projectRoot}: ${formatSessionRefs(newInProject)}. Address one explicitly.`);
+    }
+
+    await sleep(pollMs, input.signal);
+  }
+
+  throw new Error(`Timed out waiting for a Pi intercom session to register in ${input.projectRoot}. The Herdr pane may still be starting, or pi-intercom may not be loaded there.`);
+}
+
+function formatSessionRefs(sessions: SessionInfo[]): string {
+  return sessions
+    .map((session) => `${session.name || "Unnamed session"} (${session.id.slice(0, 8)})`)
+    .join(", ");
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolveSleep, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("Cancelled"));
+      return;
+    }
+    let timer: NodeJS.Timeout;
+    const cleanup = () => signal?.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      clearTimeout(timer);
+      cleanup();
+      reject(new Error("Cancelled"));
+    };
+    timer = setTimeout(() => {
+      cleanup();
+      resolveSleep();
+    }, ms);
+    timer.unref?.();
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/dist/extensions/pi-intercom/reply-tracker.test.ts

@@ -50,10 +50,38 @@ test("reply with to resolves matching pending ask", () => {
   tracker.recordIncomingMessage(createSession("planner-id", "planner"), createMessage("ask-1", "First"), 1000);
   tracker.recordIncomingMessage(createSession("reviewer-id", "reviewer"), createMessage("ask-2", "Second"), 1001);
 
-  assert.equal(tracker.resolveReplyTarget({ to: "reviewer" }, 1002).message.id, "ask-2");
+  assert.equal(tracker.resolveReplyTarget({ to: "ReViEwEr" }, 1002).message.id, "ask-2");
   assert.equal(tracker.resolveReplyTarget({ to: "planner-id" }, 1002).message.id, "ask-1");
 });
 
+test("reply with to resolves a pending ask by a unique short session ID", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("019fd3c4-1111-7222-8333-444444444444", "planner"), createMessage("ask-1", "First"), 1000);
+  tracker.recordIncomingMessage(createSession("019fd3d5-1111-7222-8333-444444444444", "reviewer"), createMessage("ask-2", "Second"), 1001);
+
+  assert.equal(tracker.resolveReplyTarget({ to: "019fd3c4" }, 1002).message.id, "ask-1");
+  assert.equal(tracker.resolveReplyTarget({ to: "019fd3c4", replyTo: "ask-1" }, 1002).message.id, "ask-1");
+});
+
+test("reply with to prefers an exact sender name over another sender ID prefix", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("planner-session-id", "019fd3c4"), createMessage("ask-1", "Named sender"), 1000);
+  tracker.recordIncomingMessage(createSession("019fd3c4-1111-7222-8333-444444444444", "reviewer"), createMessage("ask-2", "Prefixed sender"), 1001);
+
+  assert.equal(tracker.resolveReplyTarget({ to: "019fd3c4" }, 1002).message.id, "ask-1");
+});
+
+test("reply with to clearly rejects an ambiguous session ID prefix", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("019fd3c4-1111-7222-8333-444444444444", "planner"), createMessage("ask-1", "First"), 1000);
+  tracker.recordIncomingMessage(createSession("019fd3c4-5555-7666-8777-888888888888", "reviewer"), createMessage("ask-2", "Second"), 1001);
+
+  assert.throws(
+    () => tracker.resolveReplyTarget({ to: "019fd3c4" }, 1002),
+    /Multiple pending asks match ID prefix "019fd3c4" — use a longer session ID prefix or specify `replyTo`/,
+  );
+});
+
 test("explicit to overrides the current turn context", () => {
   const tracker = new ReplyTracker();
   const current = tracker.recordIncomingMessage(createSession("planner-id", "planner"), createMessage("ask-1", "First"), 1000);
@@ -132,3 +160,60 @@ test("dismissing a pending ask removes queued turn context", () => {
 
   assert.throws(() => tracker.resolveReplyTarget({}, 1002), /No active intercom context to reply to/);
 });
+
+test("findUniquePendingAskFrom returns the sole match by exact sender ID", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("planner-id", "planner"), createMessage("ask-1", "Need a decision"), 1000);
+
+  const context = tracker.findUniquePendingAskFrom("planner-id", 1001);
+
+  assert.equal(context?.message.id, "ask-1");
+});
+
+test("findUniquePendingAskFrom returns the sole match by case-insensitive name", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("planner-id", "Planner"), createMessage("ask-1", "Need a decision"), 1000);
+
+  const context = tracker.findUniquePendingAskFrom("PLANNER", 1001);
+
+  assert.equal(context?.message.id, "ask-1");
+});
+
+test("findUniquePendingAskFrom does not resolve an ID prefix", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("abcdef-session-id", "planner"), createMessage("ask-1", "Need a decision"), 1000);
+
+  assert.equal(tracker.findUniquePendingAskFrom("abcdef", 1001), null);
+});
+
+test("findUniquePendingAskFrom returns null when there is no match", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("planner-id", "planner"), createMessage("ask-1", "Need a decision"), 1000);
+
+  assert.equal(tracker.findUniquePendingAskFrom("reviewer-id", 1001), null);
+});
+
+test("findUniquePendingAskFrom returns null when the sole match has expired", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("planner-id", "planner"), createMessage("ask-1", "Need a decision"), 1000);
+
+  const expiredAt = 1000 + getAskTimeoutMs() + 1;
+  assert.equal(tracker.findUniquePendingAskFrom("planner-id", expiredAt), null);
+});
+
+test("findUniquePendingAskFrom returns null when multiple asks match", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("planner-id", "planner"), createMessage("ask-1", "First"), 1000);
+  tracker.recordIncomingMessage(createSession("planner-id", "planner"), createMessage("ask-2", "Second"), 1001);
+
+  assert.equal(tracker.findUniquePendingAskFrom("planner-id", 1002), null);
+});
+
+test("findUniquePendingAskFrom does not mutate tracker state", () => {
+  const tracker = new ReplyTracker();
+  tracker.recordIncomingMessage(createSession("planner-id", "planner"), createMessage("ask-1", "Need a decision"), 1000);
+
+  tracker.findUniquePendingAskFrom("planner-id", 1001);
+
+  assert.deepEqual(tracker.listPending(1002).map((context) => context.message.id), ["ask-1"]);
+});

package/dist/extensions/pi-intercom/reply-tracker.ts

@@ -8,13 +8,42 @@ export interface IntercomContext {
 }
 
 function matchesPendingSender(context: IntercomContext, to: string): boolean {
-  if (context.from.id === to) {
+  if (context.from.id === to || context.from.id.startsWith(to)) {
     return true;
   }
 
   return context.from.name?.toLowerCase() === to.toLowerCase();
 }
 
+function resolvePendingSender(pending: IntercomContext[], to: string): IntercomContext {
+  const exactIdMatches = pending.filter((context) => context.from.id === to);
+  if (exactIdMatches.length === 1) {
+    return exactIdMatches[0]!;
+  }
+  if (exactIdMatches.length > 1) {
+    throw new Error(`Multiple pending asks from session ID "${to}" — specify \`replyTo\``);
+  }
+
+  const lowerTo = to.toLowerCase();
+  const exactNameMatches = pending.filter((context) => context.from.name?.toLowerCase() === lowerTo);
+  if (exactNameMatches.length === 1) {
+    return exactNameMatches[0]!;
+  }
+  if (exactNameMatches.length > 1) {
+    throw new Error(`Multiple pending asks match sender name "${to}" — specify a full session ID or \`replyTo\``);
+  }
+
+  const idPrefixMatches = pending.filter((context) => context.from.id.startsWith(to));
+  if (idPrefixMatches.length === 1) {
+    return idPrefixMatches[0]!;
+  }
+  if (idPrefixMatches.length > 1) {
+    throw new Error(`Multiple pending asks match ID prefix "${to}" — use a longer session ID prefix or specify \`replyTo\``);
+  }
+
+  throw new Error(`No pending ask from "${to}"`);
+}
+
 export class ReplyTracker {
   private readonly pendingAsks = new Map<string, IntercomContext>();
   private readonly pendingTurnContexts: IntercomContext[] = [];
@@ -65,14 +94,7 @@ export class ReplyTracker {
 
     const pending = Array.from(this.pendingAsks.values());
     if (options.to) {
-      const matches = pending.filter((context) => matchesPendingSender(context, options.to!));
-      if (matches.length === 1) {
-        return matches[0]!;
-      }
-      if (matches.length > 1) {
-        throw new Error(`Multiple pending asks from "${options.to}" — use the sender session ID instead.`);
-      }
-      throw new Error(`No pending ask from "${options.to}"`);
+      return resolvePendingSender(pending, options.to);
     }
 
     if (this.currentTurnContext) {
@@ -89,6 +111,16 @@ export class ReplyTracker {
     throw new Error("Multiple pending asks — specify `to`");
   }
 
+  findUniquePendingAskFrom(to: string, now = Date.now()): IntercomContext | null {
+    const candidates = Array.from(this.pendingAsks.values()).filter((context) => {
+      if (now - context.receivedAt > this.askTimeoutMs) {
+        return false;
+      }
+      return context.from.id === to || context.from.name?.toLowerCase() === to.toLowerCase();
+    });
+    return candidates.length === 1 ? candidates[0]! : null;
+  }
+
   markReplied(replyTo: string): void {
     this.dismissPendingAsk(replyTo);
   }