@nurix/nustack 0.10.0-dev.9 → 0.11.0

package/dist/lib/session-engine/supervisor.js

@@ -0,0 +1,321 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { ClaudeSession } from "./claudeAdapter.js";
+import { FRAME_VERSION, parseInboundFrame, serializeFrame, } from "./frames.js";
+import { inspectSession, reclaimSession } from "./prune.js";
+import { sessionRegistryPath, readSessionRegistry, updateSessionRegistry } from "./registry.js";
+import { createSessionWorktree } from "./worktree.js";
+function defaultProbeClaude(env) {
+    return new Promise((resolve) => {
+        execFile("claude", ["--version"], { env, timeout: 5_000 }, (error, stdout) => {
+            if (error)
+                resolve({ found: false, version: null });
+            else
+                resolve({ found: true, version: stdout.trim() });
+        });
+    });
+}
+export class SessionSupervisor {
+    options;
+    env;
+    sessions = new Map();
+    closingSessions = new Set();
+    shuttingDown = false;
+    resolveDone = null;
+    lines = null;
+    registryWrites = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        this.env = options.env ?? process.env;
+    }
+    emit(frame) {
+        this.options.output.write(serializeFrame(frame));
+    }
+    status(sessionId, status, message = null) {
+        this.emit({ v: FRAME_VERSION, type: "session.status", sessionId, status, message });
+    }
+    error(sessionId, code, message) {
+        this.emit({ v: FRAME_VERSION, type: "session.error", sessionId, code, message });
+    }
+    async boundProjectOf(projectPath) {
+        try {
+            const parsed = JSON.parse(await readFile(path.join(projectPath, ".nustack", "workspace.json"), "utf8"));
+            const id = parsed?.workspaceId;
+            return typeof id === "string" && id.trim() ? id.trim() : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async moveSessionRow(record, to) {
+        const client = this.options.sessions;
+        if (!client || !record.projectId)
+            return;
+        try {
+            await client.transitionSession(record.projectId, record.sessionId, to);
+        }
+        catch {
+        }
+    }
+    async updateRegistry(mutate) {
+        const run = () => updateSessionRegistry(this.env, mutate);
+        this.registryWrites = this.registryWrites.then(run, run);
+        return this.registryWrites;
+    }
+    async run() {
+        const probe = this.options.probeClaude ?? (() => defaultProbeClaude(this.env));
+        const claude = await probe();
+        this.emit({ v: FRAME_VERSION, type: "engine.hello", engineVersion: this.options.engineVersion, claude });
+        const lines = createInterface({ input: this.options.input });
+        this.lines = lines;
+        lines.on("line", (line) => {
+            if (line.trim() === "")
+                return;
+            const parsed = parseInboundFrame(line);
+            if (!parsed.ok) {
+                this.error(null, parsed.error.code, parsed.error.message);
+                return;
+            }
+            void this.handle(parsed.frame);
+        });
+        await new Promise((resolve) => {
+            this.resolveDone = resolve;
+            lines.on("close", () => void this.shutdown());
+        });
+    }
+    async handle(frame) {
+        switch (frame.type) {
+            case "engine.shutdown":
+                await this.shutdown();
+                return;
+            case "session.open":
+                await this.openSession(frame.sessionId, frame.projectPath, frame.permissionMode, frame.isolated, frame.resumeSessionId, frame.commit);
+                return;
+            case "session.turn": {
+                const session = this.sessions.get(frame.sessionId);
+                if (!session)
+                    return this.error(frame.sessionId, "SESSION_UNKNOWN", `no open session ${frame.sessionId}`);
+                session.adapter.sendTurn(frame.text);
+                this.status(frame.sessionId, "running");
+                return;
+            }
+            case "session.approval": {
+                const session = this.sessions.get(frame.sessionId);
+                if (!session)
+                    return this.error(frame.sessionId, "SESSION_UNKNOWN", `no open session ${frame.sessionId}`);
+                session.adapter.respondApproval(frame.requestId, frame.verdict);
+                return;
+            }
+            case "session.interrupt": {
+                const session = this.sessions.get(frame.sessionId);
+                if (!session)
+                    return this.error(frame.sessionId, "SESSION_UNKNOWN", `no open session ${frame.sessionId}`);
+                session.adapter.interrupt();
+                return;
+            }
+            case "session.close": {
+                const session = this.sessions.get(frame.sessionId);
+                if (!session)
+                    return this.error(frame.sessionId, "SESSION_UNKNOWN", `no open session ${frame.sessionId}`);
+                this.closingSessions.add(frame.sessionId);
+                session.adapter.stop();
+                return;
+            }
+            case "session.list":
+                await this.sendRoster();
+                return;
+            case "session.reclaim":
+                await this.reclaimRow(frame.sessionId);
+                return;
+        }
+    }
+    async openSession(sessionId, projectPath, permissionMode, isolated, resumeSessionId, commit) {
+        if (this.sessions.has(sessionId))
+            return this.error(sessionId, "SESSION_ALREADY_OPEN", `session ${sessionId} is already open`);
+        this.status(sessionId, "starting");
+        const worktree = await createSessionWorktree(projectPath, sessionId, this.env, isolated === true, commit);
+        if (worktree.commitRefusal !== null) {
+            this.error(sessionId, worktree.commitRefusal.code, worktree.commitRefusal.detail);
+            this.status(sessionId, "error", `could not open ${String(commit)}`);
+            return;
+        }
+        const record = {
+            sessionId,
+            projectPath,
+            worktreePath: worktree.worktreePath,
+            branch: worktree.branch,
+            provider: "claude-code",
+            providerSessionId: null,
+            createdAt: new Date().toISOString(),
+            status: "open",
+            nustack: 1,
+            projectId: await this.boundProjectOf(projectPath),
+            permissionMode: permissionMode ?? null,
+            baseBranch: worktree.baseBranch,
+            baseCommit: worktree.baseCommit,
+            enginePid: process.pid,
+            closedAt: null,
+        };
+        const adapterOptions = {
+            cwd: worktree.worktreePath,
+            permissionMode,
+            resumeSessionId,
+            env: this.env,
+            onEvent: (event) => {
+                this.emit({ v: FRAME_VERSION, type: "session.event", sessionId, event });
+                if (typeof event === "object" && event !== null && event.type === "result") {
+                    this.status(sessionId, "ready");
+                }
+            },
+            onApprovalRequest: (request) => {
+                this.emit({
+                    v: FRAME_VERSION,
+                    type: "session.approvalRequest",
+                    sessionId,
+                    requestId: request.requestId,
+                    toolName: request.toolName,
+                    displayName: request.displayName,
+                    toolInput: request.toolInput,
+                    description: request.description,
+                });
+            },
+            onProtocolError: (code, message) => this.error(sessionId, code, message),
+            onSessionId: (vendorSessionId) => {
+                record.providerSessionId = vendorSessionId;
+                void this.updateRegistry((sessions) => sessions.map((row) => (row.sessionId === sessionId ? { ...row, providerSessionId: vendorSessionId } : row)));
+                const client = this.options.sessions;
+                if (client && record.projectId) {
+                    void client.setVendorSessionId(record.projectId, sessionId, vendorSessionId).catch(() => undefined);
+                }
+            },
+            onExit: (code) => {
+                const wasExpected = this.closingSessions.delete(sessionId) || this.shuttingDown;
+                this.sessions.delete(sessionId);
+                if (!wasExpected)
+                    this.error(sessionId, "ADAPTER_FAILED", `claude exited unexpectedly (code ${String(code)})`);
+                this.emit({ v: FRAME_VERSION, type: "session.closed", sessionId });
+                void this.updateRegistry((sessions) => sessions.map((row) => row.sessionId === sessionId ? { ...row, status: "closed", closedAt: new Date().toISOString() } : row));
+                void this.moveSessionRow(record, wasExpected ? "done" : "failed");
+            },
+        };
+        const create = this.options.createAdapter ?? ((opts) => new ClaudeSession(opts));
+        let adapter;
+        try {
+            adapter = create(adapterOptions);
+        }
+        catch (error) {
+            return this.error(sessionId, "ADAPTER_FAILED", error instanceof Error ? error.message : String(error));
+        }
+        this.sessions.set(sessionId, { adapter, record });
+        await this.updateRegistry((sessions) => [...sessions.filter((row) => row.sessionId !== sessionId), record]);
+        if (this.options.sessions && record.projectId) {
+            try {
+                await this.options.sessions.createSession(record.projectId, {
+                    id: sessionId,
+                    startedBy: "person",
+                    substrate: "device",
+                    mode: "synchronous",
+                    nustack: 1,
+                    vendor: "claude_code",
+                    renderer: "claude_transcript",
+                    status: "created",
+                });
+            }
+            catch {
+            }
+        }
+        this.emit({
+            v: FRAME_VERSION,
+            type: "session.opened",
+            sessionId,
+            projectPath,
+            worktreePath: worktree.worktreePath,
+            branch: worktree.branch,
+            isolated: worktree.isolated,
+            commit: worktree.baseCommit,
+        });
+        this.status(sessionId, "ready");
+    }
+    async sendRoster() {
+        const { records, dropped } = await readSessionRegistry(this.env);
+        const rows = [];
+        for (const record of records) {
+            const attached = this.sessions.has(record.sessionId);
+            const facts = await inspectSession(record, this.env);
+            const reclaimable = !attached && facts.reclaimable;
+            const reason = attached ? "this engine is running it — close the session first" : facts.reason;
+            rows.push({
+                sessionId: record.sessionId,
+                projectPath: record.projectPath,
+                worktreePath: record.worktreePath,
+                branch: record.branch,
+                createdAt: record.createdAt,
+                status: record.status,
+                closedAt: record.closedAt ?? null,
+                permissionMode: record.permissionMode ?? null,
+                baseBranch: record.baseBranch ?? null,
+                attached,
+                liveElsewhere: !attached && record.status === "open" && typeof record.enginePid === "number" && !facts.stale,
+                isolated: facts.isolated,
+                checkoutPresent: facts.checkoutPresent,
+                worktreePresent: facts.worktreePresent,
+                branchExists: facts.branchExists,
+                reading: facts.reading,
+                dirty: facts.dirty,
+                stale: facts.stale,
+                reclaimable,
+                reason,
+            });
+        }
+        this.emit({
+            v: FRAME_VERSION,
+            type: "session.roster",
+            registryPath: sessionRegistryPath(this.env),
+            unreadable: dropped,
+            sessions: rows,
+        });
+    }
+    async reclaimRow(sessionId) {
+        if (this.sessions.has(sessionId)) {
+            return this.error(sessionId, "SESSION_ATTACHED", `session ${sessionId} is open in this engine — close it first`);
+        }
+        const { records } = await readSessionRegistry(this.env);
+        const record = records.find((row) => row.sessionId === sessionId);
+        if (!record)
+            return this.error(sessionId, "SESSION_UNKNOWN", `no session ${sessionId} in this machine's registry`);
+        const reclaim = this.registryWrites.then(() => reclaimSession(record, {}, this.env), () => reclaimSession(record, {}, this.env));
+        this.registryWrites = reclaim.then(() => undefined, () => undefined);
+        try {
+            const outcome = await reclaim;
+            this.emit({
+                v: FRAME_VERSION,
+                type: "session.reclaimed",
+                sessionId,
+                removedWorktree: outcome.removedWorktree,
+                deletedBranch: outcome.deletedBranch,
+                droppedRow: outcome.droppedRow,
+                reason: outcome.reason,
+            });
+        }
+        catch (error) {
+            this.error(sessionId, "RECLAIM_FAILED", error instanceof Error ? error.message : String(error));
+        }
+    }
+    async shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        const held = [...this.sessions.keys()];
+        for (const [, session] of this.sessions)
+            session.adapter.stop();
+        this.sessions.clear();
+        if (held.length > 0) {
+            const closedAt = new Date().toISOString();
+            await this.updateRegistry((sessions) => sessions.map((row) => (held.includes(row.sessionId) && row.status === "open" ? { ...row, status: "closed", closedAt } : row)));
+        }
+        this.lines?.close();
+        this.resolveDone?.();
+    }
+}

package/dist/lib/session-engine/worktree.js

@@ -0,0 +1,89 @@
+import { execFile } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export const ENGINE_SESSION_BRANCH_PREFIX = "nustack/session-";
+export function sessionsHome(env = process.env) {
+    const override = env.NUSTACK_SESSIONS_HOME;
+    if (override && override !== "")
+        return override;
+    return path.join(os.homedir(), ".nustack", "sessions");
+}
+export const LEGACY_ENGINE_BRANCH_PREFIX = "nustack/lane-";
+const FETCH_TIMEOUT_MS = 10 * 60_000;
+export function legacyEngineHome(env = process.env) {
+    const override = env.NUSTACK_LEGACY_ENGINE_HOME;
+    if (override && override !== "")
+        return override;
+    return path.join(os.homedir(), ".nustack", "lanes");
+}
+function git(args, cwd) {
+    return gitOutcome(args, cwd).then((outcome) => (outcome.ok ? outcome.stdout : null));
+}
+export function gitOutcome(args, cwd, timeoutMs = 15_000) {
+    return new Promise((resolve) => {
+        const failed = (error) => {
+            resolve({ ok: false, code: null, stdout: "", stderr: error instanceof Error ? error.message : String(error) });
+        };
+        try {
+            execFile("git", args, { cwd, timeout: timeoutMs }, (error, stdout, stderr) => {
+                const raw = error?.code;
+                const code = error ? (typeof raw === "number" ? raw : null) : 0;
+                resolve({ ok: !error, code, stdout: stdout.trim(), stderr: stderr.trim() });
+            });
+        }
+        catch (error) {
+            failed(error);
+        }
+    });
+}
+export async function createSessionWorktree(projectPath, sessionId, env = process.env, isolate = false, commit) {
+    const inPlace = {
+        worktreePath: projectPath,
+        branch: null,
+        isolated: false,
+        baseBranch: null,
+        baseCommit: null,
+        commitRefusal: null,
+    };
+    if (!isolate && commit === undefined)
+        return inPlace;
+    const isRepo = await git(["rev-parse", "--is-inside-work-tree"], projectPath);
+    if (isRepo !== "true") {
+        return commit === undefined
+            ? inPlace
+            : { ...inPlace, commitRefusal: { code: "COMMIT_UNREACHABLE", detail: `${projectPath} is not a git checkout, so ${commit} cannot be opened here.` } };
+    }
+    if (commit !== undefined) {
+        const refusal = await fetchCommit(projectPath, commit);
+        if (refusal !== null)
+            return { ...inPlace, commitRefusal: refusal };
+    }
+    const head = await git(["rev-parse", "--abbrev-ref", "HEAD"], projectPath);
+    const baseBranch = head === null || head === "HEAD" ? null : head;
+    const branch = `${ENGINE_SESSION_BRANCH_PREFIX}${sessionId}`;
+    const worktreePath = path.join(sessionsHome(env), "worktrees", sessionId);
+    await mkdir(path.dirname(worktreePath), { recursive: true });
+    const added = await git(commit === undefined
+        ? ["worktree", "add", worktreePath, "-b", branch]
+        : ["worktree", "add", worktreePath, "-b", branch, commit], projectPath);
+    if (added === null) {
+        return commit === undefined
+            ? inPlace
+            : { ...inPlace, commitRefusal: { code: "COMMIT_UNREACHABLE", detail: `git refused a worktree for ${commit} in ${projectPath}.` } };
+    }
+    const baseCommit = await git(["rev-parse", "HEAD"], worktreePath);
+    return { worktreePath, branch, isolated: true, baseBranch, baseCommit, commitRefusal: null };
+}
+async function fetchCommit(projectPath, commit) {
+    const has = () => gitOutcome(["cat-file", "-e", `${commit}^{commit}`], projectPath);
+    if ((await has()).ok)
+        return null;
+    let fetched = await gitOutcome(["fetch", "origin", commit], projectPath, FETCH_TIMEOUT_MS);
+    if (!fetched.ok)
+        fetched = await gitOutcome(["fetch", "origin"], projectPath, FETCH_TIMEOUT_MS);
+    if ((await has()).ok)
+        return null;
+    const said = `${fetched.stderr}\n${fetched.stdout}`.trim();
+    return { code: "COMMIT_UNREACHABLE", detail: said === "" ? `${commit} is not in this checkout and origin did not have it.` : said };
+}

package/dist/lib/session_telemetry.js

@@ -44,7 +44,7 @@ function toTelemetryBinding(binding, deviceRef, userId) {
         bindingId: binding.id,
         repoRoot: binding.repositoryRoot,
         organizationId: binding.organizationId,
-        workspaceId: binding.workspaceId,
+        projectId: binding.projectId,
         deviceRef,
         userId,
     };
@@ -122,7 +122,7 @@ export async function ensureBindingTelemetry(opts) {
         }
         let brokerFailure = null;
         const credential = await fetchBrokeredCredential(baseUrl, auth.accessToken, {
-            workspaceId: binding.workspaceId,
+            projectId: binding.projectId,
             service: TELEMETRY_SERVICE,
         }).catch((error) => {
             brokerFailure = error instanceof Error ? error.message : String(error);

package/dist/lib/sessions/client.js

@@ -23,19 +23,19 @@ export function makeSessionsClient(baseUrl, accessToken) {
         return { status: response.status, session: payload.data };
     }
     return {
-        async createSession(workspaceId, input) {
-            const safeId = assertSafeOpaqueId("The Workspace id", workspaceId);
-            const answered = await post(`/api/v2/workspaces/${encodeURIComponent(safeId)}/sessions`, input, "session create failed");
+        async createSession(projectId, input) {
+            const safeId = assertSafeOpaqueId("The Project id", projectId);
+            const answered = await post(`/api/v2/projects/${encodeURIComponent(safeId)}/sessions`, input, "session create failed");
             return { created: answered.status === 201, session: answered.session };
         },
-        async transitionSession(workspaceId, sessionId, to, patch = {}) {
-            const safeWorkspace = assertSafeOpaqueId("The Workspace id", workspaceId);
+        async transitionSession(projectId, sessionId, to, patch = {}) {
+            const safeProject = assertSafeOpaqueId("The Project id", projectId);
             const safeSession = assertSafeOpaqueId("The session id", sessionId);
-            const answered = await post(`/api/v2/workspaces/${encodeURIComponent(safeWorkspace)}/sessions/${encodeURIComponent(safeSession)}/transition`, { to, ...patch }, "session transition failed");
+            const answered = await post(`/api/v2/projects/${encodeURIComponent(safeProject)}/sessions/${encodeURIComponent(safeSession)}/transition`, { to, ...patch }, "session transition failed");
             return answered.session;
         },
-        async setVendorSessionId(workspaceId, sessionId, vendorSessionId) {
-            return this.transitionSession(workspaceId, sessionId, "running", { vendorSessionId });
+        async setVendorSessionId(projectId, sessionId, vendorSessionId) {
+            return this.transitionSession(projectId, sessionId, "running", { vendorSessionId });
         },
     };
 }

package/dist/lib/sessions/outsideSessions.js

@@ -9,10 +9,10 @@ function vendorOf(provider) {
 const AT_REST = new Set(["done", "failed", "cancelled"]);
 export async function recordOutsideSessions(client, input) {
     const now = input.now ?? Date.now;
-    const laneIds = new Set((input.laneSessionIds ?? []).filter((id) => Boolean(id)));
+    const engineIds = new Set((input.engineSessionIds ?? []).filter((id) => Boolean(id)));
     const report = { created: 0, finished: 0, skipped: 0, failed: 0 };
     for (const transcript of input.transcripts) {
-        if (!transcript.workspaceId) {
+        if (!transcript.projectId) {
             report.skipped += 1;
             continue;
         }
@@ -23,14 +23,14 @@ export async function recordOutsideSessions(client, input) {
         }
         const stale = now() - transcript.modifiedMs >= STOPPED_GROWING_MS;
         const vendorSessionId = transcript.vendorSessionId?.trim() || null;
-        const isLane = vendorSessionId !== null && laneIds.has(vendorSessionId);
+        const isEngineSession = vendorSessionId !== null && engineIds.has(vendorSessionId);
         try {
-            const { created, session } = await client.createSession(transcript.workspaceId, {
+            const { created, session } = await client.createSession(transcript.projectId, {
                 id: transcript.sessionKey,
                 startedBy: "person",
                 substrate: "device",
                 mode: "synchronous",
-                origin: isLane ? "inside" : "outside",
+                nustack: isEngineSession ? 1 : 0,
                 vendor: kinds.vendor,
                 renderer: kinds.renderer,
                 status: stale ? "done" : "running",
@@ -39,7 +39,7 @@ export async function recordOutsideSessions(client, input) {
             if (created)
                 report.created += 1;
             if (stale && !AT_REST.has(session.status)) {
-                await client.transitionSession(transcript.workspaceId, transcript.sessionKey, "done");
+                await client.transitionSession(transcript.projectId, transcript.sessionKey, "done");
                 report.finished += 1;
             }
             else if (!created) {

package/dist/lib/telemetry/config_renderer.js

@@ -92,7 +92,7 @@ const BINDING_TEMPLATE = `# Managed by the nustack CLI — binding: {{binding_id
     nustack:
       schema_version: {{schema_version}}
       organization_id: {{organization_id}}
-      workspace_id: {{workspace_id}}
+      project_id: {{project_id}}
       binding_id: {{binding_id}}
       device_id: {{device_id}}
       user_id: {{user_id}}
@@ -116,7 +116,7 @@ export function renderBindingInput(binding) {
         claude_glob: yamlScalar(`${claudeProjectDir(binding.repoRoot)}/**/*.jsonl`),
         schema_version: String(ENVELOPE_SCHEMA_VERSION),
         organization_id: yamlScalar(binding.organizationId),
-        workspace_id: yamlScalar(binding.workspaceId),
+        project_id: yamlScalar(binding.projectId),
         binding_id: yamlScalar(binding.bindingId),
         device_id: yamlScalar(binding.deviceRef),
         user_id: yamlScalar(binding.userId),
@@ -142,7 +142,7 @@ export function renderCodexSharedInput(bindings) {
             target: nustack
             fields:
               organization_id: ${yamlScalar(binding.organizationId)}
-              workspace_id: ${yamlScalar(binding.workspaceId)}
+              project_id: ${yamlScalar(binding.projectId)}
               binding_id: ${yamlScalar(binding.bindingId)}`)
         .join("\n");
     const dropList = ["cwd", ...providerDropFields("codex")].join(", ");

package/dist/lib/telemetry/health_report.js

@@ -38,7 +38,7 @@ export async function collectTelemetryStatus(store, probes = defaultProbes(), op
             bindingId: binding.id,
             repoRoot: binding.repositoryRoot,
             organizationId: binding.organizationId,
-            workspaceId: binding.workspaceId,
+            projectId: binding.projectId,
             deviceRef,
             userId,
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/nustack",
-  "version": "0.10.0-dev.9",
+  "version": "0.11.0",
   "description": "The nustack CLI — bootstrap NuStack services into a repo via the NuStack discovery plane.",
   "type": "module",
   "private": false,
@@ -26,15 +26,16 @@
     "commander": "^14.0.0"
   },
   "optionalDependencies": {
-    "@nurix/codegraph": "0.2.1"
+    "@nurix/codegraph": "0.2.1",
+    "@nurix/logscope": "0.1.0"
   },
   "devDependencies": {
     "@ngneat/falso": "^8.0.2",
     "@types/node": "^22.19.20",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@nurix/nustack.studio": "0.0.0",
-    "@nurix/nustack.ui": "0.0.0"
+    "@nurix/nustack.ui": "0.0.0",
+    "@nurix/nustack.studio": "0.0.0"
   },
   "publishConfig": {
     "access": "public"

package/dist/commands/lane.js

@@ -1,12 +0,0 @@
-import { LaneSupervisor } from "../lib/lanes/supervisor.js";
-import { sessionsClientFromEnv } from "../lib/sessions/client.js";
-export async function runLaneServe(engineVersion) {
-    const supervisor = new LaneSupervisor({
-        input: process.stdin,
-        output: process.stdout,
-        engineVersion,
-        sessions: sessionsClientFromEnv(process.env),
-    });
-    await supervisor.run();
-    process.exit(0);
-}