@jiezhengj/subagent-oar-agy 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jiezhengj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+本插件把独立任务委派给本机 Antigravity CLI（`agy`）执行：模型通过 `subagent_oar_agy` 工具把任务交给 agy，取回最终答复。本插件是非官方封装，与 DeepSeek 或 Google 均无隶属关系，使用风险自担。
 
-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.
+其他语言：[English](https://github.com/jiezhengj/DSH-Subagent-OAR-AGY/blob/main/README.en.md) · [Deutsch](https://github.com/jiezhengj/DSH-Subagent-OAR-AGY/blob/main/README.de.md) · [Español](https://github.com/jiezhengj/DSH-Subagent-OAR-AGY/blob/main/README.es.md) · [Français](https://github.com/jiezhengj/DSH-Subagent-OAR-AGY/blob/main/README.fr.md) · [日本語](https://github.com/jiezhengj/DSH-Subagent-OAR-AGY/blob/main/README.ja.md) · [Português](https://github.com/jiezhengj/DSH-Subagent-OAR-AGY/blob/main/README.pt.md) · [Русский](https://github.com/jiezhengj/DSH-Subagent-OAR-AGY/blob/main/README.ru.md)
+
+## 0.3.0 新增
+
+- 启动看门狗（默认 60 秒）与静默看门狗（默认 15 分钟）：AGY 卡住时以 `startup-timeout` / `stalled` 终止进程树并只通知一次。
+- 新控制工具 `subagent_oar_agy_control`：`status` 查询当前父会话的运行摘要，`cancel` 提交停止请求；工具名可用 `controlToolName` 改名。
+- 有界活动历史与状态快照：每个父会话最多 50 个运行、每个运行 20 条活动、`lastText` 最多 200 字符。
+- 安全边界：AGY 使用官方清洗后的环境变量启动；父会话诊断不含原始 stderr；本机日志脱敏。
+
+## 安装
+
+1. 打开 DeepSeek Harness 的插件管理（设置 → 插件）。
+2. 在安装输入框粘贴这一行并安装：
+
+```
+@jiezhengj/subagent-oar-agy
+```
+
+tgz 备选：`https://github.com/jiezhengj/DSH-Subagent-OAR-AGY/releases/download/v0.3.0/subagent-oar-agy-0.3.0.tgz`
+
+版本说明与完整变更见 [GitHub Release v0.3.0](https://github.com/jiezhengj/DSH-Subagent-OAR-AGY/releases/tag/v0.3.0)。
+
+3. 启用「AGY 子智能体」，新会话即可让模型调用 `subagent_oar_agy`。
+4. 安装或升级后按提示重载（必要时重启）DSH，再在新会话调用 `subagent_oar_agy`。
+
+前置条件：DSH 0.2.2-rc.1 及以上（低于 0.3.0）、本机已安装并登录 Antigravity CLI（`agy`）。本包自带运行时代码，官方 OAR 工具会从 npm 安装。也可以手动执行 `dsh plugin add @jiezhengj/subagent-oar-agy`。
+
+## 从 tgz 迁移到名称安装
+
+已通过 tgz 安装的 profile 不能直接检查更新。先在插件管理移除旧条目（或执行 `dsh plugin remove @jiezhengj/subagent-oar-agy`），再按上面的名称重新安装；插件配置通常会保留；若配置随旧条目被移除，重新填写原来的设置即可。装好后版本区应显示当前版本与「已是最新版本」，后续可在应用内检查更新。
+
+## 显示名与界面语言
+
+插件页里的正式显示名是「AGY 子智能体」，跟随 DSH 界面语言显示：
+
+| 语言 | 显示名 |
+|---|---|
+| 简体中文（zh） | AGY 子智能体 |
+| English（en） | AGY subagent |
+| Deutsch（de） | AGY-Subagent |
+| Español（es） | Subagente AGY |
+| Français（fr） | Sous-agent AGY |
+| 日本語（ja） | AGY サブエージェント |
+| Português（pt） | Subagente AGY |
+| Русский（ru） | Субагент AGY |
+
+插件页的介绍正文与详情文档同样提供这 8 种语言（`locale/<lang>.json` 的 `meta.title`/`meta.description`，以及 `docs/DETAIL.<lang>.md`）。运行时面向用户的错误、超时、取消与权限拒绝说明也会按界面语言输出：默认 `locale: auto` 跟随 DSH 的 `locale.preference` 或系统语言，也可显式设为 `de`/`en`/`es`/`fr`/`ja`/`pt`/`ru`/`zh`。
+
+## 默认是否自动执行？
+
+默认自动执行：插件以 `yolo` 档运行 agy，即传入 `--dangerously-skip-permissions`，agy 可以在你给它的工作目录中读写文件、运行命令，不再逐次询问权限。
+
+## 风险是什么？
+
+- agy 以当前用户身份运行，拥有该用户的文件与命令权限；任务提示词可能诱导它修改或删除文件。
+- 模型选择此工具后不会弹出权限确认；是否委派、委派什么内容由模型决定，最终影响由你承担。
+- agy 会把任务内容与工作目录信息发送给其模型服务（Antigravity 的政策适用）；本插件不额外收集数据，但也不改变 agy 自身的网络与遥测行为。
+- 同一目录的并发委派可能产生文件竞争（见下文）。
+
+## 如何改保守？
+
+在插件配置里改 `permissionMode`：
+
+- `plan`：只读规划，agy 只分析、不修改文件（等价于 `--mode plan`）。
+- `strict`：不传 `--dangerously-skip-permissions`，需要权限的动作被 agy 自动拒绝；插件会在结果里附上可见说明（哪个动作被拒、如何放行）。
+- `yolo`（默认）：无人值守。
+
+示例（组合包 patch 或 DSH 插件配置）：
+
+```yaml
+permissionMode: plan
+```
+
+## 安装
+
+见 [docs/INSTALL.md](./docs/INSTALL.md)。最短路径是在 DSH 插件管理页的安装框填 `@jiezhengj/subagent-oar-agy`，或执行 `dsh plugin add @jiezhengj/subagent-oar-agy`；tgz 仅作备选。
+
+## 配置项
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `providerName` | `agy` | 注册到子代理服务的运行时名 |
+| `command` | `agy` | agy 可执行文件：名称（走 PATH）或绝对路径 |
+| `model` | 空 | 传给 `agy --model` |
+| `effort` | 空 | 传给 `agy --effort` |
+| `permissionMode` | `yolo` | `yolo` / `plan` / `strict` |
+| `locale` | `auto` | 面向用户文案的语言；`auto` 跟随 DSH，或显式 `de` / `en` / `es` / `fr` / `ja` / `pt` / `ru` / `zh` |
+| `startupTimeoutMs` | `60000` | 从 spawn 到收到 agy `init` 的启动等待窗口；到期会终止进程树并以可操作诊断失败 |
+| `stallTimeoutMs` | `900000` | `init` 后连续无协议事件的静默窗口；`stderr`、非法 JSON 和普通日志不会重置它 |
+| `timeoutMs` | 不设 | 单次绝对上限，从 agy `init` 起算；与静默窗口同 tick 到期时绝对上限优先 |
+| `activityLimit` | `20` | 每次委派保留的活动摘要条数，范围 1–20 |
+| `terminalRetentionMs` | `300000` | 终态记录保留时间，默认 5 分钟 |
+| `maxRecordsPerParent` | `50` | 每个父会话最多保留的记录数，范围 1–50 |
+| `killGraceMs` | `10000` | SIGTERM 后等待退出的宽限 |
+| `controlToolName` | `subagent_oar_agy_control` | 控制工具名；属于工具行配置，官方委派工具仍用 `toolName` |
+| `env` | `{}` | 子进程环境变量覆盖，`null` 表示删除；显式值可重新提供被官方清洗移除的变量 |
+
+控制工具的调试日志走 DSH 插件日志（`ctx.logger.warn`，以 `subagent-agy <run-id>` 开头），只含脱敏摘要；不会把原始 stderr 写入父会话。
+
+
+## 状态查询与取消
+
+工具行在官方 `subagent_oar_agy` 之外注册一个控制工具 `subagent_oar_agy_control`（可用 `controlToolName` 改名）：
+
+```json
+{ "action": "status", "childId": "可选；省略时列出当前父会话的全部 AGY 运行" }
+{ "action": "cancel", "childId": "必填" }
+```
+
+`status` 只读，返回 `action`、`generatedAt`、`found` 与至多 50 个运行摘要；每个运行最多 20 条活动摘要，`lastText` 最多 200 字符，不返回完整 prompt、完整最终答复、工具参数或原始 stderr。`cancel` 只返回受理结果，实际停止与终态由 DSH 子代理服务和插件异步完成。
+
+## 可观察性与看门狗
+
+- **启动看门狗**：默认 60 秒；agy 未发出 `init` 就终止进程树，并给出 `startup-timeout` 诊断。
+- **静默看门狗**：默认 15 分钟；`init` 后没有新的协议事件（`init`、`step_update`、`result` 或生命周期边沿）就终止；持续 stderr 噪声不会掩盖卡死。
+- **绝对上限**：仍由 `timeoutMs` 控制；未配置时只依赖两个看门狗。
+- 所有路径只结算一次，并只向父会话投递一次终止通知；状态查询不会启动、恢复或继续任何委派。
+- 看门狗**没有关闭开关**。如果任务确实需要更久，调大 `startupTimeoutMs` / `stallTimeoutMs`，不要设为 0。
+
+## 安全边界
+
+AGY 子进程从官方 `scrubbedParentEnv()` 清洗后的环境启动：凭据形状变量（大小写不敏感）和 `DSH_*` 默认移除；`PATH`、`HOME`、语言与代理变量保留。只有用户在 `env` 中显式覆盖的变量才会重新提供给 agy。父会话诊断只含分类与可操作建议，原始 stderr 只写入本机脱敏日志。
+
+## 官方工具包不可用时
+
+工具行优先挂载官方 `@deepseek-ai/dsh-experimental-tool-subagent-oar`。如果该包缺失或无法解析，插件会记录警告，并回退到内置的同形一次性工具：工具名、参数、返回结构与官方一致，委派仍走本插件的 AGY 提供方。
+
+## 找不到 agy 时
+
+如果桌面环境的 PATH 不含 `~/.local/bin`，把 `command` 配成绝对路径即可：
+
+```yaml
+command: /Users/your-name/.local/bin/agy
+```
+
+## 并行与重试
+
+- **同一目录并发**：允许多个委派并行，文件竞争风险由你承担；重要任务建议分开工作目录。
+- **重试**：插件不会自动重试；失败后由你或模型显式再次发起。每次重试都会再次消耗 agy 的配额。
+
+## 工具名与共存
+
+本插件默认工具名是 **`subagent_oar_agy`**，与官方 OAR 组合包的 `subagent_oar` 天然区分，可以同时启用、互不冲突。
+
+如果你没有安装官方 OAR 组合包，又希望沿用 `subagent_oar` 这个名字，可在自己的 profile patch 中覆盖：
+
+```yaml
+- id: tool-subagent-oar-agy
+  config:
+    toolName: subagent_oar
+```
+
+反向也可：官方 OAR 已占用 `subagent_oar` 时不要覆盖，保持默认即可。
+
+## 合规声明
+
+本插件是非官方封装，不代表 Antigravity 的官方集成；使用前请自行阅读并遵守 Antigravity（Google）的服务条款。插件不索取、不存储、不转发 agy 的登录凭据，也不修改 agy 的认证状态或全局配置。
+
+## 卸载与禁用
+
+在 DSH 插件管理中禁用或移除本组合包即可；禁用或卸载后工具、提供方与看门狗一并消失；插件清理阶段会停止计时器，并终止该提供方尚未结算的 AGY 运行及其进程树，不会留下无监控进程。配置保留，重新启用后继续生效。

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# 组合包 patch：提供方 + 官方 OAR 工具（默认工具名 subagent_oar_agy，与官方 OAR 组合包的 subagent_oar 区分，可共存）。
+- insert:
+    - id: subagent-agy
+      name: "@jiezhengj/subagent-oar-agy/agy-provider"
+      config:
+        providerName: agy
+        command: agy
+        permissionMode: yolo
+    - id: tool-subagent-oar-agy
+      name: "@jiezhengj/subagent-oar-agy/tool"
+      config:
+        providers:
+          agy: agy
+        toolName: subagent_oar_agy

package/docs/DETAIL.de.md

@@ -0,0 +1,42 @@
+# Implementierungshinweise
+
+## Überblick
+
+Dieses Plugin delegiert unabhängige Aufgaben an die lokale Antigravity CLI (`agy`). Das Modell ruft `subagent_oar_agy` auf; das Plugin startet `agy --input-format stream-json --output-format stream-json`, liest den NDJSON-Ereignisstrom und liefert die endgültige Antwort an DSH zurück. Die modellseitige Form entspricht dem offiziellen OAR-Werkzeug; hier wird nur die AGY-Laufzeit ohne ACP bereitgestellt.
+
+## Voraussetzungen
+
+- Antigravity CLI (`agy`) lokal installiert und mindestens einmal angemeldet.
+- DSH 0.2.2-rc.1 oder eine kompatible Version.
+- macOS, Linux und Windows werden unterstützt (POSIX-Prozessgruppe / taskkill).
+
+## Installation und Nutzung
+
+1. Dieses Bundle in der Plugin-Seite installieren und aktivieren.
+2. In einer neuen Sitzung das Modell bitten, eine Aufgabe an AGY zu delegieren oder `subagent_oar_agy` aufzurufen.
+3. Werkzeugparameter: `runtime` (immer `agy`), `description`, `prompt`, optional `cwd`.
+
+## Berechtigungen
+
+- `yolo` (Standard): unbeaufsichtigte Ausführung.
+- `plan`: Nur-Lese-Planung ohne Schreibzugriff.
+- `strict`: Aktionen mit Berechtigungsbedarf werden von AGY automatisch abgelehnt; das Ergebnis enthält einen sichtbaren Hinweis.
+  Automatische Ablehnungen sind nie still: Sie sehen, welche Aktion abgelehnt wurde und wie Sie sie erlauben.
+
+## Daten und Datenschutz
+
+Aufgabentext wird nur an den lokalen `agy`-Prozess gesendet. Das Plugin liest, speichert oder überträgt keine AGY-Anmeldedaten und ändert keine globale Konfiguration.
+
+## Werkzeugname und Koexistenz
+
+Der Standardname ist `subagent_oar_agy` und kollidiert nicht mit `subagent_oar` aus dem offiziellen OAR-Bundle; beide können gemeinsam aktiv sein. Um `subagent_oar` zu verwenden, überschreiben Sie `toolName` im Profil-Patch.
+
+## Haftungsausschluss
+
+Dies ist eine inoffizielle Erweiterung, nicht mit DeepSeek oder Google verbunden. Nutzung auf eigenes Risiko; beachten Sie die Antigravity-Nutzungsbedingungen.
+
+## Status, watchdogs and cancellation
+
+The tool entry registers `subagent_oar_agy_control`: `status` returns a bounded snapshot of direct AGY runs (at most 50 runs, 20 activity entries each, `lastText` at most 200 characters); `cancel` only accepts a cancellation request and settles asynchronously. Defaults are a 60 s startup window, a 15 min stall window, `activityLimit=20`, `terminalRetentionMs=300000` and `maxRecordsPerParent=50`; stderr noise does not reset the stall timer. Every path settles once. There is no watchdog off switch; increase the windows instead.
+
+The child environment is the official scrubbed parent environment: credential-shaped names and `DSH_*` are removed unless explicitly supplied through `env`. Parent diagnostics never include raw stderr.

package/docs/DETAIL.en.md

@@ -0,0 +1,42 @@
+# Implementation notes
+
+## Overview
+
+This plugin delegates independent tasks to the local Antigravity CLI (`agy`). The model calls `subagent_oar_agy`; the plugin spawns `agy --input-format stream-json --output-format stream-json`, parses the NDJSON event stream, and returns the final answer to DSH. The model-facing tool reuses the official OAR tool implementation and shape; only the non-ACP AGY runtime is supplied here.
+
+## Requirements
+
+- Antigravity CLI (`agy`) installed locally and signed in at least once.
+- DSH 0.2.2-rc.1 or a compatible version.
+- macOS, Linux and Windows are supported (POSIX process-group termination / taskkill).
+
+## Install and use
+
+1. Install and enable this bundle from the plugin page.
+2. In a new session, ask the model to delegate a task to AGY, or to call `subagent_oar_agy` directly.
+3. Tool arguments: `runtime` (always `agy`), `description`, `prompt`, optional `cwd`.
+
+## Permissions
+
+- `yolo` (default): unattended execution.
+- `plan`: read-only planning, no writes.
+- `strict`: actions that need permission are auto-denied by AGY and the result carries a visible note.
+  Auto-denials are never silent: you see which action was denied and how to allow it.
+
+## Data and privacy
+
+Task text is sent only to the local `agy` process. The plugin does not read, store or forward AGY credentials or auth files, and does not modify its global configuration.
+
+## Tool name and coexistence
+
+The default tool name is `subagent_oar_agy`, which does not collide with the official OAR bundle's `subagent_oar`; both can be enabled together. To reuse `subagent_oar`, override `toolName` in your profile patch.
+
+## Disclaimer
+
+This is an unofficial wrapper, not affiliated with DeepSeek or Google. Use at your own risk and follow Antigravity's terms of service.
+
+## Status, watchdogs and cancellation
+
+The tool entry registers `subagent_oar_agy_control`: `status` returns a bounded snapshot of direct AGY runs (at most 50 runs, 20 activity entries each, `lastText` at most 200 characters); `cancel` only accepts a cancellation request and settles asynchronously. Defaults are a 60 s startup window, a 15 min stall window, `activityLimit=20`, `terminalRetentionMs=300000` and `maxRecordsPerParent=50`; stderr noise does not reset the stall timer. Every path settles once. There is no watchdog off switch; increase the windows instead.
+
+The child environment is the official scrubbed parent environment: credential-shaped names and `DSH_*` are removed unless explicitly supplied through `env`. Parent diagnostics never include raw stderr.

package/docs/DETAIL.es.md

@@ -0,0 +1,42 @@
+# Notas de implementación
+
+## Descripción
+
+Este plugin delega tareas independientes a la CLI local de Antigravity (`agy`). El modelo llama a `subagent_oar_agy`; el plugin inicia `agy --input-format stream-json --output-format stream-json`, interpreta el flujo NDJSON y devuelve la respuesta final a DSH. La forma de la herramienta reutiliza la oficial de OAR; aquí solo se aporta el runtime AGY sin ACP.
+
+## Requisitos
+
+- CLI de Antigravity (`agy`) instalada y con sesión iniciada al menos una vez.
+- DSH 0.2.2-rc.1 o una versión compatible.
+- Compatible con macOS, Linux y Windows (grupo de procesos POSIX / taskkill).
+
+## Instalación y uso
+
+1. Instala y activa este bundle desde la página de plugins.
+2. En una sesión nueva, pide al modelo que delegue una tarea a AGY o que llame a `subagent_oar_agy`.
+3. Argumentos: `runtime` (siempre `agy`), `description`, `prompt` y `cwd` opcional.
+
+## Permisos
+
+- `yolo` (predeterminado): ejecución sin supervisión.
+- `plan`: planificación de solo lectura, sin escrituras.
+- `strict`: las acciones que requieren permiso se rechazan automáticamente y el resultado incluye una nota visible.
+  Los rechazos automáticos nunca son silenciosos: verás qué acción se rechazó y cómo permitirla.
+
+## Datos y privacidad
+
+El texto de la tarea solo se envía al proceso `agy` local. El plugin no lee, almacena ni reenvía credenciales ni archivos de autenticación de AGY, y no modifica su configuración global.
+
+## Nombre de la herramienta y convivencia
+
+El nombre predeterminado es `subagent_oar_agy`, que no choca con `subagent_oar` del bundle OAR oficial; ambos pueden estar activos. Para reutilizar `subagent_oar`, sobrescribe `toolName` en el patch del perfil.
+
+## Aviso
+
+Es un envoltorio no oficial, sin relación con DeepSeek ni Google. Úsalo bajo tu responsabilidad y respeta los términos de Antigravity.
+
+## Status, watchdogs and cancellation
+
+The tool entry registers `subagent_oar_agy_control`: `status` returns a bounded snapshot of direct AGY runs (at most 50 runs, 20 activity entries each, `lastText` at most 200 characters); `cancel` only accepts a cancellation request and settles asynchronously. Defaults are a 60 s startup window, a 15 min stall window, `activityLimit=20`, `terminalRetentionMs=300000` and `maxRecordsPerParent=50`; stderr noise does not reset the stall timer. Every path settles once. There is no watchdog off switch; increase the windows instead.
+
+The child environment is the official scrubbed parent environment: credential-shaped names and `DSH_*` are removed unless explicitly supplied through `env`. Parent diagnostics never include raw stderr.

package/docs/DETAIL.fr.md

@@ -0,0 +1,42 @@
+# Notes d’implémentation
+
+## Présentation
+
+Ce plugin délègue des tâches indépendantes à la CLI Antigravity locale (`agy`). Le modèle appelle `subagent_oar_agy` ; le plugin lance `agy --input-format stream-json --output-format stream-json`, lit le flux d’événements NDJSON et renvoie la réponse finale à DSH. La forme de l’outil réutilise celle de l’OAR officiel ; seul le runtime AGY sans ACP est fourni ici.
+
+## Prérequis
+
+- CLI Antigravity (`agy`) installée localement et connectée au moins une fois.
+- DSH 0.2.2-rc.1 ou une version compatible.
+- macOS, Linux et Windows pris en charge (groupe de processus POSIX / taskkill).
+
+## Installation et utilisation
+
+1. Installez et activez ce bundle depuis la page des plugins.
+2. Dans une nouvelle session, demandez au modèle de déléguer une tâche à AGY ou d’appeler `subagent_oar_agy`.
+3. Paramètres : `runtime` (toujours `agy`), `description`, `prompt`, `cwd` facultatif.
+
+## Autorisations
+
+- `yolo` (par défaut) : exécution sans surveillance.
+- `plan` : planification en lecture seule, sans écriture.
+- `strict` : les actions nécessitant une autorisation sont refusées automatiquement et le résultat contient une note visible.
+  Les refus automatiques ne sont jamais silencieux : vous voyez l’action refusée et comment l’autoriser.
+
+## Données et confidentialité
+
+Le texte de la tâche n’est envoyé qu’au processus `agy` local. Le plugin ne lit, ne stocke et ne transmet ni identifiants ni fichiers d’authentification AGY, et ne modifie pas sa configuration globale.
+
+## Nom de l’outil et coexistence
+
+Le nom par défaut est `subagent_oar_agy`, sans collision avec `subagent_oar` du bundle OAR officiel ; les deux peuvent être actifs. Pour réutiliser `subagent_oar`, remplacez `toolName` dans le patch du profil.
+
+## Avertissement
+
+Extension non officielle, sans lien avec DeepSeek ou Google. Utilisation à vos risques ; respectez les conditions d’Antigravity.
+
+## Status, watchdogs and cancellation
+
+The tool entry registers `subagent_oar_agy_control`: `status` returns a bounded snapshot of direct AGY runs (at most 50 runs, 20 activity entries each, `lastText` at most 200 characters); `cancel` only accepts a cancellation request and settles asynchronously. Defaults are a 60 s startup window, a 15 min stall window, `activityLimit=20`, `terminalRetentionMs=300000` and `maxRecordsPerParent=50`; stderr noise does not reset the stall timer. Every path settles once. There is no watchdog off switch; increase the windows instead.
+
+The child environment is the official scrubbed parent environment: credential-shaped names and `DSH_*` are removed unless explicitly supplied through `env`. Parent diagnostics never include raw stderr.

package/docs/DETAIL.ja.md

@@ -0,0 +1,42 @@
+# 実装メモ
+
+## 概要
+
+このプラグインは独立したタスクをローカルの Antigravity CLI（`agy`）に委任します。モデルは `subagent_oar_agy` を呼び、プラグインは `agy --input-format stream-json --output-format stream-json` を起動して NDJSON イベントストリームを解析し、最終回答を DSH に返します。モデル側のツール形態は公式 OAR ツールを再利用し、ACP を使わない AGY ランタイムのみを提供します。
+
+## 要件
+
+- Antigravity CLI（`agy`）がインストール済みで、一度以上ログインしていること。
+- DSH 0.2.2-rc.1 または互換バージョン。
+- macOS、Linux、Windows に対応（POSIX プロセスグループ終了 / taskkill）。
+
+## インストールと使い方
+
+1. プラグインページからこのバンドルをインストールして有効化します。
+2. 新しいセッションで、AGY への委任または `subagent_oar_agy` の呼び出しをモデルに依頼します。
+3. 引数：`runtime`（常に `agy`）、`description`、`prompt`、任意の `cwd`。
+
+## 権限
+
+- `yolo`（既定）：無人で実行。
+- `plan`：読み取り専用の計画。書き込みなし。
+- `strict`：権限が必要な操作は AGY が自動的に拒否し、結果に可視の注記が付きます。
+  自動拒否は決して無言ではありません。拒否された操作と許可方法が表示されます。
+
+## データとプライバシー
+
+タスクのテキストはローカルの `agy` プロセスにのみ送信されます。プラグインは AGY の認証情報や認証ファイルを読み取り・保存・転送せず、グローバル設定も変更しません。
+
+## ツール名と共存
+
+既定のツール名は `subagent_oar_agy` で、公式 OAR バンドルの `subagent_oar` と衝突しないため同時に有効化できます。`subagent_oar` を使う場合はプロファイル patch で `toolName` を上書きしてください。
+
+## 免責
+
+非公式のラッパーであり、DeepSeek や Google とは関係ありません。自己責任で使用し、Antigravity の利用規約に従ってください。
+
+## Status, watchdogs and cancellation
+
+The tool entry registers `subagent_oar_agy_control`: `status` returns a bounded snapshot of direct AGY runs (at most 50 runs, 20 activity entries each, `lastText` at most 200 characters); `cancel` only accepts a cancellation request and settles asynchronously. Defaults are a 60 s startup window, a 15 min stall window, `activityLimit=20`, `terminalRetentionMs=300000` and `maxRecordsPerParent=50`; stderr noise does not reset the stall timer. Every path settles once. There is no watchdog off switch; increase the windows instead.
+
+The child environment is the official scrubbed parent environment: credential-shaped names and `DSH_*` are removed unless explicitly supplied through `env`. Parent diagnostics never include raw stderr.

package/docs/DETAIL.pt.md

@@ -0,0 +1,42 @@
+# Notas de implementação
+
+## Visão geral
+
+Este plugin delega tarefas independentes à CLI local do Antigravity (`agy`). O modelo chama `subagent_oar_agy`; o plugin inicia `agy --input-format stream-json --output-format stream-json`, interpreta o fluxo NDJSON e devolve a resposta final ao DSH. A forma da ferramenta reutiliza a do OAR oficial; aqui só é fornecido o runtime AGY sem ACP.
+
+## Requisitos
+
+- CLI do Antigravity (`agy`) instalada e com login feito ao menos uma vez.
+- DSH 0.2.2-rc.1 ou versão compatível.
+- macOS, Linux e Windows suportados (grupo de processos POSIX / taskkill).
+
+## Instalação e uso
+
+1. Instale e ative este bundle na página de plugins.
+2. Em uma nova sessão, peça ao modelo para delegar uma tarefa ao AGY ou chamar `subagent_oar_agy`.
+3. Argumentos: `runtime` (sempre `agy`), `description`, `prompt`, `cwd` opcional.
+
+## Permissões
+
+- `yolo` (padrão): execução sem supervisão.
+- `plan`: planejamento somente leitura, sem gravações.
+- `strict`: ações que exigem permissão são negadas automaticamente e o resultado traz uma nota visível.
+  Negações automáticas nunca são silenciosas: você vê qual ação foi negada e como permiti-la.
+
+## Dados e privacidade
+
+O texto da tarefa vai apenas para o processo `agy` local. O plugin não lê, armazena nem encaminha credenciais ou arquivos de autenticação do AGY, e não altera sua configuração global.
+
+## Nome da ferramenta e coexistência
+
+O nome padrão é `subagent_oar_agy`, sem colisão com `subagent_oar` do bundle OAR oficial; ambos podem ficar ativos. Para reutilizar `subagent_oar`, sobrescreva `toolName` no patch do perfil.
+
+## Aviso
+
+É um wrapper não oficial, sem vínculo com DeepSeek ou Google. Use por sua conta e risco e siga os termos do Antigravity.
+
+## Status, watchdogs and cancellation
+
+The tool entry registers `subagent_oar_agy_control`: `status` returns a bounded snapshot of direct AGY runs (at most 50 runs, 20 activity entries each, `lastText` at most 200 characters); `cancel` only accepts a cancellation request and settles asynchronously. Defaults are a 60 s startup window, a 15 min stall window, `activityLimit=20`, `terminalRetentionMs=300000` and `maxRecordsPerParent=50`; stderr noise does not reset the stall timer. Every path settles once. There is no watchdog off switch; increase the windows instead.
+
+The child environment is the official scrubbed parent environment: credential-shaped names and `DSH_*` are removed unless explicitly supplied through `env`. Parent diagnostics never include raw stderr.

package/docs/DETAIL.ru.md

@@ -0,0 +1,42 @@
+# Заметки о реализации
+
+## Обзор
+
+Плагин передаёт независимые задачи локальному Antigravity CLI (`agy`). Модель вызывает `subagent_oar_agy`; плагин запускает `agy --input-format stream-json --output-format stream-json`, разбирает поток событий NDJSON и возвращает итоговый ответ в DSH. Форма инструмента повторяет официальный OAR; здесь реализована только среда выполнения AGY без ACP.
+
+## Требования
+
+- Antigravity CLI (`agy`) установлен локально и хотя бы раз выполнен вход.
+- DSH 0.2.2-rc.1 или совместимая версия.
+- Поддерживаются macOS, Linux и Windows (группа процессов POSIX / taskkill).
+
+## Установка и использование
+
+1. Установите и включите этот бандл на странице плагинов.
+2. В новой сессии попросите модель передать задачу в AGY или вызвать `subagent_oar_agy`.
+3. Параметры: `runtime` (всегда `agy`), `description`, `prompt`, необязательный `cwd`.
+
+## Разрешения
+
+- `yolo` (по умолчанию): выполнение без присмотра.
+- `plan`: планирование только для чтения, без записи.
+- `strict`: действия, требующие разрешения, автоматически отклоняются, а результат содержит видимое примечание.
+  Автоматические отказы никогда не безмолвны: видно, какое действие отклонено и как его разрешить.
+
+## Данные и конфиденциальность
+
+Текст задачи отправляется только локальному процессу `agy`. Плагин не читает, не хранит и не передаёт учётные данные и файлы аутентификации AGY, не изменяет его глобальную конфигурацию.
+
+## Имя инструмента и совместимость
+
+Имя по умолчанию — `subagent_oar_agy`, оно не конфликтует с `subagent_oar` из официального OAR-бандла; оба могут быть включены. Чтобы использовать `subagent_oar`, переопределите `toolName` в патче профиля.
+
+## Отказ от ответственности
+
+Это неофициальная обёртка, не связанная с DeepSeek или Google. Используйте на свой риск и соблюдайте условия Antigravity.
+
+## Status, watchdogs and cancellation
+
+The tool entry registers `subagent_oar_agy_control`: `status` returns a bounded snapshot of direct AGY runs (at most 50 runs, 20 activity entries each, `lastText` at most 200 characters); `cancel` only accepts a cancellation request and settles asynchronously. Defaults are a 60 s startup window, a 15 min stall window, `activityLimit=20`, `terminalRetentionMs=300000` and `maxRecordsPerParent=50`; stderr noise does not reset the stall timer. Every path settles once. There is no watchdog off switch; increase the windows instead.
+
+The child environment is the official scrubbed parent environment: credential-shaped names and `DSH_*` are removed unless explicitly supplied through `env`. Parent diagnostics never include raw stderr.

package/docs/DETAIL.zh.md

@@ -0,0 +1,40 @@
+# 实现说明
+
+## 概述
+
+本插件把独立任务委派给本机 Antigravity CLI（`agy`）。模型通过 `subagent_oar_agy` 工具发起委派，插件启动 `agy --input-format stream-json --output-format stream-json` 子进程，解析 NDJSON 事件流，把终态答复交回 DSH。模型侧复用官方 OAR 工具的实现与参数形态，插件只提供非 ACP 的 AGY 运行时。
+
+## 要求
+
+- 本机已安装 Antigravity CLI（`agy`），并至少完成一次交互登录。
+- DSH 0.2.2-rc.1 或兼容版本。
+- 支持 macOS、Linux 与 Windows（POSIX 进程组终止 / taskkill）。
+
+## 安装与使用
+
+1. 在插件页安装并启用本组合包。
+2. 新会话中让模型把任务交给 AGY，或直接要求调用 `subagent_oar_agy`。
+3. 工具参数：`runtime`（固定 `agy`）、`description`、`prompt`、可选 `cwd`。
+
+## 权限
+
+- `yolo`（默认）：无人值守执行。
+- `plan`：只读规划，不写入。
+- `strict`：需要权限的动作由 AGY 自动拒绝，结果中会附可见说明。
+  权限档被自动拒绝时不会静默失败，你会看到被拒绝的动作与放行方法。
+
+## 状态、看门狗与取消
+
+插件注册 `subagent_oar_agy_control`：`status` 返回当前父会话的有限运行摘要（至多 50 个运行、每个至多 20 条活动、`lastText` 至多 200 字符），`cancel` 只受理取消并异步结算。默认启动窗口 60 秒、静默窗口 15 分钟、`activityLimit=20`、`terminalRetentionMs=300000`、`maxRecordsPerParent=50`；持续 stderr 噪声不会重置静默计时。所有路径只结算一次。看门狗没有关闭开关，只能调大窗口。
+
+## 数据与隐私
+
+任务文本只发送给本机 `agy` 进程；插件不读取、不存储、不转发 AGY 的凭据或认证文件，也不修改其全局配置。AGY 子进程只继承官方清洗后的环境变量：凭据形状变量与 `DSH_*` 默认移除，`env` 显式覆盖可重新提供。父会话失败诊断不含原始 stderr。
+
+## 工具名与共存
+
+默认工具名是 `subagent_oar_agy`，与官方 OAR 组合包的 `subagent_oar` 互不冲突，可同时启用。如需沿用 `subagent_oar`，可在 profile patch 中覆盖 `toolName`。
+
+## 声明
+
+本插件是非官方封装，与 DeepSeek、Google 均无隶属关系；使用风险自担，请遵守 Antigravity 的服务条款。

package/docs/INSTALL.md

@@ -0,0 +1,40 @@
+# 安装与升级
+
+## 前置条件
+
+- DeepSeek Harness 0.2.2-rc.1 或更高（组合包 `engines.dsh` 为 `>=0.2.2-rc.1 <0.3.0`）。
+- 本机已安装并登录 Antigravity CLI（agy 1.5 及以上），终端里能以 `agy` 或绝对路径运行。
+
+## 0.3.0 升级提示
+
+从 0.2.8 升级到 0.3.0 后，`subagent_oar_agy_control` 需要在新会话中才会出现在工具表；官方 `subagent_oar_agy` 的 schema 不变。升级会保留现有配置。
+
+## 安装
+
+1. 在 DSH 插件管理中安装组合包，安装输入框填包名：`@jiezhengj/subagent-oar-agy`（主路径，支持后续检查更新）。
+   - tgz 备选：`https://github.com/jiezhengj/DSH-Subagent-OAR-AGY/releases/download/v0.3.0/subagent-oar-agy-0.3.0.tgz`
+   - 或本地 tarball：`dsh plugin add /path/to/subagent_oar_agy-<version>.tgz`
+2. 在插件列表启用「AGY 子智能体」（包名 `@jiezhengj/subagent-oar-agy`），按提示重载（必要时重启 DSH）；模型工具列表出现 `subagent_oar_agy`。
+3. 安装或升级完成后，在新会话调用 `subagent_oar_agy` 验证工具可用；新增的 `subagent_oar_agy_control` 也需要新会话/重载后才出现在工具表，控制工具不会修改官方委派工具的 schema。
+
+安装后默认 `permissionMode: yolo`，如不希望自动执行，先改成 `plan` 或 `strict` 再启用（见 README）。
+
+## 从 tgz 迁移到名称安装
+
+已通过 tgz 安装的 profile 不能直接检查更新。先在插件管理移除旧条目（或执行 `dsh plugin remove @jiezhengj/subagent-oar-agy`），再按上面的名称重新安装；插件配置通常会保留；若配置随旧条目被移除，重新填写原来的设置即可。装好后版本区应显示当前版本与「已是最新版本」，后续可在应用内检查更新。
+
+## 升级
+
+按名称安装后，可在插件管理的版本区检查更新并一键升级；升级后配置保留，无需重新填写。升级后建议做一次最小委派验证；官方 OAR 工具包版本在本组合包内精确锁定，随组合包一起升级。
+
+## 禁用与重新启用
+
+禁用组合包后，`subagent_oar_agy`、`subagent_oar_agy_control` 工具与 `agy` 提供方一并移除；插件清理阶段会停止看门狗计时器，并终止该提供方尚未结算的 AGY 运行及其进程树。DSH 其他功能不受影响，重新启用后原配置继续生效。
+
+## 工具名冲突
+
+本插件默认工具名是 `subagent_oar_agy`，与官方 OAR 组合包的 `subagent_oar` 不冲突，可同时启用。若你希望本插件也用 `subagent_oar`（仅在没有官方 OAR 时），按 README 覆盖 `toolName`；DSH 对重复工具名会明确报错并拒绝注册第二个，不会静默覆盖。
+
+## 卸载
+
+`dsh plugin remove @jiezhengj/subagent-oar-agy`（或在插件管理中移除）。卸载不会修改 agy 的安装、登录状态或配置。

package/icon.svg

@@ -0,0 +1,10 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="AGY">
+  <defs>
+    <linearGradient id="agy-mark" x1="18" y1="5" x2="18" y2="31" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#5BA8FF"/>
+      <stop offset="1" stop-color="#1D4ED8"/>
+    </linearGradient>
+  </defs>
+  <path fill-rule="evenodd" clip-rule="evenodd" d="M18 5.5 29.5 30.5H23.6L21.6 25.8H14.4L12.4 30.5H6.5L18 5.5ZM18 14.8 15.2 21.6H20.8L18 14.8Z" fill="url(#agy-mark)"/>
+  <circle cx="27.8" cy="8.2" r="2.6" fill="#F472B6"/>
+</svg>

package/locale/de.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "AGY-Subagent",
+    "description": "Unabhängige Aufgaben an die lokale Antigravity CLI (agy) delegieren: Das Modell ruft subagent_oar_agy auf, das Plugin startet einen agy-Unterprozess und liefert die endgültige Antwort. Nutzt die offizielle OAR-Tool-Form mit einer AGY-Laufzeit ohne ACP; koexistiert mit dem offiziellen OAR-Bundle.",
+    "detail": "docs/DETAIL.de.md"
+  }
+}

package/locale/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "AGY subagent",
+    "description": "Delegate independent tasks to the local Antigravity CLI (agy): the model calls subagent_oar_agy, the plugin runs an agy subprocess and returns the final answer. Reuses the official OAR tool shape with a non-ACP AGY runtime; coexists with the official OAR bundle.",
+    "detail": "docs/DETAIL.en.md"
+  }
+}

package/locale/es.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Subagente AGY",
+    "description": "Delega tareas independientes a la CLI local de Antigravity (agy): el modelo llama a subagent_oar_agy, el plugin ejecuta un subproceso agy y devuelve la respuesta final. Reutiliza la forma de la herramienta OAR oficial con un runtime AGY sin ACP; convive con el bundle OAR oficial.",
+    "detail": "docs/DETAIL.es.md"
+  }
+}

package/locale/fr.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Sous-agent AGY",
+    "description": "Déléguez des tâches indépendantes à la CLI Antigravity locale (agy) : le modèle appelle subagent_oar_agy, le plugin lance un sous-processus agy et renvoie la réponse finale. Réutilise la forme de l’outil OAR officiel avec un runtime AGY sans ACP ; coexiste avec le bundle OAR officiel.",
+    "detail": "docs/DETAIL.fr.md"
+  }
+}