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

package/port/oracle/src/schema.ts

@@ -0,0 +1,158 @@
+import type { SystemOneRequest } from "@typesafe-ai/sdk";
+import { Type } from "typebox";
+import { Check, Errors } from "typebox/value";
+import { TypeSafeIntegrationError } from "./errors.js";
+
+/** Default UTF-8 JSON byte budget for one evaluation request; the tool and the client share it. */
+export const DEFAULT_MAX_INPUT_BYTES = 65_536;
+
+/** Questions one request may ask. More than this needs `chunkEvaluationRequest`, which splits and fans out. */
+export const DEFAULT_MAX_QUESTIONS = 32;
+
+// The API accepts structured descriptions, not only strings. The schema is the only shape guidance the model gets
+// before its first call, so every field the agent authors says what it means.
+const entry = (description?: string) => Type.Union([
+  Type.String(),
+  Type.Null(),
+  Type.Array(Type.Unknown()),
+  Type.Record(Type.String(), Type.Unknown()),
+], description === undefined ? {} : { description });
+const instructions = Type.Optional(entry("One judgment about the whole state, phrased as a question or a statement."));
+const question = Type.Union([
+  Type.Object({
+    type: Type.Literal("noul", { description: "Yes or no: the probability the instructions hold." }),
+    instructions,
+    criteria: Type.Optional(Type.Union([
+      Type.Null(),
+      Type.Object({ true: Type.Optional(entry()), false: Type.Optional(entry()) }, { additionalProperties: false }),
+    ], { description: "Optional: what counts as yes and what counts as no, { true, false }." })),
+  }, { additionalProperties: false }),
+  Type.Object({
+    type: Type.Literal("choice", { description: "Pick one criteria label." }),
+    instructions,
+    criteria: Type.Record(Type.String({ minLength: 1, maxLength: 200 }), entry(), {
+      minProperties: 1,
+      maxProperties: 64,
+      description: "The options as a map from label to when it applies: { billing: \"Charges and payments\", other: null }. 1–64 entries.",
+    }),
+  }, { additionalProperties: false }),
+  Type.Object({
+    type: Type.Literal("score", { description: "Rate against the ordered criteria levels." }),
+    instructions,
+    criteria: Type.Array(entry(), { minItems: 2, maxItems: 32, description: "Ordered rubric levels, lowest first: [\"neutral\", \"angry\"]. 2–32 levels." }),
+  }, { additionalProperties: false }),
+]);
+
+/** The JSON schema used by both the Pi tool and the programmatic interface. */
+export const evaluationSchema = Type.Object({
+  state: entry("What to judge: text, or an object whose fields the questions name."),
+  questions: Type.Record(Type.String({ minLength: 1, maxLength: 100 }), question, {
+    minProperties: 1,
+    maxProperties: DEFAULT_MAX_QUESTIONS,
+    description: "Questions keyed by a short id, as an object map, not an array: { \"urgent\": { type: \"noul\", instructions: ... } }.",
+  }),
+  model: Type.Optional(Type.String({ minLength: 1, maxLength: 100, description: "Jev model id, e.g. jev-latest. Omit for the default." })),
+}, { additionalProperties: false });
+
+const usage = `Expected { state, questions: { <id>: { type: "choice", instructions, criteria: { label: description|null } } | { type: "score", instructions, criteria: [level0, level1, ...] } | { type: "noul", instructions } } }; 1–${DEFAULT_MAX_QUESTIONS} questions, Choice 1–64 options, Score 2–32 levels.`;
+
+/** Paths and messages only; never the submitted values. */
+function describeSchemaErrors(value: unknown): string {
+  const details: string[] = [];
+  for (const error of Errors(evaluationSchema, value)) {
+    const path = error.instancePath.replace(/^\//, "").replace(/\//g, ".") || "request";
+    details.push(`${path.slice(0, 120)}: ${error.message}`);
+    if (details.length === 3) break;
+  }
+  return details.join("; ");
+}
+
+/** Validate without including submitted content in validation errors. Prefer prepareEvaluationRequest(), which also accepts near-misses and enforces the byte budget. */
+export function parseEvaluationRequest(value: unknown): SystemOneRequest {
+  if (value !== null && typeof value === "object" && !Array.isArray(value) && !isJsonSafe(value)) {
+    throw new TypeSafeIntegrationError("validation", `Invalid evaluation request: state and questions must be plain JSON. ${usage}`);
+  }
+  if (!Check(evaluationSchema, value)) {
+    throw new TypeSafeIntegrationError("validation", `Invalid evaluation request at ${describeSchemaErrors(value)}. ${usage}`);
+  }
+  return value as SystemOneRequest;
+}
+
+function isJsonSafe(value: unknown): boolean {
+  try {
+    // Walk before schema validation to reject cycles and non-JSON values.
+    // Object descriptors avoid executing getters while checking user data.
+    const ancestors = new Set<object>();
+    const walk = (item: unknown, depth: number): void => {
+      if (depth > 64) throw new Error();
+      if (item === null || typeof item === "string" || typeof item === "boolean") return;
+      if (typeof item === "number" && Number.isFinite(item)) return;
+      if (typeof item !== "object" || ancestors.has(item)) throw new Error();
+      if (!Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null) throw new Error();
+      ancestors.add(item);
+      if (Object.getOwnPropertySymbols(item).length) throw new Error();
+      for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(item))) {
+        if (Array.isArray(item) && key === "length") continue;
+        if (!descriptor.enumerable || descriptor.get || descriptor.set) throw new Error();
+        // SDK helpers include optional object fields whose value is undefined.
+        // JSON serialization omits those fields; array elements must remain JSON.
+        if (descriptor.value === undefined && !Array.isArray(item)) continue;
+        walk(descriptor.value, depth + 1);
+      }
+      ancestors.delete(item);
+    };
+    walk(value, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Accept common near-misses from language models without loosening the schema itself. Prefer prepareEvaluationRequest(), which applies this before validating. */
+export function normalizeEvaluationRequest(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const request = value as Record<string, unknown>;
+  const questions = request.questions;
+  if (!questions || typeof questions !== "object" || Array.isArray(questions)) return value;
+  const normalized: Record<string, unknown> = {};
+  for (const [id, question] of Object.entries(questions as Record<string, unknown>)) {
+    if (!question || typeof question !== "object" || Array.isArray(question)) { normalized[id] = question; continue; }
+    const { options, levels, choices, ...rest } = question as Record<string, unknown>;
+    const item: Record<string, unknown> = { ...rest };
+    if (item.criteria === undefined) {
+      const alias = options ?? levels ?? choices;
+      if (alias !== undefined) item.criteria = alias;
+    }
+    if (item.type === "choice" && Array.isArray(item.criteria) && item.criteria.every(label => typeof label === "string" && label)) {
+      item.criteria = Object.fromEntries((item.criteria as string[]).map(label => [label, null]));
+    }
+    if (item.type === "noul" && typeof item.criteria === "string") {
+      item.criteria = { true: item.criteria };
+    }
+    normalized[id] = item;
+  }
+  return { ...request, questions: normalized };
+}
+
+export interface PrepareEvaluationOptions {
+  /** UTF-8 JSON bytes of the serialized request. Default: DEFAULT_MAX_INPUT_BYTES. */
+  maxInputBytes?: number;
+}
+
+/** One byte rule for every limit check: measure the serialized request and name the configured limit. */
+export function assertWithinByteLimit(text: string, maxInputBytes: number): void {
+  if (Buffer.byteLength(text, "utf8") > maxInputBytes) {
+    throw new TypeSafeIntegrationError("validation", `Evaluation exceeds the ${maxInputBytes}-byte input limit.`);
+  }
+}
+
+/**
+ * The one admission rule: normalize known near-miss aliases, validate the schema and JSON-safety, then enforce the byte
+ * budget — always in that order. The Pi tool, the playground, and client.evaluate() all pass through here, so what one
+ * accepts the others accept.
+ */
+export function prepareEvaluationRequest(value: unknown, options: PrepareEvaluationOptions = {}): SystemOneRequest {
+  const validated = parseEvaluationRequest(normalizeEvaluationRequest(value));
+  assertWithinByteLimit(JSON.stringify(validated), options.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES);
+  return validated;
+}

package/port/oracle/src/ui.ts

@@ -0,0 +1,4 @@
+// Interactive helpers that need Pi's TUI. Kept out of the root entry so the library stays usable without Pi.
+export { promptForApiKey } from "./key-prompt.js";
+export { loginWithPrompt, ensureApiKey } from "./login.js";
+export type { LoginResult, EnsureApiKeyResult } from "./login.js";

package/port/oracle/src/usage.ts

@@ -0,0 +1,258 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { piTypesafeDir } from "./credentials.js";
+
+/**
+ * TypeSafe bills input tokens only; output is free. The default mirrors the $42-per-billion-input-token rate the README
+ * quotes, so a spend cap means something before anyone configures a price. Override it when the rate changes.
+ */
+export const DEFAULT_USD_PER_MTOK = 0.042;
+/** Ledger days kept on disk; older entries are dropped on the next write. */
+const KEEP_DAYS = 31;
+const USAGE_VERSION = 1;
+
+/** Counters for one window (a session, or one local day). */
+export interface UsageTotals {
+  readonly requestsStarted: number;
+  readonly requestsSucceeded: number;
+  readonly requestsFailed: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+}
+
+/** One day of persisted totals plus the cost estimate for that day. */
+export interface UsageReport extends UsageTotals {
+  readonly day: string;
+  readonly estimatedUsd: number;
+}
+
+/**
+ * Client-side spend caps. Every field is optional; an absent field is unlimited. Session caps come from the client
+ * options only; day caps also read the `PI_TYPESAFE_MAX_*` environment variables so a headless run can bound itself
+ * without editing code. A cap that is reached raises a `budget` error before the next request leaves the process.
+ */
+export interface SpendCaps {
+  readonly maxRequests?: number;
+  readonly maxRequestsPerDay?: number;
+  readonly maxInputTokensPerDay?: number;
+  readonly maxUsdPerDay?: number;
+}
+
+/** The cap that stops the next request, with what it allows and what has been used today. */
+export interface BlockedCap {
+  readonly cap: "requestsPerDay" | "inputTokensPerDay" | "usdPerDay";
+  readonly limit: number;
+  readonly used: number;
+  readonly day: string;
+}
+
+interface LedgerFile {
+  readonly version: number;
+  readonly days: Record<string, UsageTotals>;
+}
+
+export function localDay(now: Date = new Date()): string {
+  const pad = (value: number) => String(value).padStart(2, "0");
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+
+/** The stored ledger. Alongside the key store so one directory holds every pi-typesafe file. */
+export function usagePath(): string {
+  return join(piTypesafeDir(), "usage.json");
+}
+
+/** Input-token cost, rounded to a micro-dollar so the number stays readable. */
+export function estimateUsd(inputTokens: number, usdPerMTok: number): number {
+  return Math.round((inputTokens * usdPerMTok) / 1e6 * 1e6) / 1e6;
+}
+
+export function emptyTotals(): UsageTotals {
+  return { requestsStarted: 0, requestsSucceeded: 0, requestsFailed: 0, inputTokens: 0, outputTokens: 0 };
+}
+
+function count(value: unknown): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+function totalsOf(value: unknown): UsageTotals {
+  const raw = (value ?? {}) as Record<string, unknown>;
+  return {
+    requestsStarted: count(raw.requestsStarted),
+    requestsSucceeded: count(raw.requestsSucceeded),
+    requestsFailed: count(raw.requestsFailed),
+    inputTokens: count(raw.inputTokens),
+    outputTokens: count(raw.outputTokens),
+  };
+}
+
+function readDays(path: string): Record<string, UsageTotals> {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    const days = parsed && typeof parsed === "object" ? (parsed as { days?: unknown }).days : undefined;
+    if (!days || typeof days !== "object" || Array.isArray(days)) return {};
+    const result: Record<string, UsageTotals> = {};
+    for (const [day, totals] of Object.entries(days as Record<string, unknown>)) {
+      if (/^\d{4}-\d{2}-\d{2}$/.test(day)) result[day] = totalsOf(totals);
+    }
+    return result;
+  } catch {
+    // A missing, unreadable, or corrupt ledger restarts today's count; it never blocks a request.
+    return {};
+  }
+}
+
+function keepRecent(days: Record<string, UsageTotals>, today: string): Record<string, UsageTotals> {
+  const names = Object.keys(days).sort();
+  const result: Record<string, UsageTotals> = {};
+  for (const name of names.slice(-KEEP_DAYS)) result[name] = days[name] as UsageTotals;
+  result[today] = days[today] ?? emptyTotals();
+  return result;
+}
+
+/** Owner-only, atomic, and best-effort: a ledger this process cannot write never fails a request. */
+function writeDays(path: string, days: Record<string, UsageTotals>): void {
+  const file: LedgerFile = { version: USAGE_VERSION, days };
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(temporary, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600, flag: "w" });
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, path);
+  } catch {
+    try { rmSync(temporary, { force: true }); } catch { /* best-effort cleanup only */ }
+  }
+}
+
+/** The caps a headless run may set without code: `PI_TYPESAFE_MAX_USD_PER_DAY` and its siblings. */
+export function capsFromEnvironment(env: NodeJS.ProcessEnv = process.env): SpendCaps {
+  const number = (name: string): number | undefined => {
+    const raw = env[name]?.trim();
+    if (!raw) return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 ? value : undefined;
+  };
+  const maxRequestsPerDay = number("PI_TYPESAFE_MAX_REQUESTS_PER_DAY");
+  const maxInputTokensPerDay = number("PI_TYPESAFE_MAX_INPUT_TOKENS_PER_DAY");
+  const maxUsdPerDay = number("PI_TYPESAFE_MAX_USD_PER_DAY");
+  return {
+    ...(maxRequestsPerDay === undefined ? {} : { maxRequestsPerDay: Math.floor(maxRequestsPerDay) }),
+    ...(maxInputTokensPerDay === undefined ? {} : { maxInputTokensPerDay: Math.floor(maxInputTokensPerDay) }),
+    ...(maxUsdPerDay === undefined ? {} : { maxUsdPerDay }),
+  };
+}
+
+/** Environment first for day caps, then the explicit option; a cap is never raised by the environment. */
+export function mergeCaps(explicit: SpendCaps, environment: SpendCaps): SpendCaps {
+  const lowest = (a: number | undefined, b: number | undefined) =>
+    a === undefined ? b : b === undefined ? a : Math.min(a, b);
+  const maxRequestsPerDay = lowest(explicit.maxRequestsPerDay, environment.maxRequestsPerDay);
+  const maxInputTokensPerDay = lowest(explicit.maxInputTokensPerDay, environment.maxInputTokensPerDay);
+  const maxUsdPerDay = lowest(explicit.maxUsdPerDay, environment.maxUsdPerDay);
+  return {
+    ...(explicit.maxRequests === undefined ? {} : { maxRequests: explicit.maxRequests }),
+    ...(maxRequestsPerDay === undefined ? {} : { maxRequestsPerDay }),
+    ...(maxInputTokensPerDay === undefined ? {} : { maxInputTokensPerDay }),
+    ...(maxUsdPerDay === undefined ? {} : { maxUsdPerDay }),
+  };
+}
+
+export interface UsageLedgerOptions {
+  /** Defaults to usagePath(); tests point it at a temporary file. */
+  path?: string;
+  /** Clock for the local day and for rollover; injectable for tests. */
+  now?: () => Date;
+  usdPerMTok?: number;
+}
+
+/**
+ * One day of persisted request, token, and cost totals, plus the caps that stop the next request. The in-memory copy is
+ * authoritative for this process; the file is the cross-process, across-restart record. Reads are defensive, writes are
+ * atomic and best-effort, and a day rolls over on the local date, so a long eval cannot accumulate forever unnoticed.
+ */
+export interface UsageLedger {
+  readonly path: string;
+  readonly usdPerMTok: number;
+  /** Today's totals, after any rollover. */
+  today(): UsageReport;
+  /** Count the attempt before it is submitted; a request that never returns still counts. */
+  recordStart(): void;
+  recordSuccess(inputTokens: number, outputTokens: number): void;
+  recordFailure(): void;
+  /** The reached day cap that blocks the next request, or undefined. The caller owns the caps. */
+  blocked(caps: SpendCaps): BlockedCap | undefined;
+  /** One line for status output: today's requests, tokens, and cost, with the caps that apply. */
+  describe(caps?: SpendCaps): string;
+}
+
+export function openUsageLedger(options: UsageLedgerOptions = {}): UsageLedger {
+  const path = options.path ?? usagePath();
+  const now = options.now ?? (() => new Date());
+  const usdPerMTok = options.usdPerMTok && options.usdPerMTok > 0 ? options.usdPerMTok : DEFAULT_USD_PER_MTOK;
+  let day = localDay(now());
+  let days = keepRecent(readDays(path), day);
+  let totals = days[day] as UsageTotals;
+
+  const report = (value: UsageTotals, name: string): UsageReport => ({
+    ...value, day: name, estimatedUsd: estimateUsd(value.inputTokens, usdPerMTok),
+  });
+
+  const save = () => {
+    days = keepRecent({ ...days, [day]: totals }, day);
+    writeDays(path, days);
+  };
+
+  const roll = () => {
+    const current = localDay(now());
+    if (current === day) return;
+    day = current;
+    totals = days[day] ?? emptyTotals();
+    days = keepRecent(days, day);
+  };
+
+  const add = (delta: Partial<UsageTotals>) => {
+    roll();
+    totals = {
+      requestsStarted: totals.requestsStarted + (delta.requestsStarted ?? 0),
+      requestsSucceeded: totals.requestsSucceeded + (delta.requestsSucceeded ?? 0),
+      requestsFailed: totals.requestsFailed + (delta.requestsFailed ?? 0),
+      inputTokens: totals.inputTokens + (delta.inputTokens ?? 0),
+      outputTokens: totals.outputTokens + (delta.outputTokens ?? 0),
+    };
+    save();
+  };
+
+  return {
+    path,
+    usdPerMTok,
+    today: () => { roll(); return report(totals, day); },
+    recordStart: () => add({ requestsStarted: 1 }),
+    recordSuccess: (inputTokens, outputTokens) => add({
+      requestsSucceeded: 1,
+      inputTokens: Number.isSafeInteger(inputTokens) && inputTokens > 0 ? inputTokens : 0,
+      outputTokens: Number.isSafeInteger(outputTokens) && outputTokens > 0 ? outputTokens : 0,
+    }),
+    recordFailure: () => add({ requestsFailed: 1 }),
+    blocked: (caps: SpendCaps) => {
+      roll();
+      const checks: Array<[BlockedCap["cap"], number | undefined, number]> = [
+        ["requestsPerDay", caps.maxRequestsPerDay, totals.requestsStarted],
+        ["inputTokensPerDay", caps.maxInputTokensPerDay, totals.inputTokens],
+        ["usdPerDay", caps.maxUsdPerDay, estimateUsd(totals.inputTokens, usdPerMTok)],
+      ];
+      for (const [cap, limit, used] of checks) {
+        if (limit !== undefined && used >= limit) return { cap, limit, used, day };
+      }
+      return undefined;
+    },
+    describe: (caps: SpendCaps = {}) => {
+      roll();
+      const current = report(totals, day);
+      const limits = [
+        caps.maxRequestsPerDay === undefined ? undefined : `${current.requestsStarted}/${caps.maxRequestsPerDay} requests`,
+        caps.maxInputTokensPerDay === undefined ? undefined : `${current.inputTokens}/${caps.maxInputTokensPerDay} input tokens`,
+        caps.maxUsdPerDay === undefined ? undefined : `$${current.estimatedUsd.toFixed(4)}/$${caps.maxUsdPerDay.toFixed(2)}`,
+      ].filter((part): part is string => part !== undefined);
+      return `${current.requestsStarted} requests today (${current.requestsSucceeded} ok, ${current.requestsFailed} failed), ${current.inputTokens} input / ${current.outputTokens} output tokens, ~$${current.estimatedUsd.toFixed(4)}${limits.length ? `; caps ${limits.join(", ")}` : "; no daily cap"}`;
+    },
+  };
+}

package/port/oracle/tests/ask.test.ts

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { ask, DEFAULT_ASK_TIMEOUT_MS } from "../src/ask.js";
+import type { Judge } from "../src/ask.js";
+import { TypeSafeIntegrationError } from "../src/errors.js";
+import { noul } from "../src/index.js";
+import type { Evaluation } from "../src/client.js";
+import type { Questions, SystemOneRequest, SystemOneResult } from "@typesafe-ai/sdk";
+
+const request: SystemOneRequest<Questions> = { state: "synthetic", questions: { yes: noul("Is this synthetic?") } };
+const result: SystemOneResult<Questions> = {
+  model: "jev-test",
+  answers: { yes: { type: "noul", noul: 0.9 } },
+  usage: { input_tokens: 12, output_tokens: 0 },
+};
+
+function judgeReturning(value: SystemOneResult<Questions>): Judge {
+  return { evaluate: async <Q extends Questions>(): Promise<Evaluation<Q>> => ({ ...value, elapsedMs: 7 } as Evaluation<Q>) };
+}
+
+test("a successful ask returns the typed answers, model, usage, and duration", async () => {
+  const answer = await ask(judgeReturning(result), request);
+  assert.equal(answer.ok, true);
+  assert.ok(answer.ok);
+  const yes = answer.answers.yes;
+  assert.equal(yes?.type === "noul" ? yes.noul : undefined, 0.9);
+  assert.equal(answer.model, "jev-test");
+  assert.equal(answer.usage.input_tokens, 12);
+  assert.equal(answer.elapsedMs, 7);
+});
+
+test("a typed failure comes back as data, with pi-typesafe's own code and message", async () => {
+  const budget = await ask({ evaluate: async () => { throw new TypeSafeIntegrationError("budget", "TypeSafe request limit reached (1 attempts per client instance)."); } }, request);
+  assert.deepEqual(budget, { ok: false, error: "TypeSafe request limit reached (1 attempts per client instance).", errorCode: "budget" });
+  const http = await ask({ evaluate: async () => { throw new TypeSafeIntegrationError("http", "TypeSafe returned HTTP 401. Check TYPESAFE_API_KEY. No automatic retry was made.", 401); } }, request);
+  assert.equal(http.ok, false);
+  assert.equal(http.ok === false && http.errorCode, "http");
+});
+
+test("an unknown failure is replaced by a fixed message so nothing from the transport escapes", async () => {
+  const answer = await ask({ evaluate: async () => { throw new Error("upstream body with a key: sk-secret"); } }, request);
+  assert.deepEqual(answer, { ok: false, error: "TypeSafe request failed." });
+  assert.equal(JSON.stringify(answer).includes("sk-secret"), false);
+});
+
+test("the ask deadline and the caller's signal both cancel the request", async () => {
+  const slow: Judge = {
+    evaluate: async <Q extends Questions>(_request: SystemOneRequest<Q>, options?: { signal?: AbortSignal }) => {
+      await new Promise((_resolve, reject) => {
+        options?.signal?.addEventListener("abort", () => reject(new TypeSafeIntegrationError("aborted", "TypeSafe request cancelled before submission.")), { once: true });
+      });
+      throw new Error("unreachable");
+    },
+  };
+  const timedOut = await ask(slow, request, { timeoutMs: 5 });
+  assert.deepEqual(timedOut, { ok: false, error: "TypeSafe request cancelled before submission.", errorCode: "aborted" });
+
+  const controller = new AbortController();
+  const aborted = ask(slow, request, { signal: controller.signal, timeoutMs: 5_000 });
+  controller.abort();
+  assert.equal((await aborted).ok, false);
+  assert.equal(DEFAULT_ASK_TIMEOUT_MS, 15_000);
+});

package/port/oracle/tests/auth.test.ts

@@ -0,0 +1,141 @@
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, before, test } from "node:test";
+import { authState, authStatePath, clearAuthState, describeAuth, recordAuthFailure, recordAuthVerified } from "../src/auth.js";
+import { credentialsPath, storeApiKey } from "../src/credentials.js";
+import { TypeSafeIntegrationError } from "../src/errors.js";
+
+const workspace = mkdtempSync(join(tmpdir(), "pi-typesafe-auth-"));
+const savedAgentDir = process.env.PI_CODING_AGENT_DIR;
+const savedKey = process.env.TYPESAFE_API_KEY;
+before(() => {
+  process.env.PI_CODING_AGENT_DIR = workspace;
+  delete process.env.TYPESAFE_API_KEY;
+});
+after(() => {
+  if (savedAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR; else process.env.PI_CODING_AGENT_DIR = savedAgentDir;
+  if (savedKey === undefined) delete process.env.TYPESAFE_API_KEY; else process.env.TYPESAFE_API_KEY = savedKey;
+});
+
+test("no key at all is an error the consumer cannot mistake for a working setup", () => {
+  const state = authState();
+  assert.equal(state.kind, "missing");
+  assert.equal(state.keyName, "no key");
+  assert.equal(state.usable, false);
+  assert.equal(state.verified, false);
+  const report = describeAuth(state);
+  assert.equal(report.level, "error");
+  assert.ok(report.text.includes("every Jev judgment is skipped"));
+});
+
+test("another backend reports its own key and never the TypeSafe login hint", () => {
+  const savedOpenRouter = process.env.OPENROUTER_API_KEY;
+  try {
+    delete process.env.OPENROUTER_API_KEY;
+    process.env.TYPESAFE_API_KEY = "env-key-0123456789abcdef";
+    assert.equal(authState().backend, "typesafe");
+    const missing = authState({ backend: "openrouter" });
+    assert.equal(missing.backend, "openrouter");
+    assert.equal(missing.kind, "missing");
+    assert.equal(missing.usable, false);
+    const report = describeAuth(missing);
+    assert.equal(report.level, "error");
+    assert.ok(report.text.startsWith("OpenRouter key: missing"));
+    assert.ok(report.text.includes("OPENROUTER_API_KEY is set"));
+    assert.ok(!report.text.includes("/typesafe login"));
+
+    process.env.OPENROUTER_API_KEY = "sk-or-0123456789abcdef";
+    const present = authState({ backend: "openrouter" });
+    assert.equal(present.kind, "environment");
+    assert.equal(present.keyName, "OPENROUTER_API_KEY");
+    assert.equal(present.usable, true);
+    assert.ok(describeAuth(present).text.startsWith("OpenRouter key: OPENROUTER_API_KEY"));
+  } finally {
+    delete process.env.TYPESAFE_API_KEY;
+    if (savedOpenRouter === undefined) delete process.env.OPENROUTER_API_KEY; else process.env.OPENROUTER_API_KEY = savedOpenRouter;
+  }
+});
+
+test("an environment key is usable but unverified until something proves it", () => {
+  process.env.TYPESAFE_API_KEY = "env-key-0123456789abcdef";
+  try {
+    const before = describeAuth(authState());
+    assert.equal(before.level, "warning");
+    assert.ok(before.text.includes("TYPESAFE_API_KEY"));
+    assert.ok(before.text.includes("not verified yet"));
+    recordAuthVerified(new Date("2026-01-01T00:00:00.000Z"));
+    const state = authState();
+    assert.equal(state.usable, true);
+    assert.equal(state.verified, true);
+    assert.equal(state.verifiedAt, "2026-01-01T00:00:00.000Z");
+    assert.equal(describeAuth(state).level, "ok");
+    assert.equal(statSync(authStatePath()).mode & 0o777, 0o600);
+  } finally {
+    delete process.env.TYPESAFE_API_KEY;
+  }
+});
+
+test("a rejected key degrades loudly and a later success clears it", () => {
+  storeApiKey("stored-key-0123456789abcdef");
+  recordAuthVerified(new Date("2026-01-02T00:00:00.000Z"));
+  recordAuthFailure(new TypeSafeIntegrationError("http", "TypeSafe returned HTTP 401. Check TYPESAFE_API_KEY. No automatic retry was made.", 401), new Date("2026-01-02T01:00:00.000Z"));
+  const degraded = authState();
+  assert.equal(degraded.kind, "stored");
+  assert.equal(degraded.usable, false);
+  assert.equal(degraded.verified, false);
+  assert.deepEqual(degraded.lastFailure, {
+    code: "http",
+    status: 401,
+    message: "TypeSafe returned HTTP 401. Check TYPESAFE_API_KEY. No automatic retry was made.",
+    at: "2026-01-02T01:00:00.000Z",
+  });
+  const report = describeAuth(degraded);
+  assert.equal(report.level, "error");
+  assert.ok(report.text.includes("was rejected"));
+
+  // A successful request proves the key again and drops the failure.
+  recordAuthVerified(new Date("2026-01-02T02:00:00.000Z"));
+  const recovered = authState();
+  assert.equal(recovered.usable, true);
+  assert.equal(recovered.verified, true);
+  assert.equal(recovered.lastFailure, undefined);
+});
+
+test("a non-authentication failure degrades the signal without pretending the key is gone", () => {
+  storeApiKey("stored-key-0123456789abcdef");
+  recordAuthVerified(new Date("2026-01-03T00:00:00.000Z"));
+  recordAuthFailure(new TypeSafeIntegrationError("timeout", "TypeSafe request timed out; it was not retried and may still be billed."), new Date("2026-01-03T00:05:00.000Z"));
+  const state = authState();
+  assert.equal(state.usable, true);
+  assert.equal(state.verified, true);
+  assert.equal(describeAuth(state).level, "ok");
+  assert.ok(describeAuth(state).text.includes("Last failure"));
+});
+
+test("a stored key readable by other users is reported as unusable, never as enabled", () => {
+  const path = credentialsPath();
+  writeFileSync(path, JSON.stringify({ apiKey: "stored-key-0123456789abcdef" }), { mode: 0o600 });
+  chmodSync(path, 0o644);
+  try {
+    const state = authState();
+    assert.equal(state.kind, "unusable");
+    assert.equal(state.usable, false);
+    assert.equal(state.reason !== undefined, true);
+    assert.equal(describeAuth(state).level, "error");
+  } finally {
+    chmodSync(path, 0o600);
+  }
+});
+
+test("a corrupt auth record is ignored and clearing forgets both facts", () => {
+  writeFileSync(authStatePath(), "{ not json");
+  assert.equal(authState().verified, false);
+  assert.equal(authState().lastFailure, undefined);
+  recordAuthVerified(new Date("2026-01-04T00:00:00.000Z"));
+  clearAuthState();
+  const cleared = authState();
+  assert.equal(cleared.verified, false);
+  assert.equal(cleared.lastFailure, undefined);
+});