@gr8ful/spf 0.19.0 → 0.19.1

package/dist/core/runner.js

@@ -66,6 +66,30 @@ export class Run {
     phases = [];
     tokens = 0;
     cost = 0;
+    /** The BILLABLE half of `tokens` — see `UsageBreakdown.billable_tokens`'s doc comment. What `assertRunBudget` actually checks `defaults.max_run_tokens` against; `tokens` stays the display total. */
+    billable_tokens = 0;
+    /**
+     * True once this run has DISPATCHED at least one `claude_code` agent
+     * while `ANTHROPIC_BASE_URL` pointed somewhere other than Anthropic's own
+     * API — i.e. a gateway/proxy stood in for Anthropic on a call that
+     * actually happened. Read by `Console.sessionFinished` to label the run's
+     * printed cost as an estimate rather than a fact: `claude`'s own
+     * `total_cost_usd` is ANTHROPIC's price table applied to whatever the CLI
+     * thinks it called, which is honest only when Anthropic itself served the
+     * request.
+     *
+     * Starts `false` and is flipped by `recordDispatch()` below, called once
+     * per agent dispatch (`agents.ts`'s `execute()`, right before the real
+     * coding-agent call) — computed from what this run actually DISPATCHED,
+     * never from the roster's static shape (see `agents.ts`'s
+     * `isGatewayEstimatedDispatch` vs. `isGatewayEstimatedCost` doc comments
+     * for why that distinction matters: a chain can configure a `claude_code`
+     * agent it never actually calls this run, and labeling a real cost as
+     * "estimated" because the roster merely CONTAINS such an agent would be
+     * its own kind of dishonesty). Sticky: once a qualifying dispatch has
+     * happened, a later non-qualifying one must never flip it back to false.
+     */
+    cost_is_estimate = false;
     repo_root; // where every agent is spawned to work — always absolute
     /** Every git operation for this run, bound to repo_root. Never call git_helper directly. */
     git;
@@ -107,12 +131,23 @@ export class Run {
         this.agent_map[agent] = entry;
         writeFileSync(this.agentMapPath, JSON.stringify(this.agent_map, null, 2));
     }
+    /**
+     * Called once per agent dispatch, right before the real coding-agent call
+     * (`agents.ts`'s `execute()`) — see `cost_is_estimate`'s own doc comment
+     * for why this, not the roster, is what decides the label. Sticky: only
+     * ever flips `cost_is_estimate` from false to true, never back.
+     */
+    recordDispatch(agent) {
+        if (agents.isGatewayEstimatedDispatch(agent))
+            this.cost_is_estimate = true;
+    }
     // ── usage (run totals mirror what the tracer accumulates in the trace db) ─
-    async addUsage(tokens, cost) {
+    async addUsage(tokens, cost, billableTokens) {
         this.tokens += tokens;
         this.cost += cost;
-        await this.tracer.sessionAddUsage(this.adw_id, tokens, cost);
-        await this.console.notifyUsage(this.tokens, this.cost);
+        this.billable_tokens += billableTokens;
+        await this.tracer.sessionAddUsage(this.adw_id, tokens, cost, billableTokens);
+        await this.console.notifyUsage(this.tokens, this.cost, this.billable_tokens);
     }
     // ── the phase primitive ─────────────────────────────────────────────────
     async phase(params, fn) {
@@ -157,7 +192,7 @@ export class Run {
             await this.tracer.phaseUpsert(phase);
             await this.tracer.sessionFinish(this.adw_id, false);
             await this.console.phaseEnded(phase, (performance.now() - clock) / 1000);
-            await this.console.sessionFinished(false, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db));
+            await this.console.sessionFinished(false, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db), this.cost_is_estimate);
             throw error;
         }
     }
@@ -185,7 +220,7 @@ export class Run {
             await this.console.note(`not accepted: ${note}`);
         }
         await this.tracer.sessionFinish(this.adw_id, ok);
-        await this.console.sessionFinished(ok, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db));
+        await this.console.sessionFinished(ok, this.tokens, this.cost, describeObservabilityDb(this.cfg.observability.db), this.cost_is_estimate);
         return ok ? 0 : 1;
     }
 }

package/dist/core/tiering.js

@@ -25,7 +25,7 @@
  * stands. `effectiveAgent` is the one place that turns a resolution into an
  * actual `AgentConfig` — overriding `model` and NOTHING else.
  */
-import { ollamaBaseUrl } from "./ollama_provider.js";
+import { ollamaApiKey, ollamaBaseUrl } from "./ollama_provider.js";
 // ── the classifier (design doc §2) ──────────────────────────────────────────
 /**
  * One explicit `name -> weight` table entry per BUILT-IN chain
@@ -184,9 +184,13 @@ async function fetchServedOllamaTags() {
     try {
         // ollamaBaseUrl() is the SAME default-substitution a real dispatch
         // uses, including treating a set-but-EMPTY OLLAMA_BASE_URL as unset —
-        // never re-derive that default here.
+        // never re-derive that default here. Same for ollamaApiKey(): against a
+        // gateway (not bare Ollama) this endpoint 401s without a bearer — send
+        // the SAME dummy-or-real bearer a real dispatch sends (byte-identical
+        // to doctor.ts's own OLLAMA_BASE_URL reachability probe), or this probe
+        // fails closed (401 -> null) even when a real dispatch would succeed.
         const url = ollamaBaseUrl().replace(/\/+$/, "") + "/models";
-        const res = await fetch(url, { signal: controller.signal });
+        const res = await fetch(url, { signal: controller.signal, headers: { authorization: `Bearer ${ollamaApiKey()}` } });
         if (res.status !== 200)
             return null;
         const body = (await res.json());

package/dist/core/tracer.d.ts

@@ -87,7 +87,13 @@ export declare class Tracer {
     sessionStart(adwId: string, engineer: string, adwName?: string | null): Promise<void>;
     sessionRequest(adwId: string, request: string): Promise<void>;
     sessionFinish(adwId: string, ok: boolean): Promise<void>;
-    sessionAddUsage(adwId: string, tokens: number, cost: number): Promise<void>;
+    /**
+     * `tokens`/`cost` are the DISPLAY totals (`total_tokens`, unchanged from
+     * before `billable_tokens` existed); `billableTokens` is the new column —
+     * see `UsageBreakdown.billable_tokens`'s doc comment for what it excludes
+     * and why. Both accumulate in the same row, same as before.
+     */
+    sessionAddUsage(adwId: string, tokens: number, cost: number, billableTokens: number): Promise<void>;
     /**
      * Record a live process for this run.
      *

package/dist/core/tracer.js

@@ -123,6 +123,12 @@ const MIGRATIONS = [
     ["agent_sessions", "context_tokens", "INTEGER"],
     ["agent_sessions", "context_window", "INTEGER"],
     ["sessions", "archived", "INTEGER DEFAULT 0"],
+    // The BILLABLE half of `total_tokens` — see `UsageBreakdown.billable_tokens`'s
+    // own doc comment (`data_types.ts`) for why the two diverge. `total_tokens`
+    // is untouched (still every re-sent token, cache reads included); this is
+    // the new column `sessionAddUsage` also increments, so a trace db from
+    // before this existed just gets a column full of 0 until its next run.
+    ["sessions", "billable_tokens", "INTEGER DEFAULT 0"],
 ];
 export class Tracer {
     db;
@@ -285,10 +291,16 @@ export class Tracer {
         if (processesError)
             throw processesError;
     }
-    async sessionAddUsage(adwId, tokens, cost) {
+    /**
+     * `tokens`/`cost` are the DISPLAY totals (`total_tokens`, unchanged from
+     * before `billable_tokens` existed); `billableTokens` is the new column —
+     * see `UsageBreakdown.billable_tokens`'s doc comment for what it excludes
+     * and why. Both accumulate in the same row, same as before.
+     */
+    async sessionAddUsage(adwId, tokens, cost, billableTokens) {
         await this.db
-            .query("UPDATE sessions SET total_tokens=total_tokens+?, total_cost=total_cost+? WHERE adw_id=?")
-            .run(tokens, cost, adwId);
+            .query("UPDATE sessions SET total_tokens=total_tokens+?, total_cost=total_cost+?, billable_tokens=billable_tokens+? WHERE adw_id=?")
+            .run(tokens, cost, billableTokens, adwId);
     }
     // ── processes (adw_id → pid, so a hung run can be found and killed) ─────
     /**

package/dist/ui/server/db.d.ts

@@ -180,10 +180,17 @@ export interface ChainHistorySession {
     started_at: string | null;
     total_tokens: number;
     total_cost: number;
-    /** In `phases.seq` order; one entry per phase iteration (e.g. `fix_1`, `fix_2`), not yet loop-normalized. */
+    /**
+     * In `phases.seq` order; one entry per phase iteration (e.g. `fix_1`,
+     * `fix_2`), not yet loop-normalized. `tokens` is the display total;
+     * `billable_tokens` is what `spf estimate`'s ceiling projection
+     * (`findCutoffPhase`) actually walks against `defaults.max_run_tokens` —
+     * see that field's own doc comment above for the old-row fallback.
+     */
     phases: {
         name: string;
         seq: number;
         tokens: number;
+        billable_tokens: number;
     }[];
 }

package/dist/ui/server/db.js

@@ -237,7 +237,7 @@ export class SfDb {
         const rows = await this.db
             .query(`SELECT adw_id, ${await this.optionalColumn("sessions", "adw_name")}, request,
                 status, engineer, started_at, ended_at,
-                total_tokens, total_cost,
+                total_tokens, total_cost, ${await this.optionalColumn("sessions", "billable_tokens")},
                 ${await this.optionalColumn("sessions", "archived")}
            FROM sessions
           WHERE COALESCE(${(await this.hasColumn("sessions", "archived")) ? "archived" : "0"}, 0) = 0
@@ -282,7 +282,7 @@ export class SfDb {
         return ((await this.db
             .query(`SELECT adw_id, ${await this.optionalColumn("sessions", "adw_name")}, request,
                   status, engineer, started_at, ended_at,
-                  total_tokens, total_cost
+                  total_tokens, total_cost, ${await this.optionalColumn("sessions", "billable_tokens")}
              FROM sessions WHERE adw_id = ?`)
             .get(adwId)) ?? null);
     }
@@ -497,7 +497,7 @@ export class SfDb {
         const phaseRows = await this.chunked(ids, (chunk) => {
             const placeholders = chunk.map(() => "?").join(", ");
             return this.db
-                .query(`SELECT p.adw_id, p.name, p.seq, e.tokens
+                .query(`SELECT p.adw_id, p.name, p.seq, e.tokens, e.payload_json
              FROM phases p LEFT JOIN events e ON e.phase_id = p.phase_id AND e.type = 'agent_end'
             WHERE p.adw_id IN (${placeholders})
             ORDER BY p.seq ASC`)
@@ -506,7 +506,24 @@ export class SfDb {
         const phasesByAdw = new Map();
         for (const row of phaseRows) {
             const list = phasesByAdw.get(row.adw_id);
-            const entry = { name: row.name, seq: row.seq, tokens: row.tokens ?? 0 };
+            const totalTokens = row.tokens ?? 0;
+            // Derived from the payload, same "parse it in JS" approach `usage()`
+            // above already uses (never a stored column) — so a phase from before
+            // `billable_tokens` existed just falls back to the total, exactly
+            // like `Session.billable_tokens`'s own doc comment (`ui/shared/types.ts`)
+            // describes for the session-level number.
+            let billableTokens = totalTokens;
+            if (row.payload_json) {
+                try {
+                    const usage = JSON.parse(row.payload_json).usage;
+                    if (usage && typeof usage.billable_tokens === "number")
+                        billableTokens = usage.billable_tokens;
+                }
+                catch {
+                    /* a payload written by an older tracer simply falls back to the total */
+                }
+            }
+            const entry = { name: row.name, seq: row.seq, tokens: totalTokens, billable_tokens: billableTokens };
             if (list)
                 list.push(entry);
             else

package/dist/ui/server/serve.d.ts

@@ -7,6 +7,13 @@ export interface UiOptions {
     webDir: string;
     /** Explicit port. Omit to try the default and probe upward on collision. */
     port?: number;
+    /**
+     * Bind address. Omit for the safe default (`127.0.0.1`, loopback-only).
+     * Set explicitly (e.g. `"0.0.0.0"`, or a specific interface IP) to make
+     * this reachable off-box — a deliberate widening, not something a caller
+     * should ever get by accident. See the module doc comment above.
+     */
+    host?: string;
     open?: boolean;
 }
 export interface UiHandle {

package/dist/ui/server/serve.js

@@ -2,9 +2,11 @@
  * `spf ui` bootstrap: bind the app to a real port, print the URL, optionally
  * open a browser, and shut down cleanly on SIGINT/SIGTERM.
  *
- * Binds loopback-only (127.0.0.1) deliberately — this server can flip a
- * database column and reveal agent prompts, and a companion CLI has no
- * reason to listen on every interface.
+ * Binds loopback-only (127.0.0.1) by DEFAULT, deliberately — this server can
+ * flip a database column and reveal agent prompts, and a companion CLI has
+ * no reason to listen on every interface unless someone explicitly asks for
+ * it via `options.host` (`--host` on the CLI). Widening the bind is an
+ * opt-in the caller states on purpose, not a default — see issue #90.
  */
 import { spawn } from "node:child_process";
 import { serve } from "@hono/node-server";
@@ -15,9 +17,9 @@ const PORT_PROBE_ATTEMPTS = 10;
 function isAddrInUse(error) {
     return typeof error === "object" && error !== null && error.code === "EADDRINUSE";
 }
-function listen(app, port) {
+function listen(app, port, hostname) {
     return new Promise((resolvePromise, reject) => {
-        const server = serve({ fetch: app.fetch, port, hostname: "127.0.0.1" }, () => resolvePromise(server));
+        const server = serve({ fetch: app.fetch, port, hostname }, () => resolvePromise(server));
         server.on("error", reject);
     });
 }
@@ -37,6 +39,7 @@ function openUrl(url) {
 export async function runUi(options) {
     const db = await SfDb.open(options.db, options.sessionsDir);
     const app = createApp(db, options.webDir);
+    const host = options.host ?? "127.0.0.1";
     const explicit = options.port !== undefined;
     const startPort = options.port ?? DEFAULT_PORT;
     let server;
@@ -45,7 +48,7 @@ export async function runUi(options) {
     for (let i = 0; i < attempts; i++) {
         port = startPort + i;
         try {
-            server = await listen(app, port);
+            server = await listen(app, port, host);
             break;
         }
         catch (error) {
@@ -61,7 +64,7 @@ export async function runUi(options) {
     }
     const info = server.address();
     const boundPort = info?.port ?? port;
-    const url = `http://127.0.0.1:${boundPort}`;
+    const url = `http://${host}:${boundPort}`;
     const shouldOpen = options.open !== false && process.stdout.isTTY && !process.env.CI && !process.env.SSH_CONNECTION;
     if (shouldOpen)
         openUrl(url);

package/dist/ui/shared/types.d.ts

@@ -24,6 +24,22 @@ export interface Session {
     ended_at: string | null;
     total_tokens: number | null;
     total_cost: number | null;
+    /**
+     * The BILLABLE half of `total_tokens` — see `UsageBreakdown.billable_tokens`'s
+     * doc comment (`core/data_types.ts`) for why the two diverge.
+     *
+     * Two ways a row can predate real tracking, both meaning "fall back to
+     * `total_tokens`" (see `cli/commands/loop.ts`'s readback):
+     *  - `null`: this db has never run the migration that adds the column at
+     *    all (`optionalColumn` in `db.ts` substitutes `NULL AS billable_tokens`
+     *    against it) — only possible for a db a writer Tracer has never opened
+     *    since this column shipped.
+     *  - `0` while `total_tokens > 0`: the column exists (a Tracer's
+     *    `ALTER TABLE ... DEFAULT 0` ran) but this SPECIFIC row was written
+     *    before that, so it was backfilled to 0 rather than to the true
+     *    (unknowable, after the fact) billable figure.
+     */
+    billable_tokens: number | null;
     /** 1 once archived out of the review list. Review state, not run state. */
     archived: number | null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",