AGENTS.md

1# src/tools/background-task/ — Background Task Tool Wrappers
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
718 files. Tool-layer wrappers for `background_output` and `background_cancel`. Does NOT implement the background execution engine — that lives in `src/features/background-agent/`. This directory provides the LLM-facing tool interface.
8 
9## THREE TOOLS
10 
11| Tool | Factory | Purpose |
12|------|---------|---------|
13| `background_output` | `createBackgroundOutput` | Get results from a running/completed background task |
14| `background_cancel` | `createBackgroundCancel` | Cancel running task(s) |
15| `createBackgroundTask` | internal | Shared factory used by both |
16 
17## KEY FILES
18 
19| File | Purpose |
20|------|---------|
21| `create-background-output.ts` | `background_output` tool: fetch task results by task_id |
22| `create-background-cancel.ts` | `background_cancel` tool: cancel by taskId or all=true |
23| `create-background-task.ts` | Shared tool factory with common params |
24| `clients.ts` | Client interfaces for background output and cancel |
25| `session-messages.ts` | Fetch session messages from OpenCode |
26| `full-session-format.ts` | Format full session output (messages, thinking blocks) |
27| `task-result-format.ts` | Format task result for LLM consumption |
28| `task-status-format.ts` | Format task status (running/completed/error) |
29| `message-dir.ts` | Temp directory for message exchange |
30| `truncate-text.ts` | Truncate large output to fit context |
31| `time-format.ts` | Human-readable duration formatting |
32| `delay.ts` | Polling delay utility |
33| `types.ts` | `BackgroundTaskOptions`, result/status types |
34| `constants.ts` | Timeout defaults, polling intervals |
35 
36## BACKGROUND OUTPUT MODES
37 
38```
39background_output(task_id, block=false)  → check current status/result
40background_output(task_id, block=true)   → wait until complete (timeout default: 120s)
41background_output(task_id, full_session=true) → return full session transcript
42background_output(task_id, message_limit=N) → last N messages only
43background_output(task_id, include_thinking=true) → include thinking blocks
44```
45 
46## RELATIONSHIP TO BACKGROUND ENGINE
47 
48```
49tools/background-task/  ← LLM tool interface
50features/background-agent/  ← execution engine (BackgroundManager)
51```
52 
53`createBackgroundOutput` queries `BackgroundManager.getTask(task_id)` — it does not manage task state.
54