@nurix/nustack 0.23.8 → 0.23.10

package/dist/lib/gate/hook.js

@@ -0,0 +1,79 @@
+import { performance } from "node:perf_hooks";
+import { GateInputError, gateBashCall, gateReadCall } from "./readGate.js";
+const TTY_NOTICE = "nustack gate: hook entry point; reads Claude Code's PreToolUse JSON on stdin\n";
+async function readStdin(stdin) {
+    const chunks = [];
+    for await (const chunk of stdin)
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+function parseCall(text, startedAt) {
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        throw new GateInputError("stdin is not JSON");
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+        throw new GateInputError("stdin is not a JSON object");
+    const fields = payload;
+    if (typeof fields.session_id !== "string" || fields.session_id === "")
+        throw new GateInputError("session_id is missing");
+    if (typeof fields.cwd !== "string" || fields.cwd === "")
+        throw new GateInputError("cwd is missing");
+    const toolInput = fields.tool_input;
+    if (toolInput === null || typeof toolInput !== "object" || Array.isArray(toolInput))
+        throw new GateInputError("tool_input is missing");
+    return {
+        sessionId: fields.session_id,
+        cwd: fields.cwd,
+        toolInput: toolInput,
+        agentType: typeof fields.agent_type === "string" && fields.agent_type !== "" ? fields.agent_type : "main",
+        startedAt,
+    };
+}
+function codeOf(error) {
+    const code = error?.code;
+    if (typeof code === "string" && code !== "")
+        return code;
+    if (error instanceof Error)
+        return error.constructor.name || error.name;
+    return "Error";
+}
+function messageOf(error) {
+    const text = error instanceof Error ? error.message : String(error);
+    return text.replace(/\s+/g, " ").trim();
+}
+function denialOf(answer) {
+    return `${JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: answer.reason,
+        },
+    })}\n`;
+}
+export async function runGateHook(subcommand, io = { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr, env: process.env }) {
+    const startedAt = performance.now();
+    process.exitCode = 0;
+    if (io.stdin.isTTY) {
+        io.stderr.write(TTY_NOTICE);
+        return;
+    }
+    try {
+        const call = parseCall(await readStdin(io.stdin), startedAt);
+        let answer;
+        if (subcommand === "read")
+            answer = await gateReadCall(call, io.env);
+        else if (subcommand === "bash")
+            answer = await gateBashCall(call, io.env);
+        else
+            throw new GateInputError(`unknown hook "${subcommand}"`);
+        if (answer.decision === "deny")
+            io.stdout.write(denialOf(answer));
+    }
+    catch (error) {
+        io.stderr.write(`nustack gate: ${codeOf(error)}: ${messageOf(error)}\n`);
+    }
+}

package/dist/lib/gate/outline.js

@@ -0,0 +1,146 @@
+import path from "node:path";
+import { loadCodegraph } from "../graph/library.js";
+export const OUTLINE_MAX_CHARS = 6_000;
+export const OUTLINE_HEAD_LINES = 20;
+const HEAD_LINE_MAX_CHARS = 200;
+const IMPORTS_MAX = 40;
+const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".mdx"]);
+const NO_SYMBOL_OUTLINE = "no symbol outline for this file type";
+export async function loadOutlineLibrary() {
+    try {
+        return (await loadCodegraph());
+    }
+    catch {
+        return null;
+    }
+}
+function lineCountOf(source) {
+    if (source === "")
+        return 0;
+    const lines = source.split("\n").length;
+    return source.endsWith("\n") ? lines - 1 : lines;
+}
+export function markdownOutline(source) {
+    const lines = source.split("\n");
+    const headings = [];
+    let fence = null;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const fenceMatch = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+        if (fenceMatch !== null) {
+            const marker = fenceMatch[1];
+            if (fence === null)
+                fence = marker[0];
+            else if (marker[0] === fence)
+                fence = null;
+            continue;
+        }
+        if (fence !== null)
+            continue;
+        const heading = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line);
+        if (heading !== null)
+            headings.push({ level: heading[1].length, title: heading[2], line: index + 1 });
+    }
+    const lastLine = lineCountOf(source);
+    return headings.map((heading, index) => {
+        const next = headings.slice(index + 1).find((candidate) => candidate.level <= heading.level);
+        return { name: heading.title, kind: `h${heading.level}`, startLine: heading.line, endLine: next === undefined ? lastLine : next.line - 1 };
+    });
+}
+function isSourceOutlineAnswer(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const answer = value;
+    return Array.isArray(answer.symbols) && Array.isArray(answer.imports) && typeof answer.lineCount === "number";
+}
+function entryLine(entry) {
+    const range = entry.endLine === undefined ? `L${entry.startLine}` : `L${entry.startLine}-${entry.endLine}`;
+    return `${range} ${entry.kind} ${entry.name}`;
+}
+function headOf(source) {
+    return source
+        .split("\n")
+        .slice(0, OUTLINE_HEAD_LINES)
+        .map((line) => (line.length > HEAD_LINE_MAX_CHARS ? `${line.slice(0, HEAD_LINE_MAX_CHARS)}…` : line));
+}
+function waysForward(entries, lineCount, tool) {
+    const ranged = entries.filter((entry) => entry.endLine !== undefined);
+    const largest = ranged.reduce((best, entry) => (best === undefined || entry.endLine - entry.startLine > best.endLine - best.startLine ? entry : best), undefined);
+    const example = largest === undefined
+        ? `offset=1 limit=${Math.min(lineCount, 200)}`
+        : `offset=${largest.startLine} limit=${largest.endLine - largest.startLine + 1} for ${largest.name} (L${largest.startLine}-${largest.endLine})`;
+    return [
+        "Ways forward:",
+        `1. Read only the range you need: Read with offset and limit, e.g. ${example}.`,
+        tool === "bash"
+            ? "2. Re-issue the same full read (this command, or a Read with no offset or limit); it passes this time."
+            : "2. Re-issue the same full Read; it passes this time.",
+    ];
+}
+export function renderOutline(input, outline) {
+    const header = [
+        `${input.displayPath}: ${outline.lineCount} lines, about ${input.estimatedTokens} tokens. This full read is answered with an outline instead (NuStack large-read gate).`,
+    ];
+    const importLines = outline.imports.length === 0
+        ? []
+        : [
+            `Imports: ${outline.imports.slice(0, IMPORTS_MAX).join(", ")}${outline.imports.length > IMPORTS_MAX ? `, +${outline.imports.length - IMPORTS_MAX} more` : ""}`,
+        ];
+    const head = ["", `First ${OUTLINE_HEAD_LINES} lines:`, ...headOf(input.source)];
+    const tail = ["", ...waysForward(outline.entries, outline.lineCount, input.tool)];
+    const fixed = (body) => [...header, ...importLines, ...body, ...head, ...tail].join("\n");
+    if (!outline.hasOutline)
+        return clip(fixed(["", NO_SYMBOL_OUTLINE]));
+    const ordered = [...outline.entries].sort((a, b) => a.startLine - b.startLine);
+    const shown = ["", `${outline.label}:`];
+    let text = fixed(shown);
+    for (let index = 0; index < ordered.length; index++) {
+        const remaining = ordered.length - index - 1;
+        const candidate = [...shown, entryLine(ordered[index])];
+        const withMore = remaining > 0 ? [...candidate, `+${remaining} more`] : candidate;
+        if (fixed(withMore).length > OUTLINE_MAX_CHARS) {
+            shown.push(`+${ordered.length - index} more`);
+            return clip(fixed(shown));
+        }
+        shown.push(entryLine(ordered[index]));
+        text = fixed(shown);
+    }
+    return clip(text);
+}
+function clip(text) {
+    return text.length <= OUTLINE_MAX_CHARS ? text : `${text.slice(0, OUTLINE_MAX_CHARS - 1)}…`;
+}
+export async function buildOutline(input, library) {
+    const lineCount = input.partialLineCount ?? lineCountOf(input.source);
+    if (input.partialLineCount !== undefined) {
+        return { text: renderOutline(input, { entries: [], imports: [], lineCount, hasOutline: false, label: "" }), kind: "fallback" };
+    }
+    if (MARKDOWN_EXTENSIONS.has(path.extname(input.displayPath).toLowerCase())) {
+        const entries = markdownOutline(input.source);
+        return {
+            text: renderOutline(input, { entries, imports: [], lineCount, hasOutline: entries.length > 0, label: "Headings" }),
+            kind: entries.length > 0 ? "headings" : "fallback",
+        };
+    }
+    if (library !== null && typeof library.outlineSource === "function") {
+        let answer = null;
+        try {
+            answer = await library.outlineSource(input.displayPath, input.source);
+        }
+        catch {
+        }
+        if (isSourceOutlineAnswer(answer) && (answer.symbols.length > 0 || answer.imports.length > 0)) {
+            return {
+                text: renderOutline(input, {
+                    entries: answer.symbols,
+                    imports: answer.imports,
+                    lineCount: answer.lineCount,
+                    hasOutline: true,
+                    label: "Symbols",
+                }),
+                kind: "symbols",
+            };
+        }
+    }
+    return { text: renderOutline(input, { entries: [], imports: [], lineCount, hasOutline: false, label: "" }), kind: "fallback" };
+}

package/dist/lib/gate/readGate.js

@@ -0,0 +1,126 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, openSync, readFileSync, readSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { assessBashRead, classifyBashRead } from "./bashRead.js";
+import { assessFullRead, readLeadingLines, regularFileSize, tokensOfLength } from "./estimate.js";
+import { GATE_MIN_THRESHOLD_TOKENS, isGateOff, resolveThreshold } from "./settings.js";
+export class GateInputError extends Error {
+    code = "HOOK_INPUT_INVALID";
+    constructor(message) {
+        super(message);
+        this.name = "GateInputError";
+    }
+}
+const PASS = { decision: "pass" };
+const OUTLINE_SOURCE_MAX_BYTES = 8 * 1024 * 1024;
+const OUTLINE_HEAD_SCAN_LINES = 20;
+function resolvePath(cwd, file) {
+    return path.isAbsolute(file) ? file : path.resolve(cwd, file);
+}
+function realPathOf(file) {
+    try {
+        return realpathSync(file);
+    }
+    catch {
+        return file;
+    }
+}
+export async function gateReadCall(call, env = process.env) {
+    if (isGateOff(env))
+        return PASS;
+    const filePath = call.toolInput.file_path;
+    if (typeof filePath !== "string" || filePath === "")
+        throw new GateInputError("tool_input.file_path is missing");
+    if (call.toolInput.offset != null || call.toolInput.limit != null)
+        return PASS;
+    const resolved = resolvePath(call.cwd, filePath);
+    const assessment = assessFullRead(resolved, () => resolveThreshold(env).thresholdTokens, GATE_MIN_THRESHOLD_TOKENS);
+    return answerAssessment(call, resolved, assessment, "read");
+}
+export async function gateBashCall(call, env = process.env) {
+    if (isGateOff(env))
+        return PASS;
+    const command = call.toolInput.command;
+    if (typeof command !== "string")
+        throw new GateInputError("tool_input.command is missing");
+    const read = classifyBashRead(command);
+    if (read === null)
+        return PASS;
+    const resolved = resolvePath(call.cwd, read.path);
+    const assessment = assessBashRead(resolved, read.range, () => resolveThreshold(env).thresholdTokens, GATE_MIN_THRESHOLD_TOKENS, env);
+    return answerAssessment(call, resolved, assessment, "bash");
+}
+async function answerAssessment(call, resolved, assessment, tool) {
+    if (assessment.decision === "pass")
+        return PASS;
+    return answerLargeRead(call, resolved, assessment.estimatedTokens, tool);
+}
+async function answerLargeRead(call, resolved, estimatedTokens, tool) {
+    const [{ openLocalStore, withTransaction }, routing, outline] = await Promise.all([
+        import("../local_store/database.js"),
+        import("../local_store/routing.js"),
+        import("./outline.js"),
+    ]);
+    const realPath = realPathOf(resolved);
+    const store = await openLocalStore();
+    try {
+        let denial = null;
+        if (!routing.isPathGated(store, call.sessionId, realPath)) {
+            const { source, partialLineCount } = readOutlineSource(realPath);
+            const library = partialLineCount === undefined ? await outline.loadOutlineLibrary() : null;
+            const rendered = await outline.buildOutline({ displayPath: resolved, source, estimatedTokens, tool, partialLineCount }, library);
+            denial = rendered.text;
+        }
+        const now = Date.now();
+        const isDenied = withTransaction(store, () => {
+            const isInserted = routing.gatePathOnce(store, call.sessionId, realPath, now);
+            const reason = isInserted ? (denial ?? fallbackDenial(resolved, estimatedTokens)) : null;
+            const returnedTokens = reason === null ? estimatedTokens : tokensOfLength(reason.length);
+            routing.insertLabelRow(store, {
+                id: `lr_${randomUUID()}`,
+                session_id: call.sessionId,
+                agent_type: call.agentType,
+                path: realPath,
+                estimated_tokens: estimatedTokens,
+                returned_tokens: returnedTokens,
+                handler: isInserted ? "outline" : "bypass",
+                check_result: null,
+                bypass_used: isInserted ? 0 : 1,
+                latency_ms: Math.max(0, Math.round(performance.now() - call.startedAt)),
+                tokens_kept_out: isInserted ? estimatedTokens - returnedTokens : -estimatedTokens,
+                created_at: now,
+            });
+            denial = reason;
+            return isInserted;
+        });
+        return isDenied && denial !== null ? { decision: "deny", reason: denial } : PASS;
+    }
+    finally {
+        store.close();
+    }
+}
+function readOutlineSource(file) {
+    const size = regularFileSize(file) ?? 0;
+    if (size <= OUTLINE_SOURCE_MAX_BYTES)
+        return { source: readFileSync(file, "utf8") };
+    const head = readLeadingLines(file, OUTLINE_HEAD_SCAN_LINES);
+    const descriptor = openSync(file, "r");
+    try {
+        const buffer = Buffer.alloc(head.bytes);
+        readSync(descriptor, buffer, 0, head.bytes, 0);
+        return { source: buffer.toString("utf8"), partialLineCount: readLeadingLines(file, Number.POSITIVE_INFINITY).lines };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function fallbackDenial(resolved, estimatedTokens) {
+    return [
+        `${resolved}: about ${estimatedTokens} tokens. This full read is answered without its content (NuStack large-read gate).`,
+        "",
+        "Ways forward:",
+        "1. Read only the range you need: Read with offset and limit.",
+        "2. Re-issue the same full read; it passes this time.",
+    ].join("\n");
+}

package/dist/lib/gate/settings.js

@@ -0,0 +1,24 @@
+import { GATE_THRESHOLD_TOKENS_MAX, GATE_THRESHOLD_TOKENS_MIN, readDesktopSettings } from "../desktop_settings.js";
+export const NUSTACK_GATE_ENV = "NUSTACK_GATE";
+export const NUSTACK_GATE_THRESHOLD_ENV = "NUSTACK_GATE_THRESHOLD_TOKENS";
+export const GATE_DEFAULT_THRESHOLD_TOKENS = 4_000;
+export const GATE_MIN_THRESHOLD_TOKENS = GATE_THRESHOLD_TOKENS_MIN;
+export function isGateOff(env = process.env) {
+    return env[NUSTACK_GATE_ENV] === "off";
+}
+function envThreshold(env) {
+    const text = env[NUSTACK_GATE_THRESHOLD_ENV]?.trim();
+    if (text === undefined || !/^\d+$/.test(text))
+        return null;
+    const value = Number.parseInt(text, 10);
+    return value >= GATE_THRESHOLD_TOKENS_MIN && value <= GATE_THRESHOLD_TOKENS_MAX ? value : null;
+}
+export function resolveThreshold(env = process.env, readSettings = readDesktopSettings) {
+    const fromEnv = envThreshold(env);
+    if (fromEnv !== null)
+        return { thresholdTokens: fromEnv, thresholdSource: "env" };
+    const fromSettings = readSettings().routing.gateThresholdTokens;
+    if (fromSettings !== null)
+        return { thresholdTokens: fromSettings, thresholdSource: "settings" };
+    return { thresholdTokens: GATE_DEFAULT_THRESHOLD_TOKENS, thresholdSource: "default" };
+}

package/dist/lib/gate/subcommands.js

@@ -0,0 +1 @@
+export const HOOK_SUBCOMMANDS = ["read", "bash"];

package/dist/lib/local_store/database.js

@@ -1,4 +1,5 @@
-import { chmod } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { chmod, open } from "node:fs/promises";
 import path from "node:path";
 import { mkdirSecure } from "../secure_file.js";
 import { stateDbPath } from "./paths.js";
@@ -53,6 +54,46 @@ export async function openLocalStore(options = {}) {
         },
     };
 }
+export async function readStoreVersion(dbFile = stateDbPath()) {
+    if (!existsSync(dbFile))
+        return null;
+    let db;
+    try {
+        db = await withSuppressedSqliteWarning(async () => {
+            const { DatabaseSync } = await loadSqlite();
+            return new DatabaseSync(dbFile, { readOnly: true });
+        });
+    }
+    catch {
+        return headerUserVersion(dbFile);
+    }
+    try {
+        const row = db.prepare("PRAGMA user_version").get();
+        return typeof row?.user_version === "number" ? row.user_version : null;
+    }
+    catch {
+        return headerUserVersion(dbFile);
+    }
+    finally {
+        db.close();
+    }
+}
+async function headerUserVersion(dbFile) {
+    try {
+        const handle = await open(dbFile, "r");
+        try {
+            const header = Buffer.alloc(64);
+            const { bytesRead } = await handle.read(header, 0, 64, 0);
+            return bytesRead === 64 ? header.readInt32BE(60) : null;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return null;
+    }
+}
 export function withTransaction(store, fn) {
     const { db } = store;
     db.exec("BEGIN IMMEDIATE");

package/dist/lib/local_store/index.js

@@ -12,3 +12,4 @@ export * from "./history_decisions.js";
 export * from "./accepted_uploads.js";
 export * from "./project_events_cache.js";
 export * from "./filebeat_state.js";
+export * from "./routing.js";

package/dist/lib/local_store/migrations.js

@@ -309,6 +309,41 @@ const MIGRATION_V9 = {
         `DROP TABLE record_store`,
     ],
 };
+const MIGRATION_V10 = {
+    version: 10,
+    statements: [
+        `CREATE TABLE routing_latch (
+            session_id TEXT,
+            job_kind TEXT,
+            failures INTEGER NOT NULL DEFAULT 0,
+            budget_misses INTEGER NOT NULL DEFAULT 0,
+            latched_at INTEGER,
+            PRIMARY KEY (session_id, job_kind)
+        )`,
+        `CREATE TABLE label_rows (
+            id TEXT PRIMARY KEY,
+            session_id TEXT,
+            agent_type TEXT,
+            path TEXT,
+            estimated_tokens INTEGER,
+            returned_tokens INTEGER,
+            handler TEXT,
+            check_result TEXT,
+            bypass_used INTEGER,
+            latency_ms INTEGER,
+            tokens_kept_out INTEGER,
+            created_at INTEGER,
+            sync_state TEXT NOT NULL DEFAULT 'pending'
+        )`,
+        `CREATE INDEX label_rows_sync_state_created_at_idx ON label_rows (sync_state, created_at)`,
+        `CREATE TABLE gated_paths (
+            session_id TEXT,
+            path TEXT,
+            gated_at INTEGER,
+            PRIMARY KEY (session_id, path)
+        )`,
+    ],
+};
 export const MIGRATIONS = [
     MIGRATION_V1,
     MIGRATION_V2,
@@ -319,6 +354,7 @@ export const MIGRATIONS = [
     MIGRATION_V7,
     MIGRATION_V8,
     MIGRATION_V9,
+    MIGRATION_V10,
 ];
 export const LATEST_SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
 export class LocalSchemaTooNewError extends Error {

package/dist/lib/local_store/routing.js

@@ -0,0 +1,137 @@
+export const ROUTING_LATCH_LIMIT = 2;
+export const ROUTING_JOB_KINDS = ["read.bulk", "lane.subagent"];
+export const LABEL_ROW_HANDLERS = [
+    "outline",
+    "bypass",
+    "digest",
+    "full_read",
+    "local_model",
+    "redirect",
+    "pack_hit",
+    "pack_miss",
+];
+export const LABEL_ROW_CHECK_RESULTS = ["pass", "fail", "budget", "unavailable", "latched"];
+export const LABEL_ROW_ID_MAX = 128;
+export const LABEL_ROW_PATH_MAX = 512;
+export const LABEL_ROW_SYNC_STATES = ["pending", "synced", "refused", "local"];
+export const GATED_PATH_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+export class LabelRowRefusedError extends Error {
+    code = "LABEL_ROW_REFUSED";
+    constructor(message) {
+        super(message);
+        this.name = "LabelRowRefusedError";
+    }
+}
+function isOneOf(values, value) {
+    return typeof value === "string" && values.includes(value);
+}
+function requireIdentifier(field, value) {
+    if (typeof value !== "string" || value.length < 1 || value.length > LABEL_ROW_ID_MAX) {
+        throw new LabelRowRefusedError(`${field} must be 1-${LABEL_ROW_ID_MAX} characters`);
+    }
+}
+function requireInteger(field, value, isSigned) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || (!isSigned && value < 0)) {
+        throw new LabelRowRefusedError(`${field} must be a${isSigned ? "n" : " non-negative"} integer`);
+    }
+}
+export function clipLabelRowPath(path) {
+    return path.length <= LABEL_ROW_PATH_MAX ? path : `…${path.slice(path.length - (LABEL_ROW_PATH_MAX - 1))}`;
+}
+export function insertLabelRow(store, row, syncState = "pending") {
+    requireIdentifier("id", row.id);
+    requireIdentifier("session_id", row.session_id);
+    requireIdentifier("agent_type", row.agent_type);
+    if (!isOneOf(LABEL_ROW_HANDLERS, row.handler))
+        throw new LabelRowRefusedError(`unknown handler "${String(row.handler)}"`);
+    if (row.check_result !== null && !isOneOf(LABEL_ROW_CHECK_RESULTS, row.check_result)) {
+        throw new LabelRowRefusedError(`unknown check result "${String(row.check_result)}"`);
+    }
+    if (!isOneOf(LABEL_ROW_SYNC_STATES, syncState))
+        throw new LabelRowRefusedError(`unknown sync state "${String(syncState)}"`);
+    if (row.bypass_used !== 0 && row.bypass_used !== 1)
+        throw new LabelRowRefusedError("bypass_used must be 0 or 1");
+    if (row.path !== null && typeof row.path !== "string")
+        throw new LabelRowRefusedError("path must be a string or null");
+    requireInteger("estimated_tokens", row.estimated_tokens, false);
+    requireInteger("returned_tokens", row.returned_tokens, false);
+    requireInteger("latency_ms", row.latency_ms, false);
+    requireInteger("tokens_kept_out", row.tokens_kept_out, true);
+    requireInteger("created_at", row.created_at, false);
+    store.db
+        .prepare(`INSERT INTO label_rows (id, session_id, agent_type, path, estimated_tokens, returned_tokens, handler,
+                check_result, bypass_used, latency_ms, tokens_kept_out, created_at, sync_state)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(row.id, row.session_id, row.agent_type, row.path === null ? null : clipLabelRowPath(row.path), row.estimated_tokens, row.returned_tokens, row.handler, row.check_result, row.bypass_used, row.latency_ms, row.tokens_kept_out, row.created_at, syncState);
+}
+export function labelRowWire(record) {
+    return {
+        id: record.id,
+        sessionId: record.session_id,
+        agentType: record.agent_type,
+        path: record.path,
+        estimatedTokens: record.estimated_tokens,
+        returnedTokens: record.returned_tokens,
+        handler: record.handler,
+        checkResult: record.check_result,
+        isBypassUsed: record.bypass_used === 1,
+        latencyMs: record.latency_ms,
+        tokensKeptOut: record.tokens_kept_out,
+        createdAt: record.created_at,
+    };
+}
+export function listPendingLabelRows(store, limit) {
+    return store.db
+        .prepare("SELECT * FROM label_rows WHERE sync_state = 'pending' ORDER BY created_at, id LIMIT ?")
+        .all(limit);
+}
+function markPending(store, ids, state) {
+    if (ids.length === 0)
+        return 0;
+    const placeholders = ids.map(() => "?").join(", ");
+    const result = store.db
+        .prepare(`UPDATE label_rows SET sync_state = ? WHERE sync_state = 'pending' AND id IN (${placeholders})`)
+        .run(state, ...ids);
+    return Number(result.changes);
+}
+export function markLabelRowsSynced(store, ids) {
+    return markPending(store, ids, "synced");
+}
+export function markLabelRowsRefused(store, ids) {
+    return markPending(store, ids, "refused");
+}
+export function isLatched(store, sessionId, jobKind) {
+    const row = store.db
+        .prepare("SELECT latched_at FROM routing_latch WHERE session_id = ? AND job_kind = ?")
+        .get(sessionId, jobKind);
+    return row?.latched_at != null;
+}
+export function recordRoutingMiss(store, sessionId, jobKind, miss, now = Date.now()) {
+    if (!isOneOf(ROUTING_JOB_KINDS, jobKind))
+        throw new Error(`unknown routing job kind "${String(jobKind)}"`);
+    const failures = miss === "failure" ? 1 : 0;
+    const budgetMisses = miss === "budget" ? 1 : 0;
+    store.db
+        .prepare(`INSERT INTO routing_latch (session_id, job_kind, failures, budget_misses, latched_at)
+             VALUES (?, ?, ?, ?, NULL)
+             ON CONFLICT (session_id, job_kind) DO UPDATE SET
+                failures = failures + excluded.failures,
+                budget_misses = budget_misses + excluded.budget_misses`)
+        .run(sessionId, jobKind, failures, budgetMisses);
+    store.db
+        .prepare(`UPDATE routing_latch SET latched_at = ?
+             WHERE session_id = ? AND job_kind = ? AND latched_at IS NULL AND failures + budget_misses >= ?`)
+        .run(now, sessionId, jobKind, ROUTING_LATCH_LIMIT);
+}
+export function isPathGated(store, sessionId, path) {
+    return store.db.prepare("SELECT 1 FROM gated_paths WHERE session_id = ? AND path = ?").get(sessionId, path) !== undefined;
+}
+export function gatePathOnce(store, sessionId, path, now = Date.now()) {
+    const result = store.db
+        .prepare("INSERT INTO gated_paths (session_id, path, gated_at) VALUES (?, ?, ?) ON CONFLICT (session_id, path) DO NOTHING")
+        .run(sessionId, path, now);
+    const isInserted = Number(result.changes) === 1;
+    if (isInserted)
+        store.db.prepare("DELETE FROM gated_paths WHERE gated_at < ?").run(now - GATED_PATH_RETENTION_MS);
+    return isInserted;
+}

package/dist/lib/nustack_client.js

@@ -21,8 +21,10 @@ const KEYS_PLANE = "the credential plane (/api/v1/keys)";
 export function apiError(payload, status, label, plane) {
     if (status === 401 && !envToken())
         return Object.assign(new Error(deadCredentialCopy("revoked")), { code: "SIGNED_OUT" });
-    const code = typeof payload?.error === "object" && typeof payload.error?.code === "string" ? payload.error.code : "UNEXPECTED";
-    return Object.assign(new Error(errorMessage(payload, status, label, plane)), { code });
+    const envelope = typeof payload?.error === "object" ? payload.error : undefined;
+    const code = typeof envelope?.code === "string" ? envelope.code : "UNEXPECTED";
+    const details = envelope?.details && typeof envelope.details === "object" && !Array.isArray(envelope.details) ? envelope.details : undefined;
+    return Object.assign(new Error(errorMessage(payload, status, label, plane)), details ? { code, details } : { code });
 }
 export function errorMessage(payload, status, label, plane) {
     if (plane && status === 404 && typeof payload?.error === "string") {