@sagentlab/navarch-runtime 0.1.1 → 0.1.3

package/dist/session.cjs

@@ -14,14 +14,16 @@ 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 git_worktree_cjs_1 = require("./git-worktree.cjs");
+const github_pr_cjs_1 = require("./github-pr.cjs");
+/** Filename the generated platform MCP config is written under inside the session metadata directory. */
 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
+ *   3. optionally stand up a Docker sandbox when explicitly configured
  *   4. run the configured agent adapter (Claude Code or Codex, per
  *      NAVARCH_AGENT — adapters/index.cts#selectAdapter), heartbeating the
  *      lease throughout
@@ -29,19 +31,29 @@ const log = (0, logger_cjs_1.createLogger)("session");
  *      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.
+ * NEEDS LIVE VERIFICATION: the full path requires a real `claude` (or
+ * `codex`) binary and a live control-plane API; Docker-backed execution also
+ * requires a real Docker daemon. 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;
+    const execution = bundle.execution ?? {
+        profile: task.execution_profile ?? "standard",
+        model: config.agentType === "codex" ? "gpt-5.6" : "best",
+        reasoning_effort: "medium",
+    };
+    const executionReport = {
+        model: execution.model,
+        execution_profile: execution.profile,
+        reasoning_effort: execution.reasoning_effort,
+    };
     // 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);
+    const workDir = node_path_1.default.join(config.workspaceRoot, "sessions", 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");
@@ -56,15 +68,72 @@ async function runSession(deps, claimed, sessionId) {
         secrets = issued.secrets;
         registry.registerAll(secrets);
     }
-    const abortController = new AbortController();
+    const cloneUrl = bundle.repository?.clone_url ??
+        (task.repo ? `https://github.com/${task.repo.replace(/\.git$/, "")}.git` : null);
+    if (!cloneUrl) {
+        const failureSummary = `Project ${task.project_id} has no GitHub repository URL. Set it in Project settings before dispatching work.`;
+        await api.completeLease(leaseId, {
+            status: "failed",
+            report: failureSummary,
+            failure_summary: failureSummary,
+            evidence_urls: [],
+            cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
+            exit_status: "crashed",
+            agent_type: config.agentType,
+            ...executionReport,
+        });
+        secrets = {};
+        await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+        return;
+    }
+    const githubToken = secrets[bundle.repository?.credential_secret_name ?? "github-pat"];
+    const gitWorktree = new git_worktree_cjs_1.GitWorktree({
+        workspaceRoot: config.workspaceRoot,
+        projectId: task.project_id,
+        taskId: task.id,
+        sessionId,
+        cloneUrl,
+        githubToken,
+    });
+    const knownGuidanceIds = new Set((bundle.guidance ?? []).map((entry) => entry.id));
+    const deliveredGuidance = [...(bundle.guidance ?? [])];
+    let guidanceCursor = bundle.guidance_cursor ?? null;
+    let pendingGuidance = [];
+    let activeAbortController = null;
     let leaseLost = false;
-    const heartbeatTimer = setInterval(() => {
-        api.heartbeatLease(leaseId).catch((err) => {
+    let heartbeatInFlight = null;
+    const pollLease = () => {
+        if (heartbeatInFlight)
+            return heartbeatInFlight;
+        const request = api
+            .heartbeatLease(leaseId, { guidance_after: guidanceCursor })
+            .then((heartbeat) => {
+            guidanceCursor = heartbeat.guidance_cursor ?? guidanceCursor;
+            const fresh = (heartbeat.guidance ?? []).filter((entry) => {
+                if (knownGuidanceIds.has(entry.id))
+                    return false;
+                knownGuidanceIds.add(entry.id);
+                return true;
+            });
+            if (fresh.length > 0) {
+                pendingGuidance.push(...fresh);
+                deliveredGuidance.push(...fresh);
+                log.info(`received ${fresh.length} guidance update${fresh.length === 1 ? "" : "s"} for ${leaseId}; restarting the agent turn in the same worktree.`);
+                activeAbortController?.abort();
+            }
+        })
+            .catch((err) => {
             log.warn(`lease heartbeat failed for ${leaseId}: ${String(err)} — killing session.`);
             leaseLost = true;
-            abortController.abort();
+            activeAbortController?.abort();
+        })
+            .finally(() => {
+            heartbeatInFlight = null;
         });
-    }, config.leaseHeartbeatIntervalMs);
+        heartbeatInFlight = request;
+        return request;
+    };
+    const heartbeatTimer = setInterval(() => void pollLease(), config.leaseHeartbeatIntervalMs);
     const dockerAvailable = config.sandboxMode === "docker" && (await (0, sandbox_cjs_1.isDockerAvailable)());
     if (config.sandboxMode === "docker" && !dockerAvailable) {
         clearInterval(heartbeatTimer);
@@ -73,16 +142,26 @@ async function runSession(deps, claimed, sessionId) {
             .completeLease(leaseId, {
             status: "failed",
             report: "Docker sandbox unavailable on this machine.",
+            failure_summary: "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,
+            ...executionReport,
         })
             .catch((err) => log.warn(`complete() after docker-unavailable also failed: ${String(err)}`));
+        secrets = {};
+        await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
         return;
     }
     const sandbox = dockerAvailable
-        ? new sandbox_cjs_1.DockerSandbox({ sessionId, workspaceRoot: config.workspaceRoot, image: config.dockerImage })
+        ? new sandbox_cjs_1.DockerSandbox({
+            sessionId,
+            workspaceRoot: node_path_1.default.join(config.workspaceRoot, "sessions"),
+            image: config.dockerImage,
+            containerWorkDir: gitWorktree.worktreePath,
+            sharedGitDir: gitWorktree.repositoryPath,
+        })
         : null;
     // Platform MCP config (implementation-plan.md WP-07: "--mcp-config
     // pointing at the platform MCP server"): generated fresh per session,
@@ -90,8 +169,8 @@ async function runSession(deps, claimed, sessionId) {
     // auth app/api/mcp/route.ts requires -- see lib/navarch/mcp/context.ts),
     // unless the operator pinned a static override via NAVARCH_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) --
+    // workDir (host path), which Docker mode mounts at that same absolute path
+    // so worktree .git pointers and this config path remain valid --
     // the selected adapter (adapters/claude.cts or adapters/codex.cts) needs a
     // path valid in whichever environment it actually runs.
     let mcpConfigPath = config.mcpConfigPath;
@@ -102,13 +181,13 @@ async function runSession(deps, claimed, sessionId) {
             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);
+        mcpConfigPath = node_path_1.default.join(workDir, MCP_CONFIG_FILENAME);
     }
     try {
+        await gitWorktree.prepare();
         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 NAVARCH_AGENT
         // (config.cts's `agentType`) — see adapters/index.cts#selectAdapter.
@@ -118,27 +197,78 @@ async function runSession(deps, claimed, sessionId) {
         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 attempts = [];
+        let result;
+        while (true) {
+            // Guidance can arrive while the worktree/sandbox is being prepared.
+            // It is already included in deliveredGuidance, so clear the pending
+            // notification and start the first turn with the corrected prompt.
+            pendingGuidance = [];
+            activeAbortController = new AbortController();
+            if (leaseLost)
+                activeAbortController.abort();
+            const runPrompt = deliveredGuidance.length > (bundle.guidance?.length ?? 0)
+                ? (0, prompt_cjs_1.renderGuidanceCorrectionPrompt)(promptText, deliveredGuidance)
+                : promptText;
+            await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, "prompt.md"), runPrompt, "utf8");
+            const turnResult = await adapter.run({
+                prompt: runPrompt,
+                mcpConfigPath,
+                bin,
+                extraArgs,
+                model: execution.model,
+                reasoningEffort: execution.reasoning_effort,
+                timeoutMs: config.sessionTimeoutMs,
+                env: toEnvMap(secrets),
+                cwd: sandbox ? undefined : gitWorktree.worktreePath,
+                dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
+                signal: activeAbortController.signal,
+            });
+            activeAbortController = null;
+            attempts.push(turnResult);
+            // Close the small race between a naturally completed turn and the next
+            // scheduled heartbeat. If guidance landed, run another turn before the
+            // lease can be completed.
+            await pollLease();
+            if (!leaseLost && pendingGuidance.length > 0)
+                continue;
+            result = {
+                ...turnResult,
+                tokensIn: attempts.reduce((sum, attempt) => sum + (attempt.tokensIn ?? 0), 0),
+                tokensOut: attempts.reduce((sum, attempt) => sum + (attempt.tokensOut ?? 0), 0),
+                costUsd: attempts.reduce((sum, attempt) => sum + (attempt.costUsd ?? 0), 0),
+            };
+            break;
+        }
         const mapping = (0, exit_conditions_cjs_1.mapExitCondition)({ ...result, killedByLeaseLoss: leaseLost || result.killedByLeaseLoss });
+        try {
+            const prUrl = await (0, github_pr_cjs_1.findHeadBranchPullRequestUrl)({
+                repository: bundle.repository?.full_name ?? task.repo,
+                headBranch: gitWorktree.branch,
+                githubToken,
+            });
+            if (prUrl)
+                mapping.evidenceUrls.push(prUrl);
+        }
+        catch (err) {
+            // Evidence discovery is best-effort: a GitHub outage or token scope
+            // mismatch must not turn an otherwise valid completion into a crash.
+            log.warn(`head-branch PR lookup failed for ${leaseId}: ${String(err)}`);
+        }
         const knownSecrets = registry.list();
-        const transcript = [
-            "# stdout",
-            (0, redact_cjs_1.redactText)(result.stdout, knownSecrets),
+        if (mapping.leaseOutcome === "failed") {
+            log.warn(`adapter failed for ${leaseId}: ${(0, redact_cjs_1.redactText)(mapping.reportSummary, knownSecrets)}`);
+        }
+        const transcript = attempts
+            .flatMap((attempt, index) => [
+            `# agent turn ${index + 1} stdout`,
+            (0, redact_cjs_1.redactText)(attempt.stdout, knownSecrets),
             "",
-            "# stderr",
-            (0, redact_cjs_1.redactText)(result.stderr, knownSecrets),
+            `# agent turn ${index + 1} stderr`,
+            (0, redact_cjs_1.redactText)(attempt.stderr, knownSecrets),
             "",
-        ].join("\n");
+        ])
+            .join("\n");
         let transcriptUrl;
         try {
             const { upload_url, public_url } = await api.getTranscriptUploadUrl(leaseId);
@@ -160,26 +290,32 @@ async function runSession(deps, claimed, sessionId) {
             transcript_url: transcriptUrl,
             exit_status: mapping.exitStatus,
             agent_type: config.agentType,
+            ...executionReport,
         });
     }
     catch (err) {
         log.error(`session ${leaseId} threw before completing: ${String(err)}`);
+        const failureSummary = (0, redact_cjs_1.redactText)(`Session crashed: ${String(err)}`, registry.list());
         await api
             .completeLease(leaseId, {
             status: "failed",
-            report: (0, redact_cjs_1.redactText)(`Session crashed: ${String(err)}`, registry.list()),
+            report: failureSummary,
+            failure_summary: failureSummary,
             evidence_urls: [],
             cost: { tokens_in: 0, tokens_out: 0, cost_usd: 0 },
             exit_status: "crashed",
             agent_type: config.agentType,
+            ...executionReport,
         })
             .catch((completeErr) => log.warn(`complete() after crash also failed: ${String(completeErr)}`));
     }
     finally {
         clearInterval(heartbeatTimer);
+        activeAbortController?.abort();
         secrets = {};
         if (sandbox)
-            await sandbox.wipe();
+            await sandbox.stop();
+        await gitWorktree.cleanup();
         await node_fs_1.promises.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
     }
 }
@@ -191,6 +327,14 @@ function toEnvMap(secrets) {
     }
     if (secrets["github-pat"] && !out.GITHUB_TOKEN) {
         out.GITHUB_TOKEN = secrets["github-pat"];
+        // Make ordinary `git push` calls from the agent use the in-memory token.
+        // The helper contains only an env-var reference; the token itself never
+        // lands in argv, git config, or the worktree.
+        out.GIT_CONFIG_COUNT = "1";
+        out.GIT_CONFIG_KEY_0 = "credential.helper";
+        out.GIT_CONFIG_VALUE_0 =
+            '!f() { echo username=x-access-token; echo "password=$GITHUB_TOKEN"; }; f';
+        out.GIT_TERMINAL_PROMPT = "0";
     }
     return out;
 }

package/dist/types.cjs

@@ -6,14 +6,7 @@
 //   - docs/navarch/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.
+// These contracts are implemented by the matching app/api routes and are
+// documented in schema-design.md §7. runtime/src/api.cts is the only place
+// that turns them into HTTP calls.
 Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.1",
-  "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.",
+  "version": "0.1.3",
+  "description": "Navarch machine-side session manager: registers a machine, claims tasks from the control-plane dispatcher, runs them via the Claude Code or Codex adapter, and reports results back.",
   "type": "commonjs",
   "license": "MIT",
   "repository": {
@@ -37,10 +37,10 @@
     "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"
+    "start": "node bin/navarch.cjs start",
+    "register": "node bin/navarch.cjs register",
+    "connect": "node bin/navarch.cjs connect",
+    "doctor": "node bin/navarch.cjs doctor"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",