@pi-in-go/pigpen-pi-typesafe 0.1.0

package/port/oracle/src/credentials.ts

@@ -0,0 +1,136 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DEFAULT_BACKEND, TYPESAFE_KEY_ENV, resolveBackend, usesTypesafeKey } from "./backends.js";
+import type { BackendSpec } from "./backends.js";
+import { TypeSafeIntegrationError } from "./errors.js";
+
+export type KeySource = "environment" | "stored";
+
+/**
+ * The complete answer to "which key is in effect" for a valid backend: it never throws. An invalid backend — an
+ * unknown name or an endpoint object that fails validation — throws the same `configuration` error as resolveBackend.
+ */
+export type KeySituation =
+  /** `keyEnv` names the variable that was read; absent means `TYPESAFE_API_KEY`. */
+  | { readonly kind: "environment"; readonly key: string; readonly keyEnv?: string }
+  | { readonly kind: "stored"; readonly key: string; readonly path: string }
+  | { readonly kind: "missing" }
+  | { readonly kind: "unusable"; readonly path: string; readonly reason: string };
+
+/** Mirrors Pi's agent directory rule; every pi-typesafe file lives in this one directory. */
+export function piTypesafeDir(): string {
+  const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+  const agentDir = configured
+    ? (configured === "~" || configured.startsWith("~/") ? join(homedir(), configured.slice(1)) : configured)
+    : join(homedir(), ".pi", "agent");
+  return join(agentDir, "pi-typesafe");
+}
+
+/** Where the key lives, next to Pi's own auth.json. */
+export function credentialsPath(): string {
+  return join(piTypesafeDir(), "auth.json");
+}
+
+/** Accepts the key only when it is a plausible token; never logs or echoes the value. */
+export function normalizeApiKey(value: unknown): string {
+  const key = typeof value === "string" ? value.trim() : "";
+  if (key.length < 16 || key.length > 512 || /\s/.test(key) || /[^\x21-\x7e]/.test(key)) {
+    throw new TypeSafeIntegrationError("validation", "That does not look like a TypeSafe API key. Copy the complete key from console.typesafe.ai and try again; nothing was saved.");
+  }
+  return key;
+}
+
+/**
+ * The stored key, or `undefined` when the file is missing, unreadable, or holds no usable value. Throws
+ * `configuration` when the file is readable by other users; keySituation() reports that case as `unusable` instead.
+ */
+export function readStoredApiKey(): string | undefined {
+  const path = credentialsPath();
+  try {
+    if (process.platform !== "win32" && (statSync(path).mode & 0o077) !== 0) {
+      // Refuse to use a key other local users can read; the user must fix permissions or log in again.
+      throw new TypeSafeIntegrationError("configuration", `Refusing to read ${path}: it is readable by other users. Run chmod 600 on it, or run /typesafe logout and /typesafe login.`);
+    }
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    const key = parsed && typeof parsed === "object" ? (parsed as { apiKey?: unknown }).apiKey : undefined;
+    return typeof key === "string" && key.trim() ? key.trim() : undefined;
+  } catch (error) {
+    if (error instanceof TypeSafeIntegrationError) throw error;
+    return undefined;
+  }
+}
+
+/**
+ * What the environment, the login store, and file permissions add up to right now for one judgment backend. A valid
+ * backend never throws: the "unusable" kind carries the user-facing reason (a stored key that other local users can
+ * read). An invalid backend — an unknown name or an endpoint object that fails validation — throws the same
+ * `configuration` error as resolveBackend(), so validate a user-supplied endpoint with resolveBackend() first.
+ * The TypeSafe backend reads `TYPESAFE_API_KEY`, then the login store. Every other backend reads only its own
+ * environment variable, because the store holds a TypeSafe key and a login verifies against api.typesafe.ai.
+ */
+export function keySituation(backend: BackendSpec = DEFAULT_BACKEND): KeySituation {
+  const config = resolveBackend(backend);
+  const keyEnv = config.keyEnv;
+  const fromEnvironment = process.env[keyEnv]?.trim();
+  if (fromEnvironment) return { kind: "environment", key: fromEnvironment, keyEnv };
+  if (!usesTypesafeKey(config)) return { kind: "missing" };
+  const path = credentialsPath();
+  try {
+    const key = readStoredApiKey();
+    return key ? { kind: "stored", key, path } : { kind: "missing" };
+  } catch (error) {
+    // readStoredApiKey only throws for a store this process must not use; report it instead of failing the caller.
+    if (error instanceof TypeSafeIntegrationError && error.code === "configuration") return { kind: "unusable", path, reason: error.message };
+    throw error;
+  }
+}
+
+/** Short phrase naming the source; full sentences stay with the caller. */
+export function keySourceLabel(situation: KeySituation): string {
+  switch (situation.kind) {
+    case "environment": return situation.keyEnv ?? TYPESAFE_KEY_ENV;
+    case "stored": return "/typesafe login";
+    case "missing": return "no key";
+    case "unusable": return "unusable key";
+  }
+}
+
+/**
+ * The pre-0.4.0 key interface, frozen for existing callers: environment first so CI and scripts stay explicit, the
+ * stored key as the interactive default, `undefined` when no key is configured, and a `configuration` error when a
+ * store must not be read. New code should call keySituation() instead: same precedence, never throws for a valid
+ * backend (an invalid one throws resolveBackend's `configuration` error), and the "must not be read" case arrives as
+ * `unusable` with the reason.
+ */
+export function resolveApiKey(backend: BackendSpec = DEFAULT_BACKEND): { key: string; source: KeySource } | undefined {
+  const situation = keySituation(backend);
+  if (situation.kind === "unusable") throw new TypeSafeIntegrationError("configuration", situation.reason);
+  return situation.kind === "environment" || situation.kind === "stored" ? { key: situation.key, source: situation.kind } : undefined;
+}
+
+export function storeApiKey(value: unknown): string {
+  const key = normalizeApiKey(value);
+  const path = credentialsPath();
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify({ apiKey: key }, null, 2)}\n`, { mode: 0o600, flag: "w" });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, path);
+  } catch {
+    throw new TypeSafeIntegrationError("configuration", `Could not write ${path}. Check directory permissions, or set TYPESAFE_API_KEY in the environment instead.`);
+  }
+  return path;
+}
+
+export function clearStoredApiKey(): boolean {
+  const path = credentialsPath();
+  try {
+    statSync(path);
+  } catch {
+    return false;
+  }
+  rmSync(path, { force: true });
+  return true;
+}

package/port/oracle/src/errors.ts

@@ -0,0 +1,53 @@
+import { APIError, APIConnectionError, APITimeoutError, APIUserAbortError } from "@typesafe-ai/sdk";
+import { DECISIONS_BACKENDS, TYPESAFE_KEY_ENV, backendConfig } from "./backends.js";
+import type { BackendConfig, BackendSpec } from "./backends.js";
+
+export type IntegrationErrorCode = "configuration" | "validation" | "budget" | "aborted" | "timeout" | "http" | "connection" | "response";
+
+/**
+ * Safe to display: never contains upstream bodies, keys, or submitted state. The only header value a message can
+ * quote is a numeric Retry-After count in seconds, which cannot carry a secret.
+ */
+export class TypeSafeIntegrationError extends Error {
+  override readonly name = "TypeSafeIntegrationError";
+  constructor(
+    readonly code: IntegrationErrorCode,
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+  }
+}
+
+/** A numeric Retry-After delay in seconds; dates, blanks, and anything else stay out of the message. */
+function retryAfterSeconds(error: APIError): number | undefined {
+  const raw = error.headers?.get("retry-after")?.trim();
+  if (!raw) return undefined;
+  const seconds = Number(raw);
+  return Number.isSafeInteger(seconds) && seconds >= 0 ? seconds : undefined;
+}
+
+/**
+ * Classify an error into a message safe to display. `backend` names the key variable the 401 advice tells the user
+ * to check and selects the 402 wording; omitting it keeps the one-argument call and assumes the default TypeSafe key.
+ */
+export function safeError(error: unknown, backend?: BackendSpec | BackendConfig): TypeSafeIntegrationError {
+  if (error instanceof TypeSafeIntegrationError) return error;
+  if (error instanceof APIUserAbortError) return new TypeSafeIntegrationError("aborted", "TypeSafe request cancelled; an already submitted request may still be billed.");
+  if (error instanceof APITimeoutError) return new TypeSafeIntegrationError("timeout", "TypeSafe request timed out; it was not retried and may still be billed.");
+  if (error instanceof APIError) {
+    const config = backend === undefined ? undefined : typeof backend === "string" ? backendConfig(backend) : backend;
+    const keyEnv = config?.keyEnv ?? TYPESAFE_KEY_ENV;
+    const openrouter = config !== undefined && config.host === DECISIONS_BACKENDS.openrouter.host;
+    const retry = error.status === 429 ? retryAfterSeconds(error) : undefined;
+    const advice = error.status === 401 ? `Check ${keyEnv}.`
+      : error.status === 402 ? (openrouter ? "Insufficient credits. Add credits at https://openrouter.ai/credits." : "Check your account balance.")
+      : error.status === 403 ? "Check your account access and model permissions."
+      : error.status === 429 ? `Check your account quota and try again later.${retry === undefined ? "" : ` Retry after ${retry} seconds.`}`
+      : error.status === 400 || error.status === 422 ? "Check the question format and model limits."
+      : "Try again later or check the service status.";
+    return new TypeSafeIntegrationError("http", `TypeSafe returned HTTP ${error.status}. ${advice} No automatic retry was made.`, error.status);
+  }
+  if (error instanceof APIConnectionError) return new TypeSafeIntegrationError("connection", "Could not complete the TypeSafe connection. No automatic retry was made.");
+  return new TypeSafeIntegrationError("response", "TypeSafe returned an unreadable or unexpected response.");
+}

package/port/oracle/src/extension.ts

@@ -0,0 +1,204 @@
+import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Static } from "typebox";
+import { Text } from "@earendil-works/pi-tui";
+import type { Questions } from "@typesafe-ai/sdk";
+import { DEFAULT_BACKEND, defaultModelId } from "./backends.js";
+import { createTypeSafe, DEFAULT_MAX_REQUESTS } from "./client.js";
+import type { Evaluation, TypeSafe } from "./client.js";
+import { authState, clearAuthState, describeAuth } from "./auth.js";
+import { clearStoredApiKey, credentialsPath, keySituation, keySourceLabel } from "./credentials.js";
+import { TypeSafeIntegrationError, safeError } from "./errors.js";
+import { loginWithPrompt } from "./login.js";
+import { DEFAULT_MAX_INPUT_BYTES, evaluationSchema, normalizeEvaluationRequest, prepareEvaluationRequest } from "./schema.js";
+
+const disclosure = "Submitted state and questions will be sent to api.typesafe.ai and may incur charges. Do not include secrets. The extension does not collect files or conversation history. Results are model judgments, not proof or authorization.";
+const sample = {
+  state: { message: "I was charged twice for my subscription. Please help today." },
+  questions: {
+    category: { type: "choice", instructions: "Which team should handle this message?", criteria: { billing: "Charges and payments", technical: "Software failures", other: "None of these" } },
+    urgent: { type: "noul", instructions: "Does the sender request help today?" },
+    frustration: { type: "score", instructions: "How frustrated does the sender sound?", criteria: ["Neutral request", "Frustrated but civil", "Angry or threatening"] },
+  },
+};
+
+function format(result: Evaluation<Questions>, expanded = false): string {
+  const lines = [`TypeSafe · ${JSON.stringify(result.model)} · ${result.elapsedMs} ms`];
+  for (const [id, answer] of Object.entries(result.answers)) {
+    const label = JSON.stringify(id);
+    if (answer.type === "noul") lines.push(`${label}: P(yes) = ${answer.noul.toFixed(3)}`);
+    else if (answer.type === "choice") lines.push(`${label}: ${JSON.stringify(answer.choice)} · confidence ${answer.confidence.toFixed(3)}`);
+    else lines.push(`${label}: ${answer.score.toFixed(3)} · confidence ${answer.confidence.toFixed(3)}`);
+    if (expanded && answer.type !== "noul") lines.push(`  ${JSON.stringify(answer.probabilities)}`);
+  }
+  lines.push(`${result.usage.input_tokens} input / ${result.usage.output_tokens} output tokens`);
+  lines.push("Confidence is distribution concentration, not proof of correctness.");
+  return lines.join("\n");
+}
+
+/** Native Pi registration; importing the root library does not load this module. */
+export default function typesafeExtension(pi: ExtensionAPI): void {
+  let enabled = process.env.PI_TYPESAFE_ENABLED === "1";
+  let client: TypeSafe | undefined;
+  // One callout per distinct degradation per session: a long run must not bury the reason in repeated notices.
+  let calledOut: string | undefined;
+  const getClient = () => client ??= createTypeSafe();
+  const callOut = (ctx: ExtensionContext | undefined, key: string, text: string) => {
+    if (calledOut === key) return;
+    calledOut = key;
+    try {
+      if (ctx?.hasUI) ctx.ui.notify(text, "warning");
+      else pi.sendMessage({ customType: "typesafe-status", content: text, display: true });
+    } catch {
+      // Reporting must never replace the failure it describes, and a headless run may have no message channel.
+    }
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    enabled = process.env.PI_TYPESAFE_ENABLED === "1";
+    client = undefined;
+    calledOut = undefined;
+    // An enabled extension with no usable key used to look exactly like a working one. Say it at startup; an
+    // unverified-but-present key stays quiet, because the first request is what proves it.
+    const auth = describeAuth(authState());
+    if (enabled && auth.level === "error") callOut(ctx, `start:${auth.level}`, `TypeSafe is enabled but judgments are skipped. ${auth.text}`);
+  });
+
+  pi.registerEntryRenderer<Evaluation<Questions>>("typesafe-result", (entry, { expanded }) => new Text(entry.data ? format(entry.data, expanded) : "TypeSafe · no result", 0, 0));
+
+  pi.registerTool({
+    name: "typesafe_evaluate",
+    label: "TypeSafe",
+    description: `Evaluate supplied state with independent Choice, Score, and Noul questions in one TypeSafe request. Each question judges the whole state, so when several items are involved, put each item in a named state field (e.g. \`reports.r1\`) and ask one question per item per dimension (e.g. \`r1_owner\`, \`r2_owner\`), naming the field in the instructions; never aggregate several items into one question. ${disclosure} Requires operator opt-in via /typesafe enable or PI_TYPESAFE_ENABLED=1. Limit: 32 questions, ${DEFAULT_MAX_INPUT_BYTES / 1024} KiB JSON, ${DEFAULT_MAX_REQUESTS} attempts per session; no retries.`,
+    promptSnippet: "Ask batched structured questions with TypeSafe (external service; operator opt-in required)",
+    promptGuidelines: [
+      // The payload shape is what models get wrong on the first call; the same sample the playground edits is the cheapest way to show it.
+      // Every session pays for this line on every tool listing, so the sample stays short.
+      `Request shape, all three question kinds in one call: ${JSON.stringify(sample)}`,
+      "Use typesafe_evaluate only for requested semantic judgments, not calculations or exact lookups; send only the relevant permitted data.",
+      "Batch independent typesafe_evaluate questions over the same state; use code or explicit permission rules for actions, never confidence as authorization.",
+      "When typesafe_evaluate judges several items, give each item a named state field and ask one question per item per dimension, naming the field in the instructions; one question over many items returns an unusable blend.",
+      "Report typesafe_evaluate answers as the model's judgments with their probabilities; do not replace them with your own guesses, and say when an answer is uncertain.",
+    ],
+    parameters: evaluationSchema,
+    // Pi validates against `parameters` after this hook; the cast only names the schema's type.
+    prepareArguments: args => normalizeEvaluationRequest(args) as Static<typeof evaluationSchema>,
+    async execute(_id, params, signal, _onUpdate, ctx): Promise<AgentToolResult<Evaluation<Questions>>> {
+      if (!enabled) throw new TypeSafeIntegrationError("configuration", "TypeSafe is disabled. Ask the operator to run /typesafe enable; do not enable it by editing configuration or environment files.");
+      // The tool admits through the same rule as the library; evaluate() re-runs it idempotently.
+      const request = prepareEvaluationRequest(params);
+      try {
+        const result = await getClient().evaluate(request, signal ? { signal } : {});
+        return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
+      } catch (error) {
+        const safe = safeError(error);
+        // Authentication degradation is louder than a single failed call: it means every later judgment is skipped.
+        const rejected = safe.code === "http" && (safe.status === 401 || safe.status === 403);
+        if (rejected || safe.code === "configuration") {
+          callOut(ctx, `run:${safe.code}:${safe.status ?? ""}`, `TypeSafe is not authenticated (${safe.message}) Judgments will fail until the key is fixed.`);
+        }
+        throw safe;
+      }
+    },
+    renderCall(args) {
+      return new Text(`TypeSafe · ${Object.keys(args.questions ?? {}).length} questions · external request`, 0, 0);
+    },
+    renderResult(result, { expanded, isPartial }) {
+      if (isPartial) return new Text("TypeSafe · waiting for response", 0, 0);
+      if (!result.details?.answers) return new Text(result.content.filter(part => part.type === "text").map(part => part.text).join("\n"), 0, 0);
+      return new Text(format(result.details, expanded), 0, 0);
+    },
+  });
+
+  const actions = ["login", "logout", "setup", "status", "enable", "disable", "test", "playground"];
+  pi.registerCommand("typesafe", {
+    description: "TypeSafe login, consent, usage, sample test, and JSON playground",
+    getArgumentCompletions(prefix) {
+      const matches = actions.filter(action => action.startsWith(prefix)).map(action => ({ value: action, label: action }));
+      return matches.length ? matches : null;
+    },
+    async handler(args, ctx) {
+      const action = args.trim() || "status";
+      const report = (text: string, level: "info" | "warning" | "error" = "info") => {
+        if (ctx.hasUI) ctx.ui.notify(text, level);
+        else pi.sendMessage({ customType: "typesafe-status", content: text, display: true });
+      };
+      try {
+        if (action === "status") {
+          const spend = client?.getSpend();
+          const auth = describeAuth(authState());
+          const session = spend
+            ? `Session ${spend.session.requestsStarted}/${DEFAULT_MAX_REQUESTS} attempts, ${spend.session.requestsSucceeded} successful, ${spend.session.requestsFailed} failed, ${spend.session.inputTokens} input tokens (~$${spend.session.estimatedUsd.toFixed(4)}).`
+            : `Session 0/${DEFAULT_MAX_REQUESTS} attempts; no client yet in this session.`;
+          const today = spend
+            ? `Today ${spend.today.requestsStarted} requests (${spend.today.requestsSucceeded} ok, ${spend.today.requestsFailed} failed), ${spend.today.inputTokens} input tokens, ~$${spend.today.estimatedUsd.toFixed(4)}.`
+            : "";
+          const blocked = spend?.blocked ? ` Cap reached: ${spend.blocked.cap} ${spend.blocked.used}/${spend.blocked.limit} on ${spend.blocked.day}; no request will be submitted until the local day rolls over.` : "";
+          report(`TypeSafe: ${enabled ? "enabled" : "disabled"}. ${auth.text} ${session} ${today}${blocked} Model: ${defaultModelId(DEFAULT_BACKEND)}. Session limits reset on session start/reload; daily counters persist and caps come from client options or PI_TYPESAFE_MAX_* environment variables. ${disclosure}`, auth.level === "error" && enabled ? "warning" : "info");
+          return;
+        }
+        if (action === "logout") {
+          const removed = clearStoredApiKey();
+          clearAuthState();
+          client = undefined;
+          enabled = false;
+          report(removed ? `Removed the stored key at ${credentialsPath()}. TypeSafe is disabled.` : "No stored key to remove." + (process.env.TYPESAFE_API_KEY?.trim() ? " TYPESAFE_API_KEY is still set in the environment." : ""));
+          return;
+        }
+        if (action === "disable") {
+          enabled = false;
+          report("TypeSafe disabled for future agent calls. In-flight requests are not cancelled.");
+          return;
+        }
+        if (!actions.includes(action)) {
+          report(`Usage: /typesafe ${actions.join(" | ")}`, "warning");
+          return;
+        }
+        if (!ctx.hasUI) {
+          report("This command needs interactive Pi. For headless tool use, explicitly set PI_TYPESAFE_ENABLED=1 and TYPESAFE_API_KEY before launching Pi.", "warning");
+          return;
+        }
+        const situation = keySituation();
+        if (action === "login" || (action === "setup" && situation.kind === "missing")) {
+          if (process.env.TYPESAFE_API_KEY?.trim()) {
+            report("TYPESAFE_API_KEY is set in the environment and takes precedence over a stored key. Unset it before using /typesafe login.", "warning");
+            return;
+          }
+          const login = await loginWithPrompt(ctx);
+          if (login === undefined) { report("Login cancelled; nothing was saved."); return; }
+          client = undefined;
+          report(`Key verified (${login.models} model${login.models === 1 ? "" : "s"} available) and saved to ${login.path} with owner-only permissions. Run /typesafe enable to allow agent tool calls.`);
+          return;
+        }
+        if (action === "setup") {
+          const current = situation.kind === "environment" || situation.kind === "stored" ? `configured via ${keySourceLabel(situation)}`
+            : situation.kind === "unusable" ? `unusable — ${situation.reason}`
+            : "missing";
+          report(`Key ${current}. Run /typesafe test for one sample request or /typesafe enable to allow agent tool calls.`);
+          return;
+        }
+        if (action === "enable") {
+          if (situation.kind === "missing") { report("Run /typesafe login first: no API key is configured.", "warning"); return; }
+          if (situation.kind === "unusable") { report(`The stored key cannot be used. ${situation.reason}`, "warning"); return; }
+          if (await ctx.ui.confirm("Enable TypeSafe for this session?", disclosure)) {
+            enabled = true;
+            report(`TypeSafe enabled. Up to ${DEFAULT_MAX_REQUESTS} attempts in this session; /typesafe disable stops future agent calls.`);
+          }
+          return;
+        }
+        let request = sample;
+        if (action === "playground") {
+          const text = await ctx.ui.editor("TypeSafe request JSON · edit state and questions", JSON.stringify(sample, null, 2));
+          if (text === undefined) return;
+          try { request = JSON.parse(text); } catch { report("Invalid JSON. Keep quoted strings on one line; nothing was sent.", "error"); return; }
+        }
+        const validated = prepareEvaluationRequest(request);
+        if (!await ctx.ui.confirm("Send this TypeSafe request?", disclosure)) return;
+        const result = await getClient().evaluate(validated);
+        // Playground results stay out of LLM context; the agent tool returns its own results normally.
+        pi.appendEntry("typesafe-result", result);
+      } catch (error) {
+        report(safeError(error).message, "error");
+      }
+    },
+  });
+}

package/port/oracle/src/index.ts

@@ -0,0 +1,31 @@
+export { createTypeSafe, backendHost, resolveBackend, DEFAULT_MAX_REQUESTS, DECISIONS_BACKENDS, DEFAULT_BACKEND } from "./client.js";
+export type {
+  TypeSafe, TypeSafeOptions, EvaluationOptions, Evaluation, UsageSnapshot, SpendReport,
+  TypeSafeBackend, BackendConfig, BackendEndpoint, BackendSpec, ResolvedBackend,
+} from "./client.js";
+export { ask, DEFAULT_ASK_TIMEOUT_MS } from "./ask.js";
+export type { AskAnswer, AskOptions, Judge } from "./ask.js";
+export { fanOut, DEFAULT_CONCURRENCY, evaluateMany, evaluateAll, chunkEvaluationRequest } from "./batch.js";
+export type { BatchEvaluation, BatchOptions, FanOutOptions, Settled } from "./batch.js";
+export { authState, authStatePath, clearAuthState, describeAuth, recordAuthFailure, recordAuthVerified } from "./auth.js";
+export type { AuthFailure, AuthReport, AuthState } from "./auth.js";
+export {
+  clearStoredApiKey, credentialsPath, keySituation, keySourceLabel, normalizeApiKey, piTypesafeDir, resolveApiKey, storeApiKey,
+} from "./credentials.js";
+export type { KeySituation, KeySource } from "./credentials.js";
+export {
+  capsFromEnvironment, DEFAULT_USD_PER_MTOK, emptyTotals, estimateUsd, localDay, mergeCaps, openUsageLedger, usagePath,
+} from "./usage.js";
+export type { BlockedCap, SpendCaps, UsageLedger, UsageLedgerOptions, UsageReport, UsageTotals } from "./usage.js";
+export { TypeSafeIntegrationError } from "./errors.js";
+export type { IntegrationErrorCode } from "./errors.js";
+export {
+  DEFAULT_MAX_INPUT_BYTES, DEFAULT_MAX_QUESTIONS, evaluationSchema, normalizeEvaluationRequest, parseEvaluationRequest, prepareEvaluationRequest,
+} from "./schema.js";
+export type { PrepareEvaluationOptions } from "./schema.js";
+export { choice, noul, score } from "@typesafe-ai/sdk";
+export type {
+  Questions, Question, SystemOneRequest, SystemOneResult, EntryType, JsonValue,
+  ChoiceQuestion, ChoiceResponse, NoulQuestion, NoulResponse,
+  ScoreQuestion, ScoreResponse, Usage,
+} from "@typesafe-ai/sdk";

package/port/oracle/src/key-prompt.ts

@@ -0,0 +1,51 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Container, CURSOR_MARKER, type Focusable, Input, Key, matchesKey, Text, truncateToWidth } from "@earendil-works/pi-tui";
+
+/** Single-line input that renders bullets instead of the typed value. */
+class SecretInput extends Input {
+  override render(width: number): string[] {
+    const length = [...this.getValue()].length;
+    const bullets = "•".repeat(Math.min(length, Math.max(0, width - 2)));
+    const cursor = this.focused ? `${CURSOR_MARKER}\x1b[7m \x1b[27m` : "";
+    return [truncateToWidth(bullets + cursor, width, "")];
+  }
+}
+
+class KeyPrompt extends Container implements Focusable {
+  private readonly input = new SecretInput();
+  private isFocused = false;
+
+  constructor(theme: { fg(color: string, text: string): string; bold(text: string): string }, done: (value: string | undefined) => void) {
+    super();
+    this.addChild(new Text(theme.fg("accent", theme.bold("TypeSafe API key")), 1, 0));
+    this.addChild(new Text(theme.fg("muted", "Paste the key from console.typesafe.ai › API Keys. Input is hidden. Enter saves, Esc cancels."), 1, 0));
+    this.addChild(this.input);
+    this.input.onSubmit = value => done(value);
+    this.input.onEscape = () => done(undefined);
+  }
+
+  get focused(): boolean {
+    return this.isFocused;
+  }
+
+  set focused(value: boolean) {
+    this.isFocused = value;
+    this.input.focused = value;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.escape)) {
+      this.input.onEscape?.();
+      return;
+    }
+    this.input.handleInput(data);
+  }
+}
+
+/** Hidden input in the TUI; falls back to Pi's plain input dialog where custom components are unavailable. */
+export async function promptForApiKey(ctx: ExtensionCommandContext): Promise<string | undefined> {
+  if (typeof ctx.ui.custom === "function") {
+    return ctx.ui.custom<string | undefined>((_tui, theme, _keybindings, done) => new KeyPrompt(theme, done));
+  }
+  return ctx.ui.input("TypeSafe API key (visible while typing)", "Paste the key, then press Enter");
+}

package/port/oracle/src/login.ts

@@ -0,0 +1,60 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_BACKEND, resolveBackend, usesTypesafeKey } from "./backends.js";
+import type { BackendSpec } from "./backends.js";
+import { createTypeSafe } from "./client.js";
+import { keySituation, normalizeApiKey, storeApiKey } from "./credentials.js";
+import type { KeySource } from "./credentials.js";
+import { TypeSafeIntegrationError } from "./errors.js";
+import { promptForApiKey } from "./key-prompt.js";
+
+export interface LoginResult {
+  /** Where the verified key was saved. */
+  path: string;
+  /** Number of models the key can access; proves the key was accepted by the API. */
+  models: number;
+}
+
+/**
+ * Prompt for a TypeSafe key (hidden input), verify it against api.typesafe.ai with a model listing, and store it for
+ * every pi-typesafe consumer. Resolves to undefined when the user cancels. Rejects with TypeSafeIntegrationError for an
+ * invalid or unverifiable key. Refuses when TYPESAFE_API_KEY is set, because the environment would shadow the stored
+ * key. Other backends have no login: their key is an environment variable only.
+ */
+export async function loginWithPrompt(ctx: ExtensionCommandContext): Promise<LoginResult | undefined> {
+  if (process.env.TYPESAFE_API_KEY?.trim()) {
+    throw new TypeSafeIntegrationError("configuration", "TYPESAFE_API_KEY is set in the environment and takes precedence over a stored key. Unset it before logging in interactively.");
+  }
+  if (!ctx.hasUI) {
+    throw new TypeSafeIntegrationError("configuration", "Logging in needs an interactive session. Set TYPESAFE_API_KEY in the environment instead.");
+  }
+  const entered = await promptForApiKey(ctx);
+  if (entered === undefined) return undefined;
+  const key = normalizeApiKey(entered);
+  // Verify before saving so a bad paste fails here, not on first use.
+  const models = await createTypeSafe({ apiKey: key }).listModels();
+  return { path: storeApiKey(key), models: models.length };
+}
+
+export type EnsureApiKeyResult =
+  | { source: KeySource; login?: undefined }
+  | { source: "stored"; login: LoginResult };
+
+/**
+ * Use the configured key for the backend if there is one; otherwise run the login prompt. `undefined` means the user
+ * cancelled. A store that must not be read throws `configuration` with the reason instead of prompting, so a
+ * permissions problem stays visible; the result shape is frozen for existing callers. A backend without a login store
+ * (every backend except TypeSafe) throws `configuration` naming its environment variable instead of prompting, because
+ * the prompt would verify the key against the wrong service and store it where the TypeSafe key lives.
+ */
+export async function ensureApiKey(ctx: ExtensionCommandContext, options: { backend?: BackendSpec } = {}): Promise<EnsureApiKeyResult | undefined> {
+  const backend = options.backend ?? DEFAULT_BACKEND;
+  const situation = keySituation(backend);
+  if (situation.kind === "environment" || situation.kind === "stored") return { source: situation.kind };
+  if (situation.kind === "unusable") throw new TypeSafeIntegrationError("configuration", situation.reason);
+  const config = resolveBackend(backend);
+  if (!usesTypesafeKey(config)) {
+    throw new TypeSafeIntegrationError("configuration", `No ${config.label} key. Set ${config.keyEnv} in the environment; /typesafe login stores a TypeSafe key only.`);
+  }
+  const login = await loginWithPrompt(ctx);
+  return login ? { source: "stored", login } : undefined;
+}