pi-sessions 0.8.0 → 0.9.0

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

@@ -0,0 +1,91 @@
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import type { ClipboardStatus, HandoffSplitDirection, LaunchBackend } from "./launch/backend.ts";
+import type { HandoffSubagent } from "./metadata.ts";
+import type { PreparedHandoff } from "./spawn.ts";
+
+export const DEFERRED_LAUNCH = "deferred" as const;
+export const SUBAGENT_LAUNCH = "subagent" as const;
+
+export const LAUNCH_DIRECTIONS = ["left", "right", "up", "down"] as const;
+export const HANDOFF_DIRECTION_LAUNCH_SCHEMA = Type.Union([
+  Type.Literal("left"),
+  Type.Literal("right"),
+  Type.Literal("up"),
+  Type.Literal("down"),
+]);
+
+export const HANDOFF_NON_SUBAGENT_LAUNCH_SCHEMA = Type.Union([
+  HANDOFF_DIRECTION_LAUNCH_SCHEMA,
+  Type.Literal(DEFERRED_LAUNCH),
+]);
+
+export const HANDOFF_LAUNCH_VALUE_SCHEMA = Type.Union([
+  HANDOFF_NON_SUBAGENT_LAUNCH_SCHEMA,
+  Type.Literal(SUBAGENT_LAUNCH),
+]);
+
+export type HandoffLaunchValue = Static<typeof HANDOFF_LAUNCH_VALUE_SCHEMA>;
+
+export interface HandoffLaunchTargetPreparation {
+  manager: SessionManager;
+  childSessionId: string;
+  parentSessionId: string;
+  parentSessionFile: string;
+  requestResponse: boolean;
+}
+
+export interface HandoffLaunchTargetInput {
+  prepared: PreparedHandoff;
+  parentSessionId: string;
+  title: string;
+  goal: string;
+  requestResponse: boolean;
+  model: string;
+  cwd: string;
+}
+
+export type HandoffLaunchTargetOutcome =
+  | {
+      success: true;
+      backend: string;
+      clipboardStatus?: ClipboardStatus | undefined;
+    }
+  | { success: false; error: string };
+
+/** A backend plus the handoff policy required to prepare and launch one child. */
+export interface HandoffLaunchTarget {
+  value: HandoffLaunchValue;
+  description?: string | undefined;
+  requestResponseDefault: boolean;
+  bootstrapMode: "review" | "automatic";
+  /** Subagent launches stamp their child's identity into the durable handoff record. */
+  describeSubagentChild?(input: {
+    childSessionId: string;
+    ownerSessionId: string;
+    requestResponse: boolean;
+  }): HandoffSubagent;
+  prepareChild(input: HandoffLaunchTargetPreparation): void;
+  launch(input: HandoffLaunchTargetInput): Promise<HandoffLaunchTargetOutcome>;
+}
+
+export function createBackendLaunchTarget(
+  value: HandoffSplitDirection | "deferred",
+  backend: LaunchBackend,
+  description?: string | undefined,
+): HandoffLaunchTarget {
+  return {
+    value,
+    ...(description ? { description } : {}),
+    requestResponseDefault: false,
+    bootstrapMode: "review",
+    prepareChild() {},
+    launch(input) {
+      return backend.launch({
+        cwd: input.cwd,
+        title: input.title,
+        resumeCommand: input.prepared.resumeCommand,
+      });
+    },
+  };
+}

package/extensions/session-handoff/metadata.ts

@@ -1,79 +1,111 @@
-import { Buffer } from "node:buffer";
 import type { CustomEntry, SessionEntry } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+import { HANDOFF_KICKOFF_CUSTOM_TYPE, HANDOFF_KICKOFF_DETAILS_SCHEMA } from "./kickoff.ts";
+import {
+  HANDOFF_NON_SUBAGENT_LAUNCH_SCHEMA,
+  type HandoffLaunchValue,
+  SUBAGENT_LAUNCH,
+} from "./launch-target.ts";
 
 export const HANDOFF_METADATA_CUSTOM_TYPE = "pi-sessions.handoff";
-export const HANDOFF_BOOTSTRAP_ENV = "PI_SESSIONS_HANDOFF_BOOTSTRAP";
+export const HANDOFF_BOOTSTRAP_PENDING_CUSTOM_TYPE = "pi-sessions.handoff-bootstrap";
+export const HANDOFF_BOOTSTRAP_CONSUMED_CUSTOM_TYPE = "pi-sessions.handoff-bootstrap-consumed";
 export const HANDOFF_STALE_SESSION_MESSAGE =
   "Session handoff failed: target session already has user input.";
+export const SESSION_STARTING_MESSAGE =
+  "Target session is still starting. wait for it to show up in session_search, then resend.";
+
+// A subagent's self-knowledge, stamped into the durable handoff record so the
+// child never opens the parent transcript to learn who it is.
+export const HANDOFF_SUBAGENT_SCHEMA = Type.Object({
+  childSessionId: Type.String(),
+  ownerSessionId: Type.String(),
+  depth: Type.Integer({ minimum: 1 }),
+  requestResponse: Type.Boolean(),
+});
 
-export const HANDOFF_SESSION_METADATA_SCHEMA = Type.Object({
+const HANDOFF_METADATA_BASE = {
   origin: Type.Literal("handoff"),
   goal: Type.String(),
-  nextTask: Type.String(),
   title: Type.String(),
   initial_prompt: Type.String(),
-});
-
-export const IMMEDIATE_HANDOFF_BOOTSTRAP_SCHEMA = Type.Object({
-  sessionId: Type.String(),
-  goal: Type.String(),
-  nextTask: Type.String(),
-  title: Type.String(),
-  initialPrompt: Type.String(),
-});
+};
+
+export const HANDOFF_SESSION_METADATA_SCHEMA = Type.Union([
+  Type.Object({
+    ...HANDOFF_METADATA_BASE,
+    launch: Type.Literal(SUBAGENT_LAUNCH),
+    subagent: HANDOFF_SUBAGENT_SCHEMA,
+  }),
+  Type.Object({
+    ...HANDOFF_METADATA_BASE,
+    launch: HANDOFF_NON_SUBAGENT_LAUNCH_SCHEMA,
+    subagent: Type.Optional(Type.Never()),
+  }),
+]);
 
-export const CHILD_GENERATED_HANDOFF_BOOTSTRAP_SCHEMA = Type.Object({
+const HANDOFF_BOOTSTRAP_BASE = {
   mode: Type.Literal("generate"),
   sessionId: Type.String(),
   goal: Type.String(),
   title: Type.String(),
   parentSessionFile: Type.String(),
-  requestResponse: Type.Optional(Type.Boolean()),
-});
+  sourceLeafId: Type.String(),
+  requestResponse: Type.Boolean(),
+  bootstrapMode: Type.Union([Type.Literal("review"), Type.Literal("automatic")]),
+};
 
 export const HANDOFF_BOOTSTRAP_SCHEMA = Type.Union([
-  IMMEDIATE_HANDOFF_BOOTSTRAP_SCHEMA,
-  CHILD_GENERATED_HANDOFF_BOOTSTRAP_SCHEMA,
+  Type.Object({
+    ...HANDOFF_BOOTSTRAP_BASE,
+    launch: Type.Literal(SUBAGENT_LAUNCH),
+    subagent: HANDOFF_SUBAGENT_SCHEMA,
+  }),
+  Type.Object({
+    ...HANDOFF_BOOTSTRAP_BASE,
+    launch: HANDOFF_NON_SUBAGENT_LAUNCH_SCHEMA,
+    subagent: Type.Optional(Type.Never()),
+  }),
 ]);
 
+export const HANDOFF_BOOTSTRAP_CONSUMED_SCHEMA = Type.Object({
+  bootstrapEntryId: Type.String(),
+  reason: Type.Union([
+    Type.Literal("cancelled"),
+    Type.Literal("prefilled"),
+    Type.Literal("stale"),
+    Type.Literal("invalid"),
+  ]),
+});
+
+export type HandoffSubagent = Static<typeof HANDOFF_SUBAGENT_SCHEMA>;
 export type HandoffSessionMetadata = Static<typeof HANDOFF_SESSION_METADATA_SCHEMA>;
-export type ImmediateHandoffBootstrap = Static<typeof IMMEDIATE_HANDOFF_BOOTSTRAP_SCHEMA>;
-export type ChildGeneratedHandoffBootstrap = Static<
-  typeof CHILD_GENERATED_HANDOFF_BOOTSTRAP_SCHEMA
->;
 export type HandoffBootstrap = Static<typeof HANDOFF_BOOTSTRAP_SCHEMA>;
+export type ChildGeneratedHandoffBootstrap = HandoffBootstrap;
+export type HandoffBootstrapConsumed = Static<typeof HANDOFF_BOOTSTRAP_CONSUMED_SCHEMA>;
+export type HandoffBootstrapConsumedReason = HandoffBootstrapConsumed["reason"];
 
 export function createHandoffSessionMetadata(
   goal: string,
-  nextTask: string,
   initialPrompt: string,
   title: string,
+  launch: HandoffLaunchValue,
+  subagent: HandoffSubagent | undefined,
 ): HandoffSessionMetadata {
-  const normalizedGoal = goal.trim();
-  const normalizedNextTask = nextTask.trim() || normalizedGoal;
-
-  return {
-    origin: "handoff",
-    goal: normalizedGoal,
-    nextTask: normalizedNextTask,
+  const base = {
+    origin: "handoff" as const,
+    goal: goal.trim(),
     title,
     initial_prompt: initialPrompt.trim(),
   };
-}
-
-export function createHandoffBootstrap(
-  sessionId: string,
-  metadata: HandoffSessionMetadata,
-): ImmediateHandoffBootstrap {
-  return {
-    sessionId,
-    goal: metadata.goal,
-    nextTask: metadata.nextTask,
-    title: metadata.title,
-    initialPrompt: metadata.initial_prompt,
-  };
+  if (launch === SUBAGENT_LAUNCH) {
+    if (!subagent) {
+      throw new Error("A subagent handoff requires a subagent identity block.");
+    }
+    return { ...base, launch, subagent };
+  }
+  return { ...base, launch };
 }
 
 export function createChildGeneratedHandoffBootstrap(options: {
@@ -81,35 +113,86 @@ export function createChildGeneratedHandoffBootstrap(options: {
   goal: string;
   title: string;
   parentSessionFile: string;
-  requestResponse?: boolean | undefined;
+  sourceLeafId: string;
+  requestResponse: boolean;
+  bootstrapMode: "review" | "automatic";
+  launch: HandoffLaunchValue;
+  subagent?: HandoffSubagent | undefined;
 }): ChildGeneratedHandoffBootstrap {
-  return {
-    mode: "generate",
+  const base = {
+    mode: "generate" as const,
     sessionId: options.sessionId,
     goal: options.goal.trim(),
     title: options.title.trim(),
     parentSessionFile: options.parentSessionFile,
-    ...(options.requestResponse === undefined ? {} : { requestResponse: options.requestResponse }),
+    sourceLeafId: options.sourceLeafId,
+    requestResponse: options.requestResponse,
+    bootstrapMode: options.bootstrapMode,
   };
+  if (options.launch === SUBAGENT_LAUNCH) {
+    if (!options.subagent) {
+      throw new Error("A subagent handoff requires a subagent identity block.");
+    }
+    return { ...base, launch: options.launch, subagent: options.subagent };
+  }
+  return { ...base, launch: options.launch };
 }
 
-export function isChildGeneratedHandoffBootstrap(
-  bootstrap: HandoffBootstrap,
-): bootstrap is ChildGeneratedHandoffBootstrap {
-  return "mode" in bootstrap && bootstrap.mode === "generate";
-}
+export type PendingHandoffBootstrapScan =
+  | { kind: "pending"; entryId: string; bootstrap: HandoffBootstrap }
+  | { kind: "invalid"; entryId: string };
+
+/**
+ * Finds the newest unconsumed pending bootstrap on a branch. Consumption is
+ * append-only: a delivered kickoff or consumed marker must reference the
+ * bootstrap entry it consumed.
+ */
+export function findPendingHandoffBootstrap(
+  branch: readonly SessionEntry[],
+): PendingHandoffBootstrapScan | undefined {
+  const consumedEntryIds = new Set<string>();
+  for (const entry of branch) {
+    if (entry.type === "custom_message" && entry.customType === HANDOFF_KICKOFF_CUSTOM_TYPE) {
+      const details = safeParseTypeBoxValue(HANDOFF_KICKOFF_DETAILS_SCHEMA, entry.details);
+      if (details?.bootstrapEntryId) {
+        consumedEntryIds.add(details.bootstrapEntryId);
+      }
+    }
+    if (entry.type === "custom" && entry.customType === HANDOFF_BOOTSTRAP_CONSUMED_CUSTOM_TYPE) {
+      const consumed = safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_CONSUMED_SCHEMA, entry.data);
+      if (consumed) {
+        consumedEntryIds.add(consumed.bootstrapEntryId);
+      }
+    }
+  }
 
-export function encodeHandoffBootstrap(bootstrap: HandoffBootstrap): string {
-  return Buffer.from(JSON.stringify(bootstrap), "utf8").toString("base64");
-}
+  for (let i = branch.length - 1; i >= 0; i -= 1) {
+    const entry = branch[i];
+    if (
+      entry?.type !== "custom" ||
+      entry.customType !== HANDOFF_BOOTSTRAP_PENDING_CUSTOM_TYPE ||
+      consumedEntryIds.has(entry.id)
+    ) {
+      continue;
+    }
 
-export function parseHandoffBootstrap(value: string): HandoffBootstrap | undefined {
-  try {
-    const decoded = Buffer.from(value, "base64").toString("utf8");
-    return safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_SCHEMA, JSON.parse(decoded));
-  } catch {
-    return undefined;
+    const bootstrap = safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_SCHEMA, entry.data);
+    return bootstrap
+      ? { kind: "pending", entryId: entry.id, bootstrap }
+      : { kind: "invalid", entryId: entry.id };
   }
+
+  return undefined;
+}
+
+/**
+ * A session is *starting* when its active branch still carries an unconsumed,
+ * well-formed handoff bootstrap: it has been prepared but has not received its
+ * kickoff. An invalid bootstrap does not count — the child consumes it and
+ * proceeds as an ordinary session rather than kicking off a handoff.
+ */
+export function isSessionStarting(branch: readonly SessionEntry[]): boolean {
+  return findPendingHandoffBootstrap(branch)?.kind === "pending";
 }
 
 export function parseHandoffSessionMetadata(value: unknown): HandoffSessionMetadata | undefined {
@@ -133,8 +216,14 @@ export function getHandoffMetadataFromEntries(
   return undefined;
 }
 
-export function hasUserMessages(entries: readonly SessionEntry[]): boolean {
-  return entries.some((entry) => entry.type === "message" && entry.message.role === "user");
+// Bootstrap freshness: an existing kickoff counts as a started conversation
+// even though no native user message exists.
+export function hasStartedConversation(entries: readonly SessionEntry[]): boolean {
+  return entries.some(
+    (entry) =>
+      (entry.type === "message" && entry.message.role === "user") ||
+      (entry.type === "custom_message" && entry.customType === HANDOFF_KICKOFF_CUSTOM_TYPE),
+  );
 }
 
 function parseCustomHandoffMetadata(entry: CustomEntry): HandoffSessionMetadata | undefined {

package/extensions/session-handoff/model.ts

@@ -0,0 +1,58 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { formatAvailableModelList, resolveAuthenticatedModel } from "../shared/model-resolution.ts";
+import { isThinkingLevel } from "../shared/thinking-levels.ts";
+
+export function formatModelArgument(
+  model: Model<Api> | undefined,
+  thinkingLevel: ThinkingLevel | undefined,
+): string | undefined {
+  if (!model) {
+    return undefined;
+  }
+
+  const base = `${model.provider}/${model.id}`;
+  return thinkingLevel ? `${base}:${thinkingLevel}` : base;
+}
+
+export function parseModelArgument(value: string): {
+  model: string;
+  thinkingLevel?: ThinkingLevel | undefined;
+} {
+  const separator = value.lastIndexOf(":");
+  const suffix = separator >= 0 ? value.slice(separator + 1) : undefined;
+  if (!isThinkingLevel(suffix)) {
+    return { model: value };
+  }
+  return {
+    model: value.slice(0, separator),
+    thinkingLevel: suffix,
+  };
+}
+
+export interface HandoffModelOverride {
+  model: Model<Api>;
+  thinkingLevel: ThinkingLevel | undefined;
+}
+
+export function resolveModelOverride(
+  modelRuntime: ModelRuntime,
+  modelPattern: string,
+  thinkingLevel?: ThinkingLevel | undefined,
+): HandoffModelOverride {
+  const resolution = resolveAuthenticatedModel({ modelRuntime, modelPattern, thinkingLevel });
+  if (!resolution.ok) {
+    const warning = resolution.warning ? ` ${resolution.warning}` : "";
+    throw new Error(
+      `${resolution.error}${warning} Available models: ${formatAvailableModelList(
+        modelRuntime.getAvailableSnapshot(),
+      )}.`,
+    );
+  }
+
+  return {
+    model: resolution.model,
+    thinkingLevel: resolution.thinkingLevel,
+  };
+}

package/extensions/session-handoff/query.ts

@@ -264,7 +264,6 @@ function getBestTextSnippet(result: SearchSessionResult): string | undefined {
 function getSessionTitle(result: SearchSessionResult): string {
   return (
     normalizeDisplayText(result.sessionName) ??
-    normalizeDisplayText(result.handoffNextTask) ??
     normalizeDisplayText(result.handoffGoal) ??
     normalizeDisplayText(result.firstUserPrompt) ??
     normalizeDisplayText(stripSearchSnippetMarkers(getBestTextSnippet(result))) ??

package/extensions/session-handoff/receipt.ts

@@ -0,0 +1,96 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { Box, type Component, Container, Text } from "@earendil-works/pi-tui";
+import { type Static, type TLiteral, Type } from "typebox";
+import type { RenderTheme } from "../shared/rendering/theme.ts";
+import { THINKING_LEVELS } from "../shared/thinking-levels.ts";
+import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+import type { ClipboardStatus } from "./launch/backend.ts";
+import { HANDOFF_LAUNCH_VALUE_SCHEMA, type HandoffLaunchValue } from "./launch-target.ts";
+
+const THINKING_LEVEL_SCHEMAS = THINKING_LEVELS.map((level) => Type.Literal(level)) as [
+  TLiteral<ThinkingLevel>,
+  ...TLiteral<ThinkingLevel>[],
+];
+
+export const HANDOFF_LAUNCH_RECEIPT_SCHEMA = Type.Object({
+  sessionId: Type.String(),
+  childSessionFile: Type.String(),
+  title: Type.String(),
+  launch: HANDOFF_LAUNCH_VALUE_SCHEMA,
+  resumeCommand: Type.String(),
+  backend: Type.Optional(Type.String()),
+  cwd: Type.Optional(Type.String()),
+  model: Type.String(),
+  provider: Type.Optional(Type.String()),
+  modelName: Type.Optional(Type.String()),
+  thinkingLevel: Type.Optional(Type.Union(THINKING_LEVEL_SCHEMAS)),
+});
+
+export type HandoffLaunchReceipt = Static<typeof HANDOFF_LAUNCH_RECEIPT_SCHEMA>;
+
+export function parseHandoffLaunchReceiptEntry(
+  entry: SessionEntry,
+): HandoffLaunchReceipt | undefined {
+  if (
+    entry.type === "message" &&
+    entry.message.role === "toolResult" &&
+    entry.message.toolName === "session_handoff"
+  ) {
+    return safeParseTypeBoxValue(HANDOFF_LAUNCH_RECEIPT_SCHEMA, entry.message.details);
+  }
+  return undefined;
+}
+
+export function buildLaunchReceipt(options: {
+  sessionId: string;
+  childSessionFile: string;
+  title: string;
+  launch: HandoffLaunchValue;
+  resumeCommand: string;
+  backend?: string | undefined;
+  targetCwd: string;
+  parentCwd: string;
+  childModel: string;
+  childProvider: string;
+  childModelName: string;
+  thinkingLevel?: ThinkingLevel | undefined;
+}): HandoffLaunchReceipt {
+  return {
+    sessionId: options.sessionId,
+    childSessionFile: options.childSessionFile,
+    title: options.title,
+    launch: options.launch,
+    resumeCommand: options.resumeCommand,
+    ...(options.backend ? { backend: options.backend } : {}),
+    ...(options.targetCwd !== options.parentCwd ? { cwd: options.targetCwd } : {}),
+    model: options.childModel,
+    provider: options.childProvider,
+    modelName: options.childModelName,
+    ...(options.thinkingLevel ? { thinkingLevel: options.thinkingLevel } : {}),
+  };
+}
+
+export function createLaunchCommandComponent(
+  command: string,
+  label: string,
+  theme: RenderTheme,
+): Component {
+  const container = new Container();
+  container.addChild(new Text(theme.fg("muted", label), 0, 0));
+  const commandBox = new Box(1, 0, (text) => theme.bg("customMessageBg", text));
+  commandBox.addChild(new Text(theme.fg("toolOutput", command), 0, 0));
+  container.addChild(commandBox);
+  return container;
+}
+
+export function formatDeferredCommandLabel(clipboardStatus?: ClipboardStatus | undefined): string {
+  switch (clipboardStatus) {
+    case "copied":
+      return "resume command · copied to clipboard";
+    case "failed":
+      return "resume command · clipboard copy failed";
+    default:
+      return "resume command";
+  }
+}

package/extensions/session-handoff/review.ts

@@ -1,8 +1,4 @@
-import type {
-  ExtensionCommandContext,
-  ExtensionUIContext,
-  Theme,
-} from "@earendil-works/pi-coding-agent";
+import type { ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
 import {
   Key,
@@ -11,6 +7,7 @@ import {
   visibleWidth,
   wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
+import { renderStrongModal } from "./strong-modal.ts";
 
 const PREVIEW_TIMEOUT_MS = 8_000;
 const PREVIEW_BODY_LINE_LIMIT = 16;
@@ -205,17 +202,6 @@ export class HandoffPreviewComponent implements Component {
   }
 }
 
-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);
-}
-
 function formatKeymapLine(left: string, right: string): string {
   return `${left.padEnd(27, " ")}${right}`;
 }
@@ -235,18 +221,6 @@ function renderPromptSection(lines: string[], width: number, _theme: Theme): str
   ];
 }
 
-export async function reviewHandoffDraft(
-  ctx: ExtensionCommandContext,
-  draft: string,
-): Promise<string | undefined> {
-  const result = await reviewHandoffDraftForSend(ctx.ui, draft);
-  if (result.action !== "send") {
-    return undefined;
-  }
-
-  return result.prompt;
-}
-
 export async function reviewHandoffDraftForSend(
   ui: ExtensionUIContext,
   draft: string,