1// SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
2// SPDX-FileCopyrightText: Petr Baudis <pasky@ucw.cz>
3//
4// SPDX-License-Identifier: MIT
5
6import { complete, type Message, type Tool } from "@mariozechner/pi-ai";
7import type {
8 ExtensionAPI,
9 ExtensionCommandContext,
10 ExtensionContext,
11 SessionEntry,
12} from "@mariozechner/pi-coding-agent";
13import { BorderedLoader, SessionManager, convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
14import { Key, matchesKey } from "@mariozechner/pi-tui";
15import { Type } from "@sinclair/typebox";
16import * as fs from "node:fs";
17import * as os from "node:os";
18import * as path from "node:path";
19
20const STATUS_KEY = "handoff";
21const COUNTDOWN_SECONDS = 10;
22
23/**
24 * Model used for handoff extraction calls. Set PI_HANDOFF_MODEL env var
25 * as "provider/modelId" (e.g. "anthropic/claude-haiku-4-5") to use a
26 * different model for extraction than the session's current model.
27 */
28const HANDOFF_MODEL_OVERRIDE = process.env.PI_HANDOFF_MODEL;
29
30const SYSTEM_PROMPT = `You're helping transfer context between coding sessions. The next session starts fresh with no memory of this conversation, so extract what matters.
31
32Consider these questions:
33- What was just done or implemented?
34- What decisions were made and why?
35- What technical details were discovered (APIs, methods, patterns)?
36- What constraints, limitations, or caveats were found?
37- What patterns or approaches are being followed?
38- What is still unfinished or unresolved?
39- What open questions or risks are worth flagging?
40
41Rules:
42- Be concrete: prefer file paths, specific decisions, and actual commands over vague summaries.
43- Only include files from the provided candidate list.
44- Only include skills from the provided loaded skills list.
45- If something wasn't explicitly discussed, don't include it.`;
46
47const QUERY_SYSTEM_PROMPT = `You answer questions about a prior pi session.
48
49Rules:
50- Use only facts from the provided conversation.
51- Prefer concrete outputs: file paths, decisions, TODOs, errors.
52- If not present, say explicitly: "Not found in provided session.".
53- Keep answer concise.`;
54
55/**
56 * Tool definition passed to the extraction LLM call. Models produce
57 * structured tool-call arguments far more reliably than free-form JSON
58 * in a text response, so we use a single tool instead of responseFormat.
59 */
60const HANDOFF_EXTRACTION_TOOL: Tool = {
61 name: "extract_handoff_context",
62 description: "Extract handoff context from the conversation for a new session.",
63 parameters: Type.Object({
64 relevantFiles: Type.Array(Type.String(), {
65 description: "File paths relevant to continuing this work, chosen from the provided candidate list",
66 }),
67 skillsInUse: Type.Array(Type.String(), {
68 description: "Skills relevant to the goal, chosen from the provided list of loaded skills",
69 }),
70 context: Type.String({
71 description:
72 "Key context: what was done, decisions made, technical details discovered, constraints, and patterns being followed",
73 }),
74 openItems: Type.Array(Type.String(), {
75 description: "Unfinished work, open questions, known risks, and things to watch out for",
76 }),
77 }),
78};
79
80type PendingAutoSubmit = {
81 ctx: ExtensionContext;
82 sessionFile: string | undefined;
83 interval: ReturnType<typeof setInterval>;
84 unsubscribeInput: () => void;
85};
86
87type PendingHandoff = {
88 prompt: string;
89 parentSession: string | undefined;
90 newModel: string | undefined;
91};
92
93function isEditableInput(data: string): boolean {
94 if (!data) return false;
95 if (data.length === 1) {
96 const code = data.charCodeAt(0);
97 if (code >= 32 && code !== 127) return true;
98 if (code === 8 || code === 13) return true;
99 }
100
101 if (data === "\n" || data === "\r") return true;
102 if (data === "\x7f") return true;
103
104 if (data.length > 1 && !data.startsWith("\x1b")) return true;
105
106 return false;
107}
108
109function statusLine(ctx: ExtensionContext, seconds: number): string {
110 const accent = ctx.ui.theme.fg("accent", `handoff auto-submit in ${seconds}s`);
111 const hint = ctx.ui.theme.fg("dim", "(type to edit, Esc to cancel)");
112 return `${accent} ${hint}`;
113}
114
115function getSessionsRoot(sessionFile: string | undefined): string | undefined {
116 if (!sessionFile) return undefined;
117 const normalized = sessionFile.replace(/\\/g, "/");
118 const marker = "/sessions/";
119 const idx = normalized.indexOf(marker);
120 if (idx === -1) {
121 return path.dirname(path.resolve(sessionFile));
122 }
123 return normalized.slice(0, idx + marker.length - 1);
124}
125
126function getFallbackSessionsRoot(): string | undefined {
127 const configuredDir = process.env.PI_CODING_AGENT_DIR;
128 const candidate = configuredDir
129 ? path.resolve(configuredDir, "sessions")
130 : path.resolve(os.homedir(), ".pi", "agent", "sessions");
131 return fs.existsSync(candidate) ? candidate : undefined;
132}
133
134function normalizeSessionPath(sessionPath: string, sessionsRoot: string | undefined): string {
135 if (path.isAbsolute(sessionPath)) return path.resolve(sessionPath);
136 if (sessionsRoot) return path.resolve(sessionsRoot, sessionPath);
137 return path.resolve(sessionPath);
138}
139
140function sessionPathAllowed(candidate: string, sessionsRoot: string | undefined): boolean {
141 if (!sessionsRoot) return true;
142 const root = path.resolve(sessionsRoot);
143 const resolved = path.resolve(candidate);
144 return resolved === root || resolved.startsWith(`${root}${path.sep}`);
145}
146
147/**
148 * Build a candidate file set from two sources:
149 * 1. Primary: actual tool calls (read, write, edit, create) in the session
150 * 2. Secondary: file-like patterns in the conversation text (catches files
151 * that were discussed but never opened)
152 */
153function extractCandidateFiles(entries: SessionEntry[], conversationText: string): Set<string> {
154 const files = new Set<string>();
155 const fileToolNames = new Set(["read", "write", "edit", "create"]);
156
157 // Primary: files from actual tool calls
158 for (const entry of entries) {
159 if (entry.type !== "message") continue;
160 const msg = entry.message;
161 if (msg.role !== "assistant") continue;
162
163 for (const block of msg.content) {
164 if (typeof block !== "object" || block === null || block.type !== "toolCall") continue;
165 if (!fileToolNames.has(block.name)) continue;
166
167 const args = block.arguments as Record<string, unknown>;
168 const filePath =
169 typeof args.path === "string" ? args.path : typeof args.file === "string" ? args.file : undefined;
170 if (!filePath) continue;
171 if (filePath.endsWith("/SKILL.md")) continue;
172
173 files.add(filePath);
174 }
175 }
176
177 // Secondary: file-like patterns from conversation text.
178 // Trailing lookahead so the boundary isn't consumed — otherwise adjacent
179 // files separated by a single space (e.g. "file1.txt file2.txt") get skipped.
180 const filePattern = /(?:^|\s)([a-zA-Z0-9._\-/]+\.[a-zA-Z0-9]+)(?=\s|$|[,;:)])/gm;
181 for (const match of conversationText.matchAll(filePattern)) {
182 const candidate = match[1];
183 if (candidate && !candidate.startsWith(".") && candidate.length > 2) {
184 files.add(candidate);
185 }
186 }
187
188 return files;
189}
190
191/**
192 * Extract skill names that were actually loaded during the conversation.
193 * Looks for read() tool calls targeting SKILL.md files and derives the
194 * skill name from the parent directory (the convention for pi skills).
195 */
196function extractLoadedSkills(entries: SessionEntry[]): string[] {
197 const skills = new Set<string>();
198 for (const entry of entries) {
199 if (entry.type !== "message") continue;
200 const msg = entry.message;
201 if (msg.role !== "assistant") continue;
202
203 for (const block of msg.content) {
204 if (typeof block !== "object" || block === null || block.type !== "toolCall") continue;
205
206 // read() calls where the path ends in SKILL.md
207 if (block.name !== "read") continue;
208 const args = block.arguments as Record<string, unknown>;
209 const filePath = typeof args.path === "string" ? args.path : undefined;
210 if (!filePath?.endsWith("/SKILL.md")) continue;
211
212 // Skill name is the parent directory name:
213 // .../skills/backing-up-with-keld/SKILL.md → backing-up-with-keld
214 const parent = path.basename(path.dirname(filePath));
215 if (parent && parent !== "skills") {
216 skills.add(parent);
217 }
218 }
219 }
220 return [...skills].sort();
221}
222
223/**
224 * Resolve the model to use for handoff extraction calls. Uses the
225 * PI_HANDOFF_MODEL env var if set, otherwise falls back to the session model.
226 */
227function resolveExtractionModel(ctx: {
228 model: ExtensionContext["model"];
229 modelRegistry: ExtensionContext["modelRegistry"];
230}): ExtensionContext["model"] {
231 if (!HANDOFF_MODEL_OVERRIDE) return ctx.model;
232 const slashIdx = HANDOFF_MODEL_OVERRIDE.indexOf("/");
233 if (slashIdx <= 0) return ctx.model;
234 const provider = HANDOFF_MODEL_OVERRIDE.slice(0, slashIdx);
235 const modelId = HANDOFF_MODEL_OVERRIDE.slice(slashIdx + 1);
236 return ctx.modelRegistry.find(provider, modelId) ?? ctx.model;
237}
238
239type HandoffExtraction = {
240 files: string[];
241 skills: string[];
242 context: string;
243 openItems: string[];
244};
245
246/**
247 * Run the extraction LLM call and return structured context, or null if
248 * aborted or the model didn't produce a valid tool call.
249 */
250async function extractHandoffContext(
251 model: NonNullable<ExtensionContext["model"]>,
252 apiKey: string,
253 headers: Record<string, string> | undefined,
254 conversationText: string,
255 goal: string,
256 candidateFiles: string[],
257 loadedSkills: string[],
258 signal?: AbortSignal,
259): Promise<HandoffExtraction | null> {
260 const filesContext =
261 candidateFiles.length > 0
262 ? `\n\n## Candidate Files\n\nThese files were touched or mentioned during the session. Return only the ones relevant to the goal.\n\n${candidateFiles.map((f) => `- ${f}`).join("\n")}`
263 : "";
264
265 const skillsContext =
266 loadedSkills.length > 0
267 ? `\n\n## Skills Loaded During This Session\n\n${loadedSkills.map((s) => `- ${s}`).join("\n")}\n\nReturn only the skills from this list that are relevant to the goal.`
268 : "";
269
270 const userMessage: Message = {
271 role: "user",
272 content: [
273 {
274 type: "text",
275 text: `## Conversation\n\n${conversationText}\n\n## Goal for Next Session\n\n${goal}${filesContext}${skillsContext}`,
276 },
277 ],
278 timestamp: Date.now(),
279 };
280
281 const response = await complete(
282 model,
283 {
284 systemPrompt: SYSTEM_PROMPT,
285 messages: [userMessage],
286 tools: [HANDOFF_EXTRACTION_TOOL],
287 },
288 { apiKey, headers, signal },
289 );
290
291 if (response.stopReason === "aborted") return null;
292
293 const toolCall = response.content.find((c) => c.type === "toolCall" && c.name === "extract_handoff_context");
294
295 if (!toolCall || toolCall.type !== "toolCall") {
296 console.error("Model did not call extract_handoff_context:", response.content);
297 return null;
298 }
299
300 const args = toolCall.arguments as Record<string, unknown>;
301
302 if (
303 !Array.isArray(args.relevantFiles) ||
304 !Array.isArray(args.skillsInUse) ||
305 typeof args.context !== "string" ||
306 !Array.isArray(args.openItems)
307 ) {
308 console.error("Unexpected tool call arguments shape:", args);
309 return null;
310 }
311
312 const candidateSet = new Set(candidateFiles);
313 const loadedSkillSet = new Set(loadedSkills);
314
315 return {
316 files: (args.relevantFiles as string[]).filter((f) => typeof f === "string" && candidateSet.has(f)),
317 skills: (args.skillsInUse as string[]).filter((s) => typeof s === "string" && loadedSkillSet.has(s)),
318 context: args.context as string,
319 openItems: (args.openItems as string[]).filter((item) => typeof item === "string"),
320 };
321}
322
323/**
324 * Assemble the handoff draft. The user's goal goes last so it has the
325 * most weight in the new session (recency bias).
326 */
327function assembleHandoffDraft(result: HandoffExtraction, goal: string, parentSessionFile: string | undefined): string {
328 const parentBlock = parentSessionFile
329 ? `**Parent session:** \`${parentSessionFile}\`\n\nUse the \`session_query\` tool with this path if you need details from the prior thread.\n\n`
330 : "";
331
332 const filesSection = result.files.length > 0 ? `## Files\n\n${result.files.map((f) => `- ${f}`).join("\n")}\n\n` : "";
333
334 const skillsSection =
335 result.skills.length > 0 ? `## Skills in Use\n\n${result.skills.map((s) => `- ${s}`).join("\n")}\n\n` : "";
336
337 const contextSection = `## Context\n\n${result.context}\n\n`;
338
339 const openItemsSection =
340 result.openItems.length > 0 ? `## Open Items\n\n${result.openItems.map((item) => `- ${item}`).join("\n")}\n\n` : "";
341
342 return `${parentBlock}${filesSection}${skillsSection}${contextSection}${openItemsSection}${goal}`.trim();
343}
344
345export default function (pi: ExtensionAPI) {
346 let pending: PendingAutoSubmit | null = null;
347 let pendingHandoff: PendingHandoff | null = null;
348 let handoffTimestamp: number | null = null;
349
350 const clearPending = (ctx?: ExtensionContext, notify?: string) => {
351 if (!pending) return;
352
353 clearInterval(pending.interval);
354 pending.unsubscribeInput();
355 pending.ctx.ui.setStatus(STATUS_KEY, undefined);
356
357 const local = pending;
358 pending = null;
359
360 if (notify && ctx) {
361 ctx.ui.notify(notify, "info");
362 } else if (notify) {
363 local.ctx.ui.notify(notify, "info");
364 }
365 };
366
367 const autoSubmitDraft = () => {
368 if (!pending) return;
369
370 const active = pending;
371 const currentSession = active.ctx.sessionManager.getSessionFile();
372 if (active.sessionFile && currentSession !== active.sessionFile) {
373 clearPending(undefined);
374 return;
375 }
376
377 const draft = active.ctx.ui.getEditorText().trim();
378 clearPending(undefined);
379
380 if (!draft) {
381 active.ctx.ui.notify("Handoff draft is empty", "warning");
382 return;
383 }
384
385 active.ctx.ui.setEditorText("");
386
387 try {
388 if (active.ctx.isIdle()) {
389 pi.sendUserMessage(draft);
390 } else {
391 pi.sendUserMessage(draft, { deliverAs: "followUp" });
392 }
393 } catch {
394 pi.sendUserMessage(draft);
395 }
396 };
397
398 const startCountdown = (ctx: ExtensionContext) => {
399 clearPending(ctx);
400
401 let seconds = COUNTDOWN_SECONDS;
402 ctx.ui.setStatus(STATUS_KEY, statusLine(ctx, seconds));
403
404 const unsubscribeInput = ctx.ui.onTerminalInput((data) => {
405 if (matchesKey(data, Key.escape)) {
406 clearPending(ctx, "Handoff auto-submit cancelled");
407 return { consume: true };
408 }
409
410 if (isEditableInput(data)) {
411 clearPending(ctx, "Handoff auto-submit stopped (editing)");
412 }
413
414 return undefined;
415 });
416
417 const interval = setInterval(() => {
418 if (!pending) return;
419
420 seconds -= 1;
421 if (seconds <= 0) {
422 autoSubmitDraft();
423 return;
424 }
425
426 ctx.ui.setStatus(STATUS_KEY, statusLine(ctx, seconds));
427 }, 1000);
428
429 pending = {
430 ctx,
431 sessionFile: ctx.sessionManager.getSessionFile(),
432 interval,
433 unsubscribeInput,
434 };
435 };
436
437 pi.on("session_before_switch", (_event, ctx) => {
438 if (pending) clearPending(ctx);
439 });
440
441 pi.on("session_switch", (_event, ctx) => {
442 if (pending) clearPending(ctx);
443 // A proper session switch (e.g. /new) fully resets agent state,
444 // so clear the context filter to avoid hiding new messages.
445 handoffTimestamp = null;
446 });
447
448 pi.on("session_before_fork", (_event, ctx) => {
449 if (pending) clearPending(ctx);
450 });
451
452 pi.on("session_fork", (_event, ctx) => {
453 if (pending) clearPending(ctx);
454 });
455
456 pi.on("session_before_tree", (_event, ctx) => {
457 if (pending) clearPending(ctx);
458 });
459
460 pi.on("session_tree", (_event, ctx) => {
461 if (pending) clearPending(ctx);
462 });
463
464 pi.on("session_shutdown", (_event, ctx) => {
465 if (pending) clearPending(ctx);
466 });
467
468 // --- Tool-path handoff coordination ---
469 //
470 // The /handoff command has ExtensionCommandContext with ctx.newSession()
471 // which does a full agent reset. The handoff tool only gets
472 // ExtensionContext, which lacks newSession(). So the tool stores a
473 // pending handoff and these handlers complete it:
474 //
475 // 1. agent_end: after the agent loop finishes, switch sessions and
476 // send the handoff prompt in the next macrotask
477 // 2. context: filter pre-handoff messages since the low-level session
478 // switch doesn't clear agent.state.messages
479 // 3. session_switch (above): clears the filter on proper switches
480
481 pi.on("agent_end", (_event, ctx) => {
482 if (!pendingHandoff) return;
483
484 const { prompt, parentSession, newModel } = pendingHandoff;
485 pendingHandoff = null;
486
487 handoffTimestamp = Date.now();
488 (ctx.sessionManager as any).newSession({ parentSession });
489
490 setTimeout(async () => {
491 if (newModel) {
492 const slashIdx = newModel.indexOf("/");
493 if (slashIdx > 0) {
494 const provider = newModel.slice(0, slashIdx);
495 const modelId = newModel.slice(slashIdx + 1);
496 const model = ctx.modelRegistry.find(provider, modelId);
497 if (model) await pi.setModel(model);
498 }
499 }
500 pi.sendUserMessage(prompt);
501 }, 0);
502 });
503
504 pi.on("context", (event) => {
505 if (handoffTimestamp === null) return;
506
507 const newMessages = (event as any).messages.filter((m: any) => m.timestamp >= handoffTimestamp);
508 if (newMessages.length > 0) {
509 return { messages: newMessages };
510 }
511 });
512
513 pi.registerTool({
514 name: "session_query",
515 label: (params) => `Session Query: ${params.question}`,
516 description:
517 "Query a prior pi session file. Use when handoff prompt references a parent session and you need details.",
518 parameters: Type.Object({
519 sessionPath: Type.String({
520 description:
521 "Session .jsonl path. Absolute path, or relative to sessions root (e.g. 2026-02-16/foo/session.jsonl)",
522 }),
523 question: Type.String({ description: "Question about that session" }),
524 }),
525 async execute(_toolCallId, params, signal, onUpdate, ctx) {
526 const currentSessionFile = ctx.sessionManager.getSessionFile();
527 const sessionsRoot = getSessionsRoot(currentSessionFile) ?? getFallbackSessionsRoot();
528 const resolvedPath = normalizeSessionPath(params.sessionPath, sessionsRoot);
529
530 const error = (text: string) => ({
531 content: [{ type: "text" as const, text }],
532 details: { error: true },
533 });
534
535 const cancelled = () => ({
536 content: [{ type: "text" as const, text: "Session query cancelled." }],
537 details: { cancelled: true },
538 });
539
540 if (signal.aborted) {
541 return cancelled();
542 }
543
544 if (!resolvedPath.endsWith(".jsonl")) {
545 return error(`Invalid session path (expected .jsonl): ${params.sessionPath}`);
546 }
547
548 if (!sessionPathAllowed(resolvedPath, sessionsRoot)) {
549 return error(`Session path outside allowed sessions directory: ${params.sessionPath}`);
550 }
551
552 if (!fs.existsSync(resolvedPath)) {
553 return error(`Session file not found: ${resolvedPath}`);
554 }
555
556 let fileStats: fs.Stats;
557 try {
558 fileStats = fs.statSync(resolvedPath);
559 } catch (err) {
560 return error(`Failed to stat session file: ${String(err)}`);
561 }
562
563 if (!fileStats.isFile()) {
564 return error(`Session path is not a file: ${resolvedPath}`);
565 }
566
567 onUpdate?.({
568 content: [{ type: "text", text: `Querying: ${resolvedPath}` }],
569 details: { status: "loading", sessionPath: resolvedPath },
570 });
571
572 let sessionManager: SessionManager;
573 try {
574 sessionManager = SessionManager.open(resolvedPath);
575 } catch (err) {
576 return error(`Failed to open session: ${String(err)}`);
577 }
578
579 const branch = sessionManager.getBranch();
580 const messages = branch
581 .filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
582 .map((entry) => entry.message);
583
584 if (messages.length === 0) {
585 return {
586 content: [{ type: "text" as const, text: "Session has no messages." }],
587 details: { empty: true, sessionPath: resolvedPath },
588 };
589 }
590
591 if (!ctx.model) {
592 return error("No model selected for session query.");
593 }
594
595 const conversationText = serializeConversation(convertToLlm(messages));
596 try {
597 const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
598 if (!auth.ok) {
599 return error(`Failed to get API key: ${auth.error}`);
600 }
601 const userMessage: Message = {
602 role: "user",
603 content: [
604 {
605 type: "text",
606 text: `## Session\n\n${conversationText}\n\n## Question\n\n${params.question}`,
607 },
608 ],
609 timestamp: Date.now(),
610 };
611
612 const response = await complete(
613 ctx.model,
614 { systemPrompt: QUERY_SYSTEM_PROMPT, messages: [userMessage] },
615 { apiKey: auth.apiKey, headers: auth.headers, signal },
616 );
617
618 if (response.stopReason === "aborted") {
619 return cancelled();
620 }
621
622 const answer = response.content
623 .filter((c): c is { type: "text"; text: string } => c.type === "text")
624 .map((c) => c.text)
625 .join("\n")
626 .trim();
627
628 return {
629 content: [{ type: "text" as const, text: answer || "No answer generated." }],
630 details: {
631 sessionPath: resolvedPath,
632 question: params.question,
633 messageCount: messages.length,
634 },
635 };
636 } catch (err) {
637 if (signal.aborted) {
638 return cancelled();
639 }
640 if (err instanceof Error && err.name === "AbortError") {
641 return cancelled();
642 }
643 return error(`Session query failed: ${String(err)}`);
644 }
645 },
646 });
647
648 pi.registerTool({
649 name: "handoff",
650 label: "Handoff",
651 description:
652 "Transfer context to a new session. Use when the user explicitly asks for a handoff or when the context window is nearly full. Provide a goal describing what the new session should focus on.",
653 parameters: Type.Object({
654 goal: Type.String({
655 description: "The goal/task for the new session",
656 }),
657 model: Type.Optional(
658 Type.String({
659 description: "Model for the new session as provider/modelId (e.g. 'anthropic/claude-haiku-4-5')",
660 }),
661 ),
662 }),
663 async execute(_toolCallId, params, signal, _onUpdate, ctx) {
664 if (!ctx.model) {
665 return {
666 content: [{ type: "text" as const, text: "No model selected." }],
667 };
668 }
669
670 const branch = ctx.sessionManager.getBranch();
671 const messages = branch
672 .filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
673 .map((entry) => entry.message);
674
675 if (messages.length === 0) {
676 return {
677 content: [
678 {
679 type: "text" as const,
680 text: "No conversation to hand off.",
681 },
682 ],
683 };
684 }
685
686 const llmMessages = convertToLlm(messages);
687 const conversationText = serializeConversation(llmMessages);
688 const candidateFiles = [...extractCandidateFiles(branch, conversationText)];
689 const loadedSkills = extractLoadedSkills(branch);
690
691 const extractionModel = resolveExtractionModel(ctx) ?? ctx.model;
692 const auth = await ctx.modelRegistry.getApiKeyAndHeaders(extractionModel);
693 if (!auth.ok) {
694 return {
695 content: [
696 {
697 type: "text" as const,
698 text: `Failed to get API key: ${auth.error}`,
699 },
700 ],
701 };
702 }
703
704 let result: HandoffExtraction | null;
705 try {
706 result = await extractHandoffContext(
707 extractionModel,
708 auth.apiKey,
709 auth.headers,
710 conversationText,
711 params.goal,
712 candidateFiles,
713 loadedSkills,
714 signal,
715 );
716 } catch (err) {
717 if (signal.aborted) {
718 return {
719 content: [
720 {
721 type: "text" as const,
722 text: "Handoff cancelled.",
723 },
724 ],
725 };
726 }
727 return {
728 content: [
729 {
730 type: "text" as const,
731 text: `Handoff extraction failed: ${String(err)}`,
732 },
733 ],
734 };
735 }
736
737 if (!result) {
738 return {
739 content: [
740 {
741 type: "text" as const,
742 text: "Handoff extraction failed or was cancelled.",
743 },
744 ],
745 };
746 }
747
748 const currentSessionFile = ctx.sessionManager.getSessionFile();
749 const prompt = assembleHandoffDraft(result, params.goal, currentSessionFile);
750
751 pendingHandoff = {
752 prompt,
753 parentSession: currentSessionFile,
754 newModel: params.model,
755 };
756
757 return {
758 content: [
759 {
760 type: "text" as const,
761 text: "Handoff prepared. The session will switch after this turn completes.",
762 },
763 ],
764 };
765 },
766 });
767
768 pi.registerCommand("handoff", {
769 description: "Transfer context to a new session (-model provider/modelId)",
770 handler: async (args: string, ctx: ExtensionCommandContext) => {
771 if (!ctx.hasUI) {
772 ctx.ui.notify("/handoff requires interactive mode", "error");
773 return;
774 }
775
776 if (!ctx.model) {
777 ctx.ui.notify("No model selected", "error");
778 return;
779 }
780
781 // Parse optional -model flag from args
782 let remaining = args;
783 let newSessionModel: string | undefined;
784
785 const modelMatch = remaining.match(/(?:^|\s)-model\s+(\S+)/);
786 if (modelMatch) {
787 newSessionModel = modelMatch[1];
788 remaining = remaining.replace(modelMatch[0], " ");
789 }
790
791 let goal = remaining.trim();
792 if (!goal) {
793 const entered = await ctx.ui.input("handoff goal", "What should the new thread do?");
794 if (!entered?.trim()) {
795 ctx.ui.notify("Handoff cancelled", "info");
796 return;
797 }
798 goal = entered.trim();
799 }
800
801 const branch = ctx.sessionManager.getBranch();
802 const messages = branch
803 .filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
804 .map((entry) => entry.message);
805
806 if (messages.length === 0) {
807 ctx.ui.notify("No conversation to hand off", "warning");
808 return;
809 }
810
811 const llmMessages = convertToLlm(messages);
812 const conversationText = serializeConversation(llmMessages);
813 const currentSessionFile = ctx.sessionManager.getSessionFile();
814 const candidateFiles = [...extractCandidateFiles(branch, conversationText)];
815 const loadedSkills = extractLoadedSkills(branch);
816 const extractionModel = resolveExtractionModel(ctx) ?? ctx.model;
817
818 const result = await ctx.ui.custom<HandoffExtraction | null>((tui, theme, _kb, done) => {
819 const loader = new BorderedLoader(tui, theme, "Extracting handoff context...");
820 loader.onAbort = () => done(null);
821
822 const run = async () => {
823 const auth = await ctx.modelRegistry.getApiKeyAndHeaders(extractionModel);
824 if (!auth.ok) {
825 throw new Error(`Failed to get API key: ${auth.error}`);
826 }
827
828 return extractHandoffContext(
829 extractionModel,
830 auth.apiKey,
831 auth.headers,
832 conversationText,
833 goal,
834 candidateFiles,
835 loadedSkills,
836 loader.signal,
837 );
838 };
839
840 run()
841 .then(done)
842 .catch((err) => {
843 console.error("handoff generation failed", err);
844 done(null);
845 });
846
847 return loader;
848 });
849
850 if (!result) {
851 ctx.ui.notify("Handoff cancelled", "info");
852 return;
853 }
854
855 const prefillDraft = assembleHandoffDraft(result, goal, currentSessionFile);
856
857 const editedPrompt = await ctx.ui.editor("Edit handoff draft", prefillDraft);
858 if (editedPrompt === undefined) {
859 ctx.ui.notify("Handoff cancelled", "info");
860 return;
861 }
862
863 const next = await ctx.newSession({
864 parentSession: currentSessionFile,
865 });
866
867 if (next.cancelled) {
868 ctx.ui.notify("New session cancelled", "info");
869 return;
870 }
871
872 // Apply -model if specified
873 if (newSessionModel) {
874 const slashIdx = newSessionModel.indexOf("/");
875 if (slashIdx > 0) {
876 const provider = newSessionModel.slice(0, slashIdx);
877 const modelId = newSessionModel.slice(slashIdx + 1);
878 const model = ctx.modelRegistry.find(provider, modelId);
879 if (model) {
880 await pi.setModel(model);
881 } else {
882 ctx.ui.notify(`Unknown model: ${newSessionModel}`, "warning");
883 }
884 } else {
885 ctx.ui.notify(`Invalid model format "${newSessionModel}", expected provider/modelId`, "warning");
886 }
887 }
888
889 const newSessionFile = ctx.sessionManager.getSessionFile();
890 if (newSessionFile) {
891 ctx.ui.notify(`Switched to new session: ${newSessionFile}`, "info");
892 }
893
894 ctx.ui.setEditorText(editedPrompt);
895 startCountdown(ctx);
896 },
897 });
898}