agy-yolo-bridge 0.0.0-stage → 1.0.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/README.md CHANGED
@@ -1,3 +1,539 @@
1
- # Temporary Holding Version
1
+ # agy-yolo-bridge
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/badge/version-1.0.0-blue.svg)](package.json)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
5
+ [![Tested with Vitest](https://img.shields.io/badge/tested_with-vitest-6E9F18.svg)](https://vitest.dev/)
6
+ [![Code Quality: Biome](https://img.shields.io/badge/linted_with-biome-60a5fa.svg)](https://biomejs.dev/)
7
+ [![Node Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](package.json)
8
+
9
+ > **Enterprise-grade, modular OpenCode plugin (v1/v2) and standalone CLI tool bridging custom markdown commands (`commands/*.md`), repository constitutions (`AGENTS.md`), and specialized role personas (`agents/*.md`) to the Google Antigravity Agent Client Protocol (ACP) in autonomous YOLO mode (`accept-edits`).**
10
+
11
+ ---
12
+
13
+ ## Table of Contents
14
+
15
+ - [Overview](#overview)
16
+ - [Quick Start & Installation](#quick-start--installation)
17
+ - [1. As an OpenCode Plugin](#1-as-an-opencode-plugin)
18
+ - [2. As a Standalone CLI Tool](#2-as-a-standalone-cli-tool)
19
+ - [Prerequisites](#prerequisites)
20
+ - [The Universal 3-Tier Layering Model](#the-universal-3-tier-layering-model)
21
+ - [Tier 1: Constitution Layer (AGENTS.md)](#tier-1-constitution-layer-agentsmd)
22
+ - [Tier 2: Agent Persona Layer (agents/*.md)](#tier-2-agent-persona-layer-agentsmd)
23
+ - [Tier 3: Action / Command Layer (commands/*.md)](#tier-3-action--command-layer-commandsmd)
24
+ - [Authoring Guide & Procedures](#authoring-guide--procedures)
25
+ - [How to Create Agent Personas (agents/*.md)](#how-to-create-agent-personas-agentsmd)
26
+ - [How to Create Custom Commands (commands/*.md)](#how-to-create-custom-commands-commandsmd)
27
+ - [Automated Multi-Stage Orchestration](#automated-multi-stage-orchestration)
28
+ - [The 4-Stage Autonomous Pipeline](#the-4-stage-autonomous-pipeline)
29
+ - [Configuring Automated Orchestration in opencode.json](#configuring-automated-orchestration-in-opencodejson)
30
+ - [Enumeration Reference (ENUMs & Types)](#enumeration-reference-enums--types)
31
+ - [Execution Modes (mode / targetMode)](#execution-modes-mode--targetmode)
32
+ - [Thinking Budgets (thoughtLevel)](#thinking-budgets-thoughtlevel)
33
+ - [Streaming Event Types (SessionEvent)](#streaming-event-types-sessionevent)
34
+ - [OpenCode Tool Domain & Agent Tool Calling](#opencode-tool-domain--agent-tool-calling)
35
+ - [agy_exec (Universal Instruction Execution)](#agy_exec-universal-instruction-execution)
36
+ - [agy_ship_plan (Implementation Plan Execution)](#agy_ship_plan-implementation-plan-execution)
37
+ - [OpenCode Native MCP Bridging](#opencode-native-mcp-bridging)
38
+ - [Session Architecture & Process Safety](#session-architecture--process-safety)
39
+ - [Single-Flight Workspace Mutex](#single-flight-workspace-mutex)
40
+ - [Process Group Supervisor & Anti-Zombie Guarantees](#process-group-supervisor--anti-zombie-guarantees)
41
+ - [Configuration Reference](#configuration-reference)
42
+ - [Configuration File (agy-bridge.json)](#configuration-file-agy-bridgejson)
43
+ - [Environment Variables](#environment-variables)
44
+ - [Development & Verification](#development--verification)
45
+ - [License](#license)
46
+
47
+ ---
48
+
49
+ ## Overview
50
+
51
+ When building complex software systems with autonomous AI coding agents, developers require strict governance, role specialization, and deterministic execution. Traditional single-agent setups frequently encounter:
52
+
53
+ - **Prompt Contamination**: Instructions from planning leak into execution, causing agents to write superficial code without exhaustive testing.
54
+ - **Permission Prompt Fatigue**: Constant confirmation popups interrupt large refactorings or multi-file changes.
55
+ - **Tool Incompatibility**: MCP servers defined in one toolchain are not accessible in the agent execution runtime.
56
+ - **Dual-Model Confusion**: Mixing local models with cloud models without clear role boundaries causes runtime indeterminism.
57
+
58
+ **`agy-yolo-bridge`** solves this by creating a decoupled, zero-guesswork bridge between **OpenCode** and **Google Antigravity CLI (`agy`)**. It reads instructions from native markdown files, bridges all configured MCP servers dynamically, and executes tasks via Antigravity's Agent Client Protocol (ACP) in autonomous YOLO mode (`accept-edits`).
59
+
60
+ ---
61
+
62
+ ## Quick Start & Installation
63
+
64
+ ### Prerequisites
65
+
66
+ 1. **Node.js**: `>= 22.0.0`
67
+ 2. **Google Antigravity CLI (`agy`)**: Installed and authenticated in your environment:
68
+
69
+ ```bash
70
+ agy --version
71
+ ```
72
+
73
+ ### 1. As an OpenCode Plugin
74
+
75
+ Add `agy-yolo-bridge` to your project's `opencode.json` (or global `~/.config/opencode/opencode.json`):
76
+
77
+ ```json
78
+ {
79
+ "$schema": "https://opencode.ai/config.json",
80
+ "plugins": ["agy-yolo-bridge@latest"]
81
+ }
82
+ ```
83
+
84
+ Once declared, OpenCode automatically loads the plugin, registers `/agy` and all workspace markdown commands (`commands/*.md`), and exposes the `agy_exec` tool.
85
+
86
+ ### 2. As a Standalone CLI Tool
87
+
88
+ Install globally or run via `npx`:
89
+
90
+ ```bash
91
+ # Global installation
92
+ npm install -g agy-yolo-bridge
93
+
94
+ # Execute immediately via npx
95
+ npx agy-yolo-bridge ship
96
+ ```
97
+
98
+ ---
99
+
100
+ ## The Universal 3-Tier Layering Model
101
+
102
+ `agy-yolo-bridge` implements a deterministic 3-tier layering model that separates enterprise invariants from role personas and task commands:
103
+
104
+ ```
105
+ ┌────────────────────────────────────────────────────────────────────────┐
106
+ │ TIER 1: CONSTITUTION │
107
+ │ AGENTS.md / .opencode/AGENTS.md │
108
+ │ Universal repository invariants, security rules, VCS push prohibition │
109
+ └───────────────────────────────────┬────────────────────────────────────┘
110
+ │ (Always loaded into system prompt)
111
+ ▼
112
+ ┌────────────────────────────────────────────────────────────────────────┐
113
+ │ TIER 2: PERSONA │
114
+ │ .opencode/agents/<persona>.md │
115
+ │ Specialized role behaviors, domain expertise, and operational modes │
116
+ └───────────────────────────────────┬────────────────────────────────────┘
117
+ │ (Inherited by active task)
118
+ ▼
119
+ ┌────────────────────────────────────────────────────────────────────────┐
120
+ │ TIER 3: ACTION │
121
+ │ .opencode/commands/<action>.md │
122
+ │ Surgical task specifications, dynamic template variables ($ARGUMENTS)│
123
+ └────────────────────────────────────────────────────────────────────────┘
124
+ ```
125
+
126
+ Synthesized System Prompt formula:
127
+ $$\text{System Prompt} = \mathbf{AGENTS.md} \;+\; \mathbf{agents/<name>.md} \;+\; \mathbf{commands/<name>.md}$$
128
+
129
+ ### Tier 1: Constitution Layer (`AGENTS.md`)
130
+
131
+ Defines the authoritative rules of the repository (e.g., zero untyped `any`, 7-tag docstring standard, strict prohibition of unprompted `git commit` or `git push`).
132
+
133
+ - **Auto-Discovery Precedence**:
134
+ 1. `./AGENTS.md` (Workspace root)
135
+ 2. `.opencode/AGENTS.md`
136
+ 3. `.agent/AGENTS.md`
137
+ 4. `~/.config/opencode/AGENTS.md` (User global fallback)
138
+
139
+ ### Tier 2: Agent Persona Layer (`agents/*.md`)
140
+
141
+ Defines the specific job title, behavior, and capabilities of an agent.
142
+
143
+ - **Discovery Precedence**:
144
+ 1. `config.agents` mapping dictionary
145
+ 2. `.opencode/agents/<name>.md`
146
+ 3. `agents/<name>.md`
147
+ 4. `.agent/agents/<name>.md`
148
+ 5. `~/.config/opencode/agents/<name>.md`
149
+
150
+ ### Tier 3: Action / Command Layer (`commands/*.md`)
151
+
152
+ Defines executable task workflows triggered via OpenCode slash commands or the CLI.
153
+
154
+ - **Discovery Precedence**:
155
+ 1. `config.commands` mapping dictionary
156
+ 2. `.opencode/commands/<name>.md`
157
+ 3. `commands/<name>.md`
158
+ 4. Explicit markdown file path (e.g. `.agent/handoff/02_TECHNICAL_PLAN.md`)
159
+
160
+ ---
161
+
162
+ ## Authoring Guide & Procedures
163
+
164
+ ### How to Create Agent Personas (`agents/*.md`)
165
+
166
+ Create a markdown file in `.opencode/agents/<name>.md` (or `~/.config/opencode/agents/<name>.md`).
167
+
168
+ #### Persona YAML Frontmatter
169
+
170
+ ```yaml
171
+ ---
172
+ description: "Human-readable summary of persona responsibility"
173
+ model: "gemini-3.8-flash-high" # Target LLM model
174
+ mode: "accept-edits" # "accept-edits" (YOLO) | "default" | "plan"
175
+ thoughtLevel: "high" # "low" | "medium" | "high"
176
+ ---
177
+ ```
178
+
179
+ #### Production Persona Example: Implementation Driver (`agents/build.md`)
180
+
181
+ ```markdown
182
+ ---
183
+
184
+ description: "Autonomous Universal Implementation & Self-Healing Driver"
185
+ mode: accept-edits
186
+ thoughtLevel: low
187
+ ---
188
+
189
+ # Agent Role: Autonomous Universal Implementation Driver (`build`)
190
+
191
+ You are the **Principal Implementation Engineer** operating under `AGENTS.md`.
192
+ When invoked via `/ship`, your mandate is to:
193
+
194
+ 1. Ingest `.agent/handoff/02_TECHNICAL_PLAN.md` and `.agent/handoff/00_TASK_STATE.json`.
195
+ 2. Verify dependency research freshness in `.agent/handoff/01_RESEARCH_REPORT.md`.
196
+ 3. Implement all code changes adhering to the universal 7-tag docstring standard.
197
+ 4. Author comprehensive unit and integration tests covering positive and negative paths.
198
+ 5. Verify all linters, typecheckers, and test suites exit with code 0.
199
+ 6. Generate `.agent/handoff/03_BUILD_MANIFEST.md` and dispatch the `reviewer` subagent.
200
+ 7. If `04_REVIEW_AUDIT.md` returns `status: REJECTED_RETURN_TO_BUILD`, remediate defects and loop until approved.
201
+ ```
202
+
203
+ #### Production Persona Example: Lead QA Auditor (`agents/reviewer.md`)
204
+
205
+ ```markdown
206
+ ---
207
+
208
+ description: "Independent Lead QA & Principal Cybersecurity Auditor"
209
+ mode: accept-edits
210
+ thoughtLevel: low
211
+ ---
212
+
213
+ # Agent Role: Independent Lead QA Auditor (`reviewer`)
214
+
215
+ You are the **Lead QA & Cybersecurity Auditor**. Dispatched exclusively after the build phase, your mandate is:
216
+
217
+ - **Strict Read-Only Source Mandate:** Never mutate application source code directly.
218
+ - **6-Pillar QA Inspection:** Audit API contracts, frontend hydration, OWASP Top 10 vulnerabilities, supply-chain CVEs, anti-decorative test quality, and 7-tag docstrings.
219
+ - **Output:** Write definitive audit findings strictly to `.agent/handoff/04_REVIEW_AUDIT.md`.
220
+ ```
221
+
222
+ ---
223
+
224
+ ### How to Create Custom Commands (`commands/*.md`)
225
+
226
+ Create a markdown file in `.opencode/commands/<name>.md` (or `~/.config/opencode/commands/<name>.md`). The filename directly determines the slash command name (e.g. `audit.md` becomes `/audit`).
227
+
228
+ #### Command YAML Frontmatter
229
+
230
+ ```yaml
231
+ ---
232
+ description: "Run automated security, memory leak, and race condition audit"
233
+ agent: "reviewer" # Optional: binds command to Tier 2 persona
234
+ model: "gemini-3.8-flash-high" # Optional: overrides default model
235
+ mode: "accept-edits" # "accept-edits" | "default" | "plan"
236
+ thoughtLevel: "high" # "low" | "medium" | "high"
237
+ timeoutMs: 600000 # Execution timeout in milliseconds (default: 600000)
238
+ ---
239
+ ```
240
+
241
+ #### Dynamic Template Placeholders
242
+
243
+ Interpolate runtime context directly into your instruction:
244
+
245
+ | Placeholder | Alias | Description | Replacement Example |
246
+ | :----------- | :--------- | :-------------------------------------- | :------------------------- |
247
+ | `$ARGUMENTS` | `{{ARGS}}` | Arguments passed after the command | `src/auth.ts --strict` |
248
+ | `{{CWD}}` | — | Current working directory absolute path | `/workspace/my-service` |
249
+ | `{{DATE}}` | — | Current UTC ISO timestamp | `2026-11-22T10:00:00.000Z` |
250
+
251
+ #### Production Command Example (`commands/audit.md`)
252
+
253
+ ```markdown
254
+ ---
255
+
256
+ description: "Run comprehensive AppSec and concurrency audit"
257
+ agent: reviewer
258
+ thoughtLevel: high
259
+ mode: accept-edits
260
+ ---
261
+
262
+ # Deep Security & Concurrency Audit
263
+
264
+ Target Scope: $ARGUMENTS
265
+
266
+ Audit Invariants:
267
+
268
+ 1. Identify all unsanitized SQL, shell, or DOM injection sinks.
269
+ 2. Verify all event listeners, database pools, and streams have explicit teardowns.
270
+ 3. Detect race conditions on shared mutable states.
271
+
272
+ Output findings in a markdown table and assign severity ratings (CRITICAL, HIGH, MEDIUM, LOW).
273
+ ```
274
+
275
+ ---
276
+
277
+ ## Automated Multi-Stage Orchestration
278
+
279
+ `agy-yolo-bridge` enables fully autonomous, self-healing software delivery workflows by dividing responsibilities between OpenCode's planning capabilities and Antigravity's high-performance execution engine.
280
+
281
+ ### The 4-Stage Autonomous Pipeline
282
+
283
+ ```
284
+ ┌────────────────────────────────────────────────────────────────────────────────┐
285
+ │ STAGE 1: SPECIFICATION & RESEARCH (OpenCode Native Runtime) │
286
+ │ User / Agent 'plan' -> Explores repo, queries MCPs (context7, grep), writes │
287
+ │ .agent/handoff/01_RESEARCH_REPORT.md and 02_TECHNICAL_PLAN.md │
288
+ └──────────────────────────────────────┬─────────────────────────────────────────┘
289
+ │
290
+ ▼ (User executes /ship)
291
+ ┌────────────────────────────────────────────────────────────────────────────────┐
292
+ │ STAGE 2: AUTONOMOUS BUILD (Antigravity ACP via agy-yolo-bridge) │
293
+ │ Antigravity ACP (agent: build) in YOLO mode: │
294
+ │ - Reads 02_TECHNICAL_PLAN.md & verifies research freshness │
295
+ │ - Implements production code & tests across files │
296
+ │ - Runs compiler, linters, and test suites until 0 exit code │
297
+ │ - Emits .agent/handoff/03_BUILD_MANIFEST.md │
298
+ └──────────────────────────────────────┬─────────────────────────────────────────┘
299
+ │
300
+ ▼ (Build auto-dispatches Reviewer)
301
+ ┌────────────────────────────────────────────────────────────────────────────────┐
302
+ │ STAGE 3: ADVERSARIAL QA & REMEDIATION LOOP │
303
+ │ Antigravity ACP (agent: reviewer): │
304
+ │ - Audits git diff against plan & OWASP invariants │
305
+ │ - Writes .agent/handoff/04_REVIEW_AUDIT.md │
306
+ │ │
307
+ │ ┌───────────────────────┐ │
308
+ │ ▼ │ │
309
+ │ [REJECTED] ──> Build remediates & re-tests ──> Re-dispatches Reviewer │
310
+ │ │ │
311
+ │ ▼ [APPROVED_FOR_HUMAN_REVIEW] │
312
+ └──────────────────────────────────────┬─────────────────────────────────────────┘
313
+ │
314
+ ▼ (User inspects diff & runs /commit)
315
+ ┌────────────────────────────────────────────────────────────────────────────────┐
316
+ │ STAGE 4: RELEASE & VCS GATE (OpenCode Native Runtime) │
317
+ │ Agent 'committer': Verifies audit approval, filters secrets, stages files, │
318
+ │ generates Conventional Commit citing task_id, and pushes cleanly. │
319
+ └────────────────────────────────────────────────────────────────────────────────┘
320
+ ```
321
+
322
+ ### Configuring Automated Orchestration in `opencode.json`
323
+
324
+ To establish this exact automated pipeline in your workspace, configure your `opencode.json`:
325
+
326
+ ```json
327
+ {
328
+ "$schema": "https://opencode.ai/config.json",
329
+ "default_agent": "plan",
330
+ "plugins": ["agy-yolo-bridge@latest"],
331
+ "commands": {
332
+ "ship": {
333
+ "description": "Execute approved plan, verify, deep review, and loop until PASS via Antigravity",
334
+ "template": "/agy agent:build .agent/handoff/02_TECHNICAL_PLAN.md"
335
+ },
336
+ "commit": {
337
+ "agent": "committer",
338
+ "description": "Verify audit approval, filter secrets, commit via Conventional Commits, push, and archive task",
339
+ "template": "Verify .agent/handoff/04_REVIEW_AUDIT.md has status APPROVED_FOR_HUMAN_REVIEW and matches active task_id. Filter out all secrets and ephemeral files, stage verified changes, commit using Conventional Commits 1.0.0 citing task_id, push to current remote branch, and archive task artifacts."
340
+ }
341
+ }
342
+ }
343
+ ```
344
+
345
+ > [!TIP]
346
+ > Notice that `"agent": "build"` is omitted from `commands.ship`. When you type `/ship`, OpenCode expands the command directly to `/agy agent:build .agent/handoff/02_TECHNICAL_PLAN.md`, delegating the entire coding and testing phase directly to Antigravity ACP in YOLO mode!
347
+
348
+ ---
349
+
350
+ ## Enumeration Reference (ENUMs & Types)
351
+
352
+ ### Execution Modes (`mode` / `targetMode`)
353
+
354
+ | Value | Identifier | Description | Autonomy Level |
355
+ | :--------------- | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------- |
356
+ | `"accept-edits"` | YOLO Mode | **Default**. Automatically accepts all proposed file edits and tool execution permissions without user confirmation prompts. Ideal for CI/CD, headless workers, and automated pipelines. | Full Autonomy |
357
+ | `"default"` | Interactive Mode | Standard agent mode. Presents interactive confirmation prompts for sensitive tool executions and file modifications according to client permission gates. | Guarded Autonomy |
358
+ | `"plan"` | Architectural Mode | Read-only planning mode. Analyzes workspace context and outputs markdown execution plans without modifying files on disk. | Read-Only |
359
+
360
+ ### Thinking Budgets (`thoughtLevel`)
361
+
362
+ Controls the computational budget allocated to chain-of-thought (CoT) reasoning in supported models (e.g., `gemini-3.8-flash-high`, `gemini-3.8-pro`):
363
+
364
+ | Value | Latency | Reasoning Depth | Recommended Use Cases |
365
+ | :--------- | :------ | :--------------------------- | :-------------------------------------------------------------- |
366
+ | `"low"` | ~1-3s | Minimal reasoning chain | Straightforward tasks, unit test fixes, boilerplate scaffolding |
367
+ | `"medium"` | ~3-8s | Balanced reasoning | Standard feature implementation, bug fixing, test authoring |
368
+ | `"high"` | ~8-25s | Deep multi-step verification | Complex refactoring, AppSec audits, concurrent architectures |
369
+
370
+ ### Streaming Event Types (`SessionEvent`)
371
+
372
+ The ACP engine streams structured telemetry and events in real time:
373
+
374
+ | Event Type | Payload Properties | Description |
375
+ | :-------------- | :-------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
376
+ | `"status"` | `message: string` | Lifecycle transitions (session initialization, model setup, shutdown). |
377
+ | `"thought"` | `thought: string` | Real-time chain-of-thought reasoning stream emitted by the model. |
378
+ | `"message"` | `content: string` | Streaming text fragments of the assistant's direct response. |
379
+ | `"tool_start"` | `callId: string`, `toolName: string`, `args?: Record<string, unknown>` | Notification that an external or MCP tool has begun execution. |
380
+ | `"tool_update"` | `callId: string`, `status: string`, `output?: string` | Intermediate output or progress updates from an active tool execution. |
381
+ | `"usage"` | `promptTokens?: number`, `candidateTokens?: number`, `totalTokens?: number` | Cumulative token consumption telemetry. |
382
+ | `"stderr"` | `message: string` | Diagnostic output and standard error from the Antigravity subprocess. |
383
+
384
+ ---
385
+
386
+ ## OpenCode Tool Domain & Agent Tool Calling
387
+
388
+ The bridge registers strictly typed tools conforming to `@opencode/schema/tool`, enabling autonomous agents to invoke Antigravity ACP programmatically without triggering harness warnings.
389
+
390
+ ### `agy_exec` (Universal Instruction Execution)
391
+
392
+ Executes any custom command or markdown file via Antigravity ACP.
393
+
394
+ - **Input Schema:**
395
+ - `command` (`string`, optional): Name of a registered command (e.g. `"audit"`).
396
+ - `agent` (`string`, optional): Role persona name (e.g. `"build"`, `"reviewer"`).
397
+ - `instructionPath` (`string`, optional): Relative or absolute path to instruction markdown file.
398
+ - `inlineInstruction` / `prompt` (`string`, optional): Raw prompt or instruction text.
399
+ - `args` (`string`, optional): Contextual user arguments.
400
+ - **Output Schema:** `output: Schema.String`
401
+ - **Return Shape:** `{ content: string, output: string }`
402
+
403
+ #### Tool Invocation Example:
404
+
405
+ ```json
406
+ {
407
+ "tool": "agy_exec",
408
+ "arguments": {
409
+ "agent": "build",
410
+ "instructionPath": ".agent/handoff/02_TECHNICAL_PLAN.md",
411
+ "args": "--verify-all"
412
+ }
413
+ }
414
+ ```
415
+
416
+ ### `agy_ship_plan` (Implementation Plan Execution)
417
+
418
+ Specialized helper tool to execute an approved implementation plan in YOLO mode.
419
+
420
+ - **Input Schema:**
421
+ - `planPath` (`string`, optional): Explicit path to plan file.
422
+ - `inlinePlanText` (`string`, optional): Inline markdown plan text.
423
+ - **Output Schema:** `output: Schema.String`
424
+
425
+ ---
426
+
427
+ ## OpenCode Native MCP Bridging
428
+
429
+ Antigravity natively includes internal tools. To ensure complete alignment with your OpenCode project, `agy-yolo-bridge` dynamically imports all MCP servers defined in OpenCode:
430
+
431
+ 1. **Sources Inspected**:
432
+ - Runtime `ctx.mcp.list()` (active plugin context)
433
+ - `.opencode/mcp.json`
434
+ - `opencode.json` (workspace root)
435
+ - `~/.config/opencode/opencode.json` (user global)
436
+ 2. **Protocol Conversion**:
437
+ - **Local Stdio MCP Servers**: Converts `command`, `args`, `env`, and `cwd` into standard ACP server parameters.
438
+ - **Remote HTTP/SSE MCP Servers**: Converts `url` and custom `headers` into standard ACP endpoints.
439
+ 3. **Sterility & Isolation**:
440
+ - Passes `--include-default-customizations=false` to Antigravity ACP.
441
+ - Antigravity sees **only** OpenCode MCP servers and your markdown instructions, eliminating tool shadowing and prompt interference.
442
+
443
+ ---
444
+
445
+ ## Session Architecture & Process Safety
446
+
447
+ ### Single-Flight Workspace Mutex
448
+
449
+ To prevent concurrent file mutation conflicts, the bridge enforces an atomic workspace lock:
450
+
451
+ - Creates `.opencode/.agy-yolo-bridge.lock` containing the active PID, timestamp, and task identifier.
452
+ - **Stale Lock Recovery**: Automatically verifies dead PIDs (`process.kill(pid, 0)`) and lock timeouts, automatically releasing abandoned locks.
453
+
454
+ ### Process Group Supervisor & Anti-Zombie Guarantees
455
+
456
+ Child subprocesses can become orphaned zombie processes if the parent crashes or is interrupted:
457
+
458
+ - Spawns Antigravity in an isolated process group (`detached: true`).
459
+ - Hooks OS signals (`SIGINT`, `SIGTERM`, `SIGHUP`) and `AbortSignal` cancellation tokens.
460
+ - Dispatches `SIGTERM` to the entire negative PID group (`-child.pid`), escalating to `SIGKILL` after an explicit grace period.
461
+
462
+ ---
463
+
464
+ ## Configuration Reference
465
+
466
+ ### Configuration File (`agy-bridge.json`)
467
+
468
+ Place `agy-bridge.json` in your workspace root or `.opencode/agy-bridge.json`:
469
+
470
+ ```json
471
+ {
472
+ "$schema": "./agy-bridge.schema.json",
473
+ "binaryPath": "agy",
474
+ "requireAgentsMd": false,
475
+ "commandsDir": ".opencode/commands",
476
+ "agentsDir": ".opencode/agents",
477
+ "loadOpenCodeMcp": true,
478
+ "useCustomSystemPrompt": true,
479
+ "yolo": true,
480
+ "targetMode": "accept-edits",
481
+ "model": "gemini-3.8-flash-high",
482
+ "thoughtLevel": "high",
483
+ "timeoutMs": 600000,
484
+ "commands": {
485
+ "audit": ".opencode/commands/audit.md",
486
+ "review": ".opencode/commands/review.md",
487
+ "ship": ".opencode/commands/ship.md"
488
+ }
489
+ }
490
+ ```
491
+
492
+ ### Environment Variables
493
+
494
+ | Variable | Type | Default | Description |
495
+ | :------------------------------------ | :------------------ | :--------------------- | :-------------------------------------------------- |
496
+ | `AGY_BRIDGE_BINARY` | `string` | `"agy"` | Path or command name for Antigravity CLI binary |
497
+ | `AGY_BRIDGE_REQUIRE_AGENTS_MD` | `boolean` (`1`/`0`) | `false` | Mandate that `AGENTS.md` constitution exists |
498
+ | `AGY_BRIDGE_AGENTS_MD_PATH` | `string` | `undefined` | Explicit file path override to `AGENTS.md` |
499
+ | `AGY_BRIDGE_AGENTS_DIR` | `string` | `".opencode/agents"` | Directory path for agent personas (`*.md`) |
500
+ | `AGY_BRIDGE_COMMANDS_DIR` | `string` | `".opencode/commands"` | Directory path for custom commands (`*.md`) |
501
+ | `AGY_BRIDGE_LOAD_OPENCODE_MCP` | `boolean` (`1`/`0`) | `true` | Bridge OpenCode MCP servers to Antigravity ACP |
502
+ | `AGY_BRIDGE_USE_CUSTOM_SYSTEM_PROMPT` | `boolean` (`1`/`0`) | `true` | Override default system prompt with constitution |
503
+ | `AGY_BRIDGE_YOLO` | `boolean` (`1`/`0`) | `true` | Enable YOLO mode (`accept-edits`) |
504
+ | `AGY_BRIDGE_MODE` | `enum` | `"accept-edits"` | Target ACP mode (`accept-edits`, `default`, `plan`) |
505
+ | `AGY_BRIDGE_MODEL` | `string` | `undefined` | Target LLM model identifier |
506
+ | `AGY_BRIDGE_THOUGHT_LEVEL` | `enum` | `undefined` | Thinking budget (`low`, `medium`, `high`) |
507
+ | `AGY_BRIDGE_TIMEOUT_MS` | `number` | `600000` | Task execution timeout in milliseconds (10 min) |
508
+
509
+ ---
510
+
511
+ ## Development & Verification
512
+
513
+ `agy-yolo-bridge` enforces strict quality standards using Biome and Vitest:
514
+
515
+ ```bash
516
+ # Check formatting, lint rules, and import sorting with Biome (sub-second)
517
+ pnpm run lint
518
+
519
+ # Auto-fix formatting and lint issues
520
+ pnpm run lint:fix
521
+
522
+ # Format all files
523
+ pnpm run format
524
+
525
+ # Run strict TypeScript typecheck
526
+ pnpm run typecheck
527
+
528
+ # Execute comprehensive Vitest test suite (70+ unit & integration tests)
529
+ pnpm test
530
+
531
+ # Build production distribution bundle
532
+ pnpm run build
533
+ ```
534
+
535
+ ---
536
+
537
+ ## License
538
+
539
+ [MIT](LICENSE) © 2026 Shukoi. Distributed under the terms of the MIT License.
@@ -0,0 +1,77 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "title": "AGY YOLO Bridge Configuration",
4
+ "type": "object",
5
+ "additionalProperties": false,
6
+ "properties": {
7
+ "binaryPath": { "type": "string", "minLength": 1 },
8
+ "agent": { "type": "string", "minLength": 1 },
9
+ "requireAgentsMd": { "type": "boolean" },
10
+ "agentsMdPath": { "type": "string" },
11
+ "agentsDir": { "type": "string", "minLength": 1 },
12
+ "agents": {
13
+ "type": "object",
14
+ "additionalProperties": {
15
+ "oneOf": [
16
+ { "type": "string", "minLength": 1 },
17
+ {
18
+ "type": "object",
19
+ "required": ["personaPath"],
20
+ "properties": {
21
+ "personaPath": { "type": "string", "minLength": 1 },
22
+ "description": { "type": "string" },
23
+ "model": { "type": "string" },
24
+ "thoughtLevel": { "type": "string", "enum": ["low", "medium", "high"] },
25
+ "targetMode": { "type": "string", "enum": ["accept-edits", "default", "plan"] }
26
+ }
27
+ }
28
+ ]
29
+ }
30
+ },
31
+ "commandsDir": { "type": "string", "minLength": 1 },
32
+ "commands": {
33
+ "type": "object",
34
+ "additionalProperties": {
35
+ "oneOf": [
36
+ { "type": "string", "minLength": 1 },
37
+ {
38
+ "type": "object",
39
+ "required": ["instructionPath"],
40
+ "properties": {
41
+ "instructionPath": { "type": "string", "minLength": 1 },
42
+ "description": { "type": "string" },
43
+ "model": { "type": "string" },
44
+ "thoughtLevel": { "type": "string", "enum": ["low", "medium", "high"] },
45
+ "targetMode": { "type": "string", "enum": ["accept-edits", "default", "plan"] },
46
+ "yolo": { "type": "boolean" }
47
+ }
48
+ }
49
+ ]
50
+ }
51
+ },
52
+ "loadOpenCodeMcp": { "type": "boolean" },
53
+ "useCustomSystemPrompt": { "type": "boolean" },
54
+ "planPaths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
55
+ "planDir": { "type": "string", "minLength": 1 },
56
+ "yolo": { "type": "boolean" },
57
+ "sandbox": { "type": "boolean" },
58
+ "disableTelemetry": { "type": "boolean" },
59
+ "includeDefaultCustomizations": { "type": "boolean" },
60
+ "processPerSession": { "type": "boolean" },
61
+ "targetMode": { "type": "string", "enum": ["accept-edits", "default", "plan"] },
62
+ "model": { "type": "string" },
63
+ "thoughtLevel": { "type": "string", "enum": ["low", "medium", "high"] },
64
+ "addDirs": { "type": "array", "items": { "type": "string" } },
65
+ "handshakeTimeoutMs": { "type": "integer", "minimum": 1000 },
66
+ "idleTimeoutMs": { "type": "integer", "minimum": 5000 },
67
+ "maxExecutionTimeoutMs": { "type": "integer", "minimum": 10000 },
68
+ "shutdownGraceMs": { "type": "integer", "minimum": 500 },
69
+ "maxLogEntries": { "type": "integer", "minimum": 50 },
70
+ "maxOutputChars": { "type": "integer", "minimum": 4096 },
71
+ "lockStaleMs": { "type": "integer", "minimum": 5000 },
72
+ "executionPromptTemplate": { "type": "string", "minLength": 1 },
73
+ "cloudCodeEndpoint": { "type": "string" },
74
+ "appDataDir": { "type": "string" },
75
+ "geminiDir": { "type": "string" }
76
+ }
77
+ }
package/biome.json ADDED
@@ -0,0 +1,44 @@
1
+ {
2
+ "$schema": "https://biomejs.dev/schemas/2.6.8/schema.json",
3
+ "vcs": {
4
+ "enabled": true,
5
+ "clientKind": "git",
6
+ "useIgnoreFile": true
7
+ },
8
+ "files": {
9
+ "includes": ["**", "!!**/dist", "!!**/node_modules", "!!**/package-lock.json"]
10
+ },
11
+ "formatter": {
12
+ "enabled": true,
13
+ "indentStyle": "space",
14
+ "indentWidth": 2,
15
+ "lineWidth": 100
16
+ },
17
+ "linter": {
18
+ "enabled": true,
19
+ "rules": {
20
+ "preset": "recommended",
21
+ "style": {
22
+ "noNonNullAssertion": "off"
23
+ },
24
+ "suspicious": {
25
+ "noExplicitAny": "off"
26
+ }
27
+ }
28
+ },
29
+ "javascript": {
30
+ "formatter": {
31
+ "quoteStyle": "single",
32
+ "trailingCommas": "all",
33
+ "semicolons": "always"
34
+ }
35
+ },
36
+ "assist": {
37
+ "enabled": true,
38
+ "actions": {
39
+ "source": {
40
+ "organizeImports": "on"
41
+ }
42
+ }
43
+ }
44
+ }