@sagentlab/navarch-runtime 0.1.91 → 0.1.93

package/dist/conversation/turn-runner.cjs

@@ -0,0 +1,402 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeConversationText = sanitizeConversationText;
+exports.takeChunk = takeChunk;
+exports.httpStatus = httpStatus;
+exports.runConversationTurn = runConversationTurn;
+exports.recoverUnfinishedTurn = recoverUnfinishedTurn;
+const node_crypto_1 = require("node:crypto");
+const node_perf_hooks_1 = require("node:perf_hooks");
+const logger_cjs_1 = require("../logger.cjs");
+const prompt_cjs_1 = require("./prompt.cjs");
+const workspace_cjs_1 = require("./workspace.cjs");
+// Bounds mirror lib/navarch/navi-conversations.ts CONVERSATION_LIMITS.
+const MAX_DELTA_CHARS = 4_000;
+const SIZE_FLUSH_CHARS = 3_500;
+// A conversation holds at most 512 events across 20 turns, three of them status
+// events per turn. Twenty paced text appends per turn keeps 20 long turns
+// (20 x 23 = 460) under that cap without knowing what earlier turns used.
+const MAX_TEXT_APPENDS = 20;
+// Appends are retried until the lease runs out; the terminal gets a few attempts.
+const TERMINAL_ATTEMPTS = 4;
+const MAX_RETRY_DELAY_MS = 2_000;
+/** Server lease length (CONVERSATION_LIMITS.leaseMs). */
+const LEASE_MS = 60_000;
+const RECOVERY_GIVE_UP_MS = 15 * 60_000;
+const EMPTY = {
+    firstEventMs: null, firstTextMs: null, firstTextAckedMs: null, textAppends: 0, toolStatuses: 0,
+};
+/** PostgreSQL JSONB rejects NUL and unpaired surrogates (server validConversationText). */
+function sanitizeConversationText(text) {
+    return text
+        .replace(/\u0000/g, "")
+        .replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "�");
+}
+/** Splits at most `limit` UTF-16 units off the front without cutting a surrogate pair. */
+function takeChunk(text, limit = MAX_DELTA_CHARS) {
+    if (text.length <= limit)
+        return [text, ""];
+    let cut = limit;
+    const last = text.charCodeAt(cut - 1);
+    if (last >= 0xd800 && last <= 0xdbff)
+        cut -= 1;
+    return [text.slice(0, cut), text.slice(cut)];
+}
+/** A 4xx answer (other than 408/429) means this runtime no longer holds the turn. */
+function lostAuthority(error) {
+    const status = httpStatus(error);
+    return status !== null && status >= 400 && status < 500 && status !== 429 && status !== 408;
+}
+/** HTTP status carried by a NavarchApiError, read structurally so tests can throw lookalikes. */
+function httpStatus(error) {
+    const status = error?.status;
+    return typeof status === "number" ? status : null;
+}
+function verdict(status) {
+    if (status === "cancelled")
+        return "cancelled";
+    if (status === "expired_lease")
+        return "expired";
+    return status === "failed" ? "failed" : "lost";
+}
+/**
+ * Executes one conversation turn on this machine's selected adapter.
+ *
+ * - The claim token is journaled before the claim, and `started` is journaled
+ *   before the agent is launched, so a turn id never launches twice.
+ * - Every append is journaled before it is sent and resent identically until
+ *   acknowledged. Appends are serial, so event order equals send order.
+ * - Text is sent as it is parsed from the live agent stream. The first text
+ *   goes out at once; later text is coalesced behind the in-flight append and a
+ *   short gap so one answer cannot exhaust the 512-event conversation cap.
+ * - A renewal, append acknowledgement or fencing error showing that the turn is
+ *   no longer running kills the process this runner launched, and only that one.
+ */
+async function runConversationTurn(deps, conversationId, turnId) {
+    const log = deps.log ?? (0, logger_cjs_1.createLogger)("navi");
+    const now = deps.now ?? Date.now;
+    const newId = deps.newId ?? node_crypto_1.randomUUID;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const command = (body) => deps.api.conversationCommand(deps.machineId, conversationId, body);
+    const { journal } = await deps.journal.open(conversationId, turnId, newId());
+    if (journal.state === "done")
+        return { outcome: "already_done", ...EMPTY };
+    // `claimed` and `started` records belong to an earlier process or run. The
+    // recovery sweep settles them; they are never launched again.
+    if (journal.state !== "claiming")
+        return { outcome: "deferred", ...EMPTY };
+    let claim;
+    const claimSentAt = Date.now();
+    try {
+        claim = await command({ op: "claim", turnId: journal.turnId, token: journal.token });
+    }
+    catch (error) {
+        if (lostAuthority(error)) {
+            await deps.journal.finish(journal, "lost");
+            return { outcome: "lost", ...EMPTY };
+        }
+        throw error; // transport or 5xx: the journal stays `claiming` and the same token is retried
+    }
+    if (claim.status !== "running") {
+        const result = verdict(claim.status);
+        await deps.journal.finish(journal, result);
+        return { outcome: result, ...EMPTY };
+    }
+    journal.state = "claimed";
+    await deps.journal.write(journal);
+    const controller = new AbortController();
+    const onShutdown = () => controller.abort();
+    deps.signal?.addEventListener("abort", onShutdown, { once: true });
+    if (deps.signal?.aborted)
+        controller.abort();
+    // Mutable run state lives in one object so closures and the main flow agree on it.
+    const run = {
+        lost: null,
+        finished: false,
+        nextIndex: journal.acked,
+        textAppends: 0,
+        toolStatuses: 0,
+        launchedAt: 0,
+        firstTextAckedMs: null,
+        pendingText: "",
+        flushing: null,
+        finalizing: false,
+        lastAppendAt: 0,
+        agentFailed: false,
+    };
+    const leaseMs = deps.leaseMs ?? LEASE_MS;
+    let leaseTimer;
+    let renewTimer;
+    let gapTimer;
+    const lose = (reason) => {
+        if (run.lost)
+            return;
+        run.lost = reason;
+        controller.abort();
+    };
+    /**
+     * The agent stops when the lease can no longer be renewed in time. The
+     * deadline is local: `leaseMs` after the moment this runtime sent the request
+     * the server just acknowledged, which never outlasts the server's own lease.
+     * The server's absolute `leaseUntil` is deliberately not compared with the
+     * local clock, so a skewed runtime clock cannot kill a healthy turn.
+     */
+    const armLease = (sentAt) => {
+        if (run.finished)
+            return;
+        clearTimeout(leaseTimer);
+        leaseTimer = setTimeout(() => lose("expired"), Math.max(0, sentAt + leaseMs - Date.now()));
+    };
+    /** True while the server still reports this turn as running. */
+    const absorb = (result, sentAt) => {
+        if (result.status !== "running")
+            return false;
+        armLease(sentAt);
+        return true;
+    };
+    /** Journals, then sends, one event; resends the identical event on a transient failure. */
+    const send = async (text, terminal) => {
+        const event = { id: newId(), index: run.nextIndex + 1, text, ...(terminal ? { terminal } : {}) };
+        run.nextIndex = event.index;
+        journal.pending = event;
+        await deps.journal.write(journal);
+        const firstAttemptAt = Date.now();
+        for (let attempt = 1;; attempt += 1) {
+            const sentAt = Date.now();
+            try {
+                const result = await command({
+                    op: "append", turnId: journal.turnId, token: journal.token,
+                    eventId: event.id, index: event.index, text: event.text, ...(terminal ? { terminal } : {}),
+                });
+                journal.acked = event.index;
+                delete journal.pending;
+                await deps.journal.write(journal);
+                if (!terminal && !absorb(result, sentAt))
+                    lose(verdict(result.status));
+                return result;
+            }
+            catch (error) {
+                if (lostAuthority(error)) {
+                    lose("lost");
+                    return null;
+                }
+                // A text append is retried through an outage for up to one lease length
+                // (the lease timer also aborts the turn); a terminal gets a few tries.
+                // Renewals can keep succeeding while appends fail, so the append retry
+                // has its own bound.
+                const stuck = controller.signal.aborted || Date.now() - firstAttemptAt >= leaseMs;
+                if (terminal ? attempt >= TERMINAL_ATTEMPTS : stuck) {
+                    lose("lost");
+                    return null;
+                }
+                await sleep(Math.min(MAX_RETRY_DELAY_MS, (deps.retryDelayMs ?? 250) * 2 ** Math.min(attempt - 1, 6)));
+            }
+        }
+    };
+    const flush = () => {
+        if (run.flushing || run.lost || run.finalizing || !run.pendingText)
+            return;
+        const budgetLeft = run.textAppends < MAX_TEXT_APPENDS;
+        // The gap doubles every four appends, so 20 appends cover a long answer
+        // (250 ms, 500 ms, 1 s, 2 s, 4 s) instead of bursting through the budget.
+        const baseGap = deps.appendGapMs ?? 250;
+        const gap = run.textAppends === 0 ? 0 : baseGap * 2 ** Math.floor(run.textAppends / 4);
+        const wait = run.lastAppendAt + gap - now();
+        const sizeReady = run.pendingText.length >= SIZE_FLUSH_CHARS;
+        if ((!budgetLeft && !sizeReady) || (wait > 0 && !sizeReady)) {
+            if (budgetLeft && !gapTimer)
+                gapTimer = setTimeout(() => { gapTimer = undefined; flush(); }, wait);
+            return;
+        }
+        const [chunk, rest] = takeChunk(run.pendingText);
+        run.pendingText = rest;
+        run.textAppends += 1;
+        run.flushing = send(chunk)
+            .then((result) => {
+            if (result && run.firstTextAckedMs === null)
+                run.firstTextAckedMs = node_perf_hooks_1.performance.now() - run.launchedAt;
+        })
+            .catch((error) => {
+            log.warn(`conversation ${conversationId} turn ${turnId} append failed: ${String(error).slice(0, 300)}`);
+            lose("lost");
+        })
+            .finally(() => {
+            run.flushing = null;
+            run.lastAppendAt = now();
+            flush();
+        });
+    };
+    const onEvent = (event) => {
+        if (run.lost)
+            return;
+        if (event.type === "text") {
+            run.pendingText += sanitizeConversationText(event.text);
+            flush();
+        }
+        else if (event.type === "tool_status") {
+            // Never mixed into assistant text. Transport v1 carries only public
+            // text and a terminal state, so tool progress stays on this machine.
+            run.toolStatuses += 1;
+        }
+        else {
+            run.agentFailed = true;
+        }
+    };
+    const scheduleRenew = () => {
+        renewTimer = setTimeout(async () => {
+            if (run.lost || run.finished || controller.signal.aborted)
+                return;
+            const sentAt = Date.now();
+            try {
+                const result = await command({ op: "renew", turnId: journal.turnId, token: journal.token });
+                if (run.finished)
+                    return;
+                if (!absorb(result, sentAt)) {
+                    if (!run.finalizing)
+                        lose(verdict(result.status));
+                    return;
+                }
+            }
+            catch (error) {
+                if (run.finished)
+                    return;
+                if (lostAuthority(error)) {
+                    lose("lost");
+                    return;
+                }
+                // Transient failure: keep going until the armed lease deadline fires.
+            }
+            scheduleRenew();
+        }, deps.renewIntervalMs ?? 20_000);
+    };
+    /** Sends the terminal event and returns what the control plane recorded, or null if unconfirmed. */
+    const sendTerminal = async (text, terminal) => {
+        const acked = await send(text, terminal);
+        if (!acked)
+            return null;
+        // The server acknowledges a late terminal (after stop, expiry or an output
+        // limit) with 200 and its own terminal status, which is what actually happened.
+        return acked.status === terminal ? terminal : verdict(acked.status);
+    };
+    let terminalAcked = null;
+    let outcome = "failed";
+    let metrics = { firstEventMs: null, firstTextMs: null };
+    try {
+        const repositoryUrl = (0, workspace_cjs_1.validRepositoryUrl)(claim.repository);
+        const snapshot = claim.conversation;
+        let prepared = null;
+        let prompt = "";
+        armLease(claimSentAt);
+        scheduleRenew();
+        try {
+            if (!repositoryUrl)
+                throw new Error("claim carries no usable repository URL");
+            if (!snapshot || snapshot.id !== conversationId)
+                throw new Error("claim carries no matching conversation");
+            prompt = (0, prompt_cjs_1.buildConversationPrompt)(snapshot, journal.turnId);
+            prepared = await deps.prepareWorkspace({ conversationId, repositoryUrl, signal: controller.signal });
+        }
+        catch (error) {
+            if (!run.lost)
+                log.warn(`conversation ${conversationId} turn ${turnId} could not start: ${String(error).slice(0, 300)}`);
+        }
+        if (prepared && !run.lost) {
+            // After this write a crash can never lead to a second launch of this turn id.
+            journal.state = "started";
+            await deps.journal.write(journal);
+            run.launchedAt = node_perf_hooks_1.performance.now();
+            const result = await deps.adapter.conversation.run({
+                prompt, bin: deps.bin, ...(deps.model ? { model: deps.model } : {}),
+                cwd: prepared.cwd, env: deps.env, settingsPath: prepared.settingsPath,
+                timeoutMs: deps.turnTimeoutMs, signal: controller.signal, onEvent,
+            });
+            metrics = { firstEventMs: result.firstEventMs, firstTextMs: result.firstTextMs };
+            journal.firstEventMs = result.firstEventMs;
+            journal.firstTextMs = result.firstTextMs;
+            if (!result.succeeded || run.agentFailed) {
+                log.warn(`conversation ${conversationId} turn ${turnId} agent ended without success (exit ${result.exitCode}, timedOut=${result.timedOut}, aborted=${result.aborted}): ${result.stderr.slice(-300)}`);
+            }
+            // No more events can arrive. Stop background flushing, let the in-flight
+            // append finish, then send the remainder serially.
+            run.finalizing = true;
+            clearTimeout(gapTimer);
+            await run.flushing;
+            if (!run.lost) {
+                const completed = result.succeeded && !run.agentFailed && !result.aborted;
+                while (run.pendingText.length > MAX_DELTA_CHARS && !run.lost) {
+                    const [chunk, rest] = takeChunk(run.pendingText);
+                    run.pendingText = rest;
+                    await send(chunk);
+                }
+                if (!run.lost) {
+                    const text = run.pendingText;
+                    run.pendingText = "";
+                    terminalAcked = await sendTerminal(text, completed ? "completed" : "failed");
+                }
+            }
+        }
+        else if (!run.lost) {
+            // Setup failed before any agent ran: a public failed terminal with no text.
+            terminalAcked = await sendTerminal("", "failed");
+        }
+    }
+    catch (error) {
+        log.warn(`conversation ${conversationId} turn ${turnId} aborted: ${String(error).slice(0, 300)}`);
+        lose("lost");
+    }
+    finally {
+        run.finished = true;
+        clearTimeout(leaseTimer);
+        clearTimeout(renewTimer);
+        clearTimeout(gapTimer);
+        deps.signal?.removeEventListener("abort", onShutdown);
+    }
+    // An acknowledged terminal is the control plane's verdict; a timer that fired
+    // while it was in flight must not rewrite it.
+    if (terminalAcked)
+        outcome = terminalAcked;
+    else if (run.lost)
+        outcome = run.lost;
+    else
+        outcome = "lost";
+    await deps.journal.finish(journal, outcome);
+    return { outcome, ...metrics, firstTextAckedMs: run.firstTextAckedMs, textAppends: run.textAppends, toolStatuses: run.toolStatuses };
+}
+/**
+ * Settles a journal this process did not finish (crash, kill, or shutdown
+ * while the agent ran). It never launches the agent. It resends the one event
+ * that may not have been acknowledged, then a public `failed` terminal, so the
+ * user sees a result instead of waiting for lease expiry. If the control plane
+ * no longer honors the token, the record is closed as lost.
+ */
+async function recoverUnfinishedTurn(deps, journal) {
+    const now = deps.now ?? Date.now;
+    const newId = deps.newId ?? node_crypto_1.randomUUID;
+    const send = (event) => deps.api.conversationCommand(deps.machineId, journal.conversationId, {
+        op: "append", turnId: journal.turnId, token: journal.token,
+        eventId: event.id, index: event.index, text: event.text, ...(event.terminal ? { terminal: event.terminal } : {}),
+    });
+    try {
+        // `claiming` records never get here: the loop re-sends their claim instead.
+        let index = journal.acked;
+        let terminal = false;
+        if (journal.pending) {
+            await send(journal.pending);
+            index = journal.pending.index;
+            terminal = !!journal.pending.terminal;
+            journal.acked = index;
+            delete journal.pending;
+        }
+        if (!terminal)
+            await send({ id: newId(), index: index + 1, text: "", terminal: "failed" });
+        await deps.journal.finish(journal, "failed");
+        return "settled";
+    }
+    catch (error) {
+        if (lostAuthority(error) || now() - journal.updatedAt > RECOVERY_GIVE_UP_MS) {
+            await deps.journal.finish(journal, "lost");
+            return "settled";
+        }
+        return "retry";
+    }
+}

package/dist/conversation/workspace.cjs

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.conversationEnv = conversationEnv;
+exports.validRepositoryUrl = validRepositoryUrl;
+exports.conversationRoot = conversationRoot;
+exports.prepareConversationWorkspace = prepareConversationWorkspace;
+exports.removeConversationWorkspace = removeConversationWorkspace;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const sandbox_cjs_1 = require("../sandbox.cjs");
+const journal_cjs_1 = require("./journal.cjs");
+const CLONE_TIMEOUT_MS = 3 * 60_000;
+const REPOSITORY_MARKER = "repository-url";
+/** Variables that carry this runtime's own or a task's credentials, never a conversation's. */
+const WITHHELD_ENV = /^(NAVARCH_|GH_|GITHUB_|GIT_ASKPASS$|SSH_ASKPASS$|SSH_AUTH_SOCK$)/;
+/**
+ * Environment for a conversation child. It inherits the machine's own login
+ * (HOME, PATH, provider keys the local agent needs) but not the Navarch
+ * machine token, broker or GitHub credentials the runtime holds for tasks.
+ */
+function conversationEnv(base = process.env) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (value === undefined || WITHHELD_ENV.test(key))
+            continue;
+        env[key] = value;
+    }
+    return env;
+}
+/**
+ * Maps the project's stored repository value to a GitHub https clone URL.
+ * The control plane stores a free-form value; the task path accepts
+ * `owner/name`, `git@github.com:owner/name(.git)` and `https://github.com/...`
+ * (lib/navarch/github-repository.ts), and so does this one. Anything else
+ * (another host, `ext::`, `file:`, `-` options, embedded credentials) returns
+ * null, so the runtime never hands an unvalidated string to git.
+ */
+function validRepositoryUrl(value) {
+    if (typeof value !== "string" || value.length > 2048 || /[\s\0]/.test(value))
+        return null;
+    const fullName = value
+        .replace(/^git@github\.com:/i, "")
+        .replace(/^https:\/\/github\.com\//i, "")
+        .replace(/\.git$/i, "")
+        .replace(/\/+$/, "");
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(fullName) || fullName.startsWith("-"))
+        return null;
+    return `https://github.com/${fullName}.git`;
+}
+function conversationRoot(workspaceRoot, conversationId) {
+    return node_path_1.default.join(workspaceRoot, "conversations", (0, journal_cjs_1.assertUuid)(conversationId, "conversation id"));
+}
+/**
+ * Prepares the conversation's own checkout. Each conversation gets a separate
+ * directory, so two conversations never share files, history or git config.
+ * The first turn clones; later turns of the same conversation reuse the
+ * checkout so a follow-up sees the same revision as the first answer.
+ *
+ * The clone uses the machine's own git credentials (the same ones a local
+ * `git clone` would use), never a Navarch server-side provider credential.
+ * A repository this machine cannot read fails the turn instead of falling back.
+ */
+async function prepareConversationWorkspace(options) {
+    const url = validRepositoryUrl(options.repositoryUrl);
+    if (!url)
+        throw new Error("repository URL is not a plain https URL");
+    const runner = options.runner ?? sandbox_cjs_1.nodeCommandRunner;
+    const root = conversationRoot(options.workspaceRoot, options.conversationId);
+    const workspace = {
+        root,
+        checkout: node_path_1.default.join(root, "repo"),
+        metaDir: node_path_1.default.join(root, "meta"),
+    };
+    await node_fs_1.promises.mkdir(workspace.metaDir, { recursive: true, mode: 0o700 });
+    const marker = node_path_1.default.join(root, REPOSITORY_MARKER);
+    const recorded = await node_fs_1.promises.readFile(marker, "utf8").catch(() => null);
+    const hasCheckout = await node_fs_1.promises.stat(node_path_1.default.join(workspace.checkout, ".git")).then(() => true, () => false);
+    if (hasCheckout && recorded === url)
+        return workspace;
+    // New conversation, a changed repository URL, or an interrupted clone.
+    await node_fs_1.promises.rm(workspace.checkout, { recursive: true, force: true });
+    const env = {
+        ...options.env,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_ALLOW_PROTOCOL: "https",
+        GIT_CONFIG_COUNT: "1",
+        GIT_CONFIG_KEY_0: "core.hooksPath",
+        GIT_CONFIG_VALUE_0: process.platform === "win32" ? "NUL" : "/dev/null",
+    };
+    const result = await runner.run("git", ["clone", "--quiet", "--filter=blob:none", "--no-tags", "--", url, workspace.checkout], { cwd: root, env, timeoutMs: CLONE_TIMEOUT_MS, signal: options.signal });
+    if (result.code !== 0) {
+        await node_fs_1.promises.rm(workspace.checkout, { recursive: true, force: true }).catch(() => undefined);
+        throw new Error(`git clone failed with exit ${result.code}: ${result.stderr.slice(-500)}`);
+    }
+    await node_fs_1.promises.writeFile(marker, url, { encoding: "utf8", mode: 0o600 });
+    return workspace;
+}
+async function removeConversationWorkspace(workspaceRoot, conversationId) {
+    await node_fs_1.promises.rm(conversationRoot(workspaceRoot, conversationId), { recursive: true, force: true });
+}