okstra 0.147.0 → 0.148.0

package/src/commands/execute/run.mjs

@@ -7,10 +7,10 @@ const USAGE = `okstra run — host-aware okstra execution front door
 
 Usage:
   okstra run --project-root <dir> --project-id <id> --task-group <tg> \\
-    --task-id <tid> --task-type <type> [--lead-runtime auto|claude-code|codex|external]
+    --task-id <tid> --task-type <type> [--lead-runtime auto|claude-code|codex|antigravity|external]
 
-Claude Code native execution remains the /okstra-run skill front door. Bare
-'okstra run' orchestrates Codex and external/tmux CLI execution.
+Host-native Claude Code, Codex, and Antigravity execution use the okstra-run
+skill front door. Bare 'okstra run' orchestrates only external/tmux all-CLI execution.
 `;
 
 function flagValue(args, flag) {
@@ -48,55 +48,22 @@ function projectRootFromArgs(args) {
   return flagValue(args, "--project-root");
 }
 
-function withoutDispatchOnlyFlags(args) {
-  const out = [];
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (arg === "--enable-codex-report-writer") continue;
-    if (arg === "--report-writer-codex-model") {
-      i += 1;
-      continue;
-    }
-    if (arg.startsWith("--report-writer-codex-model=")) continue;
-    out.push(arg);
-  }
-  return out;
-}
-
 function renderArgs(args, resolution) {
   return [
     "--lead-runtime", resolution.resolvedRuntime,
     "--lead-runtime-request", resolution.requestedRuntime,
     "--runtime-resolution-json", JSON.stringify(resolution),
-    ...withoutDispatchOnlyFlags(withoutLeadRuntimeFlags(args)),
+    ...withoutLeadRuntimeFlags(args),
   ];
 }
 
-function codexDispatchArgs(args, projectRoot, runManifestPath) {
-  const out = ["--project-root", projectRoot, "--run-manifest", runManifestPath];
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (arg === "--enable-codex-report-writer") {
-      out.push(arg);
-      continue;
-    }
-    if (arg === "--report-writer-codex-model") {
-      out.push(arg, args[i + 1] ?? "");
-      i += 1;
-      continue;
-    }
-    if (arg.startsWith("--report-writer-codex-model=")) out.push(arg);
-  }
-  return out;
-}
-
 export function buildRunPlan({ args, paths, resolution, runManifestPath = "" }) {
   void paths;
   const projectRoot = projectRootFromArgs(args);
   if (resolution.resolvedRuntime === "claude-code") {
     return {
       ok: false,
-      reason: "Bare okstra run cannot invoke Claude Code TeamCreate / Agent(...). Use /okstra-run in Claude Code or pass --lead-runtime external|codex.",
+      reason: "Bare okstra run cannot invoke host-native Claude workers. Use the okstra-run skill in Claude Code or pass --lead-runtime external.",
       commands: [],
     };
   }
@@ -115,12 +82,17 @@ export function buildRunPlan({ args, paths, resolution, runManifestPath = "" })
 
   if (resolution.resolvedRuntime === "codex") {
     return {
-      ok: true,
-      reason: resolution.reason,
-      commands: [
-        { name: "codex-run", args: renderArgs(args, resolution), capture: true },
-        { name: "codex-dispatch", args: codexDispatchArgs(args, projectRoot, runManifestPath), capture: false },
-      ],
+      ok: false,
+      reason: "Bare okstra run cannot invoke host-native Codex workers. Use the okstra-run skill in Codex or pass --lead-runtime external for an all-CLI run.",
+      commands: [],
+    };
+  }
+
+  if (resolution.resolvedRuntime === "antigravity") {
+    return {
+      ok: false,
+      reason: "Bare okstra run cannot invoke host-native Antigravity workers. Use the okstra-run skill in Antigravity or pass --lead-runtime external for an all-CLI run.",
+      commands: [],
     };
   }
 
@@ -147,11 +119,6 @@ async function runTeam(args) {
   return await runTeamCommand(args);
 }
 
-async function runCodexDispatch(args) {
-  const { run: runCodexDispatchCommand } = await import("./codex-dispatch.mjs");
-  return await runCodexDispatchCommand(args);
-}
-
 export async function run(args) {
   if (args.includes("--help") || args.includes("-h")) {
     process.stdout.write(USAGE);
@@ -192,9 +159,7 @@ export async function run(args) {
 
   const plan = buildRunPlan({ args, paths, resolution, runManifestPath });
   for (const command of plan.commands.slice(1)) {
-    const code = command.name.startsWith("team ")
-      ? await runTeam(command.args)
-      : await runCodexDispatch(command.args);
+    const code = await runTeam(command.args);
     if (code !== 0) return code;
   }
   return 0;

package/src/commands/execute/wizard.mjs

@@ -20,7 +20,7 @@ Subcommands:
 
 Usage:
   okstra wizard new-state-file
-  okstra wizard init --state-file <path> --project-root <p> --project-id <id>
+  okstra wizard init --state-file <path> --project-root <p> --project-id <id> --host-runtime <runtime>
   okstra wizard step --state-file <path> [--answer <value>]
   okstra wizard render-args --state-file <path>
   okstra wizard confirmation --state-file <path>
@@ -106,6 +106,9 @@ export async function run(args) {
     pyArgs.push("--workspace-root", paths.workspace);
     pyArgs.push("--project-root", flags["project-root"]);
     pyArgs.push("--project-id", flags["project-id"]);
+    if (flags["host-runtime"]) {
+      pyArgs.push("--host-runtime", flags["host-runtime"]);
+    }
   } else if (sub === "step" && flags.answer !== undefined) {
     pyArgs.push("--answer", flags.answer);
   }

package/src/commands/lifecycle/doctor.mjs

@@ -14,7 +14,7 @@ const USAGE = `okstra doctor — diagnose the installed runtime
 
 Usage:
   okstra doctor               Run all checks and print a summary
-  okstra doctor --runtime <claude-code|codex|external|all>
+  okstra doctor --runtime <claude-code|codex|antigravity|external|all>
   okstra doctor --phase <phase>
   okstra doctor --json        Machine-readable result
 Checks:
@@ -48,7 +48,7 @@ export function parseDoctorArgs(args) {
     } else if (arg === "--runtime" || arg.startsWith("--runtime=")) {
       const value = arg.startsWith("--runtime=") ? arg.slice("--runtime=".length) : args[i + 1];
       if (!value || value.startsWith("--")) {
-        throw new Error("--runtime requires one of: claude-code, codex, external, all");
+        throw new Error("--runtime requires one of: claude-code, codex, antigravity, external, all");
       }
       result.runtime = validateInstallRuntime(value);
       if (arg === "--runtime") i++;
@@ -226,6 +226,9 @@ export async function run(args) {
     await check("bin: okstra.sh", () => checkBashEntry(paths.bin, "okstra.sh")),
     await check("bin: okstra-codex-exec.sh", () => checkBashEntry(paths.bin, "okstra-codex-exec.sh")),
     await check("bin: okstra-antigravity-exec.sh", () => checkBashEntry(paths.bin, "okstra-antigravity-exec.sh")),
+    await check("bin: okstra-grok-exec.sh", () => checkBashEntry(paths.bin, "okstra-grok-exec.sh")),
+    await check("bin: okstra-kimi-exec.sh", () => checkBashEntry(paths.bin, "okstra-kimi-exec.sh")),
+    await check("bin: okstra-provider-exec.py", () => checkBashEntry(paths.bin, "okstra-provider-exec.py")),
     await check("bin: okstra-central.sh", () => checkBashEntry(paths.bin, "okstra-central.sh")),
     ...(await Promise.all(
       requiredSkillNamesForRuntime(resolvedRuntime).map((name) =>
@@ -275,7 +278,7 @@ export async function run(args) {
 
   if (!runtimeResolution.ok) {
     process.stdout.write(
-      `  [WARN] runtime host: ${runtimeResolution.reason} skill checks skipped — pass --runtime <claude-code|codex|external> to include them.\n`,
+      `  [WARN] runtime host: ${runtimeResolution.reason} skill checks skipped — pass --runtime <claude-code|codex|antigravity|external> to include them.\n`,
     );
   }
   if (dockerWarning) {

package/src/commands/lifecycle/install.mjs

@@ -8,6 +8,7 @@ import { fileExists } from "../../lib/proc.mjs";
 import { buildRuntimeManifest, RUNTIMES_MANIFEST_REL } from "../../lib/runtime-manifest.mjs";
 import { normalizeRuntimeRequest, resolveRuntime } from "../../lib/runtime-resolver.mjs";
 import { OBSOLETE_SKILL_NAMES, USER_SKILL_NAMES } from "../../lib/skill-catalog.mjs";
+import { renderWorkerAgentDefinitions } from "../../lib/worker-agent-render.mjs";
 
 const SKILLS_MANIFEST_REL = "installed-skills.json";
 const AGENTS_MANIFEST_REL = "installed-agents.json";
@@ -29,6 +30,9 @@ const BIN_ENTRYPOINTS = [
   "okstra-codex-exec.sh",
   "okstra-claude-exec.sh",
   "okstra-antigravity-exec.sh",
+  "okstra-grok-exec.sh",
+  "okstra-kimi-exec.sh",
+  "okstra-provider-exec.py",
   "okstra-trace-cleanup.sh",
   "okstra-subagent-reclaim.sh",
   "okstra-team-reconcile.sh",
@@ -47,6 +51,7 @@ const REQUIRED_PROMPT_RESOURCE_FILES = Object.freeze([
   ["prompts", "lead", "okstra-lead-contract.md"],
   ["prompts", "lead", "adapters", "claude-code.md"],
   ["prompts", "lead", "adapters", "codex.md"],
+  ["prompts", "lead", "adapters", "antigravity.md"],
   ["prompts", "lead", "adapters", "external.md"],
   ["prompts", "lead", "context-loader.md"],
   ["prompts", "lead", "team-contract.md"],
@@ -69,7 +74,7 @@ const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra
 
 Usage:
   okstra install              Install/update runtime (copy mode)
-  okstra install --runtime <claude-code|codex|external|all>
+  okstra install --runtime <claude-code|codex|antigravity|external|all>
   okstra install --link <p>   Dev only: symlink ~/.okstra/{lib/python,bin}
                               to the source repo at <p>. agents/ resolves
                               to <p>/agents. Not advertised to end users.
@@ -120,13 +125,15 @@ const ENSURE_USAGE = `okstra ensure-installed — idempotent install check
 
 Usage:
   okstra ensure-installed     Verify install; reinstall if version/files drift
-  okstra ensure-installed --runtime <claude-code|codex|external|all>
+  okstra ensure-installed --runtime <claude-code|codex|antigravity|external|all>
   okstra ensure-installed -q  Same, but suppress success output
 
 Skills call this on every run. Returns 0 quickly when the install is fresh.
 `;
 
-const INSTALL_RUNTIMES = new Set(["auto", "claude-code", "codex", "external", "all"]);
+const INSTALL_RUNTIMES = new Set([
+  "auto", "claude-code", "codex", "antigravity", "external", "all",
+]);
 
 export function runtimeIncludesClaudeAssets(runtime, resolution = null) {
   if (runtime === "claude-code" || runtime === "all") return true;
@@ -140,7 +147,7 @@ function readRuntimeFlag(args, index) {
   }
   const next = args[index + 1];
   if (!next || next.startsWith("--")) {
-    throw new Error("--runtime requires one of: claude-code, codex, external, all");
+    throw new Error("--runtime requires one of: claude-code, codex, antigravity, external, all");
   }
   return { value: next, nextIndex: index + 1 };
 }
@@ -148,7 +155,7 @@ function readRuntimeFlag(args, index) {
 export function validateInstallRuntime(value) {
   const runtime = normalizeRuntimeRequest(value);
   if (!INSTALL_RUNTIMES.has(runtime)) {
-    throw new Error(`unknown runtime '${runtime}' (expected: auto, claude-code, codex, external, all)`);
+    throw new Error(`unknown runtime '${runtime}' (expected: auto, claude-code, codex, antigravity, external, all)`);
   }
   return runtime;
 }
@@ -496,7 +503,9 @@ async function listWorkerFiles(workersRoot) {
   try {
     const entries = await fs.readdir(workersRoot, { withFileTypes: true });
     return entries
-      .filter((e) => e.isFile() && e.name.endsWith(".md"))
+      .filter((e) => (
+        e.isFile() && e.name.endsWith(".md") && !e.name.startsWith("_")
+      ))
       .map((e) => e.name);
   } catch (err) {
     if (err.code === "ENOENT") return [];
@@ -551,18 +560,32 @@ async function installAgentsCopy(runtimeRoot, opts) {
 async function installAgentsLink(repoAbs, opts) {
   const { dryRun, quiet } = opts;
   const srcRoot = join(repoAbs, "agents", "workers");
-  const names = await listWorkerFiles(srcRoot);
+  const sourceNames = await listWorkerFiles(srcRoot);
+  const renderedDefinitions = await renderWorkerAgentDefinitions(srcRoot);
+  const names = [
+    ...sourceNames,
+    ...renderedDefinitions.map(({ name }) => name),
+  ].sort();
   if (names.length === 0) {
     if (!quiet) process.stdout.write("  agents: <repo>/agents/workers missing — skipped\n");
     return { installed: [] };
   }
   if (!dryRun) await fs.mkdir(CLAUDE_AGENTS_DIR, { recursive: true });
-  for (const name of names) {
+  for (const name of sourceNames) {
     const src = join(srcRoot, name);
     const dst = join(CLAUDE_AGENTS_DIR, name);
     const action = await ensureSymlink(src, dst, { dryRun });
     if (!quiet) process.stdout.write(`  agents/${name}: ${action}\n`);
   }
+  for (const { name, content } of renderedDefinitions) {
+    const dst = join(CLAUDE_AGENTS_DIR, name);
+    if (dryRun) {
+      process.stdout.write(`[dry-run] render ${name} -> ${dst}\n`);
+    } else {
+      await writeFileAtomic(dst, content, 0o644);
+    }
+    if (!quiet) process.stdout.write(`  agents/${name}: rendered\n`);
+  }
   return { installed: names };
 }
 

package/src/lib/runtime-manifest.mjs

@@ -1,6 +1,6 @@
 export const RUNTIMES_MANIFEST_REL = "installed-runtimes.json";
 export const RUNTIME_MANIFEST_SCHEMA_VERSION = 2;
-export const EXPLICIT_RUNTIME_VALUES = ["claude-code", "codex", "external"];
+export const EXPLICIT_RUNTIME_VALUES = ["claude-code", "codex", "antigravity", "external"];
 
 export function runtimeListForSelection(runtime, resolution = null) {
   if (runtime === "all") return [...EXPLICIT_RUNTIME_VALUES];

package/src/lib/runtime-resolver.mjs

@@ -1,5 +1,5 @@
 export const RUNTIME_AUTO = "auto";
-export const EXPLICIT_RUNTIMES = ["claude-code", "codex", "external"];
+export const EXPLICIT_RUNTIMES = ["claude-code", "codex", "antigravity", "external"];
 export const VALID_RUNTIME_REQUESTS = [RUNTIME_AUTO, ...EXPLICIT_RUNTIMES, "all"];
 
 const VALID_HOSTS = new Set(EXPLICIT_RUNTIMES);
@@ -118,6 +118,6 @@ export function resolveRuntime({
 
   return failResult(
     request,
-    `host unknown: set OKSTRA_RUNTIME_HOST=claude-code|codex|external or pass ${explicitRuntimeFlag(command)} explicitly.`,
+    `host unknown: set OKSTRA_RUNTIME_HOST=claude-code|codex|antigravity|external or pass ${explicitRuntimeFlag(command)} explicitly.`,
   );
 }

package/src/lib/worker-agent-render.mjs

@@ -0,0 +1,50 @@
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+
+const TEMPLATE_NAME = "_cli-wrapper-template.md";
+const PARAM_SUFFIX = ".params.json";
+
+async function pathExists(path) {
+  try {
+    await fs.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function renderWorkerAgentDefinitions(workersRoot) {
+  const templatePath = join(workersRoot, TEMPLATE_NAME);
+  if (!(await pathExists(templatePath))) return [];
+
+  const template = await fs.readFile(templatePath, "utf8");
+  const entries = await fs.readdir(workersRoot);
+  const paramFiles = entries.filter((name) => name.endsWith(PARAM_SUFFIX)).sort();
+
+  return Promise.all(paramFiles.map(async (paramFile) => {
+    const params = JSON.parse(
+      await fs.readFile(join(workersRoot, paramFile), "utf8"),
+    );
+    const content = template.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
+      if (!(key in params)) {
+        throw new Error(
+          `cli-wrapper template: unresolved token {{${key}}} in ${paramFile}`,
+        );
+      }
+      return params[key];
+    });
+    return {
+      name: paramFile.replace(/\.params\.json$/, ".md"),
+      content,
+    };
+  }));
+}
+
+export async function writeWorkerAgentDefinitions(workersRoot, destinationRoot) {
+  const definitions = await renderWorkerAgentDefinitions(workersRoot);
+  await fs.mkdir(destinationRoot, { recursive: true });
+  await Promise.all(definitions.map(({ name, content }) => (
+    fs.writeFile(join(destinationRoot, name), content, "utf8")
+  )));
+  return definitions;
+}