scoutline 0.1.0 → 0.6.0

package/dist/capabilities/diagnostics.js

@@ -0,0 +1,139 @@
+/**
+ * Diagnostics Capability Contract (DESIGN.md §14, P4-04, P6-06).
+ *
+ * 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 descriptor-derived
+ * inventory 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 and metadata types (`ProviderCapability`,
+ *     `ProviderDescriptor`, `ProviderId`) and shared errors. P6-06 keeps
+ *     the inventory descriptor-derived; no concrete Adapter, no
+ *     Provider transport, no production registry import lives here.
+ *   - Imports no Provider transport, no Provider Adapter, no Vision
+ *     operation→capability mapping, no MiniMax specialized-vision
+ *     conformance registry, no command presentation. The previous
+ *     hand-maintained inventory required those imports; the
+ *     descriptor-derived inventory does not.
+ *
+ * Inventory derivation (P6-06):
+ *   - `sharedCapabilities` is the intersection across every descriptor
+ *     passed to `buildDiagnosticsReport`, preserving deterministic
+ *     canonical order from the FIRST descriptor.
+ *   - `zaiOnlyCapabilities` is the Z.AI descriptor's capabilities
+ *     minus the union of every OTHER built-in descriptor's
+ *     capabilities, preserving Z.AI descriptor order. Values are
+ *     descriptor capability IDs only — no hand-maintained aliases.
+ *   - `repository-exploration` is excluded from shared while any
+ *     built-in lacks it, and included in Z.AI-only the moment Z.AI
+ *     advertises it and another built-in does not.
+ */
+import { ScoutlineError } from "../lib/errors.js";
+// ---------------------------------------------------------------------------
+// Descriptor-derived inventory (P6-06).
+//
+// Pure calculations over the exact descriptor list passed to
+// `buildDiagnosticsReport`. No descriptor.create(), no transport, no
+// production registry import. Empty/single/missing-ZAI lists are
+// handled deterministically; the algorithms never rely on array
+// indexing accidents.
+// ---------------------------------------------------------------------------
+/**
+ * Derive the shared Capabilities inventory: the intersection of every
+ * descriptor's `capabilities()` set, preserving deterministic
+ * canonical order from the FIRST descriptor in the list.
+ *
+ * Edge cases:
+ *   - Empty descriptor list: returns an empty array.
+ *   - Single descriptor: returns that descriptor's capabilities in
+ *     their declared order (the intersection of one set is itself).
+ *   - Two or more: keeps a capability from the first descriptor iff
+ *     every other descriptor also advertises it.
+ *
+ * The returned array is frozen so callers cannot mutate the cached
+ * derivation in place.
+ */
+export function deriveSharedCapabilities(descriptors) {
+    if (descriptors.length === 0)
+        return Object.freeze([]);
+    const [first, ...rest] = descriptors;
+    if (rest.length === 0) {
+        return Object.freeze([...first.capabilities()]);
+    }
+    const otherSets = rest.map((d) => d.capabilities());
+    const out = [];
+    for (const cap of first.capabilities()) {
+        if (otherSets.every((set) => set.has(cap))) {
+            out.push(cap);
+        }
+    }
+    return Object.freeze(out);
+}
+/**
+ * Derive the Z.AI-only Capabilities inventory: capabilities advertised
+ * by the Z.AI descriptor minus the union of capabilities advertised by
+ * every OTHER descriptor in the list. Preserves Z.AI descriptor order.
+ *
+ * Edge cases:
+ *   - Empty descriptor list: returns an empty array.
+ *   - Z.AI absent from the list: returns an empty array.
+ *   - Z.AI present as the only descriptor: returns its capabilities
+ *     verbatim (the "minus nothing" case).
+ *   - Z.AI with other descriptors: each capability in Z.AI descriptor
+ *     order is kept iff no other descriptor advertises it.
+ *
+ * The returned values are descriptor capability IDs only. No
+ * hand-maintained aliases, no parallel base-release list, no
+ * invented names. `repository-exploration` lands here naturally the
+ * moment Z.AI advertises it and another built-in does not.
+ */
+export function deriveZaiOnlyCapabilities(descriptors) {
+    const zai = descriptors.find((d) => d.id === "zai");
+    if (!zai)
+        return Object.freeze([]);
+    const others = descriptors.filter((d) => d.id !== "zai");
+    if (others.length === 0) {
+        return Object.freeze([...zai.capabilities()]);
+    }
+    const union = new Set();
+    for (const descriptor of others) {
+        for (const cap of descriptor.capabilities()) {
+            union.add(cap);
+        }
+    }
+    const out = [];
+    for (const cap of zai.capabilities()) {
+        if (!union.has(cap)) {
+            out.push(cap);
+        }
+    }
+    return Object.freeze(out);
+}
+// ---------------------------------------------------------------------------
+// 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":"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"}

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"}

package/dist/capabilities/quota.js

@@ -0,0 +1,129 @@
+/**
+ * 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 { ScoutlineError } from "../lib/errors.js";
+function isFiniteNonnegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isFinitePositive(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function clampPercent(value) {
+    if (value < 0)
+        return 0;
+    if (value > 100)
+        return 100;
+    return value;
+}
+/**
+ * Validate a count set: both `used` and `limit` must be finite,
+ * nonnegative, with `used` not greater than `limit`. Returns the pair
+ * or `null` so an invalid set can be omitted together.
+ */
+function validCountSet(used, limit) {
+    if (!isFiniteNonnegative(used) || !isFiniteNonnegative(limit))
+        return null;
+    if (used > limit)
+        return null;
+    return { used: used, limit: limit };
+}
+/**
+ * Derive a remaining percentage from finite nonnegative counts where
+ * used is not greater than limit and limit is positive. Returns `null`
+ * when the counts cannot yield a percentage.
+ */
+function derivePercentFromCounts(used, limit) {
+    const counts = validCountSet(used, limit);
+    if (counts === null)
+        return null;
+    if (counts.limit <= 0)
+        return null;
+    return ((counts.limit - counts.used) / counts.limit) * 100;
+}
+function epochMsToIso(epochMs) {
+    if (!isFinitePositive(epochMs))
+        return undefined;
+    return new Date(epochMs).toISOString();
+}
+/**
+ * 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 function buildQuotaWindow(inputs) {
+    let remainingPercent;
+    if (Number.isFinite(inputs.explicitRemainingPercent)) {
+        remainingPercent = inputs.explicitRemainingPercent;
+    }
+    else {
+        const derived = derivePercentFromCounts(inputs.used, inputs.limit);
+        if (derived !== null)
+            remainingPercent = derived;
+    }
+    if (remainingPercent === undefined) {
+        throw new ScoutlineError("quota category has neither a valid remaining percentage nor valid counts", "QUOTA_ERROR", { exitCode: 1 });
+    }
+    const window = { remainingPercent: clampPercent(remainingPercent) };
+    const counts = validCountSet(inputs.used, inputs.limit);
+    if (counts !== null) {
+        window.used = counts.used;
+        window.limit = counts.limit;
+        window.remaining = counts.limit - counts.used;
+    }
+    if (isFinitePositive(inputs.durationSeconds)) {
+        window.durationSeconds = inputs.durationSeconds;
+    }
+    const iso = epochMsToIso(inputs.resetsAtEpochMs);
+    if (iso !== undefined) {
+        window.resetsAt = iso;
+    }
+    return window;
+}
+// ---------------------------------------------------------------------------
+// Failure normalization
+// ---------------------------------------------------------------------------
+/**
+ * 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 function quotaFailureFromError(provider, error) {
+    const code = error instanceof ScoutlineError ? error.code : "UNKNOWN_ERROR";
+    const message = error instanceof Error ? error.message : String(error);
+    const failure = {
+        provider,
+        status: "error",
+        error: { code, message },
+    };
+    if (error instanceof ScoutlineError && error.help) {
+        failure.error.help = error.help;
+    }
+    return failure;
+}
+//# sourceMappingURL=quota.js.map

package/dist/capabilities/quota.js.map

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

package/dist/capabilities/reader.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Provider-neutral Reader Capability Contract (core-flows D1, D2;
+ * tech-plan D1, D2).
+ *
+ * This module declares the single Reader operation (`reader-fetch`), its
+ * provider-neutral request, identity, cache, and result shapes, the total
+ * normalized cache decoder, and the `ReaderRawResponse` type capturing
+ * what the Z.AI WebReader MCP actually returns at runtime.
+ *
+ * It imports NO concrete Provider, transport, or Adapter. It does no URL
+ * rewriting, raw response parsing, Provider field mapping, Provider
+ * selection, retries, or presentation.
+ *
+ * Scope of this file:
+ *   - request, operation, cache-identity, and result type contracts;
+ *   - the discriminated `ReaderOperationKind` union;
+ *   - a total decoder for the cacheable normalized result
+ *     (`decodeReaderFetchResult`);
+ *   - the `ReaderRawResponse` type consumed by Ticket 02's `webRead`
+ *     signature fix.
+ *
+ * Ticket 01 introduces ONLY this contract and the decoder. Ticket 02
+ * fixes `webRead` to return `ReaderRawResponse`. Ticket 03 supplies the
+ * Z.AI Reader Adapter. Ticket 04 cuts the handler over. Nothing in this
+ * file is allowed to widen that boundary.
+ *
+ * Evidence base: [`artifacts/reader-webreader-characterization/`](../../../../.traycer/epics/4f065460-3416-4832-95a6-7ac5576fcfbc/artifacts/reader-webreader-characterization/index.md).
+ */
+import type { ProviderId } from "../providers/types.js";
+/**
+ * The single Reader Capability operation. Cache identity partitions by
+ * the composite `${capability}-${operation}` literal; the v2 partitioned
+ * key shape is
+ * `v2.reader-reader-fetch.<provider>.<credential-hash>.<request-hash>.json`.
+ *
+ * `--extract` and `--max-chars` are handler-level projections and do
+ * NOT participate in the cache identity (tech-plan D1, D2).
+ */
+export type ReaderOperationKind = "reader-fetch";
+/**
+ * Provider-neutral Reader fetch request. `url` MUST be supplied
+ * explicitly (the handler rejects non-`http(s)` values at parse time
+ * with `VALIDATION_ERROR` before this request reaches the Adapter).
+ *
+ * Every field except `url` participates in the v0.2 legacy cache key
+ * (`buildLegacyReaderCacheKey`) and in the v2 partitioned cache identity
+ * (`buildProviderCacheKey`). `--extract`, `--max-chars`, `--full-envelope`,
+ * `--no-cache`, and output mode NEVER appear here — they are projections
+ * applied after the cached normalized result.
+ *
+ * Field name parity with the v0.2 `webRead` request shape is intentional;
+ * the Adapter maps each field to the Z.AI WebReader MCP argument of the
+ * same semantics. The field order in the v0.2 insertion-order key is
+ * locked by the legacy helper, not by this interface.
+ */
+export interface ReaderFetchRequest {
+    readonly url: string;
+    readonly format?: "markdown" | "text";
+    readonly retainImages?: boolean;
+    readonly withLinksSummary?: boolean;
+    readonly noGfm?: boolean;
+    readonly keepImgDataUrl?: boolean;
+    readonly withImagesSummary?: boolean;
+    readonly timeout?: number;
+}
+/**
+ * Normalized Reader fetch result. `schemaVersion: 1` is the breaking
+ * migration shape (core-flows D1 — `data`-mode returns the envelope,
+ * not a raw string).
+ *
+ * `truncated` and `originalContentLength` are NOT part of this contract.
+ * They are handler-level projections applied by `commands/read.ts` after
+ * the cached normalized result is produced (tech-plan D5). The cache
+ * stores the full content; truncation state is recomputed on every read.
+ *
+ * `title` is `string | null`. Every observed Z.AI WebReader response
+ * carries a non-empty string title (see characterization artifact), but
+ * the contract keeps the nullable arm for forward-compat and for
+ * Adapter-side coercion of empty / whitespace-only titles.
+ *
+ * `metadata` and `external` are typed `unknown` defensively. The
+ * characterization probe observed both as flat object maps, but the
+ * contract does not promote or restructure them — they pass through
+ * verbatim from the Provider.
+ */
+export interface ReaderFetchResult {
+    readonly schemaVersion: 1;
+    /** Exactly what the caller passed to the operation. */
+    readonly url: string;
+    /**
+     * The URL the operation actually fetched. Differs from `url` only when
+     * a Provider-side rewrite occurred (e.g. `gist.github.com/<id>` →
+     * `gist.github.com/<id>/raw`).
+     */
+    readonly finalUrl: string;
+    /** Page title if the Provider returned one; `null` if absent or blank. */
+    readonly title: string | null;
+    /** Page content as markdown or plain text per `format`. */
+    readonly content: string;
+    /** Mirrors the request `format`; defaults to `"markdown"`. */
+    readonly contentFormat: "markdown" | "text";
+    /** Optional Provider-derived metadata blob; preserved verbatim. */
+    readonly metadata?: unknown;
+    /** Optional Provider-derived external-resource blob; preserved verbatim. */
+    readonly external?: unknown;
+}
+/**
+ * Object shape of a successful Z.AI WebReader MCP response. Field names
+ * mirror the wire shape observed in the characterization probe. Every
+ * field is optional at the wire layer — the Capability decoder enforces
+ * the stronger invariants (`title`, `url`, `content` must be non-empty
+ * strings) before promoting any value into a `ReaderFetchResult`.
+ *
+ * `description` is declared here so the Adapter can read it without
+ * crashing on rich pages (the probe confirmed `description` appears
+ * both at the top level and inside `metadata` for rich pages). The v1
+ * envelope does NOT surface it; it is dropped during normalization.
+ */
+export interface ReaderRawObjectResponse {
+    readonly title?: string;
+    readonly description?: string;
+    readonly url?: string;
+    readonly content?: string;
+    readonly metadata?: unknown;
+    readonly external?: unknown;
+}
+/**
+ * The complete raw shape returned by `scoutline.zai.reader.webReader` at
+ * runtime. Either a structured object (the common case) or a bare
+ * `string` carrying an MCP-level error envelope (the characterization
+ * probe captured the exact shape: `"MCP error -500: ..."`).
+ *
+ * Ticket 02 widens the existing `webRead` method's TypeScript signature from
+ * the inaccurate `Promise<string>` to `Promise<ReaderRawResponse>` so
+ * raw-tool callers (`scoutline.zai.reader.*`) and the future Reader
+ * Adapter both see an honest path.
+ *
+ * The Capability decoder (`decodeReaderFetchResult`) only trusts
+ * object-shape values that satisfy the required field set. A raw
+ * `string` is malformed at the Capability layer — it represents a
+ * transport-level error that the Adapter must convert into a normalized
+ * `API_ERROR` 502 per the failure-handling table, not a fetch result.
+ */
+export type ReaderRawResponse = ReaderRawObjectResponse | string;
+/**
+ * Provider-owned legacy cache candidate. Old Z.AI v0.2 read cache entries
+ * encode the raw WebReader response under the public dotted tool name
+ * (`scoutline.zai.reader.webReader`). The Adapter supplies the decoder
+ * so shared cache code never inspects Provider response shapes. An
+ * invalid decode is a cache miss.
+ */
+export interface LegacyReaderCacheCandidate<Result> {
+    readonly key: string;
+    decode(value: unknown): Result | null;
+}
+/**
+ * Identity used to read and write a Provider-partitioned Reader cache
+ * entry. `credentialFingerprint` is the full lowercase SHA-256 hex
+ * digest of the resolved credential and is NEVER re-hashed by cache
+ * code. `request` is the normalized Capability request.
+ */
+export interface ReaderCacheIdentity<Request, Result> {
+    readonly provider: ProviderId;
+    readonly capability: "reader";
+    readonly operation: ReaderOperationKind;
+    readonly credentialFingerprint: string;
+    readonly request: Readonly<Request>;
+    readonly legacyCandidates: readonly LegacyReaderCacheCandidate<Result>[];
+}
+/**
+ * Generic Reader operation descriptor. The Adapter supplies one of these
+ * for the `reader-fetch` operation it supports. The Adapter owns
+ * Provider field mapping, credentials, transport lifecycle, and error
+ * normalization. Commands and shared execution call only these four
+ * methods.
+ *
+ * Same shape as P6-02's `RepositoryOperation` — the surface is
+ * unchanged; only the operation count differs (Reader has one).
+ */
+export interface ReaderOperation<Request, Result> {
+    readonly kind: ReaderOperationKind;
+    /**
+     * Validate the request before any Provider access. Throws
+     * `ValidationError` for missing required fields and
+     * `UnsupportedOptionError` for Provider-specific options the Adapter
+     * does not accept. Validation MUST occur before credential resolution
+     * or transport construction.
+     */
+    validate(request: Request): void;
+    /**
+     * Build the cache identity for a request. Called only after
+     * `validate` succeeds. The Adapter resolves its credential once and
+     * returns full fingerprint, canonical request, and zero or more
+     * legacy candidates. Candidate construction MUST NOT read ambient
+     * environment.
+     */
+    cacheIdentity(request: Request): ReaderCacheIdentity<Request, Result>;
+    /**
+     * Total decoder for cached normalized entries. Accepts an `unknown`
+     * value, validates shape, and returns the typed result or `null`.
+     * NEVER throws, NEVER trusts a generic cast.
+     */
+    decodeCached(value: unknown): Result | null;
+    /**
+     * Invoke the Provider and return the normalized result. The Adapter
+     * closes its transport and never retries inside this method; shared
+     * execution owns retry policy.
+     */
+    invoke(request: Request): Promise<Result>;
+}
+/**
+ * Reader Capability contract. Every Adapter that supports reader
+ * fetching implements this interface and exposes it as
+ * `adapter.reader` (Ticket 03 onwards).
+ */
+export interface ReaderCapability {
+    readonly fetch: ReaderOperation<ReaderFetchRequest, ReaderFetchResult>;
+}
+/**
+ * Decode a Reader fetch result from the cache. Returns the canonical
+ * `ReaderFetchResult` on success, `null` for any malformed value.
+ *
+ * `title: null` is a valid decoded value (the Adapter coerces missing
+ * or blank titles to null before writing; the decoder round-trips it).
+ */
+export declare function decodeReaderFetchResult(value: unknown): ReaderFetchResult | null;
+//# sourceMappingURL=reader.d.ts.map

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

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