@zergai/ztc 0.2.2-dev.35681806994 → 0.2.4-dev.35964790590

package/README.md

@@ -1038,3 +1038,20 @@ the ZTC 0.1.x releases.
 ---
 
 Part of the [Zerg](https://github.com/idanbeck/zerg) autonomous AI framework.
+
+## Updating the npm CLI
+
+Run `ztc update` or `ztc --update` to install a newer npm
+release. `ztc update --check` prints JSON without installing. The
+installed channel is preserved (`dev`, `next`, or `latest`); select a channel
+explicitly with `update --channel dev|next|latest`. Updates never downgrade.
+
+Startup checks only notify on stderr when it is a terminal, never prompt or
+install, and are cached for one hour. CI, redirected stderr, and help/version
+requests skip checks. Set `ZERGAI_NO_UPDATE_CHECK=1` to disable startup checks.
+Self-installation requires the matching macOS/Linux global npm prefix; local,
+linked, npx, or other package-manager installs must use their original manager.
+Existing releases need one ordinary npm upgrade before these commands exist.
+
+See [shared updater policy](https://github.com/Epoch-ML/zerg/blob/development/docs/npm-cli-updates.md)
+for installation safety, channel switching, and packaging details.

package/dist/agent/backends/codex_auth.js

@@ -337,6 +337,9 @@ export class CodexAuthBackend {
             stream: true,
             store: false,
         };
+        if (request.outputFormat !== undefined) {
+            body.text = { format: request.outputFormat };
+        }
         if (tools.length > 0) {
             body.tools = tools;
             body.tool_choice = 'auto';

package/dist/agent/backends/types.d.ts

@@ -89,6 +89,15 @@ export interface BackendRequest {
     system: string;
     messages: LlmMessage[];
     tools: ToolDefinition[];
+    /** Explicit Responses text format for Codex subscription inference callers. */
+    outputFormat?: {
+        type: 'text' | 'json_object';
+    } | {
+        type: 'json_schema';
+        name: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+    };
     /** Router-owned retry plan. Only ZRouter transports put this on the wire. */
     routePlan?: {
         fallbacks: string[];

package/dist/agent/commands/debug.js

@@ -9,14 +9,16 @@ import { attachMiniZdePane } from '../../zerg/mini_zde_render.js';
 import { summarizeLoadedManifestYaml, summarizeManifestYaml } from '../../zerg/mini_zde_state.js';
 /**
  * Walk upward from `startDir` looking for the repo's bundled headlines
- * manifest.  Matches `<repo>/zaai/domains/core/headlines/headlines.yaml`.
+ * manifest. Matches `<repo>/zerg/zaai/...` and the installed `/app/zaai/...` layout.
  */
 function findHeadlinesManifestPath(startDir = process.cwd()) {
     let current = resolve(startDir);
     while (true) {
-        const candidate = join(current, 'zaai', 'domains', 'core', 'headlines', 'headlines.yaml');
-        if (existsSync(candidate)) {
-            return candidate;
+        for (const suite of [join(current, 'zerg', 'zaai'), join(current, 'zaai')]) {
+            const candidate = join(suite, 'domains', 'core', 'headlines', 'headlines.yaml');
+            if (existsSync(candidate)) {
+                return candidate;
+            }
         }
         const parent = dirname(current);
         if (parent === current) {

package/dist/agent/tools/adaptation.js

@@ -171,12 +171,12 @@ export const adaptationRunTool = {
             ...(args.api_auth_headers ? { api_auth_headers: JSON.parse(args.api_auth_headers) } : {}),
         };
         // Derive output_dir (mirrors cli.py) for adaptation.log.
-        // cli.py sits at zerg/zaai/domains/connector_generation/cli.py; 3 ups from its
-        // parent reaches zerg/ (the repo root), which has dcaig/ as a direct child
+        // cli.py sits at zerg/zaai/domains/connector_generation/cli.py; 4 ups from its
+        // parent reaches the monorepo root, which has dcaig/ as a direct child
         // (matches cli.py's Python-side workspace derivation at cli.py:90-91).
         const workspace = process.env.ZERG_WORKSPACE_ROOT
             || (() => {
-                const derived = resolve(dirname(runnerPath), '..', '..', '..');
+                const derived = resolve(dirname(runnerPath), '..', '..', '..', '..');
                 if (!existsSync(resolve(derived, 'dcaig'))) {
                     throw new Error(`Derived workspace ${derived} has no dcaig/ child. Set ZERG_WORKSPACE_ROOT explicitly.`);
                 }

package/dist/web/mirror_stream.js

@@ -1829,14 +1829,18 @@ export class MirrorStreamServer {
         const override = process.env.ZERG_CV_STATE_PATH;
         if (override)
             return override;
+        const zaaiRoot = process.env.ZAAI_ROOT;
+        if (zaaiRoot) {
+            return resolve(zaaiRoot, 'domains', 'zcloud', 'modules', 'cv', 'cv_runner', 'state.json');
+        }
         const repoRoot = process.env.ZERG_REPO_ROOT;
         if (repoRoot) {
-            return resolve(repoRoot, 'zaai', 'domains', 'zcloud', 'modules', 'cv', 'cv_runner', 'state.json');
+            return resolve(repoRoot, 'zerg', 'zaai', 'domains', 'zcloud', 'modules', 'cv', 'cv_runner', 'state.json');
         }
         // Walk up from this file: ztc/src/web/mirror_stream.ts -> repo root.
         const here = fileURLToPath(import.meta.url);
         const fallbackRoot = resolve(here, '..', '..', '..', '..');
-        return resolve(fallbackRoot, 'zaai', 'domains', 'zcloud', 'modules', 'cv', 'cv_runner', 'state.json');
+        return resolve(fallbackRoot, 'zerg', 'zaai', 'domains', 'zcloud', 'modules', 'cv', 'cv_runner', 'state.json');
     }
     /**
      * GET /cv/snapshot — replaces the old Django /api/cv/snapshot endpoint.
@@ -1855,7 +1859,7 @@ export class MirrorStreamServer {
         catch (error) {
             // Missing file with no override env vars set → return empty snapshot.
             // This mirrors the Django endpoint's "soft 200" path for fresh repos.
-            const overridden = !!(process.env.ZERG_CV_STATE_PATH || process.env.ZERG_REPO_ROOT);
+            const overridden = !!(process.env.ZERG_CV_STATE_PATH || process.env.ZERG_REPO_ROOT || process.env.ZAAI_ROOT);
             if (!overridden && error.code === 'ENOENT') {
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ schema_version: SCHEMA_VERSION, scenarios: [] }));

package/dist/zlm-embed.mjs

@@ -2408,6 +2408,9 @@ var init_codex_auth = __esm({
           stream: true,
           store: false
         };
+        if (request.outputFormat !== void 0) {
+          body.text = { format: request.outputFormat };
+        }
         if (tools.length > 0) {
           body.tools = tools;
           body.tool_choice = "auto";
@@ -12130,7 +12133,7 @@ var invokeSkillTool = makeInvokeSkillTool(resolveAmbientSkills);
 // src/zlm.ts
 var ZLM_EMBED_API_VERSION = "zerglang.ztc-embed/1";
 var ZLM_STDIO_PROTOCOL = "zerglang.ztc-host/1";
-var ZLM_ZTC_VERSION = true ? "0.2.2-dev.35681806994" : "development";
+var ZLM_ZTC_VERSION = true ? "0.2.4-dev.35964790590" : "development";
 var ZLM_MAX_HOST_TOOLS = 64;
 var ZLM_MAX_SYSTEM_PROMPT_BYTES = 128 * 1024;
 var ZLM_HOST_APPROVAL_CAPABILITIES = Object.freeze([

package/npm-cli/npm-process.cjs

@@ -0,0 +1,21 @@
+'use strict';
+const { execFile, spawn } = require('node:child_process');
+const { promisify } = require('node:util');
+
+// Kept separate so OS process contracts can be exercised independently from the
+// version/cache policy. This is copied alongside the updater in each artifact.
+module.exports = async function runNpm(args, options) {
+  if (args[0] === 'prefix') return promisify(execFile)('npm', args, { ...options, encoding: 'utf8', timeout: 5000, maxBuffer: 16384 });
+  await new Promise((done, fail) => {
+    const child = spawn('npm', args, { ...options, stdio: ['ignore', 'inherit', 'inherit'], shell: false });
+    // npm shares the foreground group; a terminal has already signalled it.
+    const relay = ![process.stdin, process.stdout, process.stderr].some(stream => stream.isTTY);
+    const interrupt = () => { if (relay) child.kill('SIGINT'); };
+    const terminate = () => { if (relay) child.kill('SIGTERM'); };
+    process.on('SIGINT', interrupt); process.on('SIGTERM', terminate);
+    const cleanup = () => { process.off('SIGINT', interrupt); process.off('SIGTERM', terminate); };
+    child.on('error', error => { cleanup(); fail(error); });
+    child.on('exit', (code, signal) => { cleanup(); if (code === 0) done(); else fail(new Error(`npm exited ${signal || code}`)); });
+  });
+  return { stdout: '' };
+};

package/npm-cli/run.cjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict';
+const { spawn } = require('node:child_process');
+const { join } = require('node:path');
+const { handleUpdate } = require('./update.cjs');
+
+async function main() {
+  const root = join(__dirname, '..');
+  const args = process.argv.slice(2);
+  const result = await handleUpdate({ root, args });
+  if (result !== null) { process.exitCode = result; return; }
+  if (args.length === 1 && ['--help', '-h', 'help'].includes(args[0])) {
+    process.stdout.write('Updates: update | --update [--check] [--channel dev|next|latest]\n');
+  }
+  const metadata = require('../package.json');
+  // ZTC's old TUI updaters must not install silently behind this launch policy.
+  const env = { ...process.env };
+  if (['@zergai/ztc', 'zerg-ztc'].includes(metadata.name)) {
+    env.ZTC_NO_AUTO_UPDATE = '1'; env.ZTC_DISABLE_UPDATE = '1';
+  }
+  const child = spawn(process.execPath, [join(root, metadata.zergCli.entry), ...args], { stdio: 'inherit', env });
+  // Attached terminals signal the foreground group, including the child. Relay
+  // only for non-TTY supervisors; keep the group intact for terminal resize.
+  const relay = ![process.stdin, process.stdout, process.stderr].some(stream => stream.isTTY);
+  const interrupt = () => { if (relay) child.kill('SIGINT'); };
+  const terminate = () => { if (relay) child.kill('SIGTERM'); };
+  process.on('SIGINT', interrupt); process.on('SIGTERM', terminate);
+  const cleanup = () => { process.off('SIGINT', interrupt); process.off('SIGTERM', terminate); };
+  child.on('error', error => { cleanup(); console.error(`Unable to launch ${metadata.name}: ${error.message}`); process.exitCode = 1; });
+  child.on('exit', (code, signal) => {
+    cleanup();
+    if (signal) process.kill(process.pid, signal);
+    else process.exitCode = code ?? 1;
+  });
+}
+main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/npm-cli/update.cjs

@@ -0,0 +1,161 @@
+'use strict';
+
+// Copied into each npm CLI at pack time. No repo paths or runtime dependencies.
+const runNpm = require('./npm-process.cjs');
+const { readFile, realpath, lstat, mkdir, mkdtemp, writeFile, rename, rm } = require('node:fs/promises');
+const { homedir } = require('node:os');
+const { join, resolve, isAbsolute } = require('node:path');
+const registry = 'https://registry.npmjs.org';
+const cacheLifetime = 60 * 60 * 1000;
+
+function parseVersion(version) {
+  const match = typeof version === 'string' && version.length <= 256 && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(version);
+  if (!match || match.slice(1, 4).some(n => !Number.isSafeInteger(Number(n))) || (match[4] || '').split('.').some(n => /^0\d+$/.test(n))) {
+    throw new Error('Invalid semantic version');
+  }
+  return { core: match.slice(1, 4).map(Number), pre: match[4] ? match[4].split('.') : [] };
+}
+
+function compareVersions(left, right) {
+  const a = parseVersion(left), b = parseVersion(right);
+  for (let i = 0; i < 3; i++) if (a.core[i] !== b.core[i]) return a.core[i] > b.core[i] ? 1 : -1;
+  if (!a.pre.length && b.pre.length) return 1;
+  if (a.pre.length && !b.pre.length) return -1;
+  for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+    if (a.pre[i] === b.pre[i]) continue;
+    if (a.pre[i] === undefined) return -1;
+    if (b.pre[i] === undefined) return 1;
+    const an = /^\d+$/.test(a.pre[i]), bn = /^\d+$/.test(b.pre[i]);
+    if (an !== bn) return an ? -1 : 1;
+    return (an ? BigInt(a.pre[i]) > BigInt(b.pre[i]) : a.pre[i] > b.pre[i]) ? 1 : -1;
+  }
+  return 0;
+}
+
+function releaseChannel(version) {
+  const { pre } = parseVersion(version);
+  return pre[0] === 'dev' ? 'dev' : pre.length ? 'next' : 'latest';
+}
+
+function identity(metadata) {
+  if (!/^@zergai\/[a-z0-9][a-z0-9-]*$/.test(metadata.name) && !['zerg-ztc', 'zerg-cyberdeck'].includes(metadata.name)) {
+    throw new Error('Unsupported CLI package identity');
+  }
+  parseVersion(metadata.version);
+}
+
+async function checkUpdate(metadata, { fetch = globalThis.fetch, channel = releaseChannel(metadata.version), timeoutMs = 5000 } = {}) {
+  identity(metadata);
+  if (!['dev', 'next', 'latest'].includes(channel)) throw new Error('Invalid update channel');
+  const response = await fetch(`${registry}/${encodeURIComponent(metadata.name)}/${channel}`, {
+    headers: { Accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!response.ok) throw new Error(`npm registry check failed (${response.status})`);
+  const reader = response.body.getReader();
+  const chunks = []; let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > 1024 * 1024) throw new Error('npm registry response too large');
+      chunks.push(Buffer.from(value));
+    }
+  } finally { await reader.cancel(); }
+  const data = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  if (data.name !== metadata.name) throw new Error('npm registry package identity mismatch');
+  if (releaseChannel(data.version) !== channel) throw new Error('npm registry version does not match the requested channel');
+  return { name: metadata.name, current: metadata.version, latest: data.version, channel, hasUpdate: compareVersions(data.version, metadata.version) > 0 };
+}
+
+function updateOptions(args) {
+  const options = { check: false };
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--check' && !options.check) options.check = true;
+    else if (arg === '--channel' && !options.channel && ['dev', 'next', 'latest'].includes(args[i + 1])) options.channel = args[++i];
+    else if (['--help', '-h'].includes(arg) && args.length === 2) options.help = true;
+    else throw new Error('Usage: update [--check] [--channel dev|next|latest]');
+  }
+  return options;
+}
+
+async function install(root, metadata, info, npm, env) {
+  const { stdout } = await npm(['prefix', '--global'], { env });
+  const prefix = stdout.trim();
+  if (!isAbsolute(prefix)) throw new Error('Cannot identify the global npm installation');
+  const expected = join(prefix, 'lib/node_modules', metadata.name);
+  // Compare real paths AND reject npm link. Never turn npx/local/checkouts into a
+  // global install or update a different Node-version manager's global prefix.
+  const matches = await (async () => !(await lstat(expected)).isSymbolicLink() && await realpath(root) === await realpath(expected))().catch(() => false);
+  if (!matches) {
+    throw new Error('Not this global npm installation. Update using the package manager/prefix that installed this CLI.');
+  }
+  await npm(['install', '--global', '--prefix', prefix, `--registry=${registry}`, `--@zergai:registry=${registry}`, '--no-audit', '--no-fund', `${metadata.name}@${info.latest}`], { cwd: prefix, env });
+  const installed = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  if (installed.name !== metadata.name || installed.version !== info.latest) throw new Error('npm did not install the requested package version');
+}
+
+async function startupCheck(metadata, env, fetch) {
+  const channel = releaseChannel(metadata.version);
+  const directory = join(env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'zergai-cli-updates');
+  const path = join(directory, `${encodeURIComponent(metadata.name)}-${channel}.json`);
+  try {
+    const cached = JSON.parse(await readFile(path, 'utf8'));
+    const age = Date.now() - cached.checkedAt;
+    if (Number.isFinite(age) && age >= 0 && age < cacheLifetime && cached.current === metadata.version) {
+      if (cached.latest === null) return null;
+      if (releaseChannel(cached.latest) === channel) return { latest: cached.latest, hasUpdate: compareVersions(cached.latest, metadata.version) > 0 };
+    }
+  } catch { /* Missing, stale, or malformed cache: do a bounded public check. */ }
+  let info = null;
+  try { info = await checkUpdate(metadata, { fetch, timeoutMs: 800 }); }
+  catch { /* A registry outage must not prevent use of a CLI. */ }
+  let staging;
+  try {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    staging = await mkdtemp(join(directory, '.check-'));
+    const source = join(staging, 'record');
+    await writeFile(source, JSON.stringify({ current: metadata.version, latest: info?.latest ?? null, checkedAt: Date.now() }), { flag: 'wx', mode: 0o600 });
+    await rename(source, path);
+  } catch { /* Read-only home/cache is supported. */ }
+  finally { if (staging) await rm(staging, { recursive: true, force: true }).catch(() => {}); }
+  return info;
+}
+
+async function handleUpdate({ root, args, env = process.env, stdout = process.stdout, stderr = process.stderr, fetch = globalThis.fetch, npm = runNpm }) {
+  const explicit = ['update', '--update'].includes(args[0]);
+  if (!explicit && (env.CI || env.ZERGAI_NO_UPDATE_CHECK === '1' || !stderr.isTTY || args.some(arg => ['help', '--help', '-h', 'version', '--version', '-V'].includes(arg)))) return null;
+  let options;
+  try { options = explicit ? updateOptions(args) : {}; }
+  catch (error) { stderr.write(`${error.message}\n`); return 2; }
+  if (options.help) {
+    stdout.write('Check npm and update this globally installed CLI\nUsage: update | --update [--check] [--channel dev|next|latest]\n--check prints JSON without installing. Channels are preserved by default.\nStartup only notifies; set ZERGAI_NO_UPDATE_CHECK=1 to disable checks.\n');
+    return 0;
+  }
+  try {
+    const metadata = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    identity(metadata);
+    if (!explicit) {
+      const info = await startupCheck(metadata, env, fetch);
+      if (info?.hasUpdate) stderr.write(`Update available for ${metadata.name}: ${metadata.version} → ${info.latest}. Run ${Object.keys(metadata.bin || {})[0] || metadata.name} update.\n`);
+      return null;
+    }
+    // Explicit checks/install always consult the registry; cache is advisory only.
+    const info = await checkUpdate(metadata, { fetch, ...options });
+    if (options.check) stdout.write(`${JSON.stringify(info)}\n`);
+    else if (!info.hasUpdate) stderr.write(`No newer ${info.channel} release of ${metadata.name} (installed ${metadata.version}).\n`);
+    else {
+      stderr.write(`Updating ${metadata.name}: ${metadata.version} → ${info.latest} (${info.channel})…\n`);
+      await install(resolve(root), metadata, info, npm, env);
+      stderr.write(`Updated ${metadata.name} to ${info.latest}. The next launch uses the new version.\n`);
+    }
+    return 0;
+  } catch (error) {
+    if (!explicit) return null;
+    stderr.write(`Update failed: ${error.message}\n`);
+    return 1;
+  }
+}
+
+module.exports = { compareVersions, releaseChannel, checkUpdate, handleUpdate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zergai/ztc",
-  "version": "0.2.2-dev.35681806994",
+  "version": "0.2.4-dev.35964790590",
   "description": "Zerg Terminal Client - CLI agent for continual AI systems",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -38,9 +38,12 @@
       "falkordblite"
     ]
   },
+  "zergCli": {
+    "entry": "dist/cli_main.js"
+  },
   "bin": {
-    "ztc": "dist/cli_main.js",
-    "zerg": "dist/cli_main.js"
+    "ztc": "npm-cli/run.cjs",
+    "zerg": "npm-cli/run.cjs"
   },
   "exports": {
     ".": {
@@ -129,7 +132,7 @@
     "package:prepare": "./scripts/prepare-package.sh",
     "pack:dry": "npm pack --dry-run --cache ${NPM_CONFIG_CACHE:-/tmp/ztc-npm-cache}",
     "pack:tarball": "npm pack --cache ${NPM_CONFIG_CACHE:-/tmp/ztc-npm-cache}",
-    "prepack": "npm run package:prepare",
+    "prepack": "npm run package:prepare && node ../scripts/npm/prepare-cli.mjs",
     "predev": "npm run clean",
     "dev": "npm run build:rust && tsx src/cli_main.ts",
     "dev:ink": "tsx src/cli.tsx",
@@ -161,6 +164,7 @@
     "release:preflight-governance": "node scripts/preflight-release-governance.mjs"
   },
   "files": [
+    "npm-cli/*.cjs",
     "LICENSE.md",
     "COMMERCIAL-LICENSING.md",
     "NOTICE",
@@ -234,7 +238,7 @@
   "zergRelease": {
     "branch": "development",
     "channel": "dev",
-    "sourceCommit": "151af97a4d4b5b99fc85d5d88ec93da820b1e5a3",
+    "sourceCommit": "ce17b0452956cbb4efedd020d0e153e5e5ab2302",
     "sourceVersion": "0.2.0-canary.1"
   },
   "publishConfig": {