opencode-handoff 0.1.0 → 0.3.0

package/README.md

@@ -9,6 +9,7 @@ Inspired by Amp's handoff command - see their [post](https://ampcode.com/news/ha
 - `/handoff <goal>` command that analyzes the conversation and generates a continuation prompt
 - Guides the AI to include relevant `@file` references so the next session starts with context loaded
 - Opens a new session with the prompt as an editable draft
+- `read_session` tool for retrieving full conversation transcripts from previous sessions when the handoff summary isn't sufficient
 
 ## Requirements
 
@@ -20,7 +21,7 @@ Add to your OpenCode config (`~/.config/opencode/config.json`):
 
 ```json
 {
-  "plugin": ["opencode-handoff@0.1.0"]
+  "plugin": ["opencode-handoff@0.3.0"]
 }
 ```
 
@@ -53,6 +54,24 @@ ln -sf ~/.config/opencode/opencode-handoff/src/plugin.ts ~/.config/opencode/plug
 
 The AI analyzes the conversation, extracts key decisions and relevant files, generates a focused prompt, and creates a new session with that prompt ready to edit.
 
+### Reading Previous Session Transcripts
+
+When you use `/handoff`, the generated prompt includes a session reference line:
+
+```
+Continuing work from session sess_01jxyz123. When you lack specific information you can use read_session to get it.
+```
+
+This gives the AI in the new session access to the `read_session` tool, which can fetch the full conversation transcript from the source session. If the handoff summary doesn't include something you need, just ask - the AI can look it up.
+
+**Example:**
+
+```
+You: What were the specific error messages we saw earlier?
+```
+
+The AI will use `read_session` to retrieve details from the previous session that weren't included in the handoff summary.
+
 ## Contributing
 
 Contributions are welcome! Here's how to set up for development:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-handoff",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Create focused handoff prompts for continuing work in new OpenCode sessions",
   "author": "Josh Thomas <josh@joshthomas.dev>",

package/src/files.ts

@@ -0,0 +1,66 @@
+/**
+ * File reference parsing and building for handoff sessions.
+ *
+ * Handles extraction of @file references from handoff prompts and
+ * building file parts for injection into new sessions.
+ */
+
+import * as path from "node:path"
+import * as fs from "node:fs/promises"
+import type { FilePartInput } from "@opencode-ai/sdk"
+
+/**
+ * File reference regex matching OpenCode's internal pattern.
+ * Matches @file references like @src/plugin.ts
+ */
+export const FILE_REGEX = /(?<![\w`])@(\.?[^\s`,.]*(?:\.[^\s`,.]+)*)/g
+
+/**
+ * Parse @file references from text.
+ *
+ * @param text - Text to search for @file references
+ * @returns Set of file paths referenced in the text
+ */
+export function parseFileReferences(text: string): Set<string> {
+  const fileRefs = new Set<string>()
+
+  for (const match of text.matchAll(FILE_REGEX)) {
+    if (match[1]) {
+      fileRefs.add(match[1])
+    }
+  }
+
+  return fileRefs
+}
+
+/**
+ * Build file parts for files that exist.
+ *
+ * @param directory - Project directory to resolve relative paths against
+ * @param refs - Set of file path references to check
+ * @returns Array of file parts for existing files (non-existent files are skipped)
+ */
+export async function buildFileParts(
+  directory: string,
+  refs: Set<string>
+): Promise<FilePartInput[]> {
+  const fileParts: FilePartInput[] = []
+
+  for (const ref of refs) {
+    const filepath = path.resolve(directory, ref)
+
+    try {
+      await fs.stat(filepath)
+      fileParts.push({
+        type: "file",
+        mime: "text/plain",
+        url: `file://${filepath}`,
+        filename: ref,
+      })
+    } catch {
+      // Skip silently if file doesn't exist
+    }
+  }
+
+  return fileParts
+}

package/src/plugin.ts

@@ -1,69 +1,101 @@
 import type { Plugin } from "@opencode-ai/plugin"
-import { tool } from "@opencode-ai/plugin"
+import { HandoffSession, ReadSession } from "./tools"
+import { parseFileReferences, buildFileParts } from "./files"
 
-export const HandoffPlugin: Plugin = async (ctx) => ({
-  config: async (config) => {
-    config.command = config.command || {}
-    config.command["handoff"] = {
-      description: "Create a focused handoff prompt for a new session",
-      template: `You are creating a handoff message to continue work in a new session.
-
-User's goal: $ARGUMENTS
+const HANDOFF_COMMAND = `GOAL: You are creating a handoff message to continue work in a new session.
 
+<context>
 When an AI assistant starts a fresh session, it spends significant time exploring the codebase—grepping, reading files, searching—before it can begin actual work. This "file archaeology" is wasteful when the previous session already discovered what matters.
 
 A good handoff frontloads everything the next session needs so it can start implementing immediately.
+</context>
 
+<instructions>
 Analyze this conversation and extract what matters for continuing the work.
 
-1. FILE REFERENCES (Required)
-
-   Include all relevant @file references on a SINGLE LINE, space-separated.
-
-   Why: Every @file gets loaded into context automatically. The next session won't need to search—the files are already there. This eliminates exploration entirely.
+1. Identify all relevant files that should be loaded into the next session's context
 
    Include files that will be edited, dependencies being touched, relevant tests, configs, and key reference docs. Be generous—the cost of an extra file is low; missing a critical one means another archaeology dig. Target 8-15 files, up to 20 for complex work.
 
-2. CONTEXT AND GOAL
+2. Draft the context and goal description
 
-   After the files, describe what we're working on and provide whatever context helps continue the work. Structure it based on what fits the conversation—could be tasks, findings, a simple paragraph, or detailed steps.
+   Describe what we're working on and provide whatever context helps continue the work. Structure it based on what fits the conversation—could be tasks, findings, a simple paragraph, or detailed steps.
 
    Preserve: decisions, constraints, user preferences, technical patterns.
 
    Exclude: conversation back-and-forth, dead ends, meta-commentary.
 
 The user controls what context matters. If they mentioned something to preserve, include it—trust their judgment about their workflow.
+</instructions>
+
+<user_input>
+The user's guidance for continuing work. If empty, the handoff should capture a natural continuation of the current conversation's direction.
+
+USER: $ARGUMENTS
+</user_input>
 
 ---
 
-After generating the handoff message, IMMEDIATELY call handoff_prepare with the full message as a handoff prompt:
-\`handoff_prepare(prompt="...")\``,
-    }
-  },
-
-  tool: {
-    handoff_prepare: tool({
-      description: "Prepare handoff by creating new session with generated prompt as draft",
-      args: {
-        prompt: tool.schema.string().describe("The generated handoff prompt"),
-      },
-      async execute(args, context) {
-        await ctx.client.tui.clearPrompt()
-        await ctx.client.tui.executeCommand({ body: { command: "session_new" } })
-        await new Promise(r => setTimeout(r, 200))
-        await ctx.client.tui.appendPrompt({ body: { text: args.prompt } })
-
-        await ctx.client.tui.showToast({
-          body: {
-            title: "Handoff Ready",
-            message: "Review and edit the draft, then send",
-            variant: "success",
-            duration: 4000,
-          }
-        })
-
-        return "Handoff prompt created in new session. Review and edit before sending."
+After generating the handoff message, IMMEDIATELY call handoff_session with your prompt and files:
+\`handoff_session(prompt="...", files=["src/foo.ts", "src/bar.ts", ...])\``
+
+export const HandoffPlugin: Plugin = async (ctx) => {
+  const processedSessions = new Set<string>()
+
+  return {
+    config: async (config) => {
+      config.command = config.command || {}
+      config.command["handoff"] = {
+        description: "Create a focused handoff prompt for a new session",
+        template: HANDOFF_COMMAND,
       }
-    })
+    },
+
+    tool: {
+      handoff_session: HandoffSession(ctx.client),
+      read_session: ReadSession(ctx.client),
+    },
+
+    "chat.message": async (_input, output) => {
+      const sessionID = output.message.sessionID
+
+      if (processedSessions.has(sessionID)) return
+
+      // Get non-synthetic text from the message
+      const text = output.parts
+        .filter((p): p is typeof p & { type: "text"; text: string } =>
+          p.type === "text" && !p.synthetic && typeof p.text === "string"
+        )
+        .map(p => p.text)
+        .join("\n")
+
+      if (!text.includes("Continuing work from session")) return
+
+      processedSessions.add(sessionID)
+
+      const fileRefs = parseFileReferences(text)
+      if (fileRefs.size === 0) return
+
+      const fileParts = await buildFileParts(ctx.directory, fileRefs)
+      if (fileParts.length === 0) return
+
+      // Inject file parts via noReply
+      // Must pass model and agent to prevent mode/model switching
+      await ctx.client.session.prompt({
+        path: { id: sessionID },
+        body: {
+          noReply: true,
+          model: output.message.model,
+          agent: output.message.agent,
+          parts: fileParts,
+        },
+      })
+    },
+
+    event: async ({ event }) => {
+      if (event.type === "session.deleted") {
+        processedSessions.delete(event.properties.info.id)
+      }
+    }
   }
-})
+}

package/src/tools.ts

@@ -0,0 +1,141 @@
+/**
+ * Tool definitions for opencode-handoff plugin.
+ *
+ * Factory functions that create tool definitions with injected dependencies:
+ * - HandoffSession: Create a new session with handoff prompt
+ * - ReadSession: Read conversation transcript from a session
+ */
+
+import type { PluginInput } from "@opencode-ai/plugin"
+import { tool } from "@opencode-ai/plugin"
+
+export type OpencodeClient = PluginInput["client"]
+
+/**
+ * Create the handoff_session tool.
+ *
+ * Takes the OpenCode client as a dependency for TUI and session operations.
+ */
+export const HandoffSession = (client: OpencodeClient) => {
+  return tool({
+    description: "Create a new session with the handoff prompt as an editable draft",
+    args: {
+      prompt: tool.schema.string().describe("The generated handoff prompt"),
+      files: tool.schema.array(tool.schema.string()).optional().describe("Array of file paths to load into the new session's context"),
+    },
+    async execute(args, context) {
+      const sessionReference = `Continuing work from session ${context.sessionID}. When you lack specific information you can use read_session to get it.`
+      const fileRefs = args.files?.length
+        ? args.files.map(f => `@${f.replace(/^@/, '')}`).join(' ')
+        : ''
+      const fullPrompt = fileRefs
+        ? `${sessionReference}\n\n${fileRefs}\n\n${args.prompt}`
+        : `${sessionReference}\n\n${args.prompt}`
+
+      // Double-append workaround for textarea resize bug:
+      // appendPrompt uses insertText() which bypasses onContentChange, so resize never triggers.
+      // First append sets height in old session, session_new preserves textarea element,
+      // second append populates new session with already-expanded textarea.
+      await client.tui.clearPrompt()
+      await new Promise(r => setTimeout(r, 200))
+      await client.tui.appendPrompt({ body: { text: fullPrompt } })
+      await client.tui.executeCommand({ body: { command: "session_new" } })
+      await new Promise(r => setTimeout(r, 200))
+      await client.tui.appendPrompt({ body: { text: fullPrompt } })
+
+      await client.tui.showToast({
+        body: {
+          title: "Handoff Ready",
+          message: "Review and edit the draft, then send",
+          variant: "success",
+          duration: 4000,
+        }
+      })
+
+      return "Handoff prompt created in new session. Review and edit before sending."
+    }
+  })
+}
+
+/**
+ * Format a conversation transcript for display.
+ *
+ * @param messages - Array of messages from session.messages()
+ * @param limit - Optional limit to indicate if results are truncated
+ * @returns Formatted transcript with user/assistant sections
+ */
+function formatTranscript(
+  messages: Array<{ info: any; parts: any[] }>,
+  limit?: number
+): string {
+  const lines: string[] = []
+
+  for (const msg of messages) {
+    if (msg.info.role === "user") {
+      lines.push("## User")
+      for (const part of msg.parts) {
+        if (part.type === "text" && !part.ignored) {
+          lines.push(part.text)
+        }
+        if (part.type === "file") {
+          lines.push(`[Attached: ${part.filename || "file"}]`)
+        }
+      }
+      lines.push("")
+    }
+
+    if (msg.info.role === "assistant") {
+      lines.push("## Assistant")
+      for (const part of msg.parts) {
+        if (part.type === "text") {
+          lines.push(part.text)
+        }
+        if (part.type === "tool" && part.state.status === "completed") {
+          lines.push(`[Tool: ${part.tool}] ${part.state.title}`)
+        }
+      }
+      lines.push("")
+    }
+  }
+
+  const output = lines.join("\n").trim()
+
+  if (messages.length >= (limit ?? 100)) {
+    return output + `\n\n(Showing ${messages.length} most recent messages. Use a higher 'limit' to see more.)`
+  }
+
+  return output + `\n\n(End of session - ${messages.length} messages)`
+}
+
+/**
+ * Create the read_session tool.
+ *
+ * Takes the OpenCode client as a dependency for session.messages() calls.
+ */
+export const ReadSession = (client: OpencodeClient) => {
+  return tool({
+    description: "Read the conversation transcript from a previous session. Use this when you need specific information from the source session that wasn't included in the handoff summary.",
+    args: {
+      sessionID: tool.schema.string().describe("The full session ID (e.g., sess_01jxyz...)"),
+      limit: tool.schema.number().optional().describe("Maximum number of messages to read (defaults to 100, max 500)"),
+    },
+    async execute(args) {
+      const limit = Math.min(args.limit ?? 100, 500)
+
+      try {
+        const response = await client.session.messages({
+          path: { id: args.sessionID },
+          query: { limit }
+        })
+
+        if (!response.data || response.data.length === 0) {
+          return "Session has no messages or does not exist."
+        }
+
+        return formatTranscript(response.data, limit)
+      } catch (error) {
+        return `Could not read session ${args.sessionID}: ${error instanceof Error ? error.message : 'Unknown error'}`
+      }
+    }
+  })
+}