opencode-agenthub 0.1.0 → 0.1.2

package/dist/composer/settings.js

@@ -1,11 +1,17 @@
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { normalizeModelSelection, pickModelSelection } from "./model-utils.js";
+import { spawn } from "node:child_process";
+import {
+  normalizeModelSelection,
+  pickModelSelection,
+  validateModelAgainstCatalog,
+  validateModelIdentifier
+} from "./model-utils.js";
 import { buildBuiltinVersionManifest } from "./builtin-assets.js";
 import { getDefaultProfilePlugins } from "./defaults.js";
 import { readPackageVersion } from "./package-version.js";
-import { resolveHomeConfigRoot } from "./platform.js";
+import { resolveHomeConfigRoot, spawnOptions } from "./platform.js";
 const hrPrimaryAgentName = "hr";
 const recommendedHrBootstrapModel = "openai/gpt-5.4-mini";
 const recommendedHrBootstrapVariant = "high";
@@ -253,6 +259,97 @@ const normalizeConfiguredModel = (value) => {
   return trimmed.length > 0 ? trimmed : void 0;
 };
 const fallbackInstalledModel = (installedModels, nativeModel) => installedModels[hrPrimaryAgentName]?.model || installedModels.auto?.model || Object.values(installedModels)[0]?.model || nativeModel;
+const readHrKnownModelIds = async (targetRoot) => {
+  const filePath = path.join(targetRoot, "inventory", "models", "valid-model-ids.txt");
+  try {
+    const raw = await readFile(filePath, "utf8");
+    const values = raw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    return values.length > 0 ? new Set(values) : void 0;
+  } catch {
+    return void 0;
+  }
+};
+const listAvailableOpencodeModels = async () => new Promise((resolve) => {
+  const child = spawn("opencode", ["models"], {
+    stdio: ["ignore", "pipe", "ignore"],
+    ...spawnOptions()
+  });
+  const timeout = setTimeout(() => {
+    child.kill();
+    resolve(void 0);
+  }, 15e3);
+  let stdout = "";
+  child.stdout?.on("data", (chunk) => {
+    stdout += chunk.toString();
+  });
+  child.on("error", () => {
+    clearTimeout(timeout);
+    resolve(void 0);
+  });
+  child.on("close", () => {
+    clearTimeout(timeout);
+    const models = stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    resolve(models.length > 0 ? [...new Set(models)].sort() : void 0);
+  });
+});
+const probeOpencodeModelAvailability = async (model, options = {}) => {
+  const models = await (options.listModels ?? listAvailableOpencodeModels)();
+  if (!models) {
+    return {
+      available: false,
+      reason: "probe_failed",
+      message: "Unable to verify model availability from opencode. Continue only if you know this model works in your environment."
+    };
+  }
+  return models.includes(model) ? { available: true } : {
+    available: false,
+    reason: "unavailable",
+    message: `Model '${model}' is not available in the current opencode environment.`
+  };
+};
+const agentModelValidationMessage = (agentName, model, status) => `Agent '${agentName}' model '${model}' is invalid: ${status.message}`;
+const validateHrAgentModelConfiguration = async (targetRoot, settings, options = {}) => {
+  const currentSettings = settings ?? await readAgentHubSettings(targetRoot);
+  if (!currentSettings?.agents) return { valid: true };
+  const knownModels = await readHrKnownModelIds(targetRoot);
+  const availabilityCache = /* @__PURE__ */ new Map();
+  for (const agentName of hrAgentNames) {
+    const model = currentSettings.agents[agentName]?.model;
+    if (typeof model !== "string" || model.trim().length === 0) continue;
+    const syntax = validateModelIdentifier(model);
+    if (!syntax.ok) {
+      return {
+        valid: false,
+        agentName,
+        model,
+        syntax,
+        message: agentModelValidationMessage(agentName, model, syntax)
+      };
+    }
+    const catalog = validateModelAgainstCatalog(model, knownModels);
+    if (!catalog.ok) {
+      return {
+        valid: false,
+        agentName,
+        model,
+        catalog,
+        message: agentModelValidationMessage(agentName, model, catalog)
+      };
+    }
+    const availability = availabilityCache.get(model) || await probeOpencodeModelAvailability(model, options);
+    availabilityCache.set(model, availability);
+    if (!availability.available && availability.reason !== "probe_failed") {
+      return {
+        valid: false,
+        agentName,
+        model,
+        availability,
+        message: agentModelValidationMessage(agentName, model, availability)
+      };
+    }
+  }
+  return { valid: true };
+};
 const resolveHrBootstrapAgentModels = async ({
   targetRoot,
   selection
@@ -383,11 +480,14 @@ export {
   hrAgentNames,
   hrPrimaryAgentName,
   hrSubagentNames,
+  listAvailableOpencodeModels,
   loadNativeOpenCodeConfig,
   loadNativeOpenCodePreferences,
   mergeAgentHubSettingsDefaults,
   nativeOpenCodeConfigPath,
+  probeOpencodeModelAvailability,
   readAgentHubSettings,
+  readHrKnownModelIds,
   readNativeAgentOverrides,
   readNativePluginEntries,
   readWorkflowInjectionConfig,
@@ -395,6 +495,7 @@ export {
   recommendedHrBootstrapVariant,
   resolveHrBootstrapAgentModels,
   settingsPathForRoot,
+  validateHrAgentModelConfiguration,
   workflowInjectionPathForRoot,
   writeAgentHubSettings
 };

package/dist/skills/agenthub-doctor/diagnose.js

@@ -1,6 +1,7 @@
 import { readdir, readFile, access } from "node:fs/promises";
 import path from "node:path";
 import { readAgentHubSettings } from "../../composer/settings.js";
+import { validateModelIdentifier } from "../../composer/model-utils.js";
 const readJson = async (filePath) => {
   const content = await readFile(filePath, "utf-8");
   return JSON.parse(content);
@@ -98,8 +99,28 @@ async function runDiagnostics(targetRoot) {
   if (omoIssue) {
     report.issues.push(omoIssue);
   }
+  for (const issue of diagnoseInvalidModelSyntax(settings)) {
+    report.issues.push(issue);
+  }
   return report;
 }
+const diagnoseInvalidModelSyntax = (settings) => {
+  if (!settings?.agents) return [];
+  const issues = [];
+  for (const [agentName, agent] of Object.entries(settings.agents)) {
+    if (typeof agent.model !== "string" || agent.model.trim().length === 0) continue;
+    const syntax = validateModelIdentifier(agent.model);
+    if (!syntax.ok) {
+      issues.push({
+        type: "model_invalid_syntax",
+        severity: "error",
+        message: `Agent '${agentName}' has an invalid model override: ${syntax.message}`,
+        details: { agentName, model: agent.model }
+      });
+    }
+  }
+  return issues;
+};
 async function diagnoseMissingGuards(settings) {
   if (!settings) return REQUIRED_GUARDS;
   const existingGuards = Object.keys(settings.guards || {});

package/dist/skills/agenthub-doctor/fix.js

@@ -132,7 +132,7 @@ async function createBundleForSoul(targetRoot, soulName, options = {}) {
       agent: {
         name: options.agentName ?? soulName,
         mode: options.mode ?? "primary",
-        model: options.model || "github-copilot/claude-sonnet-4.5",
+        model: options.model ?? "",
         description: "Auto-generated bundle for imported soul"
       }
     };

package/dist/skills/agenthub-doctor/interactive.js

@@ -3,9 +3,15 @@ import { readdir, readFile, access, writeFile } from "node:fs/promises";
 import path from "node:path";
 import {
   loadNativeOpenCodeConfig,
+  probeOpencodeModelAvailability,
+  readHrKnownModelIds,
   readAgentHubSettings,
   writeAgentHubSettings
 } from "../../composer/settings.js";
+import {
+  validateModelAgainstCatalog,
+  validateModelIdentifier
+} from "../../composer/model-utils.js";
 import {
   fixMissingGuards,
   createBundleForSoul,
@@ -149,9 +155,9 @@ async function createBundleFlow(rl, targetRoot) {
   const modeInput = await rl.question("Mode [primary/subagent, default: primary]: ");
   const mode = modeInput.trim() === "subagent" ? "subagent" : "primary";
   const modelInput = await rl.question(
-    "Model [default: github-copilot/claude-sonnet-4.5]: "
+    "Model [default: none]: "
   );
-  const model = modelInput.trim() || "github-copilot/claude-sonnet-4.5";
+  const model = modelInput.trim();
   const result = await createBundleForSoul(targetRoot, soulName.trim(), {
     agentName: finalAgentName,
     mode,
@@ -686,6 +692,19 @@ async function updateAgentModelOverride(targetRoot, agentName, model) {
     await writeAgentHubSettings(targetRoot, settings);
     return `Cleared model override for '${agentName}'.`;
   }
+  const syntax = validateModelIdentifier(trimmed);
+  if (!syntax.ok) {
+    return `${syntax.message} Use provider/model format or leave blank to clear the override.`;
+  }
+  const knownModels = await readHrKnownModelIds(targetRoot);
+  const catalog = validateModelAgainstCatalog(trimmed, knownModels);
+  if (!catalog.ok) {
+    return `${catalog.message} Sync HR sources or choose a listed model, then try again.`;
+  }
+  const availability = await probeOpencodeModelAvailability(trimmed);
+  if (!availability.available) {
+    return `${availability.message} Pick another model or clear the override.`;
+  }
   settings.agents[agentName] = {
     ...existing,
     model: trimmed

package/dist/skills/hr-assembly/SKILL.md

@@ -41,7 +41,10 @@ $HR_HOME/staging/<package-id>/
 - Prefer namespaced bundle/soul/profile names for adapted teams or rewrites so the package does not overwrite shared starter assets like `plan`, `build`, or `explore` unless the human explicitly requests replacement.
 - If a staged profile sets `defaultAgent`, it must use the staged bundle's `agent.name` value, not the bundle filename. This matters when bundle filenames are namespaced but `agent.name` is shorter.
 - Before final assembly, confirm whether the operator wants to keep default opencode agents such as `general`, `explore`, `plan`, and `build`. If not, the staged profile must set `"nativeAgentPolicy": "team-only"`. This suppresses host native agent merges and emits `disable: true` overrides for default opencode agents that are not supplied by the staged team itself.
+- If `nativeAgentPolicy` is `team-only` and the staged bundle set does not already provide `explore`, automatically include the built-in hidden `explore` subagent so the team retains investigation coverage without another user prompt.
+- Before final assembly, MUST verify the staged bundle set includes at least one `agent.mode: "primary"` agent that is not hidden. If all sourced candidates are subagent-style, either add/create a primary host agent or keep native agents visible. Never stage an all-subagent team as `team-only`.
 - Before final assembly, confirm whether the promoted profile should become the default personal profile for future bare `agenthub start` runs. Record that choice in `handoff.json` under `promotion_preferences.set_default_profile`.
+- If AI models are still unresolved when final assembly begins, stop and confirm the exact model choice here before writing staged agent defaults.
 - If the operator specifies a model variant such as `xhigh`, `high`, or `thinking`, store it canonically as `agent.model: "provider/model"` plus `agent.variant: "..."`. For backward compatibility, combined strings like `"provider/model xhigh"` may still be accepted on read, but staged output should prefer the split form.
 - The package must be promotable by:
 

package/dist/skills/hr-final-check/SKILL.md

@@ -69,11 +69,12 @@ Keep `final-checklist.md` compact and explicit. Use this shape:
 | descriptions are operator-readable | pass/fail |
 | MCP registrations resolve to staged servers or blocker | pass/fail |
 | handoff clearly separates test/use/promote | pass/fail |
-| model preferences were explicitly collected | pass/fail |
+| model preferences were confirmed before assembly | pass/fail |
 | final names were user-confirmed | pass/fail |
 | specialized work was delegated | pass/fail |
 | staged model ids validated against synced catalog | pass/fail |
 | profile defaultAgent matches bundle agent.name | pass/fail |
+| team includes at least one primary, non-hidden agent | pass/fail |
 | default opencode agent policy confirmed | pass/fail |
 | default profile on promote confirmed | pass/fail |
 | no host project mutations | pass/fail |
@@ -94,5 +95,6 @@ The package cannot be marked ready unless the verifier confirms:
 7. if any bundle references MCP tools, the staged package includes the referenced `mcp/*.json` files, the required `mcp-servers/` implementation files, and `mcp-servers/package.json` when runtime dependencies are needed
 8. the handoff clearly shows how to test/use the staged profile in a workspace before promote, and promote is not described as mandatory for workspace use
 9. if a profile sets `defaultAgent`, that value exactly matches one of the staged bundles' `agent.name` values (not just the bundle filename)
+10. the staged team includes at least one non-hidden primary agent, and any `team-only` profile keeps at least one such primary agent available to the operator
 
 If bundle metadata contains fake runtime keys such as `optional_skills` or `runtime_conditional_skills`, mark the package `NOT READY` until they are removed or rewritten as plain documentation outside runtime bundle semantics.

package/dist/skills/hr-staffing/SKILL.md

@@ -37,8 +37,6 @@ Every staffing plan must include:
 - `composition`
 - `required_skills`
 - `required_tools`
-- `suggested_model_provider`
-- `proposed_agent_models` (initial proposal only; final per-agent defaults require user confirmation later)
 - `draft_names` (draft agent names and draft profile name for user review)
 - `risks`
 - `next_action`
@@ -57,8 +55,8 @@ composition:
 draft_names:
 - seat: ... | proposed_agent_name: ... | reason: ...
 - profile: ... | reason: ...
-proposed_agent_models:
-- agent: ... | model: ...
+required_skills:
+- skill: ... | why: ...
 risks:
 - ...
 next_action: ...
@@ -75,7 +73,9 @@ For each recommended entry, specify:
 
 ## Decision Rules
 
+- At least one staffing-plan entry must have `deployment_role: primary-capable`.
 - Prefer the smallest team that can cover planning, sourcing/exploration, implementation, audit, verification, and documentation.
+- When multiple candidates can cover the same seat, prefer a pure-soul agent with attached skills over a mixed soul+skill agent. Use a mixed soul+skill agent only when the specialized workflow cannot be cleanly separated, the source is tightly fused, or the user explicitly wants that mixed form.
 - Prefer local worker cards from `$HR_HOME/inventory/workers/` with `inventory_status = available`.
 - Treat `draft` worker cards as sourcing inputs that still need review or explicit operator acceptance.
 - Exclude `retired` worker cards from recommended staffing compositions.

package/dist/skills/hr-support/bin/validate_staged_package.py

@@ -9,12 +9,22 @@ import tempfile
 from pathlib import Path
 
 
-def resolve_agenthub_bin() -> str:
+def wrap_executable(command: str) -> list[str]:
+    path = Path(command)
+    suffix = path.suffix.lower()
+    if suffix == ".js":
+        return ["node", command]
+    if os.name == "nt" and suffix in {".cmd", ".bat"}:
+        return ["cmd", "/c", command]
+    return [command]
+
+
+def resolve_agenthub_command() -> list[str]:
     if os.getenv("OPENCODE_AGENTHUB_BIN"):
-        return os.environ["OPENCODE_AGENTHUB_BIN"]
+        return wrap_executable(os.environ["OPENCODE_AGENTHUB_BIN"])
     found = shutil.which("opencode-agenthub")
     if found:
-        return found
+        return wrap_executable(found)
     # Portable repo-local fallback: when running from src/skills/hr-support/bin/
     # inside the source tree, try <repo-root>/bin/opencode-agenthub
     this_file = Path(__file__).resolve()
@@ -28,13 +38,19 @@ def resolve_agenthub_bin() -> str:
         and parts[-4] == "skills"
         and parts[-5] == "src"
     ):
+        repo_bin_cmd = this_file.parents[4] / "bin" / "opencode-agenthub.cmd"
+        if os.name == "nt" and repo_bin_cmd.exists():
+            return ["cmd", "/c", str(repo_bin_cmd)]
         repo_bin = this_file.parents[4] / "bin" / "opencode-agenthub"
-        if repo_bin.exists():
-            return str(repo_bin)
+        if os.name != "nt" and repo_bin.exists():
+            return [str(repo_bin)]
+        repo_dist = this_file.parents[4] / "dist" / "composer" / "opencode-profile.js"
+        if repo_dist.exists():
+            return ["node", str(repo_dist)]
     raise SystemExit(
         "Could not locate opencode-agenthub.\n"
         "  Set OPENCODE_AGENTHUB_BIN to the full path, or add opencode-agenthub to PATH.\n"
-        "  When running from source, ensure bin/opencode-agenthub exists in the repo root."
+        "  When running from source, ensure bin/opencode-agenthub (or .cmd on Windows) exists, or build dist/composer/opencode-profile.js in the repo root."
     )
 
 
@@ -152,6 +168,7 @@ def validate_profile_default_agents(import_root: Path) -> None:
             )
 
         references: list[tuple[str, str]] = []
+        primary_agent_names: set[str] = set()
         missing_bundles: list[str] = []
         for raw_bundle_name in bundle_names:
             if not isinstance(raw_bundle_name, str) or not raw_bundle_name.strip():
@@ -165,11 +182,16 @@ def validate_profile_default_agents(import_root: Path) -> None:
                 continue
             agent = bundle.get("agent", {})
             agent_name = agent.get("name") if isinstance(agent, dict) else None
+            agent_mode = agent.get("mode") if isinstance(agent, dict) else None
+            agent_hidden = agent.get("hidden") if isinstance(agent, dict) else None
             if not isinstance(agent_name, str) or not agent_name.strip():
                 raise SystemExit(
                     f"Bundle '{bundle_name}' is missing required agent.name; profile '{profile_name}' cannot use it."
                 )
-            references.append((bundle_name, agent_name.strip()))
+            normalized_agent_name = agent_name.strip()
+            references.append((bundle_name, normalized_agent_name))
+            if agent_mode == "primary" and agent_hidden is not True:
+                primary_agent_names.add(normalized_agent_name)
 
         if missing_bundles:
             detail = ", ".join(missing_bundles)
@@ -183,6 +205,10 @@ def validate_profile_default_agents(import_root: Path) -> None:
             raise SystemExit(
                 f"Profile '{profile_name}' uses nativeAgentPolicy 'team-only' and must set defaultAgent explicitly."
             )
+        if native_agent_policy == "team-only" and not primary_agent_names:
+            raise SystemExit(
+                f"Profile '{profile_name}' uses nativeAgentPolicy 'team-only' but does not include at least one primary, non-hidden agent."
+            )
         if default_agent is None:
             continue
         if not isinstance(default_agent, str) or not default_agent.strip():
@@ -208,6 +234,10 @@ def validate_profile_default_agents(import_root: Path) -> None:
 
         agent_names = {agent_name for _, agent_name in references}
         if normalized_default_agent in agent_names:
+            if normalized_default_agent not in primary_agent_names:
+                raise SystemExit(
+                    f"Profile '{profile_name}' defaultAgent '{normalized_default_agent}' must point to a primary, non-hidden agent."
+                )
             continue
 
         available = ", ".join(sorted(agent_names)) or "(none)"
@@ -223,7 +253,6 @@ def main() -> int:
             "Usage: validate_staged_package.py <stage-package-root|agenthub-home-root>"
         )
 
-    agenthub_bin = resolve_agenthub_bin()
     import_root = resolve_import_root(sys.argv[1])
     workspace_root = Path.cwd()
     validate_bundle_metadata(import_root)
@@ -235,6 +264,9 @@ def main() -> int:
     if not profiles:
         raise SystemExit("No profiles found in staged import root.")
 
+    # Integration smoke phase below requires a runnable agenthub binary.
+    agenthub_cmd = resolve_agenthub_command()
+
     with tempfile.TemporaryDirectory(prefix="agenthub-stage-validate-") as temp_dir:
         temp_root = Path(temp_dir)
         temp_home = temp_root / "home"
@@ -243,7 +275,7 @@ def main() -> int:
 
         run(
             [
-                agenthub_bin,
+                *agenthub_cmd,
                 "setup",
                 "minimal",
                 "--target-root",
@@ -252,7 +284,7 @@ def main() -> int:
         )
         run(
             [
-                agenthub_bin,
+                *agenthub_cmd,
                 "hub-import",
                 "--source",
                 str(import_root),
@@ -268,7 +300,7 @@ def main() -> int:
         for profile in profiles:
             run(
                 [
-                    agenthub_bin,
+                    *agenthub_cmd,
                     "run",
                     profile,
                     "--workspace",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-agenthub",
-  "version": "0.1.0",
-  "description": "Systematic control plane for opencode agents, skills, profiles, and shared runtime assets.",
+  "version": "0.1.2",
+  "description": "A control plane for organizing, composing, and activating OpenCode agents, skills, profiles, and bundles.",
   "type": "module",
   "main": "./dist/plugins/opencode-agenthub.js",
   "exports": {
@@ -15,7 +15,7 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "test:smoke": "bun test test/smoke-*.test.ts",
-    "prepublishOnly": "npm run build"
+    "prepack": "npm run build"
   },
   "files": [
     "LICENSE",