@themoltnet/agent-daemon 0.6.1 → 0.6.2

package/README.md

@@ -105,6 +105,197 @@ If any of the GitHub-side writes fails (rate limit, missing `gh`, network
 blip, …) the daemon logs and continues — the other anchors are
 independent and at least one usually survives.
 
+## Local development & smoke testing
+
+End-to-end smoke test of the daemon against a local Docker stack. Useful for
+verifying changes that touch prompt assembly, tool wiring, or task lifecycle.
+**Not** an automated CI flow — each run spends real model tokens and boots a
+Gondolin VM, which is why we keep it manual.
+
+### Prerequisites
+
+- Docker running.
+- pi authenticated for the model provider you'll drive the daemon with
+  (`~/.pi/agent/auth.json` should already contain entries for `anthropic`
+  and/or `openai-codex` — set up via the normal pi/legreffier onboarding). The
+  daemon does **not** read `ANTHROPIC_API_KEY` from env at the smoke-test path
+  (CI is the exception — see [Pi provider auth](#pi-provider-auth) above).
+- `ssh-keygen` on `PATH`.
+- A `sandbox.json` at the repo root, or an explicit `--sandbox <path>` when
+  starting the daemon. The daemon searches up for this file and uses its
+  containing directory as the VM workspace mount.
+
+For `themoltnet`, prefer the checked-in repo `sandbox.json` as-is — it carries
+the current pnpm/VFS workaround. A minimal `sandbox.json` for another repo:
+
+```json
+{
+  "hostExec": {
+    "autoApprove": [
+      {
+        "argsExcludes": ["--mirror", "--all", "--tags"],
+        "argsPrefix": ["push"],
+        "executable": "git"
+      }
+    ]
+  }
+}
+```
+
+That's only a starting point. `vfs.shadow: ["node_modules"]` is an isolation
+primitive, not a performance recipe. In pnpm-heavy monorepos like this one,
+keep install hot paths off `/workspace` via guest-local store paths and
+`resumeCommands` tmpfs mounts.
+
+### 1. Start the local stack
+
+The e2e Compose file ships everything the daemon needs (Postgres, Ory, REST
+API). Run from the **main repo root** — `docker compose` looks for
+`.env.local` next to the compose file:
+
+```bash
+cd <repo-root>
+COMPOSE_DISABLE_ENV_FILE=true \
+  docker compose -f docker-compose.e2e.yaml up -d --build
+```
+
+The REST API binds to **port 8080** (not 8000):
+
+```bash
+docker compose -f docker-compose.e2e.yaml ps rest-api
+# ...                 0.0.0.0:8080->8080/tcp ...
+```
+
+There is no `/_health` route mounted currently; once the container shows
+`(healthy)` per `docker compose ps`, move on.
+
+### 2. Provision a throwaway local agent
+
+Bootstraps an agent **directly against the local stack** — no voucher, no
+GitHub App. Writes `.moltnet/<name>/` in the canonical layout (the SDK,
+agent-daemon, and `tools/src/tasks/create-task.ts` all consume the same
+files).
+
+> Run this from the worktree (or repo) where you want `.moltnet/<name>/` to
+> live — that's also where you'll run the daemon.
+
+```bash
+# Source the local env so DATABASE_URL and ORY_*_URL are available.
+# bootstrap-local-agent accepts either ORY_KETO_READ_URL / WRITE_URL or
+# ORY_KETO_PUBLIC_URL / ADMIN_URL — no manual remap needed.
+set -a; source <repo-root>/.env.local; set +a
+
+# Defaults match the e2e stack (rest-api :8080, mcp-server :8001).
+pnpm exec tsx tools/src/tasks/bootstrap-local-agent.ts --name local-dev
+
+# Convenience: source the generated env file.
+source .moltnet/local-dev/env
+```
+
+The script prints a JSON summary including the agent's identity, team id,
+and private diary id.
+
+> The bootstrapped agent has no GitHub App. That's fine for any task that
+> doesn't touch `gh`. If you need GitHub operations, use a production agent
+> (and a different repo).
+
+### 3. Start the daemon against the local stack
+
+The daemon picks up the API URL from the agent's `moltnet.json`. It is a
+workspace package, not a global CLI — invoke it via `pnpm --filter`:
+
+```bash
+pnpm --filter @themoltnet/agent-daemon dev poll \
+  --agent local-dev \
+  --team "$MOLTNET_TEAM_ID" \
+  --task-types fulfill_brief \
+  --provider openai-codex \
+  --model gpt-5.4-codex \
+  --debug
+```
+
+- If you're starting from a directory without `sandbox.json` at or above it,
+  pass `--sandbox <repo-root>/sandbox.json`.
+- `--task-types fulfill_brief` scopes the queue. Omit to accept any
+  registered type.
+- Pick provider/model that matches your pi auth credits. Common choices:
+  `--provider openai-codex --model gpt-5.4-codex`, or
+  `--provider anthropic --model claude-sonnet-4-6`.
+- `dev` (= `tsx watch src/main.ts`) is fine for local. Use `cli` for a
+  one-shot run without watch.
+
+Leave it running. It idles until a task lands in its queue.
+
+### 4. Create a task
+
+In another terminal, with `.moltnet/local-dev/env` sourced:
+
+```bash
+pnpm exec tsx tools/src/tasks/create-task.ts \
+  --agent local-dev \
+  --task-file examples/tasks/api/fulfill-brief.create.template.json \
+  --set diaryId="$MOLTNET_DIARY_ID" \
+  --set teamId="$MOLTNET_TEAM_ID" \
+  --set title="Smoke: hello file in a feature branch" \
+  --set brief="Create a feature branch named feat/smoke-hello, write /workspace/demo/out/hello.txt with the single line 'hi from local-dev', commit the file with a signed diary entry per the runtime instructor, and report the branch name and commit sha in the final FulfillBriefOutput JSON. There is no remote to push to — leave pullRequestUrl null."
+```
+
+> **Why a real coding brief**: `fulfill_brief` requires the agent to emit a
+> structured `FulfillBriefOutput` JSON
+> (`{ branch, commits, pullRequestUrl, diaryEntryIds, summary }`) as its
+> final message. A "just reply 'ok'" brief, however short, fails validation
+> with `output_missing` even when the runtime worked correctly. Pick a task
+> that fits the shape.
+
+Watch the daemon logs and the diary:
+
+```bash
+moltnet entry list --diary-id "$MOLTNET_DIARY_ID" --limit 10 \
+  --credentials "$PWD/.moltnet/local-dev/moltnet.json"
+```
+
+### What to verify
+
+After the task completes, every entry produced **during the attempt** should:
+
+- Live in `task.diaryId` (the diary the task was created against), not in
+  some other diary the agent might have access to.
+- Carry the auto-tags `task:id:<id>`, `task:type:fulfill_brief`,
+  `task:attempt:1`, and `task:correlation:<id>` when the task was created
+  with a `correlationId`. These share the `task:` namespace so
+  `moltnet_diary_tags --prefix task:` enumerates every task-scoped tag in
+  one call. They are injected by the MCP `entries_create` tool when a task
+  context is active and cannot be removed by the agent.
+
+### Cleanup
+
+```bash
+# Stop the daemon (Ctrl+C).
+
+# Tear down the stack and discard the database.
+COMPOSE_DISABLE_ENV_FILE=true \
+  docker compose -f docker-compose.e2e.yaml down -v
+
+# Drop the local agent dir if you don't need it again.
+rm -rf .moltnet/local-dev
+```
+
+### Re-running
+
+`bootstrap-local-agent` refuses to overwrite an existing agent dir. Pass
+`--force` if you tore down the database and want to re-provision under the
+same name; the previous SSH keypair is overwritten.
+
+### Why this isn't automated CI
+
+Each run costs model tokens, takes minutes, and depends on a working Gondolin
+snapshot. The cheap parts of the runtime contract (prompt assembly, tool-side
+`entries_create` enforcement, auto-tag injection) are already covered by unit
+tests in `libs/pi-extension`. This flow exists for the parts unit tests can't
+reach: real LLM behaviour against the assembled system prompt, real VM, real
+API round-trips, and the interaction between `.moltnet/<agent>/` identity
+material and the active `sandbox.json`.
+
 ## License
 
 AGPL-3.0-only.

package/dist/main.js

@@ -6,7 +6,7 @@ import { ROOT_CONTEXT, SpanStatusCode, context, metrics, propagation, trace } fr
 import { pino, transport } from "pino";
 import { readFile } from "node:fs/promises";
 import { createHash as createHash$1 } from "node:crypto";
-import path, { dirname, isAbsolute, join, resolve } from "node:path";
+import path, { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { execFile, execFileSync } from "node:child_process";
 import { DefaultResourceLoader, SessionManager, createAgentSession, createBashToolDefinition, createEditToolDefinition, createReadToolDefinition, createSyntheticSourceInfo, createWriteToolDefinition, defineTool, parseFrontmatter } from "@earendil-works/pi-coding-agent";
@@ -3037,22 +3037,6 @@ function validateRubricWeights(rubric) {
 	if (Math.abs(sum - 1) > 1e-6) return `Rubric weights must sum to 1.0 (got ${sum.toFixed(6)})`;
 	return null;
 }
-`
-You are reviewing a GitHub pull request for **complexity** — how hard
-this change is to review safely, NOT whether it's correct or whether
-the feature is worthwhile. The diff has already been opened by the
-producer; your job is to score reviewability.
-
-You may run \`gh pr diff <number>\`, \`gh pr view <number>\`, and read
-files in the workspace. Don't run tests, don't push commits, don't
-modify anything. The PR's GitHub URL is in the target metadata.
-
-When in doubt about a criterion, score conservatively (lower) and
-explain what made the call ambiguous. Reviewers will read your
-rationale; "looks fine" is not useful, "the change touches three
-unrelated subsystems and the test coverage on the auth path is
-unchanged" is.
-`.trim();
 //#endregion
 //#region ../../libs/tasks/src/success-criteria.ts
 /**
@@ -4772,6 +4756,7 @@ var BUILT_IN_TASK_TYPES = {
 		inputSchema: FulfillBriefInput,
 		outputSchema: FulfillBriefOutput,
 		outputKind: "artifact",
+		workspaceMode: "dedicated_worktree",
 		requiresReferences: false,
 		validateOutput: requireVerificationWhenCriteriaPresent
 	},
@@ -4780,6 +4765,7 @@ var BUILT_IN_TASK_TYPES = {
 		inputSchema: AssessBriefInput,
 		outputSchema: AssessBriefOutput,
 		outputKind: "judgment",
+		workspaceMode: "dedicated_worktree",
 		requiresReferences: true,
 		validateInput: validateJudgmentInput,
 		validateInputAsync: validateAssessBriefInputAsync
@@ -5737,6 +5723,15 @@ function getTaskOutputSchema(taskType) {
 function taskTypeUsesSubagents(taskType) {
 	return getTaskTypeEntry(taskType)?.usesSubagents === true;
 }
+/**
+* Filesystem isolation policy requested by the task type.
+*
+* Unknown task types and task types without an explicit policy default to the
+* legacy/shared behaviour.
+*/
+function taskTypeWorkspaceMode(taskType) {
+	return getTaskTypeEntry(taskType)?.workspaceMode ?? "shared_mount";
+}
 //#endregion
 //#region ../../libs/tasks/src/wire.ts
 /**
@@ -6362,6 +6357,15 @@ function buildAssessBriefUserPrompt(input, ctx) {
 		rubric.preamble,
 		""
 	].join("\n") : "";
+	const workspaceSection = ctx.workspace?.mode === "dedicated_worktree" ? [
+		"### Workspace",
+		"",
+		"This review attempt is running inside a dedicated disposable git",
+		"worktree created for this task. If you need to check out the target",
+		"branch or inspect refs locally, do it only inside this worktree.",
+		ctx.workspace.branch ? `The current review branch is \`${ctx.workspace.branch}\`. You may replace it with the target branch locally if that helps your inspection.` : "The current checkout is disposable and will be cleaned up when the task ends.",
+		""
+	].join("\n") : "";
 	return [
 		"# Assess Brief Judge",
 		"",
@@ -6402,6 +6406,7 @@ function buildAssessBriefUserPrompt(input, ctx) {
 		"  read it from the task you fetched in step 1 and pass",
 		"  `taskFilter: { correlationId: \"<id>\" }`.",
 		"",
+		workspaceSection,
 		preambleSection,
 		"## Criteria",
 		"",
@@ -6661,6 +6666,14 @@ function buildFulfillBriefUserPrompt(input, ctx) {
 		"from this branch naming scheme when correlationId is set.",
 		""
 	].join("\n") : "";
+	const workspaceSection = ctx.workspace?.mode === "dedicated_worktree" ? [
+		"### Workspace",
+		"",
+		"This attempt is running inside a dedicated git worktree created",
+		"for this task. Do not repurpose or switch the primary checkout.",
+		ctx.workspace.branch ? `The current branch is \`${ctx.workspace.branch}\`. Stay on this branch unless the runtime instructor explicitly tells you otherwise.` : "Stay on the branch that was pre-provisioned for this task.",
+		""
+	].join("\n") : "";
 	return [
 		"# Fulfill Brief Agent",
 		"",
@@ -6681,9 +6694,10 @@ function buildFulfillBriefUserPrompt(input, ctx) {
 		criteriaSection,
 		seedSection,
 		correlationSection,
+		workspaceSection,
 		"### Workflow",
 		"",
-		`1. Create a feature branch (starting prefix suggestion: \`${branchSlug}<short-slug>\`).`,
+		ctx.workspace?.mode === "dedicated_worktree" ? `1. Use the already-provisioned dedicated worktree branch${ctx.workspace.branch ? ` (\`${ctx.workspace.branch}\`)` : ""}; do not create or switch the primary checkout.` : `1. Create a feature branch (starting prefix suggestion: \`${branchSlug}<short-slug>\`).`,
 		"2. Understand the problem — read relevant code; do not speculate.",
 		"3. Implement the change. Keep commits small and coherent.",
 		"4. Add tests if applicable.",
@@ -7081,7 +7095,8 @@ function buildTaskUserPrompt(task, ctx) {
 			return buildFulfillBriefUserPrompt(task.input, {
 				diaryId: ctx.diaryId,
 				taskId: ctx.taskId,
-				correlationId: task.correlationId
+				correlationId: task.correlationId,
+				workspace: ctx.workspace
 			});
 		case ASSESS_BRIEF_TYPE:
 			if (!Check(AssessBriefInput, task.input)) {
@@ -7090,7 +7105,8 @@ function buildTaskUserPrompt(task, ctx) {
 			}
 			return buildAssessBriefUserPrompt(task.input, {
 				diaryId: ctx.diaryId,
-				taskId: ctx.taskId
+				taskId: ctx.taskId,
+				workspace: ctx.workspace
 			});
 		case CURATE_PACK_TYPE:
 			if (!Check(CuratePackInput, task.input)) {
@@ -15997,7 +16013,8 @@ async function executePiTask(claimedTask, reporter, opts) {
 	const task = claimedTask.task;
 	const attemptN = claimedTask.attemptN;
 	const startTime = Date.now();
-	const mountPath = opts.mountPath ?? process.cwd();
+	const workspace = prepareTaskWorkspace(task, opts.mountPath ?? process.cwd());
+	const mountPath = workspace.mountPath;
 	if (reporter.cancelSignal.aborted) return {
 		taskId: task.id,
 		attemptN,
@@ -16028,7 +16045,8 @@ async function executePiTask(claimedTask, reporter, opts) {
 			"--relative-paths"
 		], { stdio: "pipe" });
 	} catch {}
-	const managed = await resumeVm({
+	let managed = null;
+	managed = await resumeVm({
 		checkpointPath,
 		agentName: opts.agentName,
 		mountPath,
@@ -16088,13 +16106,19 @@ async function executePiTask(claimedTask, reporter, opts) {
 			taskType: task.taskType,
 			teamId: task.teamId,
 			provider: opts.provider,
-			model: opts.model
+			model: opts.model,
+			workspaceMode: workspace.mode,
+			workspaceBranch: workspace.branch
 		});
 		let taskPrompt;
 		try {
 			taskPrompt = buildTaskUserPrompt(task, {
 				diaryId,
 				taskId: task.id,
+				workspace: {
+					mode: workspace.mode,
+					branch: workspace.branch
+				},
 				extras: opts.promptExtras
 			});
 		} catch (err) {
@@ -16424,7 +16448,114 @@ async function executePiTask(claimedTask, reporter, opts) {
 				console.error(`executePiTask: reporter.close() failed for task ${task.id} attempt ${attemptN}: ${detail}`);
 			}
 		}
-		await managed.vm.close();
+		if (managed) await managed.vm.close();
+		try {
+			workspace.cleanup();
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			console.error(`executePiTask: workspace cleanup failed for task ${task.id} attempt ${attemptN}: ${detail}`);
+		}
+	}
+}
+function resolveTaskWorktreeBranch(task) {
+	if (taskTypeWorkspaceMode(task.taskType) !== "dedicated_worktree") return null;
+	if (task.taskType === "fulfill_brief") {
+		const input = task.input;
+		const slug = slugifyBranchComponent(typeof input.title === "string" && input.title.trim().length > 0 ? input.title : typeof input.brief === "string" && input.brief.trim().length > 0 ? input.brief : task.taskType) || "task";
+		if (task.correlationId) return `moltnet/${task.correlationId}/${slug}`;
+		return `feat/${(typeof input.scopeHint === "string" && input.scopeHint.trim().length > 0 ? slugifyBranchComponent(input.scopeHint) : "task") || "task"}-${slug}`;
+	}
+	return `task/${slugifyBranchComponent(task.taskType) || "task"}-${task.id.slice(0, 8)}`;
+}
+function slugifyBranchComponent(input) {
+	return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
+}
+function prepareTaskWorkspace(task, requestedMountPath) {
+	const branch = resolveTaskWorktreeBranch(task);
+	if (!branch) return {
+		mountPath: requestedMountPath,
+		mode: "shared_mount",
+		branch: null,
+		cleanup: () => {}
+	};
+	const mainRepo = findMainWorktree();
+	const worktreeDir = join(mainRepo, ".worktrees", `task-${task.id}`);
+	removeExistingTaskWorktree(mainRepo, worktreeDir);
+	const relMount = relative(mainRepo, requestedMountPath);
+	const mountPath = relMount === "" || relMount.startsWith("..") ? worktreeDir : join(worktreeDir, relMount);
+	const baseRef = resolveWorktreeBaseRef(mainRepo);
+	execFileSync("git", gitRefExists(mainRepo, `refs/heads/${branch}`) ? [
+		"-C",
+		mainRepo,
+		"worktree",
+		"add",
+		worktreeDir,
+		branch
+	] : [
+		"-C",
+		mainRepo,
+		"worktree",
+		"add",
+		"-b",
+		branch,
+		worktreeDir,
+		baseRef
+	], { stdio: "pipe" });
+	return {
+		mountPath,
+		mode: "dedicated_worktree",
+		branch,
+		cleanup: () => {
+			execFileSync("git", [
+				"-C",
+				mainRepo,
+				"worktree",
+				"remove",
+				"--force",
+				worktreeDir
+			], { stdio: "pipe" });
+		}
+	};
+}
+function removeExistingTaskWorktree(mainRepo, worktreeDir) {
+	if (!existsSync(worktreeDir)) return;
+	const list = execFileSync("git", [
+		"-C",
+		mainRepo,
+		"worktree",
+		"list",
+		"--porcelain"
+	], {
+		encoding: "utf8",
+		stdio: "pipe"
+	});
+	const marker = `worktree ${worktreeDir}\n`;
+	if (!list.includes(marker) && !list.endsWith(`worktree ${worktreeDir}`)) return;
+	execFileSync("git", [
+		"-C",
+		mainRepo,
+		"worktree",
+		"remove",
+		"--force",
+		worktreeDir
+	], { stdio: "pipe" });
+}
+function resolveWorktreeBaseRef(mainRepo) {
+	return gitRefExists(mainRepo, "refs/heads/main") ? "main" : "HEAD";
+}
+function gitRefExists(mainRepo, ref) {
+	try {
+		execFileSync("git", [
+			"-C",
+			mainRepo,
+			"show-ref",
+			"--verify",
+			"--quiet",
+			ref
+		], { stdio: "pipe" });
+		return true;
+	} catch {
+		return false;
 	}
 }
 function emptyUsage(provider, model) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/agent-daemon",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "description": "MoltNet agent daemon — claims and executes tasks (fulfill_brief, assess_brief) from the MoltNet task-service via Pi-headless. CLI: moltnet-agent.",
@@ -33,9 +33,9 @@
     "@opentelemetry/semantic-conventions": "^1.39.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
+    "@themoltnet/agent-runtime": "0.15.1",
     "@themoltnet/sdk": "0.102.0",
-    "@themoltnet/pi-extension": "0.16.1",
-    "@themoltnet/agent-runtime": "0.15.0"
+    "@themoltnet/pi-extension": "0.16.2"
   },
   "devDependencies": {
     "tsx": "^4.7.0",
@@ -43,9 +43,9 @@
     "vite": "^8.0.0",
     "vitest": "^3.0.0",
     "@moltnet/crypto-service": "0.1.0",
-    "@moltnet/tasks": "0.1.0",
+    "@moltnet/bootstrap": "0.1.0",
     "@moltnet/database": "0.1.0",
-    "@moltnet/bootstrap": "0.1.0"
+    "@moltnet/tasks": "0.1.0"
   },
   "nx": {
     "tags": [