toenobu-agent 0.2.0 → 0.2.1

package/.pi/research-handoff.md

@@ -0,0 +1,64 @@
+Here's a thorough analysis of the `handoff.ts` extension:
+
+---
+
+## 📋 Summary: `handoff.ts` Extension
+
+### 1. What It Does
+
+**Handoff** is a session-transfer extension for a coding agent (part of the `pi-mono` monorepo). Its purpose is to **intelligently transfer context from one conversation session to a new, focused one** — without the information loss that comes with simple context compaction.
+
+When you invoke `/handoff <goal>`, it:
+1. Reads the current conversation history
+2. Uses an LLM to generate a concise, self-contained "handoff prompt" summarizing relevant context + your stated goal
+3. Lets you **edit the generated prompt** before committing
+4. Creates a **new session** (with a reference to the parent session)
+5. Pre-fills the editor with the prompt, ready for submission
+
+---
+
+### 2. Key Features & Functionality
+
+| Feature | Details |
+|---|---|
+| **`/handoff <goal>` command** | Registered via `pi.registerCommand("handoff", ...)` |
+| **LLM-powered summarization** | Calls `complete()` with a carefully crafted system prompt to distill the conversation |
+| **Structured output format** | Generated prompt follows a `## Context / ## Task` format — concise but self-contained |
+| **Abortable loader UI** | Shows a `BorderedLoader` while generating; supports abort/cancel mid-flight via `AbortSignal` |
+| **Interactive prompt editing** | Opens an editor UI (`ctx.ui.editor(...)`) for the user to refine the generated prompt before proceeding |
+| **Parent session tracking** | New session is created with `parentSession` linked to the current one, preserving lineage |
+| **Error handling** | Guards for: no UI, no model, empty goal, empty conversation, auth failures, generation failures, user cancellations |
+
+---
+
+### 3. Dependencies & Requirements
+
+**Runtime Dependencies:**
+- `@mariozechner/pi-ai` — provides `complete()` (LLM call) and the `Message` type
+- `@mariozechner/pi-coding-agent` — provides:
+  - `ExtensionAPI` / `SessionEntry` — extension host contract
+  - `BorderedLoader` — terminal UI loading indicator
+  - `convertToLlm` / `serializeConversation` — conversation format utilities
+
+**Runtime Requirements:**
+- Must run in **interactive (UI) mode** — `ctx.hasUI` is checked first
+- A **model must be selected** (`ctx.model`)
+- A valid **API key** must be available via `ctx.modelRegistry.getApiKeyAndHeaders()`
+- An existing **non-empty conversation** to hand off
+
+---
+
+### 4. Implementation Complexity
+
+**Overall: Low-to-Medium** ⚙️
+
+| Aspect | Assessment |
+|---|---|
+| **Code size** | ~130 lines — compact and focused |
+| **Control flow** | Linear with clear early-exit guards; async/await throughout |
+| **LLM integration** | Single `complete()` call with a static system prompt — no streaming, no multi-turn |
+| **UI interaction** | Uses 3 UI primitives: `custom()` (loader), `editor()`, `setEditorText()` — all provided by the host |
+| **State management** | Minimal — reads session branch, creates a new session, no persistent state |
+| **Error paths** | Well-handled (null checks, try/catch, cancellation signals) |
+
+The extension is a clean example of the **extension pattern** in `pi-coding-agent`: it relies heavily on the host `ExtensionAPI` for UI, auth, and session management, keeping its own logic thin — just orchestrating a generate → edit → create-session → pre-fill workflow.

package/.pi/todos/49a97d86.md

@@ -0,0 +1,40 @@
+{
+  "id": "49a97d86",
+  "title": "Implement handoff extension for session context transfer",
+  "tags": [
+    "extension",
+    "feature",
+    "pi",
+    "high-priority"
+  ],
+  "status": "completed",
+  "created_at": "2026-03-29T12:10:10.662Z",
+  "assigned_to_session": "e5898ce7-3b44-45b0-b50e-f8273d6419a4"
+}
+
+## Overview
+Create a 1:1 copy of the [pi-mono handoff.ts](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/examples/extensions/handoff.ts) extension.
+
+**Priority:** High
+
+## Implementation Steps
+1. **Setup dependencies** — Add `@mariozechner/pi-coding-agent` and `@mariozechner/pi-ai` to the project
+2. **Create extension folder** — `./extensions/`
+3. **Implement `handoff.ts`** — Copy reference implementation with:
+   - `/handoff <goal>` command
+   - LLM-powered conversation summarization
+   - `## Context` / `## Task` output format
+   - BorderedLoader UI + editor flow
+   - Parent session linking
+
+## Acceptance Criteria
+- [x] Dependencies installed
+- [x] `./extensions/handoff.ts` created
+- [x] `/handoff <goal>` command works in interactive mode
+- [x] Generates summarized context via LLM
+- [x] Opens editor for prompt refinement
+- [x] Creates new session with parent linkage
+
+## Reference
+- Source: https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/examples/extensions/handoff.ts
+- Analysis: `.pi/research-handoff.md`

package/.pi/todos/67d010fe.md

@@ -0,0 +1,11 @@
+{
+  "id": "67d010fe",
+  "title": "Delete skills/code-simplifier/",
+  "tags": [],
+  "status": "done",
+  "created_at": "2026-03-29T12:26:00.760Z"
+}
+
+Remove the unused code-simplifier skill from this project.
+
+Path: `skills/code-simplifier/`

package/Makefile

@@ -19,3 +19,7 @@ major:
 # Publish toenobu-agent
 publish:
 	npm publish
+
+#
+install:
+	npm install

package/extensions/handoff.ts

@@ -0,0 +1,153 @@
+/**
+ * Handoff extension - transfer context to a new focused session
+ *
+ * Instead of compacting (which is lossy), handoff extracts what matters
+ * for your next task and creates a new session with a generated prompt.
+ *
+ * Usage:
+ *   /handoff now implement this for teams as well
+ *   /handoff execute phase one of the plan
+ *   /handoff check other places that need this fix
+ *
+ * The generated prompt appears as a draft in the editor for review/editing.
+ */
+
+import { complete, type Message } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, SessionEntry } from "@mariozechner/pi-coding-agent";
+import { BorderedLoader, convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
+
+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:
+
+1. Summarizes relevant context from the conversation (decisions made, approaches taken, key findings)
+2. Lists any relevant files that were discussed or modified
+3. Clearly states the next task based on the user's goal
+4. Is self-contained - the new thread should be able to proceed without the old conversation
+
+Format your response as a prompt the user can send to start the new thread. Be concise but include all necessary context. Do not include any preamble like "Here's the prompt" - just output the prompt itself.
+
+Example output format:
+## Context
+We've been working on X. Key decisions:
+- Decision 1
+- Decision 2
+
+Files involved:
+- path/to/file1.ts
+- path/to/file2.ts
+
+## Task
+[Clear description of what to do next based on user's goal]`;
+
+export default function (pi: ExtensionAPI) {
+	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 auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model!);
+					if (!auth.ok || !auth.apiKey) {
+						throw new Error(auth.ok ? `No API key for ${ctx.model!.provider}` : auth.error);
+					}
+
+					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: auth.apiKey, headers: auth.headers, 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;
+			}
+
+			// Let user edit the generated prompt
+			const editedPrompt = await ctx.ui.editor("Edit handoff prompt", result);
+
+			if (editedPrompt === undefined) {
+				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;
+			}
+
+			// Set the edited prompt in the main editor for submission
+			ctx.ui.setEditorText(editedPrompt);
+			ctx.ui.notify("Handoff ready. Submit when ready.", "info");
+		},
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toenobu-agent",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "toenobu's pi coding agent skills and extensions",
   "repository": {
     "type": "git",
@@ -15,10 +15,14 @@
   "pi": {
     "skills": [
       "./skills"
+    ],
+    "extensions": [
+      "./extensions"
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*"
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-ai": "*"
   },
   "license": "MIT"
 }

package/skills/code-simplifier/SKILL.md

@@ -1,44 +0,0 @@
----
-description: Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality
----
-
-# Code Simplifier
-
-Use this skill when the user asks to simplify, refine, or clean up code.
-
-## Instructions
-
-You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality.
-
-Analyze the code and apply refinements that:
-
-1. **Preserve Functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
-
-2. **Enhance Clarity**: Simplify code structure by:
-   - Reducing unnecessary complexity and nesting
-   - Eliminating redundant code and abstractions
-   - Improving readability through clear variable and function names
-   - Consolidating related logic
-   - Removing unnecessary comments that describe obvious code
-   - Avoid nested ternary operators - prefer switch statements or if/else chains
-   - Choose clarity over brevity - explicit code is often better than overly compact code
-
-3. **Maintain Balance**: Avoid over-simplification that could:
-   - Reduce code clarity or maintainability
-   - Create overly clever solutions that are hard to understand
-   - Combine too many concerns into single functions
-   - Prioritize "fewer lines" over readability
-
-4. **Apply Best Practices**:
-   - Follow project coding standards from AGENTS.md/CLAUDE.md if present
-   - Use proper error handling patterns
-   - Maintain consistent naming conventions
-   - Use appropriate language idioms
-
-## Process
-
-1. Identify the code sections to simplify
-2. Analyze for opportunities to improve elegance and consistency
-3. Apply best practices and coding standards
-4. Ensure all functionality remains unchanged
-5. Verify the refined code is simpler and more maintainable