@apifuse/provider-sdk 2.2.0-beta.60 → 2.2.0-beta.62

package/dist/handle.d.ts

@@ -0,0 +1,208 @@
+/**
+ * LLM-friendly handles (ADR-0012): authoring API.
+ *
+ * A handle is a short string an LLM copies from one tool output into a later
+ * tool input. It is a lookup key to server state, never a carrier of encrypted
+ * payload. This module defines handle *kinds* (`defineCursor`, `defineDraft`),
+ * the schema helper `kind.field()`, the plain-value chooser `pick()`, and
+ * `HandleError`. The runtime (`ctx.handle`) lives in `runtime/handle.ts`.
+ */
+import { type ZodString, type ZodType, z } from "zod";
+import { ProviderError, type ProviderErrorOptions } from "./errors.js";
+import { type HandleAccess, type HandleFieldMeta, type HandleIssuedBy, type HandleKindDeclaration, type HandleKindType } from "./handle-meta.js";
+import type { ProviderStateDurationString } from "./types.js";
+export type { HandleAccess, HandleFieldMeta, HandleIssuedBy, HandleKindDeclaration, HandleKindType, };
+export type HandleStrength = "standard" | "high";
+/** Words issued per handle: 2 for bound kinds, 4 for public, 5 for high-strength public. */
+export type HandleWordCount = 2 | 4 | 5;
+export interface HandleKindBase<TSchema extends ZodType = ZodType> extends HandleKindDeclaration {
+    /**
+     * Zod schema validated on `create`/`update`. Writes accept its *input* type
+     * (`InputOf`); stored records and callbacks carry its *output* type (`DataOf`).
+     */
+    readonly schema: TSchema;
+    /** Live-entry quota of the kind's namespace (per connection for bound kinds). */
+    readonly maxEntries: number;
+    /** Maximum JSON-encoded record size in bytes. */
+    readonly maxValueBytes: number;
+    /** Number of words the runtime issues for this kind. */
+    readonly wordCount: HandleWordCount;
+    /**
+     * Schema for the handle field, usable in output and input positions. Carries
+     * the `x-apifuse-handle` meta and an SDK-owned English description.
+     */
+    field(): ZodString;
+}
+export interface CursorKind<TSchema extends ZodType = ZodType> extends HandleKindBase<TSchema> {
+    readonly type: "cursor";
+    readonly ttl: ProviderStateDurationString;
+    readonly ttlMs: number;
+    readonly strength: HandleStrength;
+}
+export interface DraftKind<TSchema extends ZodType = ZodType, TResultSchema extends ZodType | undefined = ZodType | undefined> extends HandleKindBase<TSchema> {
+    readonly type: "draft";
+    /** `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped, 4-5 words. */
+    readonly access: HandleAccess;
+    /** Public only; `"high"` forces 5 words. Always `"standard"` for bound drafts. */
+    readonly strength: HandleStrength;
+    readonly ttl: {
+        readonly idle: ProviderStateDurationString;
+        readonly max: ProviderStateDurationString;
+    };
+    readonly idleTtlMs: number;
+    readonly maxTtlMs: number;
+    readonly resultTtl: ProviderStateDurationString;
+    readonly resultTtlMs: number;
+    /** Optional schema describing the commit result; type-level only at runtime. */
+    readonly result: TResultSchema | undefined;
+}
+export type HandleKind = CursorKind<any> | DraftKind<any, any>;
+/** Stored record data type (schema output); what `read`, `update`, and `commit` callbacks receive. */
+export type DataOf<K extends HandleKind> = z.output<K["schema"]>;
+/** What `create` and `update` accept (schema input); differs from `DataOf` when the schema transforms or defaults. */
+export type InputOf<K extends HandleKind> = z.input<K["schema"]>;
+export type ResultOf<K extends HandleKind> = K extends DraftKind<any, infer R> ? (R extends ZodType ? z.output<R> : unknown) : never;
+export type HandleStatus = "active" | "committing" | "committed";
+export interface HandleRecord<K extends HandleKind> {
+    /** Canonical handle string (`<kind>_<word>-<word>...`). */
+    readonly handle: string;
+    readonly kind: string;
+    readonly status: HandleStatus;
+    readonly data: DataOf<K>;
+    readonly result?: ResultOf<K>;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+}
+export interface HandleCommitResult<K extends HandleKind> {
+    readonly status: "committed" | "replayed";
+    readonly handle: string;
+    readonly result: ResultOf<K>;
+}
+export interface HandleContext {
+    /** Validates `data` with `kind.schema`, stores it, and returns the canonical handle. */
+    create<K extends HandleKind>(kind: K, data: InputOf<K>): Promise<string>;
+    /**
+     * Same as `create` but returns the full record (`handle`, `status`, `data`,
+     * `createdAt`, `expiresAt`) so a provider can expose `expires_at` without
+     * recomputing ttl math. `create` is the string-returning shortcut.
+     */
+    createRecord<K extends HandleKind>(kind: K, data: InputOf<K>): Promise<HandleRecord<K>>;
+    /** Tolerantly parses `handle`, loads the record; drafts get their idle TTL touched. */
+    read<K extends HandleKind>(kind: K, handle: string): Promise<HandleRecord<K>>;
+    /** CAS update of an active draft (3 retries) with sliding TTL. */
+    update<K extends DraftKind>(kind: K, handle: string, updater: (data: DataOf<K>) => InputOf<K> | Promise<InputOf<K>>): Promise<HandleRecord<K>>;
+    /** One-shot commit with result replay; see runtime docs for the state machine. */
+    commit<K extends DraftKind>(kind: K, handle: string, work: (data: DataOf<K>) => Promise<ResultOf<K>>): Promise<HandleCommitResult<K>>;
+    /** Deletes the record; idempotent. */
+    discard<K extends HandleKind>(kind: K, handle: string): Promise<void>;
+}
+export type HandleOperation = "create" | "read" | "update" | "commit" | "discard";
+export type HandleTelemetryOutcome = "success" | "not_found" | "expired" | "invalid" | "kind_mismatch" | "busy" | "replayed" | "error";
+/** Allowlisted metadata only; handle values, data, and results are never included. */
+export interface HandleTelemetryEvent {
+    readonly providerId: string;
+    readonly kind: string;
+    readonly type: HandleKindType;
+    readonly operation: HandleOperation;
+    readonly outcome: HandleTelemetryOutcome;
+    /** `"none"` or the sorted normalization classes joined by `+`. */
+    readonly normalization: string;
+    readonly words: number;
+}
+export type HandleErrorCode = "HANDLE_INVALID" | "HANDLE_NOT_FOUND" | "HANDLE_EXPIRED" | "HANDLE_KIND_MISMATCH" | "HANDLE_BUSY" | "HANDLE_COMMITTED" | "HANDLE_CONNECTION_REQUIRED" | "HANDLE_STORAGE_UNAVAILABLE" | "HANDLE_TOO_LARGE" | "HANDLE_INVALID_DATA" | "PICK_NOT_OFFERED";
+export type HandleErrorOptions = Omit<ProviderErrorOptions, "code"> & {
+    /** Kind name the error relates to, when known. */
+    readonly kind?: string;
+};
+export declare class HandleError extends ProviderError {
+    readonly handleCode: HandleErrorCode;
+    readonly kind?: string;
+    constructor(code: HandleErrorCode, message: string, options?: HandleErrorOptions);
+    get code(): HandleErrorCode;
+}
+/**
+ * Recognizes handle errors across duplicate SDK module copies (packaged CLI
+ * `src/*` runtime vs provider `dist/*` import), where `instanceof` splits.
+ */
+export declare function isHandleError(value: unknown): value is HandleError;
+/**
+ * Standard recovery sentence appended to every handle error message so the LLM
+ * knows the next action without provider-specific wording.
+ */
+export declare function handleRecoverySentence(kind: {
+    readonly fieldName: string;
+    readonly issuedBy?: HandleIssuedBy;
+}): string;
+/** Parses a `ProviderStateDurationString` to milliseconds; throws on invalid or non-positive input. */
+export declare function parseHandleDurationMs(value: ProviderStateDurationString, label: string): number;
+export interface DefineCursorOptions<TSchema extends ZodType> {
+    /** Kind name, `/^[a-z]{2,12}$/`; becomes the handle prefix. */
+    readonly name: string;
+    /** Schema property key carrying the handle. Default `${name}_token`. */
+    readonly fieldName?: string;
+    readonly schema: TSchema;
+    readonly ttl: ProviderStateDurationString;
+    /** `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped, 4-5 words. */
+    readonly access?: HandleAccess;
+    /** Required when public. Bound default 200 per connection. */
+    readonly maxEntries?: number;
+    /** Default 16,000. */
+    readonly maxValueBytes?: number;
+    /** Public only; `"high"` forces 5 words. Auto-high when ttl > 1h. */
+    readonly strength?: HandleStrength;
+    /** Operation key(s) that issue this handle; used in error text and lint. */
+    readonly issuedBy?: HandleIssuedBy;
+}
+export interface DefineDraftOptions<TSchema extends ZodType, TResultSchema extends ZodType | undefined> {
+    readonly name: string;
+    readonly fieldName?: string;
+    readonly schema: TSchema;
+    /** Optional schema of the commit result (type-level). */
+    readonly result?: TResultSchema;
+    readonly ttl: {
+        readonly idle: ProviderStateDurationString;
+        readonly max: ProviderStateDurationString;
+    };
+    /** How long a committed record stays for replay. Default "24h". */
+    readonly resultTtl?: ProviderStateDurationString;
+    /**
+     * `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped
+     * draft for connectionless providers (`auth: none`), 4-5 words, `maxEntries`
+     * required; every lookup failure collapses to `HANDLE_INVALID`.
+     */
+    readonly access?: HandleAccess;
+    /** Required when public. Bound default 200 per connection. */
+    readonly maxEntries?: number;
+    /** Default 64,000. */
+    readonly maxValueBytes?: number;
+    /** Public only; `"high"` forces 5 words. Auto-high when ttl.max > 1h. */
+    readonly strength?: HandleStrength;
+    /** Operation key(s) that issue this handle; used in error text and lint. */
+    readonly issuedBy?: HandleIssuedBy;
+}
+/** Defines an immutable cursor kind (pagination, offered option lists). */
+export declare function defineCursor<TSchema extends ZodType>(options: DefineCursorOptions<TSchema>): CursorKind<TSchema>;
+/**
+ * Defines a mutable draft kind (multi-turn forms with one-shot commit). Bound
+ * by default; `access: "public"` opts a connectionless provider into a
+ * provider-scoped draft under the public guessing analysis (ADR-0012 D3).
+ */
+export declare function defineDraft<TSchema extends ZodType, TResultSchema extends ZodType | undefined = undefined>(options: DefineDraftOptions<TSchema, TResultSchema>): DraftKind<TSchema, TResultSchema>;
+export declare function isDraftKind(kind: HandleKind): kind is DraftKind<any, any>;
+export declare function isCursorKind(kind: HandleKind): kind is CursorKind<any>;
+export interface PickOptions<T> {
+    /** Input field name, used in the error message. */
+    readonly field: string;
+    /** Item property compared against `value`. Default = `field`. */
+    readonly by?: keyof T & string;
+    /** Operation(s) that listed the items; used in the error message when known. */
+    readonly issuedBy?: HandleIssuedBy;
+}
+/**
+ * Chooses one offered item by a plain value the LLM copied from the offer.
+ * Exact match first, then a unique case-insensitive trimmed match; otherwise
+ * `PICK_NOT_OFFERED` with the allowed values so the LLM can self-correct. The
+ * server holds the offer, so a fabricated value fails here instead of reaching
+ * upstream. This is the "one handle per offer + plain picks" half of ADR-0012.
+ */
+export declare function pick<T extends Record<string, unknown>>(items: readonly T[], value: string, options: PickOptions<T>): T;

package/dist/handle.js

@@ -0,0 +1,299 @@
+/**
+ * LLM-friendly handles (ADR-0012): authoring API.
+ *
+ * A handle is a short string an LLM copies from one tool output into a later
+ * tool input. It is a lookup key to server state, never a carrier of encrypted
+ * payload. This module defines handle *kinds* (`defineCursor`, `defineDraft`),
+ * the schema helper `kind.field()`, the plain-value chooser `pick()`, and
+ * `HandleError`. The runtime (`ctx.handle`) lives in `runtime/handle.ts`.
+ */
+import { z } from "zod";
+import { brandHandleError, hasHandleErrorBrand, ProviderError, } from "./errors.js";
+import { APIFUSE_HANDLE_META_KEY, formatHandleIssuers, handleFieldDescription, HANDLE_KIND_NAME_PATTERN, isHandleIssuedBy, } from "./handle-meta.js";
+import { BOUND_HANDLE_WORD_COUNT, HIGH_PUBLIC_HANDLE_WORD_COUNT, PUBLIC_HANDLE_WORD_COUNT, } from "./runtime/handle-wordlist.js";
+/** Public kinds whose (max) ttl exceeds this are issued with five words (auto-high). */
+const AUTO_HIGH_TTL_MS = 3_600_000;
+const DEFAULT_BOUND_MAX_ENTRIES = 200;
+const DEFAULT_CURSOR_MAX_VALUE_BYTES = 16_000;
+const DEFAULT_DRAFT_MAX_VALUE_BYTES = 64_000;
+const DEFAULT_RESULT_TTL = "24h";
+const HANDLE_ERROR_DEFAULTS = {
+    HANDLE_INVALID: { category: "input_validation", retryable: false },
+    HANDLE_NOT_FOUND: { category: "input_validation", retryable: false },
+    HANDLE_EXPIRED: { category: "input_validation", retryable: false },
+    HANDLE_KIND_MISMATCH: { category: "input_validation", retryable: false },
+    HANDLE_BUSY: { category: "internal_error", retryable: true },
+    HANDLE_COMMITTED: { category: "input_validation", retryable: false },
+    HANDLE_CONNECTION_REQUIRED: { category: "internal_error", retryable: false },
+    HANDLE_STORAGE_UNAVAILABLE: { category: "internal_error", retryable: false },
+    HANDLE_TOO_LARGE: { category: "internal_error", retryable: false },
+    HANDLE_INVALID_DATA: { category: "internal_error", retryable: false },
+    PICK_NOT_OFFERED: { category: "input_validation", retryable: false },
+};
+export class HandleError extends ProviderError {
+    handleCode;
+    kind;
+    constructor(code, message, options = {}) {
+        const { kind, ...rest } = options;
+        const defaults = HANDLE_ERROR_DEFAULTS[code];
+        super(message, {
+            category: defaults.category,
+            retryable: defaults.retryable,
+            ...rest,
+            code,
+        });
+        this.name = "HandleError";
+        this.handleCode = code;
+        this.kind = kind;
+        brandHandleError(this);
+    }
+    get code() {
+        return this.handleCode;
+    }
+}
+/**
+ * Recognizes handle errors across duplicate SDK module copies (packaged CLI
+ * `src/*` runtime vs provider `dist/*` import), where `instanceof` splits.
+ */
+export function isHandleError(value) {
+    return value instanceof HandleError || hasHandleErrorBrand(value);
+}
+/**
+ * Standard recovery sentence appended to every handle error message so the LLM
+ * knows the next action without provider-specific wording.
+ */
+export function handleRecoverySentence(kind) {
+    const issuers = formatHandleIssuers(kind.issuedBy);
+    if (issuers) {
+        return `Call ${issuers} again and pass the new \`${kind.fieldName}\` exactly as returned.`;
+    }
+    return `Request a new \`${kind.fieldName}\` and pass it exactly as returned.`;
+}
+// ---------------------------------------------------------------------------
+// Durations
+// ---------------------------------------------------------------------------
+const SHORT_DURATION_PATTERN = /^(\d+)(ms|s|m|h|d)$/;
+const ISO_DURATION_PATTERN = /^PT(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?$/;
+/** Parses a `ProviderStateDurationString` to milliseconds; throws on invalid or non-positive input. */
+export function parseHandleDurationMs(value, label) {
+    const short = SHORT_DURATION_PATTERN.exec(value);
+    let ms;
+    if (short) {
+        const amount = Number(short[1]);
+        const unit = short[2];
+        const multiplier = unit === "ms"
+            ? 1
+            : unit === "s"
+                ? 1_000
+                : unit === "m"
+                    ? 60_000
+                    : unit === "h"
+                        ? 3_600_000
+                        : 86_400_000;
+        ms = amount * multiplier;
+    }
+    else {
+        const iso = ISO_DURATION_PATTERN.exec(value);
+        if (iso && (iso[1] !== undefined || iso[2] !== undefined || iso[3] !== undefined)) {
+            ms =
+                Number(iso[1] ?? 0) * 3_600_000 +
+                    Number(iso[2] ?? 0) * 60_000 +
+                    Number(iso[3] ?? 0) * 1_000;
+        }
+    }
+    if (ms === undefined || !Number.isFinite(ms) || ms <= 0) {
+        throw new Error(`Handle kind ${label} must be a positive duration such as "10m", "2h", or "PT30M" (received ${JSON.stringify(value)}).`);
+    }
+    return Math.floor(ms);
+}
+function assertKindName(name, define) {
+    if (typeof name !== "string" || !HANDLE_KIND_NAME_PATTERN.test(name)) {
+        throw new Error(`${define}: kind name must match ${HANDLE_KIND_NAME_PATTERN} (2-12 lowercase letters, no digits or separators) so it never fuses with the word body; received ${JSON.stringify(name)}.`);
+    }
+}
+function assertFieldName(fieldName, define) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(fieldName)) {
+        throw new Error(`${define}: fieldName must be a plain identifier usable as a schema property key; received ${JSON.stringify(fieldName)}.`);
+    }
+}
+function assertPositiveInteger(value, label, define) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`${define}: ${label} must be a positive integer; received ${String(value)}.`);
+    }
+}
+function assertAccess(value, define) {
+    if (value !== "bound" && value !== "public") {
+        throw new Error(`${define}: access must be "bound" or "public"; received ${String(value)}.`);
+    }
+}
+function assertStrength(value, define) {
+    if (value !== "standard" && value !== "high") {
+        throw new Error(`${define}: strength must be "standard" or "high"; received ${String(value)}.`);
+    }
+}
+/** Validates `issuedBy` and returns a frozen copy for lists; `undefined` stays undefined. */
+function normalizeIssuedBy(value, define, name) {
+    if (value === undefined)
+        return undefined;
+    if (!isHandleIssuedBy(value) || (typeof value === "string" ? value.length === 0 : false)) {
+        throw new Error(`${define}: "${name}" issuedBy must be an operation key or a non-empty list of operation keys; received ${JSON.stringify(value)}.`);
+    }
+    if (typeof value === "string")
+        return value;
+    if (value.some((operation) => operation.length === 0)) {
+        throw new Error(`${define}: "${name}" issuedBy must not contain empty operation keys.`);
+    }
+    return Object.freeze([...value]);
+}
+/** Word count for a kind: 2 bound; public 4, or 5 when high strength or the lifetime exceeds 1h. */
+function wordCountFor(access, strength, lifetimeMs) {
+    if (access === "bound")
+        return BOUND_HANDLE_WORD_COUNT;
+    return strength === "high" || lifetimeMs > AUTO_HIGH_TTL_MS
+        ? HIGH_PUBLIC_HANDLE_WORD_COUNT
+        : PUBLIC_HANDLE_WORD_COUNT;
+}
+function createHandleField(meta) {
+    const described = z.string().min(1).describe(handleFieldDescription(meta));
+    // zod v4 `.meta()` replaces the registry entry, so carry the description over.
+    const existing = described.meta() ?? {};
+    return described.meta({ ...existing, [APIFUSE_HANDLE_META_KEY]: meta });
+}
+/** Defines an immutable cursor kind (pagination, offered option lists). */
+export function defineCursor(options) {
+    const define = "defineCursor";
+    assertKindName(options.name, define);
+    const fieldName = options.fieldName ?? `${options.name}_token`;
+    assertFieldName(fieldName, define);
+    const access = options.access ?? "bound";
+    assertAccess(access, define);
+    const ttlMs = parseHandleDurationMs(options.ttl, `"${options.name}" ttl`);
+    const strength = options.strength ?? "standard";
+    assertStrength(strength, define);
+    const issuedBy = normalizeIssuedBy(options.issuedBy, define, options.name);
+    if (access === "public" && options.maxEntries === undefined) {
+        throw new Error(`${define}: public cursor "${options.name}" must declare maxEntries (provider-wide live-entry quota).`);
+    }
+    const maxEntries = options.maxEntries ?? DEFAULT_BOUND_MAX_ENTRIES;
+    assertPositiveInteger(maxEntries, "maxEntries", define);
+    const maxValueBytes = options.maxValueBytes ?? DEFAULT_CURSOR_MAX_VALUE_BYTES;
+    assertPositiveInteger(maxValueBytes, "maxValueBytes", define);
+    const wordCount = wordCountFor(access, strength, ttlMs);
+    const meta = {
+        kind: options.name,
+        type: "cursor",
+        fieldName,
+        ...(issuedBy ? { issuedBy } : {}),
+    };
+    return Object.freeze({
+        name: options.name,
+        type: "cursor",
+        fieldName,
+        access,
+        issuedBy,
+        schema: options.schema,
+        ttl: options.ttl,
+        ttlMs,
+        strength,
+        maxEntries,
+        maxValueBytes,
+        wordCount,
+        field: () => createHandleField(meta),
+    });
+}
+/**
+ * Defines a mutable draft kind (multi-turn forms with one-shot commit). Bound
+ * by default; `access: "public"` opts a connectionless provider into a
+ * provider-scoped draft under the public guessing analysis (ADR-0012 D3).
+ */
+export function defineDraft(options) {
+    const define = "defineDraft";
+    assertKindName(options.name, define);
+    const fieldName = options.fieldName ?? `${options.name}_token`;
+    assertFieldName(fieldName, define);
+    if (!options.ttl || typeof options.ttl !== "object") {
+        throw new Error(`${define}: draft "${options.name}" ttl must be { idle, max }.`);
+    }
+    const idleTtlMs = parseHandleDurationMs(options.ttl.idle, `"${options.name}" ttl.idle`);
+    const maxTtlMs = parseHandleDurationMs(options.ttl.max, `"${options.name}" ttl.max`);
+    if (idleTtlMs > maxTtlMs) {
+        throw new Error(`${define}: draft "${options.name}" ttl.idle (${idleTtlMs}ms) must not exceed ttl.max (${maxTtlMs}ms).`);
+    }
+    const resultTtl = options.resultTtl ?? DEFAULT_RESULT_TTL;
+    const resultTtlMs = parseHandleDurationMs(resultTtl, `"${options.name}" resultTtl`);
+    const access = options.access ?? "bound";
+    assertAccess(access, define);
+    const strength = options.strength ?? "standard";
+    assertStrength(strength, define);
+    if (access === "bound" && strength !== "standard") {
+        throw new Error(`${define}: draft "${options.name}" strength applies to public drafts only; bound drafts are always two words.`);
+    }
+    const issuedBy = normalizeIssuedBy(options.issuedBy, define, options.name);
+    if (access === "public" && options.maxEntries === undefined) {
+        throw new Error(`${define}: public draft "${options.name}" must declare maxEntries (provider-wide live-entry quota).`);
+    }
+    const maxEntries = options.maxEntries ?? DEFAULT_BOUND_MAX_ENTRIES;
+    assertPositiveInteger(maxEntries, "maxEntries", define);
+    const maxValueBytes = options.maxValueBytes ?? DEFAULT_DRAFT_MAX_VALUE_BYTES;
+    assertPositiveInteger(maxValueBytes, "maxValueBytes", define);
+    // A public draft's guessable lifetime is its hard `max` ttl (idle only shortens it).
+    const wordCount = wordCountFor(access, strength, maxTtlMs);
+    const meta = {
+        kind: options.name,
+        type: "draft",
+        fieldName,
+        ...(issuedBy ? { issuedBy } : {}),
+    };
+    return Object.freeze({
+        name: options.name,
+        type: "draft",
+        fieldName,
+        access,
+        strength,
+        issuedBy,
+        schema: options.schema,
+        result: options.result,
+        ttl: options.ttl,
+        idleTtlMs,
+        maxTtlMs,
+        resultTtl,
+        resultTtlMs,
+        maxEntries,
+        maxValueBytes,
+        wordCount,
+        field: () => createHandleField(meta),
+    });
+}
+export function isDraftKind(kind) {
+    return kind.type === "draft";
+}
+export function isCursorKind(kind) {
+    return kind.type === "cursor";
+}
+/**
+ * Chooses one offered item by a plain value the LLM copied from the offer.
+ * Exact match first, then a unique case-insensitive trimmed match; otherwise
+ * `PICK_NOT_OFFERED` with the allowed values so the LLM can self-correct. The
+ * server holds the offer, so a fabricated value fails here instead of reaching
+ * upstream. This is the "one handle per offer + plain picks" half of ADR-0012.
+ */
+export function pick(items, value, options) {
+    const by = options.by ?? options.field;
+    const keyOf = (item) => {
+        const raw = item[by];
+        return typeof raw === "string" ? raw : String(raw);
+    };
+    const exact = items.find((item) => keyOf(item) === value);
+    if (exact)
+        return exact;
+    const folded = value.trim().toLowerCase();
+    const loose = items.filter((item) => keyOf(item).trim().toLowerCase() === folded);
+    if (loose.length === 1)
+        return loose[0];
+    const allowed = items.map(keyOf);
+    const issuers = formatHandleIssuers(options.issuedBy);
+    const listed = issuers
+        ? ` Use the values exactly as listed by ${issuers}.`
+        : " Use the values exactly as listed.";
+    throw new HandleError("PICK_NOT_OFFERED", `\`${options.field}\` must be one of: ${allowed.join(", ")}.${listed}`, { details: { field: options.field, allowed } });
+}

package/dist/i18n/catalog.js

@@ -100,6 +100,26 @@ export function localizeAuthTurn(turn, options) {
             : {}),
     };
 }
+/**
+ * Markers that indicate a locale value was scaffolded but never translated.
+ *
+ * ASCII tokens are matched case-sensitively as whole `\w` tokens so ordinary
+ * prose such as "todo list" or identifiers like "TBDx" are not flagged. Locale
+ * tags such as `[ko]` are matched literally (the brackets are the boundary), and
+ * the Korean/Japanese phrases are matched as-is since CJK text has no `\b`.
+ */
+const PROVIDER_LOCALE_PLACEHOLDER_PATTERNS = [
+    /\b(?:TODO|FIXME|TBD|TRANSLATE)\b/,
+    /\[(?:en|ko|ja)\]/i,
+    /번역\s*필요/,
+    /翻訳が必要/,
+];
+function isProviderLocalePlaceholderText(text) {
+    if (text.trim().length === 0) {
+        return true;
+    }
+    return PROVIDER_LOCALE_PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(text));
+}
 export function validateProviderLocaleCatalogs(options) {
     const issues = [];
     const uniqueKeys = Array.from(new Set(options.requiredKeys.map((key) => {
@@ -138,7 +158,7 @@ export function validateProviderLocaleCatalogs(options) {
                 continue;
             }
             for (const text of Array.isArray(value) ? value : [value]) {
-                if (text.trim().length === 0 || /\bTODO\b/i.test(text)) {
+                if (isProviderLocalePlaceholderText(text)) {
                     issues.push({
                         locale,
                         key,

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 export * from "./auth.js";
 export * from "./ceremonies/index.js";
-export * from "./choice-token.js";
 export type { ApiFuseConfig, BrowserConfig, ProxyCacheStatus, ProxyProtocol, ProxyResolutionOptions, ProxyResolutionSource, ProxyUserAgentSource, ProxyVendorName, ResolvedProxyConfig, SessionConfig, SmartproxyAllocatorBodyClass, } from "./config/loader.js";
 export { defineConfig, loadApiFuseConfig, resolveProxy } from "./config/loader.js";
 export { canonicalJson, digestProviderContract, extractProviderContract, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, } from "./contract.js";
@@ -20,7 +19,9 @@ export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export type { BrowserClientOptions } from "./runtime/browser.js";
 export { APIFUSE__CACHE__KEY_PEPPER_ENV, createBypassProviderCache, createProviderCache, type ProviderCacheOptions, } from "./runtime/cache.js";
-export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
+export * from "./handle.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
+export { type CreateHandleContextOptions, type CreateTestHandleContextOptions, createHandleContext, createTestHandleContext, type HandleNormalizationClass, type NormalizedHandle, normalizeHandle, } from "./runtime/handle.js";
 export { type CreateCredentialContextOptions, createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
@@ -41,7 +42,7 @@ export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export type { ResolverRuntimeOptions } from "./runtime/resolver.js";
 export type { ResolverPaidUsageContext, ResolverVendorTransport, ResolverVendorUnavailableReason, } from "./runtime/resolver-vendors/types.js";
 export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
-export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
+export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
 export { APIFUSE__OCR__API_KEY_ENV, APIFUSE__OCR__BACKEND_ENV, APIFUSE__OCR__BASE_URL_ENV, APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__OCR__MODEL_ENV, CLOUDFLARE_ACCOUNT_ID_ENV, CLOUDFLARE_WORKERS_AI_OCR_BACKEND, createCloudflareWorkersAiOcrClient, createOcrClientFromEnv, createOpenAiCompatibleOcrClient, createUnsupportedOcrClient, DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL, extractCaptchaCandidates, OPENAI_COMPATIBLE_OCR_BACKEND, } from "./runtime/ocr.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { type CreateTraceContextOptions, createTraceContext, type Span, type TraceContext, } from "./runtime/trace.js";
@@ -50,9 +51,11 @@ export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, AP
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ProviderErrorCauseFrame, type ServeOptions, serve, } from "./server/serve.js";
 export { DEFAULT_STEALTH_BROWSER, DEFAULT_STEALTH_OS, getStealthProfile, listStealthProfiles, } from "./stealth/profiles.js";
 export * from "./stream.js";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserCookie, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ChallengeSolution, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderChallenge, ProviderChallengeKind, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderResolverConfig, ProviderResolverVendor, ProviderRuntimeTarget, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, ResolverContext, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthClient, StealthBrowser, StealthChallengeClassification, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthProfileDescriptor, StealthProfileSelection, StealthOS, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
+export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserCookie, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ChallengeSolution, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChallenge, ProviderChallengeKind, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderResolverConfig, ProviderResolverVendor, ProviderRuntimeTarget, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, ResolverContext, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthClient, StealthBrowser, StealthChallengeClassification, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthProfileDescriptor, StealthProfileSelection, StealthOS, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
 export * from "./utils/date.js";
 export * from "./utils/parse.js";
 export * from "./utils/text.js";
 export * from "./utils/transform.js";
+export { HttpTelemetryCollector, type HttpTelemetrySink, type HttpTelemetryRequestSink, type HttpAttemptTelemetryEvent, type HttpAttemptSample, type HttpTelemetryErrorCode, type HttpTelemetryRetryPayload, type HttpTelemetryLogPayload, type HttpTelemetryHeaderPayload, } from "./runtime/http-telemetry.js";
+export { NativeTelemetryCollector, type NativeAttemptSample, type NativeConnectTelemetryEvent, type NativeLifecycleTelemetryEvent, type NativeTelemetryDiagnostics, type NativeTelemetryErrorCode, type NativeTelemetryHeaderPayload, type NativeTelemetryKind, type NativeTelemetryLifecycleKind, type NativeTelemetryLogPayload, type NativeTelemetryOutcome, type NativeTelemetrySink, type NativeTelemetryVendorSkipReason, type NativeVendorSkipTelemetryEvent, } from "./runtime/native-telemetry.js";

package/dist/index.js

@@ -1,7 +1,6 @@
 // @apifuse/provider-sdk
 export * from "./auth.js";
 export * from "./ceremonies/index.js";
-export * from "./choice-token.js";
 export { defineConfig, loadApiFuseConfig, resolveProxy } from "./config/loader.js";
 export { canonicalJson, digestProviderContract, extractProviderContract, PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, } from "./define.js";
@@ -17,7 +16,9 @@ export * from "./recipes/gov-api.js";
 export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export { APIFUSE__CACHE__KEY_PEPPER_ENV, createBypassProviderCache, createProviderCache, } from "./runtime/cache.js";
-export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
+export * from "./handle.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
+export { createHandleContext, createTestHandleContext, normalizeHandle, } from "./runtime/handle.js";
 export { createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
@@ -32,7 +33,7 @@ export { ResolverTelemetryCollector, } from "./runtime/resolver-telemetry.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
-export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
+export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
 export { APIFUSE__OCR__API_KEY_ENV, APIFUSE__OCR__BACKEND_ENV, APIFUSE__OCR__BASE_URL_ENV, APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__OCR__MODEL_ENV, CLOUDFLARE_ACCOUNT_ID_ENV, CLOUDFLARE_WORKERS_AI_OCR_BACKEND, createCloudflareWorkersAiOcrClient, createOcrClientFromEnv, createOpenAiCompatibleOcrClient, createUnsupportedOcrClient, DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL, extractCaptchaCandidates, OPENAI_COMPATIBLE_OCR_BACKEND, } from "./runtime/ocr.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { createTraceContext, } from "./runtime/trace.js";
@@ -45,3 +46,5 @@ export * from "./utils/date.js";
 export * from "./utils/parse.js";
 export * from "./utils/text.js";
 export * from "./utils/transform.js";
+export { HttpTelemetryCollector, } from "./runtime/http-telemetry.js";
+export { NativeTelemetryCollector, } from "./runtime/native-telemetry.js";

package/dist/lint.d.ts

@@ -80,6 +80,9 @@ export declare function lintProvider(provider: {
         contract?: ProviderContractMetaLike;
     };
     reviewed?: string;
+    /** Declared handle kinds (ADR-0012); read structurally, see readHandleKindDeclarations. */
+    handle?: unknown;
+    state?: unknown;
 }, options?: ProviderLintOptions): LintDiagnostic[];
 /** Internal detailed result used by the CLI to render suppression audits. */
 export declare function lintProviderWithInformation(provider: Parameters<typeof lintProvider>[0], options?: ProviderLintOptions): ProviderLintResult;