agy-mcp-bridge 0.1.21 → 0.1.22

package/README.md

@@ -79,6 +79,23 @@ Then call `antigravity_environment` from a fresh session — that is the proof;
 
 Two switches control delegation itself: `agy-mcp-bridge delegation off` blocks new tasks immediately without a restart, and `BRIDGE_DELEGATION=off` pins it at startup. Tasks still refuse to be delegated by policy the skill describes (security, auth, secrets, data deletion, deploy, CI and public API changes are not delegated).
 
+## Missions
+
+A mission is a plan the bridge **records and gates but never runs**: up to 12 steps in one workspace, each carrying its own `delegate` arguments and a list of `depends_on`. An MCP client writes the plan and dispatches it one step at a time; the bridge refuses to start a step whose dependencies did not all complete, so no agent is sent at a step whose inputs do not exist yet. Nothing ever starts by itself — a restart restores every plan and re-dispatches nothing.
+
+| Tool | What it does |
+|---|---|
+| `mission_create` | record the plan and return `mission_id`, progress and the `ready` step ids (the receipt does not echo the plan back) |
+| `mission_extend` | append correction or follow-up steps: the plan is append-only, so a retry is always a new step |
+| `mission_dispatch` | start one ready step as a normal supervised task; refused while a dependency is not `completed`, if the step already ran, or once the mission is canceled |
+| `mission_status` | cheap poll: per-step state, `blocked_by`, `ready` — no task text |
+| `mission_plan` | the whole recorded plan with each step's exact `delegate` arguments, for a client that lost its own copy |
+| `mission_cancel` | close the plan so nothing further can be dispatched; running agents are left alone unless `cancel_running_tasks: true` |
+
+A dispatched step **is** an ordinary task, so everything in [Delegate](#delegate) still applies to it: worktree isolation, `owns`, timeouts, redaction, process-tree release, `review_required`, and no auto-merge. Step state is derived from the task records on every read rather than cached, so a record that retention dropped shows as `lost` — which never unlocks the step waiting for it. Replies are deliberately small (`dispatch` returns five fields plus a `next_step` hint) because an orchestrator polls them; the **Nhiệm vụ** page is the human view. There is no `mission_list` — keep the `mission_id` you were given, or read it from that page.
+
+The bundled `mission-orchestrator` skill teaches a client how to write such a plan (and when not to).
+
 ## Lifecycle and limits
 
 Task state belongs to the HTTP server, not to the MCP session, and all clients share one TaskManager. `none`-lane tasks take a cross-process lock (`.bridge-state/execution.lock`); `worktree`-lane tasks rely on their own branch. Results persist to `.bridge-state/tasks/<task_id>.json` (0600, secret-redacted) and reload at startup, so you can recover an answer after a reconnect — this is history, not durable task recovery. Ctrl+C once: stop listening, cancel running tasks and reap their process trees, drain sockets for up to 3 s, print `[bridge] Stopped`. It does not revert files.
@@ -99,7 +116,7 @@ Redaction recognises common secret shapes; it does not catch everything. Keep se
 
 ## Web UI
 
-`http://127.0.0.1:3000/ui` on the same machine, no login (there is no auth to log into). It reads the same task store as the tools, so it costs your other agents no tokens. Pages: **Tasks** (bridge state, ready agents, delegation switch, per-task request/criteria/response, `denied_actions`, stdout/stderr, full prompt, worktree/branch and `owns` verdict, workspace changes with per-file line counts) and **Settings** (delegation, MCP endpoint, per-agent probe results, allowed workspaces, permission level, model, effort, wait cadence, soft deadline, step progress, usage, shutdown button). Regions patch in place, so selecting log text survives an update.
+`http://127.0.0.1:3000/ui` on the same machine, no login (there is no auth to log into). It reads the same task store as the tools, so it costs your other agents no tokens. Pages: **Tasks** (bridge state, ready agents, delegation switch, per-task request/criteria/response, `denied_actions`, stdout/stderr, full prompt, worktree/branch and `owns` verdict, workspace changes with per-file line counts), **Nhiệm vụ** (every recorded plan: steps, states, which dependency blocks which step, the exact `delegate` arguments per step, and a **Dừng kế hoạch** button that closes the plan and never touches a running agent — the page reads and stops missions, it cannot dispatch one), and **Settings** (delegation, MCP endpoint, per-agent probe results, allowed workspaces, permission level, model, effort, wait cadence, soft deadline, step progress, usage, shutdown button). Regions patch in place, so selecting log text survives an update.
 
 Long explanations, unverified notes and rarely-changed numbers live behind **More** blocks; decisions-worthy state stays visible. The no-auth warning is always visible, and the "allowlist is not a sandbox" warning is always visible at `auto`/`full`.
 
@@ -114,7 +131,7 @@ npm test          # build + unit/integration with fake executables; no AI calls
 npm run test:live # REAL agent calls, scratch workspace, disconnect/reconnect, cancel, shutdown
 ```
 
-`npm test` runs serially (`--test-concurrency=1`, ~158 s): most cases start a real loopback server and time its output, so a parallel failure reflects machine load, not code. CI runs Windows and Linux on Node 20/22. Source map: `src/index.ts` entry, `src/http.ts` routing/shutdown, `src/runtime.ts` shared CLI + TaskManager, `src/agents` adapters and registry, `src/isolation` worktrees and `owns`, `src/tasks` lifecycle/lock/output, `src/security` validation and redaction, `src/tools` tool definitions, `src/antigravity` child process, `ui/` plain HTML/CSS/JS with `src/ui/` behind it.
+`npm test` runs serially (`--test-concurrency=1`, ~158 s): most cases start a real loopback server and time its output, so a parallel failure reflects machine load, not code. CI runs Windows and Linux on Node 20/22. Source map: `src/index.ts` entry, `src/http.ts` routing/shutdown, `src/runtime.ts` shared CLI + TaskManager, `src/agents` adapters and registry, `src/missions` the plan store and its dispatch gates, `src/isolation` worktrees and `owns`, `src/tasks` lifecycle/lock/output, `src/security` validation and redaction, `src/tools` tool definitions, `src/antigravity` child process, `ui/` plain HTML/CSS/JS with `src/ui/` behind it.
 
 Pushing or merging to `main` runs CI and, when it passes, publishes to npm automatically: the [publish workflow](.github/workflows/publish.yml) bumps the patch version, tags, pushes and publishes through OIDC Trusted Publishing — no npm token in secrets, no manual version bump, nothing published if CI fails. PRs run [CI](.github/workflows/ci.yml) only. Set up once under the package's **Trusted Publisher** settings: user `thanhdo257205`, repository `MCP-bridge`, workflow `publish.yml`, empty environment, allow direct npm publish.
 
@@ -125,8 +142,8 @@ Pushing or merging to `main` runs CI and, when it passes, publishes to npm autom
 - [docs/MULTI-AGENT-PLAN.md](docs/MULTI-AGENT-PLAN.md) — the multi-agent roadmap and per-phase status.
 - [docs/HANDOFF.md](docs/HANDOFF.md) — open work (Job Object, POSIX E2E, worktree TTL) with mutation-test evidence.
 - [docs/PROMPTS.md](docs/PROMPTS.md) — review and follow-up task prompts.
-- [skills/antigravity-bridge/SKILL.md](skills/antigravity-bridge/SKILL.md) and [docs/SKILL-EVAL.md](docs/SKILL-EVAL.md) — the client-side contract and manual evaluation cases.
+- [skills/antigravity-bridge/SKILL.md](skills/antigravity-bridge/SKILL.md), [skills/mission-orchestrator/SKILL.md](skills/mission-orchestrator/SKILL.md) and [docs/SKILL-EVAL.md](docs/SKILL-EVAL.md) — the client-side contract and manual evaluation cases.
 
-The bundled `antigravity-bridge` skill teaches a client the real tool schemas, task-id recovery, timeouts, permission denials and diff review. First interactive run offers to install it (`agy-mcp-bridge skill install --client codex|claude|both` writes `~/.agents/skills/…` or `~/.claude/skills/…`); a SKILL.md you edited yourself is never overwritten. Installing the skill does not connect the server or grant any permission.
+Two skills ship with the bridge: `antigravity-bridge` teaches a client the real tool schemas, task-id recovery, timeouts, permission denials and diff review; `mission-orchestrator` teaches it how to write and drive a plan — when a mission is the right shape, how to keep it cheap, and what must never be put in one. First interactive run offers to install them (`agy-mcp-bridge skill install --client codex|claude|both [--skill <name>] [--update]` writes `~/.agents/skills/…` or `~/.claude/skills/…`); a `SKILL.md` you edited yourself is never overwritten, and one customized skill never blocks the other. Installing a skill does not connect the server or grant any permission.
 
 MIT licensed; see `LICENSE`.

package/dist/scripts/install-skill.js

@@ -1,24 +1,37 @@
 import { createHash } from 'node:crypto';
-import { readFile, mkdir, writeFile, stat, realpath, rename, rm } from 'node:fs/promises';
+import { readFile, mkdir, writeFile, stat, readdir, realpath, rename, rm } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { paths } from '../src/paths.js';
-const skillSource = () => path.join(paths.skillsDirectory, 'antigravity-bridge', 'SKILL.md');
-const skillFile = (root, client) => path.join(root, client === 'codex' ? '.agents' : '.claude', 'skills', 'antigravity-bridge', 'SKILL.md');
+const skillSource = (name, directory = paths.skillsDirectory) => path.join(directory, name, 'SKILL.md');
+const skillFile = (root, client, name) => path.join(root, client === 'codex' ? '.agents' : '.claude', 'skills', name, 'SKILL.md');
+const readIfPresent = (file) => readFile(file, 'utf8').catch(error => { if (error.code === 'ENOENT')
+    return null; throw error; });
+/** One folder per skill under `skills/`, each holding its SKILL.md, so a new skill needs no change here. */
+export async function packagedSkills(directory = paths.skillsDirectory) {
+    const names = (await readdir(directory, { withFileTypes: true }).catch(() => []))
+        .filter(entry => entry.isDirectory()).map(entry => entry.name);
+    const present = await Promise.all(names.map(async (name) => (await readIfPresent(skillSource(name, directory)) === null ? null : name)));
+    return present.filter((name) => name !== null).sort();
+}
 const normalize = (text) => text.replace(/\r\n/g, '\n');
 /** Identity of a skill file's content, independent of line endings (a Windows checkout may turn LF into CRLF). */
 export const skillHash = (text) => createHash('sha256').update(normalize(text)).digest('hex');
-/** sha256 of every SKILL.md this project has shipped (skills/known-versions.json). A file that matches one is an old packaged copy, not the owner's edit. */
+/** sha256 of every SKILL.md this project has shipped, listed per skill (skills/known-versions.json). A file that matches one is an old packaged copy, not the owner's edit. */
 export async function knownSkillHashes(file = path.join(paths.skillsDirectory, 'known-versions.json')) {
     try {
         const parsed = JSON.parse(await readFile(file, 'utf8'));
-        return new Set((parsed.versions ?? []).map(entry => entry.sha256).filter((value) => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value)));
+        const known = {};
+        for (const [name, entries] of Object.entries(parsed.skills ?? {}))
+            known[name] = new Set((entries ?? []).map(entry => entry.sha256).filter((value) => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value)));
+        return known;
     }
     catch {
-        return new Set();
+        return {};
     }
 }
+const hashesFor = (known, skill) => known[skill] ?? new Set();
 function classify(existing, content, known) {
     if (existing === null)
         return 'missing';
@@ -27,27 +40,35 @@ function classify(existing, content, known) {
         return 'installed';
     return known.has(hash) ? 'outdated' : 'different';
 }
-const readIfPresent = (file) => readFile(file, 'utf8').catch(error => { if (error.code === 'ENOENT')
-    return null; throw error; });
+async function skillSources(skills) {
+    const names = skills ?? await packagedSkills();
+    if (!names.length)
+        throw new Error('No skill was selected and this bridge ships none (expected skills/<name>/SKILL.md)');
+    return Promise.all(names.map(async (name) => ({ name, content: await readFile(skillSource(name), 'utf8') })));
+}
+/** One fingerprint for the packaged set, so "a newer skill ships" means any skill in it changed. */
+const setHash = (sources) => skillHash(sources.map(source => `${source.name}:${skillHash(source.content)}`).join('\n'));
 /**
- * Where the skill is (or would be) installed for the current user and what is there: `installed` (this version), `outdated`
- * (an older version this project shipped, safe to replace), `different` (not any shipped version: the owner's edit) or `missing`. Reads only.
+ * Where every packaged skill is (or would be) installed for the current user and what is there: `installed` (this version),
+ * `outdated` (an older version this project shipped, safe to replace), `different` (not any shipped version: the owner's edit) or `missing`. Reads only.
  */
 export async function skillStatus(options = {}) {
-    const content = await readFile(skillSource(), 'utf8');
+    const sources = await skillSources(options.skills);
     const known = options.known ?? await knownSkillHashes();
     const root = options.userHome ?? homedir();
-    const result = { currentHash: skillHash(content) };
+    const result = { currentHash: setHash(sources), codex: [], claude: [] };
     for (const client of ['codex', 'claude']) {
-        const file = skillFile(root, client);
-        result[client] = { file, state: classify(await readIfPresent(file), content, known) };
+        for (const source of sources) {
+            const file = skillFile(root, client, source.name);
+            result[client].push({ skill: source.name, file, state: classify(await readIfPresent(file), source.content, hashesFor(known, source.name)) });
+        }
     }
     return result;
 }
 export async function installSkill(options) {
     if (!['codex', 'claude', 'both'].includes(options.client))
         throw new Error('--client must be codex, claude or both');
-    const content = await readFile(skillSource(), 'utf8');
+    const sources = await skillSources(options.skills);
     const known = options.known ?? await knownSkillHashes();
     let root = options.userHome ?? homedir();
     if (options.project !== undefined) {
@@ -58,35 +79,39 @@ export async function installSkill(options) {
             throw new Error('--project must be a directory');
     }
     const clients = options.client === 'both' ? ['codex', 'claude'] : [options.client];
-    const destinations = clients.map(client => skillFile(root, client));
     const planned = [];
+    const writes = [];
     // Decide for every destination before writing any. A file that is not one of our shipped versions is never overwritten.
-    for (const filename of destinations) {
-        const state = classify(await readIfPresent(filename), content, known);
-        if (state === 'installed')
-            planned.push({ filename, unchanged: true });
-        else if (state === 'missing')
-            planned.push({ filename, unchanged: false });
-        else if (state === 'outdated') {
-            if (!options.update)
-                throw new Error(`Existing skill is an older packaged version; run again with --update to replace it: ${filename}`);
-            planned.push({ filename, unchanged: false, updated: true });
+    for (const client of clients) {
+        for (const source of sources) {
+            const filename = skillFile(root, client, source.name);
+            const state = classify(await readIfPresent(filename), source.content, hashesFor(known, source.name));
+            if (state === 'installed')
+                planned.push({ skill: source.name, filename, unchanged: true });
+            else if (state === 'missing') {
+                planned.push({ skill: source.name, filename, unchanged: false });
+                writes.push({ filename, content: source.content, replace: false });
+            }
+            else if (state === 'outdated') {
+                if (!options.update)
+                    throw new Error(`Existing skill is an older packaged version; run again with --update to replace it: ${filename}`);
+                planned.push({ skill: source.name, filename, unchanged: false, updated: true });
+                writes.push({ filename, content: source.content, replace: true });
+            }
+            else
+                throw new Error(`Existing skill differs from every packaged version (customized); review it or remove it first: ${filename}`);
         }
-        else
-            throw new Error(`Existing skill differs from every packaged version (customized); review it or remove it first: ${filename}`);
     }
-    for (const item of planned) {
-        if (item.unchanged)
-            continue;
+    for (const item of writes) {
         await mkdir(path.dirname(item.filename), { recursive: true });
-        if (!item.updated) {
-            await writeFile(item.filename, content, { flag: 'wx' });
+        if (!item.replace) {
+            await writeFile(item.filename, item.content, { flag: 'wx' });
             continue;
         }
         // Replace atomically so a crash never leaves a half-written skill.
         const temporary = `${item.filename}.${process.pid}.tmp`;
         try {
-            await writeFile(temporary, content, { flag: 'wx' });
+            await writeFile(temporary, item.content, { flag: 'wx' });
             await rename(temporary, item.filename);
         }
         finally {
@@ -96,8 +121,10 @@ export async function installSkill(options) {
     return planned;
 }
 async function main(args) {
+    const skills = await packagedSkills();
     if (args.includes('--help')) {
-        console.log('npm run skill:install -- --client codex|claude|both [--project ABSOLUTE_PROJECT_PATH] [--update]');
+        console.log('npm run skill:install -- --client codex|claude|both [--skill <name>] [--project ABSOLUTE_PROJECT_PATH] [--update]');
+        console.log(`Skills packaged with this bridge: ${skills.join(', ') || '(none)'}. Without --skill, every one of them is installed.`);
         console.log('Without --project, installs for the current user. Does not change MCP configuration or permissions.');
         console.log('--update replaces an installed copy only if it is an older version shipped by this project; a customized file is never overwritten.');
         return;
@@ -105,12 +132,15 @@ async function main(args) {
     let client;
     let project;
     let update = false;
+    const selected = [];
     for (let index = 0; index < args.length; index++) {
         const flag = args[index];
         if (flag === '--client' && client === undefined && args[index + 1])
             client = args[++index];
         else if (flag === '--project' && project === undefined && args[index + 1])
             project = args[++index];
+        else if (flag === '--skill' && !selected.includes(args[index + 1] ?? '') && args[index + 1])
+            selected.push(args[++index]);
         else if (flag === '--update' && !update)
             update = true;
         else
@@ -118,7 +148,10 @@ async function main(args) {
     }
     if (!client)
         throw new Error('Choose --client codex, claude or both');
-    const installed = await installSkill({ client, project, update });
+    for (const name of selected)
+        if (!skills.includes(name))
+            throw new Error(`--skill must be one of the packaged skills: ${skills.join(', ')}`);
+    const installed = await installSkill({ client, project, update, skills: selected.length ? selected : undefined });
     for (const item of installed)
         console.log(`[skill] ${item.unchanged ? 'Already installed' : item.updated ? 'Updated' : 'Installed'}: ${item.filename}`);
     console.log('[skill] Reopen the client if the skill does not appear. MCP connection and workspace permissions are configured separately.');

package/dist/src/cli.js

@@ -32,9 +32,9 @@ Usage: ${BIN} [command] [options]
                           Manage the directories agents may edit (restart the server afterwards)
   delegation on|off|status
                           Switch delegation to Antigravity on or off immediately (no restart)
-  skill install --client codex|claude|both [--project <dir>] [--update]
-                          Install the antigravity-bridge skill (first run also offers it once). --update replaces an older
-                          packaged copy; a file you edited yourself is never overwritten
+  skill install --client codex|claude|both [--skill <name>] [--project <dir>] [--update]
+                          Install the skills this bridge ships (first run also offers them once). Repeat --skill for one of
+                          them; --update replaces an older packaged copy, and a file you edited yourself is never overwritten
   setup codex|claude|both [--port N] [--shell powershell|cmd|bash]
                           Print the exact client configuration (changes nothing)
   setup codex|both --apply [--yes] [--tool-timeout N] [--port N]

package/dist/src/http.js

@@ -15,8 +15,8 @@ export function configuredPort(value = process.env.PORT) {
 export async function startHttpBridge(options) {
     let stopping = false;
     let baseUrl = '';
-    const ui = { manager: options.manager, environment: options.environment, mcpUrl: () => `${baseUrl}/mcp`, startedAt: Date.now(), requestShutdown: options.requestShutdown };
-    const handler = createMcpHandler(() => createServer(options.manager, options.environment), { maxRequestBodySize: 131072, maxSubscriptions: 16 });
+    const ui = { manager: options.manager, missions: options.missions, environment: options.environment, mcpUrl: () => `${baseUrl}/mcp`, startedAt: Date.now(), requestShutdown: options.requestShutdown };
+    const handler = createMcpHandler(() => createServer(options.manager, options.environment, options.missions), { maxRequestBodySize: 131072, maxSubscriptions: 16 });
     const mcp = toNodeHandler(handler, { maxRequestBodySize: 131072 });
     const server = createHttpServer((req, res) => {
         const reply = (code, body) => {
@@ -49,7 +49,7 @@ export async function startHttpBridge(options) {
             return;
         }
         if (req.url === '/health' && req.method === 'GET') {
-            reply(200, { status: 'ok', transport: 'streamable-http', mcp_endpoint: `${baseUrl}/mcp`, ...options.manager.overview() });
+            reply(200, { status: 'ok', transport: 'streamable-http', mcp_endpoint: `${baseUrl}/mcp`, ...options.manager.overview(), missions: options.missions.overview() });
             return;
         }
         if (req.url !== '/mcp') {

package/dist/src/index.js

@@ -5,7 +5,7 @@ import { createRuntime } from './runtime.js';
 import { configuredPort, startHttpBridge } from './http.js';
 async function main() {
     const port = configuredPort();
-    const { manager, environment } = await createRuntime();
+    const { manager, missions, environment } = await createRuntime();
     let stopping = false;
     let closeBridge;
     const shutdown = async () => {
@@ -26,7 +26,7 @@ async function main() {
             process.exitCode = 1;
         }
     };
-    const bridge = await startHttpBridge({ manager, environment, port, requestShutdown: shutdown });
+    const bridge = await startHttpBridge({ manager, missions, environment, port, requestShutdown: shutdown });
     closeBridge = bridge.close;
     console.error(`[bridge] HTTP server: ${bridge.baseUrl}`);
     console.error(`[bridge] MCP endpoint: ${bridge.mcpUrl}`);