@sagentlab/navarch-runtime 0.1.0

package/dist/session.cjs

@@ -0,0 +1,196 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSession = runSession;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = require("node:fs");
+const sandbox_cjs_1 = require("./sandbox.cjs");
+const index_cjs_1 = require("./adapters/index.cjs");
+const exit_conditions_cjs_1 = require("./exit-conditions.cjs");
+const redact_cjs_1 = require("./redact.cjs");
+const upload_cjs_1 = require("./upload.cjs");
+const prompt_cjs_1 = require("./prompt.cjs");
+const mcp_config_cjs_1 = require("./mcp-config.cjs");
+const logger_cjs_1 = require("./logger.cjs");
+/** Filename the generated platform MCP config is written under, inside the session's workDir (host-side; also /workspace inside the Docker sandbox -- see sandbox.cts's bind mount). */
+const MCP_CONFIG_FILENAME = "mcp-config.json";
+const log = (0, logger_cjs_1.createLogger)("session");
+/**
+ * Runs one claimed task end to end (implementation-plan.md WP-07):
+ *   1. write the prompt file
+ *   2. fetch secrets from the broker once, at session start
+ *   3. stand up a Docker sandbox, clone the repo, inject env vars
+ *   4. run the configured agent adapter (Claude Code or Codex, per
+ *      FLOTILLA_AGENT — adapters/index.cts#selectAdapter), heartbeating the
+ *      lease throughout
+ *   5. redact + upload the transcript, map the exit condition, complete the
+ *      lease (recording which agent_type ran it)
+ *   6. wipe the sandbox unconditionally
+ *
+ * NEEDS LIVE VERIFICATION: the full path requires a real Docker daemon, a
+ * real `claude` (or `codex`) binary, and a live control-plane API — none of
+ * which are available in this offline build environment. Unit tests exercise
+ * each collaborator (api.cts, sandbox.cts, exit-conditions.cts, redact.cts,
+ * adapters/*.cts) in isolation instead; see runtime/README.md.
+ */
+async function runSession(deps, claimed, sessionId) {
+    const { api, config } = deps;
+    const { lease_id: leaseId, task, context_bundle: bundle } = claimed;
+    // The session's identity is the pre-allocated session id sent at claim time
+    // (recorded on the lease by the dispatcher). Lease-scoped API calls
+    // (heartbeat/complete/issue/transcript) still key on leaseId.
+    const workDir = node_path_1.default.join(config.workspaceRoot, sessionId);
+    await node_fs_1.promises.mkdir(workDir, { recursive: true });
+    const promptText = (0, prompt_cjs_1.renderPrompt)(task, bundle);
+    await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, "prompt.md"), promptText, "utf8");
+    // Secrets: fetched once, held only in memory (registry + env map below),
+    // never written to disk on the host. They only ever reach disk inside the
+    // sandbox's tmpfs (sandbox.cts injectEnv), which is wiped with the container.
+    const registry = new redact_cjs_1.SecretRegistry();
+    let secrets = {};
+    const secretNames = bundle.secret_manifest.map((s) => s.name);
+    if (secretNames.length > 0) {
+        const issued = await api.issueSecrets({ lease_id: leaseId, secret_names: secretNames });
+        secrets = issued.secrets;
+        registry.registerAll(secrets);
+    }
+    const abortController = new AbortController();
+    let leaseLost = false;
+    const heartbeatTimer = setInterval(() => {
+        api.heartbeatLease(leaseId).catch((err) => {
+            log.warn(`lease heartbeat failed for ${leaseId}: ${String(err)} — killing session.`);
+            leaseLost = true;
+            abortController.abort();
+        });
+    }, config.leaseHeartbeatIntervalMs);
+    const dockerAvailable = config.sandboxMode === "docker" && (await (0, sandbox_cjs_1.isDockerAvailable)());
+    if (config.sandboxMode === "docker" && !dockerAvailable) {
+        clearInterval(heartbeatTimer);
+        log.warn("Docker requested but not available on this machine — failing the task instead of crashing.");
+        await api
+            .completeLease(leaseId, {
+            status: "failed",
+            report: "Docker sandbox unavailable on this machine.",
+            evidence_urls: [],
+            cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
+            exit_status: "crashed",
+            agent_type: config.agentType,
+        })
+            .catch((err) => log.warn(`complete() after docker-unavailable also failed: ${String(err)}`));
+        return;
+    }
+    const sandbox = dockerAvailable
+        ? new sandbox_cjs_1.DockerSandbox({ sessionId, workspaceRoot: config.workspaceRoot, image: config.dockerImage })
+        : null;
+    // Platform MCP config (implementation-plan.md WP-07: "--mcp-config
+    // pointing at the platform MCP server"): generated fresh per session,
+    // carrying this machine's bearer token and this session's lease id (the
+    // auth app/api/mcp/route.ts requires -- see lib/flotilla/mcp/context.ts),
+    // unless the operator pinned a static override via FLOTILLA_MCP_CONFIG_PATH
+    // (e.g. pointing at a fake MCP server in local testing). Written to
+    // workDir (host path) so it also lands at /workspace/mcp-config.json
+    // inside the Docker sandbox (sandbox.cts binds workDir at /workspace) --
+    // the selected adapter (adapters/claude.cts or adapters/codex.cts) needs a
+    // path valid in whichever environment it actually runs.
+    let mcpConfigPath = config.mcpConfigPath;
+    if (!mcpConfigPath) {
+        const mcpConfig = (0, mcp_config_cjs_1.buildNavarchMcpConfig)({
+            apiBase: api.getBaseUrl(),
+            machineToken: api.getToken() ?? "",
+            leaseId,
+        });
+        await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, MCP_CONFIG_FILENAME), JSON.stringify(mcpConfig, null, 2), "utf8");
+        mcpConfigPath = sandbox ? `/workspace/${MCP_CONFIG_FILENAME}` : node_path_1.default.join(workDir, MCP_CONFIG_FILENAME);
+    }
+    try {
+        if (sandbox) {
+            await sandbox.create();
+            await sandbox.injectEnv(toEnvMap(secrets));
+            await sandbox.cloneRepo(task.repo, Boolean(secrets["github-pat"]));
+        }
+        // Picks the Claude Code or Codex adapter per FLOTILLA_AGENT
+        // (config.cts's `agentType`) — see adapters/index.cts#selectAdapter.
+        // Both adapters implement the same AgentAdapter.run() shape
+        // (adapters/types.cts), so nothing else in this function branches on
+        // which agent is running.
+        const adapter = (0, index_cjs_1.selectAdapter)(config.agentType);
+        const bin = config.agentType === "codex" ? config.codexBin : config.claudeBin;
+        const extraArgs = config.agentType === "codex" ? config.codexExtraArgs : config.claudeExtraArgs;
+        const result = await adapter.run({
+            prompt: promptText,
+            mcpConfigPath,
+            bin,
+            extraArgs,
+            timeoutMs: config.sessionTimeoutMs,
+            env: secrets,
+            cwd: sandbox ? undefined : workDir,
+            dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
+            signal: abortController.signal,
+        });
+        const mapping = (0, exit_conditions_cjs_1.mapExitCondition)({ ...result, killedByLeaseLoss: leaseLost || result.killedByLeaseLoss });
+        const knownSecrets = registry.list();
+        const transcript = [
+            "# stdout",
+            (0, redact_cjs_1.redactText)(result.stdout, knownSecrets),
+            "",
+            "# stderr",
+            (0, redact_cjs_1.redactText)(result.stderr, knownSecrets),
+            "",
+        ].join("\n");
+        let transcriptUrl;
+        try {
+            const { upload_url, public_url } = await api.getTranscriptUploadUrl(leaseId);
+            await (0, upload_cjs_1.uploadTranscript)(upload_url, transcript);
+            transcriptUrl = public_url;
+        }
+        catch (err) {
+            log.warn(`transcript upload failed for ${leaseId}: ${String(err)}`);
+        }
+        await api.completeLease(leaseId, {
+            status: mapping.leaseOutcome,
+            report: (0, redact_cjs_1.redactText)(mapping.reportSummary, knownSecrets),
+            evidence_urls: mapping.evidenceUrls,
+            cost: {
+                tokens_in: result.tokensIn ?? 0,
+                tokens_out: result.tokensOut ?? 0,
+                cost_usd: result.costUsd ?? 0,
+            },
+            transcript_url: transcriptUrl,
+            exit_status: mapping.exitStatus,
+            agent_type: config.agentType,
+        });
+    }
+    catch (err) {
+        log.error(`session ${leaseId} threw before completing: ${String(err)}`);
+        await api
+            .completeLease(leaseId, {
+            status: "failed",
+            report: (0, redact_cjs_1.redactText)(`Session crashed: ${String(err)}`, registry.list()),
+            evidence_urls: [],
+            cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
+            exit_status: "crashed",
+            agent_type: config.agentType,
+        })
+            .catch((completeErr) => log.warn(`complete() after crash also failed: ${String(completeErr)}`));
+    }
+    finally {
+        clearInterval(heartbeatTimer);
+        secrets = {};
+        if (sandbox)
+            await sandbox.wipe();
+        await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/** Uppercases + sanitizes secret names into shell-safe env var names for injectEnv(). */
+function toEnvMap(secrets) {
+    const out = {};
+    for (const [name, value] of Object.entries(secrets)) {
+        out[name.toUpperCase().replace(/[^A-Z0-9_]/g, "_")] = value;
+    }
+    if (secrets["github-pat"] && !out.GITHUB_TOKEN) {
+        out.GITHUB_TOKEN = secrets["github-pat"];
+    }
+    return out;
+}

package/dist/types.cjs

@@ -0,0 +1,19 @@
+"use strict";
+// Navarch runtime — shared wire types.
+//
+// These interfaces mirror the JSON shapes described in:
+//   - docs/flotilla/schema-design.md        (table columns => API field names, esp. §4, §5, §7)
+//   - docs/flotilla/implementation-plan.md  (WP-07 behavioral contract)
+//   - docs/agent-platform-project-plan.md   (§3.8 dispatch/§3.9 adapter contract)
+//
+// The control-plane API is being built in parallel (WP-01/WP-04/WP-05) in
+// other worktrees this agent cannot see. Fields/endpoints marked "ASSUMED"
+// are not pinned down by an explicit route contract in the docs as written
+// and were inferred from the closest analogous shape; see the WP-07 report
+// for the full list of assumptions to confirm once those WPs land. Everything
+// else is quoted close to verbatim from schema-design.md.
+//
+// runtime/src/api.cts is the ONLY place that turns these types into HTTP
+// calls, so reconciling an assumption against the real contract is a
+// same-file edit, not a rewrite.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/upload.cjs

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadTranscript = uploadTranscript;
+/**
+ * PUTs an already-redacted transcript to the signed Supabase Storage URL the
+ * control plane hands back (schema-design.md §4 sessions.transcript_url;
+ * implementation-plan.md WP-07). Kept as its own module so the storage
+ * mechanism is a one-function swap if it ever changes.
+ */
+async function uploadTranscript(uploadUrl, content, fetchImpl = fetch) {
+    const response = await fetchImpl(uploadUrl, {
+        method: "PUT",
+        headers: { "content-type": "text/plain; charset=utf-8" },
+        body: content,
+    });
+    if (!response.ok) {
+        throw new Error(`Transcript upload failed with ${response.status}`);
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@sagentlab/navarch-runtime",
+  "version": "0.1.0",
+  "description": "Navarch machine-side session manager: registers a machine, claims tasks from the control-plane dispatcher, runs them in a Docker sandbox via the Claude Code or Codex adapter, and reports results back.",
+  "type": "commonjs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sagentlab/navarch.git",
+    "directory": "runtime"
+  },
+  "homepage": "https://www.sagentlab.com/navarch",
+  "keywords": [
+    "navarch",
+    "ai-agent",
+    "claude-code",
+    "codex",
+    "task-runner"
+  ],
+  "bin": {
+    "navarch-runtime": "./bin/navarch.cjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test",
+    "start": "node dist/cli.cjs start",
+    "register": "node dist/cli.cjs register",
+    "connect": "node dist/cli.cjs connect",
+    "doctor": "node dist/cli.cjs doctor"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}