@wacry/codeks-bridge 0.0.0-stage → 0.0.3

package/dist/inspect/capture.js

@@ -0,0 +1,370 @@
+// In-memory capture of complete exchanges for the inspector. A capture keeps
+// every byte the bridge received and sent. Only credential header values are
+// redacted; bodies are never filtered.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+const MIB = 1024 * 1024;
+export const DEFAULT_CAPTURE_MIB = 256;
+const scope = new AsyncLocalStorage();
+// Segment match keeps diagnostics such as x-ratelimit-remaining-tokens visible.
+const SENSITIVE = /(^|[-_])(auth|authorization|token|secret|password|passwd|cookie|key|apikey|credential|credentials|signature)([-_]|$)/i;
+function redact(name, value, extra) {
+    if (!extra.has(name) && !SENSITIVE.test(name))
+        return value;
+    const digest = createHash("sha256").update(value).digest("hex").slice(0, 8);
+    return `[redacted: ${value.length} chars, sha256 ${digest}]`;
+}
+/** Lowercase names, join repeated values, and redact credentials. */
+export function headerMap(headers, extra = new Set()) {
+    const result = {};
+    if (!headers)
+        return result;
+    const entries = headers instanceof Headers ? [...headers.entries()] : Object.entries(headers);
+    for (const [rawName, rawValue] of entries) {
+        if (rawValue === undefined)
+            continue;
+        const name = rawName.toLowerCase();
+        const value = Array.isArray(rawValue) ? rawValue.map(String).join(name === "set-cookie" ? "\n" : ", ") : String(rawValue);
+        result[name] = redact(name, value, extra);
+    }
+    return result;
+}
+function byteLength(chunk) {
+    return typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.byteLength;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** One HTTP message after its start line: status, headers, and timed body parts. */
+export class Message {
+    status;
+    statusText;
+    headers;
+    headersMs;
+    endedMs;
+    end = "active";
+    error;
+    parts = [];
+    bytes = 0;
+    decoder = new TextDecoder();
+    exchange;
+    constructor(exchange) { this.exchange = exchange; }
+    head(status, statusText, headers) {
+        if (this.exchange.closed)
+            return;
+        if (this.headersMs === undefined)
+            this.exchange.touch();
+        this.status = status;
+        this.statusText = statusText;
+        this.headers = headers;
+        this.headersMs ??= this.exchange.now();
+    }
+    push(chunk) {
+        if (this.exchange.closed || this.end !== "active")
+            return;
+        const text = typeof chunk === "string" ? chunk : this.decoder.decode(chunk, { stream: true });
+        if (text)
+            this.parts.push({ t: this.exchange.now(), text });
+        const size = byteLength(chunk);
+        this.bytes += size;
+        this.exchange.account(size);
+    }
+    finish(end, error) {
+        if (this.exchange.closed || this.end !== "active")
+            return;
+        const rest = this.decoder.decode();
+        if (rest)
+            this.parts.push({ t: this.exchange.now(), text: rest });
+        this.end = end;
+        if (error !== undefined)
+            this.error = message(error);
+        this.endedMs = this.exchange.now();
+        this.exchange.touch();
+    }
+    text() {
+        return this.parts.map(part => part.text).join("");
+    }
+    discard() {
+        this.parts.length = 0;
+        this.bytes = 0;
+        this.headers = undefined;
+        this.error = undefined;
+        this.decoder.decode();
+    }
+}
+/** One request from the bridge to an upstream. */
+export class Call {
+    index;
+    label;
+    startedMs;
+    method = "POST";
+    url;
+    headers;
+    text;
+    bytes;
+    error;
+    response;
+    exchange;
+    constructor(exchange, label, url, headers, text) {
+        this.exchange = exchange;
+        this.index = exchange.calls.length;
+        this.label = label;
+        this.startedMs = exchange.now();
+        this.url = url;
+        this.headers = headers;
+        this.text = text;
+        this.bytes = Buffer.byteLength(text);
+        exchange.account(this.bytes);
+        exchange.touch();
+    }
+    received(response) {
+        if (this.response || this.exchange.closed)
+            return;
+        this.response = new Message(this.exchange);
+        this.response.head(response.status, response.statusText, headerMap(response.headers));
+    }
+    chunk(value) {
+        this.response?.push(value);
+    }
+    done(end, error) {
+        this.response?.finish(end, error);
+    }
+    failed(error) {
+        if (this.exchange.closed || this.response || this.error !== undefined)
+            return;
+        this.error = message(error);
+        this.exchange.touch();
+    }
+    discard() {
+        this.text = "";
+        this.bytes = 0;
+        for (const name of Object.keys(this.headers))
+            delete this.headers[name];
+        this.error = undefined;
+        this.response?.discard();
+    }
+}
+function previewOf(request) {
+    if (typeof request.input === "string")
+        return request.input.slice(0, 200);
+    if (!Array.isArray(request.input))
+        return null;
+    for (let i = request.input.length - 1; i >= 0; i--) {
+        const item = request.input[i];
+        // A subagent's task arrives as an agent_message item after the inherited user turns.
+        const task = item?.type === "agent_message" || (item?.role === "user" && (item.type === undefined || item.type === "message"));
+        if (!task)
+            continue;
+        const text = typeof item.content === "string" ? item.content
+            : Array.isArray(item.content) ? item.content.filter((part) => typeof part?.text === "string").map((part) => part.text).join(" ") : "";
+        if (text.trim())
+            return text.trim().replace(/\s+/g, " ").slice(0, 200);
+    }
+    return null;
+}
+/** One client request and everything it caused. */
+export class Exchange {
+    id;
+    seq;
+    rev = 0;
+    startedAt = Date.now();
+    durationMs;
+    closed = false;
+    method;
+    path;
+    headers;
+    requestText;
+    requestBytes = 0;
+    meta = { model: null, kind: "invalid", stream: null, input_items: null, preview: null };
+    route;
+    responsesLite;
+    calls = [];
+    response;
+    bytes = 0;
+    inspector;
+    t0 = performance.now();
+    constructor(inspector, seq, req, res) {
+        this.inspector = inspector;
+        this.seq = seq;
+        this.id = `x${seq}`;
+        this.method = req.method ?? "";
+        this.path = req.url ?? "";
+        this.headers = headerMap(req.headers);
+        this.response = new Message(this);
+        this.tap(res);
+    }
+    now() { return Math.round((performance.now() - this.t0) * 10) / 10; }
+    touch() { this.rev = ++this.inspector.rev; }
+    account(bytes) { this.inspector.account(this, bytes); }
+    received(text) {
+        if (this.closed)
+            return;
+        this.requestText = text;
+        this.requestBytes = Buffer.byteLength(text);
+        this.account(this.requestBytes);
+    }
+    parsed(request) {
+        if (this.closed)
+            return;
+        const input = request.input;
+        this.meta = {
+            model: typeof request.model === "string" ? request.model : null,
+            kind: Array.isArray(input) && input.some(item => item?.type === "compaction_trigger") ? "compaction" : "turn",
+            stream: typeof request.stream === "boolean" ? request.stream : null,
+            input_items: Array.isArray(input) ? input.length : null,
+            preview: previewOf(request),
+        };
+        this.touch();
+    }
+    routed(route, responsesLite) {
+        if (this.closed)
+            return;
+        this.route = route;
+        this.responsesLite = responsesLite;
+        this.touch();
+    }
+    /** Records what the bridge writes, at the same calls that write it. */
+    tap(res) {
+        const exchange = this;
+        const { writeHead, write, end } = res;
+        const head = (target, status, rest) => {
+            const text = typeof rest[0] === "string" ? rest[0] : undefined;
+            const extra = text === undefined ? rest[0] : rest[1];
+            const given = Array.isArray(extra) ? Object.fromEntries(extra) : extra ?? {};
+            exchange.response.head(status, text ?? target.statusMessage, headerMap({ ...target.getHeaders(), ...headerMap(given) }));
+        };
+        const chunk = (target, value, encoding) => {
+            if (exchange.response.headersMs === undefined)
+                head(target, target.statusCode, []);
+            if (typeof value === "string")
+                exchange.response.push(typeof encoding === "string" && encoding !== "utf8" && encoding !== "utf-8" ? Buffer.from(value, encoding) : value);
+            else if (value instanceof Uint8Array)
+                exchange.response.push(value);
+        };
+        res.writeHead = function (status, ...rest) {
+            head(this, status, rest);
+            return writeHead.call(this, status, ...rest);
+        };
+        res.write = function (value, ...rest) {
+            chunk(this, value, rest[0]);
+            return write.call(this, value, ...rest);
+        };
+        res.end = function (...args) {
+            if (args.length && typeof args[0] !== "function")
+                chunk(this, args[0], args[1]);
+            return end.apply(this, args);
+        };
+        res.once("close", () => this.close(res.writableFinished));
+    }
+    close(finished) {
+        if (this.closed)
+            return;
+        this.response.finish(finished ? "complete" : "cancelled", finished ? undefined : "Client disconnected");
+        for (const call of this.calls) {
+            if (!call.response)
+                call.failed(finished ? "No upstream response" : "Cancelled by client disconnect");
+            // The bridge stops reading after the terminal event; any remaining bytes stay unread.
+            else
+                call.done(finished ? "unread" : "cancelled");
+        }
+        this.durationMs = this.now();
+        this.closed = true;
+        this.touch();
+        this.inspector.evict();
+    }
+    /** Releases captured data without stopping the underlying HTTP exchange. */
+    discard() {
+        this.closed = true;
+        this.requestText = undefined;
+        this.requestBytes = 0;
+        this.meta = { model: null, kind: "invalid", stream: null, input_items: null, preview: null };
+        this.route = undefined;
+        for (const name of Object.keys(this.headers))
+            delete this.headers[name];
+        for (const call of this.calls)
+            call.discard();
+        this.calls.length = 0;
+        this.response.discard();
+        this.bytes = 0;
+    }
+}
+/** Process-wide capture store. Nothing is kept unless capture is on. */
+export class Inspector {
+    capturing;
+    maxBytes;
+    bytes = 0;
+    evicted = 0;
+    rev = 0;
+    seq = 0;
+    startedAt = Date.now();
+    exchanges = new Map();
+    config;
+    redactions;
+    constructor(config) {
+        this.config = config;
+        this.capturing = config.inspect?.capture ?? false;
+        this.maxBytes = (config.inspect?.max_mib ?? DEFAULT_CAPTURE_MIB) * MIB;
+        this.redactions = new Set(Object.values(config.upstreams).flatMap(up => up.auth_header ? [up.auth_header.toLowerCase()] : []));
+    }
+    /** Runs one server request with a slot for its exchange. */
+    scope(fn) { return scope.run({}, fn); }
+    begin(req, res) {
+        const slot = scope.getStore();
+        if (!this.capturing || !slot)
+            return undefined;
+        const exchange = new Exchange(this, ++this.seq, req, res);
+        this.exchanges.set(exchange.id, exchange);
+        slot.exchange = exchange;
+        exchange.touch();
+        return exchange;
+    }
+    /** Records one upstream request made inside the current exchange. */
+    upstream(url, headers, text) {
+        const slot = scope.getStore();
+        const exchange = slot?.exchange;
+        if (!exchange || exchange.closed || this.exchanges.get(exchange.id) !== exchange)
+            return undefined;
+        const call = new Call(exchange, slot.label ?? "main", url, headerMap(headers, this.redactions), text);
+        exchange.calls.push(call);
+        return call;
+    }
+    account(exchange, bytes) {
+        if (this.exchanges.get(exchange.id) !== exchange)
+            return;
+        exchange.bytes += bytes;
+        this.bytes += bytes;
+        this.evict();
+    }
+    /** Rechecks the soft cap when bytes arrive or an active exchange closes. */
+    evict() {
+        if (this.bytes <= this.maxBytes)
+            return;
+        // The cap is soft: exchanges still streaming are never evicted.
+        for (const [id, candidate] of this.exchanges) {
+            if (this.bytes <= this.maxBytes)
+                break;
+            if (!candidate.closed)
+                continue;
+            this.exchanges.delete(id);
+            this.bytes -= candidate.bytes;
+            this.evicted++;
+        }
+        this.rev++;
+    }
+    clear() {
+        for (const exchange of this.exchanges.values())
+            exchange.discard();
+        this.exchanges.clear();
+        this.bytes = 0;
+        this.rev++;
+    }
+}
+/** Labels upstream calls made inside fn, such as native compaction or a handoff. */
+export function withCaptureLabel(label, fn) {
+    const slot = scope.getStore();
+    return slot?.exchange ? scope.run({ ...slot, label }, fn) : fn();
+}
+/** Records an upstream request when the current server request is being captured. */
+export function captureUpstream(url, headers, text) {
+    return scope.getStore()?.exchange?.inspector.upstream(url, headers, text);
+}

package/dist/inspect/http.d.ts

@@ -0,0 +1,7 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Inspector } from "./capture.ts";
+export declare function isInspectorPath(path: string): boolean;
+export declare function serveInspector(req: IncomingMessage, res: ServerResponse, url: URL, inspector: Inspector, token: {
+    configured: boolean;
+    valid: () => boolean;
+}): Promise<void>;

package/dist/inspect/http.js

@@ -0,0 +1,149 @@
+// HTTP routes for the inspector: static UI files and a small JSON API.
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { detail, listView, stateView, writeExport } from "./view.js";
+// src/inspect and dist/inspect are both two levels below the package root.
+const UI_DIR = new URL("../../ui/", import.meta.url);
+const TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".json": "application/json; charset=utf-8",
+};
+const PAGE_HEADERS = {
+    "content-security-policy": "default-src 'self'; img-src 'self' data: blob:; style-src 'self'; script-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
+    "x-content-type-options": "nosniff",
+    "referrer-policy": "no-referrer",
+    "cache-control": "no-cache",
+};
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+const MAX_API_BODY = 64 * 1024;
+export function isInspectorPath(path) {
+    return path === "/inspect" || path.startsWith("/inspect/");
+}
+function send(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", "x-content-type-options": "nosniff" });
+    res.end(JSON.stringify(body));
+}
+function failure(res, status, code, message) {
+    send(res, status, { error: { code, message } });
+}
+/** Without a token, only same-origin pages served from a loopback name may use the API. */
+function localPage(req) {
+    const host = req.headers.host;
+    if (!host)
+        return false;
+    let hostname;
+    try {
+        hostname = new URL(`http://${host}`).hostname;
+    }
+    catch {
+        return false;
+    }
+    if (!LOOPBACK.has(hostname))
+        return false;
+    if (req.headers.origin !== undefined && req.headers.origin !== `http://${host}`)
+        return false;
+    const site = req.headers["sec-fetch-site"];
+    return site === undefined || site === "same-origin" || site === "none";
+}
+async function readJson(req) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_API_BODY)
+            return undefined;
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function serveFile(req, res, name) {
+    const type = TYPES[extname(name)];
+    if (!type || !/^[A-Za-z0-9][\w.-]*$/.test(name)) {
+        failure(res, 404, "not_found", "Not found");
+        return;
+    }
+    let body;
+    try {
+        body = await readFile(new URL(name, UI_DIR));
+    }
+    catch {
+        failure(res, 404, "not_found", "Not found");
+        return;
+    }
+    res.writeHead(200, { ...PAGE_HEADERS, "content-type": type, "content-length": String(body.length) });
+    res.end(req.method === "HEAD" ? undefined : body);
+}
+export async function serveInspector(req, res, url, inspector, token) {
+    const path = url.pathname;
+    const method = req.method ?? "GET";
+    if (!path.startsWith("/inspect/api/")) {
+        if (method !== "GET" && method !== "HEAD") {
+            failure(res, 405, "method_not_allowed", "Use GET");
+            return;
+        }
+        if (path === "/inspect") {
+            res.writeHead(308, { location: "/inspect/" + url.search });
+            res.end();
+            return;
+        }
+        await serveFile(req, res, path === "/inspect/" ? "index.html" : path.slice("/inspect/".length));
+        return;
+    }
+    if (token.configured ? !token.valid() : !localPage(req)) {
+        if (token.configured)
+            failure(res, 401, "invalid_api_key", "Enter the bridge token");
+        else
+            failure(res, 403, "forbidden", "Open the inspector from a loopback address, or configure token_env");
+        return;
+    }
+    const route = path.slice("/inspect/api/".length);
+    if (route === "state" && method === "GET") {
+        send(res, 200, stateView(inspector));
+        return;
+    }
+    if (route === "capture" && method === "POST") {
+        const body = await readJson(req);
+        if (typeof body?.enabled !== "boolean") {
+            failure(res, 400, "invalid_request", "Send {\"enabled\": true|false}");
+            return;
+        }
+        inspector.capturing = body.enabled;
+        inspector.rev++;
+        send(res, 200, stateView(inspector));
+        return;
+    }
+    if (route === "exchanges" && method === "DELETE") {
+        inspector.clear();
+        send(res, 200, stateView(inspector));
+        return;
+    }
+    if (route === "exchanges" && method === "GET") {
+        const since = Number(url.searchParams.get("since") ?? 0);
+        send(res, 200, listView(inspector, Number.isFinite(since) ? since : 0));
+        return;
+    }
+    if (route.startsWith("exchanges/") && method === "GET") {
+        const exchange = inspector.exchanges.get(route.slice("exchanges/".length));
+        if (!exchange) {
+            failure(res, 404, "not_found", "Exchange not found; it may have been cleared or evicted");
+            return;
+        }
+        send(res, 200, detail(exchange));
+        return;
+    }
+    if (route === "export" && method === "GET") {
+        await writeExport(inspector, res);
+        return;
+    }
+    failure(res, 404, "not_found", "Unknown inspector API route");
+}