Skip to content

Commit 2846ed6

Browse files
authored
t1305: OpenCode upstream issue — stream.delta + stream.aborted plugin hooks (#2152)
* feat: draft OpenCode upstream issue for stream.delta + stream.aborted plugin hooks (t1305) Research completed: reviewed 12+ existing OpenCode issues, processor.ts source, plugin/Hooks interface. No overlap found for streaming-level plugin hooks. Draft includes code sketch, benchmark citations, and design considerations. * feat: create upstream OpenCode issue #14691 for stream.delta + stream.aborted hooks (t1305) Upstream issue: anomalyco/opencode#14691 Proposes two new plugin hooks for processor.ts streaming loop: - stream.delta: observe tokens, optionally abort - stream.aborted: handle abort with retry + steering injection Cites oh-my-pi benchmark data, references processor.ts source, includes code sketch (~30 lines change). No overlap with existing issues.
1 parent 5da6a06 commit 2846ed6

1 file changed

Lines changed: 219 additions & 0 deletions

File tree

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
# t1305: OpenCode Upstream Issue Draft
2+
3+
**Upstream issue created:** https://github.com/anomalyco/opencode/issues/14691
4+
5+
## Target Repository
6+
7+
`anomalyco/opencode` (108k+ stars)
8+
9+
## Issue Title
10+
11+
`[FEATURE]: Plugin hooks for streaming token observation (stream.delta) and abort handling (stream.aborted)`
12+
13+
## Research Summary
14+
15+
### Existing Related Issues (no direct overlap)
16+
17+
| Issue | Title | Relevance |
18+
|-------|-------|-----------|
19+
| #9737 | Expose partial tool arguments during streaming via state.raw | Identifies the exact `tool-input-delta: break` no-op in `processor.ts`. Focuses on UI state, not plugin hooks. |
20+
| #13524 | Refactor: centralize tool plugin hooks + add agent to hook input | Centralizes existing hooks, doesn't add streaming hooks. |
21+
| #12472 | Native Claude Code hooks compatibility (PreToolUse, PostToolUse, Stop) | Maps Claude Code hooks to OpenCode events. No streaming-level hooks. |
22+
| #14451 | Ability to intercept or emulate agent messages in plugins | Message interception, not token-level streaming. |
23+
| #10374 | Allow "aborted" agents to be continued | Abort recovery for subagents, not streaming abort. |
24+
| #8197 | Add retry/re-run capability when operation is aborted | UI retry button, not programmatic abort handling. |
25+
| #13809 | Preserve partial bash output for the model after abort | Partial output preservation, not plugin hooks. |
26+
27+
### Key Finding
28+
29+
The `processor.ts` streaming loop (line ~120) has explicit no-ops for `tool-input-delta` and `tool-input-end`:
30+
31+
```typescript
32+
case "tool-input-delta":
33+
break // Delta discarded
34+
case "tool-input-end":
35+
break // Completion ignored
36+
```
37+
38+
The `text-delta` case accumulates text but has no plugin hook (only `text-end` triggers `experimental.text.complete`).
39+
40+
No existing issue proposes plugin hooks at the streaming token level.
41+
42+
### Existing Hook System
43+
44+
The `Hooks` interface in `packages/plugin/src/index.ts` follows a consistent pattern:
45+
- Input: context object (sessionID, messageID, etc.)
46+
- Output: mutable object the hook can modify
47+
- Triggered via `Plugin.trigger(name, input, output)`
48+
49+
Current hooks: `chat.message`, `chat.params`, `tool.execute.before/after`, `experimental.text.complete`, etc.
50+
51+
## Motivation (from oh-my-pi benchmark data)
52+
53+
Can Boluk's "The Harness Problem" (2026-02-12) demonstrated that harness engineering is the highest-leverage optimization available:
54+
55+
- **15 LLMs improved** by changing only the edit tool format (hashline)
56+
- **5-68% success rate gains** across models (Grok Code Fast 1: 6.7% -> 68.3%)
57+
- **20-61% token reduction** (Grok 4 Fast output tokens dropped 61%)
58+
- **Zero training compute** required
59+
60+
The key insight: the harness (tool layer between model output and workspace) is where most failures happen. Streaming hooks enable a new class of harness optimizations:
61+
62+
1. **TTSR (Time-To-Stream Rules)**: Observe tokens as they stream, detect patterns (e.g., model about to repeat a known mistake), inject corrective steering before the model commits to a bad path
63+
2. **Early abort on waste**: Detect when the model is generating obviously wrong output (wrong language, hallucinated imports, infinite loops) and abort early to save tokens
64+
3. **Real-time observability**: Token-level metrics, latency tracking, pattern detection
65+
66+
## Proposed Hooks
67+
68+
### 1. `stream.delta`
69+
70+
Observe individual streaming tokens/chunks. Optionally signal abort.
71+
72+
```typescript
73+
"stream.delta"?: (
74+
input: {
75+
sessionID: string
76+
messageID: string
77+
partID: string
78+
type: "text" | "reasoning" | "tool-input"
79+
/** For tool-input deltas, the tool name and call ID */
80+
tool?: { name: string; callID: string }
81+
},
82+
output: {
83+
delta: string
84+
/** Set to true to abort the current stream */
85+
abort?: boolean
86+
},
87+
) => Promise<void>
88+
```
89+
90+
**Use cases:**
91+
- TTSR: pattern-match streaming text against rules, abort when a known-bad pattern is detected
92+
- Token counting: real-time token budget enforcement
93+
- UI: progressive rendering of tool inputs (subsumes #9737)
94+
- Observability: TTFT measurement, throughput tracking
95+
96+
### 2. `stream.aborted`
97+
98+
Handle stream abort (whether user-initiated, plugin-initiated, or error-induced). Optionally retry or inject a steering message.
99+
100+
```typescript
101+
"stream.aborted"?: (
102+
input: {
103+
sessionID: string
104+
messageID: string
105+
reason: "user" | "plugin" | "error" | "timeout"
106+
/** Accumulated text so far */
107+
partial: string
108+
/** If plugin-initiated, which plugin triggered the abort */
109+
source?: string
110+
},
111+
output: {
112+
/** Set to true to retry the stream from scratch */
113+
retry?: boolean
114+
/** Inject a user message before retry (steering) */
115+
injectMessage?: string
116+
},
117+
) => Promise<void>
118+
```
119+
120+
**Use cases:**
121+
- TTSR steering: abort detected bad pattern, inject corrective instruction, retry
122+
- Graceful degradation: on timeout, inject "please be more concise" and retry
123+
- Abort analytics: track why streams are aborted, which models/prompts cause issues
124+
- Recovery: preserve partial output context for the retry attempt
125+
126+
## Code Sketch: Changes to processor.ts
127+
128+
The change is modest -- ~30 lines added to the existing streaming loop:
129+
130+
```typescript
131+
// In processor.ts, within the for-await-of stream.fullStream loop:
132+
133+
case "text-delta":
134+
if (currentText) {
135+
// NEW: trigger stream.delta hook
136+
const deltaOutput = await Plugin.trigger(
137+
"stream.delta",
138+
{
139+
sessionID: input.sessionID,
140+
messageID: input.assistantMessage.id,
141+
partID: currentText.id,
142+
type: "text",
143+
},
144+
{ delta: value.text },
145+
)
146+
if (deltaOutput.abort) {
147+
// Record abort reason and break out of stream
148+
abortReason = "plugin"
149+
break
150+
}
151+
152+
currentText.text += deltaOutput.delta
153+
// ... existing updatePartDelta logic
154+
}
155+
break
156+
157+
case "tool-input-delta":
158+
// NEW: instead of `break`, accumulate and trigger hook
159+
const toolMatch = toolcalls[value.id]
160+
if (toolMatch && toolMatch.state.status === "pending") {
161+
const deltaOutput = await Plugin.trigger(
162+
"stream.delta",
163+
{
164+
sessionID: input.sessionID,
165+
messageID: input.assistantMessage.id,
166+
partID: toolMatch.id,
167+
type: "tool-input",
168+
tool: { name: toolMatch.tool, callID: value.id },
169+
},
170+
{ delta: value.delta },
171+
)
172+
if (deltaOutput.abort) {
173+
abortReason = "plugin"
174+
break
175+
}
176+
// Accumulate raw (also addresses #9737)
177+
await Session.updatePart({
178+
...toolMatch,
179+
state: {
180+
...toolMatch.state,
181+
raw: (toolMatch.state.raw || "") + deltaOutput.delta,
182+
},
183+
})
184+
}
185+
break
186+
187+
// After the stream loop, before error handling:
188+
if (abortReason) {
189+
const abortOutput = await Plugin.trigger(
190+
"stream.aborted",
191+
{
192+
sessionID: input.sessionID,
193+
messageID: input.assistantMessage.id,
194+
reason: abortReason,
195+
partial: currentText?.text ?? "",
196+
},
197+
{ retry: false, injectMessage: undefined },
198+
)
199+
if (abortOutput.retry) {
200+
if (abortOutput.injectMessage) {
201+
// Inject steering message as user input before retry
202+
await Session.addUserMessage(input.sessionID, abortOutput.injectMessage)
203+
}
204+
continue // Re-enter the while(true) loop
205+
}
206+
}
207+
```
208+
209+
## Design Considerations
210+
211+
1. **Performance**: `Plugin.trigger` is already called in the hot path (`text-end`). Adding it to `text-delta` adds per-token overhead. Mitigation: only invoke if any loaded plugin registers the hook (check at plugin load time, not per-token).
212+
213+
2. **Backward compatibility**: Plugins that don't register these hooks see zero change. The `output.abort` default is `undefined` (falsy), so existing behavior is preserved.
214+
215+
3. **Subsumes #9737**: The `tool-input-delta` handling naturally accumulates `state.raw`, which is exactly what #9737 requests.
216+
217+
4. **Complements #12472**: Claude Code's `PreToolUse`/`PostToolUse` map to `tool.execute.before/after`. These new hooks cover the streaming phase that Claude Code doesn't expose at all -- making OpenCode's plugin system strictly more capable.
218+
219+
5. **Complements #13524**: The centralized hook dispatch from #13524 would naturally include these new hooks.

0 commit comments

Comments
 (0)