opencandle 0.3.0 → 0.5.0

package/src/onboarding/tool-helpers.ts

@@ -0,0 +1,111 @@
+// 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 type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { ProviderCredentialError } from "../providers/provider-credential-error.js";
+import { getProvider, hasCredential, type ProviderId } from "./providers.js";
+import {
+  buildCredentialRequiredTag,
+  type CredentialRequiredReason,
+} from "./tool-tags.js";
+
+// Metadata carried on `details` for UI / test assertion. This is NOT the
+// LLM-facing contract — that lives in `content` as the tagged line. Pi
+// provider adapters serialize `content`, not `details`, into the model's
+// conversation.
+export interface CredentialRequiredDetails {
+  credentialRequired: {
+    provider: ProviderId;
+    reason: CredentialRequiredReason;
+    httpStatus?: number;
+  };
+}
+
+function buildCredentialRequiredResult(
+  provider: ProviderId,
+  reason: CredentialRequiredReason,
+  httpStatus?: number,
+): AgentToolResult<CredentialRequiredDetails> {
+  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<T>(
+  providerId: ProviderId,
+  fn: () => Promise<AgentToolResult<T>>,
+): Promise<AgentToolResult<T> | AgentToolResult<CredentialRequiredDetails>> {
+  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;
+  }
+}

package/src/onboarding/tool-tags.ts

@@ -0,0 +1,201 @@
+// 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.
+
+import type { ProviderId } from "./providers.js";
+
+// -----------------------------------------------------------------------------
+// Public types
+// -----------------------------------------------------------------------------
+
+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);
+
+// -----------------------------------------------------------------------------
+// Builders
+// -----------------------------------------------------------------------------
+
+function quote(value: string): string {
+  return `"${value.replace(/"/g, '\\"')}"`;
+}
+
+function formatField(key: string, value: string | number | boolean): string {
+  return `${key}=${value}`;
+}
+
+export function buildCredentialRequiredTag(fields: CredentialRequiredTagFields): string {
+  const parts: string[] = [
+    "[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: SoftDegradedTagFields): string {
+  return [
+    "[OPENCANDLE_SOFT_DEGRADED",
+    formatField("provider", fields.provider),
+    formatField("fallback", fields.fallback),
+    `remediation=${quote(fields.remediation)}`,
+  ].join(" ") + "]";
+}
+
+export function buildSkippedTag(fields: SkippedTagFields): string {
+  const parts: string[] = [
+    "[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: ConnectedTagFields): string {
+  return `[OPENCANDLE_CONNECTED provider=${fields.provider}]`;
+}
+
+// -----------------------------------------------------------------------------
+// Parser
+// -----------------------------------------------------------------------------
+
+const TAG_LINE_REGEX =
+  /\[OPENCANDLE_(CREDENTIAL_REQUIRED|SOFT_DEGRADED|SKIPPED|CONNECTED)([^\]]*)\]/;
+
+function parseFields(raw: string): Record<string, string> {
+  // Split on `key=value` pairs, respecting quoted values.
+  const fields: Record<string, string> = {};
+  const pattern = /(\w+)=("((?:[^"\\]|\\.)*)"|([^\s\]]+))/g;
+  let match: RegExpExecArray | null;
+  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: string): ParsedTag | undefined {
+  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: ParsedTag = {
+        kind: "credential_required",
+        provider: provider as ProviderId,
+        reason: reason as CredentialRequiredReason,
+        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 as ProviderId,
+        fallback,
+        remediation,
+      };
+    }
+
+    case "SKIPPED": {
+      const { provider, reason, remediation } = fields;
+      if (!provider || reason !== "credential_not_provided" || !remediation) {
+        return undefined;
+      }
+      const parsed: ParsedTag = {
+        kind: "skipped",
+        provider: provider as ProviderId,
+        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 as ProviderId };
+    }
+
+    default:
+      return undefined;
+  }
+}

package/src/onboarding/validation.ts

@@ -0,0 +1,158 @@
+// Pre-persist credential validation for OpenCandle data providers.
+//
+// Each `validateCredential` call makes a single cheap request to the
+// provider's canonical API with the pasted key and classifies the response
+// into one of three states:
+//
+//   - `valid`      — provider accepted the credential (persist it)
+//   - `invalid`    — provider rejected the credential (do NOT persist;
+//                    re-prompt or return a classified failure)
+//   - `transient`  — network/timeout/server error (persist anyway; the next
+//                    tool call will surface any real issue and re-open the
+//                    prompt via the credential-required tag)
+//
+// The endpoint chosen for each provider is the cheapest one available that
+// also exercises the auth header/query param — we don't pay for meaningful
+// data, just "did the server like the key". Alpha Vantage is a special case:
+// it returns HTTP 200 even for bad keys, with an `Error Message` or
+// `Information` field in the JSON body, so the body must be inspected.
+//
+// All validators share a 5-second timeout via `AbortSignal.timeout` so the
+// connect flow cannot hang if a provider is unreachable.
+
+import type { ProviderId } from "./providers.js";
+
+const VALIDATION_TIMEOUT_MS = 5_000;
+
+export type ValidationResult =
+  | { status: "valid" }
+  | { status: "invalid"; httpStatus?: number; message?: string }
+  | { status: "transient"; reason: string };
+
+type BodyClassifier = (body: string) => ValidationResult | undefined;
+
+async function validateWithFetch(
+  url: string,
+  init: RequestInit,
+  classifyBody?: BodyClassifier,
+): Promise<ValidationResult> {
+  try {
+    const response = await fetch(url, {
+      ...init,
+      signal: AbortSignal.timeout(VALIDATION_TIMEOUT_MS),
+    });
+
+    // Hard auth failures — the key is definitively bad.
+    if (response.status === 401 || response.status === 403) {
+      return { status: "invalid", httpStatus: response.status };
+    }
+
+    // FRED returns 400 with an `error_message` for bad keys.
+    if (response.status === 400) {
+      return { status: "invalid", httpStatus: 400 };
+    }
+
+    // 5xx and other non-2xx — treat as transient. Don't block the user on a
+    // provider outage; the next real tool call will surface a fresh error.
+    if (!response.ok) {
+      return { status: "transient", reason: `HTTP ${response.status}` };
+    }
+
+    // Body-level classification for providers that return 200 with an error
+    // shape (Alpha Vantage).
+    if (classifyBody) {
+      const body = await response.text();
+      const classified = classifyBody(body);
+      if (classified) return classified;
+    }
+
+    return { status: "valid" };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return { status: "transient", reason };
+  }
+}
+
+/**
+ * Alpha Vantage returns HTTP 200 with an error shape in the JSON body when
+ * the key is bad. Two fields to watch for:
+ *   - `Error Message`: indicates a malformed query OR an invalid key
+ *   - `Information`: used for rate-limit messages AND for "Invalid API key"
+ *
+ * The rate-limit form of `Information` is NOT an invalid-key signal, so we
+ * only match when the string mentions "invalid api".
+ */
+function classifyAlphaVantageBody(body: string): ValidationResult | undefined {
+  try {
+    const parsed = JSON.parse(body) as Record<string, unknown>;
+    const errorMessage = parsed["Error Message"];
+    if (typeof errorMessage === "string" && errorMessage.length > 0) {
+      return { status: "invalid", message: errorMessage };
+    }
+    const information = parsed["Information"];
+    if (typeof information === "string" && /invalid api/i.test(information)) {
+      return { status: "invalid", message: information };
+    }
+  } catch {
+    // Non-JSON body — fall through and trust the HTTP status.
+  }
+  return undefined;
+}
+
+/**
+ * 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 async function validateCredential(
+  providerId: ProviderId,
+  key: string,
+): Promise<ValidationResult> {
+  switch (providerId) {
+    case "alpha_vantage":
+      return validateWithFetch(
+        `https://www.alphavantage.co/query?function=GLOBAL_QUOTE&symbol=IBM&apikey=${encodeURIComponent(key)}`,
+        { method: "GET" },
+        classifyAlphaVantageBody,
+      );
+
+    case "fred":
+      return validateWithFetch(
+        `https://api.stlouisfed.org/fred/series?series_id=GDP&api_key=${encodeURIComponent(key)}&file_type=json`,
+        { method: "GET" },
+      );
+
+    case "finnhub":
+      return validateWithFetch(
+        `https://finnhub.io/api/v1/quote?symbol=AAPL&token=${encodeURIComponent(key)}`,
+        { method: "GET" },
+      );
+
+    case "brave":
+      return validateWithFetch(
+        "https://api.search.brave.com/res/v1/web/search?q=test&count=1",
+        {
+          method: "GET",
+          headers: {
+            "X-Subscription-Token": key,
+            Accept: "application/json",
+          },
+        },
+      );
+
+    case "exa":
+      return validateWithFetch(
+        "https://api.exa.ai/search",
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-api-key": key,
+          },
+          body: JSON.stringify({ query: "test", numResults: 1 }),
+        },
+      );
+  }
+}