pi-system-one 1.3.1 → 1.3.2

package/README.md

@@ -26,7 +26,7 @@ Pi's [v1.0.3 Codemode guide](https://github.com/earendil-works/pi/blob/v1.0.3/pa
 
 Pi v1.0.3 [defines its Score answer](https://github.com/earendil-works/pi/blob/v1.0.3/packages/ai/src/types.ts#L660-L678) with only `score` and `confidence`. Its [response parser](https://github.com/earendil-works/pi/blob/v1.0.3/packages/ai/src/api/system-one-shared.ts#L80-L119) copies only those two Score fields. [TypeSafe's HTTP API](https://docs.typesafe.ai/api#score-answer) returns `probabilities` and `legend` too. Pi's [classifier input types](https://github.com/earendil-works/pi/blob/v1.0.3/packages/ai/src/types.ts#L635-L658) and [codemode docs](https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/codemode.md#classify) document the narrower inputs shown above. These references describe Pi v1.0.3, not future releases.
 
-If you already use `codemode` to combine tools and only need Pi's classifier response, use Pi's built-in route. For standalone decisions, choose this extension when you want a direct tool without a script or Codemode setup. It also provides prompt guidance, compatible custom endpoints, and the full Score distribution when the backend supplies it. The extension can run on a host without `codemode` if that host supports its extension APIs. Its OMP package entry makes it installable in OMP, but it does not guarantee support for every Pi or OMP version. `/so config` can save non-secret settings or select Pi's native classifier. Native mode rejects Score questions because Pi v1.0.3 does not expose their probability distribution. See [Pi classifier docs for v1.0.3](https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/models.md#use-classifier-models).
+If you already use `codemode` to combine tools and only need Pi's classifier response, use Pi's built-in route. For standalone decisions, choose this extension when you want a direct tool without a script or Codemode setup. It also provides prompt guidance, compatible custom endpoints, and the full Score distribution when the backend supplies it. The extension can run on a host without `codemode` if that host supports its extension APIs. Its OMP package entry makes it installable in OMP, but it does not guarantee support for every Pi or OMP version. `/so config` can save non-secret settings or select Pi's native classifier. Native mode rejects Score questions because Pi v1.0.3 does not expose their probability distribution. Optional `auto` mode routes native-compatible Choice/Noul requests to Pi's classifier when registered and other requests to TypeSafe HTTP; it does not retry a failed call through another backend. See [Pi classifier docs for v1.0.3](https://github.com/earendil-works/pi/blob/v1.0.3/packages/coding-agent/docs/models.md#use-classifier-models).
 
 For Oh My Pi (OMP), install the published package with:
 
@@ -61,14 +61,14 @@ export SYSTEM_ONE_MODEL=reflex
 # Set SYSTEM_ONE_API_KEY only when your endpoint requires a key.
 ```
 
-Existing `SYSTEM_ONE_BASE_URL` takes precedence over saved settings. For TypeSafe, `jev-latest` is supplied automatically when no model is set. Other endpoints may require `SYSTEM_ONE_MODEL`.
+`SYSTEM_ONE_BASE_URL` selects a custom endpoint when no mode is saved. A saved mode and custom endpoint win on restart. TypeSafe defaults to `jev-latest`; other endpoints may require `SYSTEM_ONE_MODEL`.
 
 
 ---
 
 ## Configuration
 
-Run `/so config` to choose `typesafe` (default HTTP path), `custom` (any System One endpoint), or `native` (Pi classifier). `/so config native` and `/so config typesafe` switch directly. Non-secret settings are saved to `<agent-dir>/pi-system-one.json`, where `<agent-dir>` is Pi's agent directory (`~/.pi/agent` by default or `PI_CODING_AGENT_DIR`). Terminal Pi and Paseo must use the same agent directory to share that file and Pi's saved login. Restart or reload an already-running client after the other client changes settings. Use `/so status` to inspect current mode and credential availability.
+Run `/so` or `/so config` to select `typesafe` (default HTTP path), `custom` (a configured System One endpoint), `native` (Pi classifier), or `auto` (per-request routing). `/so config auto`, `/so config native`, and `/so config typesafe` switch directly. Non-secret settings are saved to `<agent-dir>/pi-system-one.json`, where `<agent-dir>` is Pi's agent directory (`~/.pi/agent` by default or `PI_CODING_AGENT_DIR`). Terminal Pi and Paseo must use the same agent directory to share that file and Pi's saved login. Restart or reload an already-running client after the other client changes settings. Use `/so status` to inspect current mode and credential availability.
 
 For example, a saved custom endpoint looks like this:
 
@@ -81,9 +81,11 @@ For example, a saved custom endpoint looks like this:
 }
 ```
 
-Never store a key in JSON. A key entered into `/so config` stays in this session only. Leave key input blank to keep it; enter `-` to forget it. For custom endpoints, set `SYSTEM_ONE_BASE_URL` with `SYSTEM_ONE_API_KEY` if using environment credentials. An environment key without an environment endpoint never follows a saved custom URL. Custom URLs saved by `/so config` must be HTTP(S), without URL credentials, query, or fragment; put authentication in the key input or environment instead. Native mode supports Choice and Noul but rejects Score questions rather than hide missing probabilities. For full Score results, select `typesafe` or `custom`.
+Never store a key in JSON. A key entered into `/so config` stays in this session only. Leave key input blank to keep it; enter `-` to forget it. For custom endpoints, set `SYSTEM_ONE_BASE_URL` with `SYSTEM_ONE_API_KEY` if using environment credentials. An environment key without an environment endpoint never follows a saved custom URL. Custom URLs saved by `/so config` must be HTTP(S), without URL credentials, query, or fragment; put authentication in the key input or environment instead. Native mode supports Choice and Noul but rejects Score questions rather than hide missing probabilities. For full Score results, select `typesafe`, `custom`, or `auto`. Auto uses native only when the complete request is compatible and Pi has a registered classifier. Otherwise, it uses canonical TypeSafe HTTP, not a custom endpoint. A failed native call does not trigger an HTTP retry. Registered models may still fail without valid credentials.
 
-Environment endpoint and model values override saved settings at startup. A saved model is not reused when an environment endpoint points elsewhere. When `/so config` changes a custom URL, blank model input clears the previous endpoint's model; enter a model to keep using one. An explicit `/so config` choice takes effect immediately in this session. If both are set, the environment endpoint wins again on next startup.
+Use `/so debug` to inspect up to 20 recent `system_one` calls in a terminal overlay. It shows selected provider (`pi-native`, `typesafe`, or `configured`), route reason, sanitized HTTP POST target, outcome, timing, and question-type counts. Failed calls distinguish provider selection from an attempted request, and show fixed native failure categories (unsupported Score, classifier exception/error, invalid response, or abort) without provider-controlled error text. Diagnostics stay in memory for the current Pi session; they never store request state, criteria, credentials, raw URLs, or raw provider error text. Target display retains origin and common API path segments but redacts URL userinfo, queries, fragments, and other path segments. In RPC mode, `/so debug` sends a brief notification instead; JSON and print modes have no UI. `/so status` remains focused on settings.
+
+A current-session selection takes effect immediately. Saved mode and saved custom endpoint win on restart. `SYSTEM_ONE_BASE_URL` selects a custom endpoint only when no mode is saved; without either, TypeSafe HTTP remains the default. Environment keys and models are used only with their matching endpoint, while `SYSTEM_ONE_TIMEOUT_MS` can override a saved timeout. `/so status` shows the mode source and notes when a saved choice ignores an environment endpoint. To return to environment-only routing, remove the saved non-secret settings file. When `/so config` changes a custom URL, blank model input clears the old endpoint's model; enter a replacement when needed.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-system-one",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "System One decisions for Pi. Plug in TypeSafe Jev, Reflex, or your own provider.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,7 @@
     "coding-agent"
   ],
   "dependencies": {
+    "@earendil-works/pi-tui": "^1.0.4",
     "system-one-core": "^0.2.1"
   },
   "peerDependencies": {

package/src/commands.ts

@@ -7,12 +7,14 @@ import {
   type ConfigMode,
   createSessionConfig,
   describeConfig,
+  isTypeSafeEndpoint,
   type SessionConfig,
   TYPESAFE_BASE_URL,
   TYPESAFE_MODEL,
 } from "./config.ts";
+import { DebugHistory, observedProvider } from "./debug.ts";
+import { DebugOverlay, debugSummary } from "./debug-ui.ts";
 import { saveStoredConfig } from "./persistence.ts";
-import { isTypeSafeEndpoint, resolveSessionProvider } from "./provider.ts";
 import { buildSystemOneTool } from "./tool.ts";
 
 export interface SessionStore {
@@ -25,13 +27,19 @@ export function registerSystemOneCommands(
   configPath?: string,
 ) {
   let registered = false;
+  const history = new DebugHistory();
+  pi.on("session_start", () => history.clear());
   function applyProvider() {
     if (registered) return;
     registered = true;
     pi.registerTool(
       buildSystemOneTool({
-        resolveProvider: (ctx) =>
-          resolveSessionProvider(store.session ?? createSessionConfig(), ctx),
+        resolveProvider: async (ctx) =>
+          observedProvider(
+            store.session ?? createSessionConfig(),
+            ctx,
+            history,
+          ),
       }),
     );
   }
@@ -43,7 +51,7 @@ export function registerSystemOneCommands(
     const current = store.session ?? createSessionConfig();
     const modes: ConfigMode[] = [
       current.mode,
-      ...(["typesafe", "custom", "native"] as ConfigMode[]).filter(
+      ...(["typesafe", "custom", "native", "auto"] as ConfigMode[]).filter(
         (mode) => mode !== current.mode,
       ),
     ];
@@ -51,6 +59,7 @@ export function registerSystemOneCommands(
       typesafe: "TypeSafe Jev (HTTP, full Score)",
       custom: "Custom System One endpoint",
       native: "Pi classifier (Choice and Noul only)",
+      auto: "Native when compatible, TypeSafe HTTP otherwise",
     };
     const options = modes.map(
       (mode) =>
@@ -68,15 +77,17 @@ export function registerSystemOneCommands(
         ? modes[options.indexOf(modeRaw)]
         : (modeRaw.trim().toLowerCase() as ConfigMode);
     if (!mode || !modes.includes(mode)) {
-      ctx.ui.notify("Choose typesafe, custom, or native.", "error");
+      ctx.ui.notify("Choose typesafe, custom, native, or auto.", "error");
       return;
     }
     const next: SessionConfig = {
       current: { ...current.current },
       mode,
+      modeSource: "session",
+      ignoredEnvironmentEndpoint: false,
       keyInMemory: current.keyInMemory,
     };
-    if (mode === "typesafe") {
+    if (mode === "typesafe" || mode === "auto") {
       next.current.baseUrl = TYPESAFE_BASE_URL;
       next.current.model = TYPESAFE_MODEL;
       // A key exported for a custom endpoint must not follow a mode switch.
@@ -148,6 +159,10 @@ export function registerSystemOneCommands(
         });
       }
     }
+    next.ignoredEnvironmentEndpoint = Boolean(
+      process.env.SYSTEM_ONE_BASE_URL &&
+        process.env.SYSTEM_ONE_BASE_URL !== next.current.baseUrl,
+    );
     if (configPath) {
       try {
         saveStoredConfig(configPath, {
@@ -198,15 +213,33 @@ export function registerSystemOneCommands(
     ctx.ui.notify(summary, "info");
   }
 
+  async function cmdDebug(ctx: ExtensionCommandContext): Promise<void> {
+    if (ctx.mode !== "tui") {
+      ctx.ui.notify(debugSummary(history.entries), "info");
+      return;
+    }
+    await ctx.ui.custom<void>(
+      (tui, theme, _keybindings, done) =>
+        new DebugOverlay([...history.entries], theme, done, () =>
+          tui.requestRender(),
+        ),
+      {
+        overlay: true,
+        overlayOptions: { anchor: "center", width: 70, maxHeight: 24 },
+      },
+    );
+  }
+
   pi.registerCommand("so", {
     description: "System One config (/so status for current)",
     getArgumentCompletions: (prefix: string) =>
-      ["config", "status"]
+      ["config", "status", "debug"]
         .filter((c) => c.startsWith(prefix.trim().toLowerCase()))
         .map((c) => ({ value: c, label: c })),
     handler: async (args, ctx) => {
       const [cmd, mode] = args.trim().toLowerCase().split(/\s+/);
       if (cmd === "status") await cmdStatus(ctx);
+      else if (cmd === "debug") await cmdDebug(ctx);
       else await cmdConfig(ctx, cmd === "config" ? mode : undefined);
     },
   });

package/src/config.ts

@@ -1,9 +1,10 @@
 // pi-system-one/src/config.ts
 //
-// Non-secret settings can persist in the user agent directory. Environment
-// variables retain precedence at startup. API keys are never written by this
-// extension: /so config keys live only in memory; Pi login or explicit
-// environment credentials provide persistent authentication.
+// Non-secret settings persist in the user agent directory. A saved mode and
+// endpoint override an inherited environment URL; environment-only setups
+// still select their URL. API keys are never written by this extension:
+// /so config keys live only in memory; Pi login or endpoint-bound environment
+// credentials provide persistent authentication.
 
 export interface SystemOneEnv {
   SYSTEM_ONE_BASE_URL?: string;
@@ -22,7 +23,24 @@ export interface SystemOneExtConfig {
 export const DEFAULT_TIMEOUT_MS = 10_000;
 export const TYPESAFE_BASE_URL = "https://api.typesafe.ai";
 export const TYPESAFE_MODEL = "jev-latest";
-export type ConfigMode = "typesafe" | "custom" | "native";
+
+export function isTypeSafeEndpoint(baseUrl: string): boolean {
+  try {
+    const url = new URL(baseUrl);
+    return (
+      url.origin === TYPESAFE_BASE_URL &&
+      url.pathname === "/" &&
+      !url.search &&
+      !url.hash &&
+      !url.username &&
+      !url.password
+    );
+  } catch {
+    return false;
+  }
+}
+
+export type ConfigMode = "typesafe" | "custom" | "native" | "auto";
 
 /** Public settings only. Credentials never belong in this file. */
 export interface StoredConfig {
@@ -59,20 +77,24 @@ export interface SessionConfig {
   /** True when the key came from `/so config` (memory-only). */
   keyInMemory: boolean;
   mode: ConfigMode;
+  modeSource: "session" | "saved" | "environment" | "default";
+  ignoredEnvironmentEndpoint: boolean;
 }
 
 export function createSessionConfig(
   env: SystemOneEnv = process.env,
   stored: StoredConfig = {},
 ): SessionConfig {
-  const mode: ConfigMode = env.SYSTEM_ONE_BASE_URL
-    ? "custom"
-    : (stored.mode ?? "typesafe");
+  const mode: ConfigMode =
+    stored.mode ?? (env.SYSTEM_ONE_BASE_URL ? "custom" : "typesafe");
   const baseUrl =
     mode === "native"
       ? ""
-      : (env.SYSTEM_ONE_BASE_URL ??
-        (mode === "typesafe" ? TYPESAFE_BASE_URL : (stored.baseUrl ?? "")));
+      : mode === "typesafe" || mode === "auto"
+        ? TYPESAFE_BASE_URL
+        : stored.mode === "custom"
+          ? (stored.baseUrl ?? "")
+          : (env.SYSTEM_ONE_BASE_URL ?? "");
   const rawTimeout = env.SYSTEM_ONE_TIMEOUT_MS
     ? Number(env.SYSTEM_ONE_TIMEOUT_MS)
     : (stored.timeoutMs ?? DEFAULT_TIMEOUT_MS);
@@ -80,23 +102,42 @@ export function createSessionConfig(
     throw new Error("SYSTEM_ONE_TIMEOUT_MS must be a positive number");
   return {
     mode,
+    modeSource: stored.mode
+      ? "saved"
+      : env.SYSTEM_ONE_BASE_URL
+        ? "environment"
+        : "default",
+    ignoredEnvironmentEndpoint: Boolean(
+      stored.mode &&
+        env.SYSTEM_ONE_BASE_URL &&
+        env.SYSTEM_ONE_BASE_URL !== baseUrl,
+    ),
     current: {
       baseUrl,
-      // An env key without an env endpoint must not follow a saved custom URL.
+      // Bind environment credentials and model to their configured endpoint.
       apiKey:
         mode === "native" ||
-        (stored.mode === "custom" && !env.SYSTEM_ONE_BASE_URL)
+        (mode === "custom" &&
+          stored.mode === "custom" &&
+          env.SYSTEM_ONE_BASE_URL !== baseUrl) ||
+        ((mode === "typesafe" || mode === "auto") &&
+          env.SYSTEM_ONE_BASE_URL &&
+          !isTypeSafeEndpoint(env.SYSTEM_ONE_BASE_URL))
           ? undefined
           : env.SYSTEM_ONE_API_KEY || undefined,
       model:
         mode === "native"
           ? TYPESAFE_MODEL
-          : env.SYSTEM_ONE_MODEL ||
-            (env.SYSTEM_ONE_BASE_URL &&
-            env.SYSTEM_ONE_BASE_URL !== stored.baseUrl
-              ? undefined
-              : stored.model) ||
-            (mode === "typesafe" ? TYPESAFE_MODEL : undefined),
+          : mode === "typesafe"
+            ? ((!env.SYSTEM_ONE_BASE_URL ||
+                isTypeSafeEndpoint(env.SYSTEM_ONE_BASE_URL)) &&
+                env.SYSTEM_ONE_MODEL) ||
+              TYPESAFE_MODEL
+            : mode === "auto"
+              ? TYPESAFE_MODEL
+              : (env.SYSTEM_ONE_BASE_URL === baseUrl
+                  ? env.SYSTEM_ONE_MODEL
+                  : undefined) || stored.model,
       timeoutMs: rawTimeout,
     },
     keyInMemory: false,
@@ -114,6 +155,8 @@ export function blankSession(): SessionConfig {
     },
     keyInMemory: false,
     mode: "custom",
+    modeSource: "default",
+    ignoredEnvironmentEndpoint: false,
   };
 }
 
@@ -164,8 +207,16 @@ export function describeConfig(session: SessionConfig): string {
           : "  api key: from environment";
   return [
     "System One:",
-    `  mode: ${session.mode}`,
-    `  endpoint: ${c.baseUrl || "none"}`,
+    `  mode: ${session.mode} (${session.modeSource})`,
+    ...(session.mode === "auto"
+      ? [
+          "  routing: per request (native when compatible; TypeSafe HTTP otherwise)",
+        ]
+      : []),
+    ...(session.ignoredEnvironmentEndpoint
+      ? ["  environment endpoint ignored by selected mode"]
+      : []),
+    `  ${session.mode === "auto" ? "HTTP fallback endpoint" : "endpoint"}: ${c.baseUrl || "none"}`,
     keyLine,
     `  model: ${c.model ?? "server default"}`,
     `  timeout: ${c.timeoutMs}ms`,

package/src/debug-ui.ts

@@ -0,0 +1,125 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+import type { DebugEntry } from "./debug.ts";
+
+function counts(entry: DebugEntry): string {
+  const { choice, noul, score } = entry.questions;
+  return `${choice} choice · ${noul} noul · ${score} score`;
+}
+
+function rowCounts(entry: DebugEntry): string {
+  const { choice, noul, score } = entry.questions;
+  return [
+    choice ? `${choice} choice` : "",
+    noul ? `${noul} noul` : "",
+    score ? `${score} score` : "",
+  ]
+    .filter(Boolean)
+    .join(" · ");
+}
+
+/** Only render fields assembled by DebugHistory, never tool input or raw provider text. */
+export function debugSummary(entries: readonly DebugEntry[]): string {
+  const last = entries[0];
+  if (!last) return "System One debug: No system_one calls yet.";
+  return `System One debug: ${last.provider} · ${last.outcome} · ${last.durationMs ?? "running"} ms · ${counts(last)}. Session-only; ${entries.length} call(s) recorded.`;
+}
+
+export class DebugOverlay {
+  private selected = 0;
+  private readonly entries: readonly DebugEntry[];
+  private readonly theme: Theme;
+  private readonly done: () => void;
+  private readonly requestRender: () => void;
+  constructor(
+    entries: readonly DebugEntry[],
+    theme: Theme,
+    done: () => void,
+    requestRender: () => void,
+  ) {
+    this.entries = entries;
+    this.theme = theme;
+    this.done = done;
+    this.requestRender = requestRender;
+  }
+
+  handleInput(data: string): void {
+    if (
+      matchesKey(data, "escape") ||
+      matchesKey(data, "q") ||
+      matchesKey(data, "ctrl+c")
+    )
+      this.done();
+    else if (matchesKey(data, "up") || matchesKey(data, "k")) {
+      this.selected = Math.max(0, this.selected - 1);
+      this.requestRender();
+    } else if (matchesKey(data, "down") || matchesKey(data, "j")) {
+      this.selected = Math.min(
+        Math.max(0, this.entries.length - 1),
+        this.selected + 1,
+      );
+      this.requestRender();
+    }
+  }
+
+  render(width: number): string[] {
+    if (width < 3) return [" ".repeat(Math.max(0, width))];
+    const inner = width - 2;
+    const th = this.theme;
+    const page = Math.floor(this.selected / 7) * 7;
+    const pageEnd = Math.min(page + 7, this.entries.length);
+    const lines = [
+      th.fg("accent", " System One · Debug"),
+      th.fg(
+        "text",
+        this.entries.length
+          ? ` ${page + 1}-${pageEnd} of ${this.entries.length} recent calls · selected #${this.selected + 1} · session-only`
+          : " Session-only · no request content saved",
+      ),
+      "",
+    ];
+    if (this.entries.length === 0) lines.push(" No system_one calls yet.");
+    else {
+      for (let index = page; index < pageEnd; index++) {
+        const entry = this.entries[index];
+        const row = `${index === this.selected ? ">" : " "} #${index + 1} ${entry.startedAt.slice(11, 19)}  ${entry.provider.padEnd(10)} ${entry.outcome.padEnd(7)} ${rowCounts(entry)}`;
+        lines.push(index === this.selected ? th.fg("accent", row) : row);
+      }
+      const entry = this.entries[this.selected];
+      lines.push(
+        "",
+        th.fg("accent", " Selected call"),
+        ` Mode: ${entry.mode}  ·  Provider: ${entry.provider}`,
+        ` Route: ${entry.reason}`,
+        ...(entry.requestTarget ? [` Target: ${entry.requestTarget}`] : []),
+        ` Questions: ${counts(entry)}`,
+        ` Outcome: ${entry.outcome}  ·  Duration: ${entry.durationMs ?? "running"} ms`,
+        ` Dispatch: ${entry.attempted ? "attempted (delivery not verified)" : "not attempted"}`,
+        ...(entry.failure
+          ? [
+              ` Failure: ${entry.failure}${entry.httpStatus ? ` (HTTP ${entry.httpStatus})` : ""}`,
+            ]
+          : []),
+      );
+    }
+    lines.push("", th.fg("text", " ↑/↓ browse · q/Esc close"));
+    const output = [th.fg("border", `╭${"─".repeat(inner)}╮`)];
+    for (const line of lines) {
+      const clipped = truncateToWidth(line, inner, "…", true);
+      output.push(
+        th.fg("border", "│") +
+          clipped +
+          " ".repeat(Math.max(0, inner - visibleWidth(clipped))) +
+          th.fg("border", "│"),
+      );
+    }
+    output.push(th.fg("border", `╰${"─".repeat(inner)}╯`));
+    return output;
+  }
+
+  invalidate(): void {}
+}

package/src/debug.ts

@@ -0,0 +1,159 @@
+import type { ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import {
+  type QuestionMap,
+  type SystemOneCallOptions,
+  SystemOneHttpError,
+  type SystemOneProvider,
+  type SystemOneRequest,
+  type SystemOneResponse,
+  SystemOneTimeoutError,
+  SystemOneTransportError,
+} from "system-one-core";
+import { type SessionConfig, TYPESAFE_BASE_URL } from "./config.ts";
+import {
+  type NativeFailureCategory,
+  PiNativeDiagnosticError,
+  type RouteObserver,
+  resolveSessionProvider,
+} from "./provider.ts";
+
+const SAFE_PATH_SEGMENTS = new Set([
+  "api",
+  "v1",
+  "v2",
+  "systemone",
+  "system-one",
+  "classify",
+]);
+
+/** Mirror HTTP provider's POST target, but never retain userinfo, query, fragment, or arbitrary path segments. */
+export function safeRequestTarget(baseUrl: string): string {
+  try {
+    // HttpSystemOneProvider appends /v1/systemone after trimming one trailing slash.
+    const url = new URL(`${baseUrl.replace(/\/$/, "")}/v1/systemone`);
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+      return "POST invalid HTTP endpoint";
+    const path = url.pathname
+      .split("/")
+      .map((segment) =>
+        SAFE_PATH_SEGMENTS.has(segment) ? segment : segment ? "[redacted]" : "",
+      )
+      .join("/");
+    const note =
+      url.search || url.hash
+        ? " (base URL contains query/fragment; check path)"
+        : "";
+    return `POST ${url.origin}${path}${note}`;
+  } catch {
+    return "POST invalid HTTP endpoint";
+  }
+}
+
+export interface DebugEntry {
+  startedAt: string;
+  mode: SessionConfig["mode"];
+  provider: "pi-native" | "typesafe" | "configured" | "not selected";
+  reason: string;
+  requestTarget?: string;
+  outcome: "pending" | "success" | "failure";
+  attempted: boolean;
+  durationMs?: number;
+  failure?:
+    | NativeFailureCategory
+    | "HTTP error"
+    | "timeout"
+    | "transport error"
+    | "request failed";
+  httpStatus?: number;
+  questions: { choice: number; noul: number; score: number };
+}
+
+/** Bounded, in-memory diagnostics. Never retain input, credentials, raw URLs or raw errors. */
+export class DebugHistory {
+  readonly entries: DebugEntry[] = [];
+
+  clear(): void {
+    this.entries.length = 0;
+  }
+
+  start(mode: SessionConfig["mode"], questions: QuestionMap): DebugEntry {
+    const counts = { choice: 0, noul: 0, score: 0 };
+    for (const question of Object.values(questions)) counts[question.type]++;
+    const entry: DebugEntry = {
+      startedAt: new Date().toISOString(),
+      mode,
+      provider: "not selected",
+      reason: "route not selected",
+      outcome: "pending",
+      attempted: false,
+      questions: counts,
+    };
+    this.entries.unshift(entry);
+    if (this.entries.length > 20) this.entries.length = 20;
+    return entry;
+  }
+}
+
+export function observedProvider(
+  session: SessionConfig,
+  ctx: ExtensionToolContext,
+  history: DebugHistory,
+): SystemOneProvider {
+  return {
+    id: "diagnostic-wrapper",
+    async evaluate<Q extends QuestionMap>(
+      request: SystemOneRequest<Q>,
+      options?: SystemOneCallOptions,
+    ): Promise<SystemOneResponse<Q>> {
+      const entry = history.start(session.mode, request.questions);
+      const started = Date.now();
+      const onRoute: RouteObserver = (provider, reason) => {
+        entry.provider = provider;
+        entry.reason = reason;
+        if (provider !== "pi-native")
+          entry.requestTarget = safeRequestTarget(
+            provider === "typesafe"
+              ? TYPESAFE_BASE_URL
+              : session.current.baseUrl,
+          );
+      };
+      try {
+        const provider = await resolveSessionProvider(
+          session,
+          ctx,
+          onRoute,
+          () => {
+            entry.attempted = true;
+          },
+        );
+        if (provider.id === "typesafe" || provider.id === "configured")
+          entry.attempted = true;
+        const response = await provider.evaluate(request, options);
+        entry.outcome = "success";
+        return response;
+      } catch (error) {
+        entry.outcome = "failure";
+        entry.failure =
+          error instanceof PiNativeDiagnosticError
+            ? error.category
+            : error instanceof SystemOneHttpError
+              ? "HTTP error"
+              : error instanceof SystemOneTimeoutError
+                ? "timeout"
+                : error instanceof SystemOneTransportError
+                  ? "transport error"
+                  : "request failed";
+        if (
+          error instanceof SystemOneHttpError &&
+          Number.isInteger(error.status) &&
+          error.status >= 100 &&
+          error.status <= 599
+        )
+          entry.httpStatus = error.status;
+        throw error;
+      } finally {
+        entry.durationMs = Math.max(0, Date.now() - started);
+      }
+    },
+  };
+}

package/src/persistence.ts

@@ -8,7 +8,7 @@ import {
 import { dirname } from "node:path";
 import type { ConfigMode, StoredConfig } from "./config.ts";
 
-const MODES: ConfigMode[] = ["typesafe", "custom", "native"];
+const MODES: ConfigMode[] = ["typesafe", "custom", "native", "auto"];
 
 function validate(value: unknown, path: string): StoredConfig {
   if (typeof value !== "object" || value === null || Array.isArray(value))
@@ -24,7 +24,7 @@ function validate(value: unknown, path: string): StoredConfig {
   }
   if (v.mode !== undefined && !MODES.includes(v.mode as ConfigMode))
     throw new Error(
-      `Invalid System One settings in ${path}: mode must be typesafe, custom, or native`,
+      `Invalid System One settings in ${path}: mode must be typesafe, custom, native, or auto`,
     );
   if (
     v.baseUrl !== undefined &&