@nurix/nustack 0.23.12 → 0.23.14

package/dist/lib/gate/bulkReadRelay.js

@@ -0,0 +1,354 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { isPidAlive, probeProjects, readServerRecord } from "../agent/desktopDoor.js";
+import { printJsonSuccess } from "../json_output.js";
+import { DIRECT_SESSION_ID } from "../local_store/routing.js";
+import { estimateReadTokens, readLeadingLines, READ_DEFAULT_LINE_LIMIT, regularFileSize, tokensOfLength } from "./estimate.js";
+import { buildOutline, loadOutlineLibrary, OUTLINE_MAX_CHARS } from "./outline.js";
+import { READ_BULK_BUDGET_BOUNDS_MS, resolveReadBulkBudget } from "./settings.js";
+const RELAY_TIMEOUT_MARGIN_MS = 10_000;
+const OUTLINE_SOURCE_MAX_BYTES = 8 * 1024 * 1024;
+const OUTLINE_HEAD_SCAN_LINES = 20;
+const REASON_FINDINGS_MAX = 3;
+const EXIT_CODES = { pass: 0, fail: 1, budget: 1, latched: 1, unavailable: 2 };
+const DESKTOP_CLOSED = "the NuStack desktop is not running — open it, then ask again";
+const DESKTOP_SILENT = "the NuStack desktop did not answer — open it, then ask again";
+const DESKTOP_OLD = "the desktop is older than the checked bulk read — update NuStack";
+function realPathOf(file) {
+    try {
+        return realpathSync(file);
+    }
+    catch {
+        return file;
+    }
+}
+function isWithin(root, file) {
+    return file === root || file.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`);
+}
+export function pickProject(projects, requested) {
+    let best = null;
+    for (const project of projects) {
+        const projectRealPath = realPathOf(project.path);
+        if (!requested.every((entry) => isWithin(projectRealPath, entry.realPath)))
+            continue;
+        if (best === null || projectRealPath.length > best.projectRealPath.length)
+            best = { project, projectRealPath };
+    }
+    if (best !== null)
+        return best;
+    const firstHolder = projects.map((project) => realPathOf(project.path)).find((root) => isWithin(root, requested[0].realPath));
+    const unheld = firstHolder === undefined ? requested[0] : requested.find((entry) => !isWithin(firstHolder, entry.realPath));
+    return { unheldPath: unheld.given };
+}
+function findingText(finding) {
+    if (typeof finding === "string")
+        return finding;
+    if (finding !== null && typeof finding === "object") {
+        const fields = finding;
+        const at = typeof fields.at === "string" ? fields.at : null;
+        const detail = [fields.message, fields.text, fields.detail, fields.kind].find((value) => typeof value === "string");
+        if (at !== null && detail !== undefined)
+            return `${at}: ${detail}`;
+        if (detail !== undefined)
+            return detail;
+    }
+    return JSON.stringify(finding);
+}
+function isDigestCheck(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const check = value;
+    return (check.result === "pass" || check.result === "fail" || check.result === "budget") && Array.isArray(check.findings);
+}
+function emptied(digest) {
+    return { ...digest, files: (digest.files ?? []).map((file) => ({ ...file, chunks: [] })) };
+}
+async function askDoor(port, token, body, timeoutMs) {
+    let response;
+    try {
+        response = await fetch(`http://127.0.0.1:${port}/api/read/bulk`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "content-type": "application/json" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (error) {
+        const name = error?.name;
+        if (name === "TimeoutError" || name === "AbortError") {
+            return { result: "budget", reason: `the desktop did not answer within ${timeoutMs} ms`, digest: null, check: null, miss: "budget" };
+        }
+        return { result: "unavailable", reason: DESKTOP_SILENT, digest: null, check: null, miss: "failure" };
+    }
+    let envelope = null;
+    try {
+        envelope = (await response.json());
+    }
+    catch {
+        envelope = null;
+    }
+    const message = typeof envelope?.message === "string" && envelope.message !== "" ? envelope.message : `HTTP ${response.status}`;
+    if (response.status >= 400 && response.status < 500) {
+        return { result: "fail", reason: `the desktop refused the bulk read: ${message}`, digest: null, check: null, miss: null };
+    }
+    if (response.status !== 200 || envelope === null || envelope.data === null || typeof envelope.data !== "object") {
+        const reason = response.status === 200 ? DESKTOP_SILENT : `the desktop could not run the bulk read: ${message}`;
+        return { result: "unavailable", reason, digest: null, check: null, miss: "failure" };
+    }
+    const data = envelope.data;
+    if (!isDigestCheck(data.check))
+        return { result: "unavailable", reason: DESKTOP_OLD, digest: null, check: null, miss: "failure" };
+    const check = data.check;
+    if (check.result === "pass")
+        return { result: "pass", reason: null, digest: data, check, miss: null };
+    if (check.result === "budget") {
+        const budget = typeof data.budgetMs === "number" ? ` of ${data.budgetMs} ms` : "";
+        return { result: "budget", reason: `the digest ran past its budget${budget}`, digest: emptied(data), check, miss: "budget" };
+    }
+    const shown = check.findings.slice(0, REASON_FINDINGS_MAX).map((finding) => `- ${findingText(finding)}`);
+    const more = check.findings.length > REASON_FINDINGS_MAX ? [`+${check.findings.length - REASON_FINDINGS_MAX} more findings`] : [];
+    return {
+        result: "fail",
+        reason: ["the digest failed its check:", ...shown, ...more].join("\n"),
+        digest: emptied(data),
+        check,
+        miss: "failure",
+    };
+}
+function lineCountOf(file) {
+    try {
+        return readLeadingLines(file, Number.POSITIVE_INFINITY).lines;
+    }
+    catch {
+        return null;
+    }
+}
+function renderPass(digest, question, requested, relativeOf) {
+    const perPath = new Map();
+    const sections = [];
+    for (const file of digest.files ?? []) {
+        const entry = requested.find((candidate) => relativeOf(candidate) === file.path);
+        const lines = [`${entry?.given ?? file.path} · ${question}`];
+        const chunks = file.chunks ?? [];
+        for (const chunk of chunks) {
+            lines.push(chunk.at);
+            for (const note of chunk.notes ?? []) {
+                const quotes = (note.quotes ?? []).length > 0 ? ` [${(note.quotes ?? []).join(", ")}]` : "";
+                lines.push(`- ${note.text ?? ""}${quotes}`);
+            }
+        }
+        if (digest.truncated === true && entry !== undefined) {
+            const total = lineCountOf(entry.realPath);
+            const last = chunks.length > 0 ? Number(/-(\d+)$/.exec(chunks[chunks.length - 1].at)?.[1] ?? 0) : 0;
+            if (total !== null && last < total)
+                lines.push(`covers lines 1–${last} of ${total}`);
+        }
+        const section = lines.join("\n");
+        sections.push(section);
+        if (entry !== undefined)
+            perPath.set(entry.realPath, (perPath.get(entry.realPath) ?? 0) + section.length);
+    }
+    const footer = `model ${digest.model ?? "unknown"} · ${digest.elapsedMs ?? 0} ms · check pass`;
+    return { text: [...sections, footer].join("\n\n"), perPath };
+}
+function outlineSourceOf(file) {
+    const size = regularFileSize(file);
+    if (size === null)
+        return null;
+    try {
+        if (size <= OUTLINE_SOURCE_MAX_BYTES)
+            return { source: readFileSync(file, "utf8") };
+        const head = readLeadingLines(file, OUTLINE_HEAD_SCAN_LINES);
+        const source = readFileSync(file).subarray(0, head.bytes).toString("utf8");
+        return { source, partialLineCount: readLeadingLines(file, Number.POSITIVE_INFINITY).lines };
+    }
+    catch {
+        return null;
+    }
+}
+function estimatedTokensOf(file) {
+    try {
+        return estimateReadTokens(readLeadingLines(file, READ_DEFAULT_LINE_LIMIT));
+    }
+    catch {
+        return 0;
+    }
+}
+async function buildOutlines(requested, estimates) {
+    const library = await loadOutlineLibrary();
+    const outlines = [];
+    let total = 0;
+    let omitted = 0;
+    for (const entry of requested) {
+        const read = outlineSourceOf(entry.realPath);
+        if (read === null) {
+            omitted++;
+            continue;
+        }
+        const rendered = await buildOutline({
+            displayPath: entry.given,
+            source: read.source,
+            estimatedTokens: estimates.get(entry.realPath) ?? 0,
+            tool: "read",
+            partialLineCount: read.partialLineCount,
+        }, read.partialLineCount === undefined ? library : null);
+        if (total + rendered.text.length > OUTLINE_MAX_CHARS) {
+            omitted++;
+            continue;
+        }
+        total += rendered.text.length;
+        outlines.push({ path: entry.given, realPath: entry.realPath, text: rendered.text });
+    }
+    return { outlines, omitted };
+}
+function renderNonPass(result, reason, outlines, omitted, requested) {
+    const perPath = new Map();
+    const blocks = [`nustack read bulk: ${result} — ${reason}`];
+    for (const outline of outlines) {
+        blocks.push(outline.text);
+        perPath.set(outline.realPath, (perPath.get(outline.realPath) ?? 0) + outline.text.length);
+    }
+    if (omitted > 0)
+        blocks.push(`+${omitted} outlines omitted`);
+    const promises = requested.map((entry) => {
+        const line = `A full Read of ${entry.given} now passes.`;
+        perPath.set(entry.realPath, (perPath.get(entry.realPath) ?? 0) + line.length);
+        return line;
+    });
+    blocks.push(promises.join("\n"));
+    return { text: blocks.join("\n\n"), perPath };
+}
+async function openStoreQuietly() {
+    try {
+        const { openLocalStore } = await import("../local_store/database.js");
+        return { store: await openLocalStore(), error: null };
+    }
+    catch (error) {
+        return { store: null, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export async function runReadBulk(options, env = process.env) {
+    const startedAt = performance.now();
+    const sessionId = options.session !== undefined && options.session !== "" ? options.session : DIRECT_SESSION_ID;
+    const isDirect = sessionId === DIRECT_SESSION_ID;
+    const agentType = options.agentType !== undefined && options.agentType !== "" ? options.agentType : "main";
+    const cwd = process.cwd();
+    const requested = options.paths.map((given) => {
+        const resolved = path.resolve(cwd, given);
+        return { given, resolved, realPath: realPathOf(resolved) };
+    });
+    const opened = await openStoreQuietly();
+    const store = opened.store;
+    try {
+        const outcome = await reachDoor(options, requested, sessionId, isDirect, store, env);
+        const estimates = new Map(requested.map((entry) => [entry.realPath, estimatedTokensOf(entry.realPath)]));
+        let text;
+        let perPath;
+        let outlines = [];
+        if (outcome.result === "pass" && outcome.digest !== null) {
+            ({ text, perPath } = renderPass(outcome.digest, options.question, requested, outcome.relativeOf));
+        }
+        else {
+            const built = await buildOutlines(requested, estimates);
+            outlines = built.outlines.map(({ path: given, text: outlineText }) => ({ path: given, text: outlineText }));
+            ({ text, perPath } = renderNonPass(outcome.result, outcome.reason ?? outcome.result, built.outlines, built.omitted, requested));
+        }
+        const answer = {
+            result: outcome.result,
+            sessionId,
+            digest: outcome.digest,
+            check: outcome.check,
+            outlines,
+            reason: outcome.result === "pass" ? null : (outcome.reason ?? outcome.result),
+        };
+        if (options.json === true)
+            printJsonSuccess("read bulk", answer);
+        else
+            console.log(text);
+        process.exitCode = EXIT_CODES[outcome.result];
+        const paths = requested.map((entry) => ({
+            realPath: entry.realPath,
+            estimatedTokens: estimates.get(entry.realPath) ?? 0,
+            returnedTokens: tokensOfLength(perPath.get(entry.realPath) ?? 0),
+        }));
+        await writeOutcome(store, opened.error, {
+            sessionId,
+            agentType,
+            result: outcome.result,
+            miss: outcome.miss,
+            latencyMs: Math.max(0, Math.round(performance.now() - startedAt)),
+            paths,
+        });
+        return answer;
+    }
+    finally {
+        store?.close();
+    }
+}
+async function reachDoor(options, requested, sessionId, isDirect, store, env) {
+    const noRelative = (entry) => entry.given;
+    if (!isDirect && store !== null) {
+        const { isLatched } = await import("../local_store/routing.js");
+        if (isLatched(store, sessionId, "read.bulk")) {
+            return {
+                result: "latched",
+                reason: "the local model missed twice in this session, so tier 1 is off for it; no digest was asked for",
+                digest: null,
+                check: null,
+                miss: null,
+                relativeOf: noRelative,
+            };
+        }
+    }
+    const record = await readServerRecord();
+    if (record === null || !isPidAlive(record.pid)) {
+        return { result: "unavailable", reason: DESKTOP_CLOSED, digest: null, check: null, miss: "failure", relativeOf: noRelative };
+    }
+    const projects = await probeProjects(record);
+    if (projects === null) {
+        return { result: "unavailable", reason: DESKTOP_SILENT, digest: null, check: null, miss: "failure", relativeOf: noRelative };
+    }
+    const picked = pickProject(projects, requested);
+    if ("unheldPath" in picked) {
+        return {
+            result: "unavailable",
+            reason: `no NuStack project holds ${picked.unheldPath} — add its folder in the desktop`,
+            digest: null,
+            check: null,
+            miss: null,
+            relativeOf: noRelative,
+        };
+    }
+    const relativeOf = (entry) => path.relative(picked.projectRealPath, entry.realPath).split(path.sep).join("/");
+    const { budgetMs } = resolveReadBulkBudget(options.budgetMs, env);
+    const body = {
+        project: picked.project.path,
+        paths: requested.map(relativeOf),
+        question: options.question,
+    };
+    if (options.lines !== undefined)
+        body.lines = options.lines;
+    if (budgetMs !== null)
+        body.budgetMs = budgetMs;
+    const timeoutMs = (budgetMs ?? READ_BULK_BUDGET_BOUNDS_MS.max) + RELAY_TIMEOUT_MARGIN_MS;
+    return { ...(await askDoor(record.port, record.token, body, timeoutMs)), relativeOf };
+}
+async function writeOutcome(store, openError, outcome) {
+    if (store === null) {
+        process.stderr.write(`nustack read bulk: the local store did not open, so this call left no label row (${openError ?? "unknown"})\n`);
+        return;
+    }
+    try {
+        const [{ withTransaction }, { recordBulkReadOutcome }] = await Promise.all([
+            import("../local_store/database.js"),
+            import("../local_store/routing.js"),
+        ]);
+        recordBulkReadOutcome(store, (fn) => withTransaction(store, () => fn()), outcome, () => `lr_${randomUUID()}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`nustack read bulk: the local store is busy, so this call left no label row (${message.replace(/\s+/g, " ").trim()})\n`);
+    }
+}

package/dist/lib/gate/hook.js

@@ -1,4 +1,6 @@
+import path from "node:path";
 import { performance } from "node:perf_hooks";
+import { classifyBashRead } from "./bashRead.js";
 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) {
@@ -45,15 +47,40 @@ function messageOf(error) {
     const text = error instanceof Error ? error.message : String(error);
     return text.replace(/\s+/g, " ").trim();
 }
-function denialOf(answer) {
+function denialOf(reason) {
     return `${JSON.stringify({
         hookSpecificOutput: {
             hookEventName: "PreToolUse",
             permissionDecision: "deny",
-            permissionDecisionReason: answer.reason,
+            permissionDecisionReason: reason,
         },
     })}\n`;
 }
+function deniedPathOf(subcommand, call) {
+    const written = subcommand === "read"
+        ? call.toolInput.file_path
+        : typeof call.toolInput.command === "string"
+            ? classifyBashRead(call.toolInput.command)?.path
+            : undefined;
+    if (typeof written !== "string" || written === "")
+        return null;
+    return path.isAbsolute(written) ? written : path.resolve(call.cwd, written);
+}
+async function reasonWithTierOne(subcommand, call, reason, io) {
+    const deniedPath = deniedPathOf(subcommand, call);
+    if (deniedPath === null)
+        return reason;
+    try {
+        const [{ isTierOneOffered, tierOneWayForward }, { withWayForward }] = await Promise.all([import("./tierOne.js"), import("./outline.js")]);
+        if (!(await isTierOneOffered(call.sessionId)))
+            return reason;
+        return withWayForward(reason, tierOneWayForward(call.sessionId, call.agentType, deniedPath));
+    }
+    catch (error) {
+        io.stderr.write(`nustack gate: ${codeOf(error)}: ${messageOf(error)}\n`);
+        return reason;
+    }
+}
 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;
@@ -71,7 +98,7 @@ export async function runGateHook(subcommand, io = { stdin: process.stdin, stdou
         else
             throw new GateInputError(`unknown hook "${subcommand}"`);
         if (answer.decision === "deny")
-            io.stdout.write(denialOf(answer));
+            io.stdout.write(denialOf(await reasonWithTierOne(subcommand, call, answer.reason, io)));
     }
     catch (error) {
         io.stderr.write(`nustack gate: ${codeOf(error)}: ${messageOf(error)}\n`);

package/dist/lib/gate/outline.js

@@ -107,6 +107,18 @@ export function renderOutline(input, outline) {
     }
     return clip(text);
 }
+export function withWayForward(denial, line) {
+    const marker = "\n\nWays forward:";
+    const at = denial.lastIndexOf(marker);
+    if (at === -1)
+        return clip(`${denial}\n${line}`);
+    const body = denial.slice(0, at);
+    const tail = `${denial.slice(at)}\n${line}`;
+    const room = OUTLINE_MAX_CHARS - tail.length;
+    if (room <= 0)
+        return clip(tail.slice(2));
+    return `${body.length <= room ? body : `${body.slice(0, room - 1)}…`}${tail}`;
+}
 function clip(text) {
     return text.length <= OUTLINE_MAX_CHARS ? text : `${text.slice(0, OUTLINE_MAX_CHARS - 1)}…`;
 }

package/dist/lib/gate/settings.js

@@ -1,4 +1,4 @@
-import { GATE_THRESHOLD_TOKENS_MAX, GATE_THRESHOLD_TOKENS_MIN, readDesktopSettings } from "../desktop_settings.js";
+import { DIGEST_BUDGET_MS_MAX, DIGEST_BUDGET_MS_MIN, 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;
@@ -22,3 +22,26 @@ export function resolveThreshold(env = process.env, readSettings = readDesktopSe
         return { thresholdTokens: fromSettings, thresholdSource: "settings" };
     return { thresholdTokens: GATE_DEFAULT_THRESHOLD_TOKENS, thresholdSource: "default" };
 }
+export const READ_BULK_BUDGET_ENV = "NUSTACK_READ_BULK_BUDGET_MS";
+export const READ_BULK_BUDGET_BOUNDS_MS = { min: DIGEST_BUDGET_MS_MIN, max: DIGEST_BUDGET_MS_MAX };
+export function isReadBulkBudgetInRange(value) {
+    return Number.isInteger(value) && value >= READ_BULK_BUDGET_BOUNDS_MS.min && value <= READ_BULK_BUDGET_BOUNDS_MS.max;
+}
+function envBudget(env) {
+    const text = env[READ_BULK_BUDGET_ENV]?.trim();
+    if (text === undefined || !/^\d+$/.test(text))
+        return null;
+    const value = Number.parseInt(text, 10);
+    return isReadBulkBudgetInRange(value) ? value : null;
+}
+export function resolveReadBulkBudget(flagBudgetMs, env = process.env, readSettings = readDesktopSettings) {
+    if (flagBudgetMs !== undefined && isReadBulkBudgetInRange(flagBudgetMs))
+        return { budgetMs: flagBudgetMs, budgetSource: "flag" };
+    const fromEnv = envBudget(env);
+    if (fromEnv !== null)
+        return { budgetMs: fromEnv, budgetSource: "env" };
+    const fromSettings = readSettings().routing.digestBudgetMs;
+    if (fromSettings !== null && isReadBulkBudgetInRange(fromSettings))
+        return { budgetMs: fromSettings, budgetSource: "settings" };
+    return { budgetMs: null, budgetSource: "none" };
+}

package/dist/lib/gate/tierOne.js

@@ -0,0 +1,22 @@
+import { isPidAlive, readServerRecord } from "../agent/desktopDoor.js";
+export async function isTierOneOffered(sessionId) {
+    const record = await readServerRecord();
+    if (record === null || !isPidAlive(record.pid))
+        return false;
+    const [{ openLocalStore }, { isLatched }] = await Promise.all([import("../local_store/database.js"), import("../local_store/routing.js")]);
+    const store = await openLocalStore();
+    try {
+        return !isLatched(store, sessionId, "read.bulk");
+    }
+    finally {
+        store.close();
+    }
+}
+function shellWord(word) {
+    return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
+}
+export function tierOneWayForward(sessionId, agentType, filePath) {
+    const agent = agentType !== "" && agentType !== "main" ? ` --agent-type ${shellWord(agentType)}` : "";
+    const command = `nustack read bulk --session ${shellWord(sessionId)}${agent} --paths ${shellWord(filePath)} --question "<your question>"`;
+    return `3. Ask the local model: \`${command}\` — a digest whose every range is the engine's, checked before you see it.`;
+}

package/dist/lib/harness/codes.js

@@ -0,0 +1,24 @@
+export const HARNESS_CODES = {
+    HARNESS_UNAVAILABLE: "HARNESS_UNAVAILABLE",
+    HARNESS_MOUNT_FAILED: "HARNESS_MOUNT_FAILED",
+    HARNESS_DIGEST_MISMATCH: "HARNESS_DIGEST_MISMATCH",
+    HARNESS_OFFLINE_NO_CACHE: "HARNESS_OFFLINE_NO_CACHE",
+    ORIGIN_MISMATCH: "ORIGIN_MISMATCH",
+    ETNA_MOUNT_PRESENT: "ETNA_MOUNT_PRESENT",
+    INIT_NEEDS_PROJECT: "INIT_NEEDS_PROJECT",
+    INIT_NEEDS_DEVICE: "INIT_NEEDS_DEVICE",
+};
+export const TRAILER_HOOK_VALUES = ["installed", "skipped_hooks_path", "skipped_foreign_hook", "skipped_not_git"];
+export const SESSION_HOOK_VALUES = ["installed", "present", "skipped_unparsable", "skipped_etna_mount"];
+export const MOUNT_STATUS_VALUES = ["mounted", "current", "failed", "skipped_etna_mount"];
+export const MOUNT_SOURCE_VALUES = ["network", "cache", "legacy"];
+export const STATUS_SOURCE_VALUES = ["version", "legacy"];
+export const STATUS_EXIT = { IN_STEP: 0, DIFFERING: 1, UNREACHABLE: 2 };
+export class HarnessError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "HarnessError";
+        this.code = code;
+    }
+}