opencandle 0.11.1 → 0.13.0

package/src/onboarding/tool-helpers.ts

@@ -1,104 +0,0 @@
-// 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

@@ -1,244 +0,0 @@
-// 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 type ExternalToolRequiredReason = "not_installed" | "session_missing" | "session_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 interface ExternalToolRequiredTagFields {
-  provider: ProviderId;
-  reason: ExternalToolRequiredReason;
-  installCmd: string;
-  loginCmd?: string;
-  fallback: string | null;
-}
-
-export type ParsedTag =
-  | ({ kind: "credential_required" } & CredentialRequiredTagFields)
-  | ({ kind: "soft_degraded" } & SoftDegradedTagFields)
-  | ({ kind: "skipped" } & SkippedTagFields)
-  | ({ kind: "connected" } & ConnectedTagFields)
-  | ({ kind: "external_tool_required" } & ExternalToolRequiredTagFields);
-
-// -----------------------------------------------------------------------------
-// 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}]`;
-}
-
-export function buildExternalToolRequiredTag(fields: ExternalToolRequiredTagFields): string {
-  const parts: string[] = [
-    "[OPENCANDLE_EXTERNAL_TOOL_REQUIRED",
-    formatField("provider", fields.provider),
-    formatField("reason", fields.reason),
-    `installCmd=${quote(fields.installCmd)}`,
-    formatField("fallback", fields.fallback ?? "none"),
-  ];
-  if (fields.loginCmd) parts.push(`loginCmd=${quote(fields.loginCmd)}`);
-  return `${parts.join(" ")}]`;
-}
-
-// -----------------------------------------------------------------------------
-// Parser
-// -----------------------------------------------------------------------------
-
-const TAG_LINE_REGEX =
-  /\[OPENCANDLE_(CREDENTIAL_REQUIRED|SOFT_DEGRADED|SKIPPED|CONNECTED|EXTERNAL_TOOL_REQUIRED)([^\]]*)\]/;
-
-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;
-  while (true) {
-    const match = pattern.exec(raw);
-    if (!match) break;
-    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 };
-    }
-
-    case "EXTERNAL_TOOL_REQUIRED": {
-      const { provider, reason, installCmd, loginCmd, fallback } = fields;
-      if (
-        !provider ||
-        (reason !== "not_installed" &&
-          reason !== "session_missing" &&
-          reason !== "session_stale") ||
-        !installCmd
-      ) {
-        return undefined;
-      }
-      return {
-        kind: "external_tool_required",
-        provider: provider as ProviderId,
-        reason,
-        installCmd,
-        loginCmd,
-        fallback: fallback === undefined || fallback === "none" ? null : fallback,
-      };
-    }
-
-    default:
-      return undefined;
-  }
-}

package/src/onboarding/validation.ts

@@ -1,152 +0,0 @@
-// 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 { ApiKeyProviderId } 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: ApiKeyProviderId,
-  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 }),
-      });
-  }
-}