pi-amplike 0.1.2 → 0.2.0

package/README.md

@@ -5,8 +5,10 @@
 ## Features
 
 ### Session Management
-- **`/handoff <goal>`** - Create a new focused session based on the current one with context compacted based on a given goal
-- **`session_query`** tool - The agent in the handed off session automatically gets the ability to query the parent session for context, decisions, or code changes
+- **Handoff** - Create a new focused session with AI-generated context transfer:
+  - **`/handoff <goal>`** command - Manually create a handoff session
+  - **`handoff` tool** - The agent can invoke this when you explicitly request a handoff
+- **`session_query`** tool - The agent in handed-off sessions automatically gets the ability to query the parent session for context, decisions, or code changes
 - Use `/resume` to switch between and navigate handed-off sessions
 
 ### Web Access
@@ -47,19 +49,27 @@ Get an API key at [jina.ai](https://jina.ai/). Even if you charge only the minim
 
 ### Session Handoff
 
-When your conversation gets long or you want to branch off to a focused task:
+When your conversation gets long or you want to branch off to a focused task, you can use handoff in two ways:
 
+**Manual handoff via command:**
 ```
 /handoff now implement this for teams as well
 /handoff execute phase one of the plan
 /handoff check other places that need this fix
 ```
 
-This creates a new session with:
-- Summarized context from the current conversation
-- List of relevant files
+**Agent-invoked handoff:**
+The agent can also initiate a handoff when you explicitly ask for it:
+```
+"Please hand this off to a new session to implement the fix"
+"Create a handoff session to execute phase one"
+```
+
+Both methods create a new session with:
+- AI-generated summary of relevant context from the current conversation
+- List of relevant files that were discussed or modified
 - Clear task description based on your goal
-- Reference to parent session (for later querying)
+- Reference to parent session (accessible via `session_query` tool)
 
 ### Session Navigation
 
@@ -90,8 +100,8 @@ session_query("/path/to/session.jsonl", "What approach was chosen?")
 
 | Component | Type | Description |
 |-----------|------|-------------|
-| [handoff](extensions/handoff.ts) | Extension | `/handoff` command for context transfer |
-| [session-query](extensions/session-query.ts) | Extension | `session_query` tool for the model |
+| [handoff](extensions/handoff.ts) | Extension | `/handoff` command + `handoff` tool for AI-powered context transfer |
+| [session-query](extensions/session-query.ts) | Extension | `session_query` tool for querying parent sessions |
 | [session-query](skills/session-query/) | Skill | Instructions for using the session_query tool |
 | [web-search](skills/web-search/) | Skill | Web search via Jina API |
 | [visit-webpage](skills/visit-webpage/) | Skill | Webpage content extraction |

package/extensions/handoff.ts

@@ -4,6 +4,10 @@
  * Instead of compacting (which is lossy), handoff extracts what matters
  * for your next task and creates a new session with a generated prompt.
  *
+ * Provides both:
+ * - /handoff command: user types `/handoff <goal>`
+ * - handoff tool: agent can call when user explicitly requests a handoff
+ *
  * Usage:
  *   /handoff now implement this for teams as well
  *   /handoff execute phase one of the plan
@@ -13,8 +17,9 @@
  */
 
 import { complete, type Message } from "@mariozechner/pi-ai";
-import type { ExtensionAPI, SessionEntry } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@mariozechner/pi-coding-agent";
 import { BorderedLoader, convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
 
 const SYSTEM_PROMPT = `You are a context transfer assistant. Given a conversation history and the user's goal for a new thread, generate a focused prompt that:
 
@@ -38,114 +43,140 @@ Files involved:
 ## Task
 [Clear description of what to do next based on user's goal]`;
 
+/**
+ * Core handoff logic. Returns an error string on failure, or undefined on success.
+ */
+async function performHandoff(pi: ExtensionAPI, ctx: ExtensionContext, goal: string, fromTool = false): Promise<string | undefined> {
+	if (!ctx.hasUI) {
+		return "Handoff requires interactive mode.";
+	}
+
+	if (!ctx.model) {
+		return "No model selected.";
+	}
+
+	const branch = ctx.sessionManager.getBranch();
+	const messages = branch
+		.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
+		.map((entry) => entry.message);
+
+	if (messages.length === 0) {
+		return "No conversation to hand off.";
+	}
+
+	const llmMessages = convertToLlm(messages);
+	const conversationText = serializeConversation(llmMessages);
+	const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+	// Generate the handoff prompt with loader UI
+	const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+		const loader = new BorderedLoader(tui, theme, `Generating handoff prompt...`);
+		loader.onAbort = () => done(null);
+
+		const doGenerate = async () => {
+			const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+
+			const userMessage: Message = {
+				role: "user",
+				content: [
+					{
+						type: "text",
+						text: `## Conversation History\n\n${conversationText}\n\n## User's Goal for New Thread\n\n${goal}`,
+					},
+				],
+				timestamp: Date.now(),
+			};
+
+			const response = await complete(
+				ctx.model!,
+				{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+				{ apiKey, signal: loader.signal },
+			);
+
+			if (response.stopReason === "aborted") {
+				return null;
+			}
+
+			return response.content
+				.filter((c): c is { type: "text"; text: string } => c.type === "text")
+				.map((c) => c.text)
+				.join("\n");
+		};
+
+		doGenerate()
+			.then(done)
+			.catch((err) => {
+				console.error("Handoff generation failed:", err);
+				done(null);
+			});
+
+		return loader;
+	});
+
+	if (result === null) {
+		return "Handoff cancelled.";
+	}
+
+	// Build the final prompt with user's goal first for easy identification
+	let finalPrompt = result;
+	if (currentSessionFile) {
+		finalPrompt = `${goal}\n\n/skill:session-query\n\n**Parent session:** \`${currentSessionFile}\`\n\n${result}`;
+	} else {
+		finalPrompt = `${goal}\n\n${result}`;
+	}
+
+	// Create new session and send the prompt.
+	// When called from a tool, we must defer the session switch until after
+	// the current turn completes (tool_result is recorded), otherwise the
+	// new session gets a tool_result without a corresponding tool_use block.
+	const sm = ctx.sessionManager as any;
+	const doSwitch = () => {
+		sm.newSession({ parentSession: currentSessionFile });
+		pi.sendUserMessage(finalPrompt, { deliverAs: "followUp" });
+	};
+
+	if (fromTool) {
+		// Defer to next tick so the tool_result is recorded in the OLD session first
+		setTimeout(doSwitch, 0);
+	} else {
+		doSwitch();
+	}
+	return undefined;
+}
+
 export default function (pi: ExtensionAPI) {
+	// /handoff command
 	pi.registerCommand("handoff", {
 		description: "Transfer context to a new focused session",
 		handler: async (args, ctx) => {
-			if (!ctx.hasUI) {
-				ctx.ui.notify("handoff requires interactive mode", "error");
-				return;
-			}
-
-			if (!ctx.model) {
-				ctx.ui.notify("No model selected", "error");
-				return;
-			}
-
 			const goal = args.trim();
 			if (!goal) {
 				ctx.ui.notify("Usage: /handoff <goal for new thread>", "error");
 				return;
 			}
 
-			// Gather conversation context from current branch
-			const branch = ctx.sessionManager.getBranch();
-			const messages = branch
-				.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
-				.map((entry) => entry.message);
-
-			if (messages.length === 0) {
-				ctx.ui.notify("No conversation to hand off", "error");
-				return;
-			}
-
-			// Convert to LLM format and serialize
-			const llmMessages = convertToLlm(messages);
-			const conversationText = serializeConversation(llmMessages);
-			const currentSessionFile = ctx.sessionManager.getSessionFile();
-
-			// Generate the handoff prompt with loader UI
-			const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
-				const loader = new BorderedLoader(tui, theme, `Generating handoff prompt...`);
-				loader.onAbort = () => done(null);
-
-				const doGenerate = async () => {
-					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
-
-					const userMessage: Message = {
-						role: "user",
-						content: [
-							{
-								type: "text",
-								text: `## Conversation History\n\n${conversationText}\n\n## User's Goal for New Thread\n\n${goal}`,
-							},
-						],
-						timestamp: Date.now(),
-					};
-
-					const response = await complete(
-						ctx.model!,
-						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
-						{ apiKey, signal: loader.signal },
-					);
-
-					if (response.stopReason === "aborted") {
-						return null;
-					}
-
-					return response.content
-						.filter((c): c is { type: "text"; text: string } => c.type === "text")
-						.map((c) => c.text)
-						.join("\n");
-				};
-
-				doGenerate()
-					.then(done)
-					.catch((err) => {
-						console.error("Handoff generation failed:", err);
-						done(null);
-					});
-
-				return loader;
-			});
-
-			if (result === null) {
-				ctx.ui.notify("Cancelled", "info");
-				return;
-			}
-
-			// Create new session with parent tracking
-			const newSessionResult = await ctx.newSession({
-				parentSession: currentSessionFile,
-			});
-
-			if (newSessionResult.cancelled) {
-				ctx.ui.notify("New session cancelled", "info");
-				return;
-			}
-
-			// Build the final prompt with user's goal first for easy identification
-			// Format: goal (first line for session preview) → skill → parent ref → context
-			let finalPrompt = result;
-			if (currentSessionFile) {
-				finalPrompt = `${goal}\n\n/skill:session-query\n\n**Parent session:** \`${currentSessionFile}\`\n\n${result}`;
-			} else {
-				// Even without parent session, put goal first
-				finalPrompt = `${goal}\n\n${result}`;
+			const error = await performHandoff(pi, ctx, goal);
+			if (error) {
+				ctx.ui.notify(error, "error");
 			}
+		},
+	});
 
-			// Immediately submit the handoff prompt to start the agent
-			pi.sendUserMessage(finalPrompt);
+	// handoff tool (agent-callable)
+	pi.registerTool({
+		name: "handoff",
+		label: "Handoff",
+		description:
+			"Transfer context to a new focused session. ONLY use this when the user explicitly asks for a handoff. Provide a goal describing what the new session should focus on.",
+		parameters: Type.Object({
+			goal: Type.String({ description: "The goal/task for the new session" }),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const error = await performHandoff(pi, ctx, params.goal, true);
+			return {
+				content: [{ type: "text", text: error ?? "Handoff complete. New session started with the generated prompt." }],
+			};
 		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-amplike",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Pi skills and extensions that provide Amp Code-like workflows (handoff, session query, web search, visit webpage).",
   "license": "MIT",
   "homepage": "https://github.com/pasky/pi-amplike",