opencode-agenthub 0.1.1 → 0.1.3

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/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,
@@ -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.
-- 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 `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`.
+- If a prior or external flow has set `promotion_preferences.set_default_profile`, preserve it in `handoff.json`. Do not proactively ask the operator about default-profile preferences during assembly.
+- If AI models are still unresolved when final assembly begins, stop and confirm the exact model choice here before writing staged agent defaults. Model confirmation must use opencode environment availability probing, not the synced inventory catalog.
 - 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

@@ -26,7 +26,7 @@ Verify that a staged package is understandable and safe before the human operato
 7. deployment role correctness
 8. unresolved risks / open decisions
 9. import-root and assemble-only validation
-10. runtime/default-profile confirmation
+10. runtime configuration confirmation
 11. protocol-compliance checkpoints
 
 ## Clarity Definitions
@@ -69,13 +69,14 @@ 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 |
+| staged model ids confirmed via opencode environment | 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 |
+| default-profile preference recorded if present | pass/fail |
 | no host project mutations | pass/fail |
 overall: READY FOR HUMAN CONFIRMATION | READY WITH CAVEATS | NOT READY
 blocker: <description or none>
@@ -89,10 +90,11 @@ The package cannot be marked ready unless the verifier confirms:
 2. the manual import fallback points to `<package-root>/agenthub-home` and is described as advanced/manual only
 3. all referenced skills either exist inside the staged `skills/` directory or are explicitly rejected as missing blockers
 4. `python3 $HR_HOME/bin/validate_staged_package.py $HR_HOME/staging/<package-id>` passes
-5. the package explicitly records whether default opencode agents are kept or hidden, and whether the promoted profile should become the default profile
-6. staged model ids either match the synced catalog exactly or are called out as blockers/caveats for human review
+5. the package explicitly records whether default opencode agents are kept or hidden, and if `promotion_preferences.set_default_profile` is present, it is consistent
+6. staged model ids are either confirmed available in the opencode environment or are called out as blockers/caveats for human review
 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,10 +37,9 @@ 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`
+- `team_size_advisory` (included when recommended team exceeds four agents)
 - `next_action`
 
 ## Compact Summary Shape
@@ -57,10 +56,11 @@ composition:
 draft_names:
 - seat: ... | proposed_agent_name: ... | reason: ...
 - profile: ... | reason: ...
-proposed_agent_models:
-- agent: ... | model: ...
+required_skills:
+- skill: ... | why: ...
 risks:
 - ...
+team_size_advisory: <omit if ≤4 agents; otherwise: "Recommend one to two primary agents with remaining agents as subagents.">
 next_action: ...
 ```
 
@@ -75,11 +75,14 @@ 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.
+- If the recommended team has more than four agents, include a `team_size_advisory` noting that the team should be structured around one to two primary agents with the remaining agents deployed as subagents. Do not recommend more than two primary-capable agents unless the user explicitly requests it.
+- 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.
-- Treat user-supplied model names as advisory until checked against `$HR_HOME/inventory/models/catalog.json` or `$HR_HOME/inventory/models/valid-model-ids.txt`. If an exact catalog match is missing, mark the proposal unresolved instead of inventing a model id.
+- Treat user-supplied model names as advisory. Model confirmation happens during staging via opencode environment availability probing, not during staffing planning. If a user-supplied name looks syntactically invalid, note that, but do not attempt catalog-based validation here.
 - If multiple valid compositions exist, present them as options rather than pretending one is certain.
 - If a skill host is unresolved, say so plainly.
 - Draft names must be treated as proposals only. The parent HR agent must show them to the user and get confirmation before adaptation starts.

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

@@ -168,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():
@@ -181,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)
@@ -199,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():
@@ -224,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)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-agenthub",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A control plane for organizing, composing, and activating OpenCode agents, skills, profiles, and bundles.",
   "type": "module",
   "main": "./dist/plugins/opencode-agenthub.js",