@nurix/nustack 0.23.18 → 0.23.20

package/dist/commands/desktopAgent.js

@@ -0,0 +1,131 @@
+import { DEVICE_TOKEN_VARIABLE } from "../lib/records/environment.js";
+import { printJsonError, printJsonSuccess } from "../lib/json_output.js";
+import { gitOutcome } from "../lib/session-engine/worktree.js";
+import { ensureBinding, mountHarness, prepareCheckout, writeNustackShim } from "../lib/desktop-agents/checkout.js";
+import { claudeArgs, claudeEnv, gitDirsOf, homeOf, realCheckout, runClaude, syncRecords } from "../lib/desktop-agents/claudeRun.js";
+import { composePrompt } from "../lib/desktop-agents/prompt.js";
+import { discardProposal, publishProposal, publishRun } from "../lib/desktop-agents/publish.js";
+import { failedResult, parseProposalRequest, parseRunRequest, } from "../lib/desktop-agents/request.js";
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function readRequest(command, parse) {
+    let raw;
+    try {
+        raw = JSON.parse(await readStdin());
+    }
+    catch {
+        printJsonError(command, { code: "REQUEST_INVALID", message: "stdin must be one JSON request." });
+        return null;
+    }
+    const parsed = parse(raw);
+    if (!parsed.ok) {
+        printJsonError(command, { code: parsed.code, message: parsed.message });
+        return null;
+    }
+    return parsed.value;
+}
+function log(line) {
+    console.error(`desktop-agent: ${line}`);
+}
+function nustackHostOf(env) {
+    const url = env.NUSTACK_URL ?? env.NUSTACK_API_BASE_URL;
+    if (!url)
+        return "nustack.tech";
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return null;
+    }
+}
+function pullRequestBody(request, costCents) {
+    return [
+        `Agent: ${request.agent.label} (\`${request.agent.slug}\`)`,
+        `Firing session: ${request.sessionId ?? "local"}`,
+        `Engine: ${request.engine}`,
+        `Cost: $${(costCents / 100).toFixed(2)}`,
+        "",
+        "Opened by a NuStack desktop agent run.",
+    ].join("\n");
+}
+async function runAccepted(request) {
+    const env = process.env;
+    let prepared;
+    try {
+        prepared = await prepareCheckout(request, env);
+    }
+    catch (error) {
+        log(`checkout: ${error instanceof Error ? error.message : String(error)}`);
+        return failedResult("checkout_unbound", "none");
+    }
+    const { worktreePath, branch, base } = prepared;
+    if (!(await ensureBinding(worktreePath, request))) {
+        log(`checkout: ${worktreePath} is not bound to Project ${request.projectId}`);
+        return failedResult("checkout_unbound", "none");
+    }
+    const mountEnv = { ...env };
+    delete mountEnv[DEVICE_TOKEN_VARIABLE];
+    const mounted = await mountHarness(worktreePath, mountEnv);
+    if (!mounted.proceed) {
+        log(mounted.line);
+        return failedResult("harness_unmounted", "none");
+    }
+    if (mounted.line)
+        log(mounted.line);
+    const binDir = await writeNustackShim(env);
+    const checkout = realCheckout(worktreePath);
+    const commonDir = await gitOutcome(["rev-parse", "--git-common-dir"], worktreePath);
+    const gitDir = await gitOutcome(["rev-parse", "--git-dir"], worktreePath);
+    const dirs = gitDirsOf(commonDir.stdout, gitDir.stdout, worktreePath);
+    const inputs = { checkout, ...dirs, home: homeOf(env), nustackHost: nustackHostOf(env) };
+    const modelEnv = claudeEnv(request, env, binDir);
+    const outcome = await runClaude(request, claudeArgs(request, inputs, modelEnv), modelEnv, worktreePath, composePrompt(request));
+    if (request.sessionId !== null) {
+        const synced = await syncRecords(env, worktreePath);
+        log(`records sync exited ${synced.code ?? "unspawned"}`);
+    }
+    const shared = { vendorSessionId: outcome.vendorSessionId, costCents: outcome.costCents, engineCheck: outcome.engineCheck, mount: mounted.mount };
+    if (outcome.reason) {
+        await gitOutcome(["reset", "--hard"], worktreePath);
+        await gitOutcome(["checkout", "--detach"], worktreePath);
+        await gitOutcome(["branch", "-D", branch], worktreePath);
+        return failedResult(outcome.reason, mounted.mount, shared);
+    }
+    const published = await publishRun(request, worktreePath, branch, base, pullRequestBody(request, outcome.costCents), env);
+    return { outcome: "done", ...shared, result: published.result, pullRequestUrl: published.pullRequestUrl };
+}
+export async function runDesktopAgentRun() {
+    const request = await readRequest("desktop-agent run", parseRunRequest);
+    if (!request)
+        return;
+    printJsonSuccess("desktop-agent run", await runAccepted(request));
+}
+export async function runDesktopAgentPrompt() {
+    const request = await readRequest("desktop-agent prompt", parseRunRequest);
+    if (!request)
+        return;
+    printJsonSuccess("desktop-agent prompt", { prompt: composePrompt(request) });
+}
+export async function runDesktopAgentPublish() {
+    const request = await readRequest("desktop-agent publish", parseProposalRequest);
+    if (!request)
+        return;
+    const published = await publishProposal(request, process.env);
+    const result = published
+        ? { outcome: "done", vendorSessionId: null, costCents: 0, result: published.result, pullRequestUrl: published.pullRequestUrl, engineCheck: { apiKeySource: null, model: null }, mount: "none" }
+        : { outcome: "failed", vendorSessionId: null, costCents: 0, result: null, pullRequestUrl: null, engineCheck: { apiKeySource: null, model: null }, mount: "none" };
+    if (!published)
+        log(`publish: ${request.branch} could not be renamed or pushed`);
+    printJsonSuccess("desktop-agent publish", result);
+}
+export async function runDesktopAgentDiscard() {
+    const request = await readRequest("desktop-agent discard", parseProposalRequest);
+    if (!request)
+        return;
+    const discarded = await discardProposal(request);
+    printJsonSuccess("desktop-agent discard", { discarded });
+}

package/dist/lib/desktop-agents/checkout.js

@@ -0,0 +1,148 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { chmod, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { HARNESS_CODES } from "../harness/codes.js";
+import { loadHarness } from "../harness/vendor.js";
+import { projectJsonPath, readBindingMarker } from "../project_context.js";
+import { gitOutcome, sessionsHome } from "../session-engine/worktree.js";
+export const DESKTOP_AGENT_CHECKOUTS_DIR = "agents";
+export const DESKTOP_AGENT_BIN_DIR = ".bin";
+export const DESKTOP_AGENT_PROPOSAL_BRANCH_PREFIX = "nustack/proposal/";
+export const DESKTOP_AGENT_EXCLUDE_START = "# nustack:desktop-agent:start";
+export const DESKTOP_AGENT_EXCLUDE_END = "# nustack:desktop-agent:end";
+const MARKER_RELATIVE = ".nustack/workspace.json";
+const FETCH_TIMEOUT_MS = 10 * 60_000;
+export function agentCheckoutsRoot(env = process.env) {
+    return path.join(sessionsHome(env), DESKTOP_AGENT_CHECKOUTS_DIR);
+}
+export function agentCheckoutPath(projectId, slug, env = process.env) {
+    return path.join(agentCheckoutsRoot(env), projectId, slug);
+}
+export async function runBranchName(slug, runId) {
+    const { AGENT_BRANCH_PREFIX } = await loadHarness("rules");
+    return `${AGENT_BRANCH_PREFIX}${slug}/${runId}`;
+}
+export function proposalBranchName(slug, runId) {
+    return `${DESKTOP_AGENT_PROPOSAL_BRANCH_PREFIX}${slug}/${runId}`;
+}
+export function agentBinDir(env = process.env) {
+    return path.join(agentCheckoutsRoot(env), DESKTOP_AGENT_BIN_DIR);
+}
+const CLI_ENTRY = fileURLToPath(new URL("../../index.js", import.meta.url));
+export async function writeNustackShim(env = process.env) {
+    const dir = agentBinDir(env);
+    await mkdir(dir, { recursive: true });
+    const shim = path.join(dir, "nustack");
+    await writeFile(shim, `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(CLI_ENTRY)} "$@"\n`);
+    await chmod(shim, 0o755);
+    return dir;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+async function gitText(args, cwd) {
+    const outcome = await gitOutcome(args, cwd);
+    return outcome.ok ? outcome.stdout : null;
+}
+async function gitMust(args, cwd, timeoutMs) {
+    const outcome = await gitOutcome(args, cwd, timeoutMs);
+    if (!outcome.ok)
+        throw new Error(`git ${args.join(" ")} failed: ${outcome.stderr || outcome.stdout}`);
+}
+export async function defaultBranchOf(checkoutPath) {
+    const head = await gitText(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], checkoutPath);
+    if (head && head.startsWith("origin/"))
+        return head.slice("origin/".length);
+    return "main";
+}
+export async function resolveBase(checkoutPath, prBase) {
+    if (prBase === "change") {
+        const current = await gitText(["rev-parse", "--abbrev-ref", "HEAD"], checkoutPath);
+        if (current && current !== "HEAD") {
+            const remote = await gitText(["ls-remote", "--heads", "origin", current], checkoutPath);
+            if (remote && remote.trim() !== "")
+                return current;
+        }
+    }
+    return defaultBranchOf(checkoutPath);
+}
+export async function prepareCheckout(request, env = process.env) {
+    const worktreePath = agentCheckoutPath(request.projectId, request.agent.slug, env);
+    if (!existsSync(path.join(worktreePath, ".git"))) {
+        await mkdir(path.dirname(worktreePath), { recursive: true });
+        await gitOutcome(["worktree", "prune"], request.checkoutPath);
+        await gitMust(["worktree", "add", "--detach", worktreePath], request.checkoutPath);
+    }
+    await gitMust(["fetch", "origin"], worktreePath, FETCH_TIMEOUT_MS);
+    await gitMust(["reset", "--hard"], worktreePath);
+    await gitMust(["clean", "-fd"], worktreePath);
+    const base = await resolveBase(request.checkoutPath, request.prBase);
+    const branch = await runBranchName(request.agent.slug, request.runId);
+    await gitMust(["checkout", "-B", branch, `origin/${base}`], worktreePath);
+    return { worktreePath, branch, base };
+}
+async function excludePathOf(worktreePath) {
+    const relative = await gitText(["rev-parse", "--git-path", "info/exclude"], worktreePath);
+    if (!relative)
+        return null;
+    return path.isAbsolute(relative) ? relative : path.join(worktreePath, relative);
+}
+async function writeExcludeBlock(worktreePath) {
+    const excludePath = await excludePathOf(worktreePath);
+    if (!excludePath)
+        return;
+    const held = existsSync(excludePath) ? await readFile(excludePath, "utf8") : "";
+    if (held.includes(DESKTOP_AGENT_EXCLUDE_START))
+        return;
+    await mkdir(path.dirname(excludePath), { recursive: true });
+    const block = [DESKTOP_AGENT_EXCLUDE_START, MARKER_RELATIVE, DESKTOP_AGENT_EXCLUDE_END].join("\n");
+    await writeFile(excludePath, `${held.replace(/\n*$/, held ? "\n" : "")}${block}\n`);
+}
+export async function ensureBinding(worktreePath, request) {
+    const own = await readBindingMarker(worktreePath);
+    if (own)
+        return own.projectId === request.projectId;
+    const person = await readBindingMarker(request.checkoutPath);
+    if (!person || person.projectId !== request.projectId)
+        return false;
+    await mkdir(path.dirname(projectJsonPath(worktreePath)), { recursive: true });
+    await copyFile(projectJsonPath(request.checkoutPath), projectJsonPath(worktreePath));
+    await writeExcludeBlock(worktreePath);
+    return true;
+}
+export function mountAnswerOf(lastLine) {
+    let envelope = null;
+    try {
+        envelope = lastLine ? JSON.parse(lastLine) : null;
+    }
+    catch {
+        envelope = null;
+    }
+    if (envelope?.ok === true)
+        return { proceed: true, mount: "nustack", line: null };
+    const code = typeof envelope?.error?.code === "string" ? envelope.error.code : "HARNESS_MOUNT_FAILED";
+    const message = typeof envelope?.error?.message === "string" ? envelope.error.message : "the mount printed no envelope";
+    if (code === HARNESS_CODES.HARNESS_UNAVAILABLE)
+        return { proceed: true, mount: "none", line: `harness: no version to mount yet (${message})` };
+    if (code === HARNESS_CODES.ETNA_MOUNT_PRESENT)
+        return { proceed: true, mount: "etna", line: `harness: etna's committed mount hook runs inside the session (${message})` };
+    return { proceed: false, code, line: `harness: mount failed ${code}: ${message}` };
+}
+export async function mountHarness(worktreePath, env) {
+    const lastLine = await new Promise((resolve) => {
+        const child = spawn(process.execPath, [CLI_ENTRY, "harness", "mount", worktreePath, "--json"], { cwd: worktreePath, env, stdio: ["ignore", "pipe", "ignore"] });
+        let stdout = "";
+        child.stdout.on("data", (chunk) => (stdout += chunk.toString("utf8")));
+        child.on("error", () => resolve(null));
+        child.on("close", () => {
+            const lines = stdout.split("\n").map((line) => line.trim()).filter((line) => line !== "");
+            resolve(lines.at(-1) ?? null);
+        });
+    });
+    return mountAnswerOf(lastLine);
+}
+export function cliEntry() {
+    return CLI_ENTRY;
+}

package/dist/lib/desktop-agents/claudeRun.js

@@ -0,0 +1,265 @@
+import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { DEVICE_TOKEN_VARIABLE, RECORD_CREDENTIAL_VARIABLE, SESSION_ID_VARIABLE } from "../records/environment.js";
+import { cliEntry } from "./checkout.js";
+export const DESKTOP_AGENT_NUSTACK_VERBS = ["nustack records emit *", "nustack obligation add *", "nustack obligation discharge *", "nustack backlog add *"];
+const REVIEW_NUSTACK_VERBS = ["nustack obligation add *", "nustack obligation discharge *"];
+const STRIPPED_FOR_MODEL = [DEVICE_TOKEN_VARIABLE, "NUSTACK_API_BASE_URL", SESSION_ID_VARIABLE, RECORD_CREDENTIAL_VARIABLE];
+const LOCAL_MODEL_KEYS = ["ANTHROPIC_MODEL", "ANTHROPIC_DEFAULT_OPUS_MODEL", "ANTHROPIC_DEFAULT_SONNET_MODEL", "ANTHROPIC_DEFAULT_HAIKU_MODEL", "CLAUDE_CODE_SUBAGENT_MODEL"];
+export const DESKTOP_AGENT_SANDBOX_DENY_READ = [
+    "~/.ssh",
+    "~/.aws",
+    "~/.config",
+    "~/Library",
+    "~/.claude-manager",
+    "~/.nustack/credentials.json",
+    "~/.nustack/device.json",
+    "~/.nustack/device_id",
+    "~/.nustack/local-engine.json",
+    "~/.nustack/recovery",
+    "~/.nustack/cache",
+    "~/Library/Application Support/co.nurix.nustack",
+];
+export function absoluteRule(absolutePath) {
+    return `//${absolutePath.replace(/^\/+/, "")}`;
+}
+export function readTools(checkout) {
+    const scope = `${absoluteRule(checkout)}/**`;
+    return [`Read(${scope})`, `Glob(${scope})`, `Grep(${scope})`];
+}
+const GIT_READ_FORMS = ["Bash(git status)", "Bash(git status *)", "Bash(git diff)", "Bash(git diff *)", "Bash(git log)", "Bash(git log *)"];
+export function allowedTools(checkout) {
+    const scope = `${absoluteRule(checkout)}/**`;
+    return [
+        ...readTools(checkout),
+        `Edit(${scope})`,
+        `Write(${scope})`,
+        ...GIT_READ_FORMS,
+        "Bash(git add *)",
+        "Bash(git commit -m *)",
+        ...DESKTOP_AGENT_NUSTACK_VERBS.map((verb) => `Bash(${verb})`),
+    ];
+}
+export function reviewTools(checkout) {
+    return [...readTools(checkout), ...GIT_READ_FORMS, ...REVIEW_NUSTACK_VERBS.map((verb) => `Bash(${verb})`)];
+}
+export function deniedTools(checkout) {
+    const gitDir = `${absoluteRule(checkout)}/.git/**`;
+    return [
+        `Edit(${gitDir})`,
+        `Write(${gitDir})`,
+        "Bash(git push *)",
+        "Bash(git -C *)",
+        "Bash(git -c *)",
+        "Bash(git --git-dir*)",
+        "Bash(git --work-tree*)",
+        "Bash(git diff --no-index*)",
+        "Bash(git commit -F*)",
+        "Bash(git commit --file*)",
+        "Bash(git commit -t*)",
+        "Bash(git commit --template*)",
+        "Bash(git * --output*)",
+        "Bash(nustack records list*)",
+        "Bash(nustack obligation list*)",
+        "Read(~/.ssh/**)",
+        "Read(~/.aws/**)",
+        "Read(~/.config/**)",
+        "Read(~/Library/**)",
+        "Read(~/.claude-manager/**)",
+        "Read(~/.nustack/*.db)",
+        "Read(~/.nustack/credentials.json)",
+        "Read(~/.nustack/device.json)",
+        "Read(~/.nustack/device_id)",
+        "Read(~/.nustack/local-engine.json)",
+    ];
+}
+export function realCheckout(checkout) {
+    try {
+        return realpathSync(checkout);
+    }
+    catch {
+        return checkout;
+    }
+}
+export function sandboxSettings(inputs) {
+    const home = realCheckout(inputs.home);
+    const nustackHome = path.join(home, ".nustack");
+    const expand = (entry) => (entry.startsWith("~/") ? path.join(home, entry.slice(2)) : entry);
+    return {
+        sandbox: {
+            enabled: true,
+            failIfUnavailable: true,
+            allowUnsandboxedCommands: false,
+            autoAllowBashIfSandboxed: false,
+            filesystem: {
+                allowWrite: [
+                    inputs.checkout,
+                    path.join(inputs.gitCommonDir, "objects"),
+                    path.join(inputs.gitCommonDir, "refs"),
+                    path.join(inputs.gitCommonDir, "logs"),
+                    inputs.worktreeGitDir,
+                    path.join(nustackHome, "state.db"),
+                    path.join(nustackHome, "state.db-wal"),
+                    path.join(nustackHome, "state.db-shm"),
+                    path.join(nustackHome, "locks"),
+                    path.join(nustackHome, "session-events"),
+                ],
+                denyRead: DESKTOP_AGENT_SANDBOX_DENY_READ.map(expand),
+            },
+            network: { allowedDomains: inputs.nustackHost ? [inputs.nustackHost] : [] },
+        },
+    };
+}
+export function runSettings(request, inputs, env) {
+    const settings = sandboxSettings(inputs);
+    if (request.engine === "local_model") {
+        const block = {};
+        for (const key of LOCAL_MODEL_KEYS) {
+            const value = env[key];
+            if (value)
+                block[key] = value;
+        }
+        settings.env = block;
+    }
+    return settings;
+}
+export function modelOf(request, env) {
+    if (request.engine === "local_model")
+        return env.ANTHROPIC_MODEL ?? request.agent.model;
+    return request.agent.model;
+}
+export function claudeArgs(request, inputs, env) {
+    const allowed = request.toolProfile === "review" ? reviewTools(inputs.checkout) : allowedTools(inputs.checkout);
+    const args = [
+        "-p",
+        "--no-session-persistence",
+        "--output-format",
+        "stream-json",
+        "--verbose",
+        "--permission-mode",
+        "dontAsk",
+        "--allowedTools",
+        allowed.join(","),
+        "--disallowedTools",
+        deniedTools(inputs.checkout).join(","),
+    ];
+    const model = modelOf(request, env);
+    if (model)
+        args.push("--model", model);
+    args.push("--settings", JSON.stringify(runSettings(request, inputs, env)));
+    if (request.budgetCents !== null)
+        args.push("--max-budget-usd", (request.budgetCents / 100).toFixed(2));
+    return args;
+}
+export function claudeEnv(request, inherited, binDir) {
+    const env = { ...inherited };
+    for (const name of STRIPPED_FOR_MODEL)
+        delete env[name];
+    if (request.sessionId !== null) {
+        env[SESSION_ID_VARIABLE] = request.sessionId;
+        env[RECORD_CREDENTIAL_VARIABLE] = "device";
+    }
+    env.PATH = [binDir, inherited.PATH ?? ""].filter((part) => part !== "").join(path.delimiter);
+    return env;
+}
+export function engineFits(request, init, env) {
+    if (request.engine === "api_key")
+        return init.apiKeySource === null || init.apiKeySource === "ANTHROPIC_API_KEY";
+    if (request.engine === "seat")
+        return init.apiKeySource === null || init.apiKeySource === "none";
+    const expected = modelOf(request, env);
+    return init.model === null || expected === null || init.model === expected;
+}
+const KILL_GRACE_MS = 3_000;
+export function runClaude(request, args, env, cwd, prompt) {
+    return new Promise((resolve) => {
+        const child = spawn(env.NUSTACK_CLAUDE_BIN ?? "claude", args, { cwd, env, stdio: ["pipe", "pipe", "pipe"], detached: true });
+        let vendorSessionId = null;
+        let costCents = 0;
+        let sawResult = false;
+        let isResultError = false;
+        let killedFor = null;
+        const engineCheck = { apiKeySource: null, model: null };
+        let settled = false;
+        const killGroup = (reason) => {
+            if (killedFor)
+                return;
+            killedFor = reason;
+            const signal = (sig) => {
+                try {
+                    if (child.pid)
+                        process.kill(-child.pid, sig);
+                }
+                catch {
+                }
+            };
+            signal("SIGTERM");
+            setTimeout(() => signal("SIGKILL"), KILL_GRACE_MS).unref();
+        };
+        const wall = setTimeout(() => killGroup("wall_clock"), request.wallSeconds * 1000);
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(wall);
+            let reason = killedFor;
+            if (!reason && (code !== 0 || !sawResult || isResultError))
+                reason = "model_failed";
+            resolve({ reason, vendorSessionId, costCents, engineCheck });
+        };
+        child.on("error", () => finish(null));
+        child.on("close", (code) => finish(code));
+        child.stderr.on("data", () => {
+        });
+        createInterface({ input: child.stdout }).on("line", (line) => {
+            let frame;
+            try {
+                const parsed = JSON.parse(line);
+                if (typeof parsed !== "object" || parsed === null)
+                    return;
+                frame = parsed;
+            }
+            catch {
+                return;
+            }
+            if (frame.type === "system" && frame.subtype === "init") {
+                if (typeof frame.session_id === "string")
+                    vendorSessionId = frame.session_id;
+                engineCheck.apiKeySource = typeof frame.apiKeySource === "string" ? frame.apiKeySource : null;
+                engineCheck.model = typeof frame.model === "string" ? frame.model : null;
+                if (!engineFits(request, engineCheck, env))
+                    killGroup("engine_mismatch");
+            }
+            if (frame.type === "result") {
+                sawResult = true;
+                isResultError = frame.is_error === true;
+                if (typeof frame.total_cost_usd === "number")
+                    costCents = Math.round(frame.total_cost_usd * 100);
+                if (typeof frame.session_id === "string" && !vendorSessionId)
+                    vendorSessionId = frame.session_id;
+            }
+        });
+        child.stdin.on("error", () => {
+        });
+        child.stdin.end(prompt);
+    });
+}
+export function gitDirsOf(gitCommonDirOutput, gitDirOutput, worktree) {
+    const absolute = (value) => realCheckout(path.isAbsolute(value) ? value : path.join(worktree, value));
+    return { gitCommonDir: absolute(gitCommonDirOutput), worktreeGitDir: absolute(gitDirOutput) };
+}
+export function syncRecords(env, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [cliEntry(), "records", "sync", "--json"], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+        let output = "";
+        child.stdout.on("data", (chunk) => (output += chunk.toString("utf8")));
+        child.on("error", () => resolve({ code: null, output }));
+        child.on("close", (code) => resolve({ code, output: output.trim() }));
+    });
+}
+export function homeOf(env) {
+    return env.HOME ?? os.homedir();
+}

package/dist/lib/desktop-agents/prompt.js

@@ -0,0 +1,47 @@
+export const LOCAL_ROWS_MAX = 50;
+export const LOCAL_DISMISSALS_MAX = 20;
+export const PREFILLED_PROMPT_MAX_CHARS = 8_000;
+export const LOCAL_TASK_TEMPLATES = {
+    distillation: "Distill the device-kept memory rows below into durable project memory. Edit the memory documents in this checkout, then commit. Nothing is pushed; the person approves the proposal.",
+    boundary_security_reviewer: "Review the open device-kept security findings below against this checkout. For each, discharge the obligation with your verdict through `nustack obligation discharge`, weighing the past dismissals. Do not edit or commit.",
+};
+const BRANCH_RULE = "Work on the current branch and commit here with `git commit -m`; never push. Write records only through the `nustack` record verbs.";
+function section(title, body) {
+    if (!body || body.trim() === "")
+        return null;
+    return `## ${title}\n\n${body.trim()}`;
+}
+function rowsSection(title, rows, max) {
+    if (!rows || rows.length === 0)
+        return null;
+    const kept = rows.slice(0, max).map((row) => `- ${JSON.stringify(row)}`);
+    return `## ${title}\n\n${kept.join("\n")}`;
+}
+function taskOf(request) {
+    const mandate = request.agent.mandate?.trim();
+    const task = request.task.trim();
+    if (mandate && task.startsWith(mandate))
+        return task.slice(mandate.length).trim();
+    if (task !== "")
+        return request.task;
+    const template = LOCAL_TASK_TEMPLATES[request.agent.slug];
+    return request.localRows !== undefined && template ? template : request.task;
+}
+function bodySections(request) {
+    const isReviewer = request.agent.slug === "boundary_security_reviewer";
+    return [
+        section("Mandate", request.agent.mandate),
+        section("Task", taskOf(request)),
+        section("Branch rule", BRANCH_RULE),
+        rowsSection("Device rows", request.localRows, LOCAL_ROWS_MAX),
+        isReviewer ? rowsSection("Past device dismissals", request.dismissals, LOCAL_DISMISSALS_MAX) : null,
+    ].filter((part) => part !== null);
+}
+export function composePrompt(request) {
+    const body = bodySections(request).join("\n\n");
+    const instructions = section("Instructions", request.instructions);
+    const whole = instructions ? `${instructions}\n\n${body}` : body;
+    if (whole.length <= PREFILLED_PROMPT_MAX_CHARS)
+        return whole;
+    return body.slice(0, PREFILLED_PROMPT_MAX_CHARS);
+}

package/dist/lib/desktop-agents/publish.js

@@ -0,0 +1,98 @@
+import { execFile } from "node:child_process";
+import { gitOutcome } from "../session-engine/worktree.js";
+import { proposalBranchName } from "./checkout.js";
+const PUSH_TIMEOUT_MS = 5 * 60_000;
+const PULL_REQUEST_URL = /https?:\/\/\S+\/pull\/(\d+)/;
+export function commitSubject(label, task) {
+    const first = task.split("\n").find((line) => line.trim() !== "")?.trim() ?? "agent run";
+    return `${label}: ${first}`.slice(0, 120);
+}
+async function gitOk(args, cwd, timeoutMs) {
+    return (await gitOutcome(args, cwd, timeoutMs)).ok;
+}
+async function commitLeftovers(worktree, subject) {
+    const status = await gitOutcome(["status", "--porcelain"], worktree);
+    if (!status.ok || status.stdout === "")
+        return;
+    await gitOutcome(["add", "-A"], worktree);
+    await gitOutcome(["commit", "-m", subject], worktree);
+}
+async function commitsAhead(worktree, base) {
+    const counted = await gitOutcome(["rev-list", "--count", `origin/${base}..HEAD`], worktree);
+    return counted.ok ? Number(counted.stdout) || 0 : 0;
+}
+async function dropLocalBranch(worktree, branch) {
+    await gitOutcome(["checkout", "--detach"], worktree);
+    await gitOutcome(["branch", "-D", branch], worktree);
+}
+function openPullRequest(cwd, args, env) {
+    return new Promise((resolve) => {
+        try {
+            execFile("gh", ["pr", "create", "--base", args.base, "--head", args.head, "--title", args.title, "--body", args.body], { cwd, env, timeout: PUSH_TIMEOUT_MS }, (error, stdout) => {
+                if (error)
+                    return resolve(null);
+                const match = PULL_REQUEST_URL.exec(stdout);
+                resolve(match ? { url: match[0], number: Number(match[1]) } : null);
+            });
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+async function pushAndOpen(worktree, branch, base, title, body, env) {
+    if (!(await gitOk(["push", "-u", "origin", branch], worktree, PUSH_TIMEOUT_MS)))
+        return null;
+    const opened = await openPullRequest(worktree, { base, head: branch, title, body }, env);
+    return addressOf(branch, opened);
+}
+export function addressOf(branch, opened) {
+    if (!opened)
+        return { result: { kind: "branch", ref: branch }, pullRequestUrl: null };
+    return { result: { kind: "pull_request", ref: branch, number: opened.number }, pullRequestUrl: opened.url };
+}
+export function pullRequestNumberOf(url) {
+    const match = PULL_REQUEST_URL.exec(url);
+    return match ? Number(match[1]) : null;
+}
+export async function publishRun(request, worktree, branch, base, body, env) {
+    if (request.publish === "none") {
+        await gitOutcome(["reset", "--hard"], worktree);
+        await dropLocalBranch(worktree, branch);
+        return { result: null, pullRequestUrl: null };
+    }
+    const subject = commitSubject(request.agent.label, request.task);
+    await commitLeftovers(worktree, subject);
+    if ((await commitsAhead(worktree, base)) === 0) {
+        await dropLocalBranch(worktree, branch);
+        return { result: null, pullRequestUrl: null };
+    }
+    if (request.publish === "local") {
+        await gitOutcome(["checkout", "--detach"], worktree);
+        return { result: { kind: "branch", ref: branch }, pullRequestUrl: null };
+    }
+    const published = await pushAndOpen(worktree, branch, base, subject, body, env);
+    if (!published) {
+        await gitOutcome(["checkout", "--detach"], worktree);
+        return { result: { kind: "branch", ref: branch }, pullRequestUrl: null };
+    }
+    await dropLocalBranch(worktree, branch);
+    return published;
+}
+function slugOf(branch, runId) {
+    const parts = branch.split("/");
+    return parts.length >= 2 && parts.at(-1) === runId ? (parts.at(-2) ?? "agent") : "agent";
+}
+export async function publishProposal(request, env) {
+    const proposal = proposalBranchName(slugOf(request.branch, request.runId), request.runId);
+    if (!(await gitOk(["branch", "-M", request.branch, proposal], request.checkoutPath)))
+        return null;
+    const body = `Memory proposal from a desktop distillation run (${request.runId}), approved on this device.`;
+    const published = await pushAndOpen(request.checkoutPath, proposal, request.base, request.title, body, env);
+    if (published)
+        await gitOutcome(["branch", "-D", proposal], request.checkoutPath);
+    return published;
+}
+export async function discardProposal(request) {
+    return gitOk(["branch", "-D", request.branch], request.checkoutPath);
+}

package/dist/lib/desktop-agents/request.js

@@ -0,0 +1,152 @@
+export const DESKTOP_AGENT_REQUEST_VERSION = 1;
+export const DESKTOP_AGENT_REFUSAL_CODES = ["REQUEST_INVALID", "REQUEST_VERSION_UNSUPPORTED"];
+export const DESKTOP_AGENT_RUN_REASONS = [
+    "checkout_unbound",
+    "harness_unmounted",
+    "wall_clock",
+    "engine_mismatch",
+    "model_failed",
+    "app_exit",
+    "cli_output_unreadable",
+];
+export const DESKTOP_AGENT_REF_SEGMENT = /^[A-Za-z0-9_-]+$/;
+export const DESKTOP_AGENT_PR_BASES = ["change", "default"];
+export const DESKTOP_AGENT_PUBLISH_MODES = ["push", "local", "none"];
+export const DESKTOP_AGENT_TOOL_PROFILES = ["change", "review"];
+export const DESKTOP_AGENT_ENGINES = ["api_key", "local_model", "seat"];
+export const DESKTOP_AGENT_MOUNT_VALUES = ["nustack", "none", "etna"];
+function invalid(field, expected) {
+    return { ok: false, code: "REQUEST_INVALID", message: `${field} must be ${expected}.` };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function isNullableString(value) {
+    return value === null || typeof value === "string";
+}
+function oneOf(values, value) {
+    return typeof value === "string" && values.includes(value);
+}
+function readVersion(raw) {
+    if (typeof raw.requestVersion !== "number" || !Number.isInteger(raw.requestVersion))
+        return invalid("requestVersion", "an integer");
+    if (raw.requestVersion !== DESKTOP_AGENT_REQUEST_VERSION) {
+        return { ok: false, code: "REQUEST_VERSION_UNSUPPORTED", message: `requestVersion ${raw.requestVersion} is not supported; this CLI reads ${DESKTOP_AGENT_REQUEST_VERSION}.` };
+    }
+    return null;
+}
+export function parseRunRequest(raw) {
+    if (!isRecord(raw))
+        return invalid("the request", "a JSON object");
+    const version = readVersion(raw);
+    if (version)
+        return version;
+    if (!isNonEmptyString(raw.runId) || !DESKTOP_AGENT_REF_SEGMENT.test(raw.runId))
+        return invalid("runId", "a string of letters, digits, '_' or '-'");
+    if (!isNonEmptyString(raw.projectId))
+        return invalid("projectId", "a non-empty string");
+    if (!(raw.sessionId === null || isNonEmptyString(raw.sessionId)))
+        return invalid("sessionId", "a non-empty string or null");
+    if (!isNonEmptyString(raw.checkoutPath))
+        return invalid("checkoutPath", "a non-empty string");
+    const agent = raw.agent;
+    if (!isRecord(agent))
+        return invalid("agent", "an object");
+    if (!isNonEmptyString(agent.slug) || !DESKTOP_AGENT_REF_SEGMENT.test(agent.slug))
+        return invalid("agent.slug", "a string of letters, digits, '_' or '-'");
+    if (!isNonEmptyString(agent.label))
+        return invalid("agent.label", "a non-empty string");
+    if (!isNullableString(agent.mandate))
+        return invalid("agent.mandate", "a string or null");
+    if (!isNullableString(agent.model))
+        return invalid("agent.model", "a string or null");
+    if (typeof raw.task !== "string")
+        return invalid("task", "a string");
+    if (!isNullableString(raw.instructions))
+        return invalid("instructions", "a string or null");
+    if (raw.localRows !== undefined && !(Array.isArray(raw.localRows) && raw.localRows.every(isRecord)))
+        return invalid("localRows", "an array of objects");
+    if (raw.dismissals !== undefined && !(Array.isArray(raw.dismissals) && raw.dismissals.every(isRecord)))
+        return invalid("dismissals", "an array of objects");
+    if (!oneOf(DESKTOP_AGENT_PR_BASES, raw.prBase))
+        return invalid("prBase", `one of ${DESKTOP_AGENT_PR_BASES.join(", ")}`);
+    if (!oneOf(DESKTOP_AGENT_PUBLISH_MODES, raw.publish))
+        return invalid("publish", `one of ${DESKTOP_AGENT_PUBLISH_MODES.join(", ")}`);
+    if (!oneOf(DESKTOP_AGENT_TOOL_PROFILES, raw.toolProfile))
+        return invalid("toolProfile", `one of ${DESKTOP_AGENT_TOOL_PROFILES.join(", ")}`);
+    if (!oneOf(DESKTOP_AGENT_ENGINES, raw.engine))
+        return invalid("engine", `one of ${DESKTOP_AGENT_ENGINES.join(", ")}`);
+    if (!(raw.budgetCents === null || (typeof raw.budgetCents === "number" && Number.isInteger(raw.budgetCents) && raw.budgetCents >= 0))) {
+        return invalid("budgetCents", "a whole number of cents or null");
+    }
+    if (typeof raw.wallSeconds !== "number" || !Number.isInteger(raw.wallSeconds) || raw.wallSeconds <= 0)
+        return invalid("wallSeconds", "a positive whole number");
+    return {
+        ok: true,
+        value: {
+            requestVersion: DESKTOP_AGENT_REQUEST_VERSION,
+            runId: raw.runId,
+            projectId: raw.projectId,
+            sessionId: raw.sessionId,
+            checkoutPath: raw.checkoutPath,
+            agent: { slug: agent.slug, label: agent.label, mandate: agent.mandate, model: agent.model },
+            task: raw.task,
+            instructions: raw.instructions,
+            ...(raw.localRows ? { localRows: raw.localRows } : {}),
+            ...(raw.dismissals ? { dismissals: raw.dismissals } : {}),
+            prBase: raw.prBase,
+            publish: raw.publish,
+            toolProfile: raw.toolProfile,
+            engine: raw.engine,
+            budgetCents: raw.budgetCents,
+            wallSeconds: raw.wallSeconds,
+        },
+    };
+}
+export function parseProposalRequest(raw) {
+    if (!isRecord(raw))
+        return invalid("the request", "a JSON object");
+    const version = readVersion(raw);
+    if (version)
+        return version;
+    if (!isNonEmptyString(raw.runId) || !DESKTOP_AGENT_REF_SEGMENT.test(raw.runId))
+        return invalid("runId", "a string of letters, digits, '_' or '-'");
+    if (!isNonEmptyString(raw.projectId))
+        return invalid("projectId", "a non-empty string");
+    if (!isNonEmptyString(raw.checkoutPath))
+        return invalid("checkoutPath", "a non-empty string");
+    if (!isNonEmptyString(raw.branch))
+        return invalid("branch", "a non-empty string");
+    if (!isNonEmptyString(raw.base))
+        return invalid("base", "a non-empty string");
+    if (typeof raw.title !== "string")
+        return invalid("title", "a string");
+    return {
+        ok: true,
+        value: {
+            requestVersion: DESKTOP_AGENT_REQUEST_VERSION,
+            runId: raw.runId,
+            projectId: raw.projectId,
+            checkoutPath: raw.checkoutPath,
+            branch: raw.branch,
+            base: raw.base,
+            title: raw.title,
+        },
+    };
+}
+export function failedResult(reason, mount, partial = {}) {
+    return {
+        outcome: "failed",
+        reason,
+        vendorSessionId: null,
+        costCents: 0,
+        result: null,
+        pullRequestUrl: null,
+        engineCheck: { apiKeySource: null, model: null },
+        mount,
+        ...partial,
+    };
+}

package/dist/program.js

@@ -38,6 +38,7 @@ import { registerSessionCommands } from "./commands/session.js";
 import { isPartCheckStale, startTelemetryReconcile } from "./lib/telemetry/part_state.js";
 import { RECORD_ALIAS_GROUPS, registerRecordAliases } from "./commands/recordAliases.js";
 import { runAgentContext, runAgentHookInstall, runAgentHookRemove } from "./commands/agent.js";
+import { runDesktopAgentDiscard, runDesktopAgentPrompt, runDesktopAgentPublish, runDesktopAgentRun } from "./commands/desktopAgent.js";
 import { runCensus } from "./commands/census.js";
 import { runGateInstall, runGateRemove, runGateStatus } from "./commands/gate.js";
 import { parseBudgetMs, parseLineWindow, runReadBulk } from "./commands/read.js";
@@ -373,6 +374,27 @@ agentHook
     .command("remove")
     .description("Remove exactly the managed SessionStart hook entry")
     .action(async () => runAgentHookRemove());
+const desktopAgent = program.command("desktop-agent").description("Run a device-placed agent for the NuStack desktop (stdin request, JSON envelope)");
+desktopAgent
+    .command("run")
+    .description("Run one desktop agent request read on stdin in the agent's own checkout")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async () => runDesktopAgentRun());
+desktopAgent
+    .command("prompt")
+    .description("Print the pre-filled prompt for a desktop agent request read on stdin")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async () => runDesktopAgentPrompt());
+desktopAgent
+    .command("publish")
+    .description("Push an approved memory proposal's branch as a pull request")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async () => runDesktopAgentPublish());
+desktopAgent
+    .command("discard")
+    .description("Delete a discarded memory proposal's local branch")
+    .option("--json", "emit the versioned machine envelope")
+    .action(async () => runDesktopAgentDiscard());
 program
     .command("census")
     .description("Measure where your Claude Code tokens go, from your own transcripts, and recommend the large-read gate's threshold")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/nustack",
-  "version": "0.23.18",
+  "version": "0.23.20",
   "description": "The nustack CLI — bootstrap NuStack services into a repo via the NuStack discovery plane.",
   "type": "module",
   "private": false,
@@ -34,10 +34,10 @@
     "@types/node": "^22.19.20",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@nurix/contracts": "2.0.2",
     "@nurix/harness": "0.0.0",
     "@nurix/nustack.studio": "0.0.0",
-    "@nurix/nustack.ui": "0.0.0"
+    "@nurix/nustack.ui": "0.0.0",
+    "@nurix/contracts": "2.0.2"
   },
   "publishConfig": {
     "access": "public"