@proagentstore/cli 0.4.31 → 0.4.33

package/dist/browser-runner/coding/engine-auth.js

@@ -0,0 +1,55 @@
+// What credential the engine process ACTUALLY got — read off the merged env, on the machine
+// where the merge happens (#248).
+//
+// The platform decides an engine's sign-in MODE (auto / machine / subscription / api-key) in the
+// cloud, but the mode is only half an answer: the runner spawns the CLI with
+// `{...process.env, ...overlay}`, so the outcome also depends on what the user's shell exports —
+// which the cloud cannot see. "Which credential am I actually billing?" was therefore
+// unanswerable from any surface, and the one time it went wrong it went wrong SILENTLY: a shell
+// `ANTHROPIC_API_KEY` beat the injected subscription token, so picking "subscription" billed per
+// token anyway (see the note on `mergeEnv`).
+//
+// This module derives the answer from the same env the process is spawned with, so the report is
+// an observation, never a restatement of the setting.
+//
+// **Presence only, never values.** Nothing here returns, logs or echoes a key or token — the
+// caller gets an enum. This is a transparency feature, not a credential channel.
+/**
+ * The env var each engine reads a PER-TOKEN API key from. Deliberately duplicated from the
+ * cloud's `ENGINE_API_KEYS` (workers/api/src/lib/coding-engines.ts) rather than imported: the
+ * runner ships inside the published CLI and does not depend on the API worker — vendoring is the
+ * house rule for shared constants across packages.
+ */
+const API_KEY_ENV = {
+    claude: "ANTHROPIC_API_KEY",
+    gemini: "GEMINI_API_KEY",
+    codex: "OPENAI_API_KEY",
+    grok: "XAI_API_KEY",
+};
+/**
+ * The env var holding a SUBSCRIPTION token. Only Claude Code has one — for every other engine
+ * "subscription" and "machine" both mean the machine's own login, so there is nothing to detect.
+ */
+const SUBSCRIPTION_ENV = {
+    claude: "CLAUDE_CODE_OAUTH_TOKEN",
+};
+/** A var counts as set only when it holds something. `mergeEnv` deletes on empty, but an
+ *  inherited `FOO=` from the shell is present-and-empty and means "no credential", not one. */
+function has(env, name) {
+    return !!name && !!env[name] && env[name].trim() !== "";
+}
+/**
+ * Derive what the engine actually authenticates with from its merged spawn env.
+ *
+ * API key wins over the subscription token because that is what the CLI itself does — Claude Code
+ * prefers `ANTHROPIC_API_KEY` over `CLAUDE_CODE_OAUTH_TOKEN`. Reporting "subscription" whenever a
+ * token happened to be present would reproduce the exact illusion this exists to dispel: the
+ * setting said subscription, the bill said per-token.
+ */
+export function resolveEngineAuth(clientType, env) {
+    if (has(env, API_KEY_ENV[clientType]))
+        return "api-key";
+    if (has(env, SUBSCRIPTION_ENV[clientType]))
+        return "subscription";
+    return "machine-login";
+}

package/dist/browser-runner/coding/engine-usage.js

@@ -0,0 +1,79 @@
+/**
+ * Engine spend, taken from the CLI's OWN report (#267).
+ *
+ * The usage ledger is written at three cloud-side choke points (`runUserWorkersAi`,
+ * `recordVoiceUsage`, `recordPlatformUsage`). The coding Engine passes through none of them: it
+ * is a child process on the user's machine talking straight to Anthropic. So the single largest
+ * line item for anyone using Coder in earnest was recorded nowhere, and the Usage page showed a
+ * total with no hint that it was incomplete.
+ *
+ * Claude Code already emits everything needed on the `result` event that ends each turn — token
+ * counts AND `total_cost_usd`, which it computes itself. That number is the one figure in the
+ * whole ledger that is NOT an estimate, so it is carried through as reported rather than being
+ * re-derived from `ai-pricing.ts` list prices.
+ *
+ * Raw (non-Claude) engines never reach this module: `HeadlessSession` only parses JSON in
+ * stream-json mode, so a Codex/Grok session produces no records at all. That is deliberate —
+ * a zero row would read as "this engine is free", which is a worse lie than a gap.
+ */
+const num = (v) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+};
+/**
+ * Pick the model id out of Claude Code's `modelUsage` map, which is keyed by model.
+ *
+ * A single turn can legitimately span more than one model (a subagent on a cheaper one), and the
+ * ledger has one model column per row. The most expensive one is the honest label for the row:
+ * attributing the turn to the cheap helper model would make an expensive session look cheap in
+ * the by-model breakdown, which is the exact question that breakdown exists to answer.
+ */
+function pickModel(modelUsage) {
+    if (!modelUsage || typeof modelUsage !== "object")
+        return "unknown";
+    let best = "";
+    let bestCost = -1;
+    for (const [model, entry] of Object.entries(modelUsage)) {
+        const cost = num(entry?.costUSD);
+        if (cost > bestCost) {
+            bestCost = cost;
+            best = model;
+        }
+    }
+    return best || "unknown";
+}
+/**
+ * Turn a stream-json `result` event into a usage record, or null when it carries no measurement.
+ *
+ * `fallbackId` is used only when the event has no `uuid` of its own (older Claude Code builds);
+ * the caller supplies something unique per turn per process.
+ *
+ * Returns null — never a zeroed record — when there is nothing to report, for the same reason
+ * raw engines record nothing: an all-zero row is indistinguishable from "this was free".
+ */
+export function parseEngineUsage(ev, fallbackId) {
+    if (!ev || typeof ev !== "object")
+        return null;
+    const e = ev;
+    if (e.type !== "result")
+        return null;
+    const usage = (e.usage && typeof e.usage === "object" ? e.usage : {});
+    const inputTokens = num(usage.input_tokens);
+    const outputTokens = num(usage.output_tokens);
+    const cacheReadTokens = num(usage.cache_read_input_tokens);
+    const cacheWriteTokens = num(usage.cache_creation_input_tokens);
+    const costUsd = num(e.total_cost_usd);
+    if (!inputTokens && !outputTokens && !cacheReadTokens && !cacheWriteTokens && !costUsd)
+        return null;
+    const uuid = typeof e.uuid === "string" && e.uuid.trim() ? e.uuid.trim() : "";
+    return {
+        id: uuid || fallbackId,
+        model: pickModel(e.modelUsage),
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        costUsd,
+        at: new Date().toISOString(),
+    };
+}

package/dist/browser-runner/coding/headless.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { parseEngineUsage } from "./engine-usage.js";
 /**
  * Merge the platform's resolved engine env over the machine's, where an EMPTY value means
  * REMOVE rather than "set to empty".
@@ -22,6 +23,16 @@ export function mergeEnv(base, overlay) {
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { handlerFor } from "./handlers.js";
+import { resolveEngineAuth } from "./engine-auth.js";
+/**
+ * How many un-drained usage records a session holds (#267).
+ *
+ * Records are drained by the cloud on capture, which polls every 3s while a session is watched,
+ * so this only fills when nobody is looking. Dropping the OLDEST past the cap is the right
+ * direction: an unbounded queue on a long-running runner is a leak, and the alternative
+ * (refusing new records) would lose the turns that just happened rather than ancient ones.
+ */
+const MAX_PENDING_USAGE = 200;
 export class HeadlessSession {
     config;
     /**
@@ -53,6 +64,19 @@ export class HeadlessSession {
     turnStartedAt = 0;
     /** Set by stop() — the only thing that ends a one-shot session (see `alive`). */
     stopped = false;
+    /** Measured engine spend not yet handed to the cloud (#267). Drained by {@link takeUsage}. */
+    pendingUsage = [];
+    /** Turn counter — only used to build a fallback id when the CLI's event has no `uuid`. */
+    usageSeq = 0;
+    /**
+     * Per-PROCESS salt for that fallback id.
+     *
+     * Without it, a runner restart resets `usageSeq` and the new session's first turn reuses the
+     * id of a turn from before the restart — which the cloud's conflict-ignoring insert would
+     * silently drop, undercounting exactly the long-lived sessions this feature exists to measure.
+     * The queue is in memory and dies with the process, so a salt can never cause a double-count.
+     */
+    usageRunId = Math.random().toString(36).slice(2, 10);
     /**
      * The engine binary could not be spawned (ENOENT, not executable).
      *
@@ -62,6 +86,24 @@ export class HeadlessSession {
      * all 40 BYOK decisions re-spawning a binary that isn't there.
      */
     spawnFailed = false;
+    /**
+     * What this engine IS, so the question is answerable instead of implied (#248, #247).
+     *
+     * Sessions have not used tmux since the move to stream-json, but the surface kept saying
+     * `tmuxSession`/`pagsTmuxTotal` long enough that a user's reasonable next move
+     * (`tmux attach -t …`) failed and looked like a broken engine. Stating the runtime beats
+     * removing the wrong word and leaving nothing in its place.
+     */
+    engineRuntime = "child-process";
+    /**
+     * The credential this engine actually runs on — computed from the SAME expression `spawn`
+     * uses, so it reports what happened rather than what was configured (#248). A getter, not a
+     * cached field, because it must never drift from the env the next turn is spawned with.
+     * Presence only: no key or token value leaves this class.
+     */
+    get authResolved() {
+        return resolveEngineAuth(this.config.clientType, mergeEnv(process.env, this.config.env));
+    }
     constructor(config) {
         this.config = config;
         this.engineLabel = `${config.clientType}:${config.id}`;
@@ -423,11 +465,21 @@ export class HeadlessSession {
                         this.push(`  ↳ ${toolResult(block.content)}`); // ↳
                 }
                 break;
-            case "result":
+            case "result": {
                 if (ev.is_error)
                     this.push(`[error] ${ev.result ?? ev.subtype ?? "failed"}`);
+                // The same event that ends the turn also reports what the turn COST (#267). It was
+                // parsed and thrown away, which is why Engine spend was absent from the ledger.
+                // An errored turn still burned tokens, so this is recorded regardless of is_error.
+                const usage = parseEngineUsage(ev, `${this.config.id}:${this.usageRunId}:${this.usageSeq++}`);
+                if (usage) {
+                    this.pendingUsage.push(usage);
+                    if (this.pendingUsage.length > MAX_PENDING_USAGE)
+                        this.pendingUsage.shift();
+                }
                 this.run = "idle"; // the turn is OVER — a fact, not a guess
                 break;
+            }
             default:
                 break;
         }
@@ -438,6 +490,21 @@ export class HeadlessSession {
     push(line) {
         this.transcript.push(line);
     }
+    /**
+     * Hand over the measured spend since the last drain, and forget it (#267).
+     *
+     * Draining rather than re-reporting keeps a 3s capture poll from re-sending the same rows
+     * forever; the cloud's insert is keyed on {@link EngineUsageRecord.id} and ignores conflicts,
+     * so the genuine race — two callers draining at once, or a retry — still cannot double-count.
+     *
+     * A raw engine returns an empty array here, always: nothing parses its stdout for usage, so
+     * there is nothing to hand over and the cloud writes no row for it.
+     */
+    takeUsage() {
+        const out = this.pendingUsage;
+        this.pendingUsage = [];
+        return out;
+    }
 }
 /** Local wall-clock "HH:MM:SS" for transcript timestamps (runner is a Node process). */
 function stamp() {

package/dist/browser-runner/coding/runtime.js

@@ -86,8 +86,13 @@ export class CodingRuntime {
         session.start();
         return this.snapshot(input.sessionId);
     }
-    /** The pane the brain reasons over + the inferred run state. */
-    snapshot(sessionId) {
+    /**
+     * The pane the brain reasons over + the inferred run state.
+     *
+     * `drainUsage` is opt-in because draining is destructive: nine cloud call sites hit
+     * `/coding/capture` and only the two that actually write the ledger may consume the records.
+     */
+    snapshot(sessionId, opts = {}) {
         const session = this.require(sessionId);
         const alive = session.alive;
         // ALWAYS return the transcript — it holds the produced output AND the
@@ -101,6 +106,11 @@ export class CodingRuntime {
             alive,
             ready: alive ? session.ready : false,
             runState: alive ? session.runState() : "idle",
+            // Reported even when the process is not alive: "what would this session bill?" is
+            // exactly the question asked about a session that just stopped.
+            authResolved: session.authResolved,
+            engineRuntime: session.engineRuntime,
+            ...(opts.drainUsage ? { usage: session.takeUsage() } : {}),
         };
     }
     /** Perform one action, then return the fresh snapshot (non-blocking, like browser act). */
@@ -122,14 +132,23 @@ export class CodingRuntime {
         return this.snapshot(sessionId);
     }
     /** Tear down a session. */
+    /**
+     * Stop and forget a session.
+     *
+     * Returns any un-drained spend (#267) rather than discarding it with the session: the last
+     * turn of a session very often runs after the final capture poll, and ending is where that
+     * record would otherwise be lost — silently, and only for the turns at the end of every
+     * session, which is a bias rather than noise.
+     */
     end(sessionId) {
         const session = this.sessions.get(sessionId);
+        const usage = session ? session.takeUsage() : [];
         if (session) {
             session.stop();
             this.sessions.delete(sessionId);
         }
         this.takeovers.delete(sessionId);
-        return { ok: true };
+        return { ok: true, usage };
     }
     list() {
         return [...this.sessions.entries()].map(([sessionId, s]) => ({
@@ -150,6 +169,8 @@ export class CodingRuntime {
             clientType: s.config.clientType,
             workDir: s.config.workDir,
             takeover: this.takeovers.has(sessionId),
+            authResolved: s.authResolved,
+            engineRuntime: s.engineRuntime,
         }));
     }
     // ── Human takeover (the "stuck" handoff) ────────────────────────────────

package/dist/browser-runner/index.js

@@ -2,6 +2,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { startRunnerServer } from "./server.js";
+import { randomUUID } from "node:crypto";
 // Resilience: a stray error in any runtime must NOT take the whole runner down —
 // that drops the tunnel and forces the user to restart `pags up` (and lose their
 // session). Log it and keep serving. Per-component handlers catch most things;
@@ -29,7 +30,11 @@ function configFromArgs() {
         host: arg("--host", process.env.PAGS_RUNNER_HOST || "127.0.0.1") || "127.0.0.1",
         port: Number(arg("--port", process.env.PAGS_RUNNER_PORT || "49171")),
         dataDir,
-        token: arg("--token", process.env.PAGS_RUNNER_TOKEN),
+        // Never start unauthenticated (#245). This surface drives a coding CLI with permissions
+        // skipped, and `authorize` now fails closed — so a missing token would make the runner
+        // answer nothing rather than answer everyone. Generate one and print it, mirroring what
+        // `pags runner connect` has always done.
+        token: arg("--token", process.env.PAGS_RUNNER_TOKEN) || `pags_runner_${randomUUID()}`,
         instanceId: arg("--instance-id", process.env.PAGS_INSTANCE_ID),
         headless: flag("--headless") || process.env.PAGS_RUNNER_HEADLESS === "1",
     };

package/dist/browser-runner/server.js

@@ -147,8 +147,11 @@ async function route(runner, req, res) {
         return json(res, 200, runner.coding.start(b));
     }
     if (req.method === "POST" && path === "/coding/capture") {
+        // `drainUsage` opts this caller in to consuming the session's measured engine spend (#267).
+        // Only the cloud paths that write the ledger send it; an older cloud omits it and simply
+        // gets the snapshot it always got.
         const b = await readJson(req);
-        return json(res, 200, runner.coding.snapshot(b.sessionId));
+        return json(res, 200, runner.coding.snapshot(b.sessionId, { drainUsage: b.drainUsage === true }));
     }
     if (req.method === "POST" && path === "/coding/act") {
         const b = await readJson(req);
@@ -391,13 +394,35 @@ async function route(runner, req, res) {
     }
     return json(res, 404, { error: "Not found" });
 }
+/**
+ * Authorize a request to the local runner (#245).
+ *
+ * This surface drives a coding CLI that `pags up` launches with
+ * `--dangerously-skip-permissions` / `--sandbox danger-full-access`, so "who may POST here" is
+ * the whole security boundary. Two things were the wrong way round:
+ *
+ * 1. **No token used to mean ALLOW.** `pags up` always generates one, so that path was safe —
+ *    but `pags-browser-runner` run directly (its own --help documents this) passes
+ *    `token: undefined`, and served the entire surface unauthenticated. Now it fails CLOSED;
+ *    the standalone entrypoint generates a token instead of starting open.
+ *
+ * 2. **A browser could reach it.** Binding to loopback is not isolation: a page the user is
+ *    visiting cannot READ a cross-origin response, but it can still SEND the POST, and the
+ *    server sets no CORS headers and did no Origin check. The token already made that
+ *    unguessable — but nothing legitimate that calls this runner is a browser (the cloud
+ *    dispatches over the relay; the CLI calls it directly), and neither sends `Origin`. So the
+ *    presence of that header is by itself proof the caller is a web page, and is refused before
+ *    the token is even considered. Also closes DNS-rebinding, which loopback does not.
+ */
 function authorize(req, config) {
+    if (req.headers.origin)
+        return false;
     const token = config.token;
     if (config.instanceId && req.headers["x-pags-instance-id"] !== config.instanceId) {
         return false;
     }
     if (!token)
-        return true;
+        return false;
     const auth = req.headers.authorization || "";
     const headerToken = req.headers["x-pags-runner-token"];
     return auth === `Bearer ${token}` || headerToken === token;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proagentstore/cli",
-  "version": "0.4.31",
+  "version": "0.4.33",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",