pi-sessions 0.18.1 → 0.20.0

package/extensions/session-messaging/pi/send-message-presenter.ts

@@ -5,6 +5,7 @@ import type { SendMessageViewModel } from "./send-message-view-model.ts";
 export function buildSendMessagePresentation(
   model: SendMessageViewModel,
   theme: RenderTheme,
+  toolName = "session_send_message",
 ): ExpandableContentPresentation {
   const target =
     model.status === "delivered"
@@ -18,7 +19,7 @@ export function buildSendMessagePresentation(
   const action = model.status === "delivered" ? "delivered to" : "to";
 
   return {
-    header: `${theme.fg("toolTitle", theme.bold("session_send_message"))} ${theme.fg(
+    header: `${theme.fg("toolTitle", theme.bold(toolName))} ${theme.fg(
       "muted",
       `${action} ${target}${metadataHint}`,
     )}`,

package/extensions/session-messaging/pi/tools.ts

@@ -1,4 +1,8 @@
-import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import {
+  defineTool,
+  type ExtensionContext,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { formatError } from "../../shared/errors.ts";
 import { ExpandableContentLayout } from "../../shared/rendering/expandable-content-layout.ts";
@@ -26,10 +30,11 @@ import { buildDeliveredMessageView, buildSendingMessageView } from "./send-messa
 import type { CancelSessionResult, SendMessageRequest, SendMessageResult } from "./service.ts";
 
 interface SendMessageService {
-  sendMessage(request: SendMessageRequest): Promise<SendMessageResult>;
+  sendMessage(request: SendMessageRequest, ctx: ExtensionContext): Promise<SendMessageResult>;
 }
 
-interface ManagedCancelSessionResult {
+/** A subagent's cancel goes through its parent's ledger, which reports the state it reconciled to. */
+export interface ManagedCancelSessionResult {
   kind: "managed";
   accepted: true;
   target: {
@@ -43,17 +48,15 @@ interface ManagedCancelSessionResult {
 }
 
 interface CancelSessionService {
-  cancelSession(sessionId: string): Promise<CancelSessionResult | ManagedCancelSessionResult>;
+  cancelSession(
+    sessionId: string,
+    ctx: ExtensionContext,
+  ): Promise<CancelSessionResult | ManagedCancelSessionResult>;
 }
 
-export type SessionSendMessageRole =
-  | { kind: "plain" }
-  | { kind: "wakeCapable" }
-  | { kind: "subagent" };
-
 export interface SessionSendMessageToolOptions {
-  role: SessionSendMessageRole;
-  hostedSessions?: boolean;
+  name: string;
+  wording: SendMessageToolWording;
   getCachedRelationTo(sessionId: string | undefined): string | undefined;
   /**
    * Resolved on every call: subagent identity depends on the active branch, so a rewind can
@@ -62,10 +65,9 @@ export interface SessionSendMessageToolOptions {
   getParentSessionId?: (() => string | undefined) | undefined;
 }
 
-export type SessionCancelRole = { kind: "plain" } | { kind: "subagent" };
-
 export interface SessionCancelToolOptions {
-  role: SessionCancelRole;
+  name: string;
+  wording: SendMessageToolWording;
   /**
    * Resolved on every call: subagent identity depends on the active branch, so a rewind can
    * turn a plain session into a subagent without re-registering this tool.
@@ -73,38 +75,12 @@ export interface SessionCancelToolOptions {
   getParentSessionId?: (() => string | undefined) | undefined;
 }
 
-interface SendMessageToolWording {
+export interface SendMessageToolWording {
   description: string;
   promptSnippet: string;
   promptGuidelines: string[];
 }
 
-function getSendMessageWording(role: SessionSendMessageRole): SendMessageToolWording {
-  switch (role.kind) {
-    case "plain":
-      return {
-        description: "Send a message to another live pi session.",
-        promptSnippet: "Send a message to another live pi session",
-        promptGuidelines: ["Use session_reachable to list live sessions and find the target."],
-      };
-    case "wakeCapable":
-      return {
-        description: "Send a message to another live pi session or a subagent.",
-        promptSnippet: "Send a message to another pi session or a subagent",
-        promptGuidelines: ["Use session_reachable to discover live sessions and owned subagents."],
-      };
-    case "subagent":
-      return {
-        description: "Send a message to another subagent.",
-        promptSnippet: "Send a message to another subagent",
-        promptGuidelines: [
-          "Use session_reachable to discover reachable subagents.",
-          "Report to your parent with submit_task_report; it cannot be reached with session_send_message.",
-        ],
-      };
-  }
-}
-
 interface SendMessageRendererState {
   callComponent?: ExpandableContentLayout | undefined;
 }
@@ -113,21 +89,14 @@ export function createSessionSendMessageTool(
   service: SendMessageService,
   options: SessionSendMessageToolOptions,
 ): ToolDefinition {
-  const { description, promptSnippet, promptGuidelines } = getSendMessageWording(options.role);
+  const { description, promptSnippet, promptGuidelines } = options.wording;
 
   return defineTool({
-    name: "session_send_message",
+    name: options.name,
     label: "Send Message to Session",
     description,
     promptSnippet,
-    promptGuidelines: [
-      ...promptGuidelines,
-      ...(options.hostedSessions
-        ? [
-            "session_reachable also lists dormant hosted sessions; sending a message wakes them automatically.",
-          ]
-        : []),
-    ],
+    promptGuidelines,
     parameters: SEND_MESSAGE_PARAMS,
     renderCall(args, theme, context) {
       const state = context.state as SendMessageRendererState;
@@ -137,12 +106,13 @@ export function createSessionSendMessageTool(
         buildSendMessagePresentation(
           buildSendingMessageView(args, options.getCachedRelationTo(args?.session)),
           theme,
+          options.name,
         ),
         context.expanded,
       );
       return component;
     },
-    renderResult(result, options, theme, context) {
+    renderResult(result, renderOptions, theme, context) {
       if (context.isError) {
         const output = getFirstText(result);
         return new Text(output ? `\n${theme.fg("error", output)}` : "", 0, 0);
@@ -155,29 +125,36 @@ export function createSessionSendMessageTool(
       }
 
       state.callComponent.update(
-        buildSendMessagePresentation(buildDeliveredMessageView(context.args, details), theme),
-        options.expanded,
+        buildSendMessagePresentation(
+          buildDeliveredMessageView(context.args, details),
+          theme,
+          options.name,
+        ),
+        renderOptions.expanded,
       );
       return new Text("", 0, 0);
     },
-    async execute(toolCallId, params: SendMessageParams, _signal, _onUpdate, _ctx) {
-      const target = parseSessionTarget(params.session, "session_send_message");
+    async execute(toolCallId, params: SendMessageParams, _signal, _onUpdate, ctx) {
+      const target = parseSessionTarget(params.session, options.name);
       if (target === options.getParentSessionId?.()) {
         throw new Error("The parent session cannot be messaged. Use submit_task_report.");
       }
 
       const body = params.message.trim();
       if (!body) {
-        throw new Error("session_send_message requires a non-empty message.");
+        throw new Error(`${options.name} requires a non-empty message.`);
       }
 
       try {
-        const result = await service.sendMessage({
-          target,
-          body,
-          requestResponse: params.requestResponse,
-          sourceToolCallId: toolCallId,
-        });
+        const result = await service.sendMessage(
+          {
+            target,
+            body,
+            requestResponse: params.requestResponse,
+            sourceToolCallId: toolCallId,
+          },
+          ctx,
+        );
         if (!result.delivered) {
           throw new Error(result.error ?? "Message was not delivered.");
         }
@@ -203,28 +180,14 @@ export function createSessionSendMessageTool(
   });
 }
 
-function getCancelPromptGuidelines(role: SessionCancelRole): string[] {
-  switch (role.kind) {
-    case "plain":
-      return ["Only cancel a user session when the user directs it."];
-    case "subagent":
-      return [
-        "Only cancel a user session when the user directs it.",
-        "Never cancel your parent session; it is waiting on your report.",
-      ];
-  }
-}
-
 export function createSessionCancelTool(
   service: CancelSessionService,
   options: SessionCancelToolOptions,
 ): ToolDefinition {
   return defineTool<typeof CANCEL_SESSION_PARAMS, CancelSessionToolDetails>({
-    name: "session_cancel",
+    name: options.name,
     label: "Cancel a running session",
-    description: "Cancel another running pi session",
-    promptSnippet: "Cancel another running pi session",
-    promptGuidelines: getCancelPromptGuidelines(options.role),
+    ...options.wording,
     parameters: CANCEL_SESSION_PARAMS,
     renderResult(result, options, theme, context) {
       const output = getFirstText(result);
@@ -244,14 +207,17 @@ export function createSessionCancelTool(
       }
       return new Text(text, 0, 0);
     },
-    async execute(_toolCallId, params: CancelSessionParams) {
-      const target = parseSessionTarget(params.session, "session_cancel");
+    async execute(_toolCallId, params: CancelSessionParams, _signal, _onUpdate, ctx) {
+      const target = parseSessionTarget(params.session, options.name);
       if (target === options.getParentSessionId?.()) {
         throw new Error("The parent session cannot be cancelled. It is waiting on your report.");
       }
 
-      const result = await service.cancelSession(target);
+      const result = await service.cancelSession(target, ctx);
       if (result.kind === "managed") {
+        if (!isConfirmedManagedCancellation(result.state)) {
+          throw new Error(buildUnknownCancellationError(result.target));
+        }
         const details: CancelSessionToolDetails = {
           kind: "managed",
           accepted: true,
@@ -260,16 +226,8 @@ export function createSessionCancelTool(
           ...(result.cancelId === undefined ? {} : { cancelId: result.cancelId }),
           ...(result.relation === undefined ? {} : { relation: result.relation }),
         };
-        if (!isConfirmedManagedCancellation(result.state)) {
-          throw new Error(buildUnknownCancellationError(result.target));
-        }
         return {
-          content: [
-            {
-              type: "text" as const,
-              text: buildCancelSessionModelText(details),
-            },
-          ],
+          content: [{ type: "text" as const, text: buildCancelSessionModelText(details) }],
           details,
         };
       }

package/extensions/session-search/extract.ts

@@ -23,6 +23,7 @@ import {
   type HandoffSessionMetadata,
   parseHandoffSessionMetadata,
 } from "../session-handoff/metadata.ts";
+import { LINEAGE_CUSTOM_TYPE, LINEAGE_SCHEMA, type SessionLineage } from "../shared/lineage.ts";
 import type { SessionOrigin } from "../shared/session-index/index.ts";
 import { contentToText, isRecord } from "../shared/text.ts";
 import { safeParseTypeBoxValue } from "../shared/typebox.ts";
@@ -97,6 +98,7 @@ export interface SessionEntryScan {
   sessionNameEntryId?: string | undefined;
   sessionNameTs?: string | undefined;
   handoffMetadata?: DurableHandoffMetadataRecord | undefined;
+  lineage?: SessionLineage | undefined;
 }
 
 export interface SessionTailBaseline {
@@ -194,7 +196,10 @@ export function extractSessionRecord(sessionPath: string): ExtractedSessionRecor
     chunks.push(...scan.chunks);
     appendDurableHandoffMetadataChunks(chunks, scan.handoffMetadata);
 
-    const parentSessionPath = normalizeParentSessionPath(header.parentSession);
+    const lineage = header.parentSession ? undefined : scan.lineage;
+    const parentSessionPath = normalizeParentSessionPath(
+      header.parentSession ?? lineage?.parentSessionFile,
+    );
     const parentSession = parentSessionPath
       ? inspectParentSession(parentSessionPath, header.id, sessionPath)
       : undefined;
@@ -211,7 +216,7 @@ export function extractSessionRecord(sessionPath: string): ExtractedSessionRecor
       messageCount: scan.messageCount,
       entryCount: scan.entryCount,
       parentSessionPath,
-      parentSessionId: parentSession?.sessionId,
+      parentSessionId: lineage?.parentSessionId ?? parentSession?.sessionId,
       sessionOrigin: deriveSessionOrigin(
         parentSessionPath,
         parentSession?.launchedSubagent ?? false,
@@ -306,6 +311,7 @@ export function scanSessionEntries(
   let sessionNameEntryId: string | undefined;
   let sessionNameTs: string | undefined;
   let handoffMetadata: DurableHandoffMetadataRecord | undefined;
+  let lineage: SessionLineage | undefined;
 
   for (const entry of entries) {
     if (!isSessionEntry(entry)) continue;
@@ -336,6 +342,9 @@ export function scanSessionEntries(
         continue;
       }
       case "custom": {
+        if (entry.customType === LINEAGE_CUSTOM_TYPE && !lineage) {
+          lineage = safeParseTypeBoxValue(LINEAGE_SCHEMA, entry.data);
+        }
         const nextHandoffMetadata = extractHandoffMetadata(entry, entryTs);
         if (nextHandoffMetadata && !handoffMetadata) {
           handoffMetadata = nextHandoffMetadata;
@@ -393,6 +402,7 @@ export function scanSessionEntries(
     sessionNameEntryId,
     sessionNameTs,
     handoffMetadata,
+    lineage,
   };
 }
 

package/extensions/shared/lineage.ts

@@ -0,0 +1,8 @@
+import { type Static, Type } from "typebox";
+
+export const LINEAGE_CUSTOM_TYPE = "pi-sessions.lineage";
+export const LINEAGE_SCHEMA = Type.Object({
+  parentSessionId: Type.String({ minLength: 1 }),
+  parentSessionFile: Type.Optional(Type.String({ minLength: 1 })),
+});
+export type SessionLineage = Static<typeof LINEAGE_SCHEMA>;

package/extensions/shared/session-index/sync.ts

@@ -231,6 +231,9 @@ function applyTailSync(
   sessionOrigin?: SessionOrigin,
 ): boolean {
   return db.transaction((): boolean => {
+    // A lineage entry can arrive after the initial header sync. Re-read the header to
+    // preserve its precedence and rebuild lineage through the normal full-sync path.
+    if (tail.scan.lineage) return false;
     // Another process may have advanced the index between our baseline read
     // and this transaction; the tail deltas would then double-count.
     const current = getSessionRowByPath(db, baseline.sessionPath);

package/extensions/shared/settings.ts

@@ -23,6 +23,7 @@ const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
       enable: Type.Optional(Type.Boolean()),
       maxDepth: Type.Optional(Type.Integer({ minimum: 0 })),
       contextLimit: Type.Optional(Type.Integer({ minimum: 1 })),
+      agentsDir: Type.Optional(Type.String()),
     }),
   ),
   handoff: Type.Optional(
@@ -125,6 +126,8 @@ export interface SessionSettings {
     maxDepth: number;
     /** Effective context window for a subagent, when smaller than its model's. */
     contextLimit?: number;
+    /** Where agent profiles for subagent launches live. */
+    agentsDir: string;
   };
   handoff: HandoffSettings;
   index: {
@@ -140,6 +143,10 @@ export function getDefaultIndexDir(): string {
   return path.join(getAgentDir(), "pi-sessions");
 }
 
+export function getDefaultAgentsDir(): string {
+  return path.join(getAgentDir(), "agents");
+}
+
 export function getDefaultIndexPath(): string {
   return path.join(getDefaultIndexDir(), "index.sqlite");
 }
@@ -168,19 +175,19 @@ function expandHome(rawPath: string): string {
   return rawPath;
 }
 
-function normalizeIndexDir(value: string | undefined): string {
+function normalizeDir(value: string | undefined, defaultDir: string, key: string): string {
   if (value === undefined) {
-    return getDefaultIndexDir();
+    return defaultDir;
   }
 
   const trimmed = value.trim();
   if (trimmed.length === 0) {
-    return getDefaultIndexDir();
+    return defaultDir;
   }
 
   const expanded = expandHome(trimmed);
   if (!path.isAbsolute(expanded)) {
-    throw new Error('sessions.index.dir must be an absolute path or start with "~/".');
+    throw new Error(`${key} must be an absolute path or start with "~/".`);
   }
 
   return path.normalize(expanded);
@@ -254,7 +261,11 @@ function resolveFeatureToggles(value: SessionFileSettings): FeatureToggles {
 }
 
 function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSettings {
-  const indexDir = normalizeIndexDir(fileSettings.index?.dir);
+  const indexDir = normalizeDir(
+    fileSettings.index?.dir,
+    getDefaultIndexDir(),
+    "sessions.index.dir",
+  );
 
   return {
     features: resolveFeatureToggles(fileSettings),
@@ -263,6 +274,11 @@ function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSetti
       ...(fileSettings.subagents?.contextLimit === undefined
         ? {}
         : { contextLimit: fileSettings.subagents.contextLimit }),
+      agentsDir: normalizeDir(
+        fileSettings.subagents?.agentsDir,
+        getDefaultAgentsDir(),
+        "sessions.subagents.agentsDir",
+      ),
     },
     handoff: {
       ...resolveAgentModelSettings(fileSettings.handoff),

package/extensions/subagents/install.ts

@@ -10,10 +10,6 @@ import type {
   SendMessageResult,
 } from "../session-messaging/install.ts";
 import type { SessionWaker } from "../session-messaging/message-router.ts";
-import {
-  createSessionCancelTool,
-  createSessionSendMessageTool,
-} from "../session-messaging/pi/tools.ts";
 import type { SessionLifecycle } from "../shared/composition.ts";
 import type { CompactionThresholdSettings, SessionSettings } from "../shared/settings.ts";
 import { isTmuxInstalled } from "../shared/tmux.ts";
@@ -82,7 +78,6 @@ export function installSubagents(
     messaging: MessagingHandle;
     readCompactionSettings: (cwd: string) => CompactionThresholdSettings;
     sendMessage(request: SendMessageRequest): Promise<SendMessageResult>;
-    hasHostedSessions?: () => boolean;
   },
 ): SubagentsHandle {
   pi.registerMessageRenderer(SUBAGENT_REPORT_MESSAGE_CUSTOM_TYPE, renderSubagentReportMessage);
@@ -154,7 +149,10 @@ export function installSubagents(
 
   pi.on("before_agent_start", (event) => {
     if (current?.child) {
-      event.systemPromptOptions.sections[SUBAGENT_PROMPT_SECTION] = SUBAGENT_PROMPT;
+      const agent = current.child.identity.agent;
+      event.systemPromptOptions.sections[SUBAGENT_PROMPT_SECTION] = agent
+        ? `${SUBAGENT_PROMPT}\n\n${agent.instructions}`
+        : SUBAGENT_PROMPT;
     }
   });
 
@@ -171,12 +169,12 @@ export function installSubagents(
 
   pi.on("agent_start", (_event, ctx) => {
     settledChildLifecycle.cancel();
-    if (current?.child) {
+    if (current?.child && !current.child.paused) {
       current.child.reportsAtTurnStart = countSubagentReports(ctx.sessionManager.getBranch());
     }
   });
 
-  pi.on("agent_settled", async (_event, ctx) => {
+  pi.on("agent_settled", async (event, ctx) => {
     const session = current;
     if (!session || session.parent.sessionId !== ctx.sessionManager.getSessionId()) {
       return;
@@ -192,7 +190,11 @@ export function installSubagents(
     }
     if (session.child) {
       await contextLimit.compactIfOverLimit(ctx);
-      await settledChildLifecycle.settle(session.parent, session.child, reconciliation);
+      // Escape in the child's pane pauses the delegated turn; it still owes its parent a report.
+      session.child.paused = event.aborted;
+      if (!event.aborted) {
+        await settledChildLifecycle.settle(session.parent, session.child, reconciliation);
+      }
     }
   });
 
@@ -225,28 +227,9 @@ export function installSubagents(
     }
   };
 
-  const registerMessagingTools = (): void => {
-    const isSubagent = handle.getParentSessionId() !== undefined;
-    pi.registerTool(
-      createSessionSendMessageTool(handle, {
-        role: isSubagent ? { kind: "subagent" } : { kind: "wakeCapable" },
-        hostedSessions: deps.hasHostedSessions?.() ?? false,
-        getCachedRelationTo: deps.messaging.getCachedRelationTo,
-        getParentSessionId: () => handle.getParentSessionId(),
-      }),
-    );
-    pi.registerTool(
-      createSessionCancelTool(handle, {
-        role: isSubagent ? { kind: "subagent" } : { kind: "plain" },
-        getParentSessionId: () => handle.getParentSessionId(),
-      }),
-    );
-  };
-
   pi.on("session_tree", async (_event, ctx) => {
     settledChildLifecycle.cancel();
     refreshChildSession();
-    registerMessagingTools();
     try {
       await reconciler.reconcileAndRestoreSuspended();
     } catch (error) {
@@ -303,9 +286,6 @@ export function installSubagents(
       reconciler.beginSession();
       current = { parent };
       refreshChildSession();
-      if (identity) {
-        registerMessagingTools();
-      }
       try {
         if (_event.reason === "reload") {
           await reconciler.reconcile();

package/extensions/subagents/launch-target.ts

@@ -19,15 +19,16 @@ export function createSubagentLaunchTarget(
     value: SUBAGENT_LAUNCH,
     description:
       "'subagent' delegates one task to a detached tmux worker and requests a report by default.",
-    requestResponseDefault: true,
     bootstrapMode: "automatic",
     approveProjectTrust: true,
+    requiredTools: ["submit_task_report"],
     describeSubagentChild(input) {
       return {
         childSessionId: input.childSessionId,
         ownerSessionId: input.ownerSessionId,
         depth: state.depth + 1,
         requestResponse: input.requestResponse,
+        ...(input.agent ? { agent: input.agent } : {}),
       };
     },
     prepareChild(input) {

package/extensions/subagents/reconcile.ts

@@ -8,7 +8,12 @@ import {
   type TmuxExecutor,
   tmuxSessionName,
 } from "../shared/tmux.ts";
-import { classifySubagent, type SubagentEvidence, type SubagentState } from "./classify.ts";
+import {
+  classifySubagent,
+  isRunningSubagentState,
+  type SubagentEvidence,
+  type SubagentState,
+} from "./classify.ts";
 import {
   type ChildSubagentLifecycle,
   collectParentLedger,
@@ -220,8 +225,11 @@ export class SubagentReconciler {
         continue;
       }
 
+      // A running child writes its report to its own transcript before sending it live; recovering it in
+      // between would deliver it as recovered. Once the child stops, recovery is the report's only path.
+      const reports = isRunningSubagentState(child.state) ? [] : child.reports;
       let reportLedger: ParentSubagentLedger | undefined;
-      for (const report of child.reports) {
+      for (const report of reports) {
         if (this.hasSentReport(report.reportId)) {
           continue;
         }

package/extensions/subagents/settle.ts

@@ -17,6 +17,7 @@ export interface SubagentChildSessionState {
   identity: HandoffSubagent;
   requestResponse: boolean;
   reportsAtTurnStart: number;
+  paused: boolean;
 }
 
 export interface SettledChildParentSession {
@@ -159,6 +160,7 @@ export function refreshSubagentChildState(
     identity,
     requestResponse: identity.requestResponse,
     reportsAtTurnStart: reports,
+    paused: false,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "type": "module",
   "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",
@@ -38,10 +38,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.10",
-    "@earendil-works/pi-agent-core": "^1.1.0",
-    "@earendil-works/pi-ai": "^1.1.0",
-    "@earendil-works/pi-coding-agent": "^1.1.0",
-    "@earendil-works/pi-tui": "^1.1.0",
+    "@earendil-works/pi-agent-core": "^1.3.0",
+    "@earendil-works/pi-ai": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
+    "@earendil-works/pi-tui": "^1.3.0",
     "@types/node": "^24.13.3",
     "strip-ansi": "^7.2.0",
     "typebox": "1.3.27",