okstra 0.160.0 → 0.162.0

package/src/commands/execute/run.mjs

@@ -1,3 +1,6 @@
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+
 import { runEnsureInstalled } from "../lifecycle/install.mjs";
 import { runPythonModule } from "../../lib/python-helper.mjs";
 import { resolvePaths } from "../../lib/paths.mjs";
@@ -6,13 +9,31 @@ import { resolveRuntime } from "../../lib/runtime-resolver.mjs";
 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|antigravity|external]
-
-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.
+  okstra run [claude|codex|antigravity|external] --project-root <dir> \\
+    --project-id <id> --task-group <tg> --task-id <tid> --task-type <type> \\
+    [--lead-runtime auto|claude-code|codex|antigravity|external] [--yes]
+
+The leading word selects the lead and is an alias for --lead-runtime, so
+'okstra run codex' starts a Codex lead. Naming a lead starts that CLI with the
+prepared prompt; 'external' instead orchestrates an all-CLI run through okstra
+team. Starting a lead whose CLI sandboxes itself asks for confirmation first,
+which --yes answers.
 `;
 
+// Leads okstra can start itself. `external` is not one: it names a harness
+// okstra does not own, so those runs are orchestrated rather than launched.
+const LAUNCHABLE_RUNTIMES = new Set(["claude-code", "codex", "antigravity"]);
+
+// The leading word users actually type. `claude` is the provider's name while
+// the runtime is `claude-code`; the rest coincide.
+const RUNTIME_ALIASES = new Map([
+  ["claude", "claude-code"],
+  ["claude-code", "claude-code"],
+  ["codex", "codex"],
+  ["antigravity", "antigravity"],
+  ["external", "external"],
+]);
+
 function flagValue(args, flag) {
   const equals = args.find((arg) => arg.startsWith(`${flag}=`));
   if (equals) return equals.slice(flag.length + 1);
@@ -20,14 +41,21 @@ function flagValue(args, flag) {
   return index >= 0 ? args[index + 1] : "";
 }
 
+export function positionalRuntime(args) {
+  const first = args[0];
+  if (!first || first.startsWith("-")) return "";
+  return RUNTIME_ALIASES.get(first) || "";
+}
+
 export function requestedRuntimeFromArgs(args) {
-  return flagValue(args, "--lead-runtime") || "auto";
+  return flagValue(args, "--lead-runtime") || positionalRuntime(args) || "auto";
 }
 
-export function withoutLeadRuntimeFlags(args) {
+export function withoutRuntimeSelection(args) {
+  const rest = positionalRuntime(args) ? args.slice(1) : args;
   const out = [];
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
     if (arg === "--lead-runtime") {
       i += 1;
       continue;
@@ -53,24 +81,17 @@ function renderArgs(args, resolution) {
     "--lead-runtime", resolution.resolvedRuntime,
     "--lead-runtime-request", resolution.requestedRuntime,
     "--runtime-resolution-json", JSON.stringify(resolution),
-    ...withoutLeadRuntimeFlags(args),
+    ...withoutRuntimeSelection(args),
   ];
 }
 
 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 host-native Claude workers. Use the okstra-run skill in Claude Code or pass --lead-runtime external.",
-      commands: [],
-    };
-  }
-
   if (resolution.resolvedRuntime === "external") {
     return {
       ok: true,
+      kind: "team",
       reason: resolution.reason,
       commands: [
         { name: "render-bundle", args: renderArgs(args, resolution), capture: true },
@@ -80,19 +101,14 @@ export function buildRunPlan({ args, paths, resolution, runManifestPath = "" })
     };
   }
 
-  if (resolution.resolvedRuntime === "codex") {
+  if (LAUNCHABLE_RUNTIMES.has(resolution.resolvedRuntime)) {
     return {
-      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: [],
+      ok: true,
+      kind: "launch-lead",
+      reason: resolution.reason,
+      // Not render-only: the lead is actually started, so prepare must commit
+      // the run and emit the launch metadata rather than preview it.
+      commands: [{ name: "prepare", args: renderArgs(args, resolution), capture: true }],
     };
   }
 
@@ -114,6 +130,73 @@ async function runRenderCommand(command, paths) {
   return result;
 }
 
+export function parseLaunchMetadata(stdout) {
+  const marker = "__OKSTRA_LAUNCH__ ";
+  const line = String(stdout || "")
+    .split("\n")
+    .reverse()
+    .find((item) => item.startsWith(marker));
+  return line ? JSON.parse(line.slice(marker.length)) : null;
+}
+
+export function withoutLaunchMetadata(stdout) {
+  return String(stdout || "")
+    .split("\n")
+    .filter((line) => !line.startsWith("__OKSTRA_LAUNCH__ "))
+    .join("\n");
+}
+
+async function confirmSandboxWaiver(launch, args) {
+  if (!launch.sandboxWaiverNote) return true;
+  process.stderr.write(`\n${launch.sandboxWaiverNote}\n`);
+  if (args.includes("--yes")) {
+    process.stderr.write("Proceeding without the sandbox (--yes).\n\n");
+    return true;
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await rl.question(
+      `Start ${launch.leadExecutable} without its sandbox? [y/N] `,
+    );
+    return answer.trim().toLowerCase() === "y";
+  } finally {
+    rl.close();
+  }
+}
+
+async function launchLead(command, paths, args) {
+  const prepared = await runPythonModule({
+    module: "okstra_ctl.run",
+    args: ["--workspace-root", paths.workspace, ...command.args],
+    stdio: "capture",
+  });
+  process.stdout.write(withoutLaunchMetadata(prepared.stdout));
+  if (prepared.stderr) process.stderr.write(prepared.stderr);
+  if (prepared.code !== 0) return prepared.code ?? 1;
+
+  const launch = parseLaunchMetadata(prepared.stdout);
+  if (!launch) {
+    process.stderr.write("error: prepare did not emit launch metadata\n");
+    return 1;
+  }
+  if (!(await confirmSandboxWaiver(launch, args))) {
+    process.stderr.write(
+      "okstra: cancelled. The task bundle is prepared; rerun to resume it.\n",
+    );
+    return 1;
+  }
+  const [executable, ...rest] = launch.launchArgv;
+  const started = spawnSync(executable, rest, {
+    cwd: launch.projectRoot,
+    stdio: "inherit",
+  });
+  if (started.error) {
+    process.stderr.write(`error: could not start ${executable}: ${started.error.message}\n`);
+    return 1;
+  }
+  return started.status ?? 1;
+}
+
 async function runTeam(args) {
   const { run: runTeamCommand } = await import("./team.mjs");
   return await runTeamCommand(args);
@@ -147,6 +230,10 @@ export async function run(args) {
   const ensureCode = await ensureRuntime(requestedRuntime);
   if (ensureCode !== 0) return ensureCode;
 
+  if (firstPlan.kind === "launch-lead") {
+    return await launchLead(firstPlan.commands[0], paths, args);
+  }
+
   const render = firstPlan.commands[0];
   const prepared = await runRenderCommand(render, paths);
   if (prepared.code !== 0) return prepared.code ?? 1;