privateer-agent 0.2.1 → 0.3.0

package/src/daemon/index.ts

@@ -1,11 +1,19 @@
 import type { Server } from "node:net";
-import type { ToolSet } from "ai";
-import { loadConfig } from "../config/load.ts";
-import { createSession } from "../session.ts";
-import { autoApproveGate } from "../permissions/gate.ts";
-import { loadMcpServers, connectMcpServers } from "../mcp/client.ts";
+import { readFileSync } from "node:fs";
+// Pi session stack. The daemon MUST be launched after ./boot.ts (env +
+// attestation dispatcher) — these are evaluated on import.
+import {
+  createAgentSessionServices,
+  createAgentSessionFromServices,
+  SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import { agentDir, configPath } from "../config/paths.ts";
+import { createEngineEventAdapter } from "../bridge/engineAdapter.ts";
+import { makePermissionGate, type GateController } from "../ext/permissionGate.ts";
+import { makePiPrivacyExtension } from "pi-privacy";
+import { makeAccountProvider } from "../providers/account.ts";
 import { RelayClient } from "../remote/relayClient.ts";
-import { hasCredentials, revokeChildSession } from "../auth/privateer.ts";
+import { hasCredentials, revokeChildSession, apiRequest, spawnAccountCredentials } from "../auth/privateer.ts";
 import {
   loadRoutines,
   upsertRoutine,
@@ -13,25 +21,65 @@ import {
   removeRoutine,
   addPendingRelay,
   drainPendingRelay,
+  addPendingCloud,
+  loadPendingCloud,
+  savePendingCloud,
+  type PendingCloud,
   routineRelayId,
 } from "../routines/store.ts";
 import type { Routine } from "../routines/schema.ts";
 import { triggerError, computeNextRun, advanceAfterRun } from "../routines/trigger.ts";
-import { splitRoutineTools, filterMcpTools } from "../routines/toolSelect.ts";
-import { deliver, type RelayPusher } from "../routines/delivery.ts";
+import { splitRoutineTools } from "../routines/toolSelect.ts";
+import { deliver, type RelayPusher, type CloudPusher } from "../routines/delivery.ts";
+import { sealJson, decodeAccountPublicKey } from "../crypto/outboxSeal.ts";
+import { redactText, collectSecrets } from "../util/redact.ts";
 import { startIpcServer, type IpcRequest, type IpcResponse } from "./ipc.ts";
 
-// The safe, read-only-plus-web toolset for unattended runs. No write/edit/bash, so
-// a routine firing with nobody watching can't mutate the filesystem or shell out.
-const SAFE_TOOLS = ["read", "glob", "grep", "web_fetch", "web_search"];
+// The safe, read-only toolset for unattended runs — Pi builtins with no
+// write/edit/bash, so a routine firing with nobody watching can't mutate the
+// filesystem or shell out. (0.2's web_fetch/web_search return once the web tools
+// land in Phase 5.) Safety is the tool restriction; the gate auto-approves what's
+// allowed but still fail-closes a dangerous shell command headlessly.
+const SAFE_TOOLS = ["read", "grep", "find", "ls"];
 
 const TICK_MS = 60_000; // scan for due routines once a minute
+const MAX_CLOUD_PLAINTEXT = 45_000;
+
+interface DaemonConfig {
+  defaultModel: string;
+  webhooks?: Record<string, { url: string; secret?: string; headers?: Record<string, string> }>;
+  providers?: Record<string, { apiKey?: string } | undefined>;
+}
+
+// Minimal config read (webhooks + providers-for-redaction + default model). The
+// full config layer is a Phase-7 port; the daemon only needs these fields.
+function loadDaemonConfig(): DaemonConfig {
+  try {
+    const raw = JSON.parse(readFileSync(configPath(), "utf8"));
+    return {
+      defaultModel: typeof raw.defaultModel === "string" ? raw.defaultModel : "openrouter/openai/gpt-4o-mini",
+      webhooks: raw.webhooks,
+      providers: raw.providers,
+    };
+  } catch {
+    return { defaultModel: "openrouter/openai/gpt-4o-mini" };
+  }
+}
+
+// Split a "provider:model" (0.2) or "provider/model" (new) spec on its first
+// separator. Model ids themselves contain "/", so we key off the first delimiter.
+function parseSpec(spec: string): { provider: string; modelId: string } {
+  const i = spec.indexOf(":");
+  const j = spec.indexOf("/");
+  const sep = i === -1 ? j : j === -1 ? i : Math.min(i, j);
+  if (sep <= 0) return { provider: spec, modelId: "" };
+  return { provider: spec.slice(0, sep), modelId: spec.slice(sep + 1) };
+}
 
 function log(msg: string): void {
   process.stdout.write(`[${new Date().toISOString()}] ${msg}\n`);
 }
 
-// Render a run's result as a self-contained markdown document for file/notice output.
 function formatResult(routine: Routine, body: string, status: "ok" | "error", error?: string): string {
   const when = new Date().toISOString();
   const head = `# ${routine.name}\n\n_${when} · ${status}${routine.model ? ` · ${routine.model}` : ""}_\n\n`;
@@ -43,38 +91,34 @@ export class Daemon {
   private server?: Server;
   private timer?: ReturnType<typeof setInterval>;
   private readonly startedAt = Date.now();
-  // Set of routine ids currently executing, so a slow run can't be re-entered by
-  // the next tick.
   private readonly running = new Set<string>();
-  // Outbound relay connection to the Privateer server, opened lazily when a signed-in
-  // user has a routine that delivers over `relay`. Pushes results to an attached
-  // controller (e.g. the mobile app) in real time.
   private relay?: RelayClient;
-  // Best-effort "is a controller attached right now?" — set on controller_attached,
-  // cleared when our socket drops. Used to decide push-live vs queue-for-later.
   private controllerAttached = false;
-  // The app sent `terminate` (End remote access): keep the relay down until the
-  // daemon restarts, even if routine edits re-run syncRelay. Results still queue
-  // durably and deliver over the other channels meanwhile.
   private relayTerminated = false;
-  // Push a result live if a controller is attached; otherwise persist it to the
-  // pending queue so it flushes the moment the app next attaches. Either path is
-  // durable, so delivery treats both as handled.
+
   private readonly pushRelay: RelayPusher = (routine, content) => {
     if (this.controllerAttached && this.relay?.sendRoutineResult(routine.name, content)) return "live";
     addPendingRelay({ routine: routine.name, at: new Date().toISOString(), content });
     return "queued";
   };
 
+  private outboxPub?: Uint8Array;
+
+  private readonly pushCloud: CloudPusher = async (routine, content, status) => {
+    const at = new Date().toISOString();
+    if (await this.postOutbox(routine.name, at, status, content)) return "sent";
+    addPendingCloud({ routine: routine.name, at, status, content });
+    return "queued";
+  };
+
   start(): void {
-    // Prime nextRun for any routine missing one, then start the loop + IPC server.
     this.primeSchedule();
     this.timer = setInterval(() => void this.tick(), TICK_MS);
     this.server = startIpcServer((req) => this.handleIpc(req));
     this.syncRelay();
+    void this.flushPendingCloud();
     const count = loadRoutines().filter((r) => r.enabled).length;
     log(`daemon started (pid ${process.pid}); ${count} enabled routine(s). Tick every ${TICK_MS / 1000}s.`);
-    // Fire an immediate scan so a just-due routine doesn't wait a full minute.
     void this.tick();
   }
 
@@ -84,46 +128,36 @@ export class Daemon {
     this.relay?.stop();
   }
 
-  // Open the relay connection when it's both wanted (a signed-in account + at least
-  // one enabled routine delivering over `relay`) and not already up. Started ahead
-  // of fire time so it's connected when a routine actually pushes. We never tear it
-  // down once up — an idle authenticated socket is cheap and reconnects itself.
   private syncRelay(): void {
     if (this.relay || this.relayTerminated) return;
     if (!hasCredentials()) return;
     const wantsRelay = loadRoutines().some((r) => r.enabled && r.delivery.includes("relay"));
     if (!wantsRelay) return;
-    this.relay = new RelayClient({
-      // The daemon publishes results but is not a drivable terminal: ignore any
-      // prompts/approvals a controller might send.
-      onPrompt: () => {},
-      onInterrupt: () => {},
-      onApprovalResponse: () => {},
-      onControllerAttached: () => this.onControllerAttached(),
-      onAttachment: () => {},
-      onTerminate: () => {
-        this.relayTerminated = true;
-        this.controllerAttached = false;
-        this.relay?.stop();
-        this.relay = undefined;
-        log("relay terminated from the app; staying offline until the daemon restarts");
-      },
-      onStatus: (text) => log(`relay: ${text}`),
-      onDisconnected: () => {
-        this.controllerAttached = false;
+    this.relay = new RelayClient(
+      {
+        onPrompt: () => {},
+        onInterrupt: () => {},
+        onApprovalResponse: () => {},
+        onControllerAttached: () => this.onControllerAttached(),
+        onAttachment: () => {},
+        onTerminate: () => {
+          this.relayTerminated = true;
+          this.controllerAttached = false;
+          this.relay?.stop();
+          this.relay = undefined;
+          log("relay terminated from the app; staying offline until the daemon restarts");
+        },
+        onStatus: (text) => log(`relay: ${text}`),
+        onDisconnected: () => {
+          this.controllerAttached = false;
+        },
       },
-    }, {
-      // Stable identity so the daemon shows up as one recognizable terminal in the
-      // app across restarts, instead of a fresh random "terminal-xxxx" each boot.
-      termId: routineRelayId(),
-      label: "Privateer Routines",
-    });
+      { termId: routineRelayId(), label: "Privateer Routines" },
+    );
     void this.relay.start();
     log("relay connection starting (routine has relay delivery + account signed in)");
   }
 
-  // The app attached: greet it, then flush any routine results that finished while it
-  // was closed so it catches up immediately (in fire order).
   private onControllerAttached(): void {
     this.controllerAttached = true;
     this.relay?.sendSnapshot([{ kind: "notice", text: "Privateer routines — results will appear here as they run." }]);
@@ -133,6 +167,54 @@ export class Daemon {
     for (const p of pending) this.relay?.sendRoutineResult(p.routine, p.content);
   }
 
+  // ── Cloud outbox (sealed store-and-forward) ────────────────────────────────
+
+  private async ensureOutboxPub(): Promise<Uint8Array | undefined> {
+    if (this.outboxPub) return this.outboxPub;
+    try {
+      const res = await apiRequest("/api/outbox/pubkey");
+      if (!res.ok) return undefined;
+      const data = (await res.json()) as { outboxPublicKey?: string | null };
+      if (!data.outboxPublicKey) return undefined;
+      this.outboxPub = decodeAccountPublicKey(data.outboxPublicKey);
+      return this.outboxPub;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private async postOutbox(routine: string, at: string, status: "ok" | "error", content: string): Promise<boolean> {
+    const pub = await this.ensureOutboxPub();
+    if (!pub) return false;
+    const body = content.length > MAX_CLOUD_PLAINTEXT ? content.slice(0, MAX_CLOUD_PLAINTEXT) + "\n…truncated" : content;
+    const sealed = sealJson(pub, { v: 1, kind: "routine", name: routine, status, at, content: body });
+    try {
+      const res = await apiRequest("/api/outbox", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ sealed }),
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  private async flushPendingCloud(): Promise<void> {
+    if (!hasCredentials()) return;
+    const queue = loadPendingCloud();
+    if (queue.length === 0) return;
+    const remaining: PendingCloud[] = [];
+    for (const p of queue) {
+      if (remaining.length === 0 && (await this.postOutbox(p.routine, p.at, p.status, p.content))) continue;
+      remaining.push(p);
+    }
+    if (remaining.length !== queue.length) {
+      savePendingCloud(remaining);
+      log(`flushed ${queue.length - remaining.length} pending cloud outbox item(s); ${remaining.length} remaining`);
+    }
+  }
+
   private primeSchedule(): void {
     for (const r of loadRoutines()) {
       if (!r.enabled) continue;
@@ -143,10 +225,11 @@ export class Daemon {
   }
 
   private async tick(): Promise<void> {
+    void this.flushPendingCloud();
     const now = Date.now();
     for (const r of loadRoutines()) {
       if (!r.enabled || this.running.has(r.id)) continue;
-      if (triggerError(r)) continue; // skip malformed triggers
+      if (triggerError(r)) continue;
       if (!r.nextRun) {
         const nr = computeNextRun(r);
         this.persistRun(r.id, { nextRun: nr?.toISOString() });
@@ -158,89 +241,94 @@ export class Daemon {
     }
   }
 
-  // Execute a routine to completion and deliver the result. Advances nextRun past
-  // now afterwards (skipping any backlog) so at most one run fires per tick.
+  // Execute a routine to completion and deliver the result. The one rewired seam:
+  // drive a headless Pi session (auto-approve gate + restricted tool set) instead of
+  // the old engine, collecting the text output.
   async runRoutine(routine: Routine): Promise<IpcResponse> {
     if (this.running.has(routine.id)) return { ok: false, message: "already running" };
     this.running.add(routine.id);
     log(`running routine "${routine.name}"`);
 
-    const config = loadConfig();
+    const config = loadDaemonConfig();
     const modelSpec = routine.model ?? config.defaultModel;
     const split = splitRoutineTools(routine.tools);
-    // If the routine names no builtin tools, it still gets the safe read/web set —
-    // a routine that only lists MCP selectors shouldn't lose the ability to read.
     const allowedTools = split.builtin.length > 0 ? split.builtin : SAFE_TOOLS;
-    const wantsEmail = routine.delivery.includes("email");
-
-    // MCP tools are fulfilled inside the agent turn. Two grants exist: explicit
-    // "<server>__<tool>" selectors in routine.tools (least privilege: only the named
-    // servers are launched and only the selected tools exposed), and the legacy email
-    // delivery, which exposes every configured server so the mail tool is reachable.
-    // Either way, egress stays an explicit tool action rather than a side channel.
-    let extraTools: ToolSet | undefined;
-    let closeMcp: (() => void) | undefined;
-    let prompt = routine.prompt;
-    if (split.mcp.length > 0 || wantsEmail) {
-      try {
-        const all = loadMcpServers(routine.cwd);
-        for (const s of split.servers) {
-          if (!all[s]) log(`  mcp: server "${s}" not configured in mcp.json — skipping`);
-        }
-        const servers = wantsEmail
-          ? all
-          : Object.fromEntries(Object.entries(all).filter(([name]) => split.servers.includes(name)));
-        const conn = await connectMcpServers(servers, routine.cwd, autoApproveGate);
-        const selected = filterMcpTools(conn.tools, split.mcp);
-        // Email needs every server's tools (the mail tool isn't in the selectors);
-        // otherwise expose only what the routine was granted.
-        extraTools = wantsEmail ? conn.tools : selected;
-        closeMcp = () => conn.clients.forEach((c) => c.close());
-        if (split.mcp.length > 0 && Object.keys(selected).length === 0) {
-          log(`  mcp: selectors matched no tools (${split.mcp.join(", ")})`);
-        }
-        if (wantsEmail) {
-          prompt +=
-            "\n\nWhen finished, email the result to the account owner using the available mail tool " +
-            "(e.g. a Gmail create/send tool). Keep the subject short and put the summary in the body.";
-        }
-      } catch (err) {
-        log(`  mcp setup failed: ${err instanceof Error ? err.message : String(err)}`);
-      }
+    if (split.mcp.length > 0 || routine.delivery.includes("email")) {
+      log("  note: MCP tools + email delivery are not wired yet (Phase 5) — skipping those");
     }
 
     let out = "";
     let status: "ok" | "error" = "ok";
     let error: string | undefined;
     try {
-      const session = createSession({
-        config,
-        modelSpec,
+      // Auto-approve (bypass) gate — safety is `tools: allowedTools`; a dangerous
+      // shell command still fail-closes headlessly (localAsk denies).
+      const gate: GateController = {
+        getMode: () => "bypass",
+        setMode: () => {},
+        allowlist: [],
+        allowedOutsideRoots: [],
         cwd: routine.cwd,
-        gate: autoApproveGate,
         confineToCwd: true,
-        allowedTools,
-        extraTools,
+        async localAsk() {
+          return "deny";
+        },
+      };
+      const services = await createAgentSessionServices({
+        cwd: routine.cwd,
+        agentDir: agentDir(),
+        resourceLoaderOptions: {
+          extensionFactories: [makePermissionGate(gate), makePiPrivacyExtension(), makeAccountProvider()] as any,
+        },
       });
-      for await (const ev of session.engine.send(prompt)) {
-        if (ev.type === "text") out += ev.text;
-        else if (ev.type === "error") {
-          status = "error";
-          error = ev.error;
+
+      const { provider, modelId } = parseSpec(modelSpec);
+      if (provider === "privateer") {
+        try {
+          const creds = await spawnAccountCredentials();
+          (services.authStorage as any).set("privateer", { type: "oauth", ...creds });
+        } catch (e) {
+          log(`  account channel unavailable: ${(e as Error).message}`);
         }
       }
+
+      const model = (services.modelRegistry as any).find(provider, modelId);
+      if (!model) {
+        status = "error";
+        error = `model ${provider}/${modelId} not found`;
+      } else {
+        const { session } = await createAgentSessionFromServices({
+          services,
+          sessionManager: SessionManager.inMemory(routine.cwd),
+          model,
+          tools: allowedTools,
+        } as any);
+        const adapter = createEngineEventAdapter();
+        session.subscribe((ev: any) => {
+          for (const ee of adapter.toEngineEvents(ev)) {
+            if (ee.type === "text") out += ee.text;
+            else if (ee.type === "error") {
+              status = "error";
+              error = ee.error;
+            }
+          }
+        });
+        await session.prompt(routine.prompt);
+      }
     } catch (err) {
       status = "error";
       error = err instanceof Error ? err.message : String(err);
-    } finally {
-      closeMcp?.();
     }
 
     const content = formatResult(routine, out, status, error);
-    const report = deliver(routine, content, status, { pushRelay: this.pushRelay });
+    const report = await deliver(routine, content, status, {
+      pushRelay: this.pushRelay,
+      pushCloud: this.pushCloud,
+      webhooks: config.webhooks,
+      redact: (text) => redactText(text, collectSecrets(config.providers)),
+    });
     log(`  "${routine.name}" ${status}; delivered via ${report.delivered.join(", ") || "(none)"}`);
 
-    // Recurring routines reschedule; one-offs disable themselves after firing.
     this.persistRun(routine.id, {
       lastRun: new Date().toISOString(),
       lastStatus: status,
@@ -251,8 +339,6 @@ export class Daemon {
     return { ok: status === "ok", message: report.delivered.join(", ") || undefined };
   }
 
-  // Merge run bookkeeping into the persisted routine, re-reading first so we don't
-  // clobber concurrent IPC edits (add/pause/remove).
   private persistRun(id: string, patch: Partial<Routine>): void {
     const current = findRoutine(loadRoutines(), id);
     if (!current) return;
@@ -270,7 +356,7 @@ export class Daemon {
         if (err) return { ok: false, message: `invalid trigger: ${err}` };
         const nr = computeNextRun(req.routine);
         upsertRoutine({ ...req.routine, nextRun: nr?.toISOString() });
-        this.syncRelay(); // connect the relay if this routine introduced relay delivery
+        this.syncRelay();
         return { ok: true, message: `routine "${req.routine.name}" saved`, routines: loadRoutines() };
       }
       case "remove": {
@@ -292,7 +378,6 @@ export class Daemon {
       case "run-now": {
         const r = findRoutine(loadRoutines(), req.idOrName);
         if (!r) return { ok: false, message: `no routine "${req.idOrName}"` };
-        // Fire in the background so the IPC caller isn't blocked on a long run.
         void this.runRoutine(r);
         return { ok: true, message: `running "${r.name}" now` };
       }
@@ -306,15 +391,13 @@ export class Daemon {
   }
 }
 
-// Entry point for `privateer daemon`.
+// Entry point for `privateer daemon`. Caller must have imported ./boot.ts first.
 export function runDaemon(): void {
   const daemon = new Daemon();
   daemon.start();
   const shutdown = () => {
     log("shutting down");
     daemon.stop();
-    // Release this process's Privateer session so the daemon drops off the
-    // app's Linked Devices immediately (best effort, then exit regardless).
     void revokeChildSession().finally(() => process.exit(0));
   };
   process.on("SIGINT", shutdown);

package/src/daemon/ipc.ts

@@ -1,7 +1,7 @@
 import { createServer, createConnection, type Socket, type Server } from "node:net";
 import { existsSync, unlinkSync, chmodSync } from "node:fs";
 import { join } from "node:path";
-import { globalDir } from "../config/load.ts";
+import { globalDir } from "../config/paths.ts";
 import type { Routine } from "../routines/schema.ts";
 
 // The CLI/TUI talks to the resident daemon over a unix domain socket. The protocol

package/src/engine/errors.ts

@@ -17,8 +17,11 @@ interface ErrorFacts {
   statusCode?: number;
   providerMessage?: string;
   code?: string; // provider's machine-readable error code, e.g. "DAILY_CAP_HIT"
+  errno?: string; // Node socket-level code, e.g. "ECONNREFUSED"
   model?: string;
   provider?: string;
+  url?: string; // the endpoint the failing request targeted
+  message?: string; // deepest non-empty Error message in the chain
 }
 
 const HOST_LABELS: Record<string, string> = {
@@ -26,70 +29,81 @@ const HOST_LABELS: Record<string, string> = {
   "api.anthropic.com": "Anthropic",
   "api.openai.com": "OpenAI",
   "cloud-api.near.ai": "NEAR AI",
+  "localhost:11434": "Ollama",
+  "127.0.0.1:11434": "Ollama",
 };
 
-// The AI SDK wraps the real provider error: a retry sequence that exhausts its
-// attempts throws AI_RetryError, whose `.lastError` is the APICallError that
-// actually carries statusCode / responseBody / requestBodyValues. Without peeling
-// that off we'd read undefined for every field and fall back to the wrapper's bare
-// "Too Many Requests". Follow `.lastError` (and a `.cause` that looks like a
-// richer error) until we reach the one with the useful fields.
-function unwrap(err: unknown): unknown {
-  let cur = err;
-  for (let i = 0; i < 5; i++) {
-    if (!cur || typeof cur !== "object") break;
-    const e = cur as Record<string, unknown>;
-    const richer = e.statusCode == null && e.responseBody == null;
-    const inner = e.lastError ?? (richer ? e.cause : undefined);
-    if (!inner || inner === cur) break;
-    cur = inner;
-  }
-  return cur;
-}
+// Socket-level failures Node/undici report via an error `code`. Distinct from the
+// provider's machine code (which comes out of the response body) — these mean the
+// request never got a response at all.
+const NETWORK_ERRNO =
+  /^(ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|EPIPE|ENETUNREACH|EHOSTUNREACH|UND_ERR_CONNECT_TIMEOUT|UND_ERR_SOCKET)$/;
 
 // Pull structured fields off an unknown error without trusting any one shape.
+//
+// The AI SDK nests the useful error: retry exhaustion throws AI_RetryError, whose
+// `.lastError` is the APICallError carrying statusCode / url / responseBody, whose
+// `.cause` on a connection failure is the socket error (often an AggregateError
+// with an EMPTY message but an errno code). No single level has everything, so
+// walk the whole chain and merge: HTTP-ish facts keep the first (shallowest)
+// value found, while `message` keeps the deepest NON-EMPTY one — inner messages
+// are more specific ("Cannot connect to API") than the wrapper's ("Failed after
+// 3 attempts…"), but the socket error at the very bottom may have none at all.
 function extract(err: unknown): ErrorFacts {
-  const e = (err ?? {}) as Record<string, unknown>;
-  const statusCode = typeof e.statusCode === "number" ? e.statusCode : undefined;
+  const facts: ErrorFacts = {};
 
   // The provider's own message + machine code, preferred over the SDK's wrapper
   // text. Providers disagree on shape: OpenAI/OpenRouter nest under `error`, while
   // the Privateer account backend returns a flat `{ message, code }` (e.g. a daily
   // usage cap). Read both shapes; keep the first message/code we find.
-  let providerMessage: string | undefined;
-  let code: string | undefined;
   const readBody = (body: unknown) => {
     const b = body as
       | { error?: { message?: unknown; code?: unknown }; message?: unknown; code?: unknown }
       | undefined;
     if (!b || typeof b !== "object") return;
     const msg = b.error?.message ?? b.message;
-    if (providerMessage == null && typeof msg === "string") providerMessage = msg;
+    if (facts.providerMessage == null && typeof msg === "string") facts.providerMessage = msg;
     const c = b.error?.code ?? b.code;
-    if (code == null && typeof c === "string") code = c;
+    if (facts.code == null && typeof c === "string") facts.code = c;
   };
-  readBody(e.data);
-  if (typeof e.responseBody === "string") {
-    try {
-      readBody(JSON.parse(e.responseBody));
-    } catch {
-      /* responseBody wasn't JSON — fall back to the wrapper message */
+
+  let cur: unknown = err;
+  for (let i = 0; i < 6 && cur && typeof cur === "object"; i++) {
+    const e = cur as Record<string, unknown>;
+
+    if (facts.statusCode == null && typeof e.statusCode === "number") facts.statusCode = e.statusCode;
+    readBody(e.data);
+    if (typeof e.responseBody === "string") {
+      try {
+        readBody(JSON.parse(e.responseBody));
+      } catch {
+        /* responseBody wasn't JSON — fall back to the wrapper message */
+      }
     }
-  }
 
-  const reqBody = e.requestBodyValues as { model?: unknown } | undefined;
-  const model = typeof reqBody?.model === "string" ? reqBody.model : undefined;
+    const reqBody = e.requestBodyValues as { model?: unknown } | undefined;
+    if (facts.model == null && typeof reqBody?.model === "string") facts.model = reqBody.model;
+
+    if (facts.url == null && typeof e.url === "string" && /^https?:/.test(e.url)) {
+      facts.url = e.url;
+      try {
+        facts.provider = HOST_LABELS[new URL(e.url).host];
+      } catch {
+        /* not a URL */
+      }
+    }
 
-  let provider: string | undefined;
-  if (typeof e.url === "string") {
-    try {
-      provider = HOST_LABELS[new URL(e.url).host];
-    } catch {
-      /* not a URL */
+    if (facts.errno == null && typeof e.code === "string" && NETWORK_ERRNO.test(e.code)) {
+      facts.errno = e.code;
     }
+    if (typeof e.message === "string" && e.message.trim()) facts.message = e.message;
+
+    const next = e.lastError ?? e.cause;
+    if (!next || next === cur) break;
+    cur = next;
   }
 
-  return { statusCode, providerMessage, code, model, provider };
+  return facts;
 }
 
 // Machine codes the Privateer backend returns for a hard account cap (daily /
@@ -116,10 +130,9 @@ function rawMessage(err: unknown): string {
 // Map a provider error to a friendly message + hint. Falls back to the raw
 // (redacted) message for anything we don't recognize, so nothing is swallowed.
 export function describeError(err: unknown): DescribedError {
-  const inner = unwrap(err);
-  const facts = extract(inner);
+  const facts = extract(err);
   const status = facts.statusCode;
-  const text = facts.providerMessage ?? rawMessage(inner);
+  const text = facts.providerMessage ?? facts.message ?? rawMessage(err);
   const forModel = facts.model ? ` for ${facts.model}` : "";
   const forProvider = facts.provider ? ` for ${facts.provider}` : "";
 
@@ -195,9 +208,36 @@ export function describeError(err: unknown): DescribedError {
       retryable: true,
     });
   }
-  if (/fetch failed|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|network/i.test(text)) {
+  if (
+    facts.errno != null ||
+    /fetch failed|cannot connect|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|network/i.test(text)
+  ) {
+    let origin: string | undefined;
+    let localhost = false;
+    if (facts.url) {
+      try {
+        const u = new URL(facts.url);
+        origin = u.origin;
+        localhost = /^(localhost$|127\.|0\.0\.0\.0$|\[::1\]$)/.test(u.hostname);
+      } catch {
+        /* not a URL */
+      }
+    }
+    // A local inference server that refuses connections isn't a flaky network —
+    // it isn't running. Say which one and how to start it; retrying won't help
+    // until the user acts, so no `retryable` flag.
+    if (localhost) {
+      const label = facts.provider ?? "the local server";
+      return out({
+        message: `Cannot connect to ${label} at ${origin} — nothing is listening there.`,
+        hint:
+          facts.provider === "Ollama"
+            ? "Start Ollama (run `ollama serve`, or open the Ollama app), then try again — or run /model to switch models."
+            : "Start the server (or check its base URL), then try again — or run /model to switch models.",
+      });
+    }
     return out({
-      message: "Network error reaching the provider.",
+      message: `Network error reaching ${facts.provider ?? origin ?? "the provider"}.`,
       hint: "Check your connection and try again.",
       retryable: true,
     });