pi-sessions 0.9.0 → 0.11.0

package/README.md

@@ -34,7 +34,7 @@
 
 ## Install
 
-Requires Pi `0.80.10` or newer and Node `>=24 <26`.
+Requires Pi `0.82.1` or newer and Node `>=24 <26`.
 
 **From npm** (recommended):
 
@@ -65,15 +65,15 @@ Open the frontend implementation task in a session to the right.
 
 ## Features
 
-| Extension          | Surface                                           | What it does                                            |
-| ------------------ | ------------------------------------------------- | ------------------------------------------------------- |
-| Session Search     | `session_search` pi tool                          | Search through old sessions                             |
-| Session Ask        | `session_ask` pi tool                             | Ask questions about old sessions                        |
-| Session Handoff    | `session_handoff` pi tool, `/handoff` board       | Start and manage focused child sessions                 |
-| Session Messaging  | `session_send_message`, `session_cancel` pi tools | Coordinate between live Pi sessions and own subagents   |
-| Session Picker     | `Alt+O`                                           | Reference old sessions in your prompt                   |
-| Session Index      | `/session-index` slash command                    | Shows index status and rebuilds the local session index |
-| Session Auto Title | in background, `/title` slash command             | Give sessions titles                                    |
+| Extension          | Surface                                                                | What it does                                            |
+| ------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------- |
+| Session Search     | `session_search` pi tool                                               | Search through old sessions                             |
+| Session Ask        | `session_ask` pi tool                                                  | Ask questions about old sessions                        |
+| Session Handoff    | `session_handoff` pi tool, `/handoff` board                            | Start and manage focused child sessions                 |
+| Session Messaging  | `session_reachable`, `session_send_message`, `session_cancel` pi tools | Coordinate between live Pi sessions and own subagents   |
+| Session Picker     | `Alt+O`                                                                | Reference old sessions in your prompt                   |
+| Session Index      | `/session-index` slash command                                         | Shows index status and rebuilds the local session index |
+| Session Auto Title | in background, `/title` slash command                                  | Give sessions titles                                    |
 
 Every feature is on by default. Turn one off with `enable: false` under its own settings namespace, which unregisters its tools and hooks.
 
@@ -93,16 +93,16 @@ Every feature is on by default. Turn one off with `enable: false` under its own
 
 ## Session Search
 
-`session_search` searches the local session index by text, repo, cwd, time range, file evidence, and whether a session is currently running.
+`session_search` searches the local session index by text, repo, cwd, time range, and file evidence.
 
-Queries support regular text for normal usage, quoted phrases, `AND` / `OR` / `NOT`, parentheses, and `-term` negation when matching needs to be stricter. Unquoted terms use prefix matching, quoted terms are exact. A search with no query returns matching sessions chronologically, newest first. Use `live: true` to restrict results to currently running sessions.
+Queries support regular text for normal usage, quoted phrases, `AND` / `OR` / `NOT`, parentheses, and `-term` negation when matching needs to be stricter. Unquoted terms use prefix matching, quoted terms are exact. A search with no query returns matching sessions chronologically, newest first.
 
 File filters distinguish read-or-write evidence from write-only evidence:
 
 - `files.touched`: sessions that read or changed a path
 - `files.changed`: sessions that changed a path
 
-Use `kind: "user"` or `kind: "subagent"` to filter by session type across the whole index. Use `relationScope: "branch"` to search subagents launched from the current conversation branch, or `relationScope: "tree"` to include subagents launched from abandoned branches as well.
+Use `kind: "user"` or `kind: "subagent"` to filter by session type across the whole index. Searching for sessions that can be addressed right now is a different question, answered by `session_reachable`.
 
 ## Session Handoff
 
@@ -116,7 +116,7 @@ Run `/handoff` to open the **Handoffs** board. The Subagents and User sessions t
 
 Agents can coordinate with live Pi sessions and their own subagents:
 
-- `session_search` with `live: true` lists live sessions
+- `session_reachable` lists the sessions this session can send messages to
 - `session_send_message` sends a message to a live session or own subagent
 - `session_cancel` aborts another live session's current turn
 
@@ -140,6 +140,8 @@ If you want to override the shortcut, put this in your `~/.pi/agent/settings.jso
   "sessions": {
     "handoff": {
       "pickerShortcut": "alt+p",
+      "model": "openai-codex/gpt-5.6-terra",
+      "thinkingLevel": "low",
       "deferred": {
         "copyToClipboard": true
       }
@@ -148,6 +150,8 @@ If you want to override the shortcut, put this in your `~/.pi/agent/settings.jso
 }
 ```
 
+`model` and `thinkingLevel` configure the agent that builds handoff prompts. They default to the new session's values when absent.
+
 `deferred.copyToClipboard` (default `true`) controls whether deferred handoffs copy the resume command to the clipboard. When off, the resume command is only shown in the tool call.
 
 Subagents require the handoff and messaging features. Limit recursive delegation depth with `sessions.subagents.maxDepth` (default `2`):
@@ -210,9 +214,10 @@ Note that generating titles for all sessions can take some time, and will hit yo
 - if you manually rename a session with `/name`, automatic retitling pauses for that session
 - Regenerate the title for the current session to resume automatic retitling
 - if unconfigured, it will attempt to use these models in order, first one that is available:
-  - `google/gemini-flash-lite-latest`
+  - `openai-codex/gpt-5.6-luna`
+  - `openai/gpt-5.6-luna`
   - `anthropic/claude-haiku-4-5`
-  - `openai/gpt-5.4-mini`
+  - `google/gemini-flash-lite-latest`
   - your currently configured model
 
 To change auto-titling settings, edit `~/.pi/agent/settings.json`:
@@ -223,20 +228,24 @@ To change auto-titling settings, edit `~/.pi/agent/settings.json`:
     "autoTitle": {
       "refreshTurns": 4,
       "timeoutSecs": 15,
+      "tokenBudget": 64,
       "model": "anthropic/claude-haiku-4-5",
       "thinkingLevel": "off",
-      "prompt": "Custom prompt that overrides the default."
+      "prompt": "Custom prompt that overrides the default.",
+      "persistRuns": false
     }
   }
 }
 ```
 
+`persistRuns` records each title request as its own session file under `~/.pi/agent/pi-sessions/session-auto-title/`, holding the exact prompt and response. Open one with `pi --session <file>` to see what the titling model was sent.
+
 ## Development
 
 ```bash
-npm install
-npm run check
-npm test
+mise trust && mise bootstrap
+mise run check
+mise run test
 ```
 
 For an end-to-end manual flow, see [SMOKE.md](./SMOKE.md).

package/dist/session-messaging/broker/client-frame.js

@@ -0,0 +1,62 @@
+// The broker runs as a detached raw-Node process with nothing installed next to
+// it, so client frames are validated by hand rather than against the TypeBox
+// schemas in shared/session-broker/protocol.ts. The broker only routes
+// envelopes, so it validates the routing fields and treats `envelope` as an
+// opaque object; the receiving client validates the envelope body in full.
+const CONTEXT = "Invalid session messaging client frame";
+export function parseClientFrame(value) {
+    const frame = requireObject(value, "/");
+    switch (frame.type) {
+        case "register":
+            return { type: "register", sessionId: requireString(frame.sessionId, "/sessionId") };
+        case "unregister":
+            return { type: "unregister" };
+        case "list":
+            return { type: "list", requestId: requireString(frame.requestId, "/requestId") };
+        case "send":
+            return {
+                type: "send",
+                requestId: requireString(frame.requestId, "/requestId"),
+                target: requireString(frame.target, "/target"),
+                envelope: requireObject(frame.envelope, "/envelope"),
+            };
+        case "incoming_ack": {
+            const error = optionalString(frame.error, "/error");
+            return {
+                type: "incoming_ack",
+                requestId: requireString(frame.requestId, "/requestId"),
+                delivered: requireBoolean(frame.delivered, "/delivered"),
+                ...(error === undefined ? {} : { error }),
+            };
+        }
+        default:
+            throw invalid("/type", "expected a known client frame type");
+    }
+}
+function requireObject(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw invalid(path, "expected an object");
+    }
+    return value;
+}
+function requireString(value, path) {
+    if (typeof value !== "string") {
+        throw invalid(path, "expected a string");
+    }
+    return value;
+}
+function requireBoolean(value, path) {
+    if (typeof value !== "boolean") {
+        throw invalid(path, "expected a boolean");
+    }
+    return value;
+}
+function optionalString(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return requireString(value, path);
+}
+function invalid(path, message) {
+    return new Error(`${CONTEXT}: ${path} ${message}`);
+}

package/dist/session-messaging/broker/process.js

@@ -0,0 +1,234 @@
+import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { join } from "node:path";
+import { readFrames, writeFrame } from "../../shared/session-broker/framing.js";
+import { getSessionMessagingDir, getSessionMessagingSocketPath, } from "../../shared/session-broker/socket-path.js";
+import { parseClientFrame, } from "./client-frame.js";
+const SEND_TIMEOUT_MS = 10_000;
+const EXIT_IDLE_MS = 5_000;
+const KEEPALIVE_DELAY_MS = 5_000;
+const messagingDir = getSessionMessagingDir();
+const socketPath = getSessionMessagingSocketPath();
+const pidPath = join(messagingDir, "broker.pid");
+const sessions = new Map();
+const pendingSends = new Map();
+let idleTimer;
+let server;
+function closeWithError(socket, message) {
+    try {
+        writeFrame(socket, { type: "error", message });
+    }
+    catch { }
+    socket.destroy();
+}
+function scheduleIdleExit() {
+    if (idleTimer)
+        clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+        if (sessions.size === 0)
+            shutdown();
+    }, EXIT_IDLE_MS);
+}
+function clearIdleExit() {
+    if (!idleTimer)
+        return;
+    clearTimeout(idleTimer);
+    idleTimer = undefined;
+}
+function unregister(sessionId) {
+    if (!sessionId)
+        return;
+    sessions.delete(sessionId);
+    failPendingSendsTo(sessionId);
+    if (sessions.size === 0)
+        scheduleIdleExit();
+}
+function resolveTarget(target) {
+    const socket = sessions.get(target);
+    if (socket)
+        return { sessionId: target, socket };
+    return { error: `No live session found for id: ${target}` };
+}
+function handleFrame(socket, message, getSessionId, setSessionId) {
+    const currentSessionId = getSessionId();
+    if (!currentSessionId && message.type !== "register") {
+        closeWithError(socket, `Received ${message.type} before register.`);
+        return;
+    }
+    switch (message.type) {
+        case "register": {
+            const existing = sessions.get(message.sessionId);
+            if (existing && existing !== socket && !existing.destroyed) {
+                writeFrame(socket, {
+                    type: "register_failed",
+                    reason: "Session messaging unavailable: this session is already registered by another live Pi process.",
+                });
+                socket.end();
+                return;
+            }
+            clearIdleExit();
+            setSessionId(message.sessionId);
+            sessions.set(message.sessionId, socket);
+            socket.setKeepAlive(true, KEEPALIVE_DELAY_MS);
+            writeFrame(socket, { type: "registered", sessionId: message.sessionId });
+            break;
+        }
+        case "unregister":
+            unregister(currentSessionId);
+            setSessionId(undefined);
+            socket.end();
+            break;
+        case "list":
+            writeFrame(socket, {
+                type: "sessions",
+                requestId: message.requestId,
+                sessionIds: [...sessions.keys()],
+            });
+            break;
+        case "send":
+            handleSend(socket, currentSessionId, message);
+            break;
+        case "incoming_ack":
+            handleIncomingAck(socket, message);
+            break;
+    }
+}
+function handleSend(socket, currentSessionId, message) {
+    const source = currentSessionId ? sessions.get(currentSessionId) : undefined;
+    if (!currentSessionId || !source) {
+        writeFrame(socket, {
+            type: "send_result",
+            requestId: message.requestId,
+            delivered: false,
+            error: "Sender session is not registered.",
+        });
+        return;
+    }
+    const resolved = resolveTarget(message.target);
+    if ("error" in resolved) {
+        writeFrame(socket, {
+            type: "send_result",
+            requestId: message.requestId,
+            delivered: false,
+            reason: "no_session",
+            error: resolved.error,
+        });
+        return;
+    }
+    if (resolved.sessionId === currentSessionId) {
+        writeFrame(socket, {
+            type: "send_result",
+            requestId: message.requestId,
+            delivered: false,
+            error: "Cannot send a session envelope to the current session.",
+        });
+        return;
+    }
+    const timeout = setTimeout(() => {
+        pendingSends.delete(message.requestId);
+        writeFrame(socket, {
+            type: "send_result",
+            requestId: message.requestId,
+            delivered: false,
+            error: "Timed out waiting for target session to accept the envelope.",
+        });
+    }, SEND_TIMEOUT_MS);
+    pendingSends.set(message.requestId, {
+        source: socket,
+        target: resolved.socket,
+        timeout,
+        targetSessionId: resolved.sessionId,
+    });
+    writeFrame(resolved.socket, {
+        type: "incoming",
+        requestId: message.requestId,
+        envelope: stampEnvelope(message.envelope, currentSessionId, resolved.sessionId),
+    });
+}
+function failPendingSendsTo(targetSessionId) {
+    for (const [requestId, pending] of pendingSends) {
+        if (pending.targetSessionId !== targetSessionId) {
+            continue;
+        }
+        clearTimeout(pending.timeout);
+        pendingSends.delete(requestId);
+        writeFrame(pending.source, {
+            type: "send_result",
+            requestId,
+            delivered: false,
+            reason: "disconnected",
+            error: "Target disconnected before accepting the envelope.",
+        });
+    }
+}
+function handleIncomingAck(socket, message) {
+    const pending = pendingSends.get(message.requestId);
+    if (!pending || pending.target !== socket)
+        return;
+    clearTimeout(pending.timeout);
+    pendingSends.delete(message.requestId);
+    writeFrame(pending.source, {
+        type: "send_result",
+        requestId: message.requestId,
+        delivered: message.delivered,
+        ...(message.error === undefined ? {} : { error: message.error }),
+    });
+}
+function stampEnvelope(envelope, source, target) {
+    return { ...envelope, source, target };
+}
+function handleConnection(socket) {
+    let sessionId;
+    socket.setKeepAlive(true, KEEPALIVE_DELAY_MS);
+    void readConnection(socket, () => sessionId, (nextSessionId) => {
+        sessionId = nextSessionId;
+    });
+    socket.on("close", () => {
+        unregister(sessionId);
+    });
+    socket.on("error", () => { });
+}
+async function readConnection(socket, getSessionId, setSessionId) {
+    try {
+        for await (const frame of readFrames(socket, parseClientFrame)) {
+            handleFrame(socket, frame, getSessionId, setSessionId);
+        }
+    }
+    catch (error) {
+        closeWithError(socket, error instanceof Error ? error.message : String(error));
+    }
+}
+function shutdown() {
+    for (const socket of sessions.values())
+        socket.end();
+    sessions.clear();
+    for (const pending of pendingSends.values())
+        clearTimeout(pending.timeout);
+    pendingSends.clear();
+    if (server)
+        server.close();
+    if (process.platform !== "win32") {
+        try {
+            unlinkSync(socketPath);
+        }
+        catch { }
+    }
+    try {
+        unlinkSync(pidPath);
+    }
+    catch { }
+    process.exit(0);
+}
+mkdirSync(messagingDir, { recursive: true, mode: 0o700 });
+if (process.platform !== "win32") {
+    try {
+        unlinkSync(socketPath);
+    }
+    catch { }
+}
+server = createServer(handleConnection);
+server.listen(socketPath, () => {
+    writeFileSync(pidPath, String(process.pid));
+});
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);

package/dist/shared/session-broker/framing.js

@@ -0,0 +1,59 @@
+import { createInterface } from "node:readline";
+const MAX_FRAME_BYTES = 256 * 1024;
+export function writeFrame(socket, frame) {
+    socket.write(`${JSON.stringify(frame)}\n`);
+}
+// The parser is injected so the detached broker can run with no dependencies
+// installed alongside it, while Pi-side callers keep using TypeBox schemas.
+export async function* readFrames(socket, parseFrame) {
+    const reader = createInterface({ input: socket, crlfDelay: Number.POSITIVE_INFINITY });
+    const lines = [];
+    const waiters = [];
+    let error;
+    let closed = false;
+    const wake = () => {
+        const waiter = waiters.shift();
+        waiter?.();
+    };
+    reader.on("line", (line) => {
+        lines.push(line);
+        wake();
+    });
+    reader.on("error", (nextError) => {
+        error = nextError instanceof Error ? nextError : new Error(String(nextError));
+        closed = true;
+        wake();
+    });
+    reader.on("close", () => {
+        closed = true;
+        wake();
+    });
+    try {
+        while (true) {
+            while (lines.length === 0 && !closed) {
+                await new Promise((resolve) => waiters.push(resolve));
+            }
+            const line = lines.shift();
+            if (line === undefined) {
+                if (error) {
+                    throw error;
+                }
+                return;
+            }
+            if (Buffer.byteLength(line, "utf8") > MAX_FRAME_BYTES) {
+                throw new Error("Session messaging frame exceeds maximum size.");
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch (parseError) {
+                throw parseError instanceof Error ? parseError : new Error(String(parseError));
+            }
+            yield parseFrame(parsed);
+        }
+    }
+    finally {
+        reader.close();
+    }
+}

package/dist/shared/session-broker/socket-path.js

@@ -0,0 +1,19 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+function sanitizePipeSegment(value) {
+    return (value
+        .replace(/[^a-zA-Z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase() || "default");
+}
+export function getSessionMessagingDir(homeDir = homedir()) {
+    return (process.env.PI_SESSIONS_MESSAGING_DIR ??
+        join(homeDir, ".pi", "agent", "pi-sessions", "messaging"));
+}
+export function getSessionMessagingSocketPath(platform = process.platform, homeDir = homedir()) {
+    const messagingDir = getSessionMessagingDir(homeDir);
+    if (platform === "win32") {
+        return `\\\\.\\pipe\\pi-sessions-messaging-${sanitizePipeSegment(messagingDir)}`;
+    }
+    return join(messagingDir, "broker.sock");
+}

package/extensions/pi-sessions.ts

@@ -9,6 +9,7 @@ import { installHandoff } from "./session-handoff/install.ts";
 import { installHooks } from "./session-hooks/install.ts";
 import { installIndex } from "./session-index/install.ts";
 import { installMessaging } from "./session-messaging/install.ts";
+import { createSessionReachableTool } from "./session-messaging/pi/reachable-tool.ts";
 import {
   createSessionCancelTool,
   createSessionSendMessageTool,
@@ -67,6 +68,18 @@ export default function piSessions(pi: ExtensionAPI): void {
       }),
     );
     pi.registerTool(createSessionCancelTool(subagents ?? messaging));
+    pi.registerTool(
+      createSessionReachableTool({
+        indexPath: index.path,
+        listSessions: () => messaging.listSessions(),
+        getRelationTo: messaging.getCachedRelationTo,
+        ...(subagents
+          ? {
+              listSubagents: async (scope) => (await subagents.roster.resolve(scope)).entries,
+            }
+          : {}),
+      }),
+    );
   }
   if (settings.features.handoff) {
     const board = {
@@ -88,7 +101,7 @@ export default function piSessions(pi: ExtensionAPI): void {
     );
   }
   if (settings.features.search) {
-    installSearch(pi, { settings, index, messaging, roster: subagents?.roster });
+    installSearch(pi, { settings, index });
   }
   if (settings.features.ask) {
     installAsk(pi, { settings, index, getModelRuntime });