@tbrandenburg/opencode-a2a-lite 0.3.1 → 0.3.3
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/README.md +20 -9
- package/dist/package.json +1 -1
- package/dist/src/acp-client.js +4 -3
- package/dist/src/bridge-error.js +7 -0
- package/dist/src/executor.js +4 -2
- package/dist/src/server.js +14 -2
- package/dist/src/terminal-output.js +10 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -24,6 +24,12 @@ A2A client ──HTTP/SSE──▶ opencode-a2a-lite ──ACP (stdio)──▶
|
|
|
24
24
|
> exposed through a public proxy. It inherits OpenCode configuration, tools, plugins and MCP. Rejecting ACP
|
|
25
25
|
> permission requests is **not** an OS sandbox, and cancellation does not roll back work.
|
|
26
26
|
|
|
27
|
+
Choosing a workspace is an explicit trust decision, not a filesystem boundary:
|
|
28
|
+
OpenCode runs as the invoking user and can access resources permitted to that user.
|
|
29
|
+
For stronger isolation use a separately secured VM or container with minimal
|
|
30
|
+
workspace mounts, credentials and network access. The isolated demo uses a private
|
|
31
|
+
HOME/configuration, but is not an OS sandbox.
|
|
32
|
+
|
|
27
33
|
## Contents
|
|
28
34
|
|
|
29
35
|
- [Quick start](#quick-start)
|
|
@@ -44,8 +50,9 @@ npx --yes @tbrandenburg/opencode-a2a-lite@latest --workspace /absolute/path/to/t
|
|
|
44
50
|
|
|
45
51
|
This starts a **gateway server** on `127.0.0.1` and launches `opencode` as a child
|
|
46
52
|
process over ACP in that workspace. It does not run any task by itself: OpenCode only
|
|
47
|
-
works when an A2A client sends a prompt.
|
|
48
|
-
|
|
53
|
+
works when an A2A client sends a prompt. On startup, the CLI prints aligned lifecycle
|
|
54
|
+
status to stderr and a machine-readable readiness record to stdout
|
|
55
|
+
(`{"ready":true,"url":"http://127.0.0.1:.../"}`). In a second terminal use the
|
|
49
56
|
**actual** URL (default port 41241):
|
|
50
57
|
|
|
51
58
|
```sh
|
|
@@ -54,8 +61,10 @@ a2a send -a http://127.0.0.1:41241 "Reply with a short greeting." --stream
|
|
|
54
61
|
a2a send -a http://127.0.0.1:41241 --context-id <returned-context-id> "Follow up"
|
|
55
62
|
```
|
|
56
63
|
|
|
57
|
-
The server runs in the foreground
|
|
58
|
-
|
|
64
|
+
The server runs in the foreground. Press Ctrl-C to see shutdown progress; it reports
|
|
65
|
+
`stopped` only after closing the listener and releasing its owned OpenCode process.
|
|
66
|
+
Status lines use color only on interactive terminals, honor `NO_COLOR`, and remain
|
|
67
|
+
plain when redirected. Startup JSON stays on stdout; human-readable status is on stderr.
|
|
59
68
|
|
|
60
69
|
## Requirements
|
|
61
70
|
|
|
@@ -115,13 +124,15 @@ reusing the ACP session for that context.
|
|
|
115
124
|
- Only ACP `end_turn` means completed; confirmed `cancelled` means canceled.
|
|
116
125
|
Errors and other stop reasons fail the task without publishing private diagnostics.
|
|
117
126
|
- Permission requests are rejected/canceled, not silently approved.
|
|
127
|
+
- A failed task names the failing phase (for example `ACP session creation failed`); the
|
|
128
|
+
underlying OpenCode diagnostic is never published. A bridge failure is permanent until restart.
|
|
118
129
|
- Defaults: 30-second startup/session allocation, 120-second prompt, 5-second
|
|
119
130
|
cancellation and 5-second ACP shutdown. Failure retires the unhealthy bridge.
|
|
120
131
|
- Streaming sends stable artifact IDs and ordered append events. Task states are
|
|
121
132
|
SDK-owned; the small [request-handler adapter](src/request-handler.ts) is retained
|
|
122
133
|
for a documented upstream cancellation persistence defect.
|
|
123
134
|
|
|
124
|
-
See [architecture
|
|
135
|
+
See [architecture and implementation pitfalls](docs/architecture.md) and
|
|
125
136
|
[SDK cancellation removal criteria](docs/sdk-cancellation.md).
|
|
126
137
|
Full A2A TCK certification, interactive approval, rich media, push notifications
|
|
127
138
|
and runtime-selected workspaces are not claimed.
|
|
@@ -154,7 +165,8 @@ Live demo/E2E are explicit manual commands requiring a provider key,
|
|
|
154
165
|
OpenCode and the official A2A CLI; `make demo` also needs `jq` and GNU `timeout`.
|
|
155
166
|
On macOS its isolated workspace cleanup additionally uses `/usr/sbin/lsof`.
|
|
156
167
|
For the exact live evidence/limitations see [acceptance](docs/acceptance.md).
|
|
157
|
-
|
|
168
|
+
`bun scripts/quality-report.ts` summarizes the latest local measurements;
|
|
169
|
+
native line/function coverage is not branch coverage or a correctness guarantee.
|
|
158
170
|
|
|
159
171
|
## Multi-agent coordination
|
|
160
172
|
|
|
@@ -167,9 +179,8 @@ For a manually owned model-issued MCP → A2A flow use the
|
|
|
167
179
|
[explicit two-worker pipeline recipe](docs/manual-two-worker-pipeline.md) and
|
|
168
180
|
[passive supervision](docs/passive-mcp-supervision.md). The
|
|
169
181
|
[portable OpenCode multi-agent skill](.opencode/skills/multi-a2a-agent/SKILL.md)
|
|
170
|
-
includes eight topology procedures
|
|
171
|
-
|
|
172
|
-
observations, not proof of general reliability.
|
|
182
|
+
includes eight topology procedures. The [historical research index](docs/history.md)
|
|
183
|
+
links scoped observations, not proof of general reliability.
|
|
173
184
|
|
|
174
185
|
The managed network/topology research lab has been **retired, not fixed**. Its
|
|
175
186
|
original failures and unverified outcomes are linked in the
|
package/dist/package.json
CHANGED
package/dist/src/acp-client.js
CHANGED
|
@@ -3,6 +3,7 @@ import { isAbsolute } from "node:path";
|
|
|
3
3
|
import { Readable, Writable } from "node:stream";
|
|
4
4
|
import * as acp from "@agentclientprotocol/sdk";
|
|
5
5
|
import manifest from "../package.json" with { type: "json" };
|
|
6
|
+
import { BridgeError } from "./bridge-error.js";
|
|
6
7
|
import { supportedOpenCode } from "./opencode-version.js";
|
|
7
8
|
import { StartupError } from "./startup-error.js";
|
|
8
9
|
export function createAcpBridge(options) {
|
|
@@ -32,7 +33,7 @@ export function createAcpBridge(options) {
|
|
|
32
33
|
function fail(message) {
|
|
33
34
|
if (failure.signal.aborted)
|
|
34
35
|
return;
|
|
35
|
-
failure.abort(message instanceof StartupError ? message : new
|
|
36
|
+
failure.abort(message instanceof StartupError ? message : new BridgeError(message));
|
|
36
37
|
ready = false;
|
|
37
38
|
connection?.close();
|
|
38
39
|
// Retain the cleanup result for close(); request errors never contain peer diagnostics.
|
|
@@ -70,14 +71,14 @@ export function createAcpBridge(options) {
|
|
|
70
71
|
}
|
|
71
72
|
function requireConnection(sessionId) {
|
|
72
73
|
if (!ready || !connection || failure.signal.aborted || stopping)
|
|
73
|
-
throw new
|
|
74
|
+
throw new BridgeError("ACP bridge unavailable");
|
|
74
75
|
if (sessionId !== undefined && !sessions.has(sessionId))
|
|
75
76
|
throw new Error("Unknown ACP session");
|
|
76
77
|
return connection;
|
|
77
78
|
}
|
|
78
79
|
function start() {
|
|
79
80
|
if (failure.signal.aborted || stopping)
|
|
80
|
-
return Promise.reject(new
|
|
81
|
+
return Promise.reject(new BridgeError("ACP bridge unavailable"));
|
|
81
82
|
if (starting)
|
|
82
83
|
return starting;
|
|
83
84
|
starting = bounded(async () => {
|
package/dist/src/executor.js
CHANGED
|
@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
|
|
|
2
2
|
import { Role, TaskState } from "@a2a-js/sdk";
|
|
3
3
|
import { TaskNotCancelableError } from "@a2a-js/sdk/errors";
|
|
4
4
|
import { AgentEvent, } from "@a2a-js/sdk/server";
|
|
5
|
+
import { BridgeError } from "./bridge-error.js";
|
|
5
6
|
export const EXPLICIT_CONTEXT = "opencode.explicitContext";
|
|
6
7
|
function textPart(text) {
|
|
7
8
|
return {
|
|
@@ -139,10 +140,11 @@ export function createAgentExecutor(bridge, options = {}) {
|
|
|
139
140
|
sessions.delete(contextId);
|
|
140
141
|
finish(TaskState.TASK_STATE_FAILED, "ACP did not complete the turn");
|
|
141
142
|
}
|
|
142
|
-
catch {
|
|
143
|
+
catch (error) {
|
|
143
144
|
sessions.delete(contextId);
|
|
145
|
+
// Only gateway-authored phase messages are published; peer diagnostics never are.
|
|
144
146
|
if (!terminal)
|
|
145
|
-
finish(TaskState.TASK_STATE_FAILED, "ACP execution failed");
|
|
147
|
+
finish(TaskState.TASK_STATE_FAILED, error instanceof BridgeError ? error.message : "ACP execution failed");
|
|
146
148
|
}
|
|
147
149
|
finally {
|
|
148
150
|
record.terminal = true;
|
package/dist/src/server.js
CHANGED
|
@@ -12,6 +12,7 @@ import { createRequestHandler } from "./request-handler.js";
|
|
|
12
12
|
import { parseOptions } from "./cli-options.js";
|
|
13
13
|
import { reportStartupError, StartupError } from "./startup-error.js";
|
|
14
14
|
import { validateIdentity } from "./identity.js";
|
|
15
|
+
import { formatStatus, supportsTerminalColor } from "./terminal-output.js";
|
|
15
16
|
export function createGateway(options) {
|
|
16
17
|
const identity = validateIdentity(options.identity);
|
|
17
18
|
if (!isAbsolute(options.workspace))
|
|
@@ -171,9 +172,14 @@ export function createGateway(options) {
|
|
|
171
172
|
}
|
|
172
173
|
export async function launchGateway(options) {
|
|
173
174
|
const gateway = createGateway(options);
|
|
175
|
+
const status = (label, detail) => console.error(formatStatus(label, detail, supportsTerminalColor(process.stderr, process.env)));
|
|
174
176
|
const stop = () => {
|
|
175
|
-
|
|
176
|
-
|
|
177
|
+
status("stopping", "gateway · draining active work and closing the listener");
|
|
178
|
+
void gateway
|
|
179
|
+
.close()
|
|
180
|
+
.then(() => status("stopped", "gateway · listener closed and OpenCode process released"))
|
|
181
|
+
.catch(() => {
|
|
182
|
+
status("error", "gateway shutdown failed · inspect the process before restarting");
|
|
177
183
|
process.exitCode = 1;
|
|
178
184
|
});
|
|
179
185
|
};
|
|
@@ -182,6 +188,12 @@ export async function launchGateway(options) {
|
|
|
182
188
|
try {
|
|
183
189
|
const ready = await gateway.start();
|
|
184
190
|
console.log(JSON.stringify({ ready: true, url: ready.url }));
|
|
191
|
+
const cardUrl = new URL(".well-known/agent-card.json", ready.url).href;
|
|
192
|
+
status("ready", `gateway · ${ready.url}`);
|
|
193
|
+
status("workspace", options.workspace);
|
|
194
|
+
status("agent card", cardUrl);
|
|
195
|
+
status("connect", `a2a send -a ${ready.url} "Reply with a short greeting." --stream`);
|
|
196
|
+
status("stop", "press Ctrl-C to stop the gateway");
|
|
185
197
|
}
|
|
186
198
|
catch (error) {
|
|
187
199
|
process.removeListener("SIGINT", stop);
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
const statusWidth = 10;
|
|
2
|
+
const accent = "\u001b[1;36m";
|
|
3
|
+
const reset = "\u001b[0m";
|
|
4
|
+
export function formatStatus(label, detail, color) {
|
|
5
|
+
const status = label.padEnd(statusWidth);
|
|
6
|
+
return color ? ` ${accent}${status}${reset} ${detail}` : ` ${status} ${detail}`;
|
|
7
|
+
}
|
|
8
|
+
export function supportsTerminalColor(stream, env) {
|
|
9
|
+
return Boolean(stream.isTTY && env.NO_COLOR === undefined && env.TERM !== "dumb");
|
|
10
|
+
}
|