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.
Files changed (55) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +220 -2
  3. package/README.zh.md +199 -0
  4. package/dist/acp/capabilities.d.ts +168 -0
  5. package/dist/acp/capabilities.js +240 -0
  6. package/dist/acp/capabilities.js.map +1 -0
  7. package/dist/acp/client.d.ts +241 -0
  8. package/dist/acp/client.js +767 -0
  9. package/dist/acp/client.js.map +1 -0
  10. package/dist/acp/types.d.ts +228 -0
  11. package/dist/acp/types.js +23 -0
  12. package/dist/acp/types.js.map +1 -0
  13. package/dist/acp-replay.d.ts +60 -0
  14. package/dist/acp-replay.js +188 -0
  15. package/dist/acp-replay.js.map +1 -0
  16. package/dist/contract.d.ts +435 -0
  17. package/dist/contract.js +126 -0
  18. package/dist/contract.js.map +1 -0
  19. package/dist/daemons.d.ts +39 -0
  20. package/dist/daemons.js +112 -0
  21. package/dist/daemons.js.map +1 -0
  22. package/dist/index.d.ts +268 -0
  23. package/dist/index.js +1882 -0
  24. package/dist/index.js.map +1 -0
  25. package/dist/opencode-bin.d.ts +73 -0
  26. package/dist/opencode-bin.js +109 -0
  27. package/dist/opencode-bin.js.map +1 -0
  28. package/dist/project.d.ts +81 -0
  29. package/dist/project.js +230 -0
  30. package/dist/project.js.map +1 -0
  31. package/dist/server.d.ts +743 -0
  32. package/dist/server.js +5029 -0
  33. package/dist/server.js.map +1 -0
  34. package/dist/session-map.d.ts +89 -0
  35. package/dist/session-map.js +305 -0
  36. package/dist/session-map.js.map +1 -0
  37. package/dist/sessions-command.d.ts +70 -0
  38. package/dist/sessions-command.js +188 -0
  39. package/dist/sessions-command.js.map +1 -0
  40. package/dist/sse.d.ts +40 -0
  41. package/dist/sse.js +147 -0
  42. package/dist/sse.js.map +1 -0
  43. package/dist/state.d.ts +161 -0
  44. package/dist/state.js +135 -0
  45. package/dist/state.js.map +1 -0
  46. package/dist/subagent-sessions.d.ts +71 -0
  47. package/dist/subagent-sessions.js +107 -0
  48. package/dist/subagent-sessions.js.map +1 -0
  49. package/dist/translate/events.d.ts +231 -0
  50. package/dist/translate/events.js +1244 -0
  51. package/dist/translate/events.js.map +1 -0
  52. package/dist/upgrade.d.ts +56 -0
  53. package/dist/upgrade.js +162 -0
  54. package/dist/upgrade.js.map +1 -0
  55. 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;