okstra 0.163.2 → 0.165.0

package/src/commands/lifecycle/install.mjs

@@ -6,7 +6,7 @@ import { getPackageRoot } from "../../lib/version.mjs";
 import { resolvePaths } from "../../lib/paths.mjs";
 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 { normalizeHostRequest, resolveRuntime } from "../../lib/host-registry-client.mjs";
 import { OBSOLETE_SKILL_NAMES, USER_SKILL_NAMES } from "../../lib/skill-catalog.mjs";
 import {
   AGENTS_MANIFEST_REL,
@@ -52,10 +52,6 @@ const BIN_ENTRYPOINTS = [
 // depend on. Intentionally an exact allowlist, not a directory wildcard.
 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"],
   ["prompts", "lead", "convergence.md"],
@@ -77,7 +73,7 @@ const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra
 
 Usage:
   okstra install              Install/update runtime (copy mode)
-  okstra install --runtime <claude-code|codex|antigravity|external|all>
+  okstra install --runtime <host-id|alias|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.
@@ -128,19 +124,14 @@ 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|antigravity|external|all>
+  okstra ensure-installed --runtime <host-id|alias|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", "antigravity", "external", "all",
-]);
-
-export function runtimeIncludesClaudeAssets(runtime, resolution = null) {
-  if (runtime === "claude-code" || runtime === "all") return true;
-  return runtime === "auto" && resolution?.resolvedRuntime === "claude-code";
+export function runtimeIncludesClaudeAssets(resolution) {
+  return resolution?.installTargets?.includes("claude") === true;
 }
 
 function readRuntimeFlag(args, index) {
@@ -150,21 +141,17 @@ function readRuntimeFlag(args, index) {
   }
   const next = args[index + 1];
   if (!next || next.startsWith("--")) {
-    throw new Error("--runtime requires one of: claude-code, codex, antigravity, external, all");
+    throw new Error("--runtime requires a host ID, alias, or all");
   }
   return { value: next, nextIndex: index + 1 };
 }
 
 export function validateInstallRuntime(value) {
-  const runtime = normalizeRuntimeRequest(value);
-  if (!INSTALL_RUNTIMES.has(runtime)) {
-    throw new Error(`unknown runtime '${runtime}' (expected: auto, claude-code, codex, antigravity, external, all)`);
-  }
-  return runtime;
+  return normalizeHostRequest(value);
 }
 
-function resolveInstallRuntime(runtime, command) {
-  const resolution = resolveRuntime({
+async function resolveInstallRuntime(runtime, command) {
+  const resolution = await resolveRuntime({
     requestedRuntime: runtime,
     command,
     env: process.env,
@@ -172,13 +159,8 @@ function resolveInstallRuntime(runtime, command) {
   });
   if (resolution.ok || runtime !== "auto") return resolution;
   return {
-    ok: false,
-    requestedRuntime: "auto",
-    resolvedRuntime: null,
-    host: "unknown",
+    ...resolution,
     confidence: "none",
-    reason: resolution.reason,
-    fallbackFrom: null,
     warnings: [resolution.reason],
   };
 }
@@ -792,7 +774,7 @@ export async function runInstall(args) {
   const pkgRoot = getPackageRoot();
   const runtimeRoot = join(pkgRoot, "runtime");
   const paths = await resolvePaths();
-  const runtimeResolution = resolveInstallRuntime(opts.runtime, "install");
+  const runtimeResolution = await resolveInstallRuntime(opts.runtime, "install");
   if (!runtimeResolution.ok && opts.runtime !== "auto") {
     process.stderr.write(`error: ${runtimeResolution.reason}\n`);
     return 2;
@@ -968,6 +950,44 @@ async function promptResourceDriftReasons(paths) {
   return reasons;
 }
 
+async function hostRelayDriftReasons(paths) {
+  const reasons = [];
+  const hostsRoot = join(paths.pythonpath, "okstra_ctl", "adapters", "hosts");
+  let entries;
+  try {
+    entries = await fs.readdir(hostsRoot, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return [`missing ${hostsRoot}`];
+    throw err;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const adapterRoot = join(hostsRoot, entry.name);
+    const manifestPath = join(adapterRoot, "manifest.json");
+    if (!(await fileExists(manifestPath))) continue;
+    let manifest;
+    try {
+      manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    } catch {
+      reasons.push(`invalid ${manifestPath}`);
+      continue;
+    }
+    const relayContract = manifest?.relayContract;
+    if (typeof relayContract !== "string" || !relayContract) {
+      reasons.push(`invalid relayContract in ${manifestPath}`);
+      continue;
+    }
+    const relayPath = resolveAbs(adapterRoot, relayContract);
+    const relayRelative = relative(adapterRoot, relayPath);
+    if (relayRelative.startsWith("..") || resolveAbs(adapterRoot) === relayPath) {
+      reasons.push(`invalid relayContract in ${manifestPath}`);
+    } else if (!(await fileExists(relayPath))) {
+      reasons.push(`missing ${relayPath}`);
+    }
+  }
+  return reasons;
+}
+
 async function agentDriftReasons(paths) {
   const reasons = [];
   const workersDir = join(paths.agents, "workers");
@@ -1051,7 +1071,7 @@ export async function runEnsureInstalled(args) {
     return 2;
   }
   const paths = await resolvePaths();
-  const runtimeResolution = resolveInstallRuntime(opts.runtime, "ensure-installed");
+  const runtimeResolution = await resolveInstallRuntime(opts.runtime, "ensure-installed");
   if (!runtimeResolution.ok && opts.runtime !== "auto") {
     process.stderr.write(`error: ${runtimeResolution.reason}\n`);
     return 2;
@@ -1093,6 +1113,9 @@ export async function runEnsureInstalled(args) {
   for (const reason of await promptResourceDriftReasons(paths)) {
     reasons.push(reason);
   }
+  for (const reason of await hostRelayDriftReasons(paths)) {
+    reasons.push(reason);
+  }
   const skillTargets = await detectSkillTargets();
   for (const reason of await skillTargetDriftReasons(skillTargets)) {
     reasons.push(reason);

package/src/commands/lifecycle/preflight.mjs

@@ -3,7 +3,7 @@ import { runEnsureInstalled } from "./install.mjs";
 import { missingHelperScripts } from "../../lib/helper-scripts.mjs";
 import { resolveInstalledScript } from "../../lib/python-helper.mjs";
 import { resolvePaths } from "../../lib/paths.mjs";
-import { checkRuntimeReadiness } from "../../lib/runtime-readiness.mjs";
+import { checkRuntimeReadiness } from "../../lib/host-registry-client.mjs";
 
 const USAGE = `okstra preflight — one-call skill preflight (ensure-installed + check-project)
 
@@ -17,7 +17,7 @@ verifies the target project has .okstra/project.json. Prints one JSON object:
   ok: false  {ok, stage, reason, ...}
              stage: install | helper_scripts_missing | resolve |
                     project_json_missing | project_json_invalid |
-                    python | parse
+                    runtime_readiness | python | parse
 
 Options:
   --runtime <name>   Runtime whose assets must be present (e.g. claude-code);
@@ -26,8 +26,8 @@ Options:
   --json             Default output format (kept for symmetry).
 
 Exit codes:
-  0   runtime fresh and project registered; inspect runtimeReadiness before dispatch
-  1   runtime install failed, or project setup missing/invalid
+  0   runtime fresh, project registered, and current host ready
+  1   runtime install failed, project setup missing/invalid, or host not ready
   2   PROJECT_ROOT could not be resolved from cwd (pass --cwd), or bad flags
 `;
 
@@ -110,6 +110,16 @@ export async function run(args) {
     runtime: opts.runtime,
     projectRoot: payload.projectRoot,
   });
+  if (["blocked", "unknown"].includes(runtimeReadiness.status)) {
+    emit({
+      ...payload,
+      ok: false,
+      stage: "runtime_readiness",
+      reason: `current host readiness is ${runtimeReadiness.status}`,
+      runtimeReadiness,
+    });
+    return 1;
+  }
   emit({ ...payload, runtimeReadiness });
   return code;
 }

package/src/lib/host-registry-client.mjs

@@ -0,0 +1,176 @@
+import { homedir } from "node:os";
+
+import { runPythonModule } from "./python-helper.mjs";
+
+export const RUNTIME_AUTO = "auto";
+
+const HOST_REQUEST_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const PLAIN_TEXT_INPUT = "plain_text_input";
+
+export class HostRegistryClientError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HostRegistryClientError";
+  }
+}
+
+async function callHosts(runPython, args) {
+  const result = await runPython({
+    module: "okstra_ctl.entrypoints.hosts",
+    args,
+    stdio: "capture",
+  });
+  if (result.code !== 0) {
+    const detail = String(result.stderr || "").trim() || `Python exited ${result.code}`;
+    throw new HostRegistryClientError(detail);
+  }
+  const stdout = String(result.stdout || "").trim();
+  if (!stdout) throw new HostRegistryClientError("host registry returned empty stdout");
+  try {
+    return JSON.parse(stdout);
+  } catch (error) {
+    throw new HostRegistryClientError(`host registry returned invalid JSON: ${error.message}`);
+  }
+}
+
+function resolutionContext(env = {}, capabilities = {}) {
+  return {
+    env: { OKSTRA_RUNTIME_HOST: String(env?.OKSTRA_RUNTIME_HOST ?? "") },
+    capabilities: {
+      claudeSkillHandoff: capabilities?.claudeSkillHandoff === true,
+      tmuxAvailable: capabilities?.tmuxAvailable === true,
+    },
+  };
+}
+
+export function createHostRegistryClient({ runPython = runPythonModule } = {}) {
+  return {
+    async catalog() {
+      return await callHosts(runPython, ["catalog", "--json"]);
+    },
+    async resolveHostRuntime({ requestedRuntime, command, env, capabilities }) {
+      return await callHosts(runPython, [
+        "resolve",
+        "--requested", requestedRuntime,
+        "--command", command,
+        "--context-json", JSON.stringify(resolutionContext(env, capabilities)),
+      ]);
+    },
+    async probeHost({
+      hostRuntime,
+      entryMode,
+      projectRoot,
+      homeDir,
+      availableFunctions = [],
+    }) {
+      const args = [
+        "probe",
+        "--host", hostRuntime,
+        "--entry-mode", entryMode,
+        "--project-root", projectRoot,
+        "--home-dir", homeDir,
+      ];
+      for (const availableFunction of availableFunctions) {
+        args.push("--available-function", availableFunction);
+      }
+      return await callHosts(runPython, args);
+    },
+  };
+}
+
+const hostRegistryClient = createHostRegistryClient();
+
+export function normalizeHostRequest(value) {
+  const runtime = String(value ?? "").trim() || RUNTIME_AUTO;
+  if (!HOST_REQUEST_PATTERN.test(runtime)) {
+    throw new Error(
+      `invalid runtime '${runtime}' (expected auto, all, or a lowercase host ID)`,
+    );
+  }
+  return runtime;
+}
+
+function failedResolution(requestedRuntime, error) {
+  return {
+    ok: false,
+    requestedRuntime,
+    resolvedRuntime: null,
+    launchMode: null,
+    installTargets: [],
+    host: "unknown",
+    confidence: "low",
+    reason: error.message,
+    fallbackFrom: null,
+    warnings: [],
+  };
+}
+
+function catalogResolution(catalog) {
+  const hosts = Array.isArray(catalog?.hosts) ? catalog.hosts : [];
+  const catalogHostIds = hosts.map((host) => host.id);
+  const installTargets = Array.from(new Set(
+    hosts.flatMap((host) => host.install_targets ?? host.installTargets ?? []),
+  )).sort();
+  return {
+    ok: true,
+    requestedRuntime: "all",
+    resolvedRuntime: "all",
+    launchMode: "catalog",
+    installTargets,
+    catalogHostIds,
+    host: "explicit",
+    confidence: "high",
+    reason: "All registered host runtimes requested.",
+    fallbackFrom: null,
+    warnings: [],
+  };
+}
+
+export async function loadHostCatalog() {
+  return await hostRegistryClient.catalog();
+}
+
+export async function resolveHostRuntime(options) {
+  return await hostRegistryClient.resolveHostRuntime(options);
+}
+
+export async function probeHost(options) {
+  return await hostRegistryClient.probeHost(options);
+}
+
+export async function resolveRuntime({
+  requestedRuntime = RUNTIME_AUTO,
+  command = "run",
+  env = {},
+  capabilities = {},
+} = {}) {
+  const request = normalizeHostRequest(requestedRuntime);
+  try {
+    if (request === "all") return catalogResolution(await loadHostCatalog());
+    return await resolveHostRuntime({
+      requestedRuntime: request,
+      command,
+      env,
+      capabilities,
+    });
+  } catch (error) {
+    if (!(error instanceof HostRegistryClientError)) throw error;
+    return failedResolution(request, error);
+  }
+}
+
+export async function checkRuntimeReadiness({
+  runtime,
+  projectRoot,
+  homeDir = homedir(),
+  hostRegistryClient = { probeHost },
+}) {
+  if (!runtime) return { runtime: "auto", status: "ready", checks: [] };
+  return await hostRegistryClient.probeHost({
+    hostRuntime: runtime,
+    entryMode: "current-session",
+    projectRoot,
+    homeDir,
+    availableFunctions: [PLAIN_TEXT_INPUT],
+  });
+}

package/src/lib/runtime-manifest.mjs

@@ -1,9 +1,7 @@
 export const RUNTIMES_MANIFEST_REL = "installed-runtimes.json";
 export const RUNTIME_MANIFEST_SCHEMA_VERSION = 2;
-export const EXPLICIT_RUNTIME_VALUES = ["claude-code", "codex", "antigravity", "external"];
-
 export function runtimeListForSelection(runtime, resolution = null) {
-  if (runtime === "all") return [...EXPLICIT_RUNTIME_VALUES];
+  if (runtime === "all") return [...(resolution?.catalogHostIds ?? [])];
   if (runtime === "auto") {
     const resolved = resolution?.resolvedRuntime;
     return resolved && resolved !== "all" ? [resolved] : [];
@@ -11,10 +9,8 @@ export function runtimeListForSelection(runtime, resolution = null) {
   return [runtime];
 }
 
-function includesClaudeRuntime(runtime, resolution = null) {
-  if (runtime === "all") return true;
-  if (runtime === "claude-code") return true;
-  return runtime === "auto" && resolution?.resolvedRuntime === "claude-code";
+function includesClaudeAssets(resolution) {
+  return resolution?.installTargets?.includes("claude") === true;
 }
 
 function defaultResolution(runtime) {
@@ -22,6 +18,8 @@ function defaultResolution(runtime) {
   return {
     requestedRuntime: runtime,
     resolvedRuntime: runtime,
+    launchMode: null,
+    installTargets: [],
     host: "explicit",
     confidence: "high",
     reason: `Explicit runtime '${runtime}' requested.`,
@@ -37,7 +35,7 @@ export function buildRuntimeManifest(
   installedAssets = null,
 ) {
   const runtimeResolution = resolution ?? defaultResolution(runtime);
-  const includesClaude = includesClaudeRuntime(runtime, runtimeResolution);
+  const includesClaude = includesClaudeAssets(runtimeResolution);
   const defaultAssets = {
     sharedRuntime: true,
     claudeSkills: includesClaude,

package/runtime/bin/okstra-wrapper-agy-stream.py

@@ -1,61 +0,0 @@
-#!/usr/bin/env python3
-"""Split `agy --output-format stream-json` output for okstra-antigravity-exec.sh.
-
-Everything agy emits is appended to the live log, so the log becomes an audit
-trail of what the worker actually did — which tools it called, on which paths,
-for how long. In the default `text` format agy prints only its closing summary,
-so an antigravity dispatch left ~2KB of self-report against codex's ~487KB of
-tool trace, and whether the worker ever opened the evidence it was asked to
-verify could not be checked from outside.
-
-stdout stays what the dispatcher's contract expects: the final response text
-only, so the subagent's captured output is unchanged by the format switch.
-"""
-from __future__ import annotations
-
-import json
-import sys
-
-
-def main() -> int:
-    if len(sys.argv) < 2:
-        print("usage: okstra-wrapper-agy-stream.py <log-path>", file=sys.stderr)
-        return 2
-    log_path = sys.argv[1]
-    final: str | None = None
-    # Lines agy emitted that are not stream-json events. Normally empty; kept so
-    # a non-JSON emitter (a stub, an older agy, a crash banner) still reaches
-    # stdout instead of being silently swallowed.
-    passthrough: list[str] = []
-    with open(log_path, "a", encoding="utf-8") as log:
-        for line in sys.stdin:
-            log.write(line)
-            log.flush()
-            stripped = line.strip()
-            if not stripped:
-                continue
-            try:
-                event = json.loads(stripped)
-            except json.JSONDecodeError:
-                passthrough.append(line)
-                continue
-            if isinstance(event, dict) and event.get("event") == "result":
-                result = event.get("result")
-                if isinstance(result, dict):
-                    final = result.get("response") or ""
-    if final is not None:
-        sys.stdout.write(final)
-    elif passthrough:
-        sys.stdout.writelines(passthrough)
-    else:
-        print(
-            "okstra-wrapper-agy-stream: no result event in agy output — "
-            f"see {log_path}",
-            file=sys.stderr,
-        )
-    sys.stdout.flush()
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())