opencode-acp-client 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/README.md +220 -2
- package/README.zh.md +199 -0
- package/dist/acp/capabilities.d.ts +168 -0
- package/dist/acp/capabilities.js +240 -0
- package/dist/acp/capabilities.js.map +1 -0
- package/dist/acp/client.d.ts +241 -0
- package/dist/acp/client.js +767 -0
- package/dist/acp/client.js.map +1 -0
- package/dist/acp/types.d.ts +228 -0
- package/dist/acp/types.js +23 -0
- package/dist/acp/types.js.map +1 -0
- package/dist/acp-replay.d.ts +60 -0
- package/dist/acp-replay.js +188 -0
- package/dist/acp-replay.js.map +1 -0
- package/dist/contract.d.ts +435 -0
- package/dist/contract.js +126 -0
- package/dist/contract.js.map +1 -0
- package/dist/daemons.d.ts +39 -0
- package/dist/daemons.js +112 -0
- package/dist/daemons.js.map +1 -0
- package/dist/index.d.ts +268 -0
- package/dist/index.js +1882 -0
- package/dist/index.js.map +1 -0
- package/dist/opencode-bin.d.ts +73 -0
- package/dist/opencode-bin.js +109 -0
- package/dist/opencode-bin.js.map +1 -0
- package/dist/project.d.ts +81 -0
- package/dist/project.js +230 -0
- package/dist/project.js.map +1 -0
- package/dist/server.d.ts +743 -0
- package/dist/server.js +5029 -0
- package/dist/server.js.map +1 -0
- package/dist/session-map.d.ts +89 -0
- package/dist/session-map.js +305 -0
- package/dist/session-map.js.map +1 -0
- package/dist/sessions-command.d.ts +70 -0
- package/dist/sessions-command.js +188 -0
- package/dist/sessions-command.js.map +1 -0
- package/dist/sse.d.ts +40 -0
- package/dist/sse.js +147 -0
- package/dist/sse.js.map +1 -0
- package/dist/state.d.ts +161 -0
- package/dist/state.js +135 -0
- package/dist/state.js.map +1 -0
- package/dist/subagent-sessions.d.ts +71 -0
- package/dist/subagent-sessions.js +107 -0
- package/dist/subagent-sessions.js.map +1 -0
- package/dist/translate/events.d.ts +231 -0
- package/dist/translate/events.js +1244 -0
- package/dist/translate/events.js.map +1 -0
- package/dist/upgrade.d.ts +56 -0
- package/dist/upgrade.js +162 -0
- package/dist/upgrade.js.map +1 -0
- package/package.json +66 -4
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ACP → opencode event translation.
|
|
3
|
+
*
|
|
4
|
+
* This is the layer that decides *how the conversation looks*. ACP speaks in
|
|
5
|
+
* coarse "chunks" and tool calls; opencode renders messages made of typed
|
|
6
|
+
* parts. Getting this wrong does not throw — the agent streams happily and the
|
|
7
|
+
* UI simply stays empty — so it is worth reading carefully.
|
|
8
|
+
*
|
|
9
|
+
* Translation rules, and why:
|
|
10
|
+
*
|
|
11
|
+
* agent_message_chunk → append to a `text` part, emit `message.part.delta`
|
|
12
|
+
* followed by `message.part.updated` (the TUI uses the
|
|
13
|
+
* delta for streaming and the full part on re-render).
|
|
14
|
+
* agent_thought_chunk → same, as a `reasoning` part. Closing it matters:
|
|
15
|
+
* a never-closed reasoning part is a spinner that
|
|
16
|
+
* never stops.
|
|
17
|
+
* tool_call / _update → one `tool` part per `toolCallId`, status mapped from
|
|
18
|
+
* ACP's free-form status strings.
|
|
19
|
+
* plan → logged only; opencode v2 has no todo surface
|
|
20
|
+
* rather than a wall of text.
|
|
21
|
+
* user_message_chunk → dropped. The bridge already appended the user's
|
|
22
|
+
* message when `/prompt` was called; echoing it again
|
|
23
|
+
* duplicates the bubble.
|
|
24
|
+
*
|
|
25
|
+
* Anything unrecognised is ignored *by design* but logged, so a new ACP agent
|
|
26
|
+
* feature shows up as a log line instead of silence.
|
|
27
|
+
*/
|
|
28
|
+
import type { BridgeEvent, Location } from '../contract.js';
|
|
29
|
+
import type { BridgeState, SessionRecord } from '../state.js';
|
|
30
|
+
import { type SessionUpdate } from '../acp/types.js';
|
|
31
|
+
import { type ChildSessionEvent } from '../subagent-sessions.js';
|
|
32
|
+
export interface TranslateSink {
|
|
33
|
+
emit(event: Omit<BridgeEvent, 'id' | 'created'> & {
|
|
34
|
+
created?: number;
|
|
35
|
+
}): BridgeEvent;
|
|
36
|
+
}
|
|
37
|
+
/** Mirrors the single agent `/api/agent` advertises (ACP has no agent list). */
|
|
38
|
+
export declare class AcpTranslator {
|
|
39
|
+
private readonly state;
|
|
40
|
+
private readonly sink;
|
|
41
|
+
private readonly location;
|
|
42
|
+
private readonly log;
|
|
43
|
+
/** `initialize`'s `agentInfo.name`; opencode wants a name, not ours to invent. */
|
|
44
|
+
private agentName;
|
|
45
|
+
/**
|
|
46
|
+
* Called when the AGENT announces a title (`session_info_update`). The bridge
|
|
47
|
+
* persists it: the title is bidirectional (derived, agent, user), and the map must
|
|
48
|
+
* hold the latest name so a restore shows it. Optional so the translator stays
|
|
49
|
+
* usable without a map (tests).
|
|
50
|
+
*/
|
|
51
|
+
private readonly onTitle?;
|
|
52
|
+
/** Per session+message+kind cursor for the currently open streaming part. */
|
|
53
|
+
private readonly openParts;
|
|
54
|
+
/** Latest ACP usage per session, replayed on `session.step.ended`. */
|
|
55
|
+
private readonly lastTokens;
|
|
56
|
+
/** Context window the agent reported (`usage_update.size`), per session. */
|
|
57
|
+
private readonly lastContextSize;
|
|
58
|
+
/** Cumulative session cost, USD only (see applyUsage). */
|
|
59
|
+
private readonly lastCost;
|
|
60
|
+
/** toolCallId → part id, so updates target the same card. */
|
|
61
|
+
private toolNames;
|
|
62
|
+
private toolInputs;
|
|
63
|
+
private readonly toolParts;
|
|
64
|
+
/**
|
|
65
|
+
* Delegated runs per root session: the child's progress and the card that reports it.
|
|
66
|
+
* Fed by `opencode/session/child_update`; see `applyChildUpdate`.
|
|
67
|
+
*/
|
|
68
|
+
private readonly children;
|
|
69
|
+
/** The `task` card each child belongs to, and the description the agent gave it. */
|
|
70
|
+
private readonly childCards;
|
|
71
|
+
/**
|
|
72
|
+
* The metadata a `task` card must keep. `session.tool.success` rewrites a row's metadata
|
|
73
|
+
* from `toolMetadata(update)` — which is `{}` for an ACP frame with no `rawOutput.metadata`
|
|
74
|
+
* — so the delegated run's state would be wiped the moment the card completes, taking the
|
|
75
|
+
* client's `Background` badge with it. Merged back in at that point.
|
|
76
|
+
*/
|
|
77
|
+
private readonly childMeta;
|
|
78
|
+
/** Provisional assistant message id per session for the current turn. */
|
|
79
|
+
private readonly activeMessage;
|
|
80
|
+
/** Assistant rows whose `session.step.started` has been emitted. */
|
|
81
|
+
private readonly stepEmitted;
|
|
82
|
+
/** Prompt dispatch time per session, used as the step's `started`. */
|
|
83
|
+
private readonly turnStartedAt;
|
|
84
|
+
constructor(state: BridgeState, sink: TranslateSink, location: Location, log?: (line: string) => void,
|
|
85
|
+
/** `initialize`'s `agentInfo.name`; opencode wants a name, not ours to invent. */
|
|
86
|
+
agentName?: string,
|
|
87
|
+
/**
|
|
88
|
+
* Called when the AGENT announces a title (`session_info_update`). The bridge
|
|
89
|
+
* persists it: the title is bidirectional (derived, agent, user), and the map must
|
|
90
|
+
* hold the latest name so a restore shows it. Optional so the translator stays
|
|
91
|
+
* usable without a map (tests).
|
|
92
|
+
*/
|
|
93
|
+
onTitle?: ((record: SessionRecord) => void) | undefined);
|
|
94
|
+
/**
|
|
95
|
+
* Name the agent on rows created from now on.
|
|
96
|
+
*
|
|
97
|
+
* Needed because a translator can be created BEFORE its agent: a turn that could
|
|
98
|
+
* not start still renders its own failure, and it has no `agentInfo.name` to use
|
|
99
|
+
* yet (it reports the placeholder). Without this, every later row in that session
|
|
100
|
+
* — after a retry succeeded — kept saying `acp` in the footer instead of the
|
|
101
|
+
* agent's real name.
|
|
102
|
+
*/
|
|
103
|
+
/**
|
|
104
|
+
* Fold one event of a delegated run into the card that reports it.
|
|
105
|
+
*
|
|
106
|
+
* Two slots, both measured against opencode's `Subagent` component:
|
|
107
|
+
* • the caption — `input.description`, re-sent with `session.tool.called`, because the
|
|
108
|
+
* row's title is the only free text the client renders;
|
|
109
|
+
* • the `Background` badge — `metadata.status`, sent with `session.tool.progress`.
|
|
110
|
+
* The client shows it when the card is `completed` while `metadata.status` is
|
|
111
|
+
* `running` (`isBackgroundSubagent`), which is exactly a delegated run that
|
|
112
|
+
* returned its card and kept working.
|
|
113
|
+
*
|
|
114
|
+
* The card is matched by the CHILD's title against a `task` call whose input names it,
|
|
115
|
+
* or — when only one task is open — by that one. An unmatched child keeps accumulating
|
|
116
|
+
* progress and is applied as soon as a card appears.
|
|
117
|
+
*/
|
|
118
|
+
applyChildUpdate(record: SessionRecord, event: ChildSessionEvent): void;
|
|
119
|
+
/** Replace the metadata of a stored tool part, keeping everything else. */
|
|
120
|
+
private updateToolMetadata;
|
|
121
|
+
/** Which `task` card reports this child. */
|
|
122
|
+
private childCard;
|
|
123
|
+
setAgentName(name: string | undefined): void;
|
|
124
|
+
/**
|
|
125
|
+
* While muted, `apply` drops every update. The one caller is the `/cd` re-load: the
|
|
126
|
+
* agent re-delivers the whole conversation over `session/load`, and those frames are
|
|
127
|
+
* the very rows the live transcript already holds. Without the mute they would pass
|
|
128
|
+
* through `ensureMessage` (apply() creates an assistant row when none is active) and
|
|
129
|
+
* render the entire history a second time.
|
|
130
|
+
*/
|
|
131
|
+
private muted;
|
|
132
|
+
mute(): void;
|
|
133
|
+
unmute(): void;
|
|
134
|
+
/** Called when a prompt starts: opens the assistant message for the turn. */
|
|
135
|
+
beginTurn(record: SessionRecord): string;
|
|
136
|
+
/** Emit `session.step.started` exactly once, immediately before the first part. */
|
|
137
|
+
private ensureStep;
|
|
138
|
+
/** Called when the prompt settles (normal or cancelled). */
|
|
139
|
+
endTurn(record: SessionRecord, opts?: {
|
|
140
|
+
error?: string;
|
|
141
|
+
interrupted?: boolean;
|
|
142
|
+
}): void;
|
|
143
|
+
/** Handle one ACP `session/update`. */
|
|
144
|
+
apply(record: SessionRecord, update: SessionUpdate): void;
|
|
145
|
+
/**
|
|
146
|
+
* Mark every tool call of this session that has not finished as cancelled.
|
|
147
|
+
*
|
|
148
|
+
* ACP: "The Client **SHOULD** preemptively mark all non-finished tool calls
|
|
149
|
+
* pertaining to the current turn as `cancelled` as soon as it sends the
|
|
150
|
+
* `session/cancel` notification."
|
|
151
|
+
*
|
|
152
|
+
* opencode has no `cancelled` tool state, so the terminal state it does have is
|
|
153
|
+
* used, carrying the reason as the tool's output. The point is the same either
|
|
154
|
+
* way: a row must not be left spinning while it waits for an update that the
|
|
155
|
+
* aborted turn will never send. Returns how many rows were closed.
|
|
156
|
+
*/
|
|
157
|
+
/**
|
|
158
|
+
* Close every tool call the agent left unfinished.
|
|
159
|
+
*
|
|
160
|
+
* Called on abort *and* at normal turn end: an agent may simply stop reporting
|
|
161
|
+
* on a call, and a tool row that still says "running" after the turn is over is
|
|
162
|
+
* a spinner that never stops. `reason` lands in the row's output, so the UI says
|
|
163
|
+
* why rather than just going red.
|
|
164
|
+
*/
|
|
165
|
+
closeOpenToolCalls(record: SessionRecord, reason: string): number;
|
|
166
|
+
/**
|
|
167
|
+
* ACP reports context usage as `{used, size}`. opencode tracks input/output
|
|
168
|
+
* separately, so map `used` onto `input` and keep the rest zeroed rather than
|
|
169
|
+
* inventing a split the agent never sent.
|
|
170
|
+
*/
|
|
171
|
+
private applyUsage;
|
|
172
|
+
/** The context window the agent reported for this session, if it sent one. */
|
|
173
|
+
contextWindowFor(sessionId: string): number | undefined;
|
|
174
|
+
/**
|
|
175
|
+
* Usage from the prompt RESULT rather than a `usage_update` frame.
|
|
176
|
+
*
|
|
177
|
+
* opencode reports `{inputTokens, outputTokens, thoughtTokens, cachedReadTokens}` in the
|
|
178
|
+
* `session/prompt` response and never sends a `usage_update`; leaving the result's usage
|
|
179
|
+
* unread made the sidebar's context meter (which reads tokens off `session.step.ended`)
|
|
180
|
+
* and the footer show nothing. Call this before `endTurn`.
|
|
181
|
+
*/
|
|
182
|
+
recordPromptUsage(record: SessionRecord, usage: unknown): void;
|
|
183
|
+
private ensureMessage;
|
|
184
|
+
private textOf;
|
|
185
|
+
private closeOpenTextParts;
|
|
186
|
+
private appendText;
|
|
187
|
+
private applyToolCall;
|
|
188
|
+
/**
|
|
189
|
+
* ACP `plan` updates have nowhere to go. opencode v2 removed todo entirely
|
|
190
|
+
* (PR #35989: tool, sidebar panel, events and the persisted table, with no
|
|
191
|
+
* stated replacement), so there is no event to emit and no route to serve. The
|
|
192
|
+
* entries are logged rather than dropped silently.
|
|
193
|
+
*/
|
|
194
|
+
private applyPlan;
|
|
195
|
+
private emitPartUpdated;
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* ACP statuses are free-form strings in practice. Map conservatively: an
|
|
199
|
+
* unknown status becomes `running`, never `completed`, so the UI keeps showing
|
|
200
|
+
* activity instead of claiming a tool finished when it did not.
|
|
201
|
+
*/
|
|
202
|
+
/**
|
|
203
|
+
* Is this input obviously a placeholder? opencode's pending frame carries `{}` (or
|
|
204
|
+
* only `{cwd}`) and the command/query arrives with `in_progress`; publishing the
|
|
205
|
+
* placeholder is what pinned every shell card to "Writing command…".
|
|
206
|
+
*
|
|
207
|
+
* `undefined` is NOT partial: a tool that never sends an input has nothing to wait
|
|
208
|
+
* for.
|
|
209
|
+
*/
|
|
210
|
+
export declare function isPartialToolInput(input: unknown): boolean;
|
|
211
|
+
/** `rawOutput.metadata` is where the agent puts `{exit, truncated, status}`. */
|
|
212
|
+
export declare function toolMetadata(update: SessionUpdate): Record<string, unknown>;
|
|
213
|
+
export declare function toolError(update: SessionUpdate): string | undefined;
|
|
214
|
+
/**
|
|
215
|
+
* Add the input key the opencode TUI reads, using ACP's `kind` to decide which one.
|
|
216
|
+
*
|
|
217
|
+
* ACP declares `rawInput` as "any JSON value" and gives `kind` as the display category, so
|
|
218
|
+
* an agent may name its file argument anything. The TUI, meanwhile, renders `read`/`edit`
|
|
219
|
+
* rows from `input.path` and a shell row from `input.command`. Without this bridge an agent
|
|
220
|
+
* that follows the spec shows up as an empty "Reading file…" / "Preparing edit…" row, which
|
|
221
|
+
* is exactly what a `{file_path}`-shaped agent produced (measured on v2.2.0).
|
|
222
|
+
*
|
|
223
|
+
* Only ADDS keys; never overwrites what the agent sent, and never guesses without a `kind`.
|
|
224
|
+
*/
|
|
225
|
+
export declare function withClientInputKey(input: unknown, kind: unknown, title: unknown): unknown;
|
|
226
|
+
/**
|
|
227
|
+
* ACP: a `tool_call`'s status "defaults to `pending`", while on a `tool_call_update` an
|
|
228
|
+
* omitted field means "unchanged" (the caller keeps the previous state and never asks here).
|
|
229
|
+
*/
|
|
230
|
+
export declare function mapToolStatus(status: unknown): 'pending' | 'running' | 'completed' | 'error';
|
|
231
|
+
export declare function toolOutput(update: SessionUpdate): string | undefined;
|