@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/model-router/taxonomy.test.mjs

@@ -1,410 +0,0 @@
-/**
- * taxonomy.test.mjs — the closed 16-reason enum, the disposition contract,
- * and the four classifiers (CLI stream-json, result subtype, stderr, HTTP).
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  FAILOVER_REASONS,
-  DISPOSITION,
-  isFailoverReason,
-  asFailoverReason,
-  RATE_LIMIT_STEPS_MS,
-  steppedCooldownMs,
-  cooldownMsFor,
-  classifyCliEvent,
-  classifyResultSubtype,
-  classifyResultالالسubtype,
-  classifyStderr,
-  classifyHttp,
-  flattenHttpBody,
-  classifyTransportError,
-} from "./taxonomy.mjs";
-
-// ---------------------------------------------------------------------------
-// Enum closure
-// ---------------------------------------------------------------------------
-
-test("FAILOVER_REASONS is the closed 16-value enum, in spec order", () => {
-  assert.equal(FAILOVER_REASONS.length, 16);
-  assert.deepEqual(FAILOVER_REASONS, [
-    "auth",
-    "auth_permanent",
-    "billing",
-    "rate_limit",
-    "overloaded",
-    "server_error",
-    "timeout",
-    "model_not_found",
-    "context_overflow",
-    "payload_too_large",
-    "content_policy",
-    "provider_policy",
-    "format",
-    "empty_response",
-    "network",
-    "unknown",
-  ]);
-});
-
-test("isFailoverReason / asFailoverReason", () => {
-  assert.ok(isFailoverReason("rate_limit"));
-  assert.ok(!isFailoverReason("nope"));
-  assert.equal(asFailoverReason("billing"), "billing");
-  assert.equal(asFailoverReason("garbage"), "unknown");
-  assert.equal(asFailoverReason(undefined), "unknown");
-});
-
-test("DISPOSITION has exactly one frozen row per reason", () => {
-  assert.deepEqual(Object.keys(DISPOSITION).sort(), [...FAILOVER_REASONS].sort());
-  for (const r of FAILOVER_REASONS) {
-    const row = DISPOSITION[r];
-    assert.ok(Object.isFrozen(row), `${r} row frozen`);
-    assert.equal(typeof row.failoverNext, "boolean", `${r}.failoverNext`);
-    assert.equal(typeof row.opensBreaker, "boolean", `${r}.opensBreaker`);
-    assert.ok("cooldownScope" in row, `${r}.cooldownScope`);
-  }
-});
-
-// ---------------------------------------------------------------------------
-// Disposition load-bearing rules (the contract)
-// ---------------------------------------------------------------------------
-
-test("context_overflow NEVER fails over, no cooldown, no breaker", () => {
-  const d = DISPOSITION.context_overflow;
-  assert.equal(d.failoverNext, false);
-  assert.equal(d.retrySame, false);
-  assert.equal(d.cooldownScope, "none");
-  assert.equal(d.cooldownMs, 0);
-  assert.equal(d.opensBreaker, false);
-});
-
-test("network NEVER fails over, no cooldown, and does NOT open a breaker (DEFER)", () => {
-  const d = DISPOSITION.network;
-  assert.equal(d.failoverNext, false);
-  assert.equal(d.cooldownScope, "none");
-  assert.equal(d.cooldownMs, 0);
-  assert.equal(d.opensBreaker, false);
-});
-
-test("payload_too_large does not fail over (shrink path)", () => {
-  const d = DISPOSITION.payload_too_large;
-  assert.equal(d.failoverNext, false);
-  assert.equal(d.cooldownMs, 0);
-  assert.equal(d.opensBreaker, false);
-});
-
-test("content_policy is sticky: no same-content failover, no cooldown", () => {
-  const d = DISPOSITION.content_policy;
-  assert.equal(d.failoverNext, false);
-  assert.equal(d.retrySame, false);
-  assert.equal(d.cooldownScope, "none");
-});
-
-test("rate_limit cooldown is backend:model and stepped 30s→1m→5m", () => {
-  const d = DISPOSITION.rate_limit;
-  assert.equal(d.cooldownScope, "backend:model");
-  assert.deepEqual(d.stepped, RATE_LIMIT_STEPS_MS);
-  assert.deepEqual(RATE_LIMIT_STEPS_MS, [30_000, 60_000, 300_000]);
-  assert.equal(d.opensBreaker, true);
-  assert.equal(d.failoverNext, true);
-});
-
-test("stepped cooldown advances and saturates at the last step", () => {
-  assert.equal(steppedCooldownMs("rate_limit", 0), 30_000);
-  assert.equal(steppedCooldownMs("rate_limit", 1), 60_000);
-  assert.equal(steppedCooldownMs("rate_limit", 2), 300_000);
-  assert.equal(steppedCooldownMs("rate_limit", 9), 300_000); // saturates
-  assert.equal(steppedCooldownMs("billing", 0), null); // not stepped
-});
-
-test("cooldownMsFor: stepped for rate_limit, flat for overloaded, Infinity for permanent", () => {
-  assert.equal(cooldownMsFor("rate_limit", 0), 30_000);
-  assert.equal(cooldownMsFor("rate_limit", 2), 300_000);
-  assert.equal(cooldownMsFor("overloaded", 5), 60_000); // flat 60s regardless of strike
-  assert.equal(cooldownMsFor("billing", 0), 6 * 60 * 60 * 1000);
-  assert.equal(cooldownMsFor("auth", 0), 5 * 60 * 1000);
-  assert.equal(cooldownMsFor("auth_permanent", 0), Infinity);
-  assert.equal(cooldownMsFor("model_not_found", 0), Infinity);
-  assert.equal(cooldownMsFor("timeout", 0), 0);
-  assert.equal(cooldownMsFor("network", 0), 0);
-});
-
-test("billing disambiguated from rate_limit: backend scope, 6h, no retry-same", () => {
-  const d = DISPOSITION.billing;
-  assert.equal(d.cooldownScope, "backend");
-  assert.equal(d.cooldownMs, 6 * 60 * 60 * 1000);
-  assert.equal(d.retrySame, false);
-});
-
-test("auth_permanent cools until operator", () => {
-  assert.equal(DISPOSITION.auth_permanent.cooldownMs, Infinity);
-  assert.equal(DISPOSITION.auth_permanent.cooldownScope, "operator");
-});
-
-test("overloaded: retry once jittered, backend:model 60s breaker", () => {
-  const d = DISPOSITION.overloaded;
-  assert.equal(d.retrySame, "jittered");
-  assert.equal(d.cooldownScope, "backend:model");
-  assert.equal(d.cooldownMs, 60_000);
-});
-
-test("timeout/empty_response retry once but never open a breaker", () => {
-  assert.equal(DISPOSITION.timeout.retrySame, true);
-  assert.equal(DISPOSITION.timeout.opensBreaker, false);
-  assert.equal(DISPOSITION.empty_response.retrySame, true);
-  assert.equal(DISPOSITION.empty_response.opensBreaker, false);
-});
-
-// ---------------------------------------------------------------------------
-// 1. CLI stream-json classifier — 1:1 enum mapping
-// ---------------------------------------------------------------------------
-
-test("classifyCliEvent maps the closed CLI enum 1:1", () => {
-  const cases = {
-    authentication_failed: "auth",
-    oauth_org_not_allowed: "auth_permanent",
-    billing_error: "billing",
-    rate_limit: "rate_limit",
-    overloaded: "overloaded",
-    invalid_request: "format",
-    model_not_found: "model_not_found",
-    server_error: "server_error",
-    max_output_tokens: "context_overflow",
-    unknown: "unknown",
-  };
-  for (const [code, expected] of Object.entries(cases)) {
-    // bare string form
-    assert.equal(classifyCliEvent(code), expected, `string ${code}`);
-    // event-object form
-    assert.equal(
-      classifyCliEvent({ type: "system", subtype: "api_retry", error: code }),
-      expected,
-      `event ${code}`
-    );
-  }
-});
-
-test("classifyCliEvent: nested error.type, unmapped api_retry → unknown, junk → null", () => {
-  assert.equal(classifyCliEvent({ type: "system", error: { type: "rate_limit" } }), "rate_limit");
-  assert.equal(classifyCliEvent({ subtype: "api_retry", error: "weird_new_code" }), "unknown");
-  assert.equal(classifyCliEvent({ type: "assistant", text: "hi" }), null);
-  assert.equal(classifyCliEvent(null), null);
-  assert.equal(classifyCliEvent(""), null);
-});
-
-// ---------------------------------------------------------------------------
-// 2. Result-json subtype classifier
-// ---------------------------------------------------------------------------
-
-test("classifyResultSubtype maps terminal subtypes", () => {
-  assert.equal(classifyResultSubtype("success"), "ok");
-  assert.equal(classifyResultSubtype("error_max_turns"), "unknown");
-  assert.equal(classifyResultSubtype("error_max_budget_usd"), "unknown");
-  assert.equal(classifyResultSubtype("error_during_execution"), "server_error");
-  assert.equal(classifyResultSubtype("error_max_output_tokens"), "context_overflow");
-  assert.equal(classifyResultSubtype("error_something_new"), "unknown");
-  assert.equal(classifyResultSubtype("partial"), null);
-  assert.equal(classifyResultSubtype(""), null);
-});
-
-test("mojibake alias resolves to the same function", () => {
-  assert.equal(classifyResultالالسubtype, classifyResultSubtype);
-  assert.equal(classifyResultالالسubtype("success"), "ok");
-});
-
-// ---------------------------------------------------------------------------
-// 3. stderr classifier (extends rate-guard.classifyStderr)
-// ---------------------------------------------------------------------------
-
-test("classifyStderr: 'Prompt is too long' → context_overflow", () => {
-  assert.equal(classifyStderr("Error: Prompt is too long: 250000 tokens"), "context_overflow");
-});
-
-test("classifyStderr: usage-policy refusal → content_policy", () => {
-  assert.equal(
-    classifyStderr("This request violates our usage policies and was blocked."),
-    "content_policy"
-  );
-  assert.equal(classifyStderr("Your request was flagged by the safety system"), "content_policy");
-});
-
-test("classifyStderr: 429 / overloaded family via rate-guard fallthrough", () => {
-  assert.equal(classifyStderr("HTTP 429 Too Many Requests"), "rate_limit");
-  assert.equal(classifyStderr("rate_limit_error: slow down"), "rate_limit");
-  assert.equal(classifyStderr("Error 529: Overloaded, try again"), "overloaded");
-});
-
-test("classifyStderr: auth / billing / network signals", () => {
-  assert.equal(classifyStderr("invalid api key provided"), "auth");
-  assert.equal(classifyStderr("Your credit balance is too low to run this"), "billing");
-  assert.equal(classifyStderr("getaddrinfo ENOTFOUND api.anthropic.com"), "network");
-});
-
-test("classifyStderr: overflow wins over a co-occurring 429 string", () => {
-  assert.equal(
-    classifyStderr("429 rate limit — but also: prompt is too long"),
-    "context_overflow"
-  );
-});
-
-test("classifyStderr: nothing matches → null", () => {
-  assert.equal(classifyStderr("the model produced a normal answer"), null);
-  assert.equal(classifyStderr(""), null);
-  assert.equal(classifyStderr(null), null);
-});
-
-// ---------------------------------------------------------------------------
-// 4. HTTP classifier
-// ---------------------------------------------------------------------------
-
-test("classifyHttp: canonical status codes", () => {
-  assert.equal(classifyHttp(401, {}), "auth");
-  assert.equal(classifyHttp(403, {}), "auth");
-  assert.equal(classifyHttp(402, {}), "billing");
-  assert.equal(classifyHttp(413, {}), "payload_too_large");
-  assert.equal(classifyHttp(429, {}), "rate_limit");
-  assert.equal(classifyHttp(500, {}), "server_error");
-  assert.equal(classifyHttp(502, {}), "server_error");
-  assert.equal(classifyHttp(503, {}), "overloaded");
-  assert.equal(classifyHttp(529, {}), "overloaded");
-});
-
-test("classifyHttp: billing vs rate_limit disambiguation", () => {
-  // 403 "key limit exceeded" is billing, not auth.
-  assert.equal(
-    classifyHttp(403, { error: { message: "Key limit exceeded for your account" } }),
-    "billing"
-  );
-  // 402 with a transient "try again in" signal is rate_limit, not billing.
-  assert.equal(
-    classifyHttp(402, { error: { message: "Usage limit reached, try again in 5 minutes" } }),
-    "rate_limit"
-  );
-  // 402 confirmed exhaustion is billing.
-  assert.equal(
-    classifyHttp(402, { error: { message: "Your credit balance is too low" } }),
-    "billing"
-  );
-});
-
-test("classifyHttp: 404 model-not-found vs generic vs billing", () => {
-  assert.equal(
-    classifyHttp(404, { error: { message: "The model `kimi-k99` does not exist" } }),
-    "model_not_found"
-  );
-  assert.equal(classifyHttp(404, { error: { message: "Not Found" } }), "unknown");
-  assert.equal(
-    classifyHttp(404, { error: { message: "credits have been exhausted" } }),
-    "billing"
-  );
-});
-
-test("classifyHttp: 400 refinement (context_overflow, format, model_not_found)", () => {
-  assert.equal(
-    classifyHttp(400, { error: { message: "This model's maximum context length is 200000 tokens" } }),
-    "context_overflow"
-  );
-  // "max_tokens" appears in both context + validation lists; the validation
-  // guard must win so it's a format error, not a misrouted overflow.
-  assert.equal(
-    classifyHttp(400, { error: { message: "Unsupported parameter: max_tokens is not supported" } }),
-    "format"
-  );
-  assert.equal(
-    classifyHttp(400, { error: { message: "invalid model specified" } }),
-    "model_not_found"
-  );
-  assert.equal(classifyHttp(400, { error: { message: "totally malformed" } }), "format");
-});
-
-test("classifyHttp: content_policy and provider_policy override status", () => {
-  assert.equal(
-    classifyHttp(400, { error: { message: "Your request was flagged by our safety system" } }),
-    "content_policy"
-  );
-  assert.equal(
-    classifyHttp(404, {
-      error: {
-        message: "No endpoints available matching your data policy. Configure privacy.",
-      },
-    }),
-    "provider_policy"
-  );
-});
-
-test("classifyHttp: OpenRouter nested metadata.raw unwrap", () => {
-  const body = {
-    error: {
-      message: "Provider returned error",
-      metadata: {
-        raw: JSON.stringify({ error: { message: "context length exceeded" } }),
-      },
-    },
-  };
-  // 200/unknown status but the real signal is inside metadata.raw.
-  assert.equal(classifyHttp(400, body), "context_overflow");
-});
-
-test("flattenHttpBody: unwraps metadata.raw and pulls codes", () => {
-  const { text, code } = flattenHttpBody({
-    error: {
-      code: "rate_limit_exceeded",
-      message: "Provider returned error",
-      metadata: { raw: JSON.stringify({ error: { message: "too many requests" } }) },
-    },
-  });
-  assert.match(text, /too many requests/);
-  assert.equal(code, "rate_limit_exceeded");
-});
-
-test("classifyHttp: structured error codes", () => {
-  assert.equal(classifyHttp(400, { error: { code: "context_length_exceeded" } }), "context_overflow");
-  assert.equal(classifyHttp(429, { error: { code: "resource_exhausted" } }), "rate_limit");
-  assert.equal(classifyHttp(402, { error: { code: "insufficient_quota" } }), "billing");
-  assert.equal(classifyHttp(404, { error: { code: "model_not_found" } }), "model_not_found");
-});
-
-test("classifyHttp: string body and transport-only (no status)", () => {
-  assert.equal(classifyHttp(null, "fetch failed: ECONNREFUSED"), "network");
-  assert.equal(classifyHttp(null, "request timed out after 60s"), "timeout");
-  assert.equal(classifyHttp(null, "received an empty response from the model"), "empty_response");
-  assert.equal(classifyHttp(null, "rate limit exceeded"), "rate_limit");
-  assert.equal(classifyHttp(undefined, null), "unknown");
-});
-
-test("classifyHttp: 5xx with request-validation body fails fast as format", () => {
-  assert.equal(
-    classifyHttp(502, { error: { message: "Unknown parameter: reasoning_effort" } }),
-    "format"
-  );
-  assert.equal(classifyHttp(500, { error: { code: "invalid_request_error" } }), "format");
-});
-
-test("classifyTransportError: node fetch/dns/abort codes", () => {
-  assert.equal(classifyTransportError({ code: "ENOTFOUND" }), "network");
-  assert.equal(classifyTransportError({ code: "ECONNREFUSED" }), "network");
-  assert.equal(classifyTransportError({ code: "ETIMEDOUT" }), "timeout");
-  assert.equal(classifyTransportError({ name: "AbortError" }), "timeout");
-  assert.equal(classifyTransportError({ name: "TimeoutError" }), "timeout");
-  assert.equal(
-    classifyTransportError({ code: "UND_ERR_CONNECT_TIMEOUT", message: "connect timeout" }),
-    "timeout"
-  );
-  assert.equal(classifyTransportError(new Error("socket hang up")), "network");
-  assert.equal(classifyTransportError(new Error("???")), "unknown");
-  assert.equal(classifyTransportError(null), "unknown");
-});
-
-test("classifiers never throw on adversarial input", () => {
-  const junk = [undefined, null, 0, {}, [], NaN, Symbol.iterator];
-  for (const j of junk) {
-    assert.doesNotThrow(() => classifyCliEvent(j));
-    assert.doesNotThrow(() => classifyResultSubtype(j));
-    assert.doesNotThrow(() => classifyStderr(j));
-    assert.doesNotThrow(() => classifyHttp(j, j));
-    assert.doesNotThrow(() => classifyTransportError(j));
-  }
-});