opencandle 0.2.0 → 0.4.0

package/dist/onboarding/connect.js

@@ -0,0 +1,118 @@
+// Shared `runProviderConnect` function — the actual side-effectful flow that
+// opens a browser, collects a pasted API key, validates it against the
+// provider's API, persists it to `~/.opencandle/config.json`, and refreshes
+// the cached Config so the next tool call sees the new credential.
+//
+// Called from two places:
+//   1. The Pi `tool_result` extension handler when the user picks "Connect now"
+//      in the just-in-time prompt (Task Group 10).
+//   2. The `/connect` Pi command (Task Group 13).
+//
+// Validation (Task Group 8 final pass): before persisting, the pasted key is
+// validated via `validateCredential`, which makes a single cheap request to
+// the provider's canonical API and classifies the response. A hard
+// auth failure (401/403 or a provider-specific error-in-200-body) is
+// returned as `invalid_key` WITHOUT persisting the bad value; a transient
+// failure (timeout, 5xx, network error) warns the user but still persists
+// the key so they aren't blocked on a provider outage — the next real tool
+// call will surface any lingering issue via the credential-required tag.
+import { openInBrowser } from "../infra/open-url.js";
+import { loadFileConfig, saveFileConfig, loadConfig, } from "../config.js";
+import { getProvider, getCredentialSource, } from "./providers.js";
+import { loadOnboardingState, markProviderCompleted, saveOnboardingState, } from "./state.js";
+import { validateCredential } from "./validation.js";
+function writeNested(obj, path, value) {
+    if (path.length === 0)
+        return obj;
+    const [head, ...rest] = path;
+    const next = { ...obj };
+    if (rest.length === 0) {
+        next[head] = value;
+    }
+    else {
+        const child = next[head] && typeof next[head] === "object"
+            ? next[head]
+            : {};
+        next[head] = writeNested(child, rest, value);
+    }
+    return next;
+}
+/**
+ * Persist an already-validated provider credential.
+ *
+ * Writes the key into `~/.opencandle/config.json` (preserving sibling fields),
+ * refreshes the cached `Config` so the next tool call sees the new value, and
+ * marks the provider as completed in the onboarding state.
+ *
+ * Shared by the TUI `/connect` flow (`runProviderConnect`) and the GUI
+ * provider-setup form. Validation is the caller's responsibility — both
+ * call sites run `validateCredential` before invoking this helper.
+ */
+export function persistProviderCredential(providerId, key) {
+    const descriptor = getProvider(providerId);
+    const existing = loadFileConfig();
+    const updated = writeNested(existing, descriptor.configPath, key);
+    saveFileConfig(updated);
+    loadConfig();
+    const state = loadOnboardingState();
+    saveOnboardingState(markProviderCompleted(state, providerId));
+}
+/**
+ * Run the connect flow for a single provider.
+ *
+ * Env-precedence short-circuit: if the provider's configured credential
+ * already comes from an environment variable, the file-config write would
+ * be invisible to the next tool call (env vars win in `resolveConfig`).
+ * Notify the user explicitly and return `blocked_by_env` — do not open
+ * the browser or collect a pasted value.
+ */
+export async function runProviderConnect(ctx, providerId) {
+    const descriptor = getProvider(providerId);
+    // Env-precedence check.
+    if (getCredentialSource(providerId) === "env") {
+        ctx.ui.notify(`${descriptor.displayName} is currently set via the ${descriptor.envVar} environment variable. ` +
+            `To change it from here, unset that variable first and reopen /connect ${descriptor.aliases[0] ?? descriptor.id}. ` +
+            `Otherwise, update ${descriptor.envVar} directly in your shell profile.`, "warning");
+        return { status: "blocked_by_env" };
+    }
+    // Open the signup URL in the user's browser. We ignore errors here — if
+    // the browser can't be opened, the user can still paste a key they
+    // already have, so we continue rather than bailing.
+    await openInBrowser(descriptor.signupUrl).catch(() => { });
+    ctx.ui.notify(`Opening ${descriptor.displayName} signup in your browser...`, "info");
+    // Prompt for the key. Uses the provider's instructionsHint as the
+    // placeholder text to remind the user what they're pasting.
+    const pasted = await ctx.ui.input(`Paste your ${descriptor.displayName} API key`, descriptor.instructionsHint);
+    if (!pasted) {
+        return { status: "cancelled" };
+    }
+    const trimmed = pasted.trim();
+    if (trimmed.length === 0) {
+        return { status: "cancelled" };
+    }
+    // Validate the key with the provider BEFORE persisting. Hard auth failures
+    // short-circuit here without writing anything; transient failures warn
+    // but proceed to persist so users don't get stuck on a provider outage.
+    ctx.ui.notify(`Verifying your ${descriptor.displayName} key...`, "info");
+    const validation = await validateCredential(providerId, trimmed);
+    if (validation.status === "invalid") {
+        const statusHint = validation.httpStatus !== undefined ? ` (HTTP ${validation.httpStatus})` : "";
+        const messageHint = validation.message ? ` — ${validation.message}` : "";
+        ctx.ui.notify(`${descriptor.displayName} rejected the key${statusHint}${messageHint}. ` +
+            `Your existing configuration was not changed. Re-run /connect ${descriptor.aliases[0] ?? descriptor.id} to try a different key.`, "error");
+        return {
+            status: "invalid_key",
+            httpStatus: validation.httpStatus,
+            message: validation.message,
+        };
+    }
+    if (validation.status === "transient") {
+        ctx.ui.notify(`Couldn't reach ${descriptor.displayName} to verify the key (${validation.reason}). ` +
+            `Saving it anyway — the next request will surface any issue.`, "warning");
+        // Fall through to persist.
+    }
+    persistProviderCredential(providerId, trimmed);
+    ctx.ui.notify(`${descriptor.displayName} connected. Your key has been saved.`, "info");
+    return { status: "connected" };
+}
+//# sourceMappingURL=connect.js.map

package/dist/onboarding/connect.js.map

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

package/dist/onboarding/credential-interceptor.d.ts

@@ -0,0 +1,44 @@
+import type { ProviderId } from "./providers.js";
+import type { OnboardingState } from "./state.js";
+import type { CredentialRequiredReason } from "./tool-tags.js";
+export interface InterceptInput {
+    /** The provider id parsed from the tagged tool-result content. */
+    provider: ProviderId;
+    /** Why the credential was flagged as required. */
+    reason: CredentialRequiredReason;
+    /** Current persistent onboarding state (providers map, welcome flag). */
+    state: OnboardingState;
+    /** Providers already prompted at least once in this session (across workflows). */
+    sessionPromptedSet: ReadonlySet<ProviderId>;
+    /**
+     * Whether a hard-tier provider has already fired a prompt earlier in the
+     * current workflow invocation. When true, subsequent hard-provider prompts
+     * in the same workflow SHALL be silenced per the "at most one prompt per
+     * workflow" requirement in `conversational-provider-setup.spec.md`.
+     */
+    hardPromptFiredInWorkflow: boolean;
+    /** Injected clock for deterministic snooze-expiry tests. */
+    now: Date;
+}
+/** Outcome of the interception decision. */
+export type InterceptAction = {
+    action: "prompt";
+    provider: ProviderId;
+    reason: CredentialRequiredReason;
+} | {
+    action: "skip";
+    provider: ProviderId;
+    remediation: string;
+    /** True when the skip is due to explicit never_ask — downstream gap-note
+     *  synthesis should suppress the `/connect` remediation in that case. */
+    silenced: boolean;
+};
+/**
+ * Pure decision function — given an `InterceptInput`, return either a
+ * `prompt` action (the extension handler should pause and call `promptUser`)
+ * or a `skip` action (the handler should replace the tool result with a
+ * `[OPENCANDLE_SKIPPED ...]` placeholder).
+ *
+ * No side effects. No Pi imports. Trivially unit-testable.
+ */
+export declare function resolveCredentialRequired(input: InterceptInput): InterceptAction;

package/dist/onboarding/credential-interceptor.js

@@ -0,0 +1,72 @@
+// Pure decision function for handling `[OPENCANDLE_CREDENTIAL_REQUIRED ...]`
+// tool results. This module has NO Pi dependencies so it can be tested in
+// isolation — the Pi extension `tool_result` handler is a thin wrapper that
+// calls this function, inspects the returned `InterceptAction`, and drives
+// the appropriate side effects (promptUser, state mutation, tool rerun).
+//
+// Decision table — see design.md Decision 3 for the canonical version.
+import { getProvider } from "./providers.js";
+function buildRemediation(providerId) {
+    const descriptor = getProvider(providerId);
+    // Prefer the first alias as the friendly target; fall back to the id.
+    const alias = descriptor.aliases[0] ?? providerId;
+    return `run /connect ${alias} to unlock`;
+}
+function skip(providerId, silenced) {
+    return {
+        action: "skip",
+        provider: providerId,
+        remediation: buildRemediation(providerId),
+        silenced,
+    };
+}
+/**
+ * Pure decision function — given an `InterceptInput`, return either a
+ * `prompt` action (the extension handler should pause and call `promptUser`)
+ * or a `skip` action (the handler should replace the tool result with a
+ * `[OPENCANDLE_SKIPPED ...]` placeholder).
+ *
+ * No side effects. No Pi imports. Trivially unit-testable.
+ */
+export function resolveCredentialRequired(input) {
+    const { provider, reason, state, sessionPromptedSet, hardPromptFiredInWorkflow, now, } = input;
+    const descriptor = getProvider(provider);
+    const entry = state.providers[provider];
+    // 1. Never-ask: always skip, marked silenced so the gap-note copy drops the
+    //    `/connect` remediation.
+    if (entry?.status === "never_ask") {
+        return skip(provider, true);
+    }
+    // 2. Completed + missing (defensive — shouldn't normally happen because the
+    //    tool layer only emits `missing` when `hasCredential` returns false, and
+    //    a completed state implies the credential was persisted).
+    if (entry?.status === "completed" && reason === "missing") {
+        return skip(provider, false);
+    }
+    // 3. Session-level dedup: a previous prompt this session already settled
+    //    the user's answer for this provider. Don't re-ask until next session.
+    if (sessionPromptedSet.has(provider)) {
+        return skip(provider, false);
+    }
+    // 4. Per-workflow cap: at most one hard-provider prompt per workflow run.
+    if (hardPromptFiredInWorkflow && descriptor.tier === "hard") {
+        return skip(provider, false);
+    }
+    // 5. Active snooze: skip without decrementing the session set (the user
+    //    will see the prompt again if they try a workflow after snoozeUntil).
+    if (entry?.status === "snoozed") {
+        const until = Date.parse(entry.snoozeUntil);
+        if (!Number.isNaN(until) && now.getTime() < until) {
+            return skip(provider, false);
+        }
+        // snoozed but expired → fall through to prompt.
+    }
+    // 6. Completed + stale: re-prompt. This is the ONE stale-credential path
+    //    this change ships — the full failure-as-invitation story is deferred.
+    if (entry?.status === "completed" && reason === "stale") {
+        return { action: "prompt", provider, reason };
+    }
+    // 7. Default: prompt.
+    return { action: "prompt", provider, reason };
+}
+//# sourceMappingURL=credential-interceptor.js.map

package/dist/onboarding/credential-interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-interceptor.js","sourceRoot":"","sources":["../../src/onboarding/credential-interceptor.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,0EAA0E;AAC1E,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,EAAE;AACF,uEAAuE;AAGvE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAwC7C,SAAS,gBAAgB,CAAC,UAAsB;IAC9C,MAAM,UAAU,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IAC3C,sEAAsE;IACtE,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC;IAClD,OAAO,gBAAgB,KAAK,YAAY,CAAC;AAC3C,CAAC;AAED,SAAS,IAAI,CACX,UAAsB,EACtB,QAAiB;IAEjB,OAAO;QACL,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,UAAU;QACpB,WAAW,EAAE,gBAAgB,CAAC,UAAU,CAAC;QACzC,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAqB;IAErB,MAAM,EACJ,QAAQ,EACR,MAAM,EACN,KAAK,EACL,kBAAkB,EAClB,yBAAyB,EACzB,GAAG,GACJ,GAAG,KAAK,CAAC;IAEV,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAExC,4EAA4E;IAC5E,6BAA6B;IAC7B,IAAI,KAAK,EAAE,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,4EAA4E;IAC5E,6EAA6E;IAC7E,8DAA8D;IAC9D,IAAI,KAAK,EAAE,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1D,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,yEAAyE;IACzE,2EAA2E;IAC3E,IAAI,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,0EAA0E;IAC1E,IAAI,yBAAyB,IAAI,UAAU,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5D,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,wEAAwE;IACxE,0EAA0E;IAC1E,IAAI,KAAK,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;YAClD,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC/B,CAAC;QACD,gDAAgD;IAClD,CAAC;IAED,yEAAyE;IACzE,2EAA2E;IAC3E,IAAI,KAAK,EAAE,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACxD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAChD,CAAC;IAED,sBAAsB;IACtB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAChD,CAAC"}

package/dist/onboarding/degradation-accumulator.d.ts

@@ -0,0 +1,21 @@
+import type { ProviderId } from "./providers.js";
+import type { OnboardingState } from "./state.js";
+export interface DegradationAccumulator {
+    /** Record that a soft-tier provider fell back during this turn. Idempotent. */
+    record(provider: ProviderId): void;
+    /** Number of distinct providers recorded since the last reset. */
+    size(): number;
+    /** True when nothing has been recorded since the last reset. */
+    isEmpty(): boolean;
+    /**
+     * Build a newline-delimited list of `[OPENCANDLE_SKIPPED ...]` tags — one
+     * per distinct recorded provider. Providers whose `state.providers[id]`
+     * entry has `status: "never_ask"` get the `(silenced)` suffix in their
+     * remediation so the system prompt instruction suppresses the `/connect`
+     * link in the final answer. Returns `null` when no providers are recorded.
+     */
+    buildCombinedAnnotation(state: OnboardingState): string | null;
+    /** Clear all recorded providers. Call this at turn_start. */
+    reset(): void;
+}
+export declare function createDegradationAccumulator(): DegradationAccumulator;

package/dist/onboarding/degradation-accumulator.js

@@ -0,0 +1,55 @@
+// Per-turn accumulator for soft-tier provider degradations. When a soft
+// provider falls back to a keyless alternative (e.g. Brave → DuckDuckGo, Exa →
+// keyless MCP, Finnhub → cached/free source), the tool result content carries
+// a `[OPENCANDLE_SOFT_DEGRADED ...]` tag. The extension's `tool_result` hook
+// records the provider id in this accumulator WITHOUT mutating the tool
+// result; at `turn_end` the accumulator builds a single combined
+// `[OPENCANDLE_SKIPPED ...]`-style annotation that gets appended to the
+// session as a sidecar entry for observability.
+//
+// Per-provider state (never_ask / snoozed / completed) lives in the persistent
+// OnboardingState on disk — the accumulator stays pure and consults the
+// caller-supplied state snapshot at `buildCombinedAnnotation` time. This keeps
+// the accumulator trivially testable without mocking the filesystem.
+import { getProvider } from "./providers.js";
+import { buildSkippedTag } from "./tool-tags.js";
+export function createDegradationAccumulator() {
+    const recorded = new Set();
+    return {
+        record(provider) {
+            recorded.add(provider);
+        },
+        size() {
+            return recorded.size;
+        },
+        isEmpty() {
+            return recorded.size === 0;
+        },
+        buildCombinedAnnotation(state) {
+            if (recorded.size === 0)
+                return null;
+            const lines = [];
+            for (const provider of recorded) {
+                const descriptor = getProvider(provider);
+                const entry = state.providers[provider];
+                const silenced = entry?.status === "never_ask";
+                const alias = descriptor.aliases[0] ?? descriptor.id;
+                const baseRemediation = `run /connect ${alias} to unlock`;
+                const remediation = silenced
+                    ? `${baseRemediation} (silenced)`
+                    : baseRemediation;
+                lines.push(buildSkippedTag({
+                    provider,
+                    reason: "credential_not_provided",
+                    remediation,
+                    silenced: silenced || undefined,
+                }));
+            }
+            return lines.join("\n");
+        },
+        reset() {
+            recorded.clear();
+        },
+    };
+}
+//# sourceMappingURL=degradation-accumulator.js.map

package/dist/onboarding/degradation-accumulator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"degradation-accumulator.js","sourceRoot":"","sources":["../../src/onboarding/degradation-accumulator.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,wEAAwE;AACxE,iEAAiE;AACjE,wEAAwE;AACxE,gDAAgD;AAChD,EAAE;AACF,+EAA+E;AAC/E,wEAAwE;AACxE,+EAA+E;AAC/E,qEAAqE;AAGrE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAqBjD,MAAM,UAAU,4BAA4B;IAC1C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAc,CAAC;IAEvC,OAAO;QACL,MAAM,CAAC,QAAoB;YACzB,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;QACD,IAAI;YACF,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QACD,OAAO;YACL,OAAO,QAAQ,CAAC,IAAI,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,uBAAuB,CAAC,KAAsB;YAC5C,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YACrC,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,KAAK,MAAM,QAAQ,IAAI,QAAQ,EAAE,CAAC;gBAChC,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;gBACzC,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;gBACxC,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAM,KAAK,WAAW,CAAC;gBAC/C,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC;gBACrD,MAAM,eAAe,GAAG,gBAAgB,KAAK,YAAY,CAAC;gBAC1D,MAAM,WAAW,GAAG,QAAQ;oBAC1B,CAAC,CAAC,GAAG,eAAe,aAAa;oBACjC,CAAC,CAAC,eAAe,CAAC;gBACpB,KAAK,CAAC,IAAI,CACR,eAAe,CAAC;oBACd,QAAQ;oBACR,MAAM,EAAE,yBAAyB;oBACjC,WAAW;oBACX,QAAQ,EAAE,QAAQ,IAAI,SAAS;iBAChC,CAAC,CACH,CAAC;YACJ,CAAC;YACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,KAAK;YACH,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/onboarding/prompt-user.d.ts

@@ -0,0 +1,23 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AskUserHandler } from "../types/index.js";
+export interface PromptOptions {
+    question: string;
+    questionType: "select" | "text" | "confirm";
+    options?: string[];
+    placeholder?: string;
+    reason?: string;
+}
+export interface PromptResult {
+    answer: string | null;
+    cancelled: boolean;
+}
+/**
+ * Ask the user a structured question, routing to the appropriate UI primitive
+ * (`ctx.ui.select` / `ctx.ui.input` / `ctx.ui.confirm`).
+ *
+ * When an `askUserHandler` is injected (test harness, programmatic runs), the
+ * handler takes precedence over `ctx.ui` and provides the answer directly.
+ *
+ * When neither a handler nor a UI is available, returns `{answer: null, cancelled: true}`.
+ */
+export declare function promptUser(ctx: ExtensionContext, opts: PromptOptions, handler?: AskUserHandler): Promise<PromptResult>;

package/dist/onboarding/prompt-user.js

@@ -0,0 +1,61 @@
+// Shared prompt primitive used by both the `ask_user` tool and the
+// credential-interception handler in the Pi `tool_result` hook.
+//
+// The original `ask_user` tool embedded its UI routing in a closure inside
+// `execute()`. Extracting it here means the `tool_result` handler can call
+// the same logic without synthesizing a fake tool call (Pi has no "execute
+// a tool now" API), and the headless harness's `askUserHandler` injection
+// point is preserved for automated flows.
+/**
+ * Ask the user a structured question, routing to the appropriate UI primitive
+ * (`ctx.ui.select` / `ctx.ui.input` / `ctx.ui.confirm`).
+ *
+ * When an `askUserHandler` is injected (test harness, programmatic runs), the
+ * handler takes precedence over `ctx.ui` and provides the answer directly.
+ *
+ * When neither a handler nor a UI is available, returns `{answer: null, cancelled: true}`.
+ */
+export async function promptUser(ctx, opts, handler) {
+    // Priority: injected handler > UI > no-UI fallback.
+    if (handler) {
+        const result = await handler({
+            question: opts.question,
+            questionType: opts.questionType,
+            options: opts.options,
+            placeholder: opts.placeholder,
+            reason: opts.reason,
+        });
+        if (result.cancelled) {
+            return { answer: null, cancelled: true };
+        }
+        return { answer: result.answer ?? null, cancelled: false };
+    }
+    if (!ctx?.hasUI) {
+        return { answer: null, cancelled: true };
+    }
+    switch (opts.questionType) {
+        case "select": {
+            const options = opts.options ?? [];
+            if (options.length === 0) {
+                return { answer: null, cancelled: true };
+            }
+            const choice = await ctx.ui.select(opts.question, options);
+            if (choice === undefined) {
+                return { answer: null, cancelled: true };
+            }
+            return { answer: choice, cancelled: false };
+        }
+        case "text": {
+            const input = await ctx.ui.input(opts.question, opts.placeholder ?? "");
+            if (input === undefined || input.trim() === "") {
+                return { answer: null, cancelled: true };
+            }
+            return { answer: input.trim(), cancelled: false };
+        }
+        case "confirm": {
+            const confirmed = await ctx.ui.confirm(opts.question, opts.reason ?? "");
+            return { answer: confirmed ? "Yes" : "No", cancelled: false };
+        }
+    }
+}
+//# sourceMappingURL=prompt-user.js.map

package/dist/onboarding/prompt-user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-user.js","sourceRoot":"","sources":["../../src/onboarding/prompt-user.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,2EAA2E;AAC3E,0EAA0E;AAC1E,0CAA0C;AAkB1C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAqB,EACrB,IAAmB,EACnB,OAAwB;IAExB,oDAAoD;IACpD,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC;YAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC3C,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC7D,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;QAChB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC3C,CAAC;IAED,QAAQ,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1B,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;YACnC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YAC3C,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC3D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YAC3C,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAC9C,CAAC;QAED,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;YACxE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;gBAC/C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YAC3C,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QACpD,CAAC;QAED,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;YACzE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAChE,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/onboarding/providers.d.ts

@@ -0,0 +1,116 @@
+export type ProviderId = "alpha_vantage" | "fred" | "finnhub" | "brave" | "exa";
+export type ProviderCategory = "fundamentals" | "macro" | "news" | "web_search";
+export type ProviderTier = "hard" | "soft";
+export interface ProviderDescriptor {
+    readonly id: ProviderId;
+    readonly displayName: string;
+    readonly category: ProviderCategory;
+    /**
+     * `hard` providers pause the workflow with a just-in-time prompt when their
+     * credential is missing; they have no meaningful fallback.
+     *
+     * `soft` providers silently use a fallback path and surface a post-answer
+     * gap note in the final output.
+     */
+    readonly tier: ProviderTier;
+    /** Lowercase friendly aliases accepted by `/connect` in addition to the id. */
+    readonly aliases: readonly string[];
+    readonly signupUrl: string;
+    readonly freeTier: boolean;
+    readonly envVar: string;
+    /** Nested key path into `OpenCandleFileConfig` where the key is persisted. */
+    readonly configPath: readonly string[];
+    readonly unlocks: readonly string[];
+    /**
+     * Human copy describing the degraded experience when missing, or `null`
+     * when there is no fallback (hard tier).
+     */
+    readonly fallbackDescription: string | null;
+    readonly snoozeDurationDays: number;
+    readonly instructionsHint: string;
+}
+export declare const PROVIDERS: readonly [{
+    readonly id: "alpha_vantage";
+    readonly displayName: "Alpha Vantage";
+    readonly category: "fundamentals";
+    readonly tier: "hard";
+    readonly aliases: readonly ["financials", "fundamentals", "company-financials", "alphavantage"];
+    readonly signupUrl: "https://www.alphavantage.co/support/#api-key";
+    readonly freeTier: true;
+    readonly envVar: "ALPHA_VANTAGE_API_KEY";
+    readonly configPath: readonly ["providers", "alphaVantage", "apiKey"];
+    readonly unlocks: readonly ["company fundamentals", "income/balance/cashflow statements", "DCF valuation", "earnings history"];
+    readonly fallbackDescription: null;
+    readonly snoozeDurationDays: 7;
+    readonly instructionsHint: "Free, about 30 seconds, signup opens in your browser";
+}, {
+    readonly id: "fred";
+    readonly displayName: "FRED";
+    readonly category: "macro";
+    readonly tier: "hard";
+    readonly aliases: readonly ["economy", "macro", "economic-data", "st-louis-fed"];
+    readonly signupUrl: "https://fredaccount.stlouisfed.org/apikeys";
+    readonly freeTier: true;
+    readonly envVar: "FRED_API_KEY";
+    readonly configPath: readonly ["providers", "fred", "apiKey"];
+    readonly unlocks: readonly ["interest rates", "inflation data", "yield curve", "economic indicators"];
+    readonly fallbackDescription: null;
+    readonly snoozeDurationDays: 7;
+    readonly instructionsHint: "Free, about 30 seconds, requires a St. Louis Fed account";
+}, {
+    readonly id: "finnhub";
+    readonly displayName: "Finnhub";
+    readonly category: "news";
+    readonly tier: "soft";
+    readonly aliases: readonly ["news", "company-news", "finnhub-news"];
+    readonly signupUrl: "https://finnhub.io/register";
+    readonly freeTier: true;
+    readonly envVar: "FINNHUB_API_KEY";
+    readonly configPath: readonly ["providers", "finnhub", "apiKey"];
+    readonly unlocks: readonly ["ticker-tagged company news", "sentiment enrichment with a dedicated news source"];
+    readonly fallbackDescription: "Other sentiment sources (Reddit, Twitter, web search) continue to work without Finnhub";
+    readonly snoozeDurationDays: 7;
+    readonly instructionsHint: "Free, about 30 seconds, signup opens in your browser";
+}, {
+    readonly id: "brave";
+    readonly displayName: "Brave Search";
+    readonly category: "web_search";
+    readonly tier: "soft";
+    readonly aliases: readonly ["brave", "brave-search"];
+    readonly signupUrl: "https://brave.com/search/api/";
+    readonly freeTier: true;
+    readonly envVar: "BRAVE_API_KEY";
+    readonly configPath: readonly ["providers", "brave", "apiKey"];
+    readonly unlocks: readonly ["tier-2 web search with freshness control", "independent search index outside of DuckDuckGo"];
+    readonly fallbackDescription: "Web search continues to work via DuckDuckGo (free, no key needed, lower-quality freshness)";
+    readonly snoozeDurationDays: 7;
+    readonly instructionsHint: "Free tier available, signup opens in your browser";
+}, {
+    readonly id: "exa";
+    readonly displayName: "Exa";
+    readonly category: "web_search";
+    readonly tier: "soft";
+    readonly aliases: readonly ["exa", "exa-search"];
+    readonly signupUrl: "https://dashboard.exa.ai/";
+    readonly freeTier: false;
+    readonly envVar: "EXA_API_KEY";
+    readonly configPath: readonly ["providers", "exa", "apiKey"];
+    readonly unlocks: readonly ["tier-1 semantic web search", "full article text and highlights", "higher freshness accuracy than DuckDuckGo"];
+    readonly fallbackDescription: "Exa search continues to work via the keyless Exa MCP endpoint, which has lower rate limits but similar quality";
+    readonly snoozeDurationDays: 7;
+    readonly instructionsHint: "Paid with free tier, signup opens in your browser";
+}];
+export declare function listAllProviders(): readonly ProviderDescriptor[];
+export declare function getProvider(id: ProviderId): ProviderDescriptor;
+export declare function getProvidersByCategory(category: ProviderCategory): readonly ProviderDescriptor[];
+export declare function getProvidersByTier(tier: ProviderTier): readonly ProviderDescriptor[];
+export declare function hasCredential(id: ProviderId): boolean;
+export declare function getCredentialSource(id: ProviderId): "env" | "file" | "absent";
+export declare function getCredential(id: ProviderId): {
+    source: "env" | "file";
+    value: string;
+} | {
+    source: "absent";
+    value?: undefined;
+};
+export declare function resolveProviderFromArgument(arg: string): ProviderDescriptor | readonly ProviderDescriptor[] | undefined;