opencandle 0.11.0 → 0.12.0

package/src/onboarding/credential-interceptor.ts

@@ -1,122 +0,0 @@
-// 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 type { ProviderId } from "./providers.js";
-import { getProvider } 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;
-    };
-
-function buildRemediation(providerId: ProviderId): string {
-  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: ProviderId, silenced: boolean): InterceptAction {
-  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: InterceptInput): InterceptAction {
-  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 };
-}

package/src/onboarding/degradation-accumulator.ts

@@ -1,77 +0,0 @@
-// 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 type { ProviderId } from "./providers.js";
-import { getProvider } from "./providers.js";
-import type { OnboardingState } from "./state.js";
-import { buildSkippedTag } from "./tool-tags.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 function createDegradationAccumulator(): DegradationAccumulator {
-  const recorded = new Set<ProviderId>();
-
-  return {
-    record(provider: ProviderId): void {
-      recorded.add(provider);
-    },
-    size(): number {
-      return recorded.size;
-    },
-    isEmpty(): boolean {
-      return recorded.size === 0;
-    },
-    buildCombinedAnnotation(state: OnboardingState): string | null {
-      if (recorded.size === 0) return null;
-      const lines: string[] = [];
-      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(): void {
-      recorded.clear();
-    },
-  };
-}

package/src/onboarding/prompt-user.ts

@@ -1,85 +0,0 @@
-// 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.
-
-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 async function promptUser(
-  ctx: ExtensionContext,
-  opts: PromptOptions,
-  handler?: AskUserHandler,
-): Promise<PromptResult> {
-  // 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 };
-    }
-  }
-}

package/src/onboarding/provider-status.ts

@@ -1,382 +0,0 @@
-import {
-  type ExternalToolCommandResult,
-  runExternalToolCommand,
-} from "../providers/external-tool-command.js";
-import type { ProviderId } from "./providers.js";
-import {
-  getCredentialSource,
-  getProvider,
-  isApiKeyProvider,
-  isExternalToolProvider,
-  isPublicHttpProvider,
-} from "./providers.js";
-import { loadOnboardingState } from "./state.js";
-
-const STATUS_TTL_MS = 60_000;
-const COMMAND_TIMEOUT_MS = 5_000;
-const PUBLIC_HTTP_TIMEOUT_MS = 3_000;
-const MAX_OUTPUT_CHARS = 32_000;
-
-export type CommandResult = ExternalToolCommandResult;
-
-export type CommandRunner = (
-  command: string,
-  args: readonly string[],
-  options?: { timeoutMs: number },
-) => Promise<CommandResult>;
-
-interface ProviderStatusBase {
-  readonly providerId: ProviderId;
-  readonly kind: "api-key" | "external-tool" | "public-http";
-  readonly state: string;
-  readonly checkedAt: string;
-  readonly cacheHit: boolean;
-  readonly message?: string;
-}
-
-export interface ApiKeyProviderStatus extends ProviderStatusBase {
-  readonly kind: "api-key";
-  readonly state: "configured" | "missing";
-  readonly credentialSource: "env" | "file" | "absent";
-}
-
-export interface ExternalToolProviderStatus extends ProviderStatusBase {
-  readonly kind: "external-tool";
-  readonly mode: "install" | "session";
-  readonly state:
-    | "installed"
-    | "missing"
-    | "session_ok"
-    | "session_missing"
-    | "session_stale"
-    | "skipped"
-    | "error";
-  readonly installCmd?: string;
-}
-
-export interface PublicHttpProviderStatus extends ProviderStatusBase {
-  readonly kind: "public-http";
-  readonly state: "reachable" | "unreachable" | "error";
-  readonly statusCode?: number;
-}
-
-export type ProviderStatus =
-  | ApiKeyProviderStatus
-  | ExternalToolProviderStatus
-  | PublicHttpProviderStatus;
-
-export interface ProbeProviderStatusOptions {
-  readonly mode?: "install" | "session";
-  readonly force?: boolean;
-  readonly respectSkipped?: boolean;
-  readonly commandRunner?: CommandRunner;
-  readonly fetchImpl?: typeof fetch;
-  readonly now?: Date;
-}
-
-interface CachedStatus {
-  readonly expiresAt: number;
-  readonly status: ProviderStatus;
-}
-
-const statusCache = new Map<string, CachedStatus>();
-
-export function clearProviderStatusCache(): void {
-  statusCache.clear();
-}
-
-export async function probeProviderStatus(
-  providerId: ProviderId,
-  options: ProbeProviderStatusOptions = {},
-): Promise<ProviderStatus> {
-  const provider = getProvider(providerId);
-  const mode = isExternalToolProvider(provider) ? (options.mode ?? "install") : "default";
-  const cacheKey = `${providerId}:${mode}`;
-  const now = options.now ?? new Date();
-  const skippedByPreference =
-    isExternalToolProvider(provider) &&
-    loadOnboardingState().providers[providerId]?.status === "never_ask";
-
-  if (skippedByPreference && (!options.force || options.respectSkipped)) {
-    return {
-      providerId,
-      kind: "external-tool",
-      mode: mode as "install" | "session",
-      state: "skipped",
-      installCmd: provider.installCmd,
-      message: `Skipped by user preference; run opencandle doctor --enable ${providerId} to re-enable.`,
-      checkedAt: now.toISOString(),
-      cacheHit: false,
-    };
-  }
-
-  if (!options.force) {
-    const cached = statusCache.get(cacheKey);
-    if (cached && cached.expiresAt > now.getTime()) {
-      return { ...cached.status, cacheHit: true };
-    }
-  }
-
-  let status: ProviderStatus;
-  if (isApiKeyProvider(provider)) {
-    const source = getCredentialSource(provider.id);
-    status = {
-      providerId,
-      kind: "api-key",
-      state: source === "absent" ? "missing" : "configured",
-      credentialSource: source,
-      checkedAt: now.toISOString(),
-      cacheHit: false,
-    };
-  } else if (isExternalToolProvider(provider)) {
-    status = await probeExternalTool(providerId, mode as "install" | "session", {
-      now,
-      commandRunner: options.commandRunner ?? runCommand,
-    });
-  } else if (isPublicHttpProvider(provider)) {
-    status = await probePublicHttp(providerId, {
-      now,
-      fetchImpl: options.fetchImpl ?? fetch,
-    });
-  } else {
-    const exhaustive: never = provider;
-    throw new Error(`Unsupported provider kind: ${JSON.stringify(exhaustive)}`);
-  }
-
-  statusCache.set(cacheKey, { status, expiresAt: now.getTime() + STATUS_TTL_MS });
-  return status;
-}
-
-export async function probeAllProviderStatuses(
-  options: Omit<ProbeProviderStatusOptions, "mode"> = {},
-): Promise<ProviderStatus[]> {
-  const { listAllProviders } = await import("./providers.js");
-  const statuses: ProviderStatus[] = [];
-  for (const provider of listAllProviders()) {
-    statuses.push(await probeProviderStatus(provider.id, options));
-  }
-  return statuses;
-}
-
-export function formatProviderStatus(status: ProviderStatus): string {
-  const provider = getProvider(status.providerId);
-  if (status.kind === "api-key") {
-    return `${provider.displayName}: ${status.state} (${status.credentialSource})`;
-  }
-  if (status.kind === "external-tool") {
-    const suffix = status.message ? ` - ${status.message}` : "";
-    return `${provider.displayName}: ${status.state} (${status.mode})${suffix}`;
-  }
-  const http = status.statusCode === undefined ? "" : ` HTTP ${status.statusCode}`;
-  const suffix = status.message ? ` - ${status.message}` : "";
-  return `${provider.displayName}: ${status.state}${http}${suffix}`;
-}
-
-async function probeExternalTool(
-  providerId: ProviderId,
-  mode: "install" | "session",
-  options: { now: Date; commandRunner: CommandRunner },
-): Promise<ExternalToolProviderStatus> {
-  const provider = getProvider(providerId);
-  if (!isExternalToolProvider(provider)) {
-    throw new Error(`Provider ${providerId} is not an external tool`);
-  }
-
-  const args =
-    mode === "install"
-      ? ["--version"]
-      : (provider.sessionProbeArgs ?? ["feed", "--max", "1", "--json"]);
-  try {
-    const result = await options.commandRunner(provider.binary, args, {
-      timeoutMs: COMMAND_TIMEOUT_MS,
-    });
-    const output = redactSensitiveOutput(`${result.stderr}\n${result.stdout}`.trim());
-
-    if (mode === "install") {
-      return {
-        providerId,
-        kind: "external-tool",
-        mode,
-        state: result.code === 0 ? "installed" : "error",
-        installCmd: provider.installCmd,
-        message: result.code === 0 ? undefined : output,
-        checkedAt: options.now.toISOString(),
-        cacheHit: false,
-      };
-    }
-
-    if (result.code === 0) {
-      const parsed = parseCliEnvelope(result.stdout, provider.binary);
-      const session = classifySessionEnvelope(providerId, parsed);
-      return {
-        providerId,
-        kind: "external-tool",
-        mode,
-        state: session.state,
-        installCmd: provider.installCmd,
-        message: session.message,
-        checkedAt: options.now.toISOString(),
-        cacheHit: false,
-      };
-    }
-
-    return {
-      providerId,
-      kind: "external-tool",
-      mode,
-      state: classifySessionFailure(output),
-      installCmd: provider.installCmd,
-      message: output,
-      checkedAt: options.now.toISOString(),
-      cacheHit: false,
-    };
-  } catch (err) {
-    const nodeError = err as NodeJS.ErrnoException;
-    if (nodeError.code === "ENOENT") {
-      return {
-        providerId,
-        kind: "external-tool",
-        mode,
-        state: "missing",
-        installCmd: provider.installCmd,
-        checkedAt: options.now.toISOString(),
-        cacheHit: false,
-      };
-    }
-    return {
-      providerId,
-      kind: "external-tool",
-      mode,
-      state: "error",
-      installCmd: provider.installCmd,
-      message: redactSensitiveOutput(err instanceof Error ? err.message : String(err)),
-      checkedAt: options.now.toISOString(),
-      cacheHit: false,
-    };
-  }
-}
-
-async function probePublicHttp(
-  providerId: ProviderId,
-  options: { now: Date; fetchImpl: typeof fetch },
-): Promise<PublicHttpProviderStatus> {
-  const provider = getProvider(providerId);
-  if (!isPublicHttpProvider(provider)) {
-    throw new Error(`Provider ${providerId} is not a public HTTP provider`);
-  }
-
-  try {
-    const response = await options.fetchImpl(provider.probeUrl, {
-      method: "GET",
-      signal: AbortSignal.timeout(PUBLIC_HTTP_TIMEOUT_MS),
-    });
-    return {
-      providerId,
-      kind: "public-http",
-      state: response.ok ? "reachable" : "unreachable",
-      statusCode: response.status,
-      checkedAt: options.now.toISOString(),
-      cacheHit: false,
-    };
-  } catch (err) {
-    return {
-      providerId,
-      kind: "public-http",
-      state: "error",
-      message: err instanceof Error ? err.message : String(err),
-      checkedAt: options.now.toISOString(),
-      cacheHit: false,
-    };
-  }
-}
-
-function parseCliEnvelope(
-  stdout: string,
-  binary: string,
-): { ok: boolean; message?: string; data?: unknown } {
-  try {
-    const parsed = JSON.parse(stdout) as {
-      ok?: unknown;
-      data?: unknown;
-      error?: { message?: unknown };
-    };
-    return {
-      ok: parsed.ok === true,
-      data: parsed.data,
-      message:
-        typeof parsed.error?.message === "string"
-          ? redactSensitiveOutput(parsed.error.message)
-          : undefined,
-    };
-  } catch {
-    return { ok: false, message: `${binary} returned non-JSON output` };
-  }
-}
-
-function classifySessionEnvelope(
-  providerId: ProviderId,
-  parsed: { ok: boolean; message?: string; data?: unknown },
-): { state: ExternalToolProviderStatus["state"]; message?: string } {
-  if (!parsed.ok) {
-    return {
-      state: classifySessionFailure(parsed.message),
-      message: parsed.message,
-    };
-  }
-
-  if (providerId === "reddit" && isRecord(parsed.data) && parsed.data.authenticated === false) {
-    return {
-      state: "session_missing",
-      message: "Reddit is not authenticated. Run rdt login.",
-    };
-  }
-
-  return { state: "session_ok" };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-function classifySessionFailure(message: string | undefined): ExternalToolProviderStatus["state"] {
-  const lower = (message ?? "").toLowerCase();
-  if (
-    lower.includes("no twitter cookies") ||
-    lower.includes("no reddit cookies") ||
-    lower.includes("not authenticated") ||
-    lower.includes("no cookies")
-  ) {
-    return "session_missing";
-  }
-  if (lower.includes("401") || lower.includes("unauthorized") || lower.includes("expired")) {
-    return "session_stale";
-  }
-  return "error";
-}
-
-export function redactSensitiveOutput(input: string): string {
-  const xCookieNames =
-    "auth_token|ct0|twid|kdt|guest_id|guest_id_ads|guest_id_marketing|personalization_id";
-  const genericSecretName =
-    "[a-z0-9_]*(?:session|token)[a-z0-9_]*|[a-z0-9_]+cookie[a-z0-9_]*|[a-z0-9_]*cookie[a-z0-9_]+";
-  return input
-    .slice(0, MAX_OUTPUT_CHARS)
-    .replace(/\b(cookie|set-cookie)\s*:\s*[^\r\n]+/gi, "$1: [redacted]")
-    .replace(new RegExp(`\\b(${xCookieNames})\\b\\s*[:=]\\s*[^;\\s,)]+`, "gi"), "$1=[redacted]")
-    .replace(new RegExp(`\\b(${xCookieNames})=([^;\\s,)]+)`, "gi"), "$1=[redacted]")
-    .replace(
-      new RegExp(`\\b(${genericSecretName})\\b\\s*[:=]\\s*[^;\\s,)]+`, "gi"),
-      "$1=[redacted]",
-    )
-    .replace(new RegExp(`\\b(${genericSecretName})=([^;\\s,)]+)`, "gi"), "$1=[redacted]")
-    .replace(
-      /(?:~|\/Users\/[^/\s]+|\/home\/[^/\s]+)?\/\.config\/rdt-cli\/credential\.json/g,
-      "[redacted-credential-path]",
-    );
-}
-
-export const runCommand: CommandRunner = (command, args, options) =>
-  runExternalToolCommand(command, args, {
-    timeoutMs: options?.timeoutMs ?? COMMAND_TIMEOUT_MS,
-    maxOutputChars: MAX_OUTPUT_CHARS,
-  });