pi-sessions 0.7.2 → 0.9.0

package/extensions/session-handoff/install.ts

@@ -0,0 +1,225 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import type { IndexHandle, SessionLifecycle } from "../shared/composition.ts";
+import type { ModelRuntimeProvider } from "../shared/model-runtime.ts";
+import { isTuiMode } from "../shared/pi-mode.ts";
+import type { SessionSettings } from "../shared/settings.ts";
+import { THINKING_LEVELS } from "../shared/thinking-levels.ts";
+import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+import { type HandoffBoardServices, openHandoffBoard } from "./board.ts";
+import { consumePendingHandoffBootstrap } from "./bootstrap.ts";
+import { HANDOFF_KICKOFF_CUSTOM_TYPE, renderHandoffKickoffMessage } from "./kickoff.ts";
+import type { ClipboardStatus } from "./launch/backend.ts";
+import { resolveSplitLaunchBackend } from "./launch/resolution.ts";
+import { createHandoffLaunchTargets } from "./launch-options.ts";
+import type { HandoffLaunchTarget } from "./launch-target.ts";
+import { openSessionReferencePicker } from "./picker.ts";
+import { SESSION_TOKEN_PREFIX } from "./query.ts";
+import {
+  executeSessionHandoffTool,
+  type HandoffToolParams,
+  MAX_HANDOFF_TITLE_LENGTH,
+} from "./tool.ts";
+import { HANDOFF_TOOL_DETAILS_SCHEMA } from "./tool-contract.ts";
+import { HandoffToolComponent } from "./tool-renderer.ts";
+import { buildHandoffLaunchSchema, buildHandoffPromptGuidelines } from "./tool-schema.ts";
+import { buildHandoffToolView } from "./tool-view-model.ts";
+import { formatHandoffError } from "./ui.ts";
+
+interface HandoffToolRendererState {
+  callComponent?: HandoffToolComponent | undefined;
+}
+
+export function installHandoff(
+  pi: ExtensionAPI,
+  deps: {
+    settings: SessionSettings;
+    index: IndexHandle;
+    getModelRuntime: ModelRuntimeProvider;
+    getLaunchTargets?: (() => readonly HandoffLaunchTarget[]) | undefined;
+    board: HandoffBoardServices;
+  },
+): SessionLifecycle {
+  const { settings } = deps;
+  const indexPath = deps.index.path;
+  let identifiedGhosttyTerminalId: string | undefined;
+  const clipboardStatusBySessionId = new Map<string, ClipboardStatus>();
+  const splitBackend = resolveSplitLaunchBackend(pi, {
+    getTerminalId: () => identifiedGhosttyTerminalId,
+  });
+
+  pi.registerMessageRenderer(HANDOFF_KICKOFF_CUSTOM_TYPE, renderHandoffKickoffMessage);
+  function registerHandoffTool(
+    models: readonly Model<Api>[],
+    launchTargets: readonly HandoffLaunchTarget[],
+  ): void {
+    pi.registerTool({
+      name: "session_handoff",
+      label: "Session Handoff",
+      description: "Start a new Pi session with a self-contained task.",
+      promptSnippet:
+        "Delegate bounded work to a background subagent or hand off context to another Pi session",
+      promptGuidelines: buildHandoffPromptGuidelines(launchTargets, models),
+      parameters: Type.Object({
+        goal: Type.String({
+          description:
+            "Self-contained briefing that explains the objective, relevant context, constraints, and expected result.",
+        }),
+        title: Type.String({
+          maxLength: MAX_HANDOFF_TITLE_LENGTH,
+          description:
+            "Short display title for the child session, 64 characters or less. Summarize the mission; do not repeat the full goal.",
+        }),
+        launch: buildHandoffLaunchSchema(launchTargets),
+        cwd: Type.Optional(
+          Type.String({
+            description: "Optional target working directory (defaults to current).",
+          }),
+        ),
+        requestResponse: Type.Optional(
+          Type.Boolean({
+            description:
+              "Whether the child session should report completion/results of its task back to this session. Defaults to true for subagent launches and false otherwise.",
+          }),
+        ),
+        provider: Type.Optional(
+          Type.String({
+            description: "Model provider for the child session.",
+          }),
+        ),
+        model: Type.Optional(
+          Type.String({
+            description: "Model id for the child session.",
+          }),
+        ),
+        thinkingLevel: Type.Optional(
+          Type.Union(
+            THINKING_LEVELS.map((level) => Type.Literal(level)),
+            {
+              description:
+                "Thinking level for the child session. For directional or deferred, override only when the user requests it.",
+            },
+          ),
+        ),
+      }),
+      renderCall(args, theme, context) {
+        const state = context.state as HandoffToolRendererState;
+        const component = state.callComponent ?? new HandoffToolComponent(theme);
+        state.callComponent = component;
+        component.update(buildHandoffToolView(args), context.expanded);
+        return component;
+      },
+      renderResult(result, options, theme, context) {
+        const text = getFirstText(result);
+        if (context.isError) {
+          return new Text(theme.fg("error", text), 0, 0);
+        }
+
+        const details = safeParseTypeBoxValue(HANDOFF_TOOL_DETAILS_SCHEMA, result.details);
+        const state = context.state as HandoffToolRendererState;
+        if (!details || !state.callComponent) {
+          return new Text(text, 0, 0);
+        }
+
+        state.callComponent.update(
+          buildHandoffToolView(context.args, details),
+          options.expanded,
+          clipboardStatusBySessionId.get(details.sessionId),
+        );
+        return new Text("", 0, 0);
+      },
+      async execute(_toolCallId, params: HandoffToolParams, _signal, _onUpdate, ctx) {
+        const modelRuntime = await deps.getModelRuntime(ctx.modelRegistry);
+        return executeSessionHandoffTool(
+          pi,
+          params,
+          ctx,
+          modelRuntime,
+          launchTargets,
+          (sessionId, status) => clipboardStatusBySessionId.set(sessionId, status),
+        );
+      },
+    });
+  }
+
+  pi.registerCommand("handoff", {
+    description: "Open the handoff board",
+    handler: async (args, ctx): Promise<void> => {
+      if (!isTuiMode(ctx)) {
+        ctx.ui.notify("handoff requires interactive mode", "error");
+        return;
+      }
+      if (args.trim()) {
+        ctx.ui.notify("/handoff does not accept arguments.", "error");
+        return;
+      }
+
+      try {
+        await openHandoffBoard(ctx, deps.board);
+      } catch (error) {
+        ctx.ui.notify(formatHandoffError(error), "error");
+      }
+    },
+  });
+
+  pi.registerShortcut(settings.handoff.pickerShortcut, {
+    description: "Open the session reference picker",
+    handler: async (ctx) => {
+      if (!isTuiMode(ctx)) {
+        return;
+      }
+
+      const result = await openSessionReferencePicker(
+        ctx,
+        indexPath,
+        settings.handoff.pickerShortcut,
+      );
+      if (result.kind !== "insert-session-token") {
+        return;
+      }
+
+      ctx.ui.pasteToEditor(`${SESSION_TOKEN_PREFIX}${result.sessionId}`);
+    },
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (splitBackend?.identifyTerminalId && ctx) {
+      identifiedGhosttyTerminalId =
+        (await splitBackend.identifyTerminalId(ctx.cwd)) ?? identifiedGhosttyTerminalId;
+    }
+
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        "\n\nWhen the user references @session:<uuid>, treat it as a session token. If you call session_ask, pass only the UUID value, not the @session: prefix.",
+    };
+  });
+
+  return {
+    async onSessionStart(_event, ctx) {
+      registerHandoffTool(
+        ctx.modelRegistry.getAvailable(),
+        createHandoffLaunchTargets({
+          pi,
+          splitBackend,
+          copyDeferredToClipboard: settings.handoff.deferred.copyToClipboard,
+          additionalTargets: deps.getLaunchTargets?.() ?? [],
+        }),
+      );
+
+      await consumePendingHandoffBootstrap(
+        pi,
+        ctx,
+        deps.getModelRuntime,
+        pi.getThinkingLevel(),
+        settings.handoff.persistRuns,
+      );
+    },
+  };
+}
+
+function getFirstText(result: { content: Array<{ type: string; text?: string }> }): string {
+  return result.content.find((item) => item.type === "text")?.text ?? "";
+}

package/extensions/session-handoff/kickoff.ts

@@ -0,0 +1,92 @@
+import type { MessageRenderer } from "@earendil-works/pi-coding-agent";
+import { Box, type Component, Text } from "@earendil-works/pi-tui";
+import { type Static, Type } from "typebox";
+import type { RenderTheme } from "../shared/rendering/theme.ts";
+import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+
+export const HANDOFF_KICKOFF_CUSTOM_TYPE = "pi-sessions.handoff-kickoff";
+
+export const HANDOFF_KICKOFF_SOURCE_SCHEMA = Type.Object({
+  sessionId: Type.String(),
+  sessionName: Type.Optional(Type.String()),
+});
+
+export const HANDOFF_KICKOFF_DETAILS_SCHEMA = Type.Object({
+  source: HANDOFF_KICKOFF_SOURCE_SCHEMA,
+  title: Type.String(),
+  bootstrapEntryId: Type.Optional(Type.String()),
+});
+
+export type HandoffKickoffSource = Static<typeof HANDOFF_KICKOFF_SOURCE_SCHEMA>;
+export type HandoffKickoffDetails = Static<typeof HANDOFF_KICKOFF_DETAILS_SCHEMA>;
+
+export interface HandoffKickoffMessage {
+  customType: typeof HANDOFF_KICKOFF_CUSTOM_TYPE;
+  content: string;
+  display: true;
+  details: HandoffKickoffDetails;
+}
+
+// The kickoff is the model-visible delivery of the approved handoff prompt:
+// content is exactly the prompt (provider context unchanged), details carry
+// renderer metadata only.
+export function buildHandoffKickoffMessage(options: {
+  prompt: string;
+  title: string;
+  source: HandoffKickoffSource;
+  bootstrapEntryId?: string | undefined;
+}): HandoffKickoffMessage {
+  return {
+    customType: HANDOFF_KICKOFF_CUSTOM_TYPE,
+    content: options.prompt,
+    display: true,
+    details: {
+      source: buildHandoffKickoffSource(options.source),
+      title: options.title,
+      ...(options.bootstrapEntryId ? { bootstrapEntryId: options.bootstrapEntryId } : {}),
+    },
+  };
+}
+
+export function buildHandoffKickoffSource(source: HandoffKickoffSource): HandoffKickoffSource {
+  return {
+    sessionId: source.sessionId,
+    ...(source.sessionName?.trim() ? { sessionName: source.sessionName.trim() } : {}),
+  };
+}
+
+export const renderHandoffKickoffMessage: MessageRenderer = (message, _options, theme) => {
+  const details = safeParseTypeBoxValue(HANDOFF_KICKOFF_DETAILS_SCHEMA, message.details);
+  if (!details) {
+    return undefined;
+  }
+
+  const prompt = typeof message.content === "string" ? message.content : "";
+  return createHandoffKickoffComponent(details, prompt, theme);
+};
+
+export function createHandoffKickoffComponent(
+  details: HandoffKickoffDetails,
+  prompt: string,
+  theme: RenderTheme,
+): Component {
+  const box = new Box(1, 1, (text: string) => theme.bg("customMessageBg", text));
+  box.addChild(new Text(renderHandoffKickoffView(details, prompt, theme), 0, 0));
+  return box;
+}
+
+export function renderHandoffKickoffView(
+  details: HandoffKickoffDetails,
+  prompt: string,
+  theme: RenderTheme,
+): string {
+  const label = theme.fg("toolTitle", theme.bold("handoff"));
+  const header = `${label} ${theme.bold(details.title)}`;
+  const from = theme.fg("muted", `from ${formatKickoffSource(details.source)}`);
+  return [`${header} ${from}`, "", theme.fg("toolOutput", prompt)].join("\n");
+}
+
+function formatKickoffSource(source: HandoffKickoffDetails["source"]): string {
+  const title = source.sessionName?.trim();
+  return title ? `${title} (${source.sessionId})` : source.sessionId;
+}

package/extensions/session-handoff/launch/backend.ts

@@ -0,0 +1,16 @@
+import type { HandoffLaunchTargetOutcome } from "../launch-target.ts";
+
+export type HandoffSplitDirection = "left" | "right" | "up" | "down";
+
+export interface LaunchInput {
+  cwd: string;
+  title: string;
+  resumeCommand: string;
+}
+
+export type ClipboardStatus = "copied" | "failed";
+
+export interface LaunchBackend {
+  name: string;
+  launch(input: LaunchInput): Promise<HandoffLaunchTargetOutcome>;
+}

package/extensions/session-handoff/launch/deferred.ts

@@ -0,0 +1,20 @@
+import { copyToClipboard } from "@earendil-works/pi-coding-agent";
+import type { LaunchBackend, LaunchInput } from "./backend.ts";
+
+export function createDeferredLaunchBackend(options: { copyToClipboard: boolean }): LaunchBackend {
+  return {
+    name: "deferred",
+    async launch(input: LaunchInput) {
+      if (!options.copyToClipboard) {
+        return { success: true, backend: "deferred" as const };
+      }
+
+      try {
+        await copyToClipboard(input.resumeCommand);
+        return { success: true, backend: "deferred" as const, clipboardStatus: "copied" as const };
+      } catch {
+        return { success: true, backend: "deferred" as const, clipboardStatus: "failed" as const };
+      }
+    },
+  };
+}

package/extensions/session-handoff/launch/ghostty.ts

@@ -0,0 +1,99 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { HandoffLaunchTargetOutcome } from "../launch-target.ts";
+import type { HandoffSplitDirection, LaunchBackend, LaunchInput } from "./backend.ts";
+import { escapeAppleScriptString, shellQuote } from "./shell.ts";
+
+const GHOSTTY_MACOS_ONLY_MESSAGE = "Split handoff currently supports Ghostty on macOS only.";
+const GHOSTTY_SPLIT_TIMEOUT_MS = 15_000;
+const OSASCRIPT_PATH = "/usr/bin/osascript";
+
+export interface GhosttyLaunchConfig {
+  direction: HandoffSplitDirection;
+  terminalId?: string | undefined;
+}
+
+export function isGhosttyHandoffAvailable(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  return platform === "darwin" && env.TERM_PROGRAM === "ghostty";
+}
+
+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;
+  }
+
+  return result.stdout.trim() || undefined;
+}
+
+export function createGhosttyLaunchBackend(
+  pi: ExtensionAPI,
+  config: GhosttyLaunchConfig,
+): LaunchBackend {
+  return {
+    name: "Ghostty",
+    async launch(input: LaunchInput): Promise<HandoffLaunchTargetOutcome> {
+      const first = await runGhosttySplit(pi, config, config.terminalId, input);
+      if (first.success || !config.terminalId) {
+        return first;
+      }
+
+      return runGhosttySplit(pi, config, undefined, input);
+    },
+  };
+}
+
+async function runGhosttySplit(
+  pi: ExtensionAPI,
+  config: GhosttyLaunchConfig,
+  terminalId: string | undefined,
+  input: LaunchInput,
+): Promise<HandoffLaunchTargetOutcome> {
+  const escapedCwd = escapeAppleScriptString(input.cwd);
+  const escapedCommand = escapeAppleScriptString(buildGhosttyShellCommand(input.resumeCommand));
+  const targetTerminalLine = terminalId
+    ? `    set targetTerminal to item 1 of (every terminal whose id is "${escapeAppleScriptString(terminalId)}")`
+    : "    set targetTerminal to focused terminal of selected tab of front window";
+  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 ${config.direction} with configuration cfg`,
+    "end tell",
+  ].join("\n");
+  const result = await pi.exec(OSASCRIPT_PATH, ["-e", appleScript], {
+    cwd: input.cwd,
+    timeout: GHOSTTY_SPLIT_TIMEOUT_MS,
+  });
+
+  if (result.code === 0) {
+    return { success: true, backend: "Ghostty" };
+  }
+
+  const details = `${result.stderr || result.stdout}`.trim() || `exit code ${result.code}`;
+  return {
+    success: false,
+    error: `Failed to launch Ghostty split: ${details}. ${GHOSTTY_MACOS_ONLY_MESSAGE}`,
+  };
+}
+
+function buildGhosttyShellCommand(resumeCommand: string): string {
+  const payload = `${resumeCommand}; exec /bin/zsh -il`;
+  return `/bin/zsh -ilc ${shellQuote(payload)}`;
+}

package/extensions/session-handoff/launch/resolution.ts

@@ -0,0 +1,57 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isInsideTmux } from "../../shared/tmux.ts";
+import type { HandoffSplitDirection, LaunchBackend } from "./backend.ts";
+import {
+  createGhosttyLaunchBackend,
+  getFocusedGhosttyTerminalId,
+  isGhosttyHandoffAvailable,
+} from "./ghostty.ts";
+import { createTmuxSplitLaunchBackend } from "./tmux.ts";
+
+export interface SplitLaunchBackend {
+  name: string;
+  create(direction: HandoffSplitDirection): LaunchBackend;
+  identifyTerminalId?(cwd: string): Promise<string | undefined>;
+}
+
+export function resolveSplitLaunchBackend(
+  pi: ExtensionAPI,
+  options: {
+    getTerminalId: () => string | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+  },
+): SplitLaunchBackend | undefined {
+  const env = options.env ?? process.env;
+  if (isInsideTmux(env)) {
+    return {
+      name: "tmux",
+      create: (direction) => createTmuxSplitLaunchBackend(pi, direction),
+    };
+  }
+  if (!isGhosttyHandoffAvailable(env)) {
+    return undefined;
+  }
+  return {
+    name: "Ghostty",
+    identifyTerminalId: (cwd) => getFocusedGhosttyTerminalId(pi, cwd),
+    create(direction) {
+      return createGhosttyLaunchBackend(pi, {
+        direction,
+        terminalId: options.getTerminalId(),
+      });
+    },
+  };
+}
+
+export function validateSplitHandoffPrerequisites(
+  ctx: ExtensionContext,
+  backend: SplitLaunchBackend | undefined,
+): string | undefined {
+  if (!ctx.sessionManager.getSessionFile()) {
+    return "Split handoff requires a persisted current session.";
+  }
+  if (!backend) {
+    return "Split handoff requires running inside tmux or Ghostty on macOS.";
+  }
+  return undefined;
+}

package/extensions/session-handoff/launch/shell.ts

@@ -0,0 +1,7 @@
+export function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+export function escapeAppleScriptString(value: string): string {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}

package/extensions/session-handoff/launch/tmux.ts

@@ -0,0 +1,31 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { HandoffSplitDirection, LaunchBackend, LaunchInput } from "./backend.ts";
+
+const TMUX_SPLIT_TIMEOUT_MS = 15_000;
+
+export function createTmuxSplitLaunchBackend(
+  pi: ExtensionAPI,
+  direction: HandoffSplitDirection,
+): LaunchBackend {
+  return {
+    name: "tmux",
+    async launch(input: LaunchInput) {
+      const result = await pi.exec("tmux", splitArgs(direction, input), {
+        cwd: input.cwd,
+        timeout: TMUX_SPLIT_TIMEOUT_MS,
+      });
+      if (result.code === 0) {
+        return { success: true, backend: "tmux" as const };
+      }
+
+      const details = `${result.stderr || result.stdout}`.trim() || `exit code ${result.code}`;
+      return { success: false, error: `Failed to launch tmux split: ${details}.` };
+    },
+  };
+}
+
+function splitArgs(direction: HandoffSplitDirection, input: LaunchInput): string[] {
+  const orientation = direction === "left" || direction === "right" ? "-h" : "-v";
+  const before = direction === "left" || direction === "up" ? ["-b"] : [];
+  return ["split-window", orientation, ...before, "-d", "-c", input.cwd, input.resumeCommand];
+}

package/extensions/session-handoff/launch-options.ts

@@ -0,0 +1,61 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createDeferredLaunchBackend } from "./launch/deferred.ts";
+import type { SplitLaunchBackend } from "./launch/resolution.ts";
+import {
+  createBackendLaunchTarget,
+  DEFERRED_LAUNCH,
+  type HandoffLaunchTarget,
+  type HandoffLaunchValue,
+  LAUNCH_DIRECTIONS,
+} from "./launch-target.ts";
+
+export interface ResolvedHandoffLaunchTarget {
+  target: HandoffLaunchTarget;
+  degradedFrom?: (typeof LAUNCH_DIRECTIONS)[number] | undefined;
+}
+
+export function createHandoffLaunchTargets(options: {
+  pi: ExtensionAPI;
+  splitBackend: SplitLaunchBackend | undefined;
+  copyDeferredToClipboard: boolean;
+  additionalTargets: readonly HandoffLaunchTarget[];
+}): HandoffLaunchTarget[] {
+  const splitBackend = options.splitBackend;
+  const splitTargets = splitBackend
+    ? LAUNCH_DIRECTIONS.map((direction, index) =>
+        createBackendLaunchTarget(
+          direction,
+          splitBackend.create(direction),
+          index === 0
+            ? `direction values open a ${splitBackend.name} split. If the user does not make the launch target clear, ask for clarification.`
+            : undefined,
+        ),
+      )
+    : [];
+  const deferred = createBackendLaunchTarget(
+    DEFERRED_LAUNCH,
+    createDeferredLaunchBackend({ copyToClipboard: options.copyDeferredToClipboard }),
+    "'deferred' creates the session and returns its resume command without opening anything.",
+  );
+  return [...splitTargets, deferred, ...options.additionalTargets];
+}
+
+export function resolveHandoffLaunchTarget(
+  requested: HandoffLaunchValue,
+  targets: readonly HandoffLaunchTarget[],
+): ResolvedHandoffLaunchTarget {
+  const exact = targets.find((target) => target.value === requested);
+  if (exact) {
+    return { target: exact };
+  }
+
+  if (LAUNCH_DIRECTIONS.some((direction) => direction === requested)) {
+    const deferred = targets.find((target) => target.value === DEFERRED_LAUNCH);
+    if (!deferred) {
+      throw new Error("Deferred handoff launch is unavailable.");
+    }
+    return { target: deferred, degradedFrom: requested as (typeof LAUNCH_DIRECTIONS)[number] };
+  }
+
+  throw new Error(`Handoff launch target is unavailable: ${requested}`);
+}