@signalridge/pi-sessions 0.0.0-stage → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 1.3.0
+### Minor Changes
+
+- 0ec64d1: Introduce an opt-in experimental package for human-controlled workspace/all-workspace session navigation and bounded, editable summary handoffs into linked sessions. Approval only prefills the editor; it never submits a model turn. Native custom entries support explicit recovery after reload.
+
+### Patch Changes
+
+- 74b65a5: Reject malformed assistant error text before restoration, snapshot stale in-memory handoff parents without rewriting history, revoke approval on subsequent delivered switch attempts, and cancel pending native character jumps before inserting reviewed paste.
+- 0925139: Validate native system replay and discovery metadata before switching, migrate historical v2 messages without writes, revoke prefill after source retirement, and preserve review Undo, configured selection controls and foreign overlay focus. Make CLI fixture startup cleanup exception-safe and document the host's RPC observation limits.
+
+## 1.2.0
+
+- Initial experimental package: workspace-scoped session navigation and explicitly reviewed, linked summary handoffs. No automatic model turn or session-file deletion.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 signalridge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# @signalridge/pi-sessions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Experimental, opt-in human-controlled session navigation and editable summary handoffs. Tested with Pi **1.0.4**; host packages are peers, not bundled. MIT, independent implementation. This is not Plan mode's approved-plan implementation action.
+
+Try explicitly with `pi -e ./packages/pi-sessions/src/index.ts`. This package is not enabled by default. Session mutations are human-command-only, never model-callable.
+
+## Commands
+
+- `/sessions`: list sessions whose native workspace matches the active workspace. `/sessions all`: explicitly include other workspaces from Pi's default session store and the current configured session directory.
+- Filter by name, stable session ID or workspace; select to inspect bounded metadata and recent user/assistant text. Confirm before native switching. There is **no delete or rename** operation. The native selector includes deletion, so this package uses a bounded independent picker.
+- `/handoff <goal>`: optionally ask the **currently selected model** to synthesize a goal-oriented summary. An omitted goal opens human input. `recover` as the complete argument is reserved for recovery, not a goal; write a descriptive goal such as `recover interrupted work` instead.
+- `/handoff recover`: explicitly inspect the approved summary saved on the current branch, review/edit it, then separately confirm replacing the current unsent draft. No automatic recovery overwrite, new session or model turn.
+
+TUI and dialog-capable RPC are supported. Print/JSON commands are rejected before authentication, provider requests or session mutations. RPC clients must implement confirm/input/select/editor. Pi 1.0.4 exposes neither RPC draft epochs nor conditional editor writes: clients must reject stale consent and preserve client-local drafts. The latest destination **Yes explicitly authorizes draft replacement**; a newer client-local draft alone cannot revoke it on the server.
+
+## Sharing and handoff
+
+Generation is opt-in **for every invocation**. Only at most 16 KiB UTF-8 of the most recent 12 user/assistant text messages is offered; each message is capped at 2 KiB. Tool results/arguments, images, thinking, system messages, custom entries, compaction summaries and credential objects are not copied. Common credential patterns are redacted, but prose may still contain secrets: inspect/redact the exact excerpt in the multiline editor before a second sharing confirmation. The goal (at most 2 KiB) is also sent to that selected model. No upload/share service is used.
+
+Authentication/generation failures produce a generic message, never raw provider errors, and offer a **manual** summary editor. Declining generation also offers a manual editor, not a fake generated summary. Escape cancels live TUI loading/generation; requests time out after 60 seconds. Ownership retirement aborts our requests and closes only our overlays. RPC pending-editor results are fenced when retired (the host has no editor cancellation API).
+
+Review/edit the summary in a multiline editor. TUI text and complete bracketed-paste payloads are sanitized **before** native insertion, including split paste markers and native-supported CSI-u pasted controls: sanitization does not move the insertion cursor or add dirty Undo snapshots. Native cursor movement, Kitty printable keys, CJK/IME and atomic paste Undo are retained. Large pastes are immediately expanded into the reviewable document, never hidden behind paste markers; Undo restores the pre-paste document and earlier editing history. Approval preserves exact leading/trailing whitespace, not Pi 1.0.4's trimmed submit callback. Choice/picker controls honor configured `tui.select.*` actions and show their bindings. Approved text must be nonempty, terminal-safe and **at most 16 KiB UTF-8**; oversized approved text is rejected, never truncated. Explicit draft-replacement consent and final creation confirmation precede native `newSession({ parentSession, setup, withSession })`.
+
+The destination saves `pi-sessions:handoff` version 1 as a **non-model custom entry** with the approved summary, goal and parent identity. Its optional prefill intent stores the source model identity and, for TUI only, the SHA256 hash of the explicitly consented source unsent draft—**never the raw unsent draft**. RPC cannot read that draft and stores no draft hash. Older records without intent remain explicitly recoverable, but never auto-prefill.
+
+After native setup, the **destination controller's `session_start` with reason `new`** owns prefill under the same interaction lock and lifecycle fences as commands. The source `withSession` callback only reports setup/model warnings, without asynchronous dialogs or editor writes. The destination first vets its current file: the exact custom entry ID/data and native parent link must be durably present, not just in memory after failed setup. It revalidates before writing the editor. RPC requires fresh destination consent; TUI only replaces an empty editor or the consented source draft matching its saved hash. Later TUI drafts are preserved. A missing/different destination model is reported, not submitted to. Nothing sends a message, starts a turn or invokes implementation; you decide whether and when to send the draft.
+
+## Native storage and recovery
+
+The native session manager remains authoritative; no parallel session-history database is kept. Pi 1.0.4 defers custom-only file persistence until the first user/assistant message. To make the reviewed handoff durable **before** that first turn, setup writes the public native header and entries to a unique, exclusive `0600` JSONL file, then reloads it using public `setSessionFile`. It never adds a synthetic model-context message.
+
+An existing saved source file is reused as the linked parent only when every exact active-branch record is present and reopening it selects that same leaf; a native tree-selected ancestor or sibling branch receives its own snapshot instead. If a nonempty source has no saved file (including an allocated-but-unwritten path), or its otherwise valid file is stale, its active native branch and native parent link are cloned into a unique private `0600` snapshot with a new ID in a private temporary directory. The old file is never overwritten; malformed existing storage is rejected, not silently bypassed. A cancelled/vetoed/failed **pre-replacement** creation removes this snapshot. Once native replacement begins it is retained, even if later setup/rebinding/prefill fails, so the source remains resumable by the parent path. In-memory destinations also receive a native recovery file; their later conversation remains subject to the host's no-session policy. Retained temporary parent/recovery files survive reload, but OS temporary-directory cleanup can eventually remove them; retain important source sessions in normal persistent storage.
+
+This record/leaf comparison is a **preflight check**, not a promise that a reused native parent is immutable. Later native source appends can advance its history while replacement hooks are pending or after it is resumed. Observable source changes during preflight revoke editor-prefill authorization; native replacement and its live parent link may still proceed with recovery-only data. A private snapshot records the captured branch when created, rather than reusing a stale or differently selected source file.
+
+Setup/prefill errors never start a model turn. Missing, unreadable or mismatched durable handoff data prevents automatic prefill. If source approval is revoked during a later asynchronous before-switch handler, native replacement may still proceed: setup retains the summary/parent for explicit recovery but strips prefill intent. Only a still-current source owner can carry approval across expected replacement shutdown. The initiated replacement's expected before-switch exemption is single-use: any subsequent delivered attempt revokes approval, including another new-session or same-target resume attempt later vetoed by another extension. Independent human attempts are not blocked by this revocation. If setup failed, resume the native parent and retry. If the summary was saved but prefill failed, `/handoff recover` can inspect it after reload. Startup, reload, resume and fork never consume prefill intent or automatically modify the editor; recovery remains explicit.
+
+## Workspaces and limits
+
+**Actual Pi 1.0.4 runtime switching opens the session header workspace and recreates cwd-bound services there**; it does not change the process's global cwd. Cross-workspace selection requires a separate explicit warning/confirmation. After switching we report both history workspace and the actual fresh context's tool/resource workspace. A host retaining its execution workspace is reported as restoring history only; this package never patches private cwd state. Missing workspaces are rejected before switching rather than invoking a private fallback.
+
+Every candidate is revalidated immediately before native switching: path, native header ID/cwd, JSONL tree and original-byte content digest must still match the preview. Preflight checks native restoration payloads, including usage/cost numbers, system sections/tool deltas and role-appropriate persisted content, then runs public nonmutating context projection, system replay and token estimation before source teardown. Supported v2 entries (including historical `hookMessage`) are migrated on an in-memory clone only. Reads stop at 32 MiB plus one oversize probe byte even if a file grows, and check cancellation between chunks. Detected unreadable/malformed data is rejected without opening or repairing its native manager. Validation accepts supported native v2/v3 payloads with entries up to 4 MiB; unsupported/older/oversized files can still be opened with Pi's own facilities. Arbitrary extension-owned custom data remains opaque; preflight is not a proof that every third-party renderer or external filesystem writer is safe. Invalid discovery metadata is skipped per row rather than hiding the valid collection. Preview text is inert and excludes non-user/assistant content. Preview is capped at 6 KiB, retained rows at 200, and visible rows adapt to the terminal while reserving controls. Undersized terminals require resizing before approval. Terminal controls/bidi instructions are stripped; CJK and narrow widths are supported in regular/fullscreen UI.
+
+**Pi's SDK list/listAll may load full session bodies and return all results. These calls do not promise bounded memory.** Limits above bound this package's retained display data, not SDK memory or disk scan work. Abort signals are passed to SDK list operations.
+
+Ownership captures the manager/session identity, full native active-branch fingerprint (including latest entry data), model identity and TUI draft/editor-factory identity. Observable changes retire the operation permanently; switching back does not revive approval. All await boundaries are checked, including after authentication and destination consent. While destination RPC consent is pending, `/sessions` and `/handoff` report the existing interaction warning. **Fences cover delivered lifecycle events and observable state, not every attempted host action.** Delivered native switch/tree/fork/compact attempts (including vetoes after our observer), shutdown, agent start or model selection retire that consent; a late Yes cannot revive retired ownership. Pi 1.0.4 short-circuits on an earlier extension's veto, so our observer may never receive that attempt. An unchanged branch/model and an invisible RPC draft provide no substitute signal. RPC clients must reject stale consent and preserve local drafts; the latest Yes explicitly authorizes replacement. Stronger guarantees require host-level non-short-circuiting attempt observation and draft epoch/conditional-write support. Source and destination ownership are runtime-local and do not rely on shared event buses. Async TUI generation completion also requires its owned overlay to remain focused; a newer foreign dialog retires continuation instead of losing focus. This package does not install a custom main editor/footer or restore stale editor snapshots.
+
+## Development
+
+`bun run --cwd packages/pi-sessions check` runs lint, typecheck and native-SDK/unit tests. Tests do not require provider credentials and assert no destination model turn.

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@signalridge/pi-sessions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.3.0",
+  "description": "Human-reviewed session navigation and summary handoffs for Pi.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "sessions",
+    "handoff"
+  ],
+  "files": [
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "src"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "piExtension": {
+    "lifecycle": "experimental"
+  },
+  "scripts": {
+    "check": "bun run lint && bun run typecheck && bun run test",
+    "format": "biome check --write .",
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run test --config vitest.config.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.0.4",
+    "@earendil-works/pi-coding-agent": "1.0.4",
+    "@earendil-works/pi-tui": "1.0.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/signalridge/pi-extensions",
+    "directory": "packages/pi-sessions"
+  },
+  "homepage": "https://github.com/signalridge/pi-extensions/tree/main/packages/pi-sessions",
+  "bugs": {
+    "url": "https://github.com/signalridge/pi-extensions/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/controller.ts

@@ -0,0 +1,84 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { handoff, prefillHandoff } from "./handoff.js";
+import { navigate } from "./navigation.js";
+import { Owner, Retired } from "./ownership.js";
+import { requireHuman } from "./ui.js";
+
+export function registerSessions(pi: ExtensionAPI): void {
+  let active: Owner<ExtensionContext> | undefined;
+  let started = false;
+  const retire = () => active?.retire();
+  pi.on("session_before_switch", (event) => {
+    if (!active) return;
+    if (
+      active.expectedSwitch &&
+      active.committing === event.reason &&
+      (event.reason !== "resume" || event.targetSessionFile === active.target)
+    ) {
+      active.expectedSwitch = false;
+      if (!active.current()) return { cancel: true };
+    } else retire();
+  });
+  pi.on("session_shutdown", (event) => active?.shutdown(event));
+  pi.on("session_before_tree", retire);
+  pi.on("session_before_fork", retire);
+  pi.on("session_before_compact", retire);
+  pi.on("session_tree", retire);
+  pi.on("agent_start", retire);
+  pi.on("model_select", () => {
+    if (active?.requireModel) retire();
+  });
+
+  pi.on("session_start", async (event, ctx) => {
+    // Native setup precedes destination binding. Recovery starts never consume
+    // persisted intent; only this fresh runtime's first, genuinely new session can.
+    if (started) return;
+    started = true;
+    if (event.reason !== "new" || !ctx.hasUI || (ctx.mode !== "tui" && ctx.mode !== "rpc")) return;
+    await own(ctx, true, prefillHandoff);
+  });
+
+  async function own<Context extends ExtensionContext>(
+    ctx: Context,
+    requireModel: boolean,
+    work: (owner: Owner<Context>) => Promise<void>,
+  ): Promise<void> {
+    if (active) {
+      ctx.ui.notify("A sessions interaction is already open. Finish or cancel it first.", "warning");
+      return;
+    }
+    const owner = new Owner(ctx, requireModel);
+    active = owner;
+    try {
+      await work(owner);
+    } catch (error: unknown) {
+      if (!(error instanceof Retired) && owner.current()) {
+        ctx.ui.notify(
+          "Session operation unavailable: invalid/unreadable session, workspace or UI. No model turn was submitted. Retry from the current session.",
+          "warning",
+        );
+      }
+    } finally {
+      owner.finish();
+      if (active === owner) active = undefined;
+    }
+  }
+  async function run(ctx: ExtensionCommandContext, argument: string, kind: "sessions" | "handoff"): Promise<void> {
+    // Reject headless commands before idle/auth/session operations.
+    requireHuman(ctx);
+    await own(ctx, kind === "handoff", async (owner) => {
+      await owner.wait(ctx.waitForIdle());
+      owner.check();
+      if (kind === "sessions") await navigate(owner, argument);
+      else await handoff(owner, argument);
+    });
+  }
+  pi.registerCommand("sessions", {
+    description: "Preview/resume current-workspace sessions; 'all' includes other workspaces",
+    handler: (args, ctx) => run(ctx, args, "sessions"),
+  });
+  pi.registerCommand("handoff", {
+    description: "Review a goal-oriented summary into a linked session, or explicitly 'recover' one",
+    handler: (args, ctx) => run(ctx, args, "handoff"),
+  });
+}