pi-sessions 0.8.0 → 0.9.0

package/extensions/session-handoff/spawn.ts

@@ -1,208 +1,103 @@
-import { randomUUID } from "node:crypto";
 import { writeFileSync } from "node:fs";
-import { join } from "node:path";
-import {
-  CURRENT_SESSION_VERSION,
-  type ExtensionAPI,
-  type ExtensionContext,
-  type SessionHeader,
-  type SessionInfoEntry,
-} from "@earendil-works/pi-coding-agent";
-import { HANDOFF_BOOTSTRAP_ENV } from "./metadata.ts";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { shellQuote } from "./launch/shell.ts";
+import { HANDOFF_BOOTSTRAP_PENDING_CUSTOM_TYPE, type HandoffBootstrap } from "./metadata.ts";
 
-const GHOSTTY_MACOS_ONLY_MESSAGE = "Split handoff currently supports Ghostty on macOS only.";
-const GHOSTTY_REQUIRED_MESSAGE = "Split handoff requires running inside Ghostty.";
-const GHOSTTY_SPLIT_TIMEOUT_MS = 15_000;
-const OSASCRIPT_PATH = "/usr/bin/osascript";
-
-export type HandoffSplitDirection = "left" | "right" | "up" | "down";
-
-export interface CreatedHandoffSession {
+export interface PreparedHandoff {
   sessionId: string;
   sessionFile: string;
+  resumeCommand: string;
 }
 
-export function isGhosttyHandoffAvailable(): boolean {
-  return process.platform === "darwin" && process.env.TERM_PROGRAM === "ghostty";
-}
-
-export async function validateSplitHandoffPrerequisites(
-  _pi: ExtensionAPI,
-  ctx: ExtensionContext,
-): Promise<string | undefined> {
-  if (!ctx.sessionManager.getSessionFile()) {
-    return "Split handoff requires a persisted current session.";
-  }
-
-  if (process.platform !== "darwin") {
-    return GHOSTTY_MACOS_ONLY_MESSAGE;
-  }
-
-  if (process.env.TERM_PROGRAM !== "ghostty") {
-    return GHOSTTY_REQUIRED_MESSAGE;
-  }
-
-  return undefined;
-}
-
-export function createHandoffSession(options: {
-  cwd: string;
-  sessionDir: string;
+/**
+ * Owns the backend-independent half of a handoff: create the prepared child
+ * session (bootstrap included) and build the self-locating resume command
+ * every failure path must surface.
+ */
+export function prepareHandoffLaunch(options: {
+  targetCwd: string;
+  parentCwd: string;
+  parentSessionDir: string;
   parentSessionFile: string;
   title: string;
-}): CreatedHandoffSession {
-  const sessionId = randomUUID();
-  const timestamp = new Date().toISOString();
-  const fileTimestamp = timestamp.replace(/[:.]/g, "-");
-  const sessionFile = join(options.sessionDir, `${fileTimestamp}_${sessionId}.jsonl`);
-
-  const header: SessionHeader = {
-    type: "session",
-    version: CURRENT_SESSION_VERSION,
-    id: sessionId,
-    timestamp,
-    cwd: options.cwd,
-    parentSession: options.parentSessionFile,
-  };
-
-  const titleEntry: SessionInfoEntry = {
-    type: "session_info",
-    id: randomUUID(),
-    parentId: null,
-    timestamp,
-    name: options.title,
-  };
-
-  writeFileSync(
-    sessionFile,
-    `${[JSON.stringify(header), JSON.stringify(titleEntry)].join("\n")}\n`,
+  model: string | undefined;
+  buildBootstrap: (sessionId: string) => HandoffBootstrap;
+  prepareChild?: ((manager: SessionManager, sessionId: string) => void) | undefined;
+}): PreparedHandoff {
+  // Same-cwd children stay in the parent's session directory, preserving a
+  // deliberate nondefault dir. Cross-cwd children live with their target
+  // project, so Pi computes that project's default storage location.
+  const sameCwd = options.targetCwd === options.parentCwd;
+  const manager = SessionManager.create(
+    options.targetCwd,
+    sameCwd ? options.parentSessionDir : undefined,
+    { parentSession: options.parentSessionFile },
   );
+  manager.appendSessionInfo(options.title);
+  manager.appendCustomEntry(
+    HANDOFF_BOOTSTRAP_PENDING_CUSTOM_TYPE,
+    options.buildBootstrap(manager.getSessionId()),
+  );
+  options.prepareChild?.(manager, manager.getSessionId());
+  flushPreparedSession(manager);
 
-  return { sessionId, sessionFile };
-}
-
-export async function getFocusedGhosttyTerminalId(
-  pi: ExtensionAPI,
-  cwd: string,
-): Promise<string | undefined> {
-  const appleScript = [
-    'tell application "Ghostty"',
-    "    get id of focused terminal of selected tab of front window",
-    "end tell",
-  ].join("\n");
-  const result = await pi.exec(OSASCRIPT_PATH, ["-e", appleScript], {
-    cwd,
-    timeout: GHOSTTY_SPLIT_TIMEOUT_MS,
-  });
-
-  if (result.code !== 0) {
-    return undefined;
+  const sessionFile = manager.getSessionFile();
+  if (!sessionFile) {
+    throw new Error("Prepared handoff session has no session file.");
   }
 
-  return result.stdout.trim() || undefined;
-}
-
-export async function launchSplitHandoffSession(
-  pi: ExtensionAPI,
-  options: {
-    cwd: string;
-    sessionDir: string;
-    direction: HandoffSplitDirection;
-    sessionId: string;
-    bootstrapValue: string;
-    title: string;
-    terminalId?: string | undefined;
-    restoreFocus?: boolean | undefined;
-    model?: string | undefined;
-  },
-): Promise<{ success: true } | { success: false; error: string }> {
-  const piCommand = buildPiLaunchCommand({
-    sessionDir: options.sessionDir,
-    sessionId: options.sessionId,
-    bootstrapValue: options.bootstrapValue,
-    title: options.title,
+  const resumeCommand = buildPiResumeCommand({
+    targetCwd: options.targetCwd,
+    parentCwd: options.parentCwd,
+    sessionId: manager.getSessionId(),
+    sessionDir: manager.usesDefaultSessionDir() ? undefined : manager.getSessionDir(),
     model: options.model,
   });
-  const escapedCwd = escapeAppleScriptString(options.cwd);
-  const escapedCommand = escapeAppleScriptString(piCommand);
-  const targetTerminalLine = options.terminalId
-    ? `    set targetTerminal to item 1 of (every terminal whose id is "${escapeAppleScriptString(options.terminalId)}")`
-    : "    set targetTerminal to focused terminal of selected tab of front window";
-  const focusLine = options.restoreFocus === false ? [] : ["    focus targetTerminal"];
-  const appleScript = [
-    'tell application "Ghostty"',
-    targetTerminalLine,
-    "    set cfg to new surface configuration",
-    `    set initial working directory of cfg to "${escapedCwd}"`,
-    `    set command of cfg to "${escapedCommand}"`,
-    `    set newTerminal to split targetTerminal direction ${options.direction} with configuration cfg`,
-    ...focusLine,
-    "end tell",
-  ].join("\n");
-  const result = await pi.exec(OSASCRIPT_PATH, ["-e", appleScript], {
-    cwd: options.cwd,
-    timeout: GHOSTTY_SPLIT_TIMEOUT_MS,
-  });
-
-  if (result.code === 0) {
-    return { success: true };
-  }
 
-  const details = `${result.stderr || result.stdout}`.trim() || `exit code ${result.code}`;
-  return {
-    success: false,
-    error:
-      `Failed to launch Ghostty split: ${details}. ` +
-      "Split handoff currently supports Ghostty on macOS only.",
-  };
+  return { sessionId: manager.getSessionId(), sessionFile, resumeCommand };
 }
 
-export function buildPiResumeCommand(
-  sessionDir: string,
-  sessionId: string,
-  bootstrapValue: string,
-  title: string,
-  model?: string | undefined,
-): string {
-  const args = [
-    `${HANDOFF_BOOTSTRAP_ENV}=${shellQuote(bootstrapValue)}`,
-    "pi",
-    "--session-dir",
-    shellQuote(sessionDir),
-    "--session-id",
-    shellQuote(sessionId),
-    "--name",
-    shellQuote(title),
-  ];
+export function formatHandoffLaunchFailure(error: string, prepared: PreparedHandoff): string {
+  return `${error} Created handoff session ${prepared.sessionId}; start it manually with: ${prepared.resumeCommand}`;
+}
 
-  if (model) {
-    args.push("--model", shellQuote(model));
+// Pi intentionally defers writing a new session until an assistant response
+// exists, so a prepared child needs one explicit initial flush of the
+// manager-assembled state to be discoverable by `pi --session-id`.
+function flushPreparedSession(manager: SessionManager): void {
+  const sessionFile = manager.getSessionFile();
+  const header = manager.getHeader();
+  if (!sessionFile || !header) {
+    throw new Error("Prepared handoff session is missing its file or header.");
   }
 
-  return args.join(" ");
+  const lines = [header, ...manager.getEntries()].map((entry) => JSON.stringify(entry));
+  writeFileSync(sessionFile, `${lines.join("\n")}\n`, { flag: "wx" });
 }
 
-export function buildPiLaunchCommand(options: {
-  sessionDir: string;
+/**
+ * The canonical recovery artifact consumed by launch backends, failure
+ * messages, clipboard delivery, and renderers. Self-locating: when the target
+ * cwd differs from the parent's, the command starts with `cd <target> &&`.
+ */
+export function buildPiResumeCommand(options: {
+  targetCwd: string;
+  parentCwd: string;
   sessionId: string;
-  bootstrapValue: string;
-  title: string;
+  sessionDir?: string | undefined;
   model?: string | undefined;
 }): string {
-  const payload = `${buildPiResumeCommand(
-    options.sessionDir,
-    options.sessionId,
-    options.bootstrapValue,
-    options.title,
-    options.model,
-  )}; exec /bin/zsh -il`;
-  return `/bin/zsh -ilc ${shellQuote(payload)}`;
-}
-
-function escapeAppleScriptString(value: string): string {
-  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
-}
+  const args = ["pi"];
+  if (options.sessionDir) {
+    args.push("--session-dir", shellQuote(options.sessionDir));
+  }
+  args.push("--session-id", shellQuote(options.sessionId));
+  if (options.model) {
+    args.push("--model", shellQuote(options.model));
+  }
 
-function shellQuote(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
+  const command = args.join(" ");
+  return options.targetCwd === options.parentCwd
+    ? command
+    : `cd ${shellQuote(options.targetCwd)} && ${command}`;
 }

package/extensions/session-handoff/strong-modal.ts

@@ -0,0 +1,13 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+export function renderStrongModal(lines: string[], width: number, theme: Theme): string[] {
+  const innerWidth = Math.max(20, width - 4);
+  const fillLine = (text: string) => {
+    const truncated = truncateToWidth(text, innerWidth, "…", true);
+    const padding = Math.max(0, innerWidth - visibleWidth(truncated));
+    return theme.bg("customMessageBg", `  ${truncated}${" ".repeat(padding)}  `);
+  };
+
+  return ["", ...lines, ""].map(fillLine);
+}

package/extensions/session-handoff/tool-contract.ts

@@ -0,0 +1,12 @@
+import { type Static, Type } from "typebox";
+import { HANDOFF_DIRECTION_LAUNCH_SCHEMA } from "./launch-target.ts";
+import { HANDOFF_LAUNCH_RECEIPT_SCHEMA } from "./receipt.ts";
+
+export const HANDOFF_TOOL_DETAILS_SCHEMA = Type.Intersect([
+  HANDOFF_LAUNCH_RECEIPT_SCHEMA,
+  Type.Object({
+    degradedFrom: Type.Optional(HANDOFF_DIRECTION_LAUNCH_SCHEMA),
+  }),
+]);
+
+export type HandoffToolDetails = Static<typeof HANDOFF_TOOL_DETAILS_SCHEMA>;

package/extensions/session-handoff/tool-presenter.ts

@@ -0,0 +1,35 @@
+import type { ExpandableContentPresentation } from "../shared/rendering/expandable-content-layout.ts";
+import type { RenderTheme } from "../shared/rendering/theme.ts";
+import type { HandoffToolViewModel } from "./tool-view-model.ts";
+
+const PENDING = "…";
+
+export function buildHandoffToolPresentation(
+  model: HandoffToolViewModel,
+  theme: RenderTheme,
+): ExpandableContentPresentation {
+  const expandedMetadata: string[] = [];
+  if (model.result) {
+    expandedMetadata.push(`${theme.bold("session")} ${model.result.sessionId}`);
+    if (model.result.cwd) {
+      expandedMetadata.push(`${theme.bold("cwd")} ${model.result.cwd}`);
+    }
+  }
+
+  return {
+    header: [
+      theme.fg("accent", "session_handoff"),
+      theme.fg("dim", `[${model.launch ?? PENDING}]`),
+      theme.bold(model.title ?? PENDING),
+    ].join(" "),
+    metadata: [
+      `${theme.fg("muted", "provider")} ${model.provider ?? PENDING}  ${theme.fg("dim", "·")}  ${theme.fg("muted", "model")} ${model.model ?? PENDING}  ${theme.fg("dim", "·")}  ${theme.fg("muted", "thinking")} ${model.thinkingLevel ?? PENDING}`,
+    ],
+    ...(expandedMetadata.length > 0 ? { expandedMetadata } : {}),
+    body: {
+      text: `${theme.bold("goal")} ${model.goal ?? PENDING}`,
+      collapsedRows: 1,
+      spacingBefore: 0,
+    },
+  };
+}

package/extensions/session-handoff/tool-renderer.ts

@@ -0,0 +1,66 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { ExpandableContentLayout } from "../shared/rendering/expandable-content-layout.ts";
+import type { ClipboardStatus } from "./launch/backend.ts";
+import { createLaunchCommandComponent, formatDeferredCommandLabel } from "./receipt.ts";
+import { buildHandoffToolPresentation } from "./tool-presenter.ts";
+import type { HandoffToolViewModel } from "./tool-view-model.ts";
+
+export class HandoffToolComponent implements Component {
+  private model: HandoffToolViewModel | undefined;
+  private clipboardStatus: ClipboardStatus | undefined;
+  private readonly layout: ExpandableContentLayout;
+
+  constructor(private readonly theme: Theme) {
+    this.layout = new ExpandableContentLayout(theme);
+  }
+
+  update(
+    model: HandoffToolViewModel,
+    expanded: boolean,
+    clipboardStatus?: ClipboardStatus | undefined,
+  ): void {
+    this.model = model;
+    this.clipboardStatus = clipboardStatus;
+    this.layout.update(buildHandoffToolPresentation(model, this.theme), expanded);
+  }
+
+  invalidate(): void {
+    this.layout.invalidate();
+  }
+
+  render(width: number): string[] {
+    if (!this.model) {
+      return [];
+    }
+
+    const container = new Container();
+    container.addChild(this.layout);
+    if (!this.model.result) {
+      return container.render(width);
+    }
+
+    const commandLabel =
+      this.model.result.launch === "deferred"
+        ? formatDeferredCommandLabel(this.clipboardStatus)
+        : "recovery command";
+    container.addChild(new Spacer(1));
+    container.addChild(
+      createLaunchCommandComponent(this.model.result.resumeCommand, commandLabel, this.theme),
+    );
+    if (this.model.result.degradedFrom) {
+      container.addChild(new Spacer(1));
+      container.addChild(
+        new Text(
+          this.theme.fg(
+            "muted",
+            `(requested ${this.model.result.degradedFrom}; split backend unavailable)`,
+          ),
+          0,
+          0,
+        ),
+      );
+    }
+    return container.render(width);
+  }
+}

package/extensions/session-handoff/tool-schema.ts

@@ -0,0 +1,54 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { formatAvailableModelList } from "../shared/model-resolution.ts";
+import { type HandoffLaunchTarget, SUBAGENT_LAUNCH } from "./launch-target.ts";
+
+export function buildHandoffLaunchSchema(targets: readonly HandoffLaunchTarget[]) {
+  const descriptions = targets.flatMap((target) =>
+    target.description ? [target.description] : [],
+  );
+  return Type.Union(
+    targets.map((target) => Type.Literal(target.value)),
+    {
+      description: ["Where to launch the child session.", ...descriptions].join(" "),
+    },
+  );
+}
+
+const SUBAGENT_GUIDELINES = [
+  'Use session_handoff with launch: "subagent" for a concrete, bounded task that can proceed independently while useful work continues in the current session.',
+  "Do not launch a subagent for work that is trivial, duplicates work already underway, requires frequent coordination, or is tightly coupled to the current session's immediate next step.",
+  "Tell every subagent explicitly whether it may modify files or should only investigate and report.",
+  "Give concurrent subagents disjoint responsibilities and non-overlapping write scopes.",
+  "After launching a subagent, do not sleep, poll, or repeatedly check its progress; continue useful work or finish the current turn and wait for its report.",
+];
+
+const LAUNCH_TARGET_GUIDELINE =
+  "Use session_handoff directional or deferred launches only when the user requests one.";
+
+const MODEL_INHERITANCE_GUIDELINES = [
+  "Leave provider and model unset to run the handoff on this session's current model.",
+  "To run the handoff on a different model, set both provider and model together (both are required).",
+];
+
+const SUBAGENT_MODEL_OVERRIDE_GUIDELINE =
+  "For subagents, choose the model that best fits the delegated task; for directional or deferred handoffs, only override the model when the task clearly warrants it. When unsure, ask the user for their preference.";
+
+const DEFAULT_MODEL_OVERRIDE_GUIDELINE =
+  "Only override the model when the task clearly warrants it.";
+
+export function buildHandoffPromptGuidelines(
+  targets: readonly HandoffLaunchTarget[],
+  models: readonly Model<Api>[],
+): string[] {
+  const hasSubagent = targets.some((target) => target.value === SUBAGENT_LAUNCH);
+  return [
+    ...(hasSubagent ? SUBAGENT_GUIDELINES : []),
+    LAUNCH_TARGET_GUIDELINE,
+    ...MODEL_INHERITANCE_GUIDELINES,
+    hasSubagent ? SUBAGENT_MODEL_OVERRIDE_GUIDELINE : DEFAULT_MODEL_OVERRIDE_GUIDELINE,
+    ...(models.length > 0
+      ? [`Available models, given as provider/model-id: ${formatAvailableModelList(models)}.`]
+      : []),
+  ];
+}

package/extensions/session-handoff/tool-view-model.ts

@@ -0,0 +1,49 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { normalizeOptionalText } from "../shared/text.ts";
+import { isThinkingLevel } from "../shared/thinking-levels.ts";
+import type { HandoffToolDetails } from "./tool-contract.ts";
+
+export interface HandoffToolViewModel {
+  launch?: string | undefined;
+  title?: string | undefined;
+  goal?: string | undefined;
+  provider?: string | undefined;
+  model?: string | undefined;
+  thinkingLevel?: ThinkingLevel | undefined;
+  result?: HandoffToolDetails | undefined;
+}
+
+export function buildHandoffToolView(
+  args: unknown,
+  result?: HandoffToolDetails | undefined,
+): HandoffToolViewModel {
+  const record = isRecord(args) ? args : {};
+  const provider = normalizeOptionalText(result?.provider) ?? readString(record.provider);
+  const model = normalizeOptionalText(result?.modelName) ?? readString(record.model);
+  const thinkingLevel = result?.thinkingLevel ?? readThinkingLevel(record.thinkingLevel);
+  return {
+    launch: readString(record.launch) ?? result?.launch,
+    title: readString(record.title) ?? result?.title,
+    goal: readString(record.goal),
+    ...(provider ? { provider } : {}),
+    ...(model ? { model } : {}),
+    ...(thinkingLevel ? { thinkingLevel } : {}),
+    ...(result ? { result } : {}),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readThinkingLevel(value: unknown): ThinkingLevel | undefined {
+  const level = readString(value);
+  return isThinkingLevel(level) ? level : undefined;
+}
+
+function readString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  return normalizeOptionalText(value);
+}