scoutline 0.1.0 → 0.2.0

package/README.md

@@ -21,6 +21,7 @@
 - **Repo** - Search and read GitHub repository code via ZRead
 - **Tools** - MCP tool discovery, schemas, and raw calls
 - **Code Mode** - TypeScript tool chaining for agent automation
+- **Provider selection** - Run shared capabilities through Z.AI or MiniMax Token Plan
 
 ## Quick Start
 
@@ -32,7 +33,14 @@ npx scoutline vision analyze ./screenshot.png "What errors do you see?"
 npx scoutline search "React 19 new features" --count 5
 ```
 
-Get your API key at: https://z.ai/manage-apikey/apikey-list
+Get your Z.AI API key at: https://z.ai/manage-apikey/apikey-list
+
+To use MiniMax instead:
+
+```bash
+export MINIMAX_API_KEY="your-minimax-key"
+npx scoutline --provider minimax search "latest LLM benchmarks"
+```
 
 ## Installation
 
@@ -63,6 +71,125 @@ Or use directly with npx:
 npx scoutline --help
 ```
 
+## Provider Selection
+
+Shared commands (`search`, `vision`, `quota`, `doctor`) accept a global
+`--provider <zai|minimax>` flag. Resolution precedence:
+
+1. Explicit `--provider <zai|minimax>` on the command line
+2. `SCOUTLINE_PROVIDER` environment variable
+3. Compatibility default `zai`
+
+Examples:
+
+```bash
+# 1. Flag wins over everything
+scoutline --provider minimax search "React 19 features"
+
+# 2. Environment variable when no flag is supplied
+export SCOUTLINE_PROVIDER=minimax
+scoutline quota
+
+# 3. Default Z.AI when nothing is supplied
+scoutline search "TypeScript best practices"
+```
+
+Provider selection is **never** inferred from which credentials are present;
+empty credentials leave the Provider unconfigured and shared capabilities will
+fail with `AUTH_ERROR` or `CONFIGURATION_ERROR`. Unknown Provider IDs fail
+fast with `VALIDATION_ERROR`.
+
+`scoutline read`, `scoutline repo`, `scoutline tools`, `scoutline tool`,
+`scoutline call`, and `scoutline code` accept the flag but ignore it; they
+remain Z.AI-only in the base release.
+
+## Capability Matrix
+
+| Capability | Z.AI | MiniMax | Notes |
+| --- | --- | --- | --- |
+| `search` | Yes | Yes | MiniMax rejects domain/recency/content-size/location controls |
+| `vision.interpret-image` (analyze) | Yes | Yes | Provider-specific media limits; uncached |
+| `vision.ui-artifact` (ui-to-code) | Yes | Available | Live-attested; conformance-gated |
+| `vision.extract-text` | Yes | Pending | Implemented, pending live conformance |
+| `vision.diagnose-error` | Yes | Available | Live-attested; conformance-gated |
+| `vision.diagram` | Yes | Pending | Implemented, pending live conformance |
+| `vision.chart` | Yes | Pending | Implemented, pending live conformance |
+| `vision.diff` (image diff) | Yes | No | Base-release Z.AI-only |
+| `vision.video` | Yes | No | Base-release Z.AI-only |
+| `quota` | Yes | Yes | Normalized `QuotaDashboard` (ADR-0001) |
+| `diagnostics` (`doctor`) | Yes | Yes | Lists both Providers; probes configured |
+| `read` (Reader) | Yes | No | Base-release Z.AI-only |
+| `repo` (Repository exploration) | Yes | No | Base-release Z.AI-only |
+| `tools`, `tool`, `call` (Raw tools) | Yes | No | Base-release Z.AI-only |
+| `code` (Code Mode) | Yes | No | Base-release Z.AI-only |
+
+Media limits for general single-image interpretation:
+
+| Provider | Formats | Maximum |
+| --- | --- | --- |
+| Z.AI | JPG, JPEG, PNG | 5 MiB |
+| MiniMax | JPG, JPEG, PNG, WebP | 50 MiB |
+
+Vision results are never written to the local response cache.
+
+### Specialized MiniMax Vision Mappings
+
+The five specialized MiniMax Vision operations (`ui-artifact`,
+`extract-text`, `diagnose-error`, `diagram`, `chart`) are **implemented**
+in this release. Each operation has a dedicated prompt-composition Module
+under `packages/scoutline/src/providers/minimax/vision-mappings/` and a
+generated mapping revision committed to source.
+
+Runtime support for these operations is gated by the compiled conformance
+registry (`src/providers/minimax/vision-conformance.ts`). A specialized
+operation is only routable through MiniMax when **every** condition holds:
+
+- offline conformance state is `pass`,
+- live conformance state is `pass`,
+- a sanitized compiled attestation matches the operation, fixture version,
+  Implementation identity, and generated mapping revision.
+
+In the current release, `ui-artifact` and `diagnose-error` have offline
+`pass`, live `pass`, and compiled attestations — they are **supported at
+runtime** through MiniMax. The remaining three operations (`extract-text`,
+`diagram`, `chart`) have offline `pass` and live `pending`; they are
+**unsupported at runtime** and surface `UNSUPPORTED_CAPABILITY`. The CLI
+falls back to Z.AI (the Z.AI Provider supports every operation in the
+base release).
+
+No environment variable, flag, or configuration value can promote a
+mapping to supported. Support is driven exclusively by the compiled
+registry state.
+
+#### Enabling live support
+
+Live support is gated on a per-operation live attestation. The
+attestation script requires explicit opt-in and `MINIMAX_API_KEY`:
+
+```bash
+SCOUTLINE_LIVE_TESTS=1 node scripts/attest-minimax-vision.mjs --operation chart
+```
+
+Replace `chart` with `ui-artifact`, `extract-text`, `diagnose-error`,
+or `diagram`. The script runs one fixture against the live Provider,
+evaluates the semantic assertions in memory, and either:
+
+- writes a sanitized attestation entry to
+  `src/providers/minimax/vision-attestations.ts`, flips the registry's
+  `live` state to `pass`, and verifies runtime support becomes `true`;
+  OR
+- sets the registry's `live` state to `fail` if the semantics do not
+  hold. No success attestation is written and the mapping remains
+  unsupported.
+
+The next `npm run build` recompiles the registry with the new
+attestation and the operation becomes routable through MiniMax.
+
+Help text, `doctor`, and the Adapter's descriptor metadata all derive
+from the same registry, so once a mapping is promoted it appears on
+every runtime surface automatically — there is no second support list
+to update.
+
 ## Usage
 
 The CLI is self-documenting. Use `--help` at any level:
@@ -72,11 +199,17 @@ scoutline --help              # All commands
 scoutline vision --help       # Vision commands
 scoutline search --help       # Search options
 scoutline repo --help         # GitHub repo commands
+scoutline doctor --help       # Provider diagnostics
+scoutline quota --help        # Plan usage
 ```
 
 ### Examples
 
 ```bash
+# Provider selection
+scoutline --provider minimax search "AI policy news"
+scoutline --provider zai search "internal docs"
+
 # Vision - analyze images
 scoutline vision analyze ./image.png "Describe this"
 scoutline vision ui-to-code ./design.png --output code
@@ -98,9 +231,14 @@ scoutline repo read anthropics/anthropic-sdk-python README.md
 scoutline repo search openai/codex "config" --language en
 scoutline repo tree openai/codex --path codex-rs --depth 2
 
+# Quota - effective or all providers
+scoutline quota                       # effective Provider
+scoutline quota --all-providers       # every configured Provider
+
 # Doctor - check setup
-scoutline doctor
-scoutline doctor --no-vision
+scoutline doctor                      # full diagnostics
+scoutline doctor --no-tools           # metadata only, no transport
+scoutline doctor --provider minimax   # MiniMax connectivity
 ```
 
 ## Output Format
@@ -115,14 +253,41 @@ Default output is **data-only** for token efficiency. Use `--output-format json`
 }
 ```
 
+Quota output is a schema-version-1 `QuotaDashboard`:
+
+```json
+{
+  "schemaVersion": 1,
+  "effectiveProvider": "zai",
+  "providers": [
+    {
+      "provider": "zai",
+      "status": "ok",
+      "categories": [
+        { "name": "requests", "unit": "requests", "current": { "remainingPercent": 87.5 } },
+        { "name": "tokens",   "unit": "tokens",   "current": { "remainingPercent": 64.2 } }
+      ]
+    }
+  ]
+}
+```
+
+Doctor output is a schema-version-1 `DiagnosticsReport` listing every built-in
+Provider with its configured state, declared capabilities, and probe status.
+
 ## Notes
 
 - `repo search` defaults to English results. Use `--language zh` for Chinese.
 - `repo tree` supports `--path` (directory scope) and `--depth` (expand subtrees).
-- `tools`, `tool`, `call`, `doctor` accept `--no-vision` to speed startup when vision tools are not needed.
+- `quota --all-providers` exits 1 if any configured Provider fails; successful
+  entries are still reported.
+- `doctor` exits 1 when the effective Provider is unconfigured or any
+  configured probe fails; successful entries are still reported.
 - `read` supports `--with-images-summary`, `--no-gfm`, and `--keep-img-data-url` for richer parsing control.
 - Vision tool calls automatically retry transient 5xx/network errors (default: 2 retries). Configure with `ZAI_MCP_VISION_RETRY_COUNT` (or `ZAI_MCP_RETRY_COUNT` for all tools).
 - Tool discovery can be cached to speed `tools`/`tool`/`doctor` (default: on, 24h TTL). Configure with `ZAI_MCP_TOOL_CACHE`, `ZAI_MCP_TOOL_CACHE_TTL_MS`, `ZAI_MCP_CACHE_DIR`.
+- The response cache uses provider-partitioned keys; legacy `zai-cli` cache
+  entries remain readable for Z.AI but are never migrated.
 
 ## Contributing
 
@@ -143,4 +308,4 @@ MIT - see [LICENSE](https://github.com/vikasagarwal101/scoutline/blob/main/LICEN
 ## Links
 
 - [GitHub Repository](https://github.com/vikasagarwal101/scoutline)
-- [Documentation](https://github.com/vikasagarwal101/scoutline/tree/main/docs)
+- [Documentation](https://github.com/vikasagarwal101/scoutline/tree/main/docs)

package/bin/scoutline.js

@@ -1,17 +1,38 @@
 #!/usr/bin/env node
 
-import("../dist/index.js").catch((err) => {
-  console.error(
-    JSON.stringify(
-      {
-        success: false,
-        error: err.message,
-        code: "LOAD_ERROR",
-        help: 'Make sure to run "npm run build" before running scoutline',
-      },
-      null,
-      2,
-    ),
-  );
-  process.exit(1);
-});
+import("../dist/index.js")
+  .then(async ({ main }) => {
+    const { createNodeCommandInvocationAdapter } =
+      await import("../dist/node-command-invocation-adapter.js");
+    const adapter = createNodeCommandInvocationAdapter();
+    const status = await main(process.argv.slice(2), {
+      invocation: adapter,
+      env: process.env,
+    });
+    adapter.setExitCode(status);
+  })
+  .catch(async (err) => {
+    try {
+      const { formatLoadFailure } = await import(
+        "../dist/node-command-invocation-adapter.js"
+      );
+      console.error(formatLoadFailure(err));
+    } catch {
+      // If the dist module is unavailable for any reason, fall back to a
+      // best-effort envelope. We do not let a missing helper hide the
+      // original load error from the user.
+      console.error(
+        JSON.stringify(
+          {
+            success: false,
+            error: err && err.message ? err.message : String(err),
+            code: "LOAD_ERROR",
+            help: 'Make sure to run "npm run build" before running scoutline',
+          },
+          null,
+          2,
+        ),
+      );
+    }
+    process.exit(1);
+  });

package/dist/capabilities/diagnostics.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Diagnostics Capability Contract (DESIGN.md §14, P4-04).
+ *
+ * Defines the schema-version-1 diagnostics report every `doctor`
+ * invocation returns, plus the capability contract each Provider
+ * Adapter implements so its connectivity can be probed without a
+ * generative request.
+ *
+ * The report is built by the doctor command from static descriptor
+ * metadata plus the success/failure of each configured Provider probe.
+ * Each Adapter performs exactly ONE connectivity attempt; shared
+ * execution owns the retry policy.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - Imports Provider identity types, shared errors, the Vision
+ *     operation→capability mapping, and the MiniMax specialized Vision
+ *     conformance registry metadata (a pure snapshot, no transport).
+ *   - Imports no Provider transport, no Provider Adapter, no command
+ *     presentation.
+ *
+ * Normalization rules (DESIGN.md §14):
+ *   - Z.AI connectivity uses tool discovery (list tools from UTCP).
+ *   - MiniMax connectivity uses a raw single-attempt quota probe
+ *     (Adapter-local quota client), NOT `QuotaCapability.invoke()`,
+ *     because it authenticates without a generative request.
+ *   - For the base release `sharedCapabilities` is Search, general
+ *     single-image interpretation, quota, and diagnostics.
+ *   - `zaiOnlyCapabilities` is Reader, repository exploration, raw
+ *     provider tools, Code Mode, image diff, and video analysis.
+ */
+import type { ProviderCapability, ProviderId } from "../providers/types.js";
+import { type ScoutlineErrorCode } from "../lib/errors.js";
+export interface DiagnosticOptions {
+    readonly probe: boolean;
+}
+export interface ProviderDiagnostic {
+    readonly provider: ProviderId;
+    readonly configured: boolean;
+    readonly capabilities: readonly ProviderCapability[];
+    readonly status: "ok" | "error" | "skipped";
+    readonly reason?: "not-configured" | "tools-disabled";
+    readonly error?: {
+        code: ScoutlineErrorCode;
+        message: string;
+        help?: string;
+    };
+}
+export interface DiagnosticsReport {
+    readonly schemaVersion: 1;
+    readonly effectiveProvider: ProviderId;
+    readonly sharedCapabilities: readonly ProviderCapability[];
+    readonly zaiOnlyCapabilities: readonly string[];
+    readonly node: {
+        readonly version: string;
+        readonly visionMcpCompatible: boolean;
+    };
+    readonly providers: readonly ProviderDiagnostic[];
+}
+/**
+ * Capability each Provider Adapter implements for connectivity
+ * diagnostics. `invoke` resolves on a successful single connectivity
+ * attempt and throws a normalized {@link ScoutlineError} on failure;
+ * the doctor command catches the throw and records a redacted error
+ * entry. Returning `void` keeps the report builder the single owner of
+ * report shape.
+ */
+export interface DiagnosticsCapability {
+    invoke(options: DiagnosticOptions): Promise<void>;
+}
+/**
+ * Capabilities supported by every Provider in the base release (DESIGN.md
+ * §14, §15). The four base capabilities are static; specialized Vision
+ * operations move into shared metadata only when their compiled
+ * conformance registry entry is supported. At P5-02 every specialized
+ * entry is pending, so this list reduces to the base four. P5-03's
+ * attested mappings automatically extend this list through the single
+ * registry query — there is no parallel support list to maintain.
+ */
+export declare const SHARED_CAPABILITIES: readonly ProviderCapability[];
+/**
+ * Capabilities that remain Z.AI-only in the base release (DESIGN.md §14),
+ * in the documented order: Reader, repository exploration, raw provider
+ * tools, Code Mode, image diff, and video analysis.
+ */
+export declare const ZAI_ONLY_CAPABILITIES: readonly string[];
+/**
+ * Map a thrown error into a normalized diagnostic error entry. The
+ * caller is responsible for recursive redaction before the entry
+ * crosses an outward boundary (the doctor command does this in
+ * {@link buildDiagnosticsReport}).
+ */
+export declare function diagnosticErrorFromError(error: unknown): {
+    code: ScoutlineErrorCode;
+    message: string;
+    help?: string;
+};
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/capabilities/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/capabilities/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC5E,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAQ3E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,CAAC;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,kBAAkB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,UAAU,CAAC;IACvC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC3D,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;KACvC,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAMD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,kBAAkB,EAA8B,CAAC;AAU5F;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAOlD,CAAC;AAMF;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG;IACxD,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAYA"}

package/dist/capabilities/diagnostics.js

@@ -0,0 +1,88 @@
+/**
+ * Diagnostics Capability Contract (DESIGN.md §14, P4-04).
+ *
+ * Defines the schema-version-1 diagnostics report every `doctor`
+ * invocation returns, plus the capability contract each Provider
+ * Adapter implements so its connectivity can be probed without a
+ * generative request.
+ *
+ * The report is built by the doctor command from static descriptor
+ * metadata plus the success/failure of each configured Provider probe.
+ * Each Adapter performs exactly ONE connectivity attempt; shared
+ * execution owns the retry policy.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - Imports Provider identity types, shared errors, the Vision
+ *     operation→capability mapping, and the MiniMax specialized Vision
+ *     conformance registry metadata (a pure snapshot, no transport).
+ *   - Imports no Provider transport, no Provider Adapter, no command
+ *     presentation.
+ *
+ * Normalization rules (DESIGN.md §14):
+ *   - Z.AI connectivity uses tool discovery (list tools from UTCP).
+ *   - MiniMax connectivity uses a raw single-attempt quota probe
+ *     (Adapter-local quota client), NOT `QuotaCapability.invoke()`,
+ *     because it authenticates without a generative request.
+ *   - For the base release `sharedCapabilities` is Search, general
+ *     single-image interpretation, quota, and diagnostics.
+ *   - `zaiOnlyCapabilities` is Reader, repository exploration, raw
+ *     provider tools, Code Mode, image diff, and video analysis.
+ */
+import { ScoutlineError } from "../lib/errors.js";
+import { visionOperationToCapability } from "./vision.js";
+import { listSupportedMiniMaxVisionOperations } from "../providers/minimax/vision-conformance.js";
+// ---------------------------------------------------------------------------
+// Static base-release metadata
+// ---------------------------------------------------------------------------
+/**
+ * Capabilities supported by every Provider in the base release (DESIGN.md
+ * §14, §15). The four base capabilities are static; specialized Vision
+ * operations move into shared metadata only when their compiled
+ * conformance registry entry is supported. At P5-02 every specialized
+ * entry is pending, so this list reduces to the base four. P5-03's
+ * attested mappings automatically extend this list through the single
+ * registry query — there is no parallel support list to maintain.
+ */
+export const SHARED_CAPABILITIES = buildSharedCapabilities();
+function buildSharedCapabilities() {
+    const caps = ["search", "vision.interpret-image", "quota", "diagnostics"];
+    for (const op of listSupportedMiniMaxVisionOperations()) {
+        caps.push(visionOperationToCapability(op));
+    }
+    return Object.freeze(caps);
+}
+/**
+ * Capabilities that remain Z.AI-only in the base release (DESIGN.md §14),
+ * in the documented order: Reader, repository exploration, raw provider
+ * tools, Code Mode, image diff, and video analysis.
+ */
+export const ZAI_ONLY_CAPABILITIES = [
+    "reader",
+    "repository-exploration",
+    "raw-provider-tools",
+    "code-mode",
+    "image-diff",
+    "video-analysis",
+];
+// ---------------------------------------------------------------------------
+// Failure normalization
+// ---------------------------------------------------------------------------
+/**
+ * Map a thrown error into a normalized diagnostic error entry. The
+ * caller is responsible for recursive redaction before the entry
+ * crosses an outward boundary (the doctor command does this in
+ * {@link buildDiagnosticsReport}).
+ */
+export function diagnosticErrorFromError(error) {
+    const code = error instanceof ScoutlineError ? error.code : "UNKNOWN_ERROR";
+    const message = error instanceof Error ? error.message : String(error);
+    const result = {
+        code,
+        message,
+    };
+    if (error instanceof ScoutlineError && error.help) {
+        result.help = error.help;
+    }
+    return result;
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/capabilities/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/capabilities/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,cAAc,EAA2B,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,oCAAoC,EAAE,MAAM,4CAA4C,CAAC;AA2ClG,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAkC,uBAAuB,EAAE,CAAC;AAE5F,SAAS,uBAAuB;IAC9B,MAAM,IAAI,GAAyB,CAAC,QAAQ,EAAE,wBAAwB,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;IAChG,KAAK,MAAM,EAAE,IAAI,oCAAoC,EAAE,EAAE,CAAC;QACxD,IAAI,CAAC,IAAI,CAAC,2BAA2B,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,QAAQ;IACR,wBAAwB;IACxB,oBAAoB;IACpB,WAAW;IACX,YAAY;IACZ,gBAAgB;CACjB,CAAC;AAEF,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAc;IAKrD,MAAM,IAAI,GACR,KAAK,YAAY,cAAc,CAAC,CAAC,CAAE,KAAK,CAAC,IAA2B,CAAC,CAAC,CAAC,eAAe,CAAC;IACzF,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,MAAM,MAAM,GAAiE;QAC3E,IAAI;QACJ,OAAO;KACR,CAAC;IACF,IAAI,KAAK,YAAY,cAAc,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAClD,MAAM,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IAC3B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/capabilities/quota.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Quota Capability Contract (DESIGN.md §13, ADR-0001).
+ *
+ * Defines the normalized Provider-quota Interface shared by every
+ * Provider that reports plan usage. Each Adapter maps its Provider
+ * response shape into named quota categories with current and optional
+ * weekly windows, optional counts, a remaining percentage, and a reset
+ * time so callers do not need Provider-specific knowledge.
+ *
+ * Normalization rules (DESIGN.md §13):
+ *   - Percentages are REMAINING percentages clamped to 0..100.
+ *   - A valid explicit remaining percentage wins; otherwise derive
+ *     `(remaining / limit) * 100` from finite nonnegative counts where
+ *     used is not greater than limit.
+ *   - Invalid optional counts are omitted together (not set to zero).
+ *   - A category that has neither a valid percentage nor valid counts
+ *     is rejected with `QUOTA_ERROR`.
+ *   - Nonempty names, finite values, and ISO dates are mandatory.
+ *
+ * This module imports only Provider identity types and shared errors;
+ * it imports no Provider transport and no Provider Adapter.
+ */
+import type { ProviderId } from "../providers/types.js";
+import { type ScoutlineErrorCode } from "../lib/errors.js";
+export interface QuotaWindow {
+    durationSeconds?: number;
+    used?: number;
+    limit?: number;
+    remaining?: number;
+    remainingPercent: number;
+    resetsAt?: string;
+}
+export interface QuotaCategory {
+    name: string;
+    unit: "requests" | "tokens";
+    current: QuotaWindow;
+    weekly?: QuotaWindow;
+}
+export interface ProviderQuotaSuccess {
+    provider: ProviderId;
+    status: "ok";
+    plan?: string;
+    categories: QuotaCategory[];
+}
+export interface ProviderQuotaFailure {
+    provider: ProviderId;
+    status: "error";
+    error: {
+        code: ScoutlineErrorCode;
+        message: string;
+        help?: string;
+    };
+}
+export interface QuotaDashboard {
+    schemaVersion: 1;
+    effectiveProvider: ProviderId;
+    providers: Array<ProviderQuotaSuccess | ProviderQuotaFailure>;
+}
+export interface QuotaCapability {
+    invoke(): Promise<ProviderQuotaSuccess>;
+}
+/**
+ * Inputs to {@link buildQuotaWindow}. Every field is optional except
+ * that at least one of `explicitRemainingPercent` or a valid count set
+ * (`used` + `limit`) must be present, otherwise the window is
+ * unrecoverable and `QUOTA_ERROR` is thrown.
+ */
+export interface QuotaWindowInputs {
+    durationSeconds?: number;
+    used?: number;
+    limit?: number;
+    resetsAtEpochMs?: number;
+    /**
+     * A Provider-supplied REMAINING percentage (already in remaining
+     * terms, not used terms). A finite value wins over count-derived
+     * derivation and is then clamped to 0..100.
+     */
+    explicitRemainingPercent?: number;
+}
+/**
+ * Build a normalized {@link QuotaWindow} from Provider inputs.
+ *
+ * Resolution order for `remainingPercent`:
+ *   1. A finite explicit remaining percentage wins (then clamped).
+ *   2. Otherwise derive from valid counts.
+ *   3. Otherwise throw `QUOTA_ERROR` — the category is unrecoverable.
+ *
+ * Invalid optional counts are omitted together; valid counts populate
+ * `used`, `limit`, and a derived `remaining`. `durationSeconds` and
+ * `resetsAt` are included only when finite/ISO-valid.
+ */
+export declare function buildQuotaWindow(inputs: QuotaWindowInputs): QuotaWindow;
+/**
+ * Map a thrown error into a normalized {@link ProviderQuotaFailure}. The
+ * caller is responsible for recursive redaction before the failure
+ * crosses an outward boundary (all-provider quota does this in P4-03).
+ */
+export declare function quotaFailureFromError(provider: ProviderId, error: unknown): ProviderQuotaFailure;
+//# sourceMappingURL=quota.d.ts.map

package/dist/capabilities/quota.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../src/capabilities/quota.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAM3E,MAAM,WAAW,WAAW;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,UAAU,CAAC;IACrB,MAAM,EAAE,IAAI,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,aAAa,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,UAAU,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,kBAAkB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,CAAC,CAAC;IACjB,iBAAiB,EAAE,UAAU,CAAC;IAC9B,SAAS,EAAE,KAAK,CAAC,oBAAoB,GAAG,oBAAoB,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACzC;AAMD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAkDD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAoCvE;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAahG"}