okstra 0.146.1 → 0.148.0

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.
@@ -80,7 +85,8 @@ Effect (copy mode):
   ${"$HOME"}/.okstra/lib/python   <- runtime/python
   ${"$HOME"}/.okstra/lib/validators <- runtime/validators  (stage/report structure validators)
   ${"$HOME"}/.okstra/bin           <- runtime/bin
-  ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.md)
+  ${"$HOME"}/.okstra/templates     <- runtime/templates  (v1 assets + v2 AI/HTML template trees)
+  ${"$HOME"}/.okstra/schemas       <- runtime/schemas  (final-report schema v1 + v2)
   ${"$HOME"}/.okstra/prompts       <- runtime/prompts  (lead contracts + coding-preflight pack)
   ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name> <- skills when ${"$HOME"}/.claude exists
@@ -119,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;
@@ -139,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 };
 }
@@ -147,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;
 }
@@ -495,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 [];
@@ -550,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 };
 }
 
@@ -775,8 +799,9 @@ export async function runInstall(args) {
     paths.bin,
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o755 },
   );
-  // templates/ tree — report.css / report.js / *.template.md are consumed at
-  // runtime by okstra-render-report-views.py and final-report assembly. They
+  // templates/ tree — the v1 report.css/report.js compatibility assets, the
+  // v2 AI handoff template, and the task-specific html/** tree are consumed by
+  // okstra-render-report-views.py and final-report assembly. They
   // are NOT covered by installNamedTemplate (which only handles the renamed
   // settings.local.json sidecar), so without this step copy-mode installs
   // miss every asset other than that single file. See
@@ -786,13 +811,10 @@ export async function runInstall(args) {
     join(paths.home, "templates"),
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
   );
-  // schemas/ tree — final-report-v1.0.schema.json is loaded at runtime by
-  // okstra_ctl.final_report_schema.load_schema() (parent-walk from the
-  // installed okstra_ctl package finds ~/.okstra/schemas/). It is needed by
-  // (a) prepare_task_bundle to write the per-task-type schema excerpt into
-  // each run's instruction-set, and (b) validate-run's data.json schema
-  // check. Without this step copy-mode installs leave load_schema() unable
-  // to locate the schema. Link mode resolves it through the repo symlink.
+  // schemas/ tree — version-selected final-report v1/v2 schemas are loaded by
+  // okstra_ctl.final_report_schema. They support bundle excerpts, legacy
+  // re-renders, new task HTML, and validate-run. Link mode resolves the same
+  // files through the repo symlink.
   const schemasResult = await copyTreeIfChanged(
     join(runtimeRoot, "schemas"),
     join(paths.home, "schemas"),
@@ -840,7 +862,7 @@ export async function runInstall(args) {
   }
   if (templatesResult.missingSource) {
     process.stderr.write(
-      "warning: runtime/templates is empty. report.css / report.js will be missing — re-run the build step.\n",
+      "warning: runtime/templates is empty. final-report Markdown and HTML templates will be missing — re-run the build step.\n",
     );
   }
   if (schemasResult.missingSource) {
@@ -994,8 +1016,14 @@ export async function runEnsureInstalled(args) {
   }
   if (!(await dirExists(paths.pythonpath))) reasons.push(`missing ${paths.pythonpath}`);
   if (!(await dirExists(paths.agents))) reasons.push(`missing agents dir ${paths.agents}`);
-  if (!(await fileExists(join(paths.home, "schemas", "final-report-v1.0.schema.json")))) {
-    reasons.push(`missing ${join(paths.home, "schemas", "final-report-v1.0.schema.json")}`);
+  for (const relative of [
+    ["schemas", "final-report-v1.0.schema.json"],
+    ["schemas", "final-report-v2.0.schema.json"],
+    ["templates", "reports", "final-report-v2.template.md"],
+    ["templates", "reports", "html", "base.template.html"],
+  ]) {
+    const installedPath = join(paths.home, ...relative);
+    if (!(await fileExists(installedPath))) reasons.push(`missing ${installedPath}`);
   }
   for (const reason of await promptResourceDriftReasons(paths)) {
     reasons.push(reason);

package/src/commands/report/finalize.mjs

@@ -10,9 +10,8 @@ Usage:
 Runs the four Phase 7 steps in their contractual order against one final-report:
 
   1. token-usage       substitute real token/cost numbers into the data.json
-  2. render-views      write the self-contained *.html sibling (skipped when the
-                       report has no C-* clarification rows and is not a plan
-                       approval target)
+  2. render-views      write the schema-v2 task-specific *.html sibling; v1
+                       keeps the legacy conditional interactive view
   3. spawn-followups   turn section 4 rows into task stubs
   4. validate-run      validate the finished run artifacts
 

package/src/commands/report/render-final-report.mjs

@@ -1,6 +1,6 @@
 import { runInstalledScript } from "../../lib/python-helper.mjs";
 
-const USAGE = `okstra render-final-report — render the markdown sibling of a final-report data.json
+const USAGE = `okstra render-final-report — render the AI handoff Markdown sibling of final-report data.json
 
 Wraps the python helper (\`okstra-render-final-report.py\`) installed under
 \`~/.okstra/bin/\` so skills call \`okstra render-final-report\` instead of
@@ -10,7 +10,9 @@ permission matching and prompts on every call).
 Usage:
   okstra render-final-report <path-to-final-report.data.json>
 
-The argument is forwarded verbatim to the python helper.
+The argument is forwarded verbatim to the Python helper. schemaVersion 1.0
+keeps the legacy Markdown template; schemaVersion 2.0 selects the AI handoff
+template. Human HTML is rendered separately from the same data.json.
 `;
 
 export async function run(args) {

package/src/commands/report/render-views.mjs

@@ -3,20 +3,20 @@ import { runInstalledScript } from "../../lib/python-helper.mjs";
 const USAGE = `okstra render-views — render the self-contained HTML view of a final-report
 
 A thin spawn shim over \`scripts/okstra-render-report-views.py\` (installed
-at \`$HOME/.okstra/bin/okstra-render-report-views.py\`). Reads the final-
-report MD and writes a single sibling:
+at \`$HOME/.okstra/bin/okstra-render-report-views.py\`). Resolves the final-
+report data and Markdown pair, then writes a single sibling:
 
-  <stem>.html       — single-file self-contained human view with form
-                       controls on §5 clarification rows (skipped when the
-                       report has no §5 C-* clarification rows)
+  <stem>.html       — single-file self-contained human view; schema v2 is
+                       always generated, while v1/quick remains conditional
 
 Usage:
-  okstra render-views <path-to-final-report.md>
+  okstra render-views <path-to-final-report.data.json|path-to-final-report.md>
       [--task-key <key>] [--task-type <type>] [--seq <NNN>]
       [--source-report <project-relative-path>]
 
-When the optional flags are omitted the script infers from the report
-path and its '- Task Type:' / '- Task Key:' lines.
+Schema v2 data is rendered directly into its task-specific HTML view and is
+always generated. Schema v1 and quick reports keep the legacy conditional
+Markdown view. Optional flags override inferred report metadata.
 `;
 
 export async function run(args) {

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;
+}