@hybridlabor-api/aos 4.13.2 → 4.14.1

package/THIRD_PARTY_NOTICES.md

@@ -309,7 +309,7 @@ dependency.
 
 <https://github.com/BuilderIO/skills> — MIT. Copyright (c) 2026 Builder.io.
 
-One skill adapted into `skills/global_config/read-the-damn-docs/SKILL.md`:
+Eleven skills are adapted under `skills/global_config/`: `read-the-damn-docs`, `stay-within-limits`, `quick-recap`, `plan-arbiter`, `factory-human-digest`, `factory-collect`, `factory-lookback`, `factory-review-prs`, `visual-plan`, `visual-recap`, and `visual-edit`. The four Factory skills and `plan-arbiter` have `installer-group` dropped and `category`/`source` added; in `factory-collect`, `factory-lookback` and `factory-review-prs` reply, close, approve, merge and publish actions are reduced to drafts or readiness reports that need the user's GO, and all of them carry an "AOS safety rules" section. `plan-arbiter` drops `agents/openai.yaml` and adds an AOS section on double plans. `stay-within-limits` and `quick-recap` are carried over with `category:` and `source:` added; `stay-within-limits` pins `ccusage` to 20.0.26 instead of `@latest`, and `quick-recap` no longer asks the installer to inject a managed `AGENTS.md` / `CLAUDE.md` block. The three visual skills (`visual-plan`, `visual-recap`, `visual-edit`) are optional and drive the Agent-Native Plan/Design services through MCP connectors (`plan` and `design`) that AOS does NOT register; you connect them yourself if needed. Each carries an "AOS notes" section. `read-the-damn-docs` is described below:
 the docs-first trigger list, the source hierarchy, the required workflow, the
 must-trigger examples, and the "if docs are unavailable" rule. AOS additionally
 adds a Verification section, a `category:` key (Builder's own validator forbids
@@ -318,8 +318,8 @@ guesswork* rule, and a pointer to the installed `firecrawl-search` /
 `firecrawl-scrape` tools. Prose only — the upstream `agents/openai.yaml` and
 README were not carried over, and no executable from the repo is referenced.
 
-The other 22 skills in that repo are **not** vendored. Six of them
-(`visual-plan`, `visual-recap`, `visual-edit`, `an`, `turn-into-app`, `rewind`)
+In the three visual skills, five path-like mentions (`/sign-in`, `/live-edit-bridge`, `/read-file`, `/write-file`, `/visualize-repo`) were reworded so the AOS validator does not read them as skill references. The other 13 skills in that repo (as of commit 0dba9ef) are **not** vendored. Three of them
+(`an`, `turn-into-app`, `rewind`) plus three others
 are build artefacts synced from a different upstream by
 `scripts/sync-agent-native-skills.mjs`, and the repo's own documentation says
 not to treat them as standalone. Its `.mcp.json` and plugin manifests register
@@ -511,3 +511,19 @@ 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.
 ```
+
+---
+
+## keli-wen/agentic-harness-patterns-skill
+
+- **Upstream:** <https://github.com/keli-wen/agentic-harness-patterns-skill> (commit 17549f5)
+- **License:** MIT
+- **Copyright:** Copyright (c) 2026
+
+Ported to `skills/global_config/agentic-harness-patterns/` (English variant only; the `-zh` variant is not shipped):
+
+| File | Upstream source |
+|---|---|
+| `skills/global_config/agentic-harness-patterns/SKILL.md` | `skills/agentic-harness-patterns/SKILL.md` (frontmatter: added `category` and `metadata`) |
+| `skills/global_config/agentic-harness-patterns/metadata.json` | `skills/agentic-harness-patterns/metadata.json` |
+| `skills/global_config/agentic-harness-patterns/references/**` | `skills/agentic-harness-patterns/references/**` (unchanged) |

package/bin/aos-acp.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// aos-acp — minimal ACP (Agent Client Protocol) client for the master-session
+// skill. Spawns one ACP agent over stdio JSON-RPC, runs one prompt, streams the
+// agent's text to stdout and a JSONL run log, and maps session/request_permission
+// onto the AOS GO gate: guarded commands (same list as go-gate.mjs) are approved
+// only with a valid GO token (~/.aos/go/<name>.token), everything else follows
+// --allow-default (deny unless told otherwise). No AO daemon, no dependencies.
+//
+//   aos-acp <claude|codex|opencode|agy> --name <worker> [--cwd <dir>]
+//           (--prompt "<text>" | --prompt-file <f>) [--allow-default deny|allow]
+//           [--go-wait <sec>] [--consume|--no-consume] [--log <file>]
+//           [--timeout <sec>] [--cmd "<custom agent command>"]
+
+import { spawn } from "node:child_process";
+import { appendFileSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+import { GUARDED_PATTERNS, slug, tokenGrantsGo } from "../.claude/hooks/go-gate.mjs";
+
+export const ADAPTERS = {
+  claude: { cmd: ["npx", "-y", "@agentclientprotocol/claude-agent-acp"], consume: false },
+  codex: { cmd: ["npx", "-y", "@agentclientprotocol/codex-acp"], consume: true },
+  opencode: { cmd: ["opencode", "acp"], consume: false, cwdFlag: "--cwd" },
+  // antigravity-acp (MIT) is third-party; its README states that driving agy
+  // through it breaches Google's Antigravity terms. Not shipped: use mcsc.
+  agy: null,
+};
+
+export function commandOf(toolCall = {}) {
+  const r = toolCall.rawInput || {};
+  const c = r.command ?? r.cmd ?? r.script ?? r.CommandLine ?? "";
+  return Array.isArray(c) ? c.join(" ") : typeof c === "string" ? c : "";
+}
+
+export function isGuarded(cmd) {
+  return GUARDED_PATTERNS.some((re) => re.test(cmd));
+}
+
+function pickOption(options, kinds) {
+  for (const k of kinds) {
+    const o = options.find((x) => x.kind === k);
+    if (o) return o.optionId;
+  }
+  return null;
+}
+
+// Returns the JSON-RPC result for a session/request_permission.
+export async function decidePermission(params, opts, log = () => {}) {
+  const options = params.options || [];
+  const cmd = commandOf(params.toolCall);
+  const guarded = !!cmd && isGuarded(cmd);
+  let allow = opts.allowDefault === "allow";
+  let reason = `default ${opts.allowDefault}`;
+  if (guarded) {
+    const deadline = Date.now() + (opts.goWait || 0) * 1000;
+    let r = tokenGrantsGo(opts.name, { consume: opts.consume });
+    if (!r.ok && opts.goWait) log("permission_pending", { command: cmd, waiting_s: opts.goWait });
+    while (!r.ok && Date.now() < deadline) {
+      await new Promise((res) => setTimeout(res, 1000));
+      r = tokenGrantsGo(opts.name, { consume: opts.consume });
+    }
+    allow = r.ok;
+    reason = r.ok ? "GO token" : r.reason;
+  }
+  const optionId = allow
+    ? pickOption(options, ["allow_once", "allow_always"])
+    : pickOption(options, ["reject_once", "reject_always"]);
+  log("permission", { command: cmd || null, title: params.toolCall?.title, guarded, allow, reason, optionId });
+  return optionId ? { outcome: { outcome: "selected", optionId } } : { outcome: { outcome: "cancelled" } };
+}
+
+export class AcpClient {
+  constructor(cmd, { cwd, env, onNotify, onRequest, log }) {
+    this.pending = new Map();
+    this.nextId = 1;
+    this.log = log;
+    this.child = spawn(cmd[0], cmd.slice(1), { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+    this.child.stderr.on("data", (d) => log("agent_stderr", { text: String(d).trimEnd() }));
+    this.exited = new Promise((res) => this.child.on("exit", (code, sig) => {
+      for (const p of this.pending.values()) p.reject(new Error(`agent exited (${code ?? sig})`));
+      res(code);
+    }));
+    createInterface({ input: this.child.stdout }).on("line", async (line) => {
+      let msg;
+      try { msg = JSON.parse(line); } catch { return log("agent_stdout", { text: line }); }
+      if (msg.method && msg.id !== undefined) {
+        try {
+          const result = await onRequest(msg.method, msg.params || {});
+          this.write({ jsonrpc: "2.0", id: msg.id, result });
+        } catch (e) {
+          this.write({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: e.message } });
+        }
+      } else if (msg.method) {
+        onNotify(msg.method, msg.params || {});
+      } else if (this.pending.has(msg.id)) {
+        const p = this.pending.get(msg.id);
+        this.pending.delete(msg.id);
+        msg.error ? p.reject(new Error(`${msg.error.code}: ${msg.error.message}`)) : p.resolve(msg.result);
+      }
+    });
+  }
+  write(obj) { this.child.stdin.write(JSON.stringify(obj) + "\n"); }
+  request(method, params) {
+    const id = this.nextId++;
+    this.log("send", { method, params });
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.write({ jsonrpc: "2.0", id, method, params });
+    });
+  }
+  notify(method, params) { this.write({ jsonrpc: "2.0", method, params }); }
+}
+
+function textOf(block) {
+  return block && block.type === "text" ? block.text : "";
+}
+
+export async function run(opts) {
+  const logFile = opts.log || join(homedir(), ".aos", "acp", `${slug(opts.name)}.jsonl`);
+  mkdirSync(dirname(logFile), { recursive: true });
+  const log = (event, data = {}) => {
+    try { appendFileSync(logFile, JSON.stringify({ ts: new Date().toISOString(), name: opts.name, event, ...data }) + "\n"); } catch { /* best effort */ }
+  };
+
+  const adapter = ADAPTERS[opts.adapter];
+  const cmd = opts.cmd ? ["sh", "-c", opts.cmd] : adapter?.cmd;
+  if (!cmd) throw new Error(opts.adapter === "agy"
+    ? "agy has no sanctioned ACP adapter (antigravity-acp breaches Google's Antigravity terms); delegate via the mcsc skill instead"
+    : `unknown adapter "${opts.adapter}" (claude|codex|opencode)`);
+  if (adapter?.cwdFlag && !opts.cmd) cmd.push(adapter.cwdFlag, opts.cwd);
+  const consume = opts.consume ?? adapter?.consume ?? true;
+  log("start", { adapter: opts.adapter, cmd: cmd.join(" "), cwd: opts.cwd, allow_default: opts.allowDefault, consume });
+
+  let sessionId;
+  const out = opts.stdout || process.stdout;
+  const client = new AcpClient(cmd, {
+    cwd: opts.cwd,
+    env: { ...process.env, AOS_SESSION_NAME: opts.name, AOS_ACP_CLIENT: "1" },
+    log,
+    onNotify: (method, p) => {
+      if (method !== "session/update") return log("notify", { method, params: p });
+      const u = p.update || {};
+      if (u.sessionUpdate === "agent_message_chunk") {
+        const t = textOf(u.content);
+        if (t) { out.write(t); log("text", { text: t }); }
+      } else if (u.sessionUpdate === "tool_call" || u.sessionUpdate === "tool_call_update") {
+        log(u.sessionUpdate, { id: u.toolCallId, title: u.title, kind: u.kind, status: u.status, command: commandOf(u) || undefined });
+      } else log("update", { kind: u.sessionUpdate });
+    },
+    onRequest: (method, p) => {
+      if (method === "session/request_permission") return decidePermission(p, { ...opts, consume }, log);
+      throw new Error(`client does not implement ${method}`);
+    },
+  });
+
+  const cancel = () => { if (sessionId) client.notify("session/cancel", { sessionId }); setTimeout(() => client.child.kill("SIGKILL"), 5000).unref(); };
+  process.once("SIGINT", cancel);
+  process.once("SIGTERM", cancel);
+  const timer = opts.timeout ? setTimeout(() => { log("timeout", {}); cancel(); }, opts.timeout * 1000) : null;
+
+  try {
+    const init = await client.request("initialize", {
+      protocolVersion: 1,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+      clientInfo: { name: "aos-acp", version: "0.1.0" },
+    });
+    log("initialized", { agent: init?.agentInfo, auth: init?.authMethods });
+    ({ sessionId } = await client.request("session/new", { cwd: opts.cwd, mcpServers: [] }));
+    log("session", { sessionId });
+    const res = await client.request("session/prompt", { sessionId, prompt: [{ type: "text", text: opts.prompt }] });
+    out.write("\n");
+    log("done", { stopReason: res?.stopReason });
+    return res?.stopReason === "end_turn" ? 0 : 1;
+  } catch (e) {
+    log("error", { message: e.message });
+    throw e;
+  } finally {
+    if (timer) clearTimeout(timer);
+    client.child.kill();
+  }
+}
+
+export function parseArgs(argv) {
+  const o = { adapter: argv[0], cwd: process.cwd(), allowDefault: "deny", goWait: 0 };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i], v = argv[i + 1];
+    if (a === "--name") o.name = v, i++;
+    else if (a === "--cwd") o.cwd = v, i++;
+    else if (a === "--prompt") o.prompt = v, i++;
+    else if (a === "--prompt-file") o.prompt = readFileSync(v, "utf8"), i++;
+    else if (a === "--allow-default") o.allowDefault = v, i++;
+    else if (a === "--go-wait") o.goWait = Number(v), i++;
+    else if (a === "--timeout") o.timeout = Number(v), i++;
+    else if (a === "--log") o.log = v, i++;
+    else if (a === "--cmd") o.cmd = v, i++;
+    else if (a === "--consume") o.consume = true;
+    else if (a === "--no-consume") o.consume = false;
+    else throw new Error(`unknown argument ${a}`);
+  }
+  if (!o.adapter || !o.name || !o.prompt) throw new Error("usage: aos-acp <claude|codex|opencode> --name <worker> --prompt <text> [--cwd <dir>] [--allow-default deny|allow] [--go-wait <sec>] [--no-consume] [--log <file>] [--timeout <sec>]");
+  if (!["deny", "allow"].includes(o.allowDefault)) throw new Error("--allow-default must be deny or allow");
+  return o;
+}
+
+const invokedAs = (() => { try { return realpathSync(process.argv[1] || ""); } catch { return ""; } })();
+if (invokedAs === fileURLToPath(import.meta.url)) {
+  Promise.resolve().then(() => run(parseArgs(process.argv.slice(2))))
+    .then((code) => process.exit(code), (e) => { console.error(`aos-acp: ${e.message}`); process.exit(2); });
+}

package/bin/aos-doctor.mjs

@@ -201,7 +201,7 @@ function checkHarnesses() {
 // ---------------------------------------------------------------- 4. Hooks & Security Gates
 function checkHooks() {
   const claudeHooksDir = h('.claude', 'hooks');
-  const EXPECTED_VERSION = { 'memb-inject.mjs': 6 };
+  const EXPECTED_VERSION = { 'memb-inject.mjs': 7 };
   const versionOf = (text) => {
     const m = /^\/\/\s*aos-hook-version:\s*(\d+)/m.exec(text);
     return m ? Number(m[1]) : null;

package/bin/aos-uninstall.mjs

@@ -45,7 +45,7 @@ const DATA_PATHS = [
 
 const AGENTS = [
   'com.bdb.memb.webui', 'com.bdb.synapse', 'com.bdb.openwiki.daemon',
-  'com.bdb.ao.daemon', 'com.bdb.agent-workspace', 'com.hybridlabor.bdb-remote',
+  'com.bdb.ao.daemon', 'com.bdb.agent-workspace', 'com.hybridlabor.bdb-remote', 'com.bdb.plan-canvas',
 ];
 
 const MODULE_DIRS = ['memB', 'bdb-synapse', 'bdb-os-remote', 'bdb-dev-creator-extension',
@@ -244,7 +244,7 @@ function execute(p) {
   if (existsSync(settings)) {
     try {
       const s = JSON.parse(readFileSync(settings, 'utf8'));
-      const bdb = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
+      const bdb = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'trail-autostart.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
       let touched = false;
       for (const [event, entries] of Object.entries(s.hooks || {})) {
         const kept = entries.filter((e) => !(e.hooks || []).some((x) => bdb.some((n) => String(x.command).includes(n))));

package/docs/master-session-acp.md

@@ -0,0 +1,51 @@
+# Master session over ACP — phase 2 (implemented)
+
+Status: `bin/aos-acp.mjs` ships. Facts below are tagged **[verified]** (checked against the ACP v1 schema, the adapter repos, or a live run on 2026-10-01) or **[open]**.
+
+## Goal
+
+Let a master session (`skills/basic/master-session/SKILL.md`) start and steer Codex, OpenCode and Claude workers **without the AO daemon**, by acting as an ACP client itself. The AO daemon stays optional.
+
+## Protocol facts used
+
+From `schema/v1/schema.json` + `meta.json` of agentclientprotocol/agent-client-protocol **[verified]**:
+
+- Agent methods: `initialize` (`protocolVersion: 1`, `clientCapabilities`), `session/new` (`cwd`, `mcpServers` — both required; result `sessionId`), `session/prompt` (`sessionId`, `prompt: ContentBlock[]`; result `stopReason` ∈ `end_turn | max_tokens | max_turn_requests | refusal | cancelled`), `session/cancel` (notification).
+- Client methods: `session/update` (notification; `update.sessionUpdate` ∈ `agent_message_chunk | agent_thought_chunk | tool_call | tool_call_update | plan | available_commands_update | usage_update | ...`, text in `update.content.text`), `session/request_permission` (request; `toolCall {toolCallId,title,kind,rawInput}`, `options [{optionId,name,kind: allow_once|allow_always|reject_once|reject_always}]`; answer `{outcome:{outcome:'selected',optionId}}` or `{outcome:{outcome:'cancelled'}}`), plus `fs/*` and `terminal/*`, which `aos-acp` does not advertise and answers with `-32601`.
+
+## Adapters
+
+| Harness | Command | Live smoke (`reply with OK`, temp dir) | Inner AOS gate | Token consumed by |
+|---|---|---|---|---|
+| opencode | `opencode acp --cwd <dir>` (opencode 1.18.30) | **[verified]** `OK`, `end_turn` | OpenCode plugin `bdb-aos.js` (loads in ACP mode; `--pure` would disable it) | plugin (`aos-acp` verifies only) |
+| claude | `npx -y @agentclientprotocol/claude-agent-acp` (Apache-2.0) | **[verified]** `OK`, `end_turn` | the user's Claude Code hooks run inside the SDK session — `go-gate` blocked a `git push` **[verified]** | hook (`aos-acp` verifies only) |
+| codex | `npx -y @agentclientprotocol/codex-acp` (Apache-2.0, v2.1.0) | handshake **[verified]**; `session/new` → `-32000 Authentication required` (no `OPENAI_API_KEY`/ChatGPT login on this machine) **[open]** | none | `aos-acp` |
+| agy | — | — | go-gate via `hooks.json` (name from `AOS_SESSION_NAME`) | — |
+
+agy: the only adapter is third-party `shubzkothekar/antigravity-acp` (MIT). Its README quotes Google's Antigravity terms ("using third party software ... to access the Service ... is a breach") and warns of account suspension **[verified]**. Not shipped; `aos-acp agy` exits 2 and points to the `mcsc` skill. Revisit if Google ships an official ACP endpoint.
+
+## Permission requests and the GO gate
+
+`session/request_permission` → `decidePermission()` in `bin/aos-acp.mjs`:
+
+| Case | Answer |
+|---|---|
+| `rawInput.command` matches the go-gate list (`git push`, `npm publish`, `npm version`, `gh pr merge`, `gh release create`, `git reset --hard`, `git clean -f`, recursive `rm`) | `allow_once` only if `tokenGrantsGo(name)` (imported from `.claude/hooks/go-gate.mjs`: `~/.aos/go/<name>.token`, < 10 min, names this worker, master transcript still ends with `GO <name>`). `--go-wait <sec>` polls for the token and logs `permission_pending` meanwhile — that is the `GO needed` row on the GO board. Otherwise `reject_once`. |
+| anything else | `--allow-default deny|allow` (deny). |
+| no option of the wanted kind | `allow_always`/`reject_always` as fallback, else `cancelled`. |
+
+Rules that carry over unchanged: the master never grants GO, never runs a denied action itself, a relayed or chat message is never approval, one GO releases one request.
+
+Double gate: opencode and claude workers also run their own AOS gate inside the agent process, and `aos-acp` passes `AOS_SESSION_NAME=<name>` so that gate finds the same token. Only one side may delete the token, so `aos-acp` defaults to `--no-consume` for those two and `--consume` for codex; override with the flags. The OpenCode plugin (`.opencode/plugins/bdb-aos.js`) accepts the token (name from `AOS_SESSION_NAME`, else the session title) with the same rules, copied inline because the plugin is installed as a single file.
+
+## Run log
+
+`~/.aos/acp/<name>.jsonl` (override `--log`): `start`, `send`, `initialized`, `session`, `text`, `tool_call`, `tool_call_update`, `permission_pending`, `permission`, `done`, `error`, `agent_stderr`. The master builds its roster and GO board for ACP workers from these files; `ListAgents` does not see them.
+
+## Open points
+
+- Codex live run not verified (auth). With `OPENAI_API_KEY` or a ChatGPT login it should pass the same smoke.
+- The Claude token path end to end needs the installed `~/.claude/hooks/go-gate.mjs` to be the version with `tokenGrantsGo` (installer copies it); the copy on the test machine predates it, so the live chain was only verified up to "the hook fires inside the SDK session".
+- OpenCode token path end to end needs the installed plugin updated; verified by unit test only.
+- Neither live adapter sent `session/request_permission` for a shell command in the smoke runs (the inner gate answered first); the mapping is covered by the fake-agent tests.
+- One `aos-acp` process per worker; no resume (`session/load`) and no concurrency cap yet.