@mgiles/perk 1.0.1 → 2.0.0

package/extension/substrate/sessionPointers.ts

@@ -0,0 +1,184 @@
+// The run-cache session-pointer carrier (contracts.md §8.35) — the capture side of the cross-run
+// session-pointer record. The TS twin of perk/state/session_pointers.py; both planes read/write the
+// same `session-pointers.json` (the cross-plane contract is the file).
+//
+// Each run writes only its OWN record, keyed by `run_id`, under the SHARED MAIN CHECKOUT
+// (`mainCheckoutRoot(cwd)`) so a linked-worktree run and a later resolver agree on one location. A
+// run fills only the slots it owns (planning runs → `planning.*`; implement runs →
+// `implementation.*`); the four class/site slots are always present (null when unset) so this
+// read-modify-write merges trivially and never clobbers a sibling write.
+//
+// Seam doctrine — best-effort + loud-but-non-fatal: every write is wrapped so a failure (unwritable
+// root, bad disk) warns to stderr and returns false, NEVER throws. A capture failure must never
+// wedge the save/launch/drive it rides on. Node builtins + cache.ts + git.ts only (loads under
+// `node --test`).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { runScratchDir } from "./cache.ts";
+import { mainCheckoutRoot } from "./git.ts";
+
+export const SESSION_POINTERS_FILE = "session-pointers.json";
+
+/** One captured session pointer (a `main` or `worker` slot of a class). */
+export interface SessionPointer {
+  /** The session-file basename (matches the `perk:workflow-state` stamp). */
+  pi_session_id: string;
+  /** The absolute path known at capture (informational). */
+  session_file: string;
+  /** The inherited parent session (fork/replacement provenance), else null. */
+  parent_pi_session_id: string | null;
+  /** ISO-8601 capture time. */
+  at: string;
+}
+
+/** The two capture sites of one session class (`main` = interior, `worker` = headless). */
+export interface SessionClassPointers {
+  main: SessionPointer | null;
+  worker: SessionPointer | null;
+}
+
+/** A run's full session-pointer record (`session-pointers.json`). */
+export interface SessionPointers {
+  run_id: string;
+  planning: SessionClassPointers;
+  implementation: SessionClassPointers;
+}
+
+export type SessionClass = "planning" | "implementation";
+export type SessionSite = "main" | "worker";
+
+/** The empty four-slot record for a run (all slots null until a capture fills one). */
+function emptyRecord(runId: string): SessionPointers {
+  return {
+    run_id: runId,
+    planning: { main: null, worker: null },
+    implementation: { main: null, worker: null },
+  };
+}
+
+function sessionPointersPath(root: string, runId: string): string {
+  return join(runScratchDir(root, runId), SESSION_POINTERS_FILE);
+}
+
+/**
+ * Read a run's session-pointers record from the shared main checkout; `null` when absent or
+ * unparseable (best-effort — a corrupt record is treated as absent, never thrown). `root` is the
+ * MAIN checkout (resolve via `mainCheckoutRoot(cwd)` at the call site).
+ */
+export function readSessionPointers(root: string, runId: string): SessionPointers | null {
+  const path = sessionPointersPath(root, runId);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as SessionPointers;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record one session pointer into `<class>.<site>` of the run's record, under the shared main
+ * checkout (`mainCheckoutRoot(cwd)`). Read-modify-write: an existing record is loaded (or a fresh
+ * four-slot record minted), only the named slot is set, and the whole record is written back — so
+ * a planning write and an implementation write to the SAME run record never clobber each other.
+ * Best-effort: returns `true` on a successful write, `false` (with a stderr warning) on any
+ * failure. Never throws. Serialized byte-compatibly with the Python writer (key order +
+ * 2-space indent + trailing newline).
+ *
+ * `preserveForeign` makes the slot first-write-wins (defense in depth against pointer
+ * shadowing): when set and the slot already holds a pointer whose `pi_session_id` differs from
+ * the incoming one, the write is SKIPPED with a loud stderr warning naming both session ids
+ * (returns `false`) — so any future shadow vector surfaces instead of silently corrupting
+ * evidence. A same-session re-capture still refreshes the slot. Default `false` keeps today's
+ * overwrite semantics (each default-caller slot has exactly one legitimate writer).
+ */
+export function recordSessionPointer(
+  cwd: string,
+  runId: string,
+  klass: SessionClass,
+  site: SessionSite,
+  pointer: SessionPointer,
+  opts: { preserveForeign?: boolean } = {},
+): boolean {
+  if (!runId) return false;
+  const root = mainCheckoutRoot(cwd);
+  try {
+    const record = readSessionPointers(root, runId) ?? emptyRecord(runId);
+    const existing = record[klass][site];
+    if (
+      opts.preserveForeign === true &&
+      existing !== null &&
+      existing.pi_session_id !== pointer.pi_session_id
+    ) {
+      console.error(
+        `perk: warning: session pointer ${klass}.${site} for run ${runId} already held by ` +
+          `${existing.pi_session_id} — skipping foreign overwrite by ${pointer.pi_session_id}`,
+      );
+      return false;
+    }
+    // The run id is authoritative — a record read from disk keeps its own; a fresh one is minted
+    // with `runId`. (A mismatched on-disk run_id is left as-is; self-keying guarantees a match.)
+    record[klass][site] = pointer;
+    const dir = runScratchDir(root, runId);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(sessionPointersPath(root, runId), serialize(record), "utf8");
+    return true;
+  } catch (error) {
+    console.error(`perk: warning: could not record session pointer (${klass}.${site}): ${error}`);
+    return false;
+  }
+}
+
+/**
+ * Capture one session pointer into `<class>.<site>` from a session file path — the call-site
+ * convenience over `recordSessionPointer`. Derives `pi_session_id` from the basename and stamps
+ * `at`. A `null`/empty `sessionFile` or `runId` is a no-op (`false`) — best-effort, never throws.
+ * `preserveForeign` threads through to `recordSessionPointer`'s first-write-wins guard.
+ */
+export function captureSessionPointer(args: {
+  cwd: string;
+  runId: string;
+  klass: SessionClass;
+  site: SessionSite;
+  sessionFile: string | null | undefined;
+  parentSessionId?: string | null;
+  preserveForeign?: boolean;
+}): boolean {
+  const { cwd, runId, klass, site, sessionFile } = args;
+  if (!sessionFile || !runId) return false;
+  return recordSessionPointer(
+    cwd,
+    runId,
+    klass,
+    site,
+    {
+      pi_session_id: basename(sessionFile),
+      session_file: sessionFile,
+      parent_pi_session_id: args.parentSessionId ?? null,
+      at: new Date().toISOString(),
+    },
+    { preserveForeign: args.preserveForeign },
+  );
+}
+
+/** Serialize a record byte-compatibly with the Python writer (explicit key order, null slots). */
+function serialize(record: SessionPointers): string {
+  const slot = (p: SessionPointer | null): Record<string, unknown> | null =>
+    p === null
+      ? null
+      : {
+          pi_session_id: p.pi_session_id,
+          session_file: p.session_file,
+          parent_pi_session_id: p.parent_pi_session_id,
+          at: p.at,
+        };
+  const payload = {
+    run_id: record.run_id,
+    planning: { main: slot(record.planning.main), worker: slot(record.planning.worker) },
+    implementation: {
+      main: slot(record.implementation.main),
+      worker: slot(record.implementation.worker),
+    },
+  };
+  return `${JSON.stringify(payload, null, 2)}\n`;
+}

package/extension/substrate/structuredOutput.ts

@@ -13,7 +13,6 @@
 import {
   type Api,
   type Context,
-  complete,
   type Model,
   type Static,
   type Tool,
@@ -21,6 +20,9 @@ import {
   type TSchema,
   validateToolCall,
 } from "@earendil-works/pi-ai";
+// `complete` (the old global API) lives on the /compat entrypoint from pi-ai 0.80; the root
+// keeps the types. Pi's extension loader aliases both the root and /compat to the compat entry.
+import { complete } from "@earendil-works/pi-ai/compat";
 
 /** Structurally-minimal slice of `ExtensionContext` needed to reuse the session's model + auth. */
 export interface ModelAuthContext {

package/extension/substrate/terminalLaunch.ts

@@ -0,0 +1,178 @@
+// The terminal review door's R7 terminal auto-launch ladder — open hunk in a terminal the human can
+// see, since hunk's TUI is constitutively a human surface (a `pi.exec` child gets pipes, no TTY).
+//
+// A pure `resolveTerminalLaunch` (platform + env + request → an argv + the rung tag, or `null` for
+// "no launcher matched") and a thin fail-soft `launchInTerminal` runner. Never throws, never
+// notifies — the caller owns messaging, and the loud print + clipboard copy are the universal
+// fallback when no rung matches or a rung fails. The `hunk session get` handshake — not a spawn
+// success — remains the ONLY verification the surface is actually up.
+//
+// The `PERK_TERMINAL_LAUNCH` env seam: unset → the platform default ladder; empty → disabled (the
+// test seam); non-empty → a custom launcher receiving the worktree as `$1` and the command as
+// `$2`.
+
+import type { ExecHost } from "./coldDoor.ts";
+
+/** Which rung of the ladder launched (or would launch) the surface. */
+export type LaunchVia = "custom" | "tmux" | "ghostty" | "iterm2" | "terminal-app";
+
+/** A human-readable name for each rung, for the door's launched-in-a-<surface> message. */
+export const LAUNCH_SURFACE: Record<LaunchVia, string> = {
+  custom: "terminal window",
+  tmux: "tmux pane",
+  ghostty: "Ghostty window",
+  iterm2: "iTerm2 window",
+  "terminal-app": "terminal window",
+};
+
+// The macOS AppleScript rungs are `on run argv` bodies: paths + commands ride argv (never
+// interpolated into the script text), so no AppleScript string-quoting hazard exists.
+
+/** Single-quote `s` for a POSIX shell line (the standard `'\''` embedded-quote escape). */
+function shQuote(s: string): string {
+  return `'${s.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Wrap `command` in the human's interactive **login shell** (`$SHELL -i -l -c '<command>'`) for
+ * the rungs whose execution context is rc-less — Ghostty's surface `command` is argv-exec'd
+ * (quote-aware word split, a relative arg0 joined onto the working directory, never a shell
+ * line), and tmux commands run under the server environment. `-i -l` sources the human's rc
+ * files, so the launched window resolves binaries exactly like the human's own terminal — which
+ * is what the bare command needs: `hunk` AND the `node` its `#!/usr/bin/env node` shebang
+ * re-resolves are often on PATH only via rc activation (mise/nvm; both misses were hit live).
+ * `$SHELL` when absolute, else `/bin/zsh` on darwin (the macOS default) / `/bin/sh` elsewhere.
+ * The shell-line rungs (iTerm2/Terminal.app) type into an interactive login shell already and
+ * take the bare command; so does the custom launcher (it owns its own environment).
+ */
+function interactiveShellWrap(
+  platform: string,
+  env: Record<string, string | undefined>,
+  command: string,
+): string {
+  const shell =
+    env.SHELL !== undefined && env.SHELL.startsWith("/")
+      ? env.SHELL
+      : platform === "darwin"
+        ? "/bin/zsh"
+        : "/bin/sh";
+  return `${shell} -i -l -c ${shQuote(command)}`;
+}
+
+/** Ghostty ≥ 1.3: a native surface configuration (cwd + command as argv items 1/2). */
+const GHOSTTY_SCRIPT = `on run argv
+	tell application "Ghostty"
+		set cfg to (new surface configuration)
+		set (initial working directory of cfg) to (item 1 of argv)
+		set (command of cfg) to (item 2 of argv)
+		set (wait after command of cfg) to true
+		new window with configuration cfg
+		activate
+	end tell
+end run`;
+
+/** iTerm2: a new window whose current session runs the composed shell line (argv item 1). */
+const ITERM_SCRIPT = `on run argv
+	tell application "iTerm"
+		set w to (create window with default profile)
+		tell current session of w to write text (item 1 of argv)
+		activate
+	end tell
+end run`;
+
+/** Terminal.app: the universal macOS fallback — `do script` the composed shell line (argv item 1). */
+const TERMINAL_SCRIPT = `on run argv
+	tell application "Terminal"
+		do script (item 1 of argv)
+		activate
+	end tell
+end run`;
+
+export interface LaunchRequest {
+  /** The review worktree — the terminal's working directory. */
+  cwd: string;
+  /**
+   * The bare surface command to run there, e.g. `hunk diff <sha12>`. The rc-less rungs wrap it
+   * in the human's interactive login shell (see `interactiveShellWrap`).
+   */
+  command: string;
+}
+
+/**
+ * Resolve the terminal-launch argv + rung tag for `platform` + `env` + `req`, first match wins:
+ *
+ * 1. `PERK_TERMINAL_LAUNCH === ""` → `null` (the test seam / opt-out);
+ * 2. `PERK_TERMINAL_LAUNCH` non-empty → a custom `sh -c` launcher (worktree `$1`, command `$2`);
+ * 3. `TMUX` set → a `tmux split-window` pane beside pi (no consent prompts);
+ * 4. `darwin`, keyed off `TERM_PROGRAM` → the matching osascript rung (ghostty / iterm2 /
+ *    terminal-app; anything unrecognized — vscode, WezTerm, absent — falls to terminal-app, the
+ *    universal macOS fallback);
+ * 5. otherwise → `null` (no Linux emulator sniffing — tmux + the custom seam cover it).
+ *
+ * Rungs that set the working directory natively (ghostty's `initial working directory`, tmux's
+ * `-c`) receive the command wrapped in the human's interactive login shell (see
+ * `interactiveShellWrap` — their execution contexts are rc-less); the shell-line rungs
+ * (iterm2/terminal-app) receive `cd '<cwd>' && <command>` as one arg (the cwd single-quoted —
+ * worktree paths can carry spaces; the command is perk-composed, never quoted) typed into an
+ * interactive login shell the terminal itself opens.
+ */
+export function resolveTerminalLaunch(
+  platform: string,
+  env: Record<string, string | undefined>,
+  req: LaunchRequest,
+): { argv: string[]; via: LaunchVia } | null {
+  const custom = env.PERK_TERMINAL_LAUNCH;
+  if (custom !== undefined) {
+    if (custom === "") return null;
+    return { argv: ["sh", "-c", custom, "sh", req.cwd, req.command], via: "custom" };
+  }
+
+  if (env.TMUX !== undefined && env.TMUX !== "") {
+    const wrapped = interactiveShellWrap(platform, env, req.command);
+    return { argv: ["tmux", "split-window", "-h", "-c", req.cwd, wrapped], via: "tmux" };
+  }
+
+  if (platform === "darwin") {
+    // The shell-line rungs run this through the terminal's shell — quote the cwd (paths can
+    // carry spaces/quotes); the command is perk-composed (`hunk diff <sha12>`), never quoted.
+    const shellLine = `cd ${shQuote(req.cwd)} && ${req.command}`;
+    const term = env.TERM_PROGRAM;
+    if (term === "ghostty") {
+      const wrapped = interactiveShellWrap(platform, env, req.command);
+      return { argv: ["osascript", "-e", GHOSTTY_SCRIPT, req.cwd, wrapped], via: "ghostty" };
+    }
+    if (term === "iTerm.app") {
+      return { argv: ["osascript", "-e", ITERM_SCRIPT, shellLine], via: "iterm2" };
+    }
+    // Apple_Terminal, vscode, WezTerm, or absent → Terminal.app (the universal macOS fallback).
+    return { argv: ["osascript", "-e", TERMINAL_SCRIPT, shellLine], via: "terminal-app" };
+  }
+
+  return null;
+}
+
+/**
+ * Launch the surface command in a terminal the human can see, best-effort. Resolves the rung from
+ * `process.platform` + `process.env`; a `null` resolution (disabled seam, unmatched platform)
+ * short-circuits to `{launched: false}`. Otherwise shells the argv with a 15s cap (guards an
+ * unanswered macOS Automation/TCC consent dialog blocking `osascript`). Fail-soft on
+ * throw/nonzero/killed — a denied or unanswered consent is just another failed rung, and the
+ * print+clipboard fallback already covers the human. Never rejects, never notifies.
+ */
+export async function launchInTerminal(
+  pi: ExecHost,
+  ctx: { cwd: string; signal?: AbortSignal },
+  req: LaunchRequest,
+): Promise<{ launched: boolean; via?: LaunchVia }> {
+  const resolved = resolveTerminalLaunch(process.platform, process.env, req);
+  if (resolved === null) return { launched: false };
+  const [cmd, ...rest] = resolved.argv;
+  if (cmd === undefined) return { launched: false };
+  try {
+    const res = await pi.exec(cmd, rest, { cwd: ctx.cwd, signal: ctx.signal, timeout: 15_000 });
+    if (res.killed || res.code !== 0) return { launched: false };
+    return { launched: true, via: resolved.via };
+  } catch {
+    return { launched: false };
+  }
+}