@openscout/protocol 0.2.63 → 0.2.82

package/src/runtime-catalog.generated.ts

@@ -0,0 +1,300 @@
+// Generated automatically from runtime-catalog.v1.json. Do not edit.
+
+export const SCOUT_RUNTIME_CATALOG_DATA = {
+  "schemaVersion": "openscout.runtime-catalog.v1",
+  "revision": "2026-08-18.1",
+  "harnesses": [
+    {
+      "id": "claude",
+      "label": "Claude Code",
+      "enabled": true,
+      "default": true,
+      "reasoningEfforts": [
+        "low",
+        "medium",
+        "high",
+        "xhigh",
+        "max"
+      ],
+      "defaultReasoningEffort": "medium",
+      "models": [
+        {
+          "id": "claude-opus-5",
+          "label": "Opus 5",
+          "enabled": true,
+          "default": true,
+          "family": "Opus",
+          "version": "5"
+        },
+        {
+          "id": "claude-sonnet-4-6",
+          "label": "Sonnet 4.6",
+          "enabled": true,
+          "family": "Sonnet",
+          "version": "4.6"
+        },
+        {
+          "id": "claude-haiku-4-5",
+          "label": "Haiku 4.5",
+          "enabled": true,
+          "family": "Haiku",
+          "version": "4.5"
+        },
+        {
+          "id": "claude-opus-4-8",
+          "label": "Opus 4.8",
+          "enabled": true,
+          "family": "Opus",
+          "version": "4.8"
+        },
+        {
+          "id": "claude-opus-4-7",
+          "label": "Opus 4.7",
+          "enabled": true,
+          "family": "Opus",
+          "version": "4.7"
+        },
+        {
+          "id": "claude-sonnet-4-5",
+          "label": "Sonnet 4.5",
+          "enabled": true,
+          "family": "Sonnet",
+          "version": "4.5"
+        }
+      ]
+    },
+    {
+      "id": "codex",
+      "label": "Codex",
+      "enabled": true,
+      "reasoningEfforts": [
+        "low",
+        "medium",
+        "high",
+        "xhigh"
+      ],
+      "defaultReasoningEffort": "medium",
+      "models": [
+        {
+          "id": "gpt-5.6-sol",
+          "label": "5.6 Sol",
+          "enabled": true,
+          "default": true,
+          "family": "GPT",
+          "version": "5.6 Sol",
+          "reasoningEfforts": [
+            "low",
+            "medium",
+            "high",
+            "xhigh",
+            "ultra"
+          ]
+        },
+        {
+          "id": "gpt-5.6-terra",
+          "label": "5.6 Terra",
+          "enabled": true,
+          "family": "GPT",
+          "version": "5.6 Terra",
+          "reasoningEfforts": [
+            "low",
+            "medium",
+            "high",
+            "xhigh",
+            "ultra"
+          ]
+        },
+        {
+          "id": "gpt-5.6-luna",
+          "label": "5.6 Luna",
+          "enabled": true,
+          "family": "GPT",
+          "version": "5.6 Luna"
+        },
+        {
+          "id": "gpt-5.5",
+          "label": "5.5",
+          "enabled": true,
+          "family": "GPT",
+          "version": "5.5"
+        },
+        {
+          "id": "gpt-5.5-mini",
+          "label": "5.5 mini",
+          "enabled": true,
+          "family": "GPT",
+          "version": "5.5 mini"
+        }
+      ]
+    },
+    {
+      "id": "grok",
+      "label": "Grok CLI",
+      "enabled": true,
+      "listed": false,
+      "reasoningEfforts": [
+        "low",
+        "medium",
+        "high",
+        "xhigh"
+      ],
+      "defaultReasoningEffort": "medium",
+      "models": [
+        {
+          "id": "grok-4.6",
+          "label": "Grok 4.6",
+          "enabled": true,
+          "default": true,
+          "family": "Grok",
+          "version": "4.6",
+          "contextWindowTokens": 500000
+        },
+        {
+          "id": "grok-4.5",
+          "label": "Grok 4.5",
+          "enabled": true,
+          "family": "Grok",
+          "version": "4.5"
+        },
+        {
+          "id": "grok-4.3",
+          "label": "Grok 4.3",
+          "enabled": true,
+          "family": "Grok",
+          "version": "4.3"
+        }
+      ]
+    },
+    {
+      "id": "grok-acp",
+      "label": "Grok",
+      "enabled": true,
+      "reasoningEfforts": null,
+      "models": [
+        {
+          "id": "grok-4.6",
+          "label": "Grok 4.6",
+          "enabled": true,
+          "default": true,
+          "family": "Grok",
+          "version": "4.6",
+          "contextWindowTokens": 500000
+        },
+        {
+          "id": "grok-4.5",
+          "label": "Grok 4.5",
+          "enabled": true,
+          "family": "Grok",
+          "version": "4.5"
+        },
+        {
+          "id": "grok-4.3",
+          "label": "Grok 4.3",
+          "enabled": true,
+          "family": "Grok",
+          "version": "4.3"
+        }
+      ]
+    },
+    {
+      "id": "kimi",
+      "label": "Kimi Code",
+      "enabled": true,
+      "reasoningEfforts": null,
+      "models": []
+    },
+    {
+      "id": "flue",
+      "label": "Flue",
+      "enabled": true,
+      "reasoningEfforts": null,
+      "models": []
+    },
+    {
+      "id": "cursor",
+      "label": "Cursor CLI",
+      "enabled": true,
+      "reasoningEfforts": null,
+      "models": []
+    },
+    {
+      "id": "opencode",
+      "label": "OpenCode",
+      "enabled": true,
+      "reasoningEfforts": null,
+      "models": [
+        {
+          "id": "opencode-go/glm-5.2",
+          "label": "GLM-5.2",
+          "enabled": true,
+          "default": true,
+          "family": "GLM",
+          "version": "5.2"
+        },
+        {
+          "id": "opencode-go/glm-5.1",
+          "label": "GLM-5.1",
+          "enabled": true,
+          "family": "GLM",
+          "version": "5.1"
+        },
+        {
+          "id": "opencode-go/kimi-k3",
+          "label": "Kimi K3",
+          "enabled": true,
+          "family": "Kimi",
+          "version": "K3"
+        },
+        {
+          "id": "opencode-go/qwen3.8-max",
+          "label": "Qwen3.8 Max",
+          "enabled": true,
+          "family": "Qwen",
+          "version": "3.8 Max"
+        },
+        {
+          "id": "opencode-go/minimax-m3",
+          "label": "MiniMax M3",
+          "enabled": true,
+          "family": "MiniMax",
+          "version": "M3"
+        },
+        {
+          "id": "opencode-go/deepseek-v4-pro",
+          "label": "DeepSeek V4 Pro",
+          "enabled": true,
+          "family": "DeepSeek",
+          "version": "V4 Pro"
+        },
+        {
+          "id": "opencode-go/grok-4.5",
+          "label": "Grok 4.5",
+          "enabled": true,
+          "family": "Grok",
+          "version": "4.5"
+        },
+        {
+          "id": "opencode/nemotron-3-ultra-free",
+          "label": "Nemotron 3 Ultra (free)",
+          "enabled": true,
+          "family": "Nemotron",
+          "version": "3 Ultra Free"
+        },
+        {
+          "id": "opencode/laguna-s-2.1-free",
+          "label": "Laguna S 2.1 (free)",
+          "enabled": true,
+          "family": "Laguna",
+          "version": "S 2.1 Free"
+        }
+      ]
+    },
+    {
+      "id": "pi",
+      "label": "Pi",
+      "enabled": true,
+      "reasoningEfforts": null,
+      "models": []
+    }
+  ]
+} as const;

package/src/runtime-catalog.md

@@ -0,0 +1,21 @@
+# Runtime model catalog
+
+The operator contract is intentionally one step:
+
+1. Edit `packages/protocol/src/runtime-catalog.v1.json`.
+
+That is all. The deployed well-known route publishes the same JSON and every
+running `scoutd` checks it once a minute. Valid revisions replace the bundled
+or persisted last-known-good catalog; malformed or unreachable revisions are
+quarantined with a warning. No generator, daemon restart, app rebuild, or
+cache-bust command is part of a model update.
+
+To intentionally restore older model contents, publish them under a new,
+higher revision. Scout rejects revision downgrades and same-revision content
+changes so retries cannot roll back or silently replace a catalog.
+
+Increment the `YYYY-MM-DD.N` `revision` and add the provider's exact model ID,
+label, harness, default, effort metadata, and `contextWindowTokens` when the
+provider publishes it. Do not infer an aggregator-qualified ID from a
+vendor announcement: xAI's `grok-4.6` proves the Grok IDs, but not an
+`opencode-go/grok-4.6` ID.

package/src/runtime-catalog.ts

@@ -0,0 +1,193 @@
+import {
+  SCOUT_LAUNCHABLE_HARNESSES,
+  SCOUT_REASONING_EFFORTS,
+  type ScoutLaunchableHarness,
+  type ScoutOwnedRuntimeCatalog,
+  type ScoutOwnedRuntimeHarness,
+  type ScoutOwnedRuntimeModel,
+  type ScoutReasoningEffort,
+} from "./runtime-catalog-contract.js";
+
+export type ScoutRuntimeCatalogParseResult =
+  | { ok: true; catalog: ScoutOwnedRuntimeCatalog }
+  | { ok: false; errors: string[] };
+
+const launchableHarnesses = new Set<string>(SCOUT_LAUNCHABLE_HARNESSES);
+const reasoningEfforts = new Set<string>(SCOUT_REASONING_EFFORTS);
+export const MAX_RUNTIME_MODELS_PER_HARNESS = 256;
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function text(value: unknown): string | null {
+  return typeof value === "string" && value.trim() === value && value.length > 0
+    ? value
+    : null;
+}
+
+function effortList(value: unknown, path: string, errors: string[]): ScoutReasoningEffort[] | null | undefined {
+  if (value === null) return null;
+  if (!Array.isArray(value)) {
+    errors.push(`${path} must be an array or null`);
+    return undefined;
+  }
+  const result: ScoutReasoningEffort[] = [];
+  const seen = new Set<string>();
+  for (const candidate of value) {
+    if (typeof candidate !== "string" || !reasoningEfforts.has(candidate)) {
+      errors.push(`${path} contains unknown effort ${String(candidate)}`);
+      continue;
+    }
+    if (seen.add(candidate)) result.push(candidate as ScoutReasoningEffort);
+    else errors.push(`${path} contains duplicate effort ${candidate}`);
+  }
+  return result;
+}
+
+function model(value: unknown, path: string, errors: string[]): ScoutOwnedRuntimeModel | null {
+  const input = record(value);
+  if (!input) {
+    errors.push(`${path} must be an object`);
+    return null;
+  }
+  const id = text(input.id);
+  const label = text(input.label);
+  if (!id || !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/u.test(id)) {
+    errors.push(`${path}.id must use provider-safe letters, numbers, dot, slash, underscore, or hyphen`);
+  }
+  if (!label) errors.push(`${path}.label is required`);
+  if (typeof input.enabled !== "boolean") errors.push(`${path}.enabled must be boolean`);
+  if (input.default === true && input.enabled !== true) errors.push(`${path} cannot be default while disabled`);
+  if (!id || !label || typeof input.enabled !== "boolean") return null;
+  const efforts = input.reasoningEfforts === undefined
+    ? undefined
+    : effortList(input.reasoningEfforts, `${path}.reasoningEfforts`, errors);
+  const defaultEffort = input.defaultReasoningEffort == null ? null : text(input.defaultReasoningEffort);
+  const contextWindowTokens = input.contextWindowTokens;
+  if (contextWindowTokens !== undefined && (!Number.isInteger(contextWindowTokens) || Number(contextWindowTokens) <= 0)) {
+    errors.push(`${path}.contextWindowTokens must be a positive integer`);
+  }
+  if (input.defaultReasoningEffort != null && (!defaultEffort || !reasoningEfforts.has(defaultEffort))) {
+    errors.push(`${path}.defaultReasoningEffort is unknown`);
+  }
+  return {
+    id,
+    label,
+    enabled: input.enabled,
+    ...(input.default === true ? { default: true } : {}),
+    ...(text(input.description) ? { description: text(input.description)! } : {}),
+    ...(text(input.family) ? { family: text(input.family)! } : {}),
+    ...(text(input.version) ? { version: text(input.version)! } : {}),
+    ...(Number.isInteger(contextWindowTokens) && Number(contextWindowTokens) > 0
+      ? { contextWindowTokens: Number(contextWindowTokens) }
+      : {}),
+    ...(input.reasoningEfforts !== undefined ? { reasoningEfforts: efforts ?? null } : {}),
+    ...(defaultEffort && reasoningEfforts.has(defaultEffort)
+      ? { defaultReasoningEffort: defaultEffort as ScoutReasoningEffort }
+      : {}),
+  };
+}
+
+function harness(value: unknown, path: string, errors: string[]): ScoutOwnedRuntimeHarness | null {
+  const input = record(value);
+  if (!input) {
+    errors.push(`${path} must be an object`);
+    return null;
+  }
+  const id = text(input.id);
+  const label = text(input.label);
+  if (!id || !launchableHarnesses.has(id)) errors.push(`${path}.id is not a launchable harness`);
+  if (!label) errors.push(`${path}.label is required`);
+  if (typeof input.enabled !== "boolean") errors.push(`${path}.enabled must be boolean`);
+  if (input.listed !== undefined && typeof input.listed !== "boolean") {
+    errors.push(`${path}.listed must be boolean when provided`);
+  }
+  if (input.default === true && input.enabled !== true) errors.push(`${path} cannot be default while disabled`);
+  const efforts = effortList(input.reasoningEfforts, `${path}.reasoningEfforts`, errors);
+  if (!id || !launchableHarnesses.has(id) || !label || typeof input.enabled !== "boolean" || efforts === undefined) {
+    return null;
+  }
+  if (!Array.isArray(input.models)) {
+    errors.push(`${path}.models must be an array`);
+    return null;
+  }
+  if (input.models.length > MAX_RUNTIME_MODELS_PER_HARNESS) {
+    errors.push(`${path}.models exceeds the ${MAX_RUNTIME_MODELS_PER_HARNESS}-model limit`);
+    return null;
+  }
+  const models = input.models
+    .map((entry, index) => model(entry, `${path}.models[${index}]`, errors))
+    .filter((entry): entry is ScoutOwnedRuntimeModel => Boolean(entry));
+  const ids = new Set<string>();
+  for (const entry of models) {
+    if (!ids.add(entry.id)) errors.push(`${path} contains duplicate model ${entry.id}`);
+    const effective = entry.reasoningEfforts === undefined ? efforts : entry.reasoningEfforts;
+    if (entry.defaultReasoningEffort && !effective?.includes(entry.defaultReasoningEffort)) {
+      errors.push(`${path} model ${entry.id} has an unsupported default effort`);
+    }
+  }
+  if (models.filter((entry) => entry.default).length > 1) errors.push(`${path} has more than one default model`);
+  for (const entry of models) {
+    if (entry.default && !entry.enabled) errors.push(`${path} model ${entry.id} cannot be default while disabled`);
+  }
+  const defaultEffort = input.defaultReasoningEffort == null ? null : text(input.defaultReasoningEffort);
+  if (defaultEffort && !efforts?.includes(defaultEffort as ScoutReasoningEffort)) {
+    errors.push(`${path}.defaultReasoningEffort is not supported`);
+  }
+  return {
+    id: id as ScoutLaunchableHarness,
+    label,
+    enabled: input.enabled,
+    ...(typeof input.listed === "boolean" ? { listed: input.listed } : {}),
+    ...(input.default === true ? { default: true } : {}),
+    reasoningEfforts: efforts,
+    ...(defaultEffort && reasoningEfforts.has(defaultEffort)
+      ? { defaultReasoningEffort: defaultEffort as ScoutReasoningEffort }
+      : {}),
+    models,
+  };
+}
+
+export function parseScoutRuntimeCatalog(value: unknown): ScoutRuntimeCatalogParseResult {
+  const input = record(value);
+  if (!input) return { ok: false, errors: ["catalog must be a JSON object"] };
+  const errors: string[] = [];
+  if (input.schemaVersion !== "openscout.runtime-catalog.v1") errors.push("unexpected schemaVersion");
+  const revision = text(input.revision);
+  if (!revision || !/^\d{4}-\d{2}-\d{2}\.\d+$/u.test(revision)) {
+    errors.push("revision must use YYYY-MM-DD.N format");
+  }
+  if (!Array.isArray(input.harnesses) || input.harnesses.length === 0) {
+    errors.push("harnesses must be a non-empty array");
+    return { ok: false, errors };
+  }
+  const harnesses = input.harnesses
+    .map((entry, index) => harness(entry, `harnesses[${index}]`, errors))
+    .filter((entry): entry is ScoutOwnedRuntimeHarness => Boolean(entry));
+  const ids = new Set<string>();
+  const sharedModels = new Map<string, string>();
+  for (const entry of harnesses) {
+    if (!ids.add(entry.id)) errors.push(`duplicate harness ${entry.id}`);
+    for (const model of entry.models) {
+      const signature = JSON.stringify([
+        model.label,
+        model.description ?? null,
+        model.family ?? null,
+        model.version ?? null,
+        model.contextWindowTokens ?? null,
+      ]);
+      const prior = sharedModels.get(model.id);
+      if (prior && prior !== signature) errors.push(`shared model ${model.id} has inconsistent metadata`);
+      sharedModels.set(model.id, signature);
+    }
+  }
+  if (harnesses.filter((entry) => entry.enabled && entry.default).length !== 1) {
+    errors.push("catalog must contain exactly one enabled default harness");
+  }
+  return errors.length || !revision
+    ? { ok: false, errors }
+    : { ok: true, catalog: { schemaVersion: "openscout.runtime-catalog.v1", revision, harnesses } };
+}

package/src/runtime-catalog.v1.json

@@ -0,0 +1,81 @@
+{
+  "schemaVersion": "openscout.runtime-catalog.v1",
+  "revision": "2026-08-18.1",
+  "harnesses": [
+    {
+      "id": "claude",
+      "label": "Claude Code",
+      "enabled": true,
+      "default": true,
+      "reasoningEfforts": ["low", "medium", "high", "xhigh", "max"],
+      "defaultReasoningEffort": "medium",
+      "models": [
+        { "id": "claude-opus-5", "label": "Opus 5", "enabled": true, "default": true, "family": "Opus", "version": "5" },
+        { "id": "claude-sonnet-4-6", "label": "Sonnet 4.6", "enabled": true, "family": "Sonnet", "version": "4.6" },
+        { "id": "claude-haiku-4-5", "label": "Haiku 4.5", "enabled": true, "family": "Haiku", "version": "4.5" },
+        { "id": "claude-opus-4-8", "label": "Opus 4.8", "enabled": true, "family": "Opus", "version": "4.8" },
+        { "id": "claude-opus-4-7", "label": "Opus 4.7", "enabled": true, "family": "Opus", "version": "4.7" },
+        { "id": "claude-sonnet-4-5", "label": "Sonnet 4.5", "enabled": true, "family": "Sonnet", "version": "4.5" }
+      ]
+    },
+    {
+      "id": "codex",
+      "label": "Codex",
+      "enabled": true,
+      "reasoningEfforts": ["low", "medium", "high", "xhigh"],
+      "defaultReasoningEffort": "medium",
+      "models": [
+        { "id": "gpt-5.6-sol", "label": "5.6 Sol", "enabled": true, "default": true, "family": "GPT", "version": "5.6 Sol", "reasoningEfforts": ["low", "medium", "high", "xhigh", "ultra"] },
+        { "id": "gpt-5.6-terra", "label": "5.6 Terra", "enabled": true, "family": "GPT", "version": "5.6 Terra", "reasoningEfforts": ["low", "medium", "high", "xhigh", "ultra"] },
+        { "id": "gpt-5.6-luna", "label": "5.6 Luna", "enabled": true, "family": "GPT", "version": "5.6 Luna" },
+        { "id": "gpt-5.5", "label": "5.5", "enabled": true, "family": "GPT", "version": "5.5" },
+        { "id": "gpt-5.5-mini", "label": "5.5 mini", "enabled": true, "family": "GPT", "version": "5.5 mini" }
+      ]
+    },
+    {
+      "id": "grok",
+      "label": "Grok CLI",
+      "enabled": true,
+      "listed": false,
+      "reasoningEfforts": ["low", "medium", "high", "xhigh"],
+      "defaultReasoningEffort": "medium",
+      "models": [
+        { "id": "grok-4.6", "label": "Grok 4.6", "enabled": true, "default": true, "family": "Grok", "version": "4.6", "contextWindowTokens": 500000 },
+        { "id": "grok-4.5", "label": "Grok 4.5", "enabled": true, "family": "Grok", "version": "4.5" },
+        { "id": "grok-4.3", "label": "Grok 4.3", "enabled": true, "family": "Grok", "version": "4.3" }
+      ]
+    },
+    {
+      "id": "grok-acp",
+      "label": "Grok",
+      "enabled": true,
+      "reasoningEfforts": null,
+      "models": [
+        { "id": "grok-4.6", "label": "Grok 4.6", "enabled": true, "default": true, "family": "Grok", "version": "4.6", "contextWindowTokens": 500000 },
+        { "id": "grok-4.5", "label": "Grok 4.5", "enabled": true, "family": "Grok", "version": "4.5" },
+        { "id": "grok-4.3", "label": "Grok 4.3", "enabled": true, "family": "Grok", "version": "4.3" }
+      ]
+    },
+    { "id": "kimi", "label": "Kimi Code", "enabled": true, "reasoningEfforts": null, "models": [] },
+    { "id": "flue", "label": "Flue", "enabled": true, "reasoningEfforts": null, "models": [] },
+    { "id": "cursor", "label": "Cursor CLI", "enabled": true, "reasoningEfforts": null, "models": [] },
+    {
+      "id": "opencode",
+      "label": "OpenCode",
+      "enabled": true,
+      "reasoningEfforts": null,
+      "models": [
+        { "id": "opencode-go/glm-5.2", "label": "GLM-5.2", "enabled": true, "default": true, "family": "GLM", "version": "5.2" },
+        { "id": "opencode-go/glm-5.1", "label": "GLM-5.1", "enabled": true, "family": "GLM", "version": "5.1" },
+        { "id": "opencode-go/kimi-k3", "label": "Kimi K3", "enabled": true, "family": "Kimi", "version": "K3" },
+        { "id": "opencode-go/qwen3.8-max", "label": "Qwen3.8 Max", "enabled": true, "family": "Qwen", "version": "3.8 Max" },
+        { "id": "opencode-go/minimax-m3", "label": "MiniMax M3", "enabled": true, "family": "MiniMax", "version": "M3" },
+        { "id": "opencode-go/deepseek-v4-pro", "label": "DeepSeek V4 Pro", "enabled": true, "family": "DeepSeek", "version": "V4 Pro" },
+        { "id": "opencode-go/grok-4.5", "label": "Grok 4.5", "enabled": true, "family": "Grok", "version": "4.5" },
+        { "id": "opencode/nemotron-3-ultra-free", "label": "Nemotron 3 Ultra (free)", "enabled": true, "family": "Nemotron", "version": "3 Ultra Free" },
+        { "id": "opencode/laguna-s-2.1-free", "label": "Laguna S 2.1 (free)", "enabled": true, "family": "Laguna", "version": "S 2.1 Free" }
+      ]
+    },
+    { "id": "pi", "label": "Pi", "enabled": true, "reasoningEfforts": null, "models": [] }
+  ]
+}