@hybridlabor-api/aos 4.7.0 → 4.7.2

package/skills/global_config/ask-tim/SKILL.md

@@ -41,6 +41,16 @@ Reach for `test-driven-development` or `tdd-workflow` on their own when you want
 
 **Forcing a specific skill into a run:** `--skill=<name>` on any startcycle variant makes it a hard requirement — for a private skill of your own no node would otherwise reach for. Validated before the run starts; a name that does not resolve halts rather than proceeding without it.
 
+## Outside the core: the ECC store
+
+When no native AOS skill fits, search the markdown-only ECC store before starting a pipeline:
+
+- `aos store search <query>` finds available fallback skills and agents.
+- `aos store install <name> --net` installs a verified item after explicit user action.
+- `aos store list --type=skills` and `aos store list --type=agents` show the catalogue.
+- The core remains the trusted AOS skill set; the store is a fallback, not a reason to bypass the startcycle validation.
+- A missing `--skill` is reported by the dispatcher with the exact install command. It never downloads during a run.
+
 ---
 
 ## On-ramps

package/skills/global_config/mcsc/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: mcsc
+description: Delegate a task to another installed CLI harness (Antigravity/agy, OpenCode, Codex) from inside an AOS repo. Use this instead of shelling out to that CLI directly whenever one is installed — it wraps the wrapper flags for you and streams live tool-call telemetry to agenttrail, which is why the board updates in real time. Reach for it any time you're about to delegate work to another harness.
+category: bdb-core
+metadata:
+  version: "0.1.0"
+---
+
+# mcsc — Multi-CLI Subagent Configurator
+
+mcsc (`mcps/mcsc/`) is AOS's own cross-harness delegation engine. It is the
+mandatory path for delegating work to another CLI harness inside an
+AOS-installed repo — not a Claude-Code-only convenience.
+
+## Why this exists
+
+Three separate, harness-specific delegation paths already exist (the Claude
+Code plugins `antigravity:antigravity-delegate`, `opencode:opencode-rescue`,
+`codex:codex-rescue` — see AGENTS.md's "Delegating to an external CLI"). Those
+are fine for interactive delegation *from a Claude Code session*, but they are
+Claude-Code-only, and none of them tell agenttrail's live board what is
+happening. mcsc's adapters
+(`mcps/mcsc/packages/core/src/adapters/{agy,codex,opencode}.js`) wrap each CLI
+once, work from any harness, and call `emitTrail()` around every delegated run
+— `SessionStart`/`SessionEnd`, plus live `PreToolUse`/`PostToolUse` where the
+underlying CLI supports structured/streaming output — so a delegated run shows
+up on the board the moment it starts, without any extra setup.
+
+Skipping mcsc doesn't just lose convenience — it makes the delegated agent
+invisible to anyone watching the live map, and to anyone in this repo who asks
+"what are the other agents doing right now."
+
+## How to use it
+
+Once installed (`mcsc` in `mcp_config.json`, entry point
+`mcps/mcsc/server.js`), it registers up to four MCP tools — one per
+installed CLI, only exposed when that CLI is detected as `ready` in the local
+inventory, and never offered back to a caller that's already running as that
+same CLI (`MCSC_CALLER` env var, avoids self-delegation loops):
+
+- `delegate_agy` — `{ prompt, model? }` → Antigravity / Gemini
+- `delegate_opencode` — `{ prompt, model?, variant? }` → OpenCode
+- `delegate_codex` — `{ prompt, model? }` → Codex
+- `delegate_smart` — `{ task_type, prompt }` → reads `rulebook.yaml` (or the
+  bundled default) and picks the best CLI for that task type automatically
+
+Call the tool that matches the harness you want, with a complete,
+self-contained `prompt` — the adapter underneath handles the CLI's actual
+flags, streams tool-call telemetry to agenttrail as it runs, and returns the
+final output. `variant` (OpenCode only) maps to `--variant` (reasoning
+effort).
+
+## What it is not
+
+- Not a replacement for the Claude Code delegation plugins for a quick,
+  interactive, single-turn ask inside a Claude Code session — those remain
+  fine for that case.
+- Not itself a review/QA step — verify a delegated result the same way
+  AGENTS.md already says to: read the actual diff, never trust the returned
+  status field alone.

package/skills/global_config/plan-canvas/scripts/lib/plan-canvas/server.js

@@ -97,6 +97,23 @@ function readJsonBody(req) {
   });
 }
 
+function isWithin(root, candidate) {
+  const relativePath = path.relative(root, candidate);
+  return relativePath === '' || (relativePath !== '..' && !relativePath.startsWith(`..${path.sep}`) && !path.isAbsolute(relativePath));
+}
+
+function confinedArtifactPath(file, workspaceRoot) {
+  if (typeof file !== 'string' || file.length === 0 || /^[a-z][a-z0-9+.-]*:\/\//i.test(file)) return null;
+  try {
+    const root = fs.realpathSync(path.resolve(workspaceRoot));
+    const candidate = fs.realpathSync(path.isAbsolute(file) ? file : path.resolve(root, file));
+    if (!isWithin(root, candidate) || !fs.statSync(candidate).isFile()) return null;
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+
 function sendJson(res, statusCode, payload) {
   const body = JSON.stringify(payload);
   res.writeHead(statusCode, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
@@ -120,6 +137,7 @@ function createPlanCanvasServer({
   idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
   heartbeatMs = 15000,
   thinkingStaleMs = DEFAULT_THINKING_STALE_MS,
+  workspaceRoot = process.cwd(),
   typingExpiryMs = DEFAULT_TYPING_EXPIRY_MS,
   presenceSweepMs = DEFAULT_PRESENCE_SWEEP_MS,
   onIdleShutdown = null,
@@ -287,10 +305,11 @@ function createPlanCanvasServer({
       if (!body.file || typeof body.file !== 'string') {
         return sendJson(res, 400, { error: 'file is required' });
       }
-      if (!fs.existsSync(path.resolve(body.file))) {
-        return sendJson(res, 404, { error: `artifact not found: ${body.file}` });
+      const artifactPath = confinedArtifactPath(body.file, workspaceRoot);
+      if (!artifactPath) {
+        return sendJson(res, 403, { error: 'artifact path is outside the workspace' });
       }
-      const { session, refused } = store.open(body.file, { reopen: Boolean(body.reopen) });
+      const { session, refused } = store.open(artifactPath, { reopen: Boolean(body.reopen) });
       if (refused) {
         return sendJson(res, 409, {
           status: 'user-ended',
@@ -514,9 +533,15 @@ function createPlanCanvasServer({
 
     // Sibling assets resolve relative to the artifact's directory and must
     // stay confined to it.
-    const baseDir = path.dirname(session.file);
-    const resolved = path.resolve(baseDir, assetPath);
-    if (resolved !== baseDir && !resolved.startsWith(baseDir + path.sep)) {
+    let baseDir;
+    let resolved;
+    try {
+      baseDir = fs.realpathSync(path.dirname(session.file));
+      resolved = fs.realpathSync(path.resolve(baseDir, assetPath));
+    } catch {
+      return sendJson(res, 404, { error: 'asset not found' });
+    }
+    if (!isWithin(baseDir, resolved)) {
       return sendJson(res, 403, { error: 'asset path escapes artifact directory' });
     }
     let data;

package/skills/global_config/plan-canvas/scripts/plan-canvas.js

@@ -186,7 +186,8 @@ async function ensureServer({ stateDir, port }) {
   const child = spawn(process.execPath, [__filename, 'server', '--port', String(port)], {
     detached: true,
     stdio: ['ignore', logFd, logFd],
-    env: { ...process.env, AOS_PLAN_CANVAS_STATE_DIR: stateDir }
+    env: { ...process.env, AOS_PLAN_CANVAS_STATE_DIR: stateDir },
+    shell: false
   });
   child.unref();
   fs.closeSync(logFd);
@@ -204,7 +205,7 @@ function openBrowser(url) {
       : platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
         : ['xdg-open', [url]];
   try {
-    spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+    spawn(cmd, args, { detached: true, stdio: 'ignore', shell: false }).unref();
     return true;
   } catch {
     return false;
@@ -357,6 +358,7 @@ async function cmdServer(args, { stateDir, port }) {
   };
   const canvas = createPlanCanvasServer({
     store,
+    workspaceRoot: process.cwd(),
     host: hostArg || DEFAULT_HOST,
     version: VERSION,
     idleTimeoutMs: resolveIdleTimeoutMs(),

package/docs/handover/agenttrail-for-ao.md

@@ -1,58 +0,0 @@
-# agenttrail for AO — waiting questions & GO/Nein handover
-
-AO (the Go daemon shipped as `@hybridlabor-api/bdb-agent-orchestrator`, binary at `~/.local/bin/ao`) can mirror what the agenttrail live map shows: an agent that waits on the human appears as a question with GO / Nein, and AO surfaces "Needs you" in its own UI — then types the human's decision into the waiting session (approved_plan_go.md:25, :57). agenttrail is the live-map daemon vendored into AOS at `skills/global_config/agenttrail/bin/agenttrail.mjs`, run as `aos-trail`; one daemon per repo, bound to 127.0.0.1 only. This document lists the HTTP surfaces AO may call and the things it must never do. The ask/answer endpoints are the AOS patch defined in production_artifacts/00_execution_plan.md ({#ask-engine}, lines 8-13) and production_artifacts/approved_plan_go.md; `/whoami` and `/model` already exist in the vendored daemon (agenttrail.mjs:583-584, :674-675).
-
-## What AO calls
-
-### 1. Find the repo's daemon — `GET /whoami`
-
-Probe `http://127.0.0.1:5330` through `5344` and match `repoPath` against the repo AO is working in — the same pattern the daemon itself uses for boot dedup (agenttrail.mjs:733-741):
-
-```sh
-curl -s http://127.0.0.1:$p/whoami
-# {"project":"aos","port":5330,"repoPath":"/Users/tim/dev/bdb-dev/aos-wt-go"}
-```
-
-Stop at the first match. If no daemon answers there is nothing to mirror — do not spawn a daemon from AO; the asker's CLI already prints `start: aos-trail . --plan …` on stderr (00_execution_plan.md:5). The `AGENTTRAIL_PORT` env var pins a single port and wins over the probe range (agenttrail.mjs:91).
-
-### 2. Read open questions — `GET /model`, `GET /ask/<id>`, `GET /events`
-
-- `GET /model` carries `asks`: one object per question `{id, question, askedBy, askedAt, expiryAt, status: 'pending' | 'go' | 'deny', decidedAt, by, expired}`. Show every ask, oldest first (`askedAt` ascending — approved_plan_go.md:36).
-- `GET /ask/<id>` returns one ask plus the last 10 decisions — the "wer · wann · was" log (00_execution_plan.md:13).
-- `GET /events` is the SSE stream; activity ticks carry `asks` too (00_execution_plan.md:10), so AO can mirror live instead of polling.
-
-A pending question past `expiryAt` flips to `status: 'deny'` with `expired: true` — render it greyed out (abgelaufen), never as a live GO/Nein pair (00_execution_plan.md:52).
-
-### 3. Answer — `POST /answer`
-
-```sh
-curl -s -X POST http://127.0.0.1:$port/answer \
-  -H 'Content-Type: application/json' \
-  --data '{"id":"<ask-id>","decision":"go"}'   # or "deny"
-```
-
-- The `content-type` header must be exactly `application/json` — a missing or different header (`text/plain`, JSON with a charset suffix) is rejected (00_execution_plan.md:13).
-- The body `{id, decision}` is capped at 4 KB.
-- `origin`: browser callers always send it, and it must equal the daemon's own `http://localhost:<port>` or `http://127.0.0.1:<port>`; AO is a local non-browser caller and may omit the header entirely (00_execution_plan.md:51 — the curl above does). If AO sends an `origin`, it must be the daemon's own.
-- A valid answer sets the ask's status + `decidedAt` + `by: 'you'` and appends `{question, decision, by, at}` to the timestamped decision log; timeout denials land there too, as `by: 'timeout'` (00_execution_plan.md:13).
-- The daemon binds 127.0.0.1 only (agenttrail.mjs:700) and sets no `Access-Control-*` header and no `OPTIONS` handler anywhere in its route chain (agenttrail.mjs:572-689) — that absence is the CSRF protection for the map's browser buttons. AO must not ask for CORS to be relaxed.
-
-That is the whole surface: AO does not call the daemon's other mutating endpoints (`/spawn`, `/setup`, `/setup-board`, `/hook`) and never writes into the repo — the daemon itself never touches the repo; state lives under `~/.agenttrail` (agenttrail.mjs:307).
-
-## What the answer means
-
-`aos-trail ask "<question>"` blocks until the question is answered or expires and exits 0 on go, 1 on deny/timeout (00_execution_plan.md:5). The default deadline is 30 minutes, overridable per question via the asker's `--timeout <10s|30m|2h|N>`; expiry auto-denies and is logged like a human decision (00_execution_plan.md:52). Questions and the decision log persist across daemon restarts in `~/.agenttrail/<repo-hash>.json` (agenttrail.mjs:308).
-
-## Mirroring in AO's UI
-
-- Pending ask → a pinned "Needs you" card with the question, the asking agent (`askedBy`), elapsed time, and one GO and one Nein button.
-- AO answers `POST /answer` only after the human clicked or said the decision for that exact ask id, and only then may it type that decision into the waiting session (approved_plan_go.md:57 — AO already recognizes "Needs You GO" and can write to the terminal, :25).
-- Re-check `GET /ask/<id>` immediately before typing: the human may have answered on the map instead, or the question may have expired meanwhile.
-
-## Hard rules
-
-- The AO button never authorizes `git push`, `npm publish`, `npm version` or recursive `rm` (approved_plan_go.md:30). Those four stay under go-gate's sole authority (`.claude/hooks/go-gate.mjs:43-49`), which opens only for the literal, human-typed `GO` as the last message in the session transcript (go-gate.mjs:10-13, transcript-only check in main() :116-151). The ask/answer flow only resolves explicit `aos-trail ask` questions and never writes to any session transcript — the map and AO remain "an observer and an answer relay, never a permission system" (00_execution_plan.md:50, approved_plan_go.md:49).
-- Never answer without the human. No batching, no defaults, no "the agent seemed sure" — one answer per explicit human decision, per question id.
-- Never auto-retry a timed-out question. Expiry → deny is final (`by: 'timeout'` in the log); only the human asking again starts a new question (approved_plan_go.md:57; the same "no silent retries / a fresh GO per action" rule the gate runs on, go-gate.mjs:13).
-- Never read `~/.agenttrail/<repo-hash>.json` or anything else inside `~/.agenttrail/` directly (agenttrail.mjs:307-308). Those files are internal state with no format contract — use the HTTP surfaces above.
-- Keep the CSRF contract intact: exact `Content-Type: application/json`, own-or-absent `origin`, and never relay an answer through web content the agent loaded.

package/docs/handover/deja-for-ao.md

@@ -1,51 +0,0 @@
-# deja for AO — session-memory handover
-
-AO (the Go daemon shipped as `@hybridlabor-api/bdb-agent-orchestrator`, binary at `~/.local/bin/ao`) can ask deja — the local session-memory engine installed together with memB by the AOS installer — for project history. This document lists the surfaces AO may call and the two things it must not do. Every command below is verified against deja-vu 0.21.1.
-
-## What AO calls at session start
-
-Run in the project directory:
-
-```sh
-deja wip --json
-```
-
-The answer is what the last session in that directory was doing (deja-vu docs/json-output.md:1192-1223):
-
-```json
-{
-  "schema_version": 2,
-  "session": "ses_fb76fff…",
-  "harness": "opencode",
-  "asked": "the orders worker is exhausting its database connections under load",
-  "decision": "bound every orders-worker query with a context",
-  "files": ["internal/worker/orders.go"],
-  "command": "go test ./internal/worker/...",
-  "command_failed": true,
-  "lines": ["working on: …", "settled: …"]
-}
-```
-
-- `schema_version: 2` is the only guaranteed field. Every other field is optional and omitted when the transcript does not carry it — treat all of them as nullable.
-- `lines` is the inject-verbatim form: one string per fact, in display order. A caller that wants to show the digest reads `lines` and does not re-assemble the fields.
-
-## Untrusted historical data
-
-Everything deja returns is transcript-derived and may carry text an attacker influenced: a directive copied from a web page persists in the index and replays into later sessions. deja-vu wraps its own agent-facing recall in `<deja-recall>` markers with an untrusted-data preamble (deja-vu docs/SECURITY-MODEL.md:235-245). AO must label or wrap the content the same way before it reaches a model, and instructions inside it must not be followed.
-
-## Other surfaces AO may use
-
-- `deja fix "<error>" --json` — what this machine ran after that error. Rows carry `command` or `edit`; `candidate: true` marks ran-next-but-unconfirmed evidence, not a guaranteed fix (deja-vu docs/json-output.md:763).
-- `deja last --json` — recent session metadata, never message bodies (deja-vu docs/json-output.md:200).
-- `deja handoff [id-prefix]` — the handoff digest for a session (deja-vu CLI reference, docs/guide/commands.html).
-- `deja blame <path> --json` — which sessions discussed a file; a top-level JSON array, no envelope (deja-vu docs/json-output.md:1107).
-- `deja doctor --json --offline` — index and store health; `--offline` keeps the version check off the network (deja-vu docs/json-output.md:356).
-
-## Stability contract
-
-Envelope-shaped answers carry `schema_version: 2`. Within a version, changes are additive only: existing field names, types and meanings stay the same. Bumping the version signals a breaking change, so branch on `schema_version` before parsing the rest of the envelope (deja-vu docs/json-output.md:7-28). `deja blame --json` returns a bare array and carries no version; its element shapes are stable.
-
-## Hard rules
-
-- Never read `~/.cache/deja/index.db` or anything else inside the index directory (`manifest.gob`, `sessions.gob`, `records.bin`, the buckets, the sidecars) directly. The format has moved forty-odd times and is explicitly not a contract (deja-vu docs/INTEGRATING.md:102-106). Use the CLI surfaces above.
-- AO must NOT run `deja install --auto` and must not wire session-start auto-recall. The approved AOS plan rules both out (production_artifacts/approved_plan_deja.md:61-66): a second writer into agent configs, and old history injected automatically at every session start, are exactly the injection vectors AOS installed deja to avoid. AO calls the `deja` CLI itself, on demand, in the project directory.