@twzrd1111/agent-killswitch 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# Agent Spend Kill-Switch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A drop-in local reverse proxy that sits in front of any OpenAI-compatible
+`/v1/chat/completions` endpoint. It enforces hard token/cost budgets, gives
+you an instant file-based kill switch, and writes every decision to an
+append-only JSONL ledger.
+
+Point any OpenAI client at it by changing one variable — `OPENAI_BASE_URL` —
+and a runaway agent can never silently burn more than you allow.
+
+## 5-minute setup (Docker)
+
+```sh
+# 1. Configure (or just use env vars)
+cp config.example.yaml config.yaml
+
+# 2. Run — the only secret is your upstream key
+docker build -t agent-killswitch .
+docker run -d --name killswitch \
+  -p 127.0.0.1:4020:4020 \
+  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
+  -v "$PWD/config.yaml:/app/config.yaml:ro" \
+  -v "$PWD/data:/app/data" \
+  agent-killswitch
+
+# 3. Point any OpenAI client at it
+export OPENAI_BASE_URL="http://127.0.0.1:4020/v1"
+```
+
+Works with LangChain, AutoGen, CrewAI, Vercel AI SDK, Cursor, and anything
+else that speaks `/v1/chat/completions` — streaming included.
+
+## The kill switch
+
+```sh
+# Stop all spend immediately (no upstream call is made after this)
+touch ./.kill          # or: curl -X POST http://127.0.0.1:4020/kill
+
+# Resume
+rm ./.kill             # or: curl -X POST http://127.0.0.1:4020/reset
+```
+
+A vetoed request returns an OpenAI-shaped error so frameworks handle it
+gracefully (HTTP 403 for the kill switch, 429 for budgets):
+
+```json
+{"error": {"type": "killswitch_veto", "code": "budget_exceeded",
+  "message": "Hourly limit $5.00 hit", "spent_usd": 5.12, "limit_usd": 5.0}}
+```
+
+## Configuration
+
+YAML file plus env overrides (env wins). Copy `config.example.yaml` to
+`config.yaml` and edit the limits:
+
+| Env var | YAML key | Default |
+|---|---|---|
+| `KILLSWITCH_CONFIG` | — (config path) | `./config.yaml` |
+| `KILLSWITCH_UPSTREAM_BASE_URL` | `upstream.base_url` | `https://api.openai.com/v1` |
+| `KILLSWITCH_API_KEY_ENV` | `upstream.api_key_env` | `OPENAI_API_KEY` |
+| `KILLSWITCH_MAX_TOKENS_MINUTE` | `limits.max_tokens_per_minute` | `100000` |
+| `KILLSWITCH_MAX_USD_HOUR` | `limits.max_usd_per_hour` | `5.00` |
+| `KILLSWITCH_MAX_USD_DAY` | `limits.max_usd_per_day` | `25.00` |
+| `KILLSWITCH_MAX_COST_REQUEST` | `limits.max_cost_per_request_usd` | `0.50` |
+| `KILLSWITCH_KILL_FILE` | `kill_switch.file_path` | `./.kill` |
+| `KILLSWITCH_KILL_API` | `kill_switch.enable_api_endpoint` | `true` |
+| `KILLSWITCH_LEDGER_PATH` | `logging.path` | `./data/spend-ledger.jsonl` |
+| `KILLSWITCH_PORT` / `PORT` | `server.port` | `4020` |
+
+Every decision — allowed or vetoed — appends one line to the JSONL ledger
+with timestamp, model, token counts, `cost_usd`, `allowed`, `veto_reason`,
+and `request_id`. Restart replays the last 48 h to rebuild the spend
+windows; the ledger file is the source of truth.
+
+## Pricing notes
+
+Costs use a static per-model table (`src/pricing.ts`, checked against
+OpenAI's published prices). There are no live pricing fetches by design.
+An **unknown model is billed at the most expensive known rate** rather than
+rejected — failing closed on cost beats failing open, and the ledger shows
+exactly what was assumed.
+
+## What it is not (v0.1 scope)
+
+OpenAI chat completions only. No Anthropic, no embeddings/images, no
+tokenizer, no multi-upstream or key rotation, no dashboard, no Redis/SQLite.
+
+## Paid support
+
+This is a local binary with no SaaS backend. Annual support (priority fixes,
+custom limits/policies, audit-export help) is available — open an issue on
+the repo with your use case and team size.

package/config.example.yaml

@@ -0,0 +1,23 @@
+upstream:
+  base_url: "https://api.openai.com/v1"
+  # Name of the env var holding the upstream API key. The key itself is
+  # never stored in this file.
+  api_key_env: "OPENAI_API_KEY"
+
+limits:
+  max_tokens_per_minute: 100000
+  max_usd_per_hour: 5.00
+  max_usd_per_day: 25.00
+  max_cost_per_request_usd: 0.50
+
+kill_switch:
+  # When this file exists, every chat-completion request is vetoed
+  # immediately without contacting upstream. `touch ./.kill` to stop.
+  file_path: "./.kill"
+  enable_api_endpoint: true
+
+logging:
+  path: "./data/spend-ledger.jsonl"
+
+server:
+  port: 4020

package/dist/config.js

@@ -0,0 +1,40 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import yaml from "js-yaml";
+function num(env, fallback) {
+    if (env === undefined || env === "")
+        return fallback;
+    const v = Number(env);
+    if (!Number.isFinite(v) || v < 0)
+        throw new Error(`Invalid numeric env value: ${env}`);
+    return v;
+}
+function str(env, fallback) {
+    return env === undefined || env === "" ? fallback : env;
+}
+/** Load YAML config, then apply env overrides. Throws on missing API key. */
+export function loadConfig(configPath) {
+    let raw = {};
+    if (fs.existsSync(configPath)) {
+        raw = (yaml.load(fs.readFileSync(configPath, "utf8")) ?? {});
+    }
+    const apiKeyEnv = str(process.env.KILLSWITCH_API_KEY_ENV, raw.upstream?.api_key_env ?? "OPENAI_API_KEY");
+    const apiKey = process.env[apiKeyEnv] ?? "";
+    if (!apiKey) {
+        throw new Error(`Upstream API key missing: set ${apiKeyEnv}`);
+    }
+    return {
+        upstreamBaseUrl: str(process.env.KILLSWITCH_UPSTREAM_BASE_URL, raw.upstream?.base_url ?? "https://api.openai.com/v1").replace(/\/+$/, ""),
+        apiKey,
+        maxTokensPerMinute: num(process.env.KILLSWITCH_MAX_TOKENS_MINUTE, raw.limits?.max_tokens_per_minute ?? 100000),
+        maxUsdPerHour: num(process.env.KILLSWITCH_MAX_USD_HOUR, raw.limits?.max_usd_per_hour ?? 5.0),
+        maxUsdPerDay: num(process.env.KILLSWITCH_MAX_USD_DAY, raw.limits?.max_usd_per_day ?? 25.0),
+        maxCostPerRequestUsd: num(process.env.KILLSWITCH_MAX_COST_REQUEST, raw.limits?.max_cost_per_request_usd ?? 0.5),
+        killFilePath: path.resolve(str(process.env.KILLSWITCH_KILL_FILE, raw.kill_switch?.file_path ?? "./.kill")),
+        enableKillApi: process.env.KILLSWITCH_KILL_API !== undefined
+            ? process.env.KILLSWITCH_KILL_API === "1" || process.env.KILLSWITCH_KILL_API === "true"
+            : (raw.kill_switch?.enable_api_endpoint ?? true),
+        ledgerPath: path.resolve(str(process.env.KILLSWITCH_LEDGER_PATH, raw.logging?.path ?? "./data/spend-ledger.jsonl")),
+        port: Math.floor(num(process.env.KILLSWITCH_PORT ?? process.env.PORT, raw.server?.port ?? 4020)),
+    };
+}

package/dist/gate.js

@@ -0,0 +1,111 @@
+import * as fs from "node:fs";
+import { pessimisticRequestCostUsd } from "./pricing.js";
+/** Instant kill switch: the mere existence of the file vetoes everything. */
+export function checkKillSwitch(filePath) {
+    try {
+        return fs.existsSync(filePath);
+    }
+    catch {
+        // If we cannot even stat the file, fail closed.
+        return true;
+    }
+}
+/** Pure pre-call budget evaluator. No I/O, no tokenizer. */
+export function evaluateGate(input) {
+    if (input.killed) {
+        return {
+            allowed: false,
+            status: 403,
+            code: "kill_switch",
+            message: "Kill switch engaged",
+            spentUsd: input.window.hourUsd,
+            limitUsd: input.maxUsdPerHour,
+        };
+    }
+    // Token velocity gate: recorded tokens in the last 60 s plus this
+    // request's max_tokens as a stand-in for its eventual size.
+    const estTokens = input.maxTokens ?? 0;
+    if (input.window.minuteTokens + estTokens > input.maxTokensPerMinute) {
+        return {
+            allowed: false,
+            status: 429,
+            code: "budget_exceeded",
+            message: `Token-per-minute limit ${input.maxTokensPerMinute} would be exceeded`,
+            spentUsd: input.window.minuteTokens,
+            limitUsd: input.maxTokensPerMinute,
+        };
+    }
+    // Pessimistic cost gate: assume every requested max_token bills at the
+    // output rate. Requests without max_tokens skip this check and are metered
+    // on actual usage instead.
+    if (input.maxTokens !== null) {
+        const pessimistic = pessimisticRequestCostUsd(input.model, input.maxTokens);
+        if (pessimistic > input.maxCostPerRequestUsd) {
+            return {
+                allowed: false,
+                status: 429,
+                code: "per_request_cap",
+                message: `Request could cost $${pessimistic.toFixed(4)}, over the per-request cap $${input.maxCostPerRequestUsd.toFixed(2)}`,
+                spentUsd: pessimistic,
+                limitUsd: input.maxCostPerRequestUsd,
+            };
+        }
+        if (input.window.hourUsd + pessimistic > input.maxUsdPerHour) {
+            return {
+                allowed: false,
+                status: 429,
+                code: "budget_exceeded",
+                message: `Hourly limit $${input.maxUsdPerHour.toFixed(2)} would be exceeded`,
+                spentUsd: input.window.hourUsd,
+                limitUsd: input.maxUsdPerHour,
+            };
+        }
+        if (input.window.dayUsd + pessimistic > input.maxUsdPerDay) {
+            return {
+                allowed: false,
+                status: 429,
+                code: "budget_exceeded",
+                message: `Daily limit $${input.maxUsdPerDay.toFixed(2)} would be exceeded`,
+                spentUsd: input.window.dayUsd,
+                limitUsd: input.maxUsdPerDay,
+            };
+        }
+    }
+    // Hard caps apply even without max_tokens: an already-blown window vetoes.
+    if (input.window.hourUsd >= input.maxUsdPerHour) {
+        return {
+            allowed: false,
+            status: 429,
+            code: "budget_exceeded",
+            message: `Hourly limit $${input.maxUsdPerHour.toFixed(2)} hit`,
+            spentUsd: input.window.hourUsd,
+            limitUsd: input.maxUsdPerHour,
+        };
+    }
+    if (input.window.dayUsd >= input.maxUsdPerDay) {
+        return {
+            allowed: false,
+            status: 429,
+            code: "budget_exceeded",
+            message: `Daily limit $${input.maxUsdPerDay.toFixed(2)} hit`,
+            spentUsd: input.window.dayUsd,
+            limitUsd: input.maxUsdPerDay,
+        };
+    }
+    return { allowed: true, status: 200, code: null, message: "allowed", spentUsd: 0, limitUsd: 0 };
+}
+/** OpenAI-shaped veto body so agent frameworks handle it like a normal API error. */
+export function vetoBody(decision) {
+    return {
+        error: {
+            type: "killswitch_veto",
+            code: decision.code,
+            message: decision.message,
+            spent_usd: round4(decision.spentUsd),
+            limit_usd: decision.limitUsd,
+        },
+    };
+}
+function round4(n) {
+    return Math.round(n * 10000) / 10000;
+}

package/dist/index.js

@@ -0,0 +1,157 @@
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { loadConfig } from "./config.js";
+import { checkKillSwitch, evaluateGate, vetoBody } from "./gate.js";
+import { Ledger } from "./ledger.js";
+import { costUsd } from "./pricing.js";
+import { forwardChatCompletion } from "./proxy.js";
+const MAX_BODY_BYTES = 10 * 1024 * 1024;
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new Error("body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function json(res, status, obj) {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(obj));
+}
+export function createServer() {
+    const configPath = process.env.KILLSWITCH_CONFIG ?? "./config.yaml";
+    const cfg = loadConfig(configPath);
+    const ledger = new Ledger(cfg.ledgerPath);
+    const replayed = ledger.load();
+    // eslint-disable-next-line no-console
+    console.log(`agent-killswitch: replayed ${replayed} ledger lines from the last 48 h`);
+    return http.createServer((req, res) => {
+        void handle(req, res, cfg, ledger).catch((err) => {
+            // eslint-disable-next-line no-console
+            console.error(`request failed: ${err.message}`);
+            if (!res.headersSent)
+                json(res, 500, { error: { type: "killswitch_error", message: "internal error" } });
+            else {
+                try {
+                    res.end();
+                }
+                catch {
+                    /* already torn down */
+                }
+            }
+        });
+    });
+}
+async function handle(req, res, cfg, ledger) {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (req.method === "GET" && url.pathname === "/healthz") {
+        const w = ledger.window();
+        json(res, 200, {
+            ok: true,
+            killed: checkKillSwitch(cfg.killFilePath),
+            hour_usd: w.hourUsd,
+            day_usd: w.dayUsd,
+        });
+        return;
+    }
+    if (cfg.enableKillApi && req.method === "POST" && url.pathname === "/kill") {
+        fs.mkdirSync(path.dirname(cfg.killFilePath), { recursive: true });
+        fs.writeFileSync(cfg.killFilePath, `${new Date().toISOString()}\n`);
+        json(res, 200, { ok: true, killed: true });
+        return;
+    }
+    if (cfg.enableKillApi && req.method === "POST" && url.pathname === "/reset") {
+        try {
+            fs.unlinkSync(cfg.killFilePath);
+        }
+        catch {
+            /* already absent */
+        }
+        json(res, 200, { ok: true, killed: false });
+        return;
+    }
+    if (req.method !== "POST" || url.pathname !== "/v1/chat/completions") {
+        json(res, 404, { error: { type: "not_found", message: "only POST /v1/chat/completions is proxied" } });
+        return;
+    }
+    const raw = await readBody(req);
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        json(res, 400, { error: { type: "invalid_request", message: "body must be JSON" } });
+        return;
+    }
+    const model = typeof body["model"] === "string" ? body["model"] : "unknown";
+    const maxTokens = typeof body["max_tokens"] === "number" && Number.isFinite(body["max_tokens"])
+        ? Math.floor(body["max_tokens"])
+        : null;
+    const requestId = req.headers["x-request-id"] ??
+        (typeof body["request_id"] === "string" ? body["request_id"] : randomUUID());
+    const now = new Date().toISOString();
+    const decision = evaluateGate({
+        killed: checkKillSwitch(cfg.killFilePath),
+        window: ledger.window(),
+        model,
+        maxTokens,
+        maxTokensPerMinute: cfg.maxTokensPerMinute,
+        maxUsdPerHour: cfg.maxUsdPerHour,
+        maxUsdPerDay: cfg.maxUsdPerDay,
+        maxCostPerRequestUsd: cfg.maxCostPerRequestUsd,
+    });
+    if (!decision.allowed) {
+        ledger.append({
+            timestamp: now,
+            model,
+            prompt_tokens: 0,
+            completion_tokens: 0,
+            total_tokens: 0,
+            cost_usd: 0,
+            allowed: false,
+            veto_reason: decision.code,
+            request_id: requestId,
+        });
+        json(res, decision.status, vetoBody(decision));
+        return;
+    }
+    // Allowed: forward, then meter on the actual usage reported upstream.
+    const result = await forwardChatCompletion(cfg.upstreamBaseUrl, cfg.apiKey, body, res, requestId);
+    if (result.usage) {
+        const u = result.usage;
+        ledger.append({
+            timestamp: now,
+            model,
+            prompt_tokens: u.prompt_tokens,
+            completion_tokens: u.completion_tokens,
+            total_tokens: u.total_tokens,
+            cost_usd: costUsd(model, u.prompt_tokens, u.completion_tokens),
+            allowed: true,
+            veto_reason: null,
+            request_id: requestId,
+        });
+    }
+}
+// CLI entry: `node dist/index.js [config.yaml]`.
+const invokedAsMain = process.argv[1] !== undefined && import.meta.url.endsWith(process.argv[1].split("/").pop() ?? "");
+if (invokedAsMain) {
+    if (process.argv[2])
+        process.env.KILLSWITCH_CONFIG = process.argv[2];
+    const port = Number(process.env.KILLSWITCH_PORT ?? process.env.PORT ?? 4020);
+    const server = createServer();
+    server.listen(port, "127.0.0.1", () => {
+        // eslint-disable-next-line no-console
+        console.log(`agent-killswitch listening on 127.0.0.1:${port}`);
+    });
+}

package/dist/ledger.js

@@ -0,0 +1,82 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+// Lines older than this are ignored on rebuild; the in-memory window only
+// ever needs the last day, with headroom for a long-downtime restart.
+const REPLAY_MS = 48 * 3600 * 1000;
+const RETAIN_MS = 48 * 3600 * 1000;
+/** Append-only JSONL ledger (source of truth) + in-memory sliding windows. */
+export class Ledger {
+    filePath;
+    spends = [];
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    /** Replay the last 48 h of the ledger to rebuild the windows. */
+    load() {
+        this.spends = [];
+        if (!fs.existsSync(this.filePath))
+            return 0;
+        const cutoff = Date.now() - REPLAY_MS;
+        let replayed = 0;
+        const content = fs.readFileSync(this.filePath, "utf8");
+        for (const raw of content.split("\n")) {
+            const line = raw.trim();
+            if (!line)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue; // A torn write must never break startup.
+            }
+            if (!parsed.allowed)
+                continue; // Vetoed calls cost nothing.
+            const atMs = Date.parse(parsed.timestamp);
+            if (!Number.isFinite(atMs) || atMs < cutoff)
+                continue;
+            this.spends.push({
+                atMs,
+                totalTokens: parsed.total_tokens ?? 0,
+                costUsd: parsed.cost_usd ?? 0,
+            });
+            replayed++;
+        }
+        return replayed;
+    }
+    window(nowMs = Date.now()) {
+        let minuteTokens = 0;
+        let hourUsd = 0;
+        let dayUsd = 0;
+        for (const s of this.spends) {
+            const age = nowMs - s.atMs;
+            if (age < 0)
+                continue;
+            if (age < 24 * 3600 * 1000) {
+                dayUsd += s.costUsd;
+                if (age < 3600 * 1000) {
+                    hourUsd += s.costUsd;
+                    if (age < 60 * 1000)
+                        minuteTokens += s.totalTokens;
+                }
+            }
+        }
+        return { minuteTokens, hourUsd, dayUsd };
+    }
+    append(line) {
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        fs.appendFileSync(this.filePath, JSON.stringify(line) + "\n", "utf8");
+        if (line.allowed) {
+            this.spends.push({
+                atMs: Date.parse(line.timestamp),
+                totalTokens: line.total_tokens,
+                costUsd: line.cost_usd,
+            });
+            // Bound memory: drop anything older than the replay horizon.
+            const cutoff = Date.now() - RETAIN_MS;
+            if (this.spends.length > 10000) {
+                this.spends = this.spends.filter((s) => s.atMs >= cutoff);
+            }
+        }
+    }
+}

package/dist/pricing.js

@@ -0,0 +1,37 @@
+// Static per-model prices in USD per 1M tokens. Checked against OpenAI's
+// published pricing 2026-11-07; update this table when OpenAI changes prices.
+// Unknown models are priced as the most expensive known model (fail closed),
+// never as the cheapest. See README for the rationale.
+const PRICES = {
+    "o1": { inputPerMTok: 15.0, outputPerMTok: 60.0 },
+    "gpt-4o": { inputPerMTok: 2.5, outputPerMTok: 10.0 },
+    "gpt-4.1": { inputPerMTok: 2.0, outputPerMTok: 8.0 },
+    "o3-mini": { inputPerMTok: 1.1, outputPerMTok: 4.4 },
+    "gpt-4.1-mini": { inputPerMTok: 0.4, outputPerMTok: 1.6 },
+    "gpt-4o-mini": { inputPerMTok: 0.15, outputPerMTok: 0.6 },
+};
+function mostExpensive() {
+    let top = { inputPerMTok: 0, outputPerMTok: 0 };
+    for (const p of Object.values(PRICES)) {
+        if (p.outputPerMTok > top.outputPerMTok)
+            top = p;
+    }
+    return top;
+}
+export function priceFor(model) {
+    const price = PRICES[model];
+    if (price)
+        return { price, known: true };
+    // Fail closed: an unlisted model could be a pricey reasoning model, so we
+    // assume the worst instead of silently undercounting spend.
+    return { price: mostExpensive(), known: false };
+}
+export function costUsd(model, promptTokens, completionTokens) {
+    const { price } = priceFor(model);
+    return (promptTokens * price.inputPerMTok + completionTokens * price.outputPerMTok) / 1_000_000;
+}
+/** Pessimistic pre-call estimate: the request's max_tokens all billed at the output rate. */
+export function pessimisticRequestCostUsd(model, maxTokens) {
+    const { price } = priceFor(model);
+    return (maxTokens * price.outputPerMTok) / 1_000_000;
+}

package/dist/proxy.js

@@ -0,0 +1,101 @@
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
+}
+/**
+ * Forward a chat-completion body upstream and pipe the response through.
+ * For streams, `stream_options.include_usage` is injected so the terminal
+ * SSE event carries usage; chunks are forwarded byte-for-byte and usage is
+ * extracted only from the final data event. Returns the observed usage
+ * (null when upstream sent none).
+ */
+export async function forwardChatCompletion(upstreamBaseUrl, apiKey, body, clientRes, requestId) {
+    const streaming = body["stream"] === true;
+    const outbound = { ...body };
+    if (streaming) {
+        const opts = { ...outbound["stream_options"] };
+        opts["include_usage"] = true;
+        outbound["stream_options"] = opts;
+    }
+    const upstreamRes = await fetch(`${upstreamBaseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${apiKey}`,
+            "x-killswitch-request-id": requestId,
+        },
+        body: JSON.stringify(outbound),
+    });
+    if (!streaming) {
+        const text = await upstreamRes.text();
+        clientRes.writeHead(upstreamRes.status, { "content-type": "application/json" });
+        clientRes.end(text);
+        if (!upstreamRes.ok)
+            return { status: upstreamRes.status, usage: null };
+        try {
+            const parsed = JSON.parse(text);
+            const u = parsed.usage;
+            if (!u)
+                return { status: upstreamRes.status, usage: null };
+            return {
+                status: upstreamRes.status,
+                usage: {
+                    prompt_tokens: num(u.prompt_tokens),
+                    completion_tokens: num(u.completion_tokens),
+                    total_tokens: num(u.total_tokens),
+                },
+            };
+        }
+        catch {
+            return { status: upstreamRes.status, usage: null };
+        }
+    }
+    // Streaming path: pipe SSE events verbatim, watching for the terminal
+    // usage event. The buffer only accumulates the current line, so memory
+    // stays flat regardless of stream length.
+    clientRes.writeHead(upstreamRes.status, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+    });
+    if (!upstreamRes.ok || !upstreamRes.body) {
+        const text = upstreamRes.body ? await upstreamRes.text() : "";
+        clientRes.end(text);
+        return { status: upstreamRes.status, usage: null };
+    }
+    let usage = null;
+    let lineBuf = "";
+    const reader = upstreamRes.body.getReader();
+    const decoder = new TextDecoder();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        clientRes.write(value); // Forward first; extraction never delays the client.
+        lineBuf += decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = lineBuf.indexOf("\n")) >= 0) {
+            const line = lineBuf.slice(0, nl).trim();
+            lineBuf = lineBuf.slice(nl + 1);
+            if (!line.startsWith("data:"))
+                continue;
+            const payload = line.slice(5).trim();
+            if (payload === "[DONE]")
+                continue;
+            try {
+                const evt = JSON.parse(payload);
+                if (evt.usage && (evt.usage.prompt_tokens !== undefined || evt.usage.total_tokens !== undefined)) {
+                    usage = {
+                        prompt_tokens: num(evt.usage.prompt_tokens),
+                        completion_tokens: num(evt.usage.completion_tokens),
+                        total_tokens: num(evt.usage.total_tokens),
+                    };
+                }
+            }
+            catch {
+                // Non-JSON data lines (e.g. keepalives) are forwarded untouched.
+            }
+        }
+    }
+    clientRes.end();
+    return { status: upstreamRes.status, usage };
+}

package/package.json

@@ -1,6 +1 @@
-{
-  "name": "@twzrd1111/agent-killswitch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{"access": "public", "author": "TWZRD", "description": "Drop-in local reverse proxy that enforces hard token/cost budgets on OpenAI-compatible chat completions, with an instant file-based kill switch and an append-only JSONL spend ledger.", "exports": {"./package.json": "./package.json"}, "files": ["dist", "config.example.yaml", "README.md"], "homepage": "https://github.com/twzrd-sol/twzrd-trust#agent-killswitch", "keywords": ["openai", "proxy", "budget", "kill-switch", "cost-control", "agents"], "license": "MIT", "name": "@twzrd1111/agent-killswitch", "repository": {"type": "git", "url": "git+https://github.com/twzrd-sol/twzrd-trust.git"}, "scripts": {"build": "tsc -p .", "ci": "npm run typecheck", "start": "node dist/index.js", "typecheck": "tsc -p . --noEmit"}, "type": "module", "version": "0.1.0", "dependencies": {"js-yaml": "^4.1.0"}, "devDependencies": {"@types/js-yaml": "^4.0.9", "@types/node": "^22.0.0", "typescript": "^5.6.0"}}