feat: add support for custom compact commands

- Add 'compact' metadata field to Command schema
- Allow users to create custom compact-type commands in .opencode/command/
- Add experimental.autoCompactCommand config to choose which command for auto-compaction
- Default /compact command uses SessionCompaction.DEFAULT_PROMPT
- UI detects compact commands and triggers with custom template
- Users can override /compact by creating their own compact.md command

This enables users to customize the compaction prompt for their specific needs,
such as creating a /handover command with detailed context for team handoffs.

Author: maxeonyx

COMPACT_COMMANDS_ANALYSIS.md

@@ -0,0 +1,211 @@
+# Custom Compact Commands: Analysis & Requirements
+
+## Core Requirements
+
+1. **Shift "/compact" to be implemented in terms of a generic custom "compact"-type command capability, similar to "/init"**
+   - Users should be able to create custom compact commands just like they create custom agents
+   - The mechanism should follow the same pattern as `/init` with custom agents
+
+2. **Users should be able to define such commands in opencode config as markdown files**
+   - Commands defined in `.opencode/command/*.md`
+   - Metadata-driven configuration (frontmatter)
+   - Template-based prompt customization
+
+3. **Example: How to implement "/handover"**
+   - Create `.opencode/command/handover.md`
+   - Use metadata to mark it as a compact-type command
+   - Define custom template for handover-specific summaries
+   - Write this example to globally-ignored directory `config.ignore/command/handover.md` for testing.
+
+4. **Remove all other custom compact prompt changes**
+   - Remove deprecated `compactPrompt` config field
+   - Clean up any legacy compact customization mechanisms
+   - Consolidate to a single, clear pattern
+
+5. **Refactor until minimal possible changes**
+   - Reuse existing patterns and infrastructure
+   - Avoid special-case logic
+   - Keep changes localized and clean
+
+## How `/init` Works (Reference Pattern)
+
+1. `/init` is defined as a regular command with a template
+2. When user types `/init`, autocomplete shows it as an option
+3. User can add custom text after it (e.g., `/init Explain the codebase`)
+4. When submitted, the full text is sent as a normal message
+5. The command's `agent` and `model` fields are used during execution
+6. No special API calls - it follows the standard message flow
+7. The agent processes the message according to its instructions
+
+## Key Architectural Insight
+
+The `/init` pattern works because:
+
+- Commands are just text templates that get inserted into the prompt
+- The `agent` field determines which agent processes the message
+- No special branching or API calls in autocomplete
+- Clean separation: command definition → text insertion → message handling
+
+## Challenges Encountered
+
+### Challenge 1: Initial Implementation Took Wrong Approach
+
+**What Happened:**
+
+- Implemented compact commands with special `compact: boolean` metadata field
+- Added special-case logic in autocomplete to detect compact commands
+- Made compact commands call compaction API directly, bypassing normal flow
+- Created dual mechanisms: global `compactPrompt` config + per-command templates
+
+**Why This Was Wrong:**
+
+- Doesn't follow `/init` pattern (direct API call vs text insertion)
+- Can't accept arguments like `/compact Focus on database changes`
+- Special-case logic breaks architectural consistency
+- Agent and model fields are ignored
+- More complex than the pattern it's supposed to mirror
+
+### Challenge 2: TUI Crash on Startup
+
+**What Happened:**
+
+- Original error: `undefined is not an object (evaluating 'x.data.providers')`
+- Error occurred in `packages/opencode/src/cli/cmd/tui/context/sync.tsx:148`
+- App crashed immediately on startup before even testing compact commands
+
+**Root Cause (from subagent analysis):**
+
+- Race condition during initialization
+- Event listener calling `setStore()` while component is being cleaned up
+- SolidJS reactive graph being torn down during async operations
+- Abort signal shared between event stream and all API calls
+- When event stream aborts, all in-flight API calls fail
+
+**Attempted Fixes Led to Cascading Issues:**
+
+1. Added safe fallbacks (`x.data?.providers ?? []`)
+2. This made agents array empty
+3. App tried to access `agents()[0].name` → crash
+4. Fixed that, then `local.agent.current().name` → crash
+5. Fixed that, but agents being empty breaks fundamental app functionality
+
+**The Deeper Problem:**
+
+- The app fundamentally requires agents to function
+- Safe fallbacks that return empty arrays just move the crash elsewhere
+- The real issue is WHY the API calls are failing in the first place
+- Went down a rabbit hole of fixing symptoms instead of root cause
+
+### Challenge 3: Too Many Changes, Lost Focus
+
+**What Happened:**
+
+- Started with compact command feature
+- Hit unrelated TUI crash
+- Made many changes trying to fix the crash
+- Now have changes across multiple files:
+  - `sync.tsx` - extensive error handling
+  - `sdk.tsx` - exposed abort signal
+  - `local.tsx` - safe agent access
+  - Plus all the compact command changes
+- Lost ability to isolate which changes are for which problem
+
+**The Right Approach Should Have Been:**
+
+1. Test compact command implementation on a working branch first
+2. If crash occurs, isolate it as a separate issue
+3. Fix crash in isolation, verify fix works
+4. Then return to feature implementation
+5. Keep changes minimal and focused
+
+## Key Files Involved in Compact Commands
+
+### Schema/Config Files
+
+- `packages/opencode/src/config/config.ts` - Command schema with `compact` field
+- `packages/opencode/src/command/index.ts` - Command.Info type and default commands
+
+### Execution Files
+
+- `packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx` - Special handling for compact commands
+- `packages/opencode/src/session/system.ts` - Compact prompt customization
+- `packages/opencode/src/session/compaction.ts` - Where compaction actually happens
+
+### SDK
+
+- `packages/sdk/js/src/gen/types.gen.ts` - Generated types including Command and Config
+
+### Example
+
+- `config.ignore/command/handover.md` - Example custom compact command
+
+## Key Files Involved in TUI Crash
+
+### Context Providers
+
+- `packages/opencode/src/cli/cmd/tui/context/sync.tsx` - Main initialization and state sync
+- `packages/opencode/src/cli/cmd/tui/context/sdk.tsx` - SDK client wrapper with abort signal
+- `packages/opencode/src/cli/cmd/tui/context/local.tsx` - Local state including current agent
+
+### Components That Use Agents
+
+- `packages/opencode/src/cli/cmd/tui/app.tsx` - Main app, displays current agent
+- `packages/opencode/src/cli/cmd/tui/component/dialog-agent.tsx` - Agent selection dialog
+- `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx` - Prompt component
+
+## Questions That Need Answers
+
+1. **Why is `/config/providers` returning undefined in the first place?**
+   - Is there a configuration issue?
+   - Is the server not starting properly?
+   - Is there a timing issue?
+
+2. **Should compact commands really call the API directly or should they follow `/init` pattern?**
+   - Direct API call: simpler but inconsistent with `/init`
+   - Text insertion: consistent but requires message routing logic
+
+3. **Where should message routing happen if we follow the `/init` pattern?**
+   - At message send time?
+   - In the session handler?
+   - Via a special compact agent?
+
+4. **What is the minimal set of changes needed?**
+   - Can we reuse more existing infrastructure?
+   - What can be deleted vs added?
+
+## Recommended Next Steps
+
+1. **Reset branch to clean state**
+   - Start fresh from `dev` branch
+   - Clear separation between feature work and bug fixes
+
+2. **First: Verify `/config/providers` works on dev branch**
+   - Test that app starts cleanly
+   - Understand why it might fail
+   - Fix any startup issues in isolation
+
+3. **Second: Design the right compact command approach**
+   - Decide: direct API call vs `/init` pattern
+   - Document the architecture before coding
+   - Identify exactly which files need changes
+
+4. **Third: Implement incrementally**
+   - One change at a time
+   - Test after each change
+   - Keep diff minimal
+
+5. **Fourth: Test thoroughly**
+   - Verify `/compact` still works
+   - Test custom compact commands
+   - Ensure no regressions
+
+## Success Criteria
+
+- [ ] User can create `.opencode/command/handover.md` with custom compact template
+- [ ] `/handover` command works like `/compact` but with custom template
+- [ ] Implementation follows same pattern as `/init` with custom agents
+- [ ] No deprecated `compactPrompt` config field
+- [ ] Minimal code changes (additions are localized, deletions exceed additions)
+- [ ] No special-case logic in autocomplete
+- [ ] App starts without crashing
+- [ ] All existing compact functionality preserved

packages/opencode/_console_1762985501455.log

@@ -0,0 +1,9 @@
+[11:11:38] [ERROR] Error: undefined is not an object (evaluating 'x.data.providers')
+Error: undefined is not an object (evaluating 'x.data.providers')
+    at <anonymous> (/home/mclarke/opencode/packages/opencode/src/cli/cmd/tui/context/sync.tsx:148:81)
+    at processTicksAndRejections (native)
+
+[11:11:38] [ERROR] Error: undefined is not an object (evaluating 'x.data.providers')
+Error: undefined is not an object (evaluating 'x.data.providers')
+    at <anonymous> (/home/mclarke/opencode/packages/opencode/src/cli/cmd/tui/context/sync.tsx:148:81)
+    at processTicksAndRejections (native)

packages/opencode/src/cli/cmd/tui/component/dialog-command.tsx

@@ -55,10 +55,10 @@ function init() {
   })
 
   const result = {
-    trigger(name: string, source?: "prompt") {
+    trigger(name: string, data?: any) {
       for (const option of options()) {
         if (option.value === name) {
-          option.onSelect?.(dialog, source)
+          option.onSelect?.(dialog, undefined, data)
           return
         }
       }

packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx

@@ -11,6 +11,7 @@ import { useCommandDialog } from "@tui/component/dialog-command"
 import { useTerminalDimensions } from "@opentui/solid"
 import { Locale } from "@/util/locale"
 import type { PromptInfo } from "./history"
+import { SessionCompaction } from "../../../../../session/compaction"
 
 export type AutocompleteRef = {
   onInput: (value: string) => void
@@ -209,20 +210,34 @@ export function Autocomplete(props: {
   const commands = createMemo((): AutocompleteOption[] => {
     const results: AutocompleteOption[] = []
     const s = session()
-    for (const command of sync.data.command) {
-      results.push({
-        display: "/" + command.name,
-        description: command.description,
-        onSelect: () => {
-          const newText = "/" + command.name + " "
-          const cursor = props.input().logicalCursor
-          props.input().deleteRange(0, 0, cursor.row, cursor.col)
-          props.input().insertText(newText)
-          props.input().cursorOffset = Bun.stringWidth(newText)
-        },
-      })
+    for (const cmd of sync.data.command) {
+      if (cmd.compact) {
+        results.push({
+          display: "/" + cmd.name,
+          description: cmd.description ?? "compact the session",
+          onSelect: () => {
+            command.trigger("session.compact", {
+              commandName: cmd.name,
+              template: cmd.template,
+            })
+          },
+        })
+      } else {
+        results.push({
+          display: "/" + cmd.name,
+          description: cmd.description,
+          onSelect: () => {
+            const newText = "/" + cmd.name + " "
+            const cursor = props.input().logicalCursor
+            props.input().deleteRange(0, 0, cursor.row, cursor.col)
+            props.input().insertText(newText)
+            props.input().cursorOffset = Bun.stringWidth(newText)
+          },
+        })
+      }
     }
     if (s) {
+      const hasCompactCommand = sync.data.command.some((c) => c.name === "compact")
       results.push(
         {
           display: "/undo",
@@ -236,12 +251,20 @@ export function Autocomplete(props: {
           description: "redo the last message",
           onSelect: () => command.trigger("session.redo"),
         },
-        {
-          display: "/compact",
-          aliases: ["/summarize"],
-          description: "compact the session",
-          onSelect: () => command.trigger("session.compact"),
-        },
+        ...(!hasCompactCommand
+          ? [
+              {
+                display: "/compact",
+                aliases: ["/summarize"],
+                description: "compact the session",
+                onSelect: () =>
+                  command.trigger("session.compact", {
+                    commandName: "compact",
+                    template: SessionCompaction.DEFAULT_PROMPT,
+                  }),
+              },
+            ]
+          : []),
         {
           display: "/unshare",
           disabled: !s.share,