scoutline 0.1.0 → 0.2.0

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/search.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Search Capability Contract (DESIGN.md §7, PRD FR-010 through FR-016).
+ *
+ * Defines the normalized meaning shared by every Search Provider.
+ * Commands consume the Capability through `SearchCapability.invoke`,
+ * which returns `SearchSource[]` in the Provider-agnostic shape. All
+ * Provider-specific fields (rank, occurrence count, count, summary
+ * truncation, field projection, presentation) remain command meaning.
+ *
+ * The Cache Identity contract (`SearchCacheIdentity`,
+ * `LegacySearchCacheCandidate`) is declared here so P2-02 can wire
+ * Provider-partitioned cache keys without further type changes.
+ *
+ * Phase 2 implements only this contract. The Z.AI and MiniMax Search
+ * Adapters arrive in P2-03 and P2-04; the production registry arrives
+ * in P2-05. The Provider descriptors advertised in P2-01 already
+ * declare the search Capability, so command wiring can begin once the
+ * Adapters exist.
+ */
+import type { ProviderId } from "../providers/types.js";
+/** Recency filter accepted by Z.AI; MiniMax rejects it. */
+export type SearchRecency = "oneDay" | "oneWeek" | "oneMonth" | "oneYear" | "noLimit";
+/**
+ * Provider controls accepted by the Search Capability. Every field is
+ * optional. MiniMax rejects `domain`, `recency`, `contentSize`, and
+ * `location` with `UNSUPPORTED_OPTION` before any SDK access.
+ */
+export interface SearchControls {
+    domain?: string;
+    recency?: SearchRecency;
+    contentSize?: "medium" | "high";
+    location?: "cn" | "us";
+}
+/**
+ * A Search request. `query` must contain at least one non-whitespace
+ * character; the Capability's `validate` enforces this and throws
+ * `ValidationError` otherwise.
+ */
+export interface SearchRequest {
+    query: string;
+    controls?: Readonly<SearchControls>;
+}
+/**
+ * Normalized Search result. Adapters populate this from their Provider
+ * response shape; commands merge, deduplicate, project, truncate, and
+ * rank downstream. Provider-only fields are discarded.
+ */
+export interface SearchSource {
+    title: string;
+    url: string;
+    summary: string;
+    source?: string;
+    date?: string;
+}
+/**
+ * Provider-owned legacy cache candidate. Old Z.AI keys encode raw
+ * `WebSearchResult[]`; the Adapter supplies the decoder so shared cache
+ * code never inspects Provider response shapes. Invalid decode is a
+ * cache miss.
+ */
+export interface LegacySearchCacheCandidate {
+    readonly key: string;
+    decode(value: unknown): readonly SearchSource[] | null;
+}
+/**
+ * Identity used to read and write a Provider-partitioned cache entry.
+ * `credentialFingerprint` is the full lowercase SHA-256 hex digest of
+ * the active credential and is never hashed a second time by cache
+ * code. Request identity uses recursively key-sorted JSON of only
+ * `query` and Provider controls.
+ */
+export interface SearchCacheIdentity {
+    readonly provider: ProviderId;
+    readonly capability: "search";
+    readonly credentialFingerprint: string;
+    readonly request: Readonly<SearchRequest>;
+    readonly legacyCandidates?: readonly LegacySearchCacheCandidate[];
+}
+/**
+ * Search Capability contract. Every Adapter that supports Search
+ * implements this interface and is consumed by shared execution. The
+ * Adapter owns Provider field mapping; commands call only these three
+ * methods.
+ */
+export interface SearchCapability {
+    /**
+     * Validate a request before any Provider access. Throws
+     * `ValidationError` for an empty or whitespace-only query, and
+     * `UnsupportedOptionError` for Provider-specific options the Adapter
+     * does not accept. Validation must occur before credential resolution
+     * or transport construction.
+     */
+    validate(request: SearchRequest): void;
+    /**
+     * Build the cache identity for a request. Called only after
+     * `validate` succeeds. `compatibility.legacyCount` is the optional
+     * command count; it may enter only `legacyCandidates` and never the
+     * new request identity.
+     */
+    cacheIdentity(request: SearchRequest, compatibility?: {
+        readonly legacyCount?: number;
+    }): SearchCacheIdentity;
+    /**
+     * Invoke the Provider and return normalized sources. The Adapter
+     * closes its transport and never retries inside this method; shared
+     * execution owns retry policy.
+     */
+    invoke(request: SearchRequest): Promise<readonly SearchSource[]>;
+}
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/capabilities/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMxD,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,SAAS,GACT,UAAU,GACV,SAAS,GACT,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,YAAY,EAAE,GAAG,IAAI,CAAC;CACxD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACnE;AAMD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAEvC;;;;;OAKG;IACH,aAAa,CACX,OAAO,EAAE,aAAa,EACtB,aAAa,CAAC,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAChD,mBAAmB,CAAC;IAEvB;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;CAClE"}

package/dist/capabilities/search.js

@@ -0,0 +1,21 @@
+/**
+ * Search Capability Contract (DESIGN.md §7, PRD FR-010 through FR-016).
+ *
+ * Defines the normalized meaning shared by every Search Provider.
+ * Commands consume the Capability through `SearchCapability.invoke`,
+ * which returns `SearchSource[]` in the Provider-agnostic shape. All
+ * Provider-specific fields (rank, occurrence count, count, summary
+ * truncation, field projection, presentation) remain command meaning.
+ *
+ * The Cache Identity contract (`SearchCacheIdentity`,
+ * `LegacySearchCacheCandidate`) is declared here so P2-02 can wire
+ * Provider-partitioned cache keys without further type changes.
+ *
+ * Phase 2 implements only this contract. The Z.AI and MiniMax Search
+ * Adapters arrive in P2-03 and P2-04; the production registry arrives
+ * in P2-05. The Provider descriptors advertised in P2-01 already
+ * declare the search Capability, so command wiring can begin once the
+ * Adapters exist.
+ */
+export {};
+//# sourceMappingURL=search.js.map

package/dist/capabilities/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/capabilities/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/capabilities/vision.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Provider Vision Capability (DESIGN.md §8, PRD FR-020, FR-022 to FR-026,
+ * FR-050, NFR-004, NFR-006).
+ *
+ * Defines the normalized Vision Capability shared by every Provider that
+ * supports single-image interpretation. Commands pass a `VisionRequest`
+ * (a discriminated union over the eight operation shapes) and the
+ * shared `invokeVision` helper:
+ *
+ *   1. Maps the operation to a stable `vision.<operation>` Capability id.
+ *   2. Reads descriptor-level capability metadata (pure; no Adapter
+ *      construction). If the descriptor does not advertise the
+ *      Capability, throws `UnsupportedCapabilityError(provider, ...)`
+ *      BEFORE `descriptor.create()` is called. No credentials, no media,
+ *      no transport, no cache, no fallback Adapter are observed.
+ *   3. Calls `descriptor.create(context)` and defensively double-checks
+ *      the Adapter's `supports(operation)`. If the Adapter says no,
+ *      throws the same error before `invoke` runs.
+ *   4. Calls `adapter.vision.invoke(request)` and returns the normalized
+ *      text. Vision never uses the response cache and never falls back
+ *      to another Provider.
+ *
+ * This module imports no Provider transport and no Provider Adapter.
+ * The error class import below is from `lib/errors.ts` (a shared error
+ * contract, not Provider transport), which is the existing boundary
+ * pattern for the Search Capability Module. The retry wrapper lives
+ * above `invokeVision` and passes a `() => Promise<string>` closure so
+ * Vision can be invoked through `executeProviderOperation("vision",
+ * ...)` (DESIGN.md §10) without coupling this file to that contract.
+ *
+ * P3-01 introduces only the contract + the early-fail ordering proof.
+ * Real Z.AI and MiniMax `vision` Adapters arrive in P3-03; the
+ * built-in descriptor factories in `providers/types.ts` advertise
+ * `vision.<operation>` Capability metadata now so the support check is
+ * wired through descriptor metadata from the start.
+ */
+/**
+ * A Provider-neutral Vision request. Commands construct one of these
+ * shapes from their semantic arguments; Adapters map them to the
+ * Provider's transport shape. Adding a new operation requires extending
+ * this union, the `ProviderCapability` union in `providers/types.ts`,
+ * and the `ALL_VISION_OPERATIONS` set below.
+ */
+export type VisionRequest = {
+    operation: "interpret-image";
+    source: string;
+    instruction: string;
+} | {
+    operation: "ui-artifact";
+    source: string;
+    instruction: string;
+    outputType: "code" | "prompt" | "spec" | "description";
+} | {
+    operation: "extract-text";
+    source: string;
+    instruction: string;
+    programmingLanguage?: string;
+} | {
+    operation: "diagnose-error";
+    source: string;
+    instruction: string;
+    context?: string;
+} | {
+    operation: "diagram";
+    source: string;
+    instruction: string;
+    diagramType?: string;
+} | {
+    operation: "chart";
+    source: string;
+    instruction: string;
+    focus?: string;
+} | {
+    operation: "diff";
+    expectedSource: string;
+    actualSource: string;
+    instruction: string;
+} | {
+    operation: "video";
+    source: string;
+    instruction: string;
+};
+/** Convenience: the set of every supported operation. */
+export type VisionOperation = VisionRequest["operation"];
+/** Every operation that exists in the discriminated union. */
+export declare const ALL_VISION_OPERATIONS: ReadonlySet<VisionOperation>;
+/**
+ * Stable Capability id for a Vision operation. Each id matches a member
+ * of the `ProviderCapability` union declared in `providers/types.ts`.
+ * This mapping is the single source of truth: Adapters advertise the id;
+ * `invokeVision` reads it; commands never branch on the id directly.
+ */
+export declare function visionOperationToCapability(operation: VisionOperation): "vision.interpret-image" | "vision.ui-artifact" | "vision.extract-text" | "vision.diagnose-error" | "vision.diagram" | "vision.chart" | "vision.diff" | "vision.video";
+/**
+ * Vision Capability contract. Every Adapter that supports a Vision
+ * operation implements this interface and exposes it as `adapter.vision`.
+ * The Adapter owns Provider field mapping, transport, and credentials;
+ * commands call only these two methods.
+ *
+ * `supports` is a pure metadata check. It MUST NOT construct a
+ * transport, read a credential, inspect a source, or perform I/O. The
+ * shared `invokeVision` helper uses descriptor metadata first and
+ * `supports` only as a defensive double-check after `create()`.
+ */
+export interface VisionCapability {
+    /**
+     * Report whether the Adapter can perform `operation` against the
+     * current environment. Pure metadata; no construction.
+     */
+    supports(operation: VisionOperation): boolean;
+    /**
+     * Invoke the Provider and return the normalized text result. The
+     * Adapter owns credentials, transport lifecycle, Provider field
+     * mapping, and failure normalization. The Adapter closes its
+     * transport and never retries inside this method.
+     */
+    invoke(request: VisionRequest): Promise<string>;
+}
+/**
+ * Minimal Adapter shape `invokeVision` needs. Defined here (instead of
+ * importing from `providers/types.ts`) so this file remains free of
+ * any Provider imports — the Boundary rule for Capability Modules
+ * (ARCHITECTURE.md §2).
+ *
+ * The descriptor's `create(context)` returns a `ProviderAdapter`; the
+ * shared helper accepts anything that exposes `id` and an optional
+ * `vision` VisionCapability, matching the Phase 3 ProviderAdapter
+ * shape defined in DESIGN.md §5.
+ */
+export interface VisionInvocationDescriptor {
+    readonly id: string;
+    capabilities(): ReadonlySet<string>;
+    create(context: {
+        readonly env: NodeJS.ProcessEnv;
+    }): {
+        readonly id: string;
+        readonly vision?: VisionCapability;
+    };
+}
+/**
+ * Invoke a Vision request through a Provider descriptor. The support
+ * check happens BEFORE `descriptor.create()` (using descriptor
+ * metadata) and is then double-checked against the Adapter's
+ * `supports` after construction. Failures throw
+ * `UnsupportedCapabilityError` and never touch credentials, media,
+ * transport, cache, or a fallback Adapter.
+ *
+ * Phase 3 P3-01 introduces the contract and the early-fail ordering
+ * proof; Phase 3 P3-03 supplies the real Adapter implementations.
+ * Until then the built-in descriptors advertise metadata so the
+ * ordering is provable today.
+ */
+export declare function invokeVision(descriptor: VisionInvocationDescriptor, request: VisionRequest, context: {
+    readonly env: NodeJS.ProcessEnv;
+}): Promise<string>;
+//# sourceMappingURL=vision.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vision.d.ts","sourceRoot":"","sources":["../../src/capabilities/vision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAQH;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB;IACE,SAAS,EAAE,iBAAiB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,GACD;IACE,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,aAAa,CAAC;CACxD,GACD;IACE,SAAS,EAAE,cAAc,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,GACD;IACE,SAAS,EAAE,gBAAgB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACD;IACE,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACD;IACE,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACD;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,GACD;IACE,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEN,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;AAEzD,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,eAAe,CAS7D,CAAC;AAMH;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,eAAe,GAExB,wBAAwB,GACxB,oBAAoB,GACpB,qBAAqB,GACrB,uBAAuB,GACvB,gBAAgB,GAChB,cAAc,GACd,aAAa,GACb,cAAc,CAmBjB;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC;IAE9C;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACjD;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,YAAY,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;KAAE,GAAG;QACpD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;KACpC,CAAC;CACH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,0BAA0B,EACtC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,GAC3C,OAAO,CAAC,MAAM,CAAC,CAuBjB"}

package/dist/capabilities/vision.js

@@ -0,0 +1,111 @@
+/**
+ * Provider Vision Capability (DESIGN.md §8, PRD FR-020, FR-022 to FR-026,
+ * FR-050, NFR-004, NFR-006).
+ *
+ * Defines the normalized Vision Capability shared by every Provider that
+ * supports single-image interpretation. Commands pass a `VisionRequest`
+ * (a discriminated union over the eight operation shapes) and the
+ * shared `invokeVision` helper:
+ *
+ *   1. Maps the operation to a stable `vision.<operation>` Capability id.
+ *   2. Reads descriptor-level capability metadata (pure; no Adapter
+ *      construction). If the descriptor does not advertise the
+ *      Capability, throws `UnsupportedCapabilityError(provider, ...)`
+ *      BEFORE `descriptor.create()` is called. No credentials, no media,
+ *      no transport, no cache, no fallback Adapter are observed.
+ *   3. Calls `descriptor.create(context)` and defensively double-checks
+ *      the Adapter's `supports(operation)`. If the Adapter says no,
+ *      throws the same error before `invoke` runs.
+ *   4. Calls `adapter.vision.invoke(request)` and returns the normalized
+ *      text. Vision never uses the response cache and never falls back
+ *      to another Provider.
+ *
+ * This module imports no Provider transport and no Provider Adapter.
+ * The error class import below is from `lib/errors.ts` (a shared error
+ * contract, not Provider transport), which is the existing boundary
+ * pattern for the Search Capability Module. The retry wrapper lives
+ * above `invokeVision` and passes a `() => Promise<string>` closure so
+ * Vision can be invoked through `executeProviderOperation("vision",
+ * ...)` (DESIGN.md §10) without coupling this file to that contract.
+ *
+ * P3-01 introduces only the contract + the early-fail ordering proof.
+ * Real Z.AI and MiniMax `vision` Adapters arrive in P3-03; the
+ * built-in descriptor factories in `providers/types.ts` advertise
+ * `vision.<operation>` Capability metadata now so the support check is
+ * wired through descriptor metadata from the start.
+ */
+import { UnsupportedCapabilityError } from "../lib/errors.js";
+/** Every operation that exists in the discriminated union. */
+export const ALL_VISION_OPERATIONS = new Set([
+    "interpret-image",
+    "ui-artifact",
+    "extract-text",
+    "diagnose-error",
+    "diagram",
+    "chart",
+    "diff",
+    "video",
+]);
+// ---------------------------------------------------------------------------
+// Operation → Capability id mapping (no Provider imports)
+// ---------------------------------------------------------------------------
+/**
+ * Stable Capability id for a Vision operation. Each id matches a member
+ * of the `ProviderCapability` union declared in `providers/types.ts`.
+ * This mapping is the single source of truth: Adapters advertise the id;
+ * `invokeVision` reads it; commands never branch on the id directly.
+ */
+export function visionOperationToCapability(operation) {
+    switch (operation) {
+        case "interpret-image":
+            return "vision.interpret-image";
+        case "ui-artifact":
+            return "vision.ui-artifact";
+        case "extract-text":
+            return "vision.extract-text";
+        case "diagnose-error":
+            return "vision.diagnose-error";
+        case "diagram":
+            return "vision.diagram";
+        case "chart":
+            return "vision.chart";
+        case "diff":
+            return "vision.diff";
+        case "video":
+            return "vision.video";
+    }
+}
+/**
+ * Invoke a Vision request through a Provider descriptor. The support
+ * check happens BEFORE `descriptor.create()` (using descriptor
+ * metadata) and is then double-checked against the Adapter's
+ * `supports` after construction. Failures throw
+ * `UnsupportedCapabilityError` and never touch credentials, media,
+ * transport, cache, or a fallback Adapter.
+ *
+ * Phase 3 P3-01 introduces the contract and the early-fail ordering
+ * proof; Phase 3 P3-03 supplies the real Adapter implementations.
+ * Until then the built-in descriptors advertise metadata so the
+ * ordering is provable today.
+ */
+export async function invokeVision(descriptor, request, context) {
+    const capabilityId = visionOperationToCapability(request.operation);
+    // Step 1: descriptor-level metadata. NO create(), NO construction.
+    if (!descriptor.capabilities().has(capabilityId)) {
+        throw new UnsupportedCapabilityError(descriptor.id, capabilityId);
+    }
+    // Step 2: create() is allowed now — it is side-effect-free, only
+    // captures the injected env. Credentials, transport, and SDK are
+    // built lazily inside Capability invocation.
+    const adapter = descriptor.create(context);
+    // Step 3: defensive double-check against the Adapter's own metadata.
+    // If the Adapter says no, fail closed before invoke runs.
+    const vision = adapter.vision;
+    if (!vision || !vision.supports(request.operation)) {
+        throw new UnsupportedCapabilityError(descriptor.id, capabilityId);
+    }
+    // Step 4: invoke. No cache lookup, no fallback Adapter. Retries live
+    // above this call in `executeProviderOperation("vision", ...)`.
+    return vision.invoke(request);
+}
+//# sourceMappingURL=vision.js.map

package/dist/capabilities/vision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.js","sourceRoot":"","sources":["../../src/capabilities/vision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAgE9D,8DAA8D;AAC9D,MAAM,CAAC,MAAM,qBAAqB,GAAiC,IAAI,GAAG,CAAC;IACzE,iBAAiB;IACjB,aAAa;IACb,cAAc;IACd,gBAAgB;IAChB,SAAS;IACT,OAAO;IACP,MAAM;IACN,OAAO;CACR,CAAC,CAAC;AAEH,8EAA8E;AAC9E,0DAA0D;AAC1D,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CACzC,SAA0B;IAU1B,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,iBAAiB;YACpB,OAAO,wBAAwB,CAAC;QAClC,KAAK,aAAa;YAChB,OAAO,oBAAoB,CAAC;QAC9B,KAAK,cAAc;YACjB,OAAO,qBAAqB,CAAC;QAC/B,KAAK,gBAAgB;YACnB,OAAO,uBAAuB,CAAC;QACjC,KAAK,SAAS;YACZ,OAAO,gBAAgB,CAAC;QAC1B,KAAK,OAAO;YACV,OAAO,cAAc,CAAC;QACxB,KAAK,MAAM;YACT,OAAO,aAAa,CAAC;QACvB,KAAK,OAAO;YACV,OAAO,cAAc,CAAC;IAC1B,CAAC;AACH,CAAC;AAyDD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAsC,EACtC,OAAsB,EACtB,OAA4C;IAE5C,MAAM,YAAY,GAAG,2BAA2B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEpE,mEAAmE;IACnE,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,0BAA0B,CAAC,UAAU,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;IACpE,CAAC;IAED,iEAAiE;IACjE,iEAAiE;IACjE,6CAA6C;IAC7C,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAE3C,qEAAqE;IACrE,0DAA0D;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,0BAA0B,CAAC,UAAU,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;IACpE,CAAC;IAED,qEAAqE;IACrE,gEAAgE;IAChE,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC"}

package/dist/command-invocation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Command Invocation Seam (DESIGN.md §2).
+ *
+ * This Module defines the pure invocation contract that separates
+ * command behaviour from process effects. `invokeCommand` owns
+ * invocation-local presentation, notice storage, and error conversion.
+ * The Node Adapter is the only Module that touches process streams,
+ * TTY state, and `process.exitCode`.
+ *
+ * Requirements: NFR-002, NFR-003, NFR-007.
+ */
+import type { OutputMode } from "./lib/output.js";
+export type TextOutputMode = "compact" | "markdown" | "refs" | "tty";
+export type CommandPresentations = Readonly<Partial<Record<TextOutputMode, string>>>;
+export interface DataCommandResult<T = unknown> {
+    readonly kind: "data";
+    readonly data: T;
+    readonly presentations?: CommandPresentations;
+    readonly exitCode?: number;
+}
+export interface TextCommandResult {
+    readonly kind: "text";
+    readonly text: string;
+    readonly exitCode?: number;
+}
+export type CommandResult<T = unknown> = DataCommandResult<T> | TextCommandResult;
+export interface CommandContext {
+    readonly stdinIsTTY: boolean;
+    readStdin(): Promise<string>;
+    notice(message: string): void;
+}
+export interface CommandInvocationAdapter {
+    readonly stdoutIsTTY: boolean;
+    readonly stdinIsTTY: boolean;
+    readonly environmentOutputMode?: string;
+    readStdin(): Promise<string>;
+    writeStdout(value: string): void;
+    writeStderr(value: string): void;
+    runQuietly<T>(operation: () => Promise<T>): Promise<T>;
+    setExitCode(value: number): void;
+}
+/**
+ * Run command behaviour through the invocation seam.
+ *
+ * 1. Create invocation-local context and notice storage.
+ * 2. Run command behaviour through `runQuietly`.
+ * 3. `runQuietly` restores dependency logging before returning.
+ * 4. Flush notices to stderr in encounter order.
+ * 5. Select a presentation override or the base data.
+ * 6. Write one final successful value to stdout.
+ * 7. Convert a thrown error into one structured stderr value.
+ * 8. Return an exit status without terminating the process.
+ *
+ * The trailing newline is appended at the Node Adapter boundary, not
+ * here, so `invokeCommand` itself is process-effect-free.
+ */
+export declare function invokeCommand(adapter: CommandInvocationAdapter, behavior: (context: CommandContext) => Promise<CommandResult>, outputMode: OutputMode, now?: () => number, secrets?: string[]): Promise<number>;
+//# sourceMappingURL=command-invocation.d.ts.map

package/dist/command-invocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-invocation.d.ts","sourceRoot":"","sources":["../src/command-invocation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKlD,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC;AAErE,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AAErF,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,IAAI,iBAAiB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC;AAElF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,UAAU,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAkCD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,aAAa,CAAC,EAC7D,UAAU,EAAE,UAAU,EACtB,GAAG,GAAE,MAAM,MAAiB,EAC5B,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,MAAM,CAAC,CAyCjB"}