@coool/opencode-adaptive 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @coool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @coool/opencode-adaptive
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Automatic model fallback and routing for [OpenCode](https://opencode.ai).
+
+You list your models in order of preference. Adaptive runs each task on the first one that works. When a model hits a quota, rate limit or outage, work moves to the next one. When the preferred model is back, it is used again.
+
+It is set up entirely from the `/adaptive` menu in OpenCode. There are no config files to edit and no model IDs to type.
+
+## What you can do with it
+
+**Use subscriptions first, pay-as-you-go second.** Put your subscription models at the top of the list and an API provider such as OpenRouter at the bottom. You get the most out of what you already pay for. The API only takes over when the subscriptions are out of quota, and the subscriptions are used again as soon as they reset.
+
+**Use cheap models for small work.** Keep separate lists for quick, standard and advanced work. Typo fixes don't need your strongest model.
+
+**Leave long runs unattended.** If a model fails mid-task, work continues on the next ready model in the tier, and the preferred model is used again at the next task — finished tool calls are not repeated, even across an OpenCode restart. A `/goal` run is a series of tasks, so it carries on by itself.
+
+## Features
+
+- **Menu setup.** Models, order and mode are set in `/adaptive` with model search. No config files.
+- **Tiers.** Quick, standard and advanced work each get their own list, and a failure stays inside the tier the work needs. The agent can ask for a tier with the `adaptive_tier` tool. Routing follows fixed rules, not a prompt the model may or may not obey.
+- **Quota awareness.** It reads usage from provider response headers. When a subscription is nearly used up (about 10% left), new tasks go to the next ready model in the tier, and it is used again after the reset time when the provider reports one.
+- **Recovery that survives a restart.** If work is interrupted and cannot continue right away because no model in its tier is ready, it is saved and resumes when one returns — even after an OpenCode restart, without repeating finished tool calls.
+- **Dry run.** In `observe` mode it records what it would have done, with the reason, before it changes anything. A session can have its own mode.
+- **Escalation on evidence only.** An outage never sends work to a more expensive tier. Moving up needs a context overflow, a policy rejection, or an explicit request from the agent.
+
+## Install
+
+```sh
+opencode plugin add @coool/opencode-adaptive
+```
+
+Needs OpenCode 2.2.1 or newer.
+
+## Set up
+
+1. Start OpenCode and run `/adaptive`.
+2. Open **Models**, pick a tier, and choose **Add model…**. Search for a model and select it. Repeat, best first. If the tier a task needs is empty, OpenCode's own model runs it.
+3. Open **Mode** and choose `active`.
+
+New installs start in `observe` mode: Adaptive records what it would do but changes nothing. Look at **Receipts** to check its decisions, then switch to `active`.
+
+| Mode      | What happens                                                           |
+| --------- | ---------------------------------------------------------------------- |
+| `off`     | Nothing.                                                               |
+| `observe` | Decisions are recorded, not applied. This is the default.              |
+| `active`  | Decisions are applied. A task changes model only when its model fails. |
+
+Any session can override the global mode: open `/adaptive` inside the session and choose **This session…**.
+
+To reorder or remove a model, select it in the tier list. **Status** shows each model's state, including subscription usage (`used 72%, resets 18:42`) when the provider reports it.
+
+## Tiers
+
+A tier is an ordered list of models. The order is your policy, and Adaptive never changes it.
+
+- **Quick** for small, mechanical work.
+- **Standard** for everything else. This is the default.
+- **Advanced** for hard work.
+
+A model can be in more than one tier.
+
+The tier for a task is the first of these that applies:
+
+1. A pinned model (`/adaptive` → **Pin**).
+2. A tier request for the session: the agent can declare one with the `adaptive_tier` tool, or you set it inside a session with `/adaptive` → **Tier**.
+3. A per-agent tier from the `agentTiers` setting (RPC only).
+4. `standard`.
+
+Background requests such as titles and summaries are observed but not routed separately in v1 — they keep OpenCode's own model.
+
+No language model or keyword matching is involved. A model is skipped if it is unknown or can't fit the context, and the receipt says why. Adaptive only uses models you added.
+
+## When a model fails
+
+- **Rate limit, quota, timeout, outage:** if the error is clear-cut and another model in the same tier is ready, the task switches to it and carries on from the current session. Your prompt is not resent and finished tool calls are not repeated. If the error is unclear or no other model is ready, OpenCode's normal retry continues.
+- **A model fails repeatedly:** it is paused for a cooldown, then tried once. If that works, it is back.
+- **Every model in the tier is blocked as a task starts:** OpenCode's own model runs it, and the decision is recorded as a receipt with the reason. A task that fails to recover is saved and resumes when a model returns.
+- **You cancel:** nothing is retried or switched.
+- **Auth error or unknown model:** the model is marked unavailable and skipped.
+
+An outage never moves work to a stronger tier. Work only moves up on real evidence: a context overflow, a content-policy rejection, or the agent calling `adaptive_escalate` with a reason and evidence. This happens at most twice per task.
+
+## Limits
+
+- No borrowing between tiers. If a tier is exhausted, the task runs on OpenCode's own model rather than another tier's models. To let a model serve two tiers, add it to both.
+- A task that moved up a tier stays there. The next task is routed again from scratch.
+- Usage figures come from response headers and are best effort. Providers that use WebSockets don't expose them.
+- The browser/desktop settings page is experimental. No released OpenCode loads it yet, so use `/adaptive`.
+
+## Troubleshooting
+
+- **Nothing changes.** You are in `observe` mode. Switch to `active` in `/adaptive` → **Mode**.
+- **A model is never picked.** Its provider must be connected in OpenCode.
+- **Receipts show `park` on a new task.** Every model in its tier was blocked when the task started, so it ran on OpenCode's own model. The receipt says why; check `/adaptive` → **Status** for cooldowns.
+- **Why did it pick that model?** `/adaptive` → **Receipts**.
+- **"Plugin failed" toast.** The plugin didn't load. Update it with `opencode plugin update`, or remove and add it again.
+
+## Privacy
+
+Nothing leaves your machine. No telemetry, no network calls of its own, no secrets in settings, receipts or logs. Receipts keep the newest 200 entries and are never added to prompts.

package/dist/adapters/codex-capacity/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./parse.js";
+export * from "./reading.js";
+export * from "./sensor.js";

package/dist/adapters/codex-capacity/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./parse.js";
+export * from "./reading.js";
+export * from "./sensor.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/codex-capacity/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/codex-capacity/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA","sourcesContent":["export * from \"./types.js\"\nexport * from \"./parse.js\"\nexport * from \"./reading.js\"\nexport * from \"./sensor.js\"\n"]}

package/dist/adapters/codex-capacity/parse.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Untrusted-header validation. Header values arrive from provider responses
+ * (or relays); every field is parsed defensively and a window is admitted only
+ * when its usage percentage is trustworthy. A usage above 100% voids the
+ * snapshot rather than leaving the other window to speak for it. Reset fields that fail validation
+ * are dropped field-wise — they cannot invalidate a valid percentage.
+ */
+import type { CodexUsage } from "./types.js";
+/**
+ * LiteLLM relays Codex headers under a provider prefix, e.g.
+ * `llm_provider-x-codex-primary-used-percent`. Matching on the substring keeps
+ * the parser independent of which relay prefix is used.
+ */
+export declare const CODEX_HEADER_MARK = "x-codex-";
+/**
+ * Allowlist predicate for the `http.response` capture option: matches plain
+ * and LiteLLM-prefixed Codex telemetry header names (case already lowered by
+ * the caller). Only quota telemetry passes — no other response header is ever
+ * captured.
+ */
+export declare function isCodexHeaderName(lowercaseName: string): boolean;
+/**
+ * Parse captured response headers into a validated usage snapshot. Header
+ * lookup is case-insensitive and accepts LiteLLM-prefixed names; fields
+ * accumulate per window in any order. Returns `null` when no window carries a
+ * trustworthy usage percentage.
+ */
+export declare function parseCodexUsage(captured: Readonly<Record<string, string>>): CodexUsage | null;

package/dist/adapters/codex-capacity/parse.js

@@ -0,0 +1,146 @@
+import { CODEX_WINDOW_KINDS } from "./types.js";
+/**
+ * LiteLLM relays Codex headers under a provider prefix, e.g.
+ * `llm_provider-x-codex-primary-used-percent`. Matching on the substring keeps
+ * the parser independent of which relay prefix is used.
+ */
+export const CODEX_HEADER_MARK = "x-codex-";
+/**
+ * Allowlist predicate for the `http.response` capture option: matches plain
+ * and LiteLLM-prefixed Codex telemetry header names (case already lowered by
+ * the caller). Only quota telemetry passes — no other response header is ever
+ * captured.
+ */
+export function isCodexHeaderName(lowercaseName) {
+    return lowercaseName.includes(CODEX_HEADER_MARK);
+}
+function finiteAtLeast(value, min) {
+    // An empty (or whitespace-only) value must not fall through Number("") === 0.
+    const trimmed = value.trim();
+    if (trimmed === "") {
+        return undefined;
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed) || parsed < min) {
+        return undefined;
+    }
+    return parsed;
+}
+function emptyAccumulator() {
+    return {
+        usedPercent: undefined,
+        overshoot: undefined,
+        resetAfterSeconds: undefined,
+        resetAtSeconds: undefined,
+    };
+}
+function takenValue(accumulator, suffix) {
+    switch (suffix) {
+        case "used-percent":
+            return accumulator.usedPercent;
+        case "reset-after-seconds":
+            return accumulator.resetAfterSeconds;
+        case "reset-at":
+            return accumulator.resetAtSeconds;
+        default:
+            return undefined;
+    }
+}
+function applyField(accumulator, suffix, value) {
+    // First valid value per field wins; invalid or duplicate values are ignored.
+    if (takenValue(accumulator, suffix) !== undefined) {
+        return;
+    }
+    switch (suffix) {
+        case "used-percent": {
+            // The percentage is the window's existence test: out of range or
+            // unparseable values never admit a window.
+            const usedPercent = finiteAtLeast(value, 0);
+            if (usedPercent === undefined) {
+                return;
+            }
+            if (usedPercent > 100) {
+                accumulator.overshoot = true;
+                return;
+            }
+            accumulator.usedPercent = usedPercent;
+            return;
+        }
+        case "reset-after-seconds": {
+            const resetAfterSeconds = finiteAtLeast(value, 0);
+            if (resetAfterSeconds !== undefined) {
+                accumulator.resetAfterSeconds = resetAfterSeconds;
+            }
+            return;
+        }
+        case "reset-at": {
+            // Documented wire quirk: reset-at can be an empty string while
+            // reset-after-seconds carries the real value. Empty and unparseable
+            // values are dropped, never guessed at.
+            const resetAtSeconds = finiteAtLeast(value, 0);
+            if (resetAtSeconds !== undefined) {
+                accumulator.resetAtSeconds = resetAtSeconds;
+            }
+            return;
+        }
+        default:
+            // window-minutes and unknown suffixes carry no reading information.
+            return;
+    }
+}
+function windowOf(accumulator) {
+    const usedPercent = accumulator.usedPercent;
+    if (usedPercent === undefined) {
+        return undefined;
+    }
+    const { resetAfterSeconds, resetAtSeconds } = accumulator;
+    return {
+        usedPercent,
+        ...(resetAfterSeconds !== undefined ? { resetAfterSeconds } : {}),
+        ...(resetAtSeconds !== undefined ? { resetAtSeconds } : {}),
+    };
+}
+/**
+ * Parse captured response headers into a validated usage snapshot. Header
+ * lookup is case-insensitive and accepts LiteLLM-prefixed names; fields
+ * accumulate per window in any order. Returns `null` when no window carries a
+ * trustworthy usage percentage.
+ */
+export function parseCodexUsage(captured) {
+    const accumulators = {
+        primary: undefined,
+        secondary: undefined,
+    };
+    for (const [rawName, value] of Object.entries(captured)) {
+        const mark = rawName.toLowerCase().indexOf(CODEX_HEADER_MARK);
+        if (mark < 0) {
+            continue;
+        }
+        const rest = rawName.slice(mark + CODEX_HEADER_MARK.length).toLowerCase();
+        const separator = rest.indexOf("-");
+        const kind = rest.slice(0, separator);
+        if (!CODEX_WINDOW_KINDS.includes(kind)) {
+            continue;
+        }
+        const key = kind;
+        const accumulator = accumulators[key] ?? emptyAccumulator();
+        applyField(accumulator, rest.slice(separator + 1), value);
+        accumulators[key] = accumulator;
+    }
+    // An overshooting window is exhausted, yet its percentage is not
+    // trustworthy: dropping just that window would let the other one present
+    // the subscription as usable, so the whole snapshot is void.
+    if (accumulators.primary?.overshoot === true || accumulators.secondary?.overshoot === true) {
+        return null;
+    }
+    const primary = windowOf(accumulators.primary ?? emptyAccumulator());
+    const secondary = windowOf(accumulators.secondary ?? emptyAccumulator());
+    if (primary === undefined && secondary === undefined) {
+        return null;
+    }
+    return {
+        ...(primary !== undefined ? { primary } : {}),
+        ...(secondary !== undefined ? { secondary } : {}),
+    };
+}
+//# sourceMappingURL=parse.js.map

package/dist/adapters/codex-capacity/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/adapters/codex-capacity/parse.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Untrusted-header validation. Header values arrive from provider responses\n * (or relays); every field is parsed defensively and a window is admitted only\n * when its usage percentage is trustworthy. A usage above 100% voids the\n * snapshot rather than leaving the other window to speak for it. Reset fields that fail validation\n * are dropped field-wise — they cannot invalidate a valid percentage.\n */\nimport type { CodexUsage, CodexWindow, CodexWindowKind } from \"./types.js\"\nimport { CODEX_WINDOW_KINDS } from \"./types.js\"\n\n/**\n * LiteLLM relays Codex headers under a provider prefix, e.g.\n * `llm_provider-x-codex-primary-used-percent`. Matching on the substring keeps\n * the parser independent of which relay prefix is used.\n */\nexport const CODEX_HEADER_MARK = \"x-codex-\"\n\n/**\n * Allowlist predicate for the `http.response` capture option: matches plain\n * and LiteLLM-prefixed Codex telemetry header names (case already lowered by\n * the caller). Only quota telemetry passes — no other response header is ever\n * captured.\n */\nexport function isCodexHeaderName(lowercaseName: string): boolean {\n  return lowercaseName.includes(CODEX_HEADER_MARK)\n}\n\ninterface WindowAccumulator {\n  usedPercent?: number | undefined\n  /** A usage above 100% was reported: the window is exhausted, not absent. */\n  overshoot?: boolean | undefined\n  resetAfterSeconds?: number | undefined\n  resetAtSeconds?: number | undefined\n}\n\nfunction finiteAtLeast(value: string, min: number): number | undefined {\n  // An empty (or whitespace-only) value must not fall through Number(\"\") === 0.\n  const trimmed = value.trim()\n  if (trimmed === \"\") {\n    return undefined\n  }\n  const parsed = Number(trimmed)\n  if (!Number.isFinite(parsed) || parsed < min) {\n    return undefined\n  }\n  return parsed\n}\n\nfunction emptyAccumulator(): WindowAccumulator {\n  return {\n    usedPercent: undefined,\n    overshoot: undefined,\n    resetAfterSeconds: undefined,\n    resetAtSeconds: undefined,\n  }\n}\n\nfunction takenValue(accumulator: WindowAccumulator, suffix: string): number | undefined {\n  switch (suffix) {\n    case \"used-percent\":\n      return accumulator.usedPercent\n    case \"reset-after-seconds\":\n      return accumulator.resetAfterSeconds\n    case \"reset-at\":\n      return accumulator.resetAtSeconds\n    default:\n      return undefined\n  }\n}\n\nfunction applyField(accumulator: WindowAccumulator, suffix: string, value: string): void {\n  // First valid value per field wins; invalid or duplicate values are ignored.\n  if (takenValue(accumulator, suffix) !== undefined) {\n    return\n  }\n  switch (suffix) {\n    case \"used-percent\": {\n      // The percentage is the window's existence test: out of range or\n      // unparseable values never admit a window.\n      const usedPercent = finiteAtLeast(value, 0)\n      if (usedPercent === undefined) {\n        return\n      }\n      if (usedPercent > 100) {\n        accumulator.overshoot = true\n        return\n      }\n      accumulator.usedPercent = usedPercent\n      return\n    }\n    case \"reset-after-seconds\": {\n      const resetAfterSeconds = finiteAtLeast(value, 0)\n      if (resetAfterSeconds !== undefined) {\n        accumulator.resetAfterSeconds = resetAfterSeconds\n      }\n      return\n    }\n    case \"reset-at\": {\n      // Documented wire quirk: reset-at can be an empty string while\n      // reset-after-seconds carries the real value. Empty and unparseable\n      // values are dropped, never guessed at.\n      const resetAtSeconds = finiteAtLeast(value, 0)\n      if (resetAtSeconds !== undefined) {\n        accumulator.resetAtSeconds = resetAtSeconds\n      }\n      return\n    }\n    default:\n      // window-minutes and unknown suffixes carry no reading information.\n      return\n  }\n}\n\nfunction windowOf(accumulator: WindowAccumulator): CodexWindow | undefined {\n  const usedPercent = accumulator.usedPercent\n  if (usedPercent === undefined) {\n    return undefined\n  }\n  const { resetAfterSeconds, resetAtSeconds } = accumulator\n  return {\n    usedPercent,\n    ...(resetAfterSeconds !== undefined ? { resetAfterSeconds } : {}),\n    ...(resetAtSeconds !== undefined ? { resetAtSeconds } : {}),\n  }\n}\n\n/**\n * Parse captured response headers into a validated usage snapshot. Header\n * lookup is case-insensitive and accepts LiteLLM-prefixed names; fields\n * accumulate per window in any order. Returns `null` when no window carries a\n * trustworthy usage percentage.\n */\nexport function parseCodexUsage(captured: Readonly<Record<string, string>>): CodexUsage | null {\n  const accumulators: Record<CodexWindowKind, WindowAccumulator | undefined> = {\n    primary: undefined,\n    secondary: undefined,\n  }\n  for (const [rawName, value] of Object.entries(captured)) {\n    const mark = rawName.toLowerCase().indexOf(CODEX_HEADER_MARK)\n    if (mark < 0) {\n      continue\n    }\n    const rest = rawName.slice(mark + CODEX_HEADER_MARK.length).toLowerCase()\n    const separator = rest.indexOf(\"-\")\n    const kind = rest.slice(0, separator)\n    if (!(CODEX_WINDOW_KINDS as readonly string[]).includes(kind)) {\n      continue\n    }\n    const key = kind as CodexWindowKind\n    const accumulator = accumulators[key] ?? emptyAccumulator()\n    applyField(accumulator, rest.slice(separator + 1), value)\n    accumulators[key] = accumulator\n  }\n  // An overshooting window is exhausted, yet its percentage is not\n  // trustworthy: dropping just that window would let the other one present\n  // the subscription as usable, so the whole snapshot is void.\n  if (accumulators.primary?.overshoot === true || accumulators.secondary?.overshoot === true) {\n    return null\n  }\n  const primary = windowOf(accumulators.primary ?? emptyAccumulator())\n  const secondary = windowOf(accumulators.secondary ?? emptyAccumulator())\n  if (primary === undefined && secondary === undefined) {\n    return null\n  }\n  return {\n    ...(primary !== undefined ? { primary } : {}),\n    ...(secondary !== undefined ? { secondary } : {}),\n  }\n}\n"]}

package/dist/adapters/codex-capacity/reading.d.ts

@@ -0,0 +1,9 @@
+import type { CapacityReading } from "../../health/capacity/types.js";
+import type { CodexUsage, CodexWindow } from "./types.js";
+export declare const CODEX_EVIDENCE = "x-codex headers";
+/**
+ * The window whose exhaustion binds first: higher usage wins, ties → primary.
+ * Returns `undefined` only for a snapshot with no window at all.
+ */
+export declare function bindingWindow(usage: CodexUsage): CodexWindow | undefined;
+export declare function readingFromUsage(usage: CodexUsage, observedAt: number): CapacityReading;

package/dist/adapters/codex-capacity/reading.js

@@ -0,0 +1,45 @@
+export const CODEX_EVIDENCE = "x-codex headers";
+function hasReset(window) {
+    return window.resetAfterSeconds !== undefined || window.resetAtSeconds !== undefined;
+}
+/**
+ * The window whose exhaustion binds first: higher usage wins, ties → primary.
+ * Returns `undefined` only for a snapshot with no window at all.
+ */
+export function bindingWindow(usage) {
+    const primary = usage.primary;
+    const secondary = usage.secondary;
+    if (primary === undefined) {
+        return secondary;
+    }
+    if (secondary === undefined) {
+        return primary;
+    }
+    return secondary.usedPercent > primary.usedPercent ? secondary : primary;
+}
+export function readingFromUsage(usage, observedAt) {
+    const window = bindingWindow(usage);
+    if (window === undefined) {
+        // No measured field — the capacity merge layer rejects this as noise.
+        return { confidence: "low", observedAt, evidence: CODEX_EVIDENCE };
+    }
+    const usedRatio = window.usedPercent / 100;
+    const remainingRatio = 1 - usedRatio;
+    let resetAt;
+    if (window.resetAfterSeconds !== undefined) {
+        resetAt = observedAt + window.resetAfterSeconds * 1000;
+    }
+    else if (window.resetAtSeconds !== undefined) {
+        resetAt = window.resetAtSeconds * 1000;
+    }
+    const confidence = hasReset(window) ? "high" : "medium";
+    return {
+        usedRatio,
+        remainingRatio,
+        ...(resetAt !== undefined ? { resetAt } : {}),
+        confidence,
+        observedAt,
+        evidence: CODEX_EVIDENCE,
+    };
+}
+//# sourceMappingURL=reading.js.map

package/dist/adapters/codex-capacity/reading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reading.js","sourceRoot":"","sources":["../../../src/adapters/codex-capacity/reading.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,cAAc,GAAG,iBAAiB,CAAA;AAE/C,SAAS,QAAQ,CAAC,MAAmB;IACnC,OAAO,MAAM,CAAC,iBAAiB,KAAK,SAAS,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,CAAA;AACtF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAA;IAC7B,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAA;IACjC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,OAAO,CAAA;IAChB,CAAC;IACD,OAAO,SAAS,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAA;AAC1E,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAiB,EAAE,UAAkB;IACpE,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAA;IACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,sEAAsE;QACtE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAA;IACpE,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,GAAG,GAAG,CAAA;IAC1C,MAAM,cAAc,GAAG,CAAC,GAAG,SAAS,CAAA;IACpC,IAAI,OAA2B,CAAA;IAC/B,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC3C,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC,iBAAiB,GAAG,IAAI,CAAA;IACxD,CAAC;SAAM,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QAC/C,OAAO,GAAG,MAAM,CAAC,cAAc,GAAG,IAAI,CAAA;IACxC,CAAC;IACD,MAAM,UAAU,GAAe,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAA;IACnE,OAAO;QACL,SAAS;QACT,cAAc;QACd,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,UAAU;QACV,UAAU;QACV,QAAQ,EAAE,cAAc;KACzB,CAAA;AACH,CAAC","sourcesContent":["/**\n * Codex usage → `CapacityReading` conversion. The binding constraint is the\n * most-consumed window (ties read the primary window, deterministic). Ratios\n * are exact percent/100 fractions; the reset timestamp is anchored to when the\n * headers were observed, preferring the relative `reset-after-seconds` over\n * the absolute `reset-at` epoch-seconds field.\n *\n * Confidence grades telemetry completeness: a binding window with BOTH a\n * usage percentage and a validated reset field is `high` (self-consistent,\n * provider-generated, actionable for draining); a percentage alone is\n * `medium`. An usage snapshot with no window at all yields a no-measurement\n * reading that the capacity merge layer discards as pure noise.\n */\nimport type { Confidence } from \"../../health/capacity/types.js\"\nimport type { CapacityReading } from \"../../health/capacity/types.js\"\nimport type { CodexUsage, CodexWindow } from \"./types.js\"\n\nexport const CODEX_EVIDENCE = \"x-codex headers\"\n\nfunction hasReset(window: CodexWindow): boolean {\n  return window.resetAfterSeconds !== undefined || window.resetAtSeconds !== undefined\n}\n\n/**\n * The window whose exhaustion binds first: higher usage wins, ties → primary.\n * Returns `undefined` only for a snapshot with no window at all.\n */\nexport function bindingWindow(usage: CodexUsage): CodexWindow | undefined {\n  const primary = usage.primary\n  const secondary = usage.secondary\n  if (primary === undefined) {\n    return secondary\n  }\n  if (secondary === undefined) {\n    return primary\n  }\n  return secondary.usedPercent > primary.usedPercent ? secondary : primary\n}\n\nexport function readingFromUsage(usage: CodexUsage, observedAt: number): CapacityReading {\n  const window = bindingWindow(usage)\n  if (window === undefined) {\n    // No measured field — the capacity merge layer rejects this as noise.\n    return { confidence: \"low\", observedAt, evidence: CODEX_EVIDENCE }\n  }\n  const usedRatio = window.usedPercent / 100\n  const remainingRatio = 1 - usedRatio\n  let resetAt: number | undefined\n  if (window.resetAfterSeconds !== undefined) {\n    resetAt = observedAt + window.resetAfterSeconds * 1000\n  } else if (window.resetAtSeconds !== undefined) {\n    resetAt = window.resetAtSeconds * 1000\n  }\n  const confidence: Confidence = hasReset(window) ? \"high\" : \"medium\"\n  return {\n    usedRatio,\n    remainingRatio,\n    ...(resetAt !== undefined ? { resetAt } : {}),\n    confidence,\n    observedAt,\n    evidence: CODEX_EVIDENCE,\n  }\n}\n"]}

package/dist/adapters/codex-capacity/sensor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The passive-header `CapacitySensor` (ADP-020). Holds the latest validated
+ * header observation; `read()` converts it to a reading. No polling, no
+ * endpoint calls, no credential handling — WebSocket-backed providers bypass
+ * the HTTP hook entirely (verified limitation), so this sensor reports
+ * `null` (no estimate) whenever no trustworthy headers have been observed.
+ * An unparseable observation CLEARS the stored usage: present-but-invalid
+ * telemetry is distrust, and a stale quota estimate must never linger.
+ */
+import type { ResourceKey } from "../../health/resource-health/types.js";
+import type { CapacityReading, CapacitySensor } from "../../health/capacity/types.js";
+export declare class CodexCapacitySensor implements CapacitySensor {
+    #private;
+    readonly id = "codex-headers";
+    readonly resource: ResourceKey;
+    constructor(resource: ResourceKey);
+    /**
+     * Record one captured-header observation. Unparseable telemetry clears the
+     * previous estimate instead of keeping it (present-but-invalid = distrust).
+     */
+    observe(captured: Readonly<Record<string, string>>, observedAt: number): void;
+    read(): Promise<CapacityReading | null>;
+}

package/dist/adapters/codex-capacity/sensor.js

@@ -0,0 +1,30 @@
+import { parseCodexUsage } from "./parse.js";
+import { readingFromUsage } from "./reading.js";
+import { CODEX_SENSOR_ID } from "./types.js";
+export class CodexCapacitySensor {
+    id = CODEX_SENSOR_ID;
+    resource;
+    #usage = null;
+    #observedAt = 0;
+    constructor(resource) {
+        this.resource = resource;
+    }
+    /**
+     * Record one captured-header observation. Unparseable telemetry clears the
+     * previous estimate instead of keeping it (present-but-invalid = distrust).
+     */
+    observe(captured, observedAt) {
+        this.#usage = parseCodexUsage(captured);
+        if (this.#usage !== null) {
+            this.#observedAt = observedAt;
+        }
+    }
+    read() {
+        const usage = this.#usage;
+        if (usage === null) {
+            return Promise.resolve(null);
+        }
+        return Promise.resolve(readingFromUsage(usage, this.#observedAt));
+    }
+}
+//# sourceMappingURL=sensor.js.map

package/dist/adapters/codex-capacity/sensor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensor.js","sourceRoot":"","sources":["../../../src/adapters/codex-capacity/sensor.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE5C,MAAM,OAAO,mBAAmB;IACrB,EAAE,GAAG,eAAe,CAAA;IACpB,QAAQ,CAAa;IAC9B,MAAM,GAAsB,IAAI,CAAA;IAChC,WAAW,GAAG,CAAC,CAAA;IAEf,YAAY,QAAqB;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,QAA0C,EAAE,UAAkB;QACpE,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;QACvC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACzB,IAAI,CAAC,WAAW,GAAG,UAAU,CAAA;QAC/B,CAAC;IACH,CAAC;IAED,IAAI;QACF,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAC9B,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAA;IACnE,CAAC;CACF","sourcesContent":["/**\n * The passive-header `CapacitySensor` (ADP-020). Holds the latest validated\n * header observation; `read()` converts it to a reading. No polling, no\n * endpoint calls, no credential handling — WebSocket-backed providers bypass\n * the HTTP hook entirely (verified limitation), so this sensor reports\n * `null` (no estimate) whenever no trustworthy headers have been observed.\n * An unparseable observation CLEARS the stored usage: present-but-invalid\n * telemetry is distrust, and a stale quota estimate must never linger.\n */\nimport type { ResourceKey } from \"../../health/resource-health/types.js\"\nimport type { CapacityReading, CapacitySensor } from \"../../health/capacity/types.js\"\nimport { parseCodexUsage } from \"./parse.js\"\nimport { readingFromUsage } from \"./reading.js\"\nimport type { CodexUsage } from \"./types.js\"\nimport { CODEX_SENSOR_ID } from \"./types.js\"\n\nexport class CodexCapacitySensor implements CapacitySensor {\n  readonly id = CODEX_SENSOR_ID\n  readonly resource: ResourceKey\n  #usage: CodexUsage | null = null\n  #observedAt = 0\n\n  constructor(resource: ResourceKey) {\n    this.resource = resource\n  }\n\n  /**\n   * Record one captured-header observation. Unparseable telemetry clears the\n   * previous estimate instead of keeping it (present-but-invalid = distrust).\n   */\n  observe(captured: Readonly<Record<string, string>>, observedAt: number): void {\n    this.#usage = parseCodexUsage(captured)\n    if (this.#usage !== null) {\n      this.#observedAt = observedAt\n    }\n  }\n\n  read(): Promise<CapacityReading | null> {\n    const usage = this.#usage\n    if (usage === null) {\n      return Promise.resolve(null)\n    }\n    return Promise.resolve(readingFromUsage(usage, this.#observedAt))\n  }\n}\n"]}

package/dist/adapters/codex-capacity/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Passive Codex/ChatGPT capacity telemetry (ADP-020).
+ *
+ * The only consumed evidence is the `x-codex-*` response-header family
+ * (including LiteLLM's `llm_provider-x-codex-*` relay form), captured from the
+ * `http.response` hook by the wiring-supplied allowlist. Verified wire facts:
+ * `x-codex-primary-used-percent` (5h window), `x-codex-secondary-used-percent`
+ * (weekly window), `x-codex-{primary,secondary}-window-minutes`,
+ * `x-codex-{primary,secondary}-reset-after-seconds`, and
+ * `x-codex-{primary,secondary}-reset-at` — where `reset-at` is documented to
+ * sometimes arrive as an EMPTY STRING while `reset-after-seconds` is present.
+ * Everything is validated; unparseable telemetry produces no estimate rather
+ * than a guess.
+ */
+export declare const CODEX_SENSOR_ID = "codex-headers";
+/** The telemetry windows Codex headers report. Primary is the 5h window. */
+export declare const CODEX_WINDOW_KINDS: readonly ["primary", "secondary"];
+export type CodexWindowKind = (typeof CODEX_WINDOW_KINDS)[number];
+export interface CodexWindow {
+    /** Usage percentage in [0, 100] — the window exists only if this is valid. */
+    readonly usedPercent: number;
+    /** Validated finite non-negative seconds until reset, when reported. */
+    readonly resetAfterSeconds?: number | undefined;
+    /** Validated finite non-negative epoch-seconds reset timestamp, when reported. */
+    readonly resetAtSeconds?: number | undefined;
+}
+/** One validated header observation. `null` windows are simply absent. */
+export interface CodexUsage {
+    readonly primary?: CodexWindow | undefined;
+    readonly secondary?: CodexWindow | undefined;
+}

package/dist/adapters/codex-capacity/types.js

@@ -0,0 +1,18 @@
+/**
+ * Passive Codex/ChatGPT capacity telemetry (ADP-020).
+ *
+ * The only consumed evidence is the `x-codex-*` response-header family
+ * (including LiteLLM's `llm_provider-x-codex-*` relay form), captured from the
+ * `http.response` hook by the wiring-supplied allowlist. Verified wire facts:
+ * `x-codex-primary-used-percent` (5h window), `x-codex-secondary-used-percent`
+ * (weekly window), `x-codex-{primary,secondary}-window-minutes`,
+ * `x-codex-{primary,secondary}-reset-after-seconds`, and
+ * `x-codex-{primary,secondary}-reset-at` — where `reset-at` is documented to
+ * sometimes arrive as an EMPTY STRING while `reset-after-seconds` is present.
+ * Everything is validated; unparseable telemetry produces no estimate rather
+ * than a guess.
+ */
+export const CODEX_SENSOR_ID = "codex-headers";
+/** The telemetry windows Codex headers report. Primary is the 5h window. */
+export const CODEX_WINDOW_KINDS = ["primary", "secondary"];
+//# sourceMappingURL=types.js.map

package/dist/adapters/codex-capacity/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/codex-capacity/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAA;AAE9C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,SAAS,EAAE,WAAW,CAAsC,CAAA","sourcesContent":["/**\n * Passive Codex/ChatGPT capacity telemetry (ADP-020).\n *\n * The only consumed evidence is the `x-codex-*` response-header family\n * (including LiteLLM's `llm_provider-x-codex-*` relay form), captured from the\n * `http.response` hook by the wiring-supplied allowlist. Verified wire facts:\n * `x-codex-primary-used-percent` (5h window), `x-codex-secondary-used-percent`\n * (weekly window), `x-codex-{primary,secondary}-window-minutes`,\n * `x-codex-{primary,secondary}-reset-after-seconds`, and\n * `x-codex-{primary,secondary}-reset-at` — where `reset-at` is documented to\n * sometimes arrive as an EMPTY STRING while `reset-after-seconds` is present.\n * Everything is validated; unparseable telemetry produces no estimate rather\n * than a guess.\n */\n\nexport const CODEX_SENSOR_ID = \"codex-headers\"\n\n/** The telemetry windows Codex headers report. Primary is the 5h window. */\nexport const CODEX_WINDOW_KINDS = [\"primary\", \"secondary\"] as const satisfies readonly string[]\n\nexport type CodexWindowKind = (typeof CODEX_WINDOW_KINDS)[number]\n\nexport interface CodexWindow {\n  /** Usage percentage in [0, 100] — the window exists only if this is valid. */\n  readonly usedPercent: number\n  /** Validated finite non-negative seconds until reset, when reported. */\n  readonly resetAfterSeconds?: number | undefined\n  /** Validated finite non-negative epoch-seconds reset timestamp, when reported. */\n  readonly resetAtSeconds?: number | undefined\n}\n\n/** One validated header observation. `null` windows are simply absent. */\nexport interface CodexUsage {\n  readonly primary?: CodexWindow | undefined\n  readonly secondary?: CodexWindow | undefined\n}\n"]}

package/dist/adapters/opencode/escalation-tool.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The typed escalation tool (T-18, ADP-015): the smallest Adaptive-owned
+ * mechanism for an agent to request stronger capability. The input schema is
+ * a plain JSON Schema — the host builds the model-facing tool definition by
+ * converting the schema, and a Standard Schema implementation is silently
+ * dropped ("Schema vendor does not support JSON Schema conversion", observed
+ * on 2.2.5). The tool also opts out of the host's code-mode bundling: with
+ * code mode enabled the host routes codemode-bundled tools through the
+ * `execute` tool only, and a direct call fails with "No tool named ... is
+ * currently available" (observed on 2.2.5). `execute` still re-validates
+ * defensively: model-produced JSON is untrusted. The tool is deliberately
+ * not a planning or task-management API.
+ */
+import { ESCALATION_TOOL_NAME } from "../../execution/escalation/index.js";
+export { ESCALATION_TOOL_NAME };
+/** Records the request against the session's current work unit. */
+export type EscalationRecorder = (sessionID: string, reason: string, evidence: string) => boolean;
+/** The tool's input schema in JSON Schema form (host-convertible). */
+declare const escalationInputSchema: {
+    type: string;
+    properties: {
+        reason: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        evidence: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+/** Keeps the tool directly callable when the host's code mode is enabled. */
+declare const escalationToolOptions: {
+    readonly codemode: false;
+};
+/** Build the plugin tool registration for the escalation request surface. */
+export declare function escalationTool(record: EscalationRecorder): {
+    name: typeof ESCALATION_TOOL_NAME;
+    description: string;
+    input: typeof escalationInputSchema;
+    options: typeof escalationToolOptions;
+    execute: (input: unknown, context: {
+        sessionID: string;
+    }) => Promise<{
+        content: string;
+    }>;
+};

package/dist/adapters/opencode/escalation-tool.js

@@ -0,0 +1,61 @@
+/**
+ * The typed escalation tool (T-18, ADP-015): the smallest Adaptive-owned
+ * mechanism for an agent to request stronger capability. The input schema is
+ * a plain JSON Schema — the host builds the model-facing tool definition by
+ * converting the schema, and a Standard Schema implementation is silently
+ * dropped ("Schema vendor does not support JSON Schema conversion", observed
+ * on 2.2.5). The tool also opts out of the host's code-mode bundling: with
+ * code mode enabled the host routes codemode-bundled tools through the
+ * `execute` tool only, and a direct call fails with "No tool named ... is
+ * currently available" (observed on 2.2.5). `execute` still re-validates
+ * defensively: model-produced JSON is untrusted. The tool is deliberately
+ * not a planning or task-management API.
+ */
+import { ESCALATION_TOOL_NAME, parseEscalationRequest } from "../../execution/escalation/index.js";
+export { ESCALATION_TOOL_NAME };
+const TOOL_DESCRIPTION = "Request stronger model capability for the current work unit. Provide a short reason and " +
+    "the concrete evidence (what failed or was blocked). Adaptive records the request as " +
+    "structured evidence and weighs it when a failure on this unit is already classified as a " +
+    "capability gap (for example context overflow or a content-policy rejection), within a " +
+    "finite budget; recording alone does not force a tier escalation. This is not a planning " +
+    "or task-management tool.";
+/** The tool's input schema in JSON Schema form (host-convertible). */
+const escalationInputSchema = {
+    type: "object",
+    properties: {
+        reason: {
+            type: "string",
+            minLength: 1,
+            description: "Short reason why the current work unit needs stronger capability.",
+        },
+        evidence: {
+            type: "string",
+            minLength: 1,
+            description: "Concrete evidence of the capability gap: what failed or was blocked.",
+        },
+    },
+    required: ["reason", "evidence"],
+    additionalProperties: false,
+};
+/** Keeps the tool directly callable when the host's code mode is enabled. */
+const escalationToolOptions = { codemode: false };
+/** Build the plugin tool registration for the escalation request surface. */
+export function escalationTool(record) {
+    return {
+        name: ESCALATION_TOOL_NAME,
+        description: TOOL_DESCRIPTION,
+        input: escalationInputSchema,
+        options: escalationToolOptions,
+        execute: (input, context) => {
+            const request = parseEscalationRequest(input);
+            if (request === undefined) {
+                return Promise.resolve({ content: "reason and evidence are required non-empty strings" });
+            }
+            const recorded = record(context.sessionID, request.reason, request.evidence);
+            return Promise.resolve(recorded
+                ? { content: "escalation request recorded for the current work unit" }
+                : { content: "no active work unit; the request was not recorded" });
+        },
+    };
+}
+//# sourceMappingURL=escalation-tool.js.map