opencandle 0.2.0 → 0.3.0

package/dist/onboarding/state.d.ts

@@ -1,8 +1,37 @@
-export declare const ONBOARDING_VERSION = 1;
+import type { ProviderId } from "./providers.js";
+export declare const ONBOARDING_VERSION = 2;
+export type ProviderOnboardingEntry = {
+    status: "completed";
+    lastPromptAt: string;
+} | {
+    status: "snoozed";
+    lastPromptAt: string;
+    snoozeUntil: string;
+} | {
+    status: "never_ask";
+    lastPromptAt: string;
+};
 export interface OnboardingState {
     version: number;
-    financeSetupStatus?: "dismissed" | "completed";
+    /** ISO 8601 timestamp the welcome message was first seeded, or undefined if never. */
+    welcomeShownAt?: string;
+    providers: Partial<Record<ProviderId, ProviderOnboardingEntry>>;
 }
 export declare function getDefaultOnboardingState(): OnboardingState;
 export declare function loadOnboardingState(path?: string): OnboardingState;
 export declare function saveOnboardingState(state: OnboardingState, path?: string): void;
+export declare function markProviderCompleted(state: OnboardingState, id: ProviderId): OnboardingState;
+export declare function markProviderSnoozed(state: OnboardingState, id: ProviderId, days: number): OnboardingState;
+export declare function markProviderNeverAsk(state: OnboardingState, id: ProviderId): OnboardingState;
+export declare function markWelcomeShown(state: OnboardingState): OnboardingState;
+export declare function getProviderEntry(state: OnboardingState, id: ProviderId): ProviderOnboardingEntry | undefined;
+export interface ShouldPromptOptions {
+    /**
+     * When true, treats a `completed` entry as eligible for re-prompt. This is
+     * how stale credentials (401 after a previously-connected key) get a fresh
+     * offer.
+     */
+    stale?: boolean;
+}
+export declare function shouldPrompt(state: OnboardingState, id: ProviderId, now: Date, options?: ShouldPromptOptions): boolean;
+export declare function shouldShowWelcome(state: OnboardingState, hasUI: boolean): boolean;

package/dist/onboarding/state.js

@@ -1,31 +1,159 @@
+// Onboarding state schema and pure helpers.
+//
+// Shape: one flag for the welcome message (`welcomeShownAt`) plus a partial
+// per-provider map with a proper discriminated union for status + snooze.
+//
+// All transition helpers are PURE — they return a new state object rather
+// than mutating. The caller is responsible for persisting via saveOnboardingState.
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { ensureParentDir, getOnboardingPath } from "../infra/opencandle-paths.js";
-export const ONBOARDING_VERSION = 1;
+export const ONBOARDING_VERSION = 2;
 export function getDefaultOnboardingState() {
-    return { version: ONBOARDING_VERSION };
+    return { version: ONBOARDING_VERSION, providers: {} };
+}
+// -----------------------------------------------------------------------------
+// Load / save
+// -----------------------------------------------------------------------------
+const STATUS_VALUES = new Set(["completed", "snoozed", "never_ask"]);
+function parseEntry(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const obj = raw;
+    const status = obj.status;
+    if (typeof status !== "string" || !STATUS_VALUES.has(status))
+        return undefined;
+    const lastPromptAt = obj.lastPromptAt;
+    if (typeof lastPromptAt !== "string")
+        return undefined;
+    if (status === "snoozed") {
+        const snoozeUntil = obj.snoozeUntil;
+        if (typeof snoozeUntil !== "string")
+            return undefined;
+        return { status: "snoozed", lastPromptAt, snoozeUntil };
+    }
+    if (status === "completed") {
+        return { status: "completed", lastPromptAt };
+    }
+    return { status: "never_ask", lastPromptAt };
+}
+function parseProvidersMap(raw) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const result = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const entry = parseEntry(value);
+        if (entry)
+            result[key] = entry;
+    }
+    return result;
 }
 export function loadOnboardingState(path = getOnboardingPath()) {
     if (!existsSync(path)) {
         return getDefaultOnboardingState();
     }
+    let raw;
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf-8"));
-        if (!parsed || typeof parsed !== "object") {
-            return getDefaultOnboardingState();
-        }
-        return {
-            version: typeof parsed.version === "number" ? parsed.version : ONBOARDING_VERSION,
-            financeSetupStatus: parsed.financeSetupStatus === "completed" || parsed.financeSetupStatus === "dismissed"
-                ? parsed.financeSetupStatus
-                : undefined,
-        };
+        raw = readFileSync(path, "utf-8");
     }
     catch {
         return getDefaultOnboardingState();
     }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return getDefaultOnboardingState();
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return getDefaultOnboardingState();
+    }
+    const obj = parsed;
+    const version = typeof obj.version === "number" ? obj.version : ONBOARDING_VERSION;
+    const welcomeShownAt = typeof obj.welcomeShownAt === "string" ? obj.welcomeShownAt : undefined;
+    const providers = parseProvidersMap(obj.providers);
+    return { version, welcomeShownAt, providers };
 }
 export function saveOnboardingState(state, path = getOnboardingPath()) {
     ensureParentDir(path);
-    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+    // Strip undefined fields for cleaner on-disk output.
+    const serializable = {
+        version: state.version,
+        providers: state.providers,
+    };
+    if (state.welcomeShownAt !== undefined) {
+        serializable.welcomeShownAt = state.welcomeShownAt;
+    }
+    writeFileSync(path, `${JSON.stringify(serializable, null, 2)}\n`, "utf-8");
+}
+// -----------------------------------------------------------------------------
+// Pure transitions
+// -----------------------------------------------------------------------------
+function nowIso() {
+    return new Date().toISOString();
+}
+export function markProviderCompleted(state, id) {
+    return {
+        ...state,
+        providers: {
+            ...state.providers,
+            [id]: { status: "completed", lastPromptAt: nowIso() },
+        },
+    };
+}
+export function markProviderSnoozed(state, id, days) {
+    const now = new Date();
+    const snoozeUntil = new Date(now.getTime() + days * 24 * 3600 * 1000);
+    return {
+        ...state,
+        providers: {
+            ...state.providers,
+            [id]: {
+                status: "snoozed",
+                lastPromptAt: now.toISOString(),
+                snoozeUntil: snoozeUntil.toISOString(),
+            },
+        },
+    };
+}
+export function markProviderNeverAsk(state, id) {
+    return {
+        ...state,
+        providers: {
+            ...state.providers,
+            [id]: { status: "never_ask", lastPromptAt: nowIso() },
+        },
+    };
+}
+export function markWelcomeShown(state) {
+    return { ...state, welcomeShownAt: nowIso() };
+}
+// -----------------------------------------------------------------------------
+// Pure queries
+// -----------------------------------------------------------------------------
+export function getProviderEntry(state, id) {
+    return state.providers[id];
+}
+export function shouldPrompt(state, id, now, options = {}) {
+    const entry = state.providers[id];
+    if (!entry)
+        return true;
+    switch (entry.status) {
+        case "never_ask":
+            return false;
+        case "completed":
+            return options.stale === true;
+        case "snoozed": {
+            const until = Date.parse(entry.snoozeUntil);
+            if (Number.isNaN(until))
+                return true;
+            return now.getTime() >= until;
+        }
+    }
+}
+export function shouldShowWelcome(state, hasUI) {
+    if (!hasUI)
+        return false;
+    return state.welcomeShownAt === undefined;
 }
 //# sourceMappingURL=state.js.map

package/dist/onboarding/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/onboarding/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAElF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAOpC,MAAM,UAAU,yBAAyB;IACvC,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAI,GAAG,iBAAiB,EAAE;IAC5D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,yBAAyB,EAAE,CAAC;IACrC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAoB,CAAC;QAC1E,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC1C,OAAO,yBAAyB,EAAE,CAAC;QACrC,CAAC;QACD,OAAO;YACL,OAAO,EAAE,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB;YACjF,kBAAkB,EAChB,MAAM,CAAC,kBAAkB,KAAK,WAAW,IAAI,MAAM,CAAC,kBAAkB,KAAK,WAAW;gBACpF,CAAC,CAAC,MAAM,CAAC,kBAAkB;gBAC3B,CAAC,CAAC,SAAS;SAChB,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,yBAAyB,EAAE,CAAC;IACrC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAsB,EAAE,IAAI,GAAG,iBAAiB,EAAE;IACpF,eAAe,CAAC,IAAI,CAAC,CAAC;IACtB,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACtE,CAAC"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/onboarding/state.ts"],"names":[],"mappings":"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"}

package/dist/onboarding/tool-helpers.d.ts

@@ -0,0 +1,34 @@
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import { type ProviderId } from "./providers.js";
+import { type CredentialRequiredReason } from "./tool-tags.js";
+export interface CredentialRequiredDetails {
+    credentialRequired: {
+        provider: ProviderId;
+        reason: CredentialRequiredReason;
+        httpStatus?: number;
+    };
+}
+/**
+ * Wrap a tool's provider-calling logic with a credential-check layer.
+ *
+ * Usage:
+ * ```
+ * async execute(_, args) {
+ *   return withCredentialCheck("alpha_vantage", async () => {
+ *     const apiKey = getConfig().alphaVantageApiKey!;
+ *     const result = await wrapProvider("alphavantage", () => getFinancials(args.symbol, apiKey));
+ *     // ... format success result ...
+ *     return { content: [...], details: [...] };
+ *   });
+ * }
+ * ```
+ *
+ * On missing credential (upfront): `fn` is NOT called. A tagged tool result
+ * is returned directly.
+ *
+ * On `ProviderCredentialError` thrown during `fn`: the error is caught and a
+ * tagged tool result is returned.
+ *
+ * Any other thrown value (plain Error, string, etc.) is re-thrown unchanged.
+ */
+export declare function withCredentialCheck<T>(providerId: ProviderId, fn: () => Promise<AgentToolResult<T>>): Promise<AgentToolResult<T> | AgentToolResult<CredentialRequiredDetails>>;

package/dist/onboarding/tool-helpers.js

@@ -0,0 +1,80 @@
+// Tool-boundary helpers for credentialed providers.
+//
+// `withCredentialCheck` is the single-entry helper that OpenCandle tools use
+// to wrap their provider calls. It centralizes:
+//   1. The upfront "credential missing" check via the registry.
+//   2. The catch-and-convert logic for `ProviderCredentialError` thrown from
+//      providers on 401/403 (stale credential after HTTP call).
+//   3. The tagged `[OPENCANDLE_CREDENTIAL_REQUIRED ...]` content emission that
+//      the Pi `tool_result` extension hook intercepts.
+//
+// Non-credential errors (network timeouts, parse errors, etc.) are re-thrown
+// unchanged so existing error handling in `wrapProvider` continues to work.
+import { ProviderCredentialError } from "../providers/provider-credential-error.js";
+import { getProvider, hasCredential } from "./providers.js";
+import { buildCredentialRequiredTag, } from "./tool-tags.js";
+function buildCredentialRequiredResult(provider, reason, httpStatus) {
+    const descriptor = getProvider(provider);
+    const tag = buildCredentialRequiredTag({
+        provider,
+        reason,
+        unlocks: descriptor.unlocks,
+        fallback: descriptor.fallbackDescription,
+        httpStatus,
+    });
+    // The second line is natural language describing what's missing. Users won't
+    // see it directly — the model sees it and uses the information to synthesize
+    // a gap note in its final answer. The tagged first line is the machine-
+    // readable signal the `tool_result` interception handler keys off of.
+    const narrative = reason === "missing"
+        ? `${descriptor.displayName} was not fetched for this request because no API key is configured. It unlocks ${descriptor.unlocks.join(", ")}.`
+        : `${descriptor.displayName} rejected the configured API key (HTTP ${httpStatus ?? "auth error"}). It may be expired or revoked.`;
+    return {
+        content: [{ type: "text", text: `${tag}\n\n${narrative}` }],
+        details: {
+            credentialRequired: {
+                provider,
+                reason,
+                ...(httpStatus !== undefined ? { httpStatus } : {}),
+            },
+        },
+    };
+}
+/**
+ * Wrap a tool's provider-calling logic with a credential-check layer.
+ *
+ * Usage:
+ * ```
+ * async execute(_, args) {
+ *   return withCredentialCheck("alpha_vantage", async () => {
+ *     const apiKey = getConfig().alphaVantageApiKey!;
+ *     const result = await wrapProvider("alphavantage", () => getFinancials(args.symbol, apiKey));
+ *     // ... format success result ...
+ *     return { content: [...], details: [...] };
+ *   });
+ * }
+ * ```
+ *
+ * On missing credential (upfront): `fn` is NOT called. A tagged tool result
+ * is returned directly.
+ *
+ * On `ProviderCredentialError` thrown during `fn`: the error is caught and a
+ * tagged tool result is returned.
+ *
+ * Any other thrown value (plain Error, string, etc.) is re-thrown unchanged.
+ */
+export async function withCredentialCheck(providerId, fn) {
+    if (!hasCredential(providerId)) {
+        return buildCredentialRequiredResult(providerId, "missing");
+    }
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (error instanceof ProviderCredentialError) {
+            return buildCredentialRequiredResult(error.provider, error.reason, error.httpStatus);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=tool-helpers.js.map

package/dist/onboarding/tool-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-helpers.js","sourceRoot":"","sources":["../../src/onboarding/tool-helpers.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,6EAA6E;AAC7E,gDAAgD;AAChD,gEAAgE;AAChE,6EAA6E;AAC7E,gEAAgE;AAChE,+EAA+E;AAC/E,uDAAuD;AACvD,EAAE;AACF,6EAA6E;AAC7E,4EAA4E;AAG5E,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,aAAa,EAAmB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EACL,0BAA0B,GAE3B,MAAM,gBAAgB,CAAC;AAcxB,SAAS,6BAA6B,CACpC,QAAoB,EACpB,MAAgC,EAChC,UAAmB;IAEnB,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,0BAA0B,CAAC;QACrC,QAAQ;QACR,MAAM;QACN,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,QAAQ,EAAE,UAAU,CAAC,mBAAmB;QACxC,UAAU;KACX,CAAC,CAAC;IACH,6EAA6E;IAC7E,6EAA6E;IAC7E,wEAAwE;IACxE,sEAAsE;IACtE,MAAM,SAAS,GACb,MAAM,KAAK,SAAS;QAClB,CAAC,CAAC,GAAG,UAAU,CAAC,WAAW,kFAAkF,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAC7I,CAAC,CAAC,GAAG,UAAU,CAAC,WAAW,0CAA0C,UAAU,IAAI,YAAY,kCAAkC,CAAC;IAEtI,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,SAAS,EAAE,EAAE,CAAC;QAC3D,OAAO,EAAE;YACP,kBAAkB,EAAE;gBAClB,QAAQ;gBACR,MAAM;gBACN,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACpD;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAsB,EACtB,EAAqC;IAErC,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,6BAA6B,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,uBAAuB,EAAE,CAAC;YAC7C,OAAO,6BAA6B,CAClC,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,CACjB,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/onboarding/tool-tags.d.ts

@@ -0,0 +1,37 @@
+import type { ProviderId } from "./providers.js";
+export type CredentialRequiredReason = "missing" | "stale";
+export interface CredentialRequiredTagFields {
+    provider: ProviderId;
+    reason: CredentialRequiredReason;
+    unlocks: readonly string[];
+    fallback: string | null;
+    httpStatus?: number;
+}
+export interface SoftDegradedTagFields {
+    provider: ProviderId;
+    fallback: string;
+    remediation: string;
+}
+export interface SkippedTagFields {
+    provider: ProviderId;
+    reason: "credential_not_provided";
+    remediation: string;
+    silenced?: boolean;
+}
+export interface ConnectedTagFields {
+    provider: ProviderId;
+}
+export type ParsedTag = ({
+    kind: "credential_required";
+} & CredentialRequiredTagFields) | ({
+    kind: "soft_degraded";
+} & SoftDegradedTagFields) | ({
+    kind: "skipped";
+} & SkippedTagFields) | ({
+    kind: "connected";
+} & ConnectedTagFields);
+export declare function buildCredentialRequiredTag(fields: CredentialRequiredTagFields): string;
+export declare function buildSoftDegradedTag(fields: SoftDegradedTagFields): string;
+export declare function buildSkippedTag(fields: SkippedTagFields): string;
+export declare function buildConnectedTag(fields: ConnectedTagFields): string;
+export declare function parseToolTag(text: string): ParsedTag | undefined;

package/dist/onboarding/tool-tags.js

@@ -0,0 +1,149 @@
+// Tool-result text tags used by OpenCandle's conversational-provider-setup
+// flow. These tagged lines are the LLM-facing contract — Pi provider adapters
+// serialize the `content` field of tool results into the model's conversation,
+// so any signal we want the model to reason over must live in text, not
+// `details`.
+//
+// Tag format (single line, parseable):
+//   [OPENCANDLE_<KIND> field=value field2=value ... ]
+//
+// Values may be:
+//   - bare: provider=alpha_vantage  reason=missing  silenced=true  httpStatus=401
+//   - quoted (for spaces or commas): remediation="run /connect economy"
+//   - lists (comma-separated inside quotes): unlocks="fundamentals, DCF"
+//   - null/absent: fallback=none
+//
+// Parser is tolerant of unknown fields and extra whitespace.
+// -----------------------------------------------------------------------------
+// Builders
+// -----------------------------------------------------------------------------
+function quote(value) {
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
+function formatField(key, value) {
+    return `${key}=${value}`;
+}
+export function buildCredentialRequiredTag(fields) {
+    const parts = [
+        "[OPENCANDLE_CREDENTIAL_REQUIRED",
+        formatField("provider", fields.provider),
+        formatField("reason", fields.reason),
+        `unlocks=${quote(fields.unlocks.join(", "))}`,
+        formatField("fallback", fields.fallback ?? "none"),
+    ];
+    if (fields.httpStatus !== undefined) {
+        parts.push(formatField("httpStatus", fields.httpStatus));
+    }
+    return `${parts.join(" ")}]`;
+}
+export function buildSoftDegradedTag(fields) {
+    return [
+        "[OPENCANDLE_SOFT_DEGRADED",
+        formatField("provider", fields.provider),
+        formatField("fallback", fields.fallback),
+        `remediation=${quote(fields.remediation)}`,
+    ].join(" ") + "]";
+}
+export function buildSkippedTag(fields) {
+    const parts = [
+        "[OPENCANDLE_SKIPPED",
+        formatField("provider", fields.provider),
+        formatField("reason", fields.reason),
+        `remediation=${quote(fields.remediation)}`,
+    ];
+    if (fields.silenced) {
+        parts.push(formatField("silenced", "true"));
+    }
+    return `${parts.join(" ")}]`;
+}
+export function buildConnectedTag(fields) {
+    return `[OPENCANDLE_CONNECTED provider=${fields.provider}]`;
+}
+// -----------------------------------------------------------------------------
+// Parser
+// -----------------------------------------------------------------------------
+const TAG_LINE_REGEX = /\[OPENCANDLE_(CREDENTIAL_REQUIRED|SOFT_DEGRADED|SKIPPED|CONNECTED)([^\]]*)\]/;
+function parseFields(raw) {
+    // Split on `key=value` pairs, respecting quoted values.
+    const fields = {};
+    const pattern = /(\w+)=("((?:[^"\\]|\\.)*)"|([^\s\]]+))/g;
+    let match;
+    while ((match = pattern.exec(raw)) !== null) {
+        const key = match[1];
+        const value = match[3] !== undefined ? match[3].replace(/\\"/g, '"') : match[4];
+        fields[key] = value;
+    }
+    return fields;
+}
+export function parseToolTag(text) {
+    const match = TAG_LINE_REGEX.exec(text);
+    if (!match)
+        return undefined;
+    const kind = match[1];
+    const rest = match[2];
+    const fields = parseFields(rest);
+    switch (kind) {
+        case "CREDENTIAL_REQUIRED": {
+            const provider = fields.provider;
+            const reason = fields.reason;
+            const unlocksRaw = fields.unlocks ?? "";
+            const fallbackRaw = fields.fallback;
+            if (!provider || (reason !== "missing" && reason !== "stale")) {
+                return undefined;
+            }
+            const unlocks = unlocksRaw
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            const fallback = fallbackRaw === undefined || fallbackRaw === "none" ? null : fallbackRaw;
+            const parsed = {
+                kind: "credential_required",
+                provider: provider,
+                reason: reason,
+                unlocks,
+                fallback,
+            };
+            if (fields.httpStatus !== undefined) {
+                const n = Number(fields.httpStatus);
+                if (!Number.isNaN(n))
+                    parsed.httpStatus = n;
+            }
+            return parsed;
+        }
+        case "SOFT_DEGRADED": {
+            const { provider, fallback, remediation } = fields;
+            if (!provider || !fallback || !remediation)
+                return undefined;
+            return {
+                kind: "soft_degraded",
+                provider: provider,
+                fallback,
+                remediation,
+            };
+        }
+        case "SKIPPED": {
+            const { provider, reason, remediation } = fields;
+            if (!provider || reason !== "credential_not_provided" || !remediation) {
+                return undefined;
+            }
+            const parsed = {
+                kind: "skipped",
+                provider: provider,
+                reason: "credential_not_provided",
+                remediation,
+            };
+            if (fields.silenced === "true")
+                parsed.silenced = true;
+            return parsed;
+        }
+        case "CONNECTED": {
+            const { provider } = fields;
+            if (!provider)
+                return undefined;
+            return { kind: "connected", provider: provider };
+        }
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=tool-tags.js.map

package/dist/onboarding/tool-tags.js.map

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

package/dist/onboarding/validation.d.ts

@@ -0,0 +1,19 @@
+import type { ProviderId } from "./providers.js";
+export type ValidationResult = {
+    status: "valid";
+} | {
+    status: "invalid";
+    httpStatus?: number;
+    message?: string;
+} | {
+    status: "transient";
+    reason: string;
+};
+/**
+ * Validate a pasted credential against the provider's API. Returns a
+ * ValidationResult describing whether the key should be persisted.
+ *
+ * This function is side-effect-free beyond the network call: it does not
+ * touch the config file, onboarding state, or any in-memory cache.
+ */
+export declare function validateCredential(providerId: ProviderId, key: string): Promise<ValidationResult>;