scoutline 0.1.0 → 0.6.0

package/dist/providers/zai/monitor-client.js

@@ -0,0 +1,117 @@
+/**
+ * Z.AI Monitor API client — Provider-local transport (DESIGN.md §13, P4-02).
+ *
+ * This Module owns the Z.AI monitor endpoint fetch mechanics moved here
+ * from `lib/monitor-client.ts`. It performs direct HTTP against
+ * `https://api.z.ai` (overridable via `ZAI_MONITOR_BASE_URL`) with an
+ * auth quirk: try the raw key first, and on 401 retry the same request
+ * with a `Bearer` prefix. Every transport dependency (fetch, timer,
+ * environment) is injectable so tests drive auth fallback and timeout
+ * deterministically without touching globals.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import Provider identity types, normalized errors.
+ *   - Must NOT import command presentation or another Provider's Adapter.
+ *
+ * Raw response text NEVER enters public errors. A non-2xx response is
+ * mapped to a stable normalized error (`AuthError` for 401/403, `ApiError`
+ * otherwise) whose message carries no response body. Transport failures
+ * map to `TimeoutError`/`NetworkError`.
+ *
+ * This transport performs ONE logical attempt (including the auth-scheme
+ * fallback). Shared execution owns retry policy.
+ */
+import { ApiError, AuthError, NetworkError, TimeoutError } from "../../lib/errors.js";
+const DEFAULT_MONITOR_BASE = "https://api.z.ai";
+const DEFAULT_TIMEOUT_MS = 30000;
+function resolveBase(env) {
+    return env.ZAI_MONITOR_BASE_URL || DEFAULT_MONITOR_BASE;
+}
+function resolveTimeoutMs(env) {
+    const raw = parseInt(env.Z_AI_TIMEOUT || String(DEFAULT_TIMEOUT_MS), 10);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
+}
+function mapStatusError(status) {
+    if (status === 401 || status === 403) {
+        return new AuthError("Z.AI monitor API authentication failed");
+    }
+    return new ApiError("Z.AI monitor API request failed", status);
+}
+function normalizeTransportError(err, timeoutMs) {
+    if (err instanceof AuthError || err instanceof ApiError)
+        return err;
+    if (err instanceof Error) {
+        if (err.name === "AbortError") {
+            return new TimeoutError(timeoutMs);
+        }
+        const lower = err.message.toLowerCase();
+        if (lower.includes("fetch") ||
+            lower.includes("econnrefused") ||
+            lower.includes("econnreset") ||
+            lower.includes("enotfound") ||
+            lower.includes("network")) {
+            return new NetworkError("Z.AI monitor network error");
+        }
+    }
+    return new ApiError("Z.AI monitor request failed", 500);
+}
+/**
+ * Perform one authenticated GET against the monitor API with the raw-key
+ * then Bearer auth fallback. Returns the unwrapped `data` payload (or the
+ * whole body when no `data` envelope is present).
+ *
+ * `path` is appended to the monitor base; `params` become query params.
+ */
+export async function fetchZaiMonitorPath(apiKey, path, params, deps = {}) {
+    const f = deps.fetch ?? fetch;
+    const setT = deps.setTimeout ?? setTimeout;
+    const clearT = deps.clearTimeout ?? clearTimeout;
+    const env = deps.env ?? process.env;
+    const base = resolveBase(env);
+    const timeoutMs = resolveTimeoutMs(env);
+    const url = new URL(base + path);
+    if (params) {
+        for (const [k, v] of Object.entries(params))
+            url.searchParams.set(k, v);
+    }
+    for (const authValue of [apiKey, `Bearer ${apiKey}`]) {
+        const controller = new AbortController();
+        const timeoutId = setT(() => controller.abort(), timeoutMs);
+        try {
+            const res = await f(url, {
+                method: "GET",
+                headers: {
+                    Authorization: authValue,
+                    "Accept-Language": "en-US,en",
+                    "Content-Type": "application/json",
+                },
+                signal: controller.signal,
+            });
+            clearT(timeoutId);
+            if (res.status === 401 && authValue === apiKey) {
+                // Auth-scheme fallback: retry the same request with Bearer.
+                continue;
+            }
+            if (!res.ok) {
+                // Drain the body so the connection can be reused, but NEVER let
+                // the raw text reach a public error message.
+                await res.text().catch(() => { });
+                throw mapStatusError(res.status);
+            }
+            const body = (await res.json());
+            return body.data ?? body;
+        }
+        catch (err) {
+            clearT(timeoutId);
+            throw normalizeTransportError(err, timeoutMs);
+        }
+    }
+    throw new AuthError("Z.AI monitor API rejected both auth schemes");
+}
+/**
+ * Fetch the Z.AI quota-limit payload (one attempt, auth-scheme fallback).
+ */
+export async function fetchZaiQuotaLimit(apiKey, deps = {}) {
+    return (await fetchZaiMonitorPath(apiKey, "/api/monitor/usage/quota/limit", undefined, deps));
+}
+//# sourceMappingURL=monitor-client.js.map

package/dist/providers/zai/monitor-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor-client.js","sourceRoot":"","sources":["../../../src/providers/zai/monitor-client.ts"],"names":[],"mappings":"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"}

package/dist/providers/zai/quota.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Z.AI Quota Capability (DESIGN.md §13, P4-02).
+ *
+ * Maps the Z.AI monitor quota-limit response into the normalized
+ * Provider-quota Interface. The normalizer is pure; the capability
+ * factory owns credential resolution, the single monitor transport
+ * attempt, and failure normalization. Shared execution owns retry.
+ *
+ * Z.AI mapping (DESIGN.md §13):
+ *   - `level` -> `plan`.
+ *   - Rolling `TIME_LIMIT` -> `requests` category with current counts,
+ *     duration in seconds, derived remaining percent, and ISO reset.
+ *   - `TOKENS_LIMIT` -> `tokens` category; convert the Provider's used
+ *     percentage to a remaining percentage.
+ *   - Categories are named `requests` then `tokens` when present.
+ *   - Per-tool breakdown (`usageDetails`) is omitted — no field in
+ *     ADR-0001.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import the quota capability contract, Provider-local monitor
+ *     transport, and normalized errors.
+ *   - Must NOT import command presentation or another Provider's Adapter.
+ */
+import type { ProviderQuotaSuccess, QuotaCapability } from "../../capabilities/quota.js";
+import { type ZaiMonitorDeps } from "./monitor-client.js";
+/**
+ * Normalize a raw Z.AI quota-limit payload into the shared Interface.
+ * Throws `QUOTA_ERROR` (via {@link buildQuotaWindow}) when a present
+ * limit entry has neither a valid percentage nor valid counts.
+ */
+export declare function normalizeZaiQuota(raw: unknown): ProviderQuotaSuccess;
+/**
+ * Options for the Z.AI QuotaCapability. `env` resolves the API key and
+ * monitor base/timeout. The transport dependencies (`fetch`, timer) are
+ * injectable for deterministic tests.
+ */
+export interface ZaiQuotaCapabilityOptions extends ZaiMonitorDeps {
+    readonly env: NodeJS.ProcessEnv;
+}
+/**
+ * Build the Z.AI QuotaCapability. `invoke` resolves the credential,
+ * performs one monitor transport attempt (auth-scheme fallback inside),
+ * and normalizes the response. Shared execution wraps this in the retry
+ * policy; quota never uses the response cache.
+ */
+export declare function createZaiQuotaCapability(options: ZaiQuotaCapabilityOptions): QuotaCapability;
+//# sourceMappingURL=quota.d.ts.map

package/dist/providers/zai/quota.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../../src/providers/zai/quota.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EAEhB,MAAM,6BAA6B,CAAC;AASrC,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAsD7B;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,oBAAoB,CAiDpE;AAmBD;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,eAAe,CAgB5F"}

package/dist/providers/zai/quota.js

@@ -0,0 +1,127 @@
+/**
+ * Z.AI Quota Capability (DESIGN.md §13, P4-02).
+ *
+ * Maps the Z.AI monitor quota-limit response into the normalized
+ * Provider-quota Interface. The normalizer is pure; the capability
+ * factory owns credential resolution, the single monitor transport
+ * attempt, and failure normalization. Shared execution owns retry.
+ *
+ * Z.AI mapping (DESIGN.md §13):
+ *   - `level` -> `plan`.
+ *   - Rolling `TIME_LIMIT` -> `requests` category with current counts,
+ *     duration in seconds, derived remaining percent, and ISO reset.
+ *   - `TOKENS_LIMIT` -> `tokens` category; convert the Provider's used
+ *     percentage to a remaining percentage.
+ *   - Categories are named `requests` then `tokens` when present.
+ *   - Per-tool breakdown (`usageDetails`) is omitted — no field in
+ *     ADR-0001.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import the quota capability contract, Provider-local monitor
+ *     transport, and normalized errors.
+ *   - Must NOT import command presentation or another Provider's Adapter.
+ */
+import { buildQuotaWindow } from "../../capabilities/quota.js";
+import { ApiError, AuthError, ConfigurationError, NetworkError, TimeoutError, } from "../../lib/errors.js";
+import { fetchZaiQuotaLimit, } from "./monitor-client.js";
+import { requireZaiApiKey } from "./credentials.js";
+function isTimeLimit(value) {
+    return (!!value && typeof value === "object" && value.type === "TIME_LIMIT");
+}
+function isTokensLimit(value) {
+    return (!!value && typeof value === "object" && value.type === "TOKENS_LIMIT");
+}
+function readNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+// ---------------------------------------------------------------------------
+// Normalizer
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a raw Z.AI quota-limit payload into the shared Interface.
+ * Throws `QUOTA_ERROR` (via {@link buildQuotaWindow}) when a present
+ * limit entry has neither a valid percentage nor valid counts.
+ */
+export function normalizeZaiQuota(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new ApiError("Z.AI quota returned a malformed response", 500);
+    }
+    const data = raw;
+    const categories = [];
+    const limits = Array.isArray(data.limits) ? data.limits : [];
+    const timeLimit = limits.find(isTimeLimit);
+    if (timeLimit) {
+        const durationSeconds = typeof timeLimit.unit === "number" && Number.isFinite(timeLimit.unit)
+            ? timeLimit.unit * 3600
+            : undefined;
+        categories.push({
+            name: "requests",
+            unit: "requests",
+            current: buildQuotaWindow({
+                used: readNumber(timeLimit.currentValue),
+                limit: readNumber(timeLimit.usage),
+                durationSeconds,
+                resetsAtEpochMs: readNumber(timeLimit.nextResetTime),
+                // Z.AI `percentage` is a USED percentage — do NOT treat it as an
+                // explicit remaining percentage. Derive from counts instead.
+            }),
+        });
+    }
+    const tokensLimit = limits.find(isTokensLimit);
+    if (tokensLimit) {
+        const usedPercent = readNumber(tokensLimit.percentage);
+        const remainingPercent = usedPercent !== undefined ? 100 - usedPercent : undefined;
+        categories.push({
+            name: "tokens",
+            unit: "tokens",
+            current: buildQuotaWindow({
+                explicitRemainingPercent: remainingPercent,
+                resetsAtEpochMs: readNumber(tokensLimit.nextResetTime),
+            }),
+        });
+    }
+    return {
+        provider: "zai",
+        status: "ok",
+        plan: typeof data.level === "string" && data.level.length > 0 ? data.level : undefined,
+        categories,
+    };
+}
+// ---------------------------------------------------------------------------
+// Capability factory
+// ---------------------------------------------------------------------------
+function normalizeZaiQuotaError(error) {
+    if (error instanceof AuthError ||
+        error instanceof ApiError ||
+        error instanceof NetworkError ||
+        error instanceof TimeoutError ||
+        error instanceof ConfigurationError) {
+        return error;
+    }
+    return new ApiError("Z.AI quota request failed", 500);
+}
+/**
+ * Build the Z.AI QuotaCapability. `invoke` resolves the credential,
+ * performs one monitor transport attempt (auth-scheme fallback inside),
+ * and normalizes the response. Shared execution wraps this in the retry
+ * policy; quota never uses the response cache.
+ */
+export function createZaiQuotaCapability(options) {
+    const { env, ...transportDeps } = options;
+    return {
+        async invoke() {
+            // Shared credential resolver (Fixup A — B4/B7): honours the
+            // ZAI_API_KEY alias and treats a missing key as a configuration
+            // failure (ConfigurationError, exit 3).
+            const apiKey = requireZaiApiKey(env);
+            try {
+                const raw = await fetchZaiQuotaLimit(apiKey, transportDeps);
+                return normalizeZaiQuota(raw);
+            }
+            catch (error) {
+                throw normalizeZaiQuotaError(error);
+            }
+        },
+    };
+}
+//# sourceMappingURL=quota.js.map

package/dist/providers/zai/quota.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota.js","sourceRoot":"","sources":["../../../src/providers/zai/quota.ts"],"names":[],"mappings":"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"}

package/dist/providers/zai/reader.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Z.AI Reader Adapter (DESIGN.md §18; reader-migration-tech-plan D4;
+ * PRD FR-??? — reader migration Ticket 03).
+ *
+ * Owns the Provider-facing half of the provider-neutral Reader
+ * Capability defined in `src/capabilities/reader.ts`:
+ *
+ *   - URL rewrite (gist.github.com/<user>/<id> -> /raw) applied BEFORE
+ *     invocation; the rewritten URL surfaces as `finalUrl` in the
+ *     result. The rewrite is Z.AI-specific because Z.AI's WebReader
+ *     MCP recognizes the rewritten URL.
+ *   - a total parser for the characterized Z.AI WebReader response
+ *     (`ReaderRawResponse`: object on success, bare string for MCP-
+ *     level error envelopes);
+ *   - encoded MCP error classification BEFORE success parsing
+ *     (`quota` is terminal `QUOTA_ERROR`; the rest of the taxonomy
+ *     uses the shared retry/terminal classification); the parsing
+ *     helpers live in `./encoded-error.ts` and are shared with
+ *     `./repository.ts`;
+ *   - a single resolved-credential fingerprint per cache identity and
+ *     exact per-operation legacy cache candidate using Ticket 01's
+ *     `buildLegacyReaderCacheKey` helper;
+ *   - `decodeCached` delegates to Ticket 01's total decoder
+ *     (`decodeReaderFetchResult`);
+ *   - a fresh transport per invocation attempt and exactly one
+ *     best-effort close in `finally`; close failure never replaces
+ *     success nor masks the primary failure;
+ *   - no leakage of raw WebReader response types outside this module.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import capability types, normalized errors, the Z.AI MCP
+ *     tool-name helpers, the legacy cache-key helper, the shared
+ *     `ZaiAdapterClientPort` typed client port, and the shared
+ *     encoded-error helpers.
+ *   - Must NOT import another Provider's Adapter, command
+ *     presentation, or extract/maxChars projection logic.
+ *
+ * Scope:
+ *   - implements the single `reader-fetch` operation only. URL scheme
+ *     validation, `--extract`, `--max-chars`, and `--full-envelope`
+ *     belong to the command layer (Ticket 04 cuts the handler over).
+ *   - descriptor metadata sequencing: Ticket 03 introduces this Adapter
+ *     handle and wires it through `ProviderAdapter.reader` WITHOUT
+ *     advertising `reader` on `createZaiDescriptor.capabilities()`;
+ *     Ticket 04 then flips the descriptor to advertise `reader` so
+ *     Provider selection and Doctor inventory derive from a single
+ *     source of truth, AND cuts `commands/read.ts` over to dispatch
+ *     through `adapter.reader.fetch`. This module owns no registry,
+ *     selection, or command cutover.
+ */
+import type { ZaiAdapterClientPort, ZaiMcpClientOptions } from "../types.js";
+import { type ReaderCapability } from "../../capabilities/reader.js";
+/**
+ * Production close bound (ms). Matches the existing
+ * `ZaiMcpClient.close(timeoutMs = 2000)` semantic; the Adapter races
+ * the close against a 2 second timer that resolves silently so a stuck
+ * close cannot stall the attempt. Tests may inject a shorter bound via
+ * {@link ZaiReaderCapabilityOptions.closeTimeoutMs}.
+ */
+export declare const ZAI_READER_CLOSE_BOUND_MS = 2000;
+/**
+ * Options accepted by {@link createZaiReaderCapability}.
+ *
+ * `closeTimeoutMs` defaults to {@link ZAI_READER_CLOSE_BOUND_MS}
+ * (2000 ms) — the existing `ZaiMcpClient.close(timeoutMs = 2000)`
+ * semantic. Tests may inject a shorter bound to bound a never-
+ * resolving `close()` without waiting for the production default.
+ */
+export interface ZaiReaderCapabilityOptions {
+    readonly env: NodeJS.ProcessEnv;
+    readonly clientFactory: (options: ZaiMcpClientOptions) => ZaiAdapterClientPort;
+    readonly closeTimeoutMs?: number;
+}
+/**
+ * Build the Z.AI Reader Capability. The capability is composed of a
+ * single typed `ReaderOperation` descriptor (`fetch`); the Adapter
+ * owns credentials, transport lifecycle, raw request/response mapping,
+ * URL rewrite, and error normalization. No transport, credential
+ * resolution, or I/O happens during construction.
+ */
+export declare function createZaiReaderCapability(options: ZaiReaderCapabilityOptions): ReaderCapability;
+//# sourceMappingURL=reader.d.ts.map

package/dist/providers/zai/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../../src/providers/zai/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAM7E,OAAO,EAGL,KAAK,gBAAgB,EAItB,MAAM,8BAA8B,CAAC;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAie9C;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,oBAAoB,CAAC;IAC/E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,gBAAgB,CAS/F"}