@tangle-network/agent-interface 0.14.0 → 0.16.0

package/dist/harness-capabilities.d.ts

@@ -29,6 +29,20 @@ export declare function harnessSupportsModel(harness: HarnessType, modelId: stri
 /** The harness to adopt for a model whose provider is vendor-locked (`anthropic` → `claude-code`,
  *  `openai` → `codex`, `moonshot` → `kimi-code`); `null` when any router-backed harness will do. */
 export declare function preferredHarnessForModel(modelId: string): HarnessType | null;
+/**
+ * Keep `modelId` when the harness can run it; otherwise return the harness's best compatible id from
+ * `candidateIds` (preferred patterns in order, highest version within a pattern). When nothing in the
+ * candidate list fits, the original id is returned unchanged so the caller sees the incompatibility
+ * instead of a silent wrong substitution. `candidateIds` are canonical ("provider/model") ids — the
+ * caller maps its own catalog shape down to ids, keeping this layer catalog-agnostic.
+ */
+export declare function snapModelToHarness(harness: HarnessType, modelId: string, candidateIds: readonly string[]): string;
+/**
+ * Keep the harness when it can run `modelId`; otherwise return the model's native harness
+ * (anthropic → claude-code, openai → codex, moonshot → kimi-code), falling back to the router-backed
+ * `opencode` for everything else.
+ */
+export declare function snapHarnessToModel(harness: HarnessType, modelId: string): HarnessType;
 /** The reasoning efforts a harness can express, independent of model — `none` up to its ceiling. */
 export declare function harnessReasoningEfforts(harness: HarnessType): readonly ReasoningEffort[];
 /** What the caller knows about a model's own reasoning capability (from a model catalog). */
@@ -44,3 +58,9 @@ export interface ModelReasoningCapability {
  * lower ceiling caps the list there. Pass `model` from your catalog; omit it for the harness-only set.
  */
 export declare function reasoningEffortsFor(harness: HarnessType, model?: ModelReasoningCapability | null): readonly ReasoningEffort[];
+/** Whether the harness's runner honors a per-turn MODEL override (vs. picking the model itself). */
+export declare function harnessHonorsModel(harness: HarnessType): boolean;
+/** Whether the harness's runner honors a reasoning-EFFORT override (vs. dropping it). */
+export declare function harnessHonorsEffort(harness: HarnessType): boolean;
+/** Whether the harness honors BOTH chat selectors — i.e. the model and effort pickers are live. */
+export declare function harnessHonorsSelectors(harness: HarnessType): boolean;

package/dist/harness-capabilities.js

@@ -29,10 +29,13 @@ export const reasoningLadder = [
  * Provider prefixes a harness is vendor-locked to (canonical-id prefix, e.g. `anthropic`, `openai`).
  * A harness with no entry is router-backed: it runs any model. Keyed by the BASE runner — aliases
  * (`claude`/`claudish`/`kimi`) resolve through `canonicalizeHarness` first.
+ *
+ * `nanoclaw` is deliberately absent despite the "claw" name: its runner routes every provider through
+ * the Tangle router (canonical model id straight to the gateway), so it is router-backed like
+ * `opencode` — not Anthropic-locked.
  */
 const harnessProviderLock = {
     "claude-code": ["anthropic"],
-    nanoclaw: ["anthropic"],
     codex: ["openai"],
     "kimi-code": ["moonshot"],
 };
@@ -68,19 +71,69 @@ export function preferredHarnessForModel(modelId) {
     }
     return null;
 }
+// ── Harness ↔ model snapping (catalog-aware) ─────────────────────────────────
+/**
+ * Per-harness ranking patterns for {@link snapModelToHarness}, best first; within one pattern the
+ * highest version wins (numeric-aware). Only vendor-locked harnesses need an entry — a router-backed
+ * harness never snaps (it runs the model as-is). Keyed by the BASE runner (aliases canonicalized).
+ */
+const harnessPreferredModelPatterns = {
+    "claude-code": [
+        /^anthropic\/claude-opus-[\d.-]+$/,
+        /^anthropic\/claude-sonnet-[\d.-]+$/,
+        /^anthropic\//,
+    ],
+    codex: [/^openai\/gpt-\d+(\.\d+)?$/, /^openai\/gpt/, /^openai\//],
+    "kimi-code": [/^moonshot\//],
+};
+const numericDesc = new Intl.Collator(undefined, {
+    numeric: true,
+    sensitivity: "base",
+});
+/**
+ * Keep `modelId` when the harness can run it; otherwise return the harness's best compatible id from
+ * `candidateIds` (preferred patterns in order, highest version within a pattern). When nothing in the
+ * candidate list fits, the original id is returned unchanged so the caller sees the incompatibility
+ * instead of a silent wrong substitution. `candidateIds` are canonical ("provider/model") ids — the
+ * caller maps its own catalog shape down to ids, keeping this layer catalog-agnostic.
+ */
+export function snapModelToHarness(harness, modelId, candidateIds) {
+    if (harnessSupportsModel(harness, modelId))
+        return modelId;
+    const patterns = harnessPreferredModelPatterns[canonicalizeHarness(harness)] ?? [];
+    for (const pattern of patterns) {
+        const matches = candidateIds
+            .filter((id) => pattern.test(id))
+            .sort((a, b) => numericDesc.compare(b, a));
+        if (matches.length > 0)
+            return matches[0];
+    }
+    return candidateIds.find((id) => harnessSupportsModel(harness, id)) ?? modelId;
+}
+/**
+ * Keep the harness when it can run `modelId`; otherwise return the model's native harness
+ * (anthropic → claude-code, openai → codex, moonshot → kimi-code), falling back to the router-backed
+ * `opencode` for everything else.
+ */
+export function snapHarnessToModel(harness, modelId) {
+    if (harnessSupportsModel(harness, modelId))
+        return harness;
+    return preferredHarnessForModel(modelId) ?? "opencode";
+}
 // ── Reasoning-effort support ──────────────────────────────────────────────────
 /**
  * The highest reasoning effort a harness's runtime can express (its native clamp ceiling). Grounded
  * in cli-bridge: codex's `model_reasoning_effort` caps at `high` (xhigh/ultracode clamp down); kimi's
  * `--thinking` is binary, so `high` is its "on"; claude-code carries the full range; `cli-base` has
- * no agent and thus no thinking. Router/model-driven harnesses default to the full range.
+ * no agent and thus no thinking; `nanoclaw`'s runner sends no thinking flag, so it expresses only
+ * `none`. Router/model-driven harnesses default to the full range.
  */
 const harnessReasoningCeiling = {
     "cli-base": "none",
     codex: "high",
     "kimi-code": "high",
     "claude-code": "ultracode",
-    nanoclaw: "ultracode",
+    nanoclaw: "none",
 };
 /** The reasoning efforts a harness can express, independent of model — `none` up to its ceiling. */
 export function harnessReasoningEfforts(harness) {
@@ -103,3 +156,40 @@ export function reasoningEffortsFor(harness, model) {
     }
     return efforts;
 }
+// ── Per-turn selector support (does the harness honor the chat pickers?) ──────
+/**
+ * Harnesses whose runner DROPS a per-turn selector — grounded in the cli-bridge adapter audit, NOT a
+ * guess. Most harnesses honor both selectors, so only the exceptions are listed; a harness absent from
+ * a set honors that selector. Keyed by the BASE runner (aliases canonicalized).
+ *
+ *   - model dropped:  `amp` (own agent picks the model), `openclaw` (dispatcher routes by its own
+ *     config), `nanoclaw` (socket-bridge runner is config/env-driven).
+ *   - effort dropped: `amp` and `factory-droids`/`hermes`/`nanoclaw` (no thinking flag is plumbed to
+ *     the underlying CLI).
+ *
+ * This is distinct from {@link reasoningEffortsFor} (which levels a harness can EXPRESS): a picker uses
+ * these to trim or mark harnesses up front, so a user's model/effort choice is never silently ignored.
+ */
+const harnessIgnoresModel = new Set([
+    "amp",
+    "openclaw",
+    "nanoclaw",
+]);
+const harnessIgnoresEffort = new Set([
+    "amp",
+    "factory-droids",
+    "hermes",
+    "nanoclaw",
+]);
+/** Whether the harness's runner honors a per-turn MODEL override (vs. picking the model itself). */
+export function harnessHonorsModel(harness) {
+    return !harnessIgnoresModel.has(canonicalizeHarness(harness));
+}
+/** Whether the harness's runner honors a reasoning-EFFORT override (vs. dropping it). */
+export function harnessHonorsEffort(harness) {
+    return !harnessIgnoresEffort.has(canonicalizeHarness(harness));
+}
+/** Whether the harness honors BOTH chat selectors — i.e. the model and effort pickers are live. */
+export function harnessHonorsSelectors(harness) {
+    return harnessHonorsModel(harness) && harnessHonorsEffort(harness);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "type": "module",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -36,11 +36,14 @@
   },
   "devDependencies": {
     "@types/node": "25.6.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "check-types": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }