@0xgeorgemathew/zcode 0.4.1 → 0.4.4

package/README.md

@@ -30,13 +30,22 @@ The orchestrator keeps product decisions, design direction, and coordination. zc
 npm install -g @0xgeorgemathew/zcode
 echo "$ZAI_API_KEY" | zcode login    # stores your Z.AI key with mode 600; zcode never prints it
 zcode doctor                         # checks the engine, isolation and key
+zcode skills install                 # optional: teach Claude Code and Codex to delegate to zcode
 
 zcode task --check "npm test" "Fix the off-by-one in src/paginate.ts"
 ```
 
 The CLI needs node 20 or later. The engine child runs best on node 26. zcode also needs the ZCode engine, which today ships inside the ZCode desktop app; zcode finds it automatically.
 
-Installing the package also installs the Claude Code skill to `~/.claude/skills/zcode` and the Codex skill to `${CODEX_HOME:-~/.codex}/skills/zcode`. These skills teach the orchestrator how to delegate to zcode. Set `ZCODE_SKIP_SKILLS=1` to skip this step. Details are in [`skills/`](skills/README.md).
+The package ships skills that teach Claude Code and Codex how to delegate to zcode. Install them with one command:
+
+```sh
+zcode skills install          # both; or: zcode skills install claude | codex
+zcode skills                  # show what is installed and where
+zcode skills uninstall        # remove them
+```
+
+The Claude Code skill goes to `~/.claude/skills/zcode` and the Codex skill to `${CODEX_HOME:-~/.codex}/skills/zcode`. The package runs no install scripts. Details are in [`skills/`](skills/README.md).
 
  
 
@@ -226,7 +235,8 @@ Inside `zcode task`, subagents are optional. The executor decides when to use th
 | `--timeout-ms` | all turns; wait | run 600000, task 1800000 | the whole invocation incl. checks and repairs |
 | `--session` | run | | 0.3 compat: continue by zcode id or engine `sess_` id |
 | `--profile` | agent | `general-purpose` | subagent profile |
-| `--mcp` / `--mcp-inherit` / `--mcp-list` | run, task, agent | hermetic | MCP servers (inline JSON or `@file`) |
+| `--mcp` / `--mcp-inherit` / `--mcp-list` | run, task, agent | hermetic, plus the desktop's `playwright` | MCP servers (inline JSON or `@file`) |
+| `--no-browser` | run, task, agent | off | Drop the desktop's `playwright` MCP server |
 | `--skills` / `--no-skills` | run, task, agent | desktop skills | add skills; or run with none |
 | `--json`, `--quiet` | all | | see Machine interface |
 | `--thinking` / `--no-thinking` | turns | run on, task off | mirror reasoning to stderr |

package/bin/zcode.js

@@ -14,6 +14,8 @@ const USAGE = `usage:
   zcode cancel <id> [--json]           stop a running session
   zcode login                          read API key from stdin → credentials
   zcode doctor [--json]                engine + isolation + key report
+  zcode skills [install|uninstall] [claude|codex]
+                                       install the orchestrator skills (default: status)
 
 session:
   --id <id>             name the session (letters, digits, . _ -); default zc-<random>.
@@ -43,6 +45,7 @@ execution:
   --profile <name>      subagent profile (agent command; default general-purpose)
   --mcp <json|@f>       add MCP servers (repeatable); hermetic by default
   --mcp-inherit         also inherit the desktop's enabled MCP servers
+  --no-browser          drop the desktop's playwright MCP server (on by default)
   --mcp-list            print the effective MCP server set as JSON and exit
   --skills <dir>        add skills (repeatable): one skill dir or a root of them
   --no-skills           empty skill set
@@ -94,9 +97,9 @@ function parseMcpSpec(value) {
   return parsed;
 }
 
-const COMMANDS = new Set(['run', 'task', 'agent', 'resume', 'status', 'list', 'wait', 'cancel', 'login', 'doctor', '__exec']);
+const COMMANDS = new Set(['run', 'task', 'agent', 'resume', 'status', 'list', 'wait', 'cancel', 'login', 'doctor', 'skills', '__exec']);
 const TASK_ONLY = new Set(['task', 'accept', 'check', 'file', 'context', 'maxRepairs', 'checkTimeoutMs']);
-const START_ONLY = new Set(['id', 'label', 'owns', 'allowOverlap', 'mcpSpecs', 'mcpInherit', 'skillsDirs', 'noSkills', 'profile', 'cwd']);
+const START_ONLY = new Set(['id', 'label', 'owns', 'allowOverlap', 'mcpSpecs', 'mcpInherit', 'noBrowser', 'skillsDirs', 'noSkills', 'profile', 'cwd']);
 
 function parseArgv(argv) {
   const out = {
@@ -127,6 +130,7 @@ function parseArgv(argv) {
       checkTimeoutMs: undefined,
       mcpSpecs: [],
       mcpInherit: false,
+      noBrowser: false,
       mcpList: false,
       skillsDirs: [],
       noSkills: false,
@@ -148,7 +152,7 @@ function parseArgv(argv) {
   ]);
   const boolFlags = new Map([
     ['--json', ['json', true]], ['--fresh', ['fresh', true]], ['--mcp-inherit', ['mcpInherit', true]],
-    ['--mcp-list', ['mcpList', true]], ['--no-skills', ['noSkills', true]],
+    ['--mcp-list', ['mcpList', true]], ['--no-skills', ['noSkills', true]], ['--no-browser', ['noBrowser', true]],
     ['--include-reasoning', ['includeReasoning', true]], ['--quiet', ['quiet', true]],
     ['--detach', ['detach', true]], ['--allow-overlap', ['allowOverlap', true]],
     ['--thinking', ['thinking', true]], ['--no-thinking', ['thinking', false]], ['--stream', ['stream', true]],
@@ -265,6 +269,8 @@ async function main() {
       return require('../lib/commands/login.js')(parsed);
     case 'doctor':
       return require('../lib/commands/doctor.js')(parsed);
+    case 'skills':
+      return require('../lib/commands/skills.js')(parsed);
     default:
       return fail(2, `unknown command "${parsed.command}".\n${USAGE}`);
   }

package/lib/appserver.js

@@ -150,6 +150,17 @@ class AppServerClient {
       if (this.onUserInputRequest) this.onUserInputRequest(frame);
       return;
     }
+    if (method === 'interaction/browserList') {
+      // The desktop app answers with its built-in browser panes; the CLI has
+      // none. An empty list lets the agent fall back to the user's own tools
+      // (Playwright, MCP browsers) instead of failing on a policy error.
+      reply({ browsers: [] });
+      return;
+    }
+    if (method === 'interaction/browserExecute') {
+      replyError(-32000, 'zcode: no built-in browser in the CLI; use Playwright or a browser MCP server');
+      return;
+    }
     // Everything else — incl. interaction/requestOfficialMcpAuthHeaders,
     // proven non-fatal with -32601 — gets method-not-found and the run
     // continues.
@@ -220,8 +231,12 @@ function workspaceKeyFor(workspacePath) {
 // turn always sees the caller's --mcp servers. Inherited servers are
 // best-effort and never block the send.
 async function waitForMcp(client, { workspacePath, required, timeoutMs = 20000, onEvent = () => {} }) {
-  if (!required || required.length === 0) return;
   const ws = { workspace: { workspacePath, workspaceKey: workspaceKeyFor(workspacePath) } };
+  if (!required || required.length === 0) {
+    // Still start inherited servers (the browser server); never block on them.
+    client.request('mcp/list', { ...ws, mode: 'connect' }, { timeoutMs: 15000 }).catch(() => {});
+    return;
+  }
   try {
     await client.request('mcp/list', { ...ws, mode: 'connect' }, { timeoutMs: 15000 });
   } catch {

package/lib/commands/exec.js

@@ -77,6 +77,7 @@ function buildInvocation(parsed) {
     acceptanceDeclared: false,
     mcpSpecs: flags.mcpSpecs,
     mcpInherit: flags.mcpInherit,
+    noBrowser: flags.noBrowser,
     skillsDirs: flags.skillsDirs.map((d) => path.resolve(d)),
     noSkills: flags.noSkills,
     profile: flags.profile,

package/lib/commands/mcp-list.js

@@ -6,7 +6,7 @@ const { effectiveMcpServers } = require('../isolation.js');
 
 module.exports = async function mcpList(parsed) {
   const { flags } = parsed;
-  const servers = effectiveMcpServers({ inherit: flags.mcpInherit, mcpSpecs: flags.mcpSpecs });
+  const servers = effectiveMcpServers({ inherit: flags.mcpInherit, browser: !flags.noBrowser, mcpSpecs: flags.mcpSpecs });
   process.stdout.write(JSON.stringify({ type: 'mcp', servers }) + '\n');
   process.exit(0);
 };

package/lib/commands/skills.js

@@ -0,0 +1,39 @@
+'use strict';
+// zcode skills [status|install|uninstall] [claude|codex]
+// Copies the orchestrator skills shipped in this package into Claude Code
+// and Codex. Nothing runs at npm install time; this command is the installer.
+const { installSkills, uninstallSkills, skillStatus, PLATFORMS } = require('../skills.js');
+
+const ACTIONS = new Set(['status', 'install', 'uninstall']);
+
+module.exports = function skills({ prompts, flags }) {
+  const [action = 'status', ...platforms] = prompts;
+  const fail = (msg) => {
+    process.stderr.write(`zcode: ${msg}\nusage: zcode skills [status|install|uninstall] [claude|codex]\n`);
+    process.exit(2);
+  };
+  if (!ACTIONS.has(action)) fail(`unknown skills action "${action}".`);
+  for (const p of platforms) if (!PLATFORMS.includes(p)) fail(`unknown platform "${p}" (claude | codex).`);
+
+  const view = (t) => ({ platform: t.platform, name: t.name, path: t.to, ...(t.installed !== undefined && { installed: t.installed }) });
+  let rows;
+  if (action === 'install') rows = installSkills({ platforms });
+  else if (action === 'uninstall') rows = uninstallSkills({ platforms });
+  else rows = skillStatus().filter((t) => !platforms.length || platforms.includes(t.platform));
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ action, skills: rows.map(view) }, null, 2) + '\n');
+    return;
+  }
+  if (rows.length === 0) {
+    process.stdout.write('zcode: nothing to uninstall\n');
+    return;
+  }
+  for (const t of rows) {
+    const what = action === 'install' ? 'installed' : action === 'uninstall' ? 'removed' : t.installed ? 'installed' : 'not installed';
+    process.stdout.write(`${t.name.padEnd(12)} ${what.padEnd(14)} ${t.to}\n`);
+  }
+  if (action === 'status' && rows.some((t) => !t.installed)) {
+    process.stdout.write('\nrun `zcode skills install` to install them\n');
+  }
+};

package/lib/executor.js

@@ -52,7 +52,7 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // Settings a session keeps across invocations (stored as invocation.json).
 const SETTING_KEYS = [
   'kind', 'label', 'cwd', 'model', 'effort', 'timeoutMs', 'maxRepairs', 'checkTimeoutMs',
-  'checks', 'owns', 'ownsDisplay', 'acceptanceDeclared', 'mcpSpecs', 'mcpInherit',
+  'checks', 'owns', 'ownsDisplay', 'acceptanceDeclared', 'mcpSpecs', 'mcpInherit', 'noBrowser',
   'skillsDirs', 'noSkills', 'profile', 'includeReasoning', 'allowOverlap', 'stream',
 ];
 
@@ -338,6 +338,7 @@ async function execute(inv, opts = {}) {
       live: liveDir(env),
       mcpSpecs: inv.mcpSpecs || [],
       mcpInherit: inv.mcpInherit,
+      browser: !inv.noBrowser,
       skillsDirs: inv.skillsDirs || [],
       noSkills: inv.noSkills,
     });

package/lib/isolation.js

@@ -142,8 +142,18 @@ function liveMcpServers(live = LIVE_ZCODE) {
 // base (specs still win by name). Hermetic default is deliberate: the
 // desktop set includes OAuth servers that can never complete headless and
 // stall the engine's connect pool.
-function effectiveMcpServers({ inherit = false, mcpSpecs = [], live = LIVE_ZCODE } = {}) {
-  const servers = inherit ? liveMcpServers(live) : {};
+// Exception: the desktop's local browser server (stdio, no OAuth) is always
+// inherited, so browser prompts open the same Playwright window the desktop
+// opens. --no-browser drops it.
+const BROWSER_SERVERS = ['playwright'];
+
+function effectiveMcpServers({ inherit = false, browser = true, mcpSpecs = [], live = LIVE_ZCODE } = {}) {
+  const liveSet = liveMcpServers(live);
+  const servers = inherit ? liveSet : {};
+  for (const name of BROWSER_SERVERS) {
+    if (!browser) delete servers[name];
+    else if (liveSet[name]) servers[name] = liveSet[name];
+  }
   for (const spec of mcpSpecs) {
     for (const [name, def] of Object.entries(spec)) servers[name] = def;
   }
@@ -200,6 +210,11 @@ function isDanglingLink(p) {
 // sources + this invocation's flags; engine state under the HOME (cli/db,
 // cli/agents, cli/rollout, logs, memories) is never touched, so a session
 // stays resumable across invocations. Returns facts for reporting.
+// Desktop skills that drive the app's own UI (the built-in browser pane).
+// The CLI cannot serve them, and loading one steers the agent away from
+// Playwright into a dead end.
+const HOST_ONLY_SKILLS = new Set(['control-browser']);
+
 function buildEngineHome({
   home,
   root,
@@ -207,6 +222,7 @@ function buildEngineHome({
   live = LIVE_ZCODE,
   mcpSpecs = [],
   mcpInherit = false,
+  browser = true,
   skillsDirs = [],
   noSkills = false,
 }) {
@@ -237,7 +253,7 @@ function buildEngineHome({
     zai.options = zai.options || {};
     zai.options.apiKey = key;
   }
-  const servers = effectiveMcpServers({ inherit: mcpInherit, mcpSpecs, live });
+  const servers = effectiveMcpServers({ inherit: mcpInherit, browser, mcpSpecs, live });
   cfg.mcp = { ...(cfg.mcp || {}), servers };
   writeJson600(path.join(cliDir, 'config.json'), cfg);
 
@@ -268,6 +284,7 @@ function buildEngineHome({
     for (const entry of listDir(liveSkills)) {
       if (!entry.isDirectory()) continue;
       if (!fs.existsSync(path.join(liveSkills, entry.name, 'SKILL.md'))) continue;
+      if (HOST_ONLY_SKILLS.has(entry.name)) continue;
       fs.cpSync(path.join(liveSkills, entry.name), path.join(skillsDir, entry.name), {
         recursive: true,
       });
@@ -345,6 +362,18 @@ function migrateRoot(env = process.env) {
 // config, and the uncontrolled overrides deleted. cwd is set by the caller.
 function engineEnv({ home, builtinProviderConfig, parentEnv = process.env }) {
   const childEnv = { ...parentEnv };
+  const realHome = parentEnv.HOME || os.homedir();
+  // The scratch HOME hides the user's tool caches. Point Playwright and npm
+  // back at the real ones so installed browsers and packages are found.
+  if (!childEnv.PLAYWRIGHT_BROWSERS_PATH) {
+    const cache = process.platform === 'darwin'
+      ? path.join(realHome, 'Library', 'Caches', 'ms-playwright')
+      : path.join(realHome, '.cache', 'ms-playwright');
+    if (fs.existsSync(cache)) childEnv.PLAYWRIGHT_BROWSERS_PATH = cache;
+  }
+  if (!childEnv.npm_config_cache && !childEnv.NPM_CONFIG_CACHE) {
+    childEnv.npm_config_cache = path.join(realHome, '.npm');
+  }
   childEnv.HOME = home;
   childEnv.ZCODE_BUILTIN_PROVIDER_CONFIG_FILE = builtinProviderConfig;
   for (const name of [

package/lib/skills.js

@@ -0,0 +1,64 @@
+'use strict';
+// The orchestrator skills shipped in the package, and where `zcode skills`
+// installs them:
+//
+//   skills/claude-code/zcode  ->  ~/.claude/skills/zcode
+//   skills/codex/zcode        ->  ${CODEX_HOME:-~/.codex}/skills/zcode
+//
+// Only the zcode skill directory is ever replaced or removed.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const pkgRoot = path.join(__dirname, '..');
+const PLATFORMS = ['claude', 'codex'];
+
+function targets(env = process.env) {
+  const home = env.HOME || os.homedir();
+  return [
+    {
+      platform: 'claude',
+      name: 'Claude Code',
+      from: path.join(pkgRoot, 'skills', 'claude-code', 'zcode'),
+      to: path.join(home, '.claude', 'skills', 'zcode'),
+    },
+    {
+      platform: 'codex',
+      name: 'Codex',
+      from: path.join(pkgRoot, 'skills', 'codex', 'zcode'),
+      to: path.join(env.CODEX_HOME || path.join(home, '.codex'), 'skills', 'zcode'),
+    },
+  ];
+}
+
+function select(platforms, env) {
+  const want = platforms && platforms.length ? new Set(platforms) : new Set(PLATFORMS);
+  return targets(env).filter((t) => want.has(t.platform));
+}
+
+function installSkills({ platforms, env = process.env } = {}) {
+  const done = [];
+  for (const t of select(platforms, env)) {
+    fs.mkdirSync(path.dirname(t.to), { recursive: true });
+    fs.rmSync(t.to, { recursive: true, force: true });
+    fs.cpSync(t.from, t.to, { recursive: true });
+    done.push(t);
+  }
+  return done;
+}
+
+function uninstallSkills({ platforms, env = process.env } = {}) {
+  const done = [];
+  for (const t of select(platforms, env)) {
+    if (!fs.existsSync(t.to)) continue;
+    fs.rmSync(t.to, { recursive: true, force: true });
+    done.push(t);
+  }
+  return done;
+}
+
+function skillStatus({ env = process.env } = {}) {
+  return targets(env).map((t) => ({ ...t, installed: fs.existsSync(path.join(t.to, 'SKILL.md')) }));
+}
+
+module.exports = { installSkills, uninstallSkills, skillStatus, targets, PLATFORMS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xgeorgemathew/zcode",
-  "version": "0.4.1",
+  "version": "0.4.4",
   "description": "Lean GLM-5.3 execution engine for orchestrator agents: task contracts, independent sessions, zcode-run verification, structured handbacks, subagents, MCP, skills. Wraps the ZCode engine. Zero dependencies.",
   "license": "MIT",
   "private": false,
@@ -21,7 +21,6 @@
     "LICENSE"
   ],
   "scripts": {
-    "postinstall": "node lib/install-skills.js",
     "test": "node --test --test-concurrency=1 \"test/unit/*.test.js\"",
     "test:live": "node --test --test-concurrency=1 \"test/live/*.test.js\"",
     "prepublishOnly": "npm test && npm run test:live",

package/skills/README.md

@@ -9,9 +9,15 @@ These skills teach an orchestrating agent how to delegate work to zcode, run ses
 
 ## Install
 
-`npm install -g @0xgeorgemathew/zcode` installs both skills for you. Its postinstall step copies the Claude Code skill to `~/.claude/skills/zcode` and the Codex skill to `${CODEX_HOME:-~/.codex}/skills/zcode`, replacing any earlier copy of the zcode skill only. Set `ZCODE_SKIP_SKILLS=1` to skip it. If npm runs with `--ignore-scripts`, nothing is copied; use the manual steps below.
+After `npm install -g @0xgeorgemathew/zcode`, install both skills with:
 
-Run these from a checkout of this repo, or from the installed package (`$(npm root -g)/@0xgeorgemathew/zcode`), which ships `skills/`.
+```sh
+zcode skills install          # or: zcode skills install claude | codex
+```
+
+This copies the Claude Code skill to `~/.claude/skills/zcode` and the Codex skill to `${CODEX_HOME:-~/.codex}/skills/zcode`, replacing only an earlier copy of the zcode skill. Run it again after upgrading zcode to refresh them. `zcode skills` shows what is installed, and `zcode skills uninstall` removes them. The package runs no install scripts, so npm never asks to allow one.
+
+To copy them by hand instead, run these from a checkout of this repo, or from the installed package (`$(npm root -g)/@0xgeorgemathew/zcode`), which ships `skills/`.
 
 **Claude Code.** Personal skills, available in every project:
 

package/lib/install-skills.js

@@ -1,54 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-// postinstall: copy the orchestrator skills into Claude Code and Codex.
-//
-//   skills/claude-code/zcode  ->  ~/.claude/skills/zcode
-//   skills/codex/zcode        ->  ${CODEX_HOME:-~/.codex}/skills/zcode
-//
-// Only the zcode skill directory is replaced; nothing else is touched.
-// Skipped inside the source checkout (a .git next to package.json) and when
-// ZCODE_SKIP_SKILLS=1. Never fails the install: errors become one warning.
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-
-const pkgRoot = path.join(__dirname, '..');
-
-function targets(env = process.env) {
-  const home = os.homedir();
-  return [
-    {
-      name: 'Claude Code',
-      from: path.join(pkgRoot, 'skills', 'claude-code', 'zcode'),
-      to: path.join(home, '.claude', 'skills', 'zcode'),
-    },
-    {
-      name: 'Codex',
-      from: path.join(pkgRoot, 'skills', 'codex', 'zcode'),
-      to: path.join(env.CODEX_HOME || path.join(home, '.codex'), 'skills', 'zcode'),
-    },
-  ];
-}
-
-function installSkills(env = process.env) {
-  const done = [];
-  for (const t of targets(env)) {
-    if (!fs.existsSync(t.from)) continue;
-    fs.mkdirSync(path.dirname(t.to), { recursive: true });
-    fs.rmSync(t.to, { recursive: true, force: true });
-    fs.cpSync(t.from, t.to, { recursive: true });
-    done.push(t);
-  }
-  return done;
-}
-
-if (require.main === module) {
-  if (process.env.ZCODE_SKIP_SKILLS === '1' || fs.existsSync(path.join(pkgRoot, '.git'))) process.exit(0);
-  try {
-    for (const t of installSkills()) console.log(`zcode: installed ${t.name} skill -> ${t.to}`);
-  } catch (err) {
-    console.warn(`zcode: could not install skills (${err.message}). Copy them from ${path.join(pkgRoot, 'skills')}.`);
-  }
-}
-
-module.exports = { installSkills, targets };