@selesai/code 0.13.12 → 0.13.13

package/dist/extensions/pi-intercom/skills/pi-intercom/SKILL.md

@@ -1,452 +0,0 @@
----
-name: pi-intercom
-description: |
-  Streamline session-to-session coordination with pi-intercom. Send messages,
-  delegate tasks, and coordinate work across multiple Selesai sessions on the same
-  machine. Use for planner-worker workflows, cross-session context sharing,
-  and real-time collaboration between sessions.
----
-
-# Selesai Intercom Skill
-
-Use this skill when you need to coordinate work across multiple Selesai sessions
-running on the same machine. Selesai-intercom enables direct 1:1 messaging between
-sessions for delegation, context sharing, and collaborative workflows.
-
-When you are supervising `pi-subagents`, delegated child agents can escalate to
-you via `contact_supervisor` if `pi-subagents` supplied child bridge metadata.
-This skill covers how to handle those orchestrator-side escalations.
-
-## When to Use
-
-- **Task delegation**: Split work between a planner session and worker sessions
-- **Context handoffs**: Send findings from a research session to an execution session
-- **Clarification loops**: Worker asks questions, planner answers, work continues
-- **Multi-session workflows**: Coordinate between specialized sessions (frontend/backend, research/implementation)
-- **Cross-codebase peer messages**: Message an explicit live peer in another project, or open a visible Herdr project pane when a long-lived conversation is needed
-
-## Core Patterns
-
-### Pattern 1: Planner-Worker Delegation
-
-The most common pattern. One session holds the big picture, others do hands-on work.
-
-**Setup** (in each session):
-```
-/name planner    # Terminal 1
-/name worker     # Terminal 2
-```
-
-**Planner delegates a task** (fire-and-forget):
-```typescript
-intercom({
-  action: "send",
-  to: "worker",
-  message: "Task-3: Add retry logic to API client. Key files: src/api/client.ts. Ask if anything's unclear."
-})
-```
-
-**Worker asks for clarification** (blocks until answer):
-```typescript
-intercom({
-  action: "ask",
-  to: "planner",
-  message: "Should I use exponential backoff or fixed intervals?"
-})
-// → Returns the planner's reply as the result
-```
-
-**Worker reports completion**:
-```typescript
-intercom({
-  action: "ask",
-  to: "planner",
-  message: "Task-3 complete. Added exponential backoff (100ms → 1600ms, max 5 retries). Ready for task-4?"
-})
-```
-
-### Pattern 2: Quick Status Check
-
-Before sending, verify who's connected:
-
-```typescript
-intercom({ action: "list" })
-// → Shows all connected sessions with names, cwd, models, and live status (`idle`, `thinking`, `tool:<name>`)
-```
-
-### Pattern 3: Reply Naturally
-
-When responding to an inbound ask, prefer `reply` instead of reconstructing raw IDs:
-
-```typescript
-// In the turn triggered by the ask:
-intercom({
-  action: "reply",
-  message: "Use exponential backoff starting at 100ms."
-})
-
-// If replying later and there might be more than one pending ask:
-intercom({ action: "pending" })
-intercom({ action: "reply", to: "planner", message: "Use exponential backoff starting at 100ms." })
-```
-
-`reply` still preserves exact threading under the hood by sending the response with the original `replyTo` value.
-
-### Pattern 4: Broadcast to Multiple Workers
-
-Send to multiple sessions in parallel:
-
-```typescript
-const workers = ["worker-1", "worker-2", "worker-3"];
-const task = "Check for null pointer exceptions in your assigned files";
-
-// Fire-and-forget to all workers
-workers.forEach(w => 
-  intercom({ action: "send", to: w, message: task })
-);
-```
-
-### Pattern 5: Send with Attachments
-
-Share code snippets, files, or context:
-
-```typescript
-intercom({
-  action: "send",
-  to: "worker",
-  message: "Here's the fix for the auth issue:",
-  attachments: [{
-    type: "snippet",
-    name: "auth.ts",
-    language: "typescript",
-    content: `function validateUser(user: User | null) {
-  if (!user) throw new Error("User required");
-  return user.email?.includes("@");
-}`
-  }]
-})
-```
-
-### Pattern 6: Cross-Codebase Peer Messages
-
-Use `to` alone to message any explicit live peer on the machine, even when it is
-in another codebase. Use `cwd` alone when there should be exactly one live peer
-in that repo. Use `to` plus `cwd` when the directory is a safety guard.
-
-```typescript
-intercom({
-  action: "ask",
-  cwd: "/path/to/other-repo",
-  to: "workbench-agent",
-  message: "Which module owns workbench source slices?"
-})
-```
-
-Only open a Herdr project pane when you need a durable visible peer session in
-that repo. For bounded work, prefer `pi-subagents` with an explicit `cwd`; the
-child can use `contact_supervisor` for owner decisions and regular `intercom`
-for explicit peer coordination.
-
-```typescript
-intercom({
-  action: "send",
-  cwd: "/path/to/other-repo",
-  openProjectPaneIfMissing: true,
-  message: "Let's discuss the workbench API ergonomics in this repo."
-})
-```
-
-If a live session already exists in that `cwd`, intercom reuses it. If multiple
-sessions are active there, pass `to` to select one by name or session ID.
-
-### Pattern 7: Handle Subagent Escalations (Orchestrator Side)
-
-When `pi-subagents` spawns a delegated child and supplies child bridge metadata,
-that child can reach you through `contact_supervisor`. You receive a formatted
-message that includes run metadata:
-
-```
-**From subagent-worker-78f659a3-1**
-
-Subagent needs a supervisor decision.
-Run: 78f659a3
-Agent: worker
-Child index: 0
-
-Which API should I use?
-```
-
-**Reply using `reply`:**
-
-```typescript
-// The reply hint in the incoming message will show the exact call:
-intercom({ action: "reply", message: "Use the stable v2 API." })
-```
-
-This works because `reply` resolves the correct sender and message ID automatically.
-
-**Three types of escalations to expect:**
-
-| Type | What it means | How to respond |
-|------|---------------|----------------|
-| `need_decision` | Subagent is blocked and waiting for your answer. Uses the shared ask timeout: 10 minutes by default, configurable with `PI_INTERCOM_ASK_TIMEOUT_MS`. | Reply promptly with a clear decision. If you need more context, ask follow-up questions via `reply`. |
-| `interview_request` | Subagent needs multiple structured answers in one blocking exchange. Uses the shared ask timeout: 10 minutes by default, configurable with `PI_INTERCOM_ASK_TIMEOUT_MS`. | Reply with plain JSON or a fenced `json` block using the provided `{ "responses": [...] }` shape. |
-| `progress_update` | Subagent is sharing meaningful progress or a plan-changing discovery. Not blocking. | Read and acknowledge. No reply required unless you want to redirect. |
-
-**When a subagent asks:**
-
-```typescript
-// In the turn triggered by the incoming ask:
-intercom({ action: "reply", message: "Use exponential backoff, max 3 retries." })
-```
-
-**When a subagent sends an interview request:**
-
-Read the rendered questions in the incoming message and reply with the exact ids in JSON. `info` questions are context-only and do not need response entries:
-
-```typescript
-intercom({
-  action: "reply",
-  message: "```json\n{\n  \"responses\": [\n    { \"id\": \"api\", \"value\": \"Stable API\" },\n    { \"id\": \"constraints\", \"value\": \"Keep the public error shape unchanged.\" }\n  ]\n}\n```"
-})
-```
-
-**If you receive multiple pending asks from different subagents:**
-
-```typescript
-intercom({ action: "pending" })
-// → Shows all unresolved inbound asks with sender, elapsed time, and preview
-
-intercom({ action: "reply", to: "subagent-worker-78f659a3-1", message: "Use the v2 API." })
-```
-
-**Important:** Only sessions where `pi-subagents` supplied child bridge metadata
-get the `contact_supervisor` tool. Normal sessions use the regular `intercom`
-tool. If you see the formatted supervisor decision/progress update message, treat
-it as a `contact_supervisor` escalation. A subagent may use regular `intercom` for
-peer coordination, including peers in other directories, but owner decisions and
-new visible project panes should go through the supervisor.
-
-## Key Differences
-
-| Action | Behavior | Use When |
-|--------|----------|----------|
-| `send` | Fire-and-forget; infers the sole pending ask as its reply | You don't need a response |
-| `ask` | Blocks until reply (10 min default, configurable with `PI_INTERCOM_ASK_TIMEOUT_MS`) | You need an answer to continue |
-| `reply` | Responds to the active or pending inbound ask | You were asked something and need to answer naturally |
-| `pending` | Lists unresolved inbound asks | You need to see who is waiting before replying |
-| `list` | Returns all sessions with live status | You need to discover targets or choose an idle peer |
-| `status` | Returns your connection state | Troubleshooting |
-
-## Visible Peer Sessions
-
-For bounded cross-codebase work, prefer `pi-subagents` with an explicit `cwd`.
-Use `intercom({ action: "send", cwd: "/path", openProjectPaneIfMissing: true, ... })`
-only when a long-lived visible peer session is useful.
-
-If Herdr is unavailable, do not invent a terminal fallback inside this workflow.
-Ask the user before opening another visible surface manually.
-
-## Important Constraints
-
-### `ask` Limitations
-
-- **Connected targets only**: `ask` fails immediately when the target is not in the live intercom roster. Use `list` before asking when liveness is uncertain; use `send` for non-blocking mailbox delivery.
-- **Configurable timeout**: If no reply arrives before the shared ask timeout, the ask fails. The default is 10 minutes; set `PI_INTERCOM_ASK_TIMEOUT_MS` to a positive millisecond value to change it.
-- **One at a time**: Cannot have multiple pending asks from the same session
-- **Cannot self-target**: A session cannot ask itself, including through disconnected-mailbox remapping
-
-```typescript
-// Check if already waiting before asking
-const result = await intercom({ action: "ask", to: "planner", message: "..." });
-if (result.isError && result.content[0].text.includes("Already waiting")) {
-  // Use send instead, or wait for current ask to complete
-}
-```
-
-### `send` Behavior
-
-- **No timeout**: Message is delivered or fails immediately
-- **Sole pending ask inference**: If the destination has exactly one pending inbound ask, `send` attaches its `replyTo` and reports `Reply sent to <target> (inferred from pending ask)`
-- **Ambiguity stays unthreaded**: Zero or multiple matching asks leave the send as an ordinary message
-- **Confirmation dialogs**: If `confirmSend: true` in config, interactive sessions confirm ordinary and inferred sends
-- **Explicit replies skip confirmation**: A caller-supplied `replyTo` skips the dialog
-
-## Best Practices
-
-### Use `ask` for blocking workflows
-
-When the worker needs information to proceed:
-
-```typescript
-// GOOD: Worker blocks until planner responds
-const reply = await intercom({
-  action: "ask",
-  to: "planner",
-  message: "API rate limit is 100/min. Should I implement client-side throttling or batching?"
-});
-// Continue with the answer...
-```
-
-### Use `send` for notifications
-
-When you just want to inform:
-
-```typescript
-// GOOD: Fire-and-forget notification
-intercom({
-  action: "send",
-  to: "reviewer",
-  message: "PR #123 is ready for review. Key changes in auth.ts."
-});
-// Continue immediately, don't wait
-```
-
-### Name sessions meaningfully
-
-Use `/name` so others can target you easily:
-
-```
-/name api-worker
-/name frontend-dev
-/name planner
-```
-
-## Error Handling
-
-### Common Errors and Solutions
-
-**"Already waiting for a reply"**
-```typescript
-// You can only have one pending ask at a time
-// Option 1: Use send instead
-intercom({ action: "send", to: "planner", message: "..." });
-
-// Option 2: Wait for current ask to complete first
-```
-
-**"Cannot message the current session"**
-```typescript
-// You cannot target yourself
-// This usually means you confused session names - double-check the target
-```
-
-**"Session not found"**
-```typescript
-const result = await intercom({ action: "send", to: "worker", message: "..." });
-if (!result.delivered) {
-  console.log("Failed:", result.reason);
-  // → "Session not found" - check the name and list available sessions
-  await intercom({ action: "list" });
-}
-```
-Replies to recently disconnected explicitly named senders can be queued by the broker and delivered if that sender reconnects with the same name and directory. Runtime-only `subagent-chat-...` aliases are not reconnect identities. New `send` calls may target a known live or recently disconnected session; blocking `ask` calls require a live target.
-
-**Ask timeout**
-```typescript
-// The ask will reject with a timeout error
-// Default: 10 minutes
-// Override: set PI_INTERCOM_ASK_TIMEOUT_MS to a positive millisecond value
-// For longer tasks, use send + follow-up ask pattern
-```
-
-## Troubleshooting
-
-### Session not appearing in list
-
-1. Check intercom is enabled: `intercom({ action: "status" })`
-2. Verify the target session has loaded pi-intercom
-3. Ensure both sessions are on the same machine (intercom is same-machine only)
-
-### Message not delivered
-
-```typescript
-const result = await intercom({ action: "send", to: "worker", message: "..." });
-if (!result.delivered) {
-  console.log("Failed:", result.reason);
-  // → "Session not found" or delivery failure reason
-}
-```
-
-### Connection lost
-
-Sessions automatically reconnect if the broker restarts. If persistently disconnected:
-
-```typescript
-intercom({ action: "status" })
-// Check if broker is running and restart if needed
-```
-
-## Common Workflows
-
-### Research → Implementation Handoff
-
-```typescript
-// Research session finds relevant code
-intercom({
-  action: "send",
-  to: "impl-session",
-  message: "Found the bug. The issue is in validateUser() - it doesn't check for null.",
-  attachments: [{
-    type: "snippet",
-    name: "validate.ts",
-    language: "typescript",
-    content: `// Line 45-52 - missing null check
-function validateUser(user: User) {
-  return user.email?.includes("@"); // crashes if user is null
-}`
-  }]
-});
-```
-
-### Pair Debugging
-
-```typescript
-// Session A encounters error
-intercom({
-  action: "ask",
-  to: "session-b",
-  message: "Getting 'Cannot read property of undefined' at line 78. Can you check if data.users is populated before this call?"
-});
-
-// Session B investigates and replies
-intercom({
-  action: "reply",
-  message: "data.users is null. The fetch failed silently. Add error handling in loadUsers()."
-});
-```
-
-### Progress Reporting
-
-```typescript
-// Worker sends periodic updates
-intercom({ action: "send", to: "planner", message: "Task-1 complete (15min). Starting Task-2." });
-// ... work ...
-intercom({ action: "send", to: "planner", message: "Task-2 complete (30min). Task-3 blocked - need API key." });
-// ... get unblocked ...
-intercom({ action: "send", to: "planner", message: "Task-3 complete. All done." });
-```
-
-### Long-Running Task with Checkpoints
-
-```typescript
-// For tasks that might exceed the ask timeout, use send + periodic asks
-
-// 1. Initial send with full context
-intercom({
-  action: "send",
-  to: "worker",
-  message: "Implement user authentication. This will take 30+ minutes. I'll check in at milestones."
-});
-
-// 2. Worker sends progress via send (no timeout)
-intercom({ action: "send", to: "planner", message: "Milestone 1: Login form complete (10min)" });
-
-// 3. Worker asks for specific decision when needed
-const decision = await intercom({
-  action: "ask",
-  to: "planner",
-  message: "Should we use JWT or session cookies? Need decision to continue."
-});
-// Continue with decision...
-```

package/dist/extensions/pi-intercom/test/inline-message.test.ts

@@ -1,184 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { stripVTControlCharacters } from "node:util";
-
-import { visibleWidth } from "@earendil-works/pi-tui";
-import { InlineMessageComponent } from "../ui/inline-message.ts";
-import type { Message, SessionInfo } from "../types.ts";
-
-const theme = {
-  fg(_name: string, text: string): string {
-    return text;
-  },
-};
-
-const from: SessionInfo = {
-  id: "session-12345678",
-  name: "sender",
-  cwd: "/tmp/project",
-  model: "model",
-  pid: 1,
-  startedAt: 0,
-  lastActivity: 0,
-};
-
-const message: Message = {
-  id: "message-1",
-  timestamp: 0,
-  content: {
-    text: "This is a long message that should use the available terminal width instead of a narrow fixed card.",
-  },
-};
-
-test("inline intercom messages render at the available terminal width", () => {
-  const component = new InlineMessageComponent(from, message, theme as any);
-
-  const lines = component.render(120);
-
-  assert.ok(lines.length > 0);
-  for (const line of lines) assert.equal(visibleWidth(line), 120);
-});
-
-test("expanded inline intercom messages show the full body without collapse controls", () => {
-  const component = new InlineMessageComponent(from, message, theme as any, "intercom({ action: \"reply\", message: \"...\" })");
-
-  const rendered = component.render(100).join("\n");
-
-  assert.match(rendered, /available terminal width/);
-  assert.match(rendered, /narrow fixed/);
-  assert.match(rendered, /card/);
-  assert.match(rendered, /To reply: intercom/);
-  assert.doesNotMatch(rendered, /Ctrl\+O/);
-});
-
-test("collapsed inline intercom messages keep preview, reply hint, and expand key visible", () => {
-  const component = new InlineMessageComponent(
-    from,
-    {
-      ...message,
-      content: {
-        text: "Alpha beta gamma delta epsilon zeta eta theta iota kappa lambda mu. This tail should only appear when expanded because the collapsed preview is intentionally brief.",
-        attachments: [{ type: "snippet", name: "note.txt", content: "important details" }],
-      },
-    },
-    theme as any,
-    "intercom({ action: \"reply\", message: \"...\" })",
-    undefined,
-    true,
-  );
-
-  const lines = component.render(120);
-  const rendered = lines.join("\n");
-
-  assert.equal(lines.length, 4);
-  for (const line of lines) assert.equal(visibleWidth(line), 120);
-  assert.match(rendered, /Alpha beta gamma/);
-  assert.doesNotMatch(rendered, /intentionally brief/);
-  assert.match(rendered, /To reply: intercom/);
-  assert.match(rendered, /Ctrl\+O/);
-  assert.match(rendered, /1 attachment/);
-});
-
-const roleCodes = {
-  accent: 31,
-  toolTitle: 32,
-  text: 33,
-  muted: 34,
-  dim: 35,
-} as const;
-
-function styledTheme(calls: string[] = []) {
-  return {
-    fg(name: keyof typeof roleCodes, text: string): string {
-      calls.push(name);
-      return `\u001b[${roleCodes[name]}m${text}\u001b[0m`;
-    },
-  };
-}
-
-test("inline message colors follow the tool-title, text, muted-border, and dim-metadata hierarchy", () => {
-  const calls: string[] = [];
-  const component = new InlineMessageComponent(
-    from,
-    {
-      ...message,
-      replyTo: "parent-message-id",
-      content: {
-        text: "Body copy",
-        attachments: [{ type: "snippet", name: "note.txt", content: "details" }],
-      },
-    },
-    styledTheme(calls) as any,
-    "intercom reply",
-  );
-
-  const lines = component.render(72);
-  const rendered = lines.join("\n");
-
-  assert.match(lines[0], /^\u001b\[34m╭\u001b\[0m\u001b\[32m From:/);
-  assert.match(rendered, /\u001b\[34m│\u001b\[0m\u001b\[33mBody copy\u001b\[0m/);
-  assert.match(rendered, /\u001b\[35m To reply: intercom reply\u001b\[0m/);
-  assert.match(rendered, /\u001b\[35m Attachment: note\.txt\u001b\[0m/);
-  assert.match(rendered, /\u001b\[35m Reply to parent-m\u001b\[0m/);
-  assert.match(lines.at(-1)!, /^\u001b\[34m╰─+╯\u001b\[0m$/);
-  assert.ok(calls.includes("toolTitle"));
-  assert.ok(calls.includes("text"));
-  assert.ok(calls.includes("muted"));
-  assert.ok(calls.includes("dim"));
-  assert.ok(!calls.includes("accent"));
-});
-
-test("collapsed inline messages preserve the same hierarchy without accent", () => {
-  const calls: string[] = [];
-  const component = new InlineMessageComponent(from, message, styledTheme(calls) as any, "intercom reply", undefined, true);
-
-  const rendered = component.render(72).join("\n");
-
-  assert.match(rendered, /\u001b\[32m From:/);
-  assert.match(rendered, /\u001b\[33mThis is a long message/);
-  assert.match(rendered, /\u001b\[35m To reply:/);
-  assert.ok(!calls.includes("accent"));
-});
-
-test("semantic styling remains ANSI- and Unicode-width safe", () => {
-  const unicodeFrom = { ...from, name: "送信者🛰️", cwd: "/tmp/計画" };
-  const unicodeMessage = {
-    ...message,
-    content: { text: "\u001b[36m色付き本文\u001b[0m with emoji 🧪 and a long Unicode tail 計画計画計画" },
-  };
-  const component = new InlineMessageComponent(unicodeFrom, unicodeMessage, styledTheme() as any, "返信");
-
-  for (const width of [18, 31, 52]) {
-    const lines = component.render(width);
-    assert.ok(lines.length > 0);
-    for (const line of lines) {
-      assert.equal(visibleWidth(line), width, `${width}: ${stripVTControlCharacters(line)}`);
-    }
-  }
-});
-
-test("inline messages pick up mutable theme proxy changes on rerender", () => {
-  const palette: Record<string, number> = { ...roleCodes };
-  const mutableTheme = new Proxy(
-    {},
-    {
-      get(_target, property) {
-        if (property !== "fg") return undefined;
-        return (name: string, text: string) => `\u001b[${palette[name]}m${text}\u001b[0m`;
-      },
-    },
-  );
-  const component = new InlineMessageComponent(from, message, mutableTheme as any);
-
-  const before = component.render(72).join("\n");
-  palette.toolTitle = 96;
-  palette.text = 97;
-  palette.muted = 90;
-  const after = component.render(72).join("\n");
-
-  assert.match(before, /\u001b\[32m From:/);
-  assert.match(after, /\u001b\[96m From:/);
-  assert.match(after, /\u001b\[97mThis is a long message/);
-  assert.match(after, /\u001b\[90m╭/);
-  assert.notEqual(before, after);
-});

package/dist/extensions/pi-intercom/test/overlay-width.test.ts

@@ -1,66 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import { visibleWidth } from "@earendil-works/pi-tui";
-import { ComposeOverlay } from "../ui/compose.ts";
-import { SessionListOverlay } from "../ui/session-list.ts";
-import type { SessionInfo } from "../types.ts";
-
-const theme = {
-  fg(_name: string, text: string): string {
-    return text;
-  },
-  bold(text: string): string {
-    return text;
-  },
-};
-
-const keybindings = {
-  matches(): boolean {
-    return false;
-  },
-  getKeys(id: string): string[] {
-    return id.includes("confirm") ? ["enter"] : ["escape", "ctrl+c"];
-  },
-};
-
-const session: SessionInfo = {
-  id: "session-12345678",
-  name: "subagent-chat-019ecaf6",
-  cwd: "/Users/envvar/.config/ghostty",
-  model: "bsy-deepseek-v4-pro",
-  pid: 1,
-  startedAt: 0,
-  lastActivity: 0,
-};
-
-function assertLineWidths(label: string, lines: string[], expectedWidth: number): void {
-  assert.ok(lines.length > 0, `${label} should render lines`);
-  for (const [index, line] of lines.entries()) {
-    assert.equal(visibleWidth(line), expectedWidth, `${label} line ${index} should match overlay width`);
-  }
-}
-
-test("compose overlay renders lines at the declared overlay width", () => {
-  const overlay = new ComposeOverlay(
-    { requestRender() {} } as any,
-    theme as any,
-    keybindings as any,
-    session,
-    "subagent-chat-019ecaf6",
-    { send: async () => ({ delivered: true, id: "message-1" }) } as any,
-    () => {},
-  );
-
-  for (const width of [1, 2, 20, 40, 72]) {
-    assertLineWidths("compose overlay", overlay.render(width), width);
-  }
-});
-
-test("session list overlay renders lines at the declared overlay width", () => {
-  const overlay = new SessionListOverlay(theme as any, keybindings as any, session, [session], () => {});
-
-  for (const width of [1, 2, 20, 50, 88]) {
-    assertLineWidths("session list overlay", overlay.render(width), width);
-  }
-});