pi-pignon 0.1.1

package/src/config/presets.ts

@@ -0,0 +1,54 @@
+/**
+ * Model presets: the four built-in model names (`fast`, `balanced`,
+ * `reasoner`, `agent`) filled from one provider. A config file selects one
+ * with `"extends": "<name>"`; `/pignon init <name>` copies one into a new
+ * config file.
+ *
+ * Ids are Pi model ids (`pi --list-models`). They are starting points, not
+ * recommendations: check prices and quality for your own work.
+ */
+
+import type { ModelSpec } from "../types.js";
+
+export interface Preset {
+  description: string;
+  models: Readonly<Record<"fast" | "balanced" | "reasoner" | "agent", ModelSpec>>;
+}
+
+export const PRESETS = {
+  openrouter: {
+    description: "OpenRouter: DeepSeek flash models, GLM for reasoning, HY4 as agent (the built-in table)",
+    models: {
+      fast: { provider: "openrouter", modelId: "deepseek/deepseek-v4-flash-0731", thinking: "off" },
+      balanced: { provider: "openrouter", modelId: "deepseek/deepseek-v4.1-flash", thinking: "low" },
+      reasoner: { provider: "openrouter", modelId: "z-ai/glm-5.3", thinking: "high" },
+      agent: { provider: "openrouter", modelId: "tencent/hy4-preview", thinking: "low" },
+    },
+  },
+  anthropic: {
+    description: "Anthropic: Haiku for small edits, Sonnet for the rest, Opus for hard reasoning",
+    models: {
+      fast: { provider: "anthropic", modelId: "claude-haiku-4-5", thinking: "off" },
+      balanced: { provider: "anthropic", modelId: "claude-sonnet-5", thinking: "low" },
+      reasoner: { provider: "anthropic", modelId: "claude-opus-5-5", thinking: "high" },
+      agent: { provider: "anthropic", modelId: "claude-sonnet-5", thinking: "medium" },
+    },
+  },
+  openai: {
+    description: "OpenAI: GPT-6 Luna for small edits, GPT-5.6 Terra for the rest, GPT-6 Sol for reasoning, Codex as agent",
+    models: {
+      fast: { provider: "openai", modelId: "gpt-6-luna", thinking: "off" },
+      balanced: { provider: "openai", modelId: "gpt-5.6-terra", thinking: "low" },
+      reasoner: { provider: "openai", modelId: "gpt-6-sol", thinking: "high" },
+      agent: { provider: "openai", modelId: "gpt-5.3-codex", thinking: "medium" },
+    },
+  },
+} as const satisfies Record<string, Preset>;
+
+export type PresetName = keyof typeof PRESETS;
+
+export const PRESET_NAMES = Object.keys(PRESETS) as PresetName[];
+
+export function isPresetName(value: unknown): value is PresetName {
+  return typeof value === "string" && value in PRESETS;
+}

package/src/config/schema.ts

@@ -0,0 +1,224 @@
+/**
+ * Shape of the config file (`~/.pi/agent/pignon.json`), as a TypeBox schema.
+ *
+ * TypeBox schemas are plain JSON Schema, so this one module gives the file's
+ * TS types, the runtime checks (`load.ts`) and `schema/config.schema.json`
+ * for editor autocompletion.
+ */
+
+import Type, { type Static } from "typebox";
+
+import { THINKING_LEVELS } from "../types.js";
+import { PRESETS, PRESET_NAMES } from "./presets.js";
+
+const ThinkingSchema = Type.Enum([...THINKING_LEVELS], {
+  description: "Pi thinking level to set with the model. Pi clamps it to what the model supports.",
+});
+
+export const ModelSpecSchema = Type.Object(
+  {
+    provider: Type.String({ minLength: 1, description: "Pi provider id, e.g. `openrouter` or `anthropic`." }),
+    modelId: Type.String({ minLength: 1, description: "Model id within the provider. Check with `pi --list-models`." }),
+    thinking: ThinkingSchema,
+  },
+  { additionalProperties: false },
+);
+
+/** A model: the name of an entry in `models`, or an inline model. */
+const modelRef = (description: string) =>
+  Type.Union([Type.String({ minLength: 1, description: "Name of an entry in `models`." }), ModelSpecSchema], {
+    description,
+  });
+
+export const ModelRefSchema = modelRef("A name from `models`, or an inline { provider, modelId, thinking }.");
+
+export const TierFileSchema = Type.Object(
+  {
+    id: Type.String({
+      pattern: "^[a-z][a-z0-9_-]*$",
+      description: "Tier name, shown on decision cards. Lowercase letters, digits, `-` and `_`.",
+    }),
+    criterion: Type.String({
+      minLength: 1,
+      description: "How to recognize a task of this tier. This text is what the decision model reads.",
+    }),
+    model: Type.Optional(modelRef("Model for every task of this tier. Use it, or both `direct` and `exploration`.")),
+    direct: Type.Optional(modelRef("Model for tasks that can be done without exploring the codebase.")),
+    exploration: Type.Optional(modelRef("Model for tasks that need to explore the codebase first.")),
+    explorationAllowed: Type.Optional(
+      Type.Boolean({
+        description: "Set false to send tasks that need exploration to the next tier up. Default true.",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export const TiersSchema = Type.Array(TierFileSchema, {
+  minItems: 2,
+  maxItems: 8,
+  description: "Difficulty tiers, easiest first. Replaces the default list as a whole.",
+});
+
+export const QuestionsSchema = Type.Object(
+  {
+    version: Type.Optional(
+      Type.String({
+        minLength: 1,
+        description: "Label stored with each decision. Change it whenever you edit the wording or the tier criteria.",
+      }),
+    ),
+    tierInstructions: Type.Optional(Type.String({ minLength: 1 })),
+    explorationInstructions: Type.Optional(Type.String({ minLength: 1 })),
+    explorationCriteria: Type.Optional(
+      Type.Object(
+        { yes: Type.Optional(Type.String({ minLength: 1 })), no: Type.Optional(Type.String({ minLength: 1 })) },
+        { additionalProperties: false },
+      ),
+    ),
+  },
+  { additionalProperties: false, description: "Wording of the questions sent to the decision model." },
+);
+
+const threshold = (description: string) => Type.Optional(Type.Number({ minimum: 0, description }));
+
+export const ThresholdsSchema = Type.Object(
+  {
+    minConfidenceDowngrade: threshold("Confidence needed to downgrade, or to move in from a model outside the table."),
+    minConfidenceUpgrade: threshold("Confidence needed to upgrade."),
+    minConfidenceForm: threshold("Confidence needed to call a task direct rather than exploration."),
+    cacheGuardTokens: threshold("Context size above which lateral switches (and downgrades, when prices are unknown) are refused."),
+    minPromptsBetweenSwitches: threshold("Prompts to wait after a switch before the next downgrade or lateral switch."),
+    maxPaybackRequests: threshold("A downgrade must recoup its cache-miss cost within this many LLM requests."),
+    assumedOutputTokensPerRequest: threshold("Output per request assumed when estimating what a downgrade saves."),
+    layaTimeoutMs: threshold("Timeout for one decision from the local Laya worker, in milliseconds."),
+  },
+  { additionalProperties: false },
+);
+
+export const ConfidenceSourceSchema = Type.Enum(["reported", "top-probability"], {
+  description:
+    "`reported`: the decision model's confidence. `top-probability`: the probability of the chosen answer, for checkpoints whose confidence is uncalibrated.",
+});
+
+const timeoutMs = (description: string) => Type.Optional(Type.Number({ exclusiveMinimum: 0, description }));
+
+export const LayaLocalDeciderSchema = Type.Object(
+  {
+    type: Type.Literal("laya-local", {
+      description: "Experimental: pignon's own Laya worker (Apple Silicon, laya-mlx), installed from the repository's worker/ directory.",
+    }),
+    timeoutMs: timeoutMs("Timeout for one decision, in milliseconds. Default: thresholds.layaTimeoutMs."),
+    command: Type.Optional(
+      Type.Array(Type.String({ minLength: 1 }), {
+        minItems: 1,
+        description:
+          "Command that starts the worker, e.g. [\"uv\", \"run\", \"--project\", \"/path/to/pignon/worker\", \"pignon-laya\"]. Default: found automatically (LAYA_PYTHON, a source checkout, then pignon-laya on PATH).",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export const LayaServeDeciderSchema = Type.Object(
+  {
+    type: Type.Literal("laya-serve", {
+      description: "A Laya model served by the official laya-serve (`pip install \"laya[serve]\"`). Runs on your machine unless url points elsewhere.",
+    }),
+    url: Type.Optional(
+      Type.String({ pattern: "^https?://", description: "Server root. Default: http://127.0.0.1:8000 (laya-serve's default port)." }),
+    ),
+    model: Type.Optional(
+      Type.String({ minLength: 1, description: "Laya checkpoint: `english`, `multilingual` or `typed-decisions`. Default: chosen by the server from the prompt's language." }),
+    ),
+    apiKeyEnv: Type.Optional(
+      Type.String({ minLength: 1, description: "Environment variable holding the server's key, when it was started with LAYA_API_KEY. Default: no key." }),
+    ),
+    timeoutMs: timeoutMs("Timeout for one decision, in milliseconds. Default: 1500."),
+  },
+  { additionalProperties: false },
+);
+
+export const JevDeciderSchema = Type.Object(
+  {
+    type: Type.Literal("jev", { description: "TypeSafe's hosted Jev model. Sends each routed prompt (first 4000 characters) to the API." }),
+    model: Type.Optional(Type.String({ minLength: 1, description: "Jev model to pin, e.g. `jev-1.13.0`. Default: jev-latest." })),
+    baseURL: Type.Optional(
+      Type.String({ minLength: 1, description: "API root. `https://openrouter.ai/api` goes through OpenRouter. Default: TypeSafe." }),
+    ),
+    apiKeyEnv: Type.Optional(
+      Type.String({ minLength: 1, description: "Environment variable holding the API key. Default: TYPESAFE_API_KEY." }),
+    ),
+    timeoutMs: timeoutMs("Timeout for one decision, in milliseconds. Default: 1500."),
+    maxRetries: Type.Optional(Type.Integer({ minimum: 0, maximum: 3, description: "Retries after a failed attempt. Default: 0." })),
+  },
+  { additionalProperties: false },
+);
+
+export const DECIDER_SCHEMAS = {
+  "laya-serve": LayaServeDeciderSchema,
+  "laya-local": LayaLocalDeciderSchema,
+  jev: JevDeciderSchema,
+} as const;
+
+export const DecidersSchema = Type.Array(Type.Union([LayaServeDeciderSchema, LayaLocalDeciderSchema, JevDeciderSchema]), {
+  minItems: 1,
+  maxItems: 4,
+  description:
+    "Decision models, in the order to try them. Default: laya-local when its experimental worker is installed, else jev when TYPESAFE_API_KEY is set. /pignon init adds laya-serve when it is running.",
+});
+
+export const StrategySchema = Type.Object(
+  {
+    mode: Type.Optional(
+      Type.Enum(["sequential", "parallel"], {
+        description:
+          "`sequential` (default): ask the deciders in order until one is confident enough. `parallel`: ask them all at once, e.g. to compare them.",
+      }),
+    ),
+    escalateBelow: Type.Optional(
+      Type.Number({ minimum: 0, maximum: 1, description: "Sequential: ask the next decider when tier confidence is below this. Default 0.75." }),
+    ),
+    pick: Type.Optional(
+      Type.Enum(["most-confident", "first"], {
+        description:
+          "Parallel: route on the most confident answer (default), or on the first decider in the list that answered (the others are only recorded).",
+      }),
+    ),
+    budgetMs: Type.Optional(
+      Type.Number({ exclusiveMinimum: 0, description: "Wall-time limit for one decision, all deciders included. Default 3000." }),
+    ),
+  },
+  { additionalProperties: false, description: "How several deciders are combined." },
+);
+
+export const ConfigFileSchema = Type.Object(
+  {
+    $schema: Type.Optional(Type.String()),
+    version: Type.Optional(Type.Literal(2, { description: "Config format version." })),
+    extends: Type.Optional(
+      Type.Enum([...PRESET_NAMES], {
+        description: `Model preset for the built-in names, applied before \`models\`: ${PRESET_NAMES.map((n) => `\`${n}\` (${PRESETS[n].description})`).join("; ")}.`,
+      }),
+    ),
+    deciders: Type.Optional(DecidersSchema),
+    strategy: Type.Optional(StrategySchema),
+    models: Type.Optional(
+      Type.Record(Type.String({ pattern: "^[A-Za-z0-9][A-Za-z0-9._-]*$" }), ModelSpecSchema, {
+        description: "Named models, referenced from `tiers`. Merged over the built-in names (fast, balanced, reasoner, agent).",
+      }),
+    ),
+    tiers: Type.Optional(TiersSchema),
+    questions: Type.Optional(QuestionsSchema),
+    confidenceSource: Type.Optional(ConfidenceSourceSchema),
+    thresholds: Type.Optional(ThresholdsSchema),
+  },
+  { additionalProperties: false, title: "pignon configuration" },
+);
+
+export type ModelRef = Static<typeof ModelRefSchema>;
+export type TierFile = Static<typeof TierFileSchema>;
+export type ConfigFile = Static<typeof ConfigFileSchema>;
+
+/** Where the published JSON Schema lives, for the `$schema` key of config files. */
+export const CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/siiick/pi-pignon/main/schema/config.schema.json";

package/src/deciders/create.ts

@@ -0,0 +1,102 @@
+/**
+ * Build the decider described by the config.
+ *
+ * With no `deciders` section, pignon picks one: the experimental Laya worker
+ * when it is installed, else Jev when its API key is set. laya-serve is never
+ * picked here, since that would need a network probe at startup; `/pignon init`
+ * probes for it and writes it into the config. When neither is possible it
+ * returns an `UnavailableDecider` whose warmup error says what to install.
+ */
+
+import type { DeciderSpec, RouterConfig } from "../types.js";
+import { DEFAULT_API_KEY_ENV, JevDecider } from "./jev.js";
+import { LayaWorker, layaRuntimeStatus } from "./laya-local.js";
+import { createLayaServeDecider } from "./laya-serve.js";
+import { parseDecision } from "./parse.js";
+import { StrategyDecider } from "./strategy.js";
+import { type Decider, type DeciderResult, DeciderError } from "./types.js";
+
+export interface CreatedDecider {
+  decider: Decider;
+  /** Things to tell the user once, at session start. */
+  notes: string[];
+}
+
+export interface CreateDeciderDeps {
+  env?: NodeJS.ProcessEnv;
+  /** Whether the local worker can run here (tests replace the platform check). */
+  layaStatus?: typeof layaRuntimeStatus;
+}
+
+export function createDecider(config: RouterConfig, deps: CreateDeciderDeps = {}): CreatedDecider {
+  const env = deps.env ?? process.env;
+  const notes: string[] = [];
+  let specs = config.deciders;
+
+  if (specs === null) {
+    const laya = (deps.layaStatus ?? layaRuntimeStatus)(env);
+    if (laya.ok) {
+      specs = [{ type: "laya-local" }];
+    } else if (env[DEFAULT_API_KEY_ENV]?.trim()) {
+      specs = [{ type: "jev" }];
+    } else {
+      return {
+        decider: new UnavailableDecider(
+          `no decider configured: start laya-serve (see pignon's README) and run /pignon init, or set ${DEFAULT_API_KEY_ENV} for Jev`,
+        ),
+        notes,
+      };
+    }
+  }
+
+  const deciders = specs.map((spec) => build(spec, config, env));
+  if (deciders.length === 1) return { decider: deciders[0]!, notes };
+  return {
+    decider: new StrategyDecider(deciders, config.strategy, (answers, latencyMs) => parseDecision(answers, latencyMs, config)),
+    notes,
+  };
+}
+
+function build(spec: DeciderSpec, config: RouterConfig, env: NodeJS.ProcessEnv): Decider {
+  switch (spec.type) {
+    case "laya-serve":
+      return createLayaServeDecider(spec, env);
+    case "laya-local":
+      return new LayaWorker({
+        timeoutMs: spec.timeoutMs ?? config.thresholds.layaTimeoutMs,
+        ...(spec.command ? { launchCommand: spec.command } : {}),
+      });
+    case "jev":
+      return new JevDecider({
+        env,
+        ...(spec.model !== undefined ? { model: spec.model } : {}),
+        ...(spec.baseURL !== undefined ? { baseURL: spec.baseURL } : {}),
+        ...(spec.apiKeyEnv !== undefined ? { apiKeyEnv: spec.apiKeyEnv } : {}),
+        ...(spec.timeoutMs !== undefined ? { timeoutMs: spec.timeoutMs } : {}),
+        ...(spec.maxRetries !== undefined ? { maxRetries: spec.maxRetries } : {}),
+      });
+  }
+}
+
+/** Stands in when no decider can run: never ready, and says why. */
+export class UnavailableDecider implements Decider {
+  readonly id = "none";
+  readonly remote = false;
+  readonly isReady = false;
+  readonly model = undefined;
+  readonly recentLogs: readonly string[];
+
+  constructor(private readonly reason: string) {
+    this.recentLogs = [reason];
+  }
+
+  async warmup(): Promise<void> {
+    throw new DeciderError(this.reason);
+  }
+
+  async decide(): Promise<DeciderResult> {
+    throw new DeciderError(this.reason);
+  }
+
+  stop(): void {}
+}

package/src/deciders/jev.ts

@@ -0,0 +1,226 @@
+/**
+ * `jev` decider: TypeSafe's hosted Jev System-One model, through the official
+ * TypeScript SDK (`@typesafe-ai/sdk`).
+ *
+ * Remote: the prompt (already capped by the router) leaves the machine. The
+ * SDK is hardened for use inside Pi's TUI:
+ * - its logger writes to `recentLogs` (for `/pignon log`), never the console,
+ *   and never at `debug` level, which would log request bodies (prompts);
+ * - retries are off by default: the SDK's timeout applies per attempt with no
+ *   total budget, and a routing decision that arrives late is useless.
+ *
+ * The same client serves `laya-serve` (see `laya-serve.ts`), which speaks the
+ * Jev API; the options below let it run without a TypeSafe key.
+ */
+
+import {
+  type Fetch,
+  type Logger,
+  type Question,
+  APIConnectionError,
+  APIError,
+  APITimeoutError,
+  APIUserAbortError,
+  AuthenticationError,
+  PermissionDeniedError,
+  RateLimitError,
+  TypeSafeClient,
+  TypeSafeError,
+} from "@typesafe-ai/sdk";
+
+import type { LayaQuestion } from "../types.js";
+import { type Decider, type DeciderResult, type DecisionRequest, DeciderError } from "./types.js";
+
+/** Environment variable holding the API key unless `apiKeyEnv` names another. */
+export const DEFAULT_API_KEY_ENV = "TYPESAFE_API_KEY";
+
+/** Jev answers in 70–500 ms; a decision later than this is not worth waiting for. */
+export const DEFAULT_JEV_TIMEOUT_MS = 1_500;
+
+const LOG_CAPACITY = 200;
+
+export interface JevDeciderOptions {
+  /** Decider id in logs and stats. Defaults to `jev`. */
+  id?: string;
+  /**
+   * Whether an API key is needed to be ready. When false and no key is set, a
+   * placeholder is sent, never the SDK's TYPESAFE_API_KEY fallback. Default: true.
+   */
+  requireApiKey?: boolean;
+  /** Said after "cannot reach the API" (e.g. how to start a local server). */
+  unreachableHint?: string;
+  /** Environment variable that holds the API key. Defaults to TYPESAFE_API_KEY. */
+  apiKeyEnv?: string;
+  /** API root, e.g. `https://openrouter.ai/api` to go through OpenRouter. Defaults to the SDK's (TypeSafe). */
+  baseURL?: string;
+  /** Jev model to pin, e.g. `jev-1.13.0`. Defaults to the SDK's (`jev-latest`). */
+  model?: string;
+  /** Timeout for one decision, in milliseconds. */
+  timeoutMs?: number;
+  /** Retries after a failed attempt. Each gets the full timeout. */
+  maxRetries?: number;
+  /** Where to read the API key and SDK settings. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /** HTTP implementation (tests). */
+  fetch?: Fetch;
+}
+
+/** Sent when no key is needed: an explicit value keeps the SDK from reading TYPESAFE_API_KEY. */
+const NO_API_KEY = "none";
+
+export class JevDecider implements Decider {
+  readonly id: string;
+  /** False when `baseURL` is this machine: the prompt does not leave it. */
+  readonly remote: boolean;
+
+  private readonly options: JevDeciderOptions;
+  private readonly apiKeyEnv: string;
+  private readonly timeoutMs: number;
+  private readonly logLines: string[] = [];
+  private client?: TypeSafeClient;
+  private lastModel?: string;
+  private stopped = false;
+
+  constructor(options: JevDeciderOptions = {}) {
+    this.options = options;
+    this.id = options.id ?? "jev";
+    this.remote = !(options.baseURL !== undefined && isLoopbackURL(options.baseURL));
+    this.apiKeyEnv = options.apiKeyEnv ?? DEFAULT_API_KEY_ENV;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_JEV_TIMEOUT_MS;
+  }
+
+  /** Ready as soon as an API key is available (or none is needed); there is nothing to load. */
+  get isReady(): boolean {
+    return !this.stopped && (this.apiKey() !== undefined || this.options.requireApiKey === false);
+  }
+
+  /** The model that last answered, else the one requests will name. */
+  get model(): string | undefined {
+    if (this.lastModel) return this.lastModel;
+    if (this.options.requireApiKey === false) return this.options.model;
+    return this.client?.defaultModel ?? this.options.model ?? this.env().TYPESAFE_DEFAULT_MODEL ?? "jev-latest";
+  }
+
+  get recentLogs(): readonly string[] {
+    return this.logLines;
+  }
+
+  /** Check the API key and build the client. No network call. */
+  async warmup(): Promise<void> {
+    this.ensureClient();
+  }
+
+  async decide(request: DecisionRequest, signal?: AbortSignal): Promise<DeciderResult> {
+    const client = this.ensureClient();
+    const started = Date.now();
+    try {
+      const result = await client.systemOne(
+        { state: request.text, questions: toSdkQuestions(request.questions) },
+        { signal, timeout: this.timeoutMs, retry: { maxRetries: this.options.maxRetries ?? 0 } },
+      );
+      // The API reports the price at runtime; the SDK does not declare it yet.
+      const cost = (result.usage as { cost?: unknown } | undefined)?.cost;
+      this.lastModel = result.model;
+      return {
+        deciderId: this.id,
+        model: result.model,
+        answers: result.answers,
+        latencyMs: Date.now() - started,
+        ...(typeof cost === "number" && Number.isFinite(cost) ? { costUsd: cost } : {}),
+      };
+    } catch (err) {
+      let error = describeError(err, this.timeoutMs);
+      if (err instanceof APIConnectionError && this.options.unreachableHint) error += `; ${this.options.unreachableHint}`;
+      this.log(`decide failed: ${error}`);
+      throw new DeciderError(`${this.id}: ${error}`, err);
+    }
+  }
+
+  stop(): void {
+    this.stopped = true;
+    this.client = undefined;
+  }
+
+  // -------------------------------------------------------------------------
+
+  private env(): NodeJS.ProcessEnv {
+    return this.options.env ?? process.env;
+  }
+
+  private apiKey(): string | undefined {
+    const key = this.env()[this.apiKeyEnv]?.trim();
+    return key ? key : undefined;
+  }
+
+  private ensureClient(): TypeSafeClient {
+    if (this.stopped) throw new DeciderError(`${this.id}: decider is stopped`);
+    if (this.client) return this.client;
+    const apiKey = this.apiKey() ?? (this.options.requireApiKey === false ? NO_API_KEY : undefined);
+    if (!apiKey) throw new DeciderError(`${this.id}: ${this.apiKeyEnv} is not set`);
+
+    const env = this.env();
+    try {
+      this.client = new TypeSafeClient({
+        apiKey,
+        baseURL: this.options.baseURL ?? env.TYPESAFE_BASE_URL,
+        defaultModel: this.options.model ?? env.TYPESAFE_DEFAULT_MODEL,
+        logger: this.logger(),
+        // `debug` logs request bodies, which hold the prompt.
+        logLevel: "warn",
+        timeout: this.timeoutMs,
+        ...(this.options.fetch ? { fetch: this.options.fetch } : {}),
+      });
+    } catch (err) {
+      throw new DeciderError(`${this.id}: ${err instanceof Error ? err.message : String(err)}`, err);
+    }
+    return this.client;
+  }
+
+  private logger(): Logger {
+    const write = (level: string) => (message: string) => this.log(`${level}: ${message}`);
+    return { debug: write("debug"), info: write("info"), warn: write("warn"), error: write("error") };
+  }
+
+  private log(line: string): void {
+    this.logLines.push(line);
+    if (this.logLines.length > LOG_CAPACITY) this.logLines.shift();
+  }
+}
+
+/** Whether a URL points at this machine. */
+export function isLoopbackURL(url: string): boolean {
+  let host: string;
+  try {
+    host = new URL(url).hostname;
+  } catch {
+    return false;
+  }
+  return host === "localhost" || host === "[::1]" || host === "::1" || /^127(\.\d{1,3}){3}$/.test(host);
+}
+
+/** Our question shapes are the Jev wire format; only the score tuple type differs. */
+function toSdkQuestions(questions: DecisionRequest["questions"]): Record<string, Question> {
+  return Object.fromEntries(Object.entries(questions).map(([name, q]) => [name, toSdkQuestion(q)]));
+}
+
+function toSdkQuestion(question: LayaQuestion): Question {
+  if (question.type === "score") {
+    if (question.criteria.length < 2) throw new DeciderError("jev: a score question needs at least two criteria");
+    return { ...question, criteria: question.criteria as unknown as readonly [string, string, ...string[]] };
+  }
+  return question;
+}
+
+/** One short line per failure, for the status bar and decision card. */
+export function describeError(err: unknown, timeoutMs: number): string {
+  if (err instanceof AuthenticationError || err instanceof PermissionDeniedError) {
+    return `API key rejected (HTTP ${err.status})`;
+  }
+  if (err instanceof RateLimitError) return "rate limited (HTTP 429)";
+  if (err instanceof APIError) return `HTTP ${err.status}${err.requestId ? ` (request ${err.requestId})` : ""}`;
+  if (err instanceof APITimeoutError) return `timed out after ${timeoutMs} ms`;
+  if (err instanceof APIUserAbortError) return "aborted";
+  if (err instanceof APIConnectionError) return `cannot reach the API: ${err.message}`;
+  if (err instanceof TypeSafeError || err instanceof Error) return err.message;
+  return String(err);
+}