@0xgeorgemathew/zcode 0.3.0

package/lib/commands/agent.js

@@ -0,0 +1,203 @@
+'use strict';
+// lib/commands/agent.js — subagent-dispatching turn, verified programmatically
+// (DESIGN §11): dispatch-forcing preamble, yolo run, then session/subagents
+// RPC joined with the scratch agents dir. Never trusts the model's prose;
+// exit 6 when no subagent ran or none ended "success".
+const fs = require('node:fs');
+const path = require('node:path');
+const { executeTurn, TurnError } = require('../appserver.js');
+const { bootstrap } = require('../bootstrap.js');
+
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Join session/subagents ended items with <home>/.zcode/cli/agents/<parent>/
+// agent_<uuid>/{metadata.json,output.txt} (all under the scratch HOME we own).
+function collectSubagents({ client, sessionId, isolationHome, scrub }) {
+  return client
+    .request('session/subagents', { sessionId }, { timeoutMs: 15000 })
+    .catch((err) => {
+      throw new TurnError(`session/subagents failed: ${scrub(err.message)}`, {
+        kind: 'subagents_rpc',
+      });
+    })
+    .then((result) => {
+      const items = (result && result.ended && result.ended.items) || [];
+      const running = (result && result.running) || [];
+      const agentsDir = path.join(
+        isolationHome,
+        '.zcode',
+        'cli',
+        'agents',
+        sessionId
+      );
+      const out = [];
+      for (const item of items) {
+        const dir = path.join(agentsDir, `agent_${(item.agentId || '').replace(/^agent_/, '')}`);
+        const metadata =
+          readJsonSafe(path.join(dir, 'metadata.json')) || null;
+        let output = null;
+        try {
+          output = fs.readFileSync(path.join(dir, 'output.txt'), 'utf8');
+        } catch {
+          /* subagent may not have flushed output */
+        }
+        out.push({
+          agentId: item.agentId || (metadata && metadata.agentId) || null,
+          childSessionId:
+            item.childSessionId || (metadata && metadata.childSessionId) || null,
+          profileId: (metadata && metadata.profileId) || item.subagentType || null,
+          title: item.title || (metadata && metadata.description) || null,
+          status: item.status || null,
+          summary: item.summary || null,
+          output,
+          startedAt: item.startedAt || null,
+          endedAt: item.endedAt || null,
+          durationMs:
+            item.startedAt && item.endedAt ? item.endedAt - item.startedAt : null,
+        });
+      }
+      return { subagents: out, runningCount: running.length };
+    });
+}
+
+module.exports = async function agent(parsed) {
+  const flags = parsed.flags;
+  const instructions = parsed.prompts.join(' ');
+  if (!instructions.trim()) {
+    process.stderr.write('zcode: agent needs instructions.\n');
+    process.exit(2);
+  }
+  const profile = flags.profile || 'general-purpose';
+  const prompt =
+    `You MUST use the Agent tool (profileId: "${profile}") to accomplish the ` +
+    `task below — do not do the work yourself. When the subagent finishes, ` +
+    `report its agent id and result.\n\nTask: ${instructions}`;
+
+  const { client, scrub, isolation, overlay } = bootstrap({
+    fresh: flags.fresh,
+    mcpSpecs: flags.mcpSpecs,
+    mcpInherit: flags.mcpInherit,
+    skillsDirs: flags.skillsDirs,
+    noSkills: flags.noSkills,
+  });
+  client.start();
+  process.on('SIGINT', () => {
+    client.kill();
+    process.exit(130);
+  });
+  const reporter = require('../ui.js').makePlainReporter({ quiet: flags.quiet });
+  try {
+    const turn = await executeTurn(client, {
+      workspacePath: flags.cwd,
+      modelId: flags.model,
+      effort: flags.effort,
+      prompt,
+      timeoutMs: flags.timeoutMs,
+      resumeSessionId: flags.session || null,
+      requiredMcp: overlay.mcp.added,
+      onEvent: (ev) => {
+        if (flags.json) process.stdout.write(JSON.stringify(ev) + '\n');
+        else reporter.onEvent(ev);
+      },
+    });
+
+    const { subagents, runningCount } = await collectSubagents({
+      client,
+      sessionId: turn.sessionId,
+      isolationHome: isolation.home,
+      scrub,
+    });
+
+    const ok = subagents.length >= 1 && subagents.every((s) => s.status === 'success');
+
+    if (flags.json) {
+      process.stdout.write(
+        JSON.stringify({
+          type: 'result',
+          ok,
+          response: turn.response,
+          model: turn.engineModel || flags.model,
+          modelRequested: flags.model,
+          effort: turn.engineReasoningLevel || flags.effort,
+          effortRequested: flags.effort,
+          mode: turn.mode,
+          sessionId: turn.sessionId,
+          resumed: turn.resumed,
+          usage: turn.usage
+            ? {
+                inputTokens: turn.usage.inputTokens ?? null,
+                outputTokens: turn.usage.outputTokens ?? null,
+              }
+            : null,
+          reasoningChars: turn.reasoningText.length,
+          toolCalls: turn.toolCallCount,
+          mcpServers: Object.keys(overlay.mcp.servers),
+          skillsInjected: overlay.skills.injected,
+          subagents,
+          runningSubagents: runningCount,
+          durationMs: turn.durationMs,
+        }) + '\n'
+      );
+    } else if (!ok) {
+      process.stdout.write(turn.response + '\n');
+    } else {
+      process.stdout.write(turn.response + '\n');
+      reporter.footer({
+        model: turn.engineModel || flags.model,
+        effort: turn.engineReasoningLevel || flags.effort,
+        toolCalls: turn.toolCallCount,
+        durationMs: turn.durationMs,
+        sessionId: turn.sessionId,
+      });
+      for (const s of subagents) {
+        const secs = typeof s.durationMs === 'number' ? `  ${(s.durationMs / 1000).toFixed(1)}s` : '';
+        process.stderr.write(
+          (process.stderr.isTTY ? '\x1b[2m' : '') +
+            `✓ subagent ${s.profileId}${secs}` +
+            (process.stderr.isTTY ? '\x1b[0m' : '') + '\n'
+        );
+        if (s.summary) {
+          process.stderr.write(
+            (process.stderr.isTTY ? '\x1b[2m' : '') +
+              `  ${s.summary.replace(/\s+/g, ' ').trim().slice(0, 200)}` +
+              (process.stderr.isTTY ? '\x1b[0m' : '') + '\n'
+          );
+        }
+      }
+    }
+    client.kill();
+    if (!ok) {
+      const why =
+        subagents.length === 0
+          ? 'no subagent was dispatched'
+          : `subagent statuses: ${subagents.map((s) => s.status).join(', ')}`;
+      process.stderr.write(`zcode: agent verification failed: ${why}\n`);
+      process.exit(6);
+    }
+    process.exit(0);
+  } catch (err) {
+    client.kill();
+    if (flags.json) {
+      process.stdout.write(
+        JSON.stringify({
+          type: 'result',
+          ok: false,
+          error: err.kind || 'error',
+          message: scrub(err.message),
+        }) + '\n'
+      );
+    }
+    if (err instanceof TurnError && err.kind === 'timeout') {
+      process.stderr.write(`zcode: ${scrub(err.message)}\n`);
+      process.exit(124);
+    }
+    process.stderr.write(`zcode: agent turn failed: ${scrub(err.message)}\n`);
+    process.exit(5);
+  }
+}

package/lib/commands/doctor.js

@@ -0,0 +1,118 @@
+'use strict';
+// lib/commands/doctor.js — engine + isolation + key report (DESIGN §10).
+// Never prints the key. Warns when the spawning node major < 26 (R11).
+const {
+  resolveEngine,
+  resolveBuiltinProviderConfig,
+  sha256File,
+  engineVersion,
+  EngineNotFoundError,
+  BuiltinConfigNotFoundError,
+} = require('../engine.js');
+const { resolveKey, NoKeyError, rootDir } = require('../key.js');
+const { ensureIsolation, engineEnv } = require('../isolation.js');
+const { effectiveMcpServers } = require('../overlay.js');
+
+module.exports = async function doctor(parsed) {
+  const flags = parsed.flags;
+  let enginePath;
+  try {
+    enginePath = resolveEngine(process.env);
+  } catch (err) {
+    if (err instanceof EngineNotFoundError) {
+      process.stderr.write(`zcode: ${err.message}\n`);
+      process.exit(4);
+    }
+    throw err;
+  }
+
+  let key;
+  try {
+    key = resolveKey(process.env);
+  } catch (err) {
+    if (err instanceof NoKeyError) {
+      process.stderr.write(`zcode: ${err.message}\n`);
+      process.exit(3);
+    }
+    throw err;
+  }
+
+  let builtinConfig;
+  try {
+    builtinConfig = resolveBuiltinProviderConfig(enginePath, process.env);
+  } catch (err) {
+    if (err instanceof BuiltinConfigNotFoundError) {
+      process.stderr.write(`zcode: ${err.message}\n`);
+      process.exit(4);
+    }
+    throw err;
+  }
+
+  const isolation = ensureIsolation(key, { fresh: flags.fresh, env: process.env });
+  const nodeBin = process.env.ZAI_CODE_NODE || process.execPath;
+  const childEnv = engineEnv({
+    home: isolation.home,
+    builtinProviderConfig: builtinConfig,
+  });
+  const version = engineVersion(nodeBin, enginePath, childEnv);
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  const nodeWarning = nodeMajor < 26;
+
+  const report = {
+    ok: true,
+    node: {
+      version: process.versions.node,
+      major: nodeMajor,
+      engineBin: nodeBin,
+      recommendation:
+        nodeMajor < 26
+          ? 'engine has only been tested under node >= 26; set ZAI_CODE_NODE to a newer interpreter'
+          : 'ok',
+      warning: nodeWarning,
+    },
+    engine: {
+      path: enginePath,
+      sha256: sha256File(enginePath),
+      version,
+      builtinProviderConfig: builtinConfig,
+    },
+    isolation: {
+      root: isolation.root,
+      home: isolation.home,
+      mode: isolation.mode,
+      builtNow: isolation.built,
+      skillsCopied:
+        (isolation.stamp && typeof isolation.stamp.skillsCopied === 'number'
+          ? isolation.stamp.skillsCopied
+          : 0) || 0,
+      mcpServersInherited: Object.keys(effectiveMcpServers({})).length,
+      experimental:
+        isolation.mode === 'synthesized'
+          ? 'synthesized config path is unproven; copy a real ~/.zcode/v2 or verify once on a clean HOME'
+          : null,
+    },
+    key: { configured: true },
+  };
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(report) + '\n');
+  } else {
+    process.stdout.write(
+      [
+        `zcode doctor`,
+        `  node ${report.node.version} (${nodeBin})${nodeWarning ? '  ⚠ ' + report.node.recommendation : ''}`,
+        `  engine ${enginePath}`,
+        `    sha256 ${report.engine.sha256}`,
+        `    version ${version ?? 'unknown'}`,
+        `  builtin provider config ${builtinConfig}`,
+        `  isolation home ${isolation.home} (mode: ${isolation.mode}${isolation.built ? ', built now' : ', cached'})`,
+        `  skills inherited ${report.isolation.skillsCopied}, mcp servers available with --mcp-inherit ${report.isolation.mcpServersInherited}`,
+        `  api key configured (never printed)`,
+        report.isolation.experimental ? `  ⚠ ${report.isolation.experimental}` : '',
+      ]
+        .filter(Boolean)
+        .join('\n') + '\n'
+    );
+  }
+  process.exit(0);
+};

package/lib/commands/login.js

@@ -0,0 +1,48 @@
+'use strict';
+// lib/commands/login.js — read the API key from stdin and store it at
+// <root>/credentials.json (mode 600, root mode 700) (DESIGN §5, §10).
+// The key is never echoed. Output deliberately contains no key material.
+const fs = require('node:fs');
+const path = require('node:path');
+const { rootDir } = require('../key.js');
+
+module.exports = async function login() {
+  if (process.stdin.isTTY) {
+    process.stderr.write(
+      'zcode login: paste your API key on stdin (it will not be echoed back):\n'
+    );
+  }
+  let input = '';
+  await new Promise((resolve) => {
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => (input += c));
+    process.stdin.on('end', resolve);
+    process.stdin.on('error', resolve);
+    if (process.stdin.isTTY) process.stdin.resume();
+  });
+  const key = input.trim();
+  if (!key) {
+    process.stderr.write('zcode login: no key received on stdin.\n');
+    process.exit(2);
+  }
+
+  const root = rootDir(process.env);
+  fs.mkdirSync(root, { recursive: true });
+  fs.chmodSync(root, 0o700);
+  const file = path.join(root, 'credentials.json');
+  fs.writeFileSync(file, JSON.stringify({ apiKey: key }, null, 2) + '\n', {
+    mode: 0o600,
+  });
+  fs.chmodSync(file, 0o600);
+  // Invalidate the isolation stamp: the scratch key must be rebuilt from the
+  // new credentials on the next run (key fingerprint change triggers it, but
+  // be explicit when the credentials file is the source).
+  const stamp = path.join(root, 'build-stamp.json');
+  try {
+    fs.rmSync(stamp, { force: true });
+  } catch {
+    /* nothing to invalidate */
+  }
+  process.stdout.write(`zcode login: key stored at ${file} (mode 600)\n`);
+  process.exit(0);
+};

package/lib/commands/mcp-list.js

@@ -0,0 +1,20 @@
+'use strict';
+// lib/commands/mcp-list.js — print the effective MCP server set for this
+// invocation as one JSON line and exit 0. Never spawns the engine; the
+// value is exactly what a run with the same flags would register.
+const { bootstrap } = require('../bootstrap.js');
+
+module.exports = async function mcpList(parsed) {
+  const flags = parsed.flags;
+  const { overlay } = bootstrap({
+    fresh: flags.fresh,
+    mcpSpecs: flags.mcpSpecs,
+    mcpInherit: flags.mcpInherit,
+    skillsDirs: flags.skillsDirs,
+    noSkills: flags.noSkills,
+  });
+  process.stdout.write(
+    JSON.stringify({ type: 'mcp', servers: overlay.mcp.servers }) + '\n'
+  );
+  process.exit(0);
+};

package/lib/commands/run.js

@@ -0,0 +1,126 @@
+'use strict';
+// lib/commands/run.js — one-shot turn (DESIGN §9, §10), agent-first: NDJSON
+// stream on stdout with --json (incl. reasoning_delta = thinking and tool
+// lifecycle), reasoning mirrored to stderr live in plain mode, session
+// continuity via --session, MCP/skills overlays applied per run.
+const { executeTurn, TurnError } = require('../appserver.js');
+const { bootstrap } = require('../bootstrap.js');
+const { makePlainReporter } = require('../ui.js');
+
+// Prompt: positional argv joined, else stdin (when piped).
+function readPrompt(parsed) {
+  if (parsed.prompts.length > 0) return parsed.prompts.join(' ');
+  if (!process.stdin.isTTY) {
+    return require('node:fs').readFileSync(0, 'utf8');
+  }
+  return '';
+}
+
+module.exports = async function run(parsed) {
+  const flags = parsed.flags;
+  const prompt = readPrompt(parsed);
+  if (!prompt.trim()) {
+    process.stderr.write('zcode: no prompt given (positional args or stdin).\n');
+    process.exit(2);
+  }
+
+  const { client, scrub, overlay } = bootstrap({
+    fresh: flags.fresh,
+    mcpSpecs: flags.mcpSpecs,
+    mcpInherit: flags.mcpInherit,
+    skillsDirs: flags.skillsDirs,
+    noSkills: flags.noSkills,
+  });
+  const workspacePath = flags.cwd;
+  let streamedText = '';
+  const reporter = makePlainReporter({ quiet: flags.quiet });
+  const onEvent = flags.json
+    ? (ev) => process.stdout.write(JSON.stringify(ev) + '\n')
+    : (ev) => {
+        if (ev.type === 'stream' && ev.kind === 'text_delta' && ev.delta) {
+          reporter.closeThinking();
+          streamedText += ev.delta;
+          process.stdout.write(ev.delta);
+        } else {
+          reporter.onEvent(ev);
+        }
+      };
+
+  client.start();
+  process.on('SIGINT', () => {
+    client.kill();
+    process.exit(130);
+  });
+  try {
+    const turn = await executeTurn(client, {
+      workspacePath,
+      modelId: flags.model,
+      effort: flags.effort,
+      prompt,
+      timeoutMs: flags.timeoutMs,
+      resumeSessionId: flags.session || null,
+      requiredMcp: overlay.mcp.added,
+      onEvent,
+    });
+    if (flags.json) {
+      const result = {
+        type: 'result',
+        ok: true,
+        response: turn.response,
+        model: turn.engineModel || flags.model,
+        modelRequested: flags.model,
+        effort: turn.engineReasoningLevel || flags.effort,
+        effortRequested: flags.effort,
+        mode: turn.mode,
+        sessionId: turn.sessionId,
+        resumed: turn.resumed,
+        usage: turn.usage
+          ? {
+              inputTokens: turn.usage.inputTokens ?? null,
+              outputTokens: turn.usage.outputTokens ?? null,
+            }
+          : null,
+        reasoningChars: turn.reasoningText.length,
+        toolCalls: turn.toolCallCount,
+        toolEvents: turn.toolEvents,
+        mcpServers: Object.keys(overlay.mcp.servers),
+        skillsInjected: overlay.skills.injected,
+        terminalStatus: turn.terminalStatus,
+        streamingEvents: turn.streamingEvents,
+        durationMs: turn.durationMs,
+      };
+      if (flags.includeReasoning) result.reasoning = turn.reasoningText;
+      process.stdout.write(JSON.stringify(result) + '\n');
+    } else {
+      reporter.footer({
+        model: turn.engineModel || flags.model,
+        effort: turn.engineReasoningLevel || flags.effort,
+        toolCalls: turn.toolCallCount,
+        durationMs: turn.durationMs,
+        sessionId: turn.sessionId,
+      });
+      if (!streamedText.trim()) process.stdout.write(turn.response);
+      process.stdout.write('\n');
+    }
+    client.kill();
+    process.exit(0);
+  } catch (err) {
+    client.kill();
+    if (flags.json) {
+      process.stdout.write(
+        JSON.stringify({
+          type: 'result',
+          ok: false,
+          error: err.kind || 'error',
+          message: scrub(err.message),
+        }) + '\n'
+      );
+    }
+    if (err instanceof TurnError && err.kind === 'timeout') {
+      process.stderr.write(`zcode: ${scrub(err.message)}\n`);
+      process.exit(124);
+    }
+    process.stderr.write(`zcode: turn failed: ${scrub(err.message)}\n`);
+    process.exit(5);
+  }
+};

package/lib/engine.js

@@ -0,0 +1,139 @@
+'use strict';
+// Engine resolution + builtin provider config (DESIGN §4).
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+const APP_BUNDLE_ENGINE =
+  '/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs';
+
+class EngineNotFoundError extends Error {
+  constructor(probed) {
+    super(
+      `ZCode engine not found. Probed:\n  ${probed.join('\n  ')}\n` +
+        'Set ZAI_CODE_ENGINE to the zcode.cjs bundle path.'
+    );
+    this.code = 'ZAI_NO_ENGINE';
+    this.probed = probed;
+  }
+}
+
+class BuiltinConfigNotFoundError extends Error {
+  constructor(probed) {
+    super(
+      `ZCode builtin provider config not found. Probed:\n  ${probed.join('\n  ')}\n` +
+        'Set ZAI_CODE_BUILTIN_PROVIDER_CONFIG to the zcode-builtin.json path.'
+    );
+    this.code = 'ZAI_NO_BUILTIN_CONFIG';
+    this.probed = probed;
+  }
+}
+
+// Resolves a candidate that is either the zcode.cjs file itself or a
+// directory containing it. Returns an absolute file path or null.
+function resolveCandidate(candidate) {
+  let st;
+  try {
+    st = fs.statSync(candidate);
+  } catch {
+    return null;
+  }
+  if (st.isFile()) return path.resolve(candidate);
+  if (st.isDirectory()) {
+    const inner = path.join(candidate, 'zcode.cjs');
+    try {
+      if (fs.statSync(inner).isFile()) return path.resolve(inner);
+    } catch {
+      /* not there */
+    }
+  }
+  return null;
+}
+
+function whichOnPath(bin, envPath) {
+  if (!envPath) return null;
+  for (const dir of envPath.split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, bin);
+    try {
+      if (fs.statSync(candidate).isFile()) return candidate;
+    } catch {
+      /* keep scanning */
+    }
+  }
+  return null;
+}
+
+// First hit wins (DESIGN §4). Throws EngineNotFoundError listing all probes.
+function resolveEngine(env = process.env) {
+  const probed = [];
+  const candidates = [];
+  if (env.ZAI_CODE_ENGINE) candidates.push(env.ZAI_CODE_ENGINE);
+  const onPath = whichOnPath('zcode', env.PATH);
+  if (onPath) candidates.push(onPath);
+  candidates.push(path.join(os.homedir(), '.local', 'bin', 'zcode'));
+  candidates.push(path.join(os.homedir(), '.zcode', 'runtime', 'zcode.cjs'));
+  candidates.push(APP_BUNDLE_ENGINE);
+  for (const candidate of candidates) {
+    const resolved = resolveCandidate(candidate);
+    if (resolved) return resolved;
+    probed.push(candidate);
+  }
+  throw new EngineNotFoundError(probed);
+}
+
+// Engine-adjacent builtin provider config, or env override. Throws
+// BuiltinConfigNotFoundError with the probed paths.
+function resolveBuiltinProviderConfig(enginePath, env = process.env) {
+  const probed = [];
+  const candidates = [];
+  if (env.ZAI_CODE_BUILTIN_PROVIDER_CONFIG) {
+    candidates.push(env.ZAI_CODE_BUILTIN_PROVIDER_CONFIG);
+  }
+  candidates.push(
+    path.resolve(
+      path.dirname(enginePath),
+      '..',
+      'config',
+      'provider',
+      'zcode-builtin.json'
+    )
+  );
+  for (const candidate of candidates) {
+    try {
+      if (fs.statSync(candidate).isFile()) return path.resolve(candidate);
+    } catch {
+      /* fall through */
+    }
+    probed.push(candidate);
+  }
+  throw new BuiltinConfigNotFoundError(probed);
+}
+
+function sha256File(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+// `zcode.cjs version` run under the ISOLATED env (never the live HOME).
+// Returns trimmed stdout or null.
+function engineVersion(nodeBin, enginePath, childEnv) {
+  const res = spawnSync(nodeBin, [enginePath, 'version'], {
+    env: childEnv,
+    encoding: 'utf8',
+    timeout: 20000,
+  });
+  if (res.error || res.status !== 0) return null;
+  return (res.stdout || '').trim() || null;
+}
+
+module.exports = {
+  resolveEngine,
+  resolveBuiltinProviderConfig,
+  sha256File,
+  engineVersion,
+  EngineNotFoundError,
+  BuiltinConfigNotFoundError,
+  APP_BUNDLE_ENGINE,
+};