@drej/agent 0.1.1 → 0.2.0

package/dist/index.mjs

@@ -0,0 +1,941 @@
+import { Drej } from "drej";
+import { SQLiteAdapter } from "@drej/sqlite";
+import { existsSync } from "fs";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+//#region src/config.ts
+const CONFIG_FILE = "drej.config.json";
+const DEFAULT_CONFIG = {
+	serverUrl: "http://localhost:8080",
+	apiKey: "",
+	adapterPath: "./.drej/ledger.db",
+	useServerProxy: true,
+	agentsDir: "./agents",
+	defaults: { resources: {
+		cpu: "1000m",
+		memory: "1Gi"
+	} }
+};
+/**
+* Read `drej.config.json` from the current working directory and merge it with
+* built-in defaults. Missing fields fall back to the defaults — the config file
+* is fully optional.
+*/
+async function readProjectConfig() {
+	if (!existsSync(CONFIG_FILE)) return DEFAULT_CONFIG;
+	const data = await Bun.file(CONFIG_FILE).json();
+	return {
+		...DEFAULT_CONFIG,
+		...data,
+		defaults: {
+			...DEFAULT_CONFIG.defaults,
+			...data.defaults ?? {},
+			resources: {
+				...DEFAULT_CONFIG.defaults.resources,
+				...data.defaults?.resources ?? {}
+			}
+		}
+	};
+}
+//#endregion
+//#region src/schema.ts
+function validateAgentSpec(data) {
+	if (!data || typeof data !== "object") throw new Error("Agent spec must be an object");
+	const item = data;
+	if (typeof item.name !== "string" || !item.name) throw new Error("Agent spec must have a 'name' string");
+	if (item.cli !== "pi") throw new Error(`Unsupported CLI: '${String(item.cli ?? "(missing)")}'. Supported values: pi`);
+	return item;
+}
+//#endregion
+//#region src/adapters/pi.ts
+const BRIDGE_SCRIPT = `
+"use strict";
+var spawn = require("child_process").spawn;
+var createInterface = require("readline").createInterface;
+var http = require("http");
+var fs = require("fs");
+
+var PORT = 3001;
+var ENV_FILE = "/etc/drej-env";
+var PI_CONFIG_FILE = "/etc/drej-pi.json";
+
+// Re-read /etc/drej-env into process.env on each Pi (re)start so setEnv() changes take effect.
+function loadEnv() {
+  if (!fs.existsSync(ENV_FILE)) return;
+  var lines = fs.readFileSync(ENV_FILE, "utf8").split("\\n");
+  for (var i = 0; i < lines.length; i++) {
+    var m = lines[i].match(/^export ([A-Za-z_][A-Za-z0-9_]*)="((?:[^"\\\\]|\\\\.)*)"$/);
+    if (m) process.env[m[1]] = m[2].replace(/\\\\"/g, '"').replace(/\\\\\\\\/g, "\\\\");
+  }
+}
+
+// Build the pi CLI args from /etc/drej-pi.json (model/provider config, written by the host).
+// Supports: provider, model, resume (--continue to resume the most recent session).
+function buildPiArgs() {
+  var args = ["--mode", "rpc", "--approve"];
+  try {
+    if (fs.existsSync(PI_CONFIG_FILE)) {
+      var cfg = JSON.parse(fs.readFileSync(PI_CONFIG_FILE, "utf8"));
+      if (cfg.provider) args.push("--provider", cfg.provider);
+      if (cfg.model) args.push("--model", cfg.model);
+      if (cfg.resume) args.push("--continue");
+    }
+  } catch (e) {}
+  return args;
+}
+
+// --- Ring-buffer logger ---
+var logBuf = [];
+function log(msg) {
+  var entry = "[" + new Date().toISOString() + "] " + msg;
+  if (logBuf.length >= 200) logBuf.shift();
+  logBuf.push(entry);
+  process.stderr.write(entry + "\\n");
+}
+
+// --- Pi process state ---
+// All mutable state lives in one object so it's easy to see what changes on restart.
+var state = {
+  proc: null,        // current ChildProcess
+  rl: null,          // readline interface on proc.stdout
+  ready: false,      // true once Pi responds to the get_state probe
+  active: null,      // { message, res, text, t0 } — the in-flight prompt, if any
+  queue: [],         // pending items: { message, streamingBehavior?, res, text, t0 }
+  gen: 0,            // incremented on every (re)start; guards against stale async callbacks
+  pendingCmds: {},   // id → { res, timer, bash? } — commands waiting for Pi's response ack
+};
+
+// Fail all in-flight pendingCmds cleanly, handling bash (SSE) vs regular (JSON) responses.
+function cleanupPendingCmds(reason) {
+  Object.keys(state.pendingCmds).forEach(function(id) {
+    var p = state.pendingCmds[id];
+    clearTimeout(p.timer);
+    if (p.bash) {
+      try { p.res.write("data: " + JSON.stringify({ error: reason }) + "\\n\\n"); p.res.end(); } catch (e) {}
+    } else {
+      respond(p.res, 500, { ok: false, error: reason });
+    }
+  });
+  state.pendingCmds = {};
+}
+
+function startPi() {
+  // End any in-flight SSE stream so the client isn't left hanging.
+  if (state.active) {
+    state.active.res.write("data: " + JSON.stringify({ error: "pi restarted" }) + "\\n\\n");
+    state.active.res.end();
+    state.active = null;
+  }
+  cleanupPendingCmds("pi restarted");
+
+  if (state.rl) { try { state.rl.close(); } catch (e) {} }
+  if (state.proc) { try { state.proc.kill("SIGTERM"); } catch (e) {} }
+  state.proc = null;
+  state.rl   = null;
+  state.ready  = false;
+  // NB: state.queue is intentionally preserved — queued prompts are re-sent to the new Pi.
+
+  loadEnv();
+  var args = buildPiArgs();
+  var gen = ++state.gen;
+  log("pi start gen=" + gen + ": " + args.join(" "));
+
+  var proc = spawn("pi", args, {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: Object.assign({}, process.env),
+  });
+  state.proc = proc;
+
+  proc.stderr.on("data", function(chunk) {
+    if (state.gen === gen) log("pi stderr: " + chunk.toString().trim());
+  });
+
+  state.rl = createInterface({ input: proc.stdout });
+  state.rl.on("line", function(line) {
+    if (state.gen === gen) handleLine(line);
+  });
+
+  proc.on("exit", function(code) {
+    if (state.gen !== gen) return;
+    log("pi exit gen=" + gen + " code=" + code);
+    state.proc  = null;
+    state.ready = false;
+    cleanupPendingCmds("pi exited");
+    if (state.active) {
+      state.active.res.write("data: " + JSON.stringify({ error: "pi exited" }) + "\\n\\n");
+      state.active.res.end();
+      state.active = null;
+    }
+  });
+
+  // Pi needs ~500ms to initialise its RPC layer before it can handle commands.
+  setTimeout(function() {
+    if (state.gen !== gen || !state.proc) return;
+    log("pi probe gen=" + gen);
+    rpc({ id: "__probe__", type: "get_state" });
+  }, 500);
+}
+
+// Write a JSON-RPC message to Pi's stdin.
+function rpc(msg) {
+  if (state.proc) state.proc.stdin.write(JSON.stringify(msg) + "\\n");
+}
+
+// Send an RPC command and hold the HTTP response open until Pi acks it.
+function rpcWithAck(msg, res) {
+  state.pendingCmds[msg.id] = { res: res };
+  rpc(msg);
+  state.pendingCmds[msg.id].timer = setTimeout(function() {
+    if (state.pendingCmds[msg.id]) {
+      respond(state.pendingCmds[msg.id].res, 504, { error: "timeout" });
+      delete state.pendingCmds[msg.id];
+    }
+  }, 5000);
+}
+
+// Dispatch a single line of output from Pi's stdout.
+function handleLine(line) {
+  if (!line.trim()) return;
+  var ev;
+  try { ev = JSON.parse(line); } catch (e) { return; }
+
+  if (!state.ready && ev.id === "__probe__" && ev.type === "response") {
+    state.ready = true;
+    var m = (ev.data && ev.data.model) || {};
+    log("pi ready model=" + m.id + " api=" + m.api);
+    flush();
+    return;
+  }
+
+  // Resolve a pending command ack.
+  // Bash returns output synchronously in ev.data — stream it as SSE then send [DONE].
+  // All other commands use JSON response.
+  if (ev.type === "response" && ev.id && state.pendingCmds[ev.id]) {
+    var pending = state.pendingCmds[ev.id];
+    clearTimeout(pending.timer);
+    delete state.pendingCmds[ev.id];
+    if (pending.bash) {
+      var output = (ev.data && ev.data.output) || "";
+      if (output) try { pending.res.write("data: " + JSON.stringify({ type: "text", text: output }) + "\\n\\n"); } catch (e) {}
+      try { pending.res.write("data: [DONE]\\n\\n"); pending.res.end(); } catch (e) {}
+    } else if (ev.success) {
+      respond(pending.res, 200, { ok: true, data: ev.data || null });
+    } else {
+      respond(pending.res, 400, { ok: false, error: ev.error || "unknown" });
+    }
+    return;
+  }
+
+  // Tool execution events: forward into the active prompt stream.
+  if (ev.type === "tool_execution_start") {
+    if (!state.active) return;
+    state.active.res.write("data: " + JSON.stringify({ type: "tool_start", toolCallId: ev.toolCallId, toolName: ev.toolName, args: ev.args }) + "\\n\\n");
+    return;
+  }
+  if (ev.type === "tool_execution_update") {
+    if (!state.active) return;
+    state.active.res.write("data: " + JSON.stringify({ type: "tool_update", toolCallId: ev.toolCallId, toolName: ev.toolName, partialResult: ev.partialResult }) + "\\n\\n");
+    return;
+  }
+  if (ev.type === "tool_execution_end") {
+    if (!state.active) return;
+    state.active.res.write("data: " + JSON.stringify({ type: "tool_end", toolCallId: ev.toolCallId, toolName: ev.toolName, result: ev.result, isError: !!ev.isError }) + "\\n\\n");
+    return;
+  }
+
+  var item = state.active;
+  if (!item) return;
+
+  // prompt: forward text_delta chunks and agent lifecycle
+  if (ev.type === "message_update") {
+    var aev = ev.assistantMessageEvent || {};
+    if (aev.type === "text_delta" && aev.delta) {
+      item.text += aev.delta;
+      item.res.write("data: " + JSON.stringify({ type: "text", text: aev.delta }) + "\\n\\n");
+    }
+  } else if (ev.type === "agent_end") {
+    log("agent_end: " + item.text.length + " chars in " + (Date.now() - item.t0) + "ms");
+    item.res.write("data: [DONE]\\n\\n");
+    item.res.end();
+    state.active = null;
+    flush();
+  }
+}
+
+// Send the next queued item to Pi, if Pi is ready and idle.
+// streamingBehavior items ("steer"/"followUp") bypass the active-slot gate and complete immediately.
+function flush() {
+  if (!state.ready || !state.queue.length || !state.proc) return;
+  var item = state.queue[0];
+  if (state.active && !item.streamingBehavior) return;
+  state.queue.shift();
+  if (!item.streamingBehavior) state.active = item;
+  item.t0 = Date.now();
+  var rpcMsg = { id: "p" + item.t0, type: "prompt", message: item.message };
+  if (item.streamingBehavior) rpcMsg.streamingBehavior = item.streamingBehavior;
+  rpc(rpcMsg);
+  item.res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", "Connection": "keep-alive" });
+  // Injections don't produce their own SSE body — their output arrives via the active prompt's stream.
+  if (item.streamingBehavior) {
+    item.res.write("data: [DONE]\\n\\n");
+    item.res.end();
+    flush();
+  }
+}
+
+// HTTP response helpers.
+function respond(res, status, body) {
+  try {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+  } catch (e) {}
+}
+
+// --- HTTP server ---
+startPi();
+
+http.createServer(function(req, res) {
+  // GET endpoints don't need a body.
+  if (req.method === "GET") {
+    if (req.url === "/health") { respond(res, 200, { ok: state.ready }); return; }
+    if (req.url === "/logs")   { res.writeHead(200, { "Content-Type": "text/plain" }); res.end(logBuf.join("\\n")); return; }
+    if (req.url === "/messages") { rpcWithAck({ id: "gm" + Date.now(), type: "get_messages" }, res); return; }
+    if (req.url === "/available-models") { rpcWithAck({ id: "gam" + Date.now(), type: "get_available_models" }, res); return; }
+    res.writeHead(404); res.end();
+    return;
+  }
+
+  if (req.method !== "POST") { res.writeHead(405); res.end(); return; }
+
+  var body = "";
+  req.on("data", function(d) { body += d; });
+  req.on("end", function() {
+    var data = {};
+    try { if (body) data = JSON.parse(body); } catch (e) { res.writeHead(400); res.end("bad json"); return; }
+
+    switch (req.url) {
+      case "/prompt":
+        state.queue.push({ message: data.message || "", streamingBehavior: data.streamingBehavior, res: res, text: "", t0: 0 });
+        flush();
+        return;
+
+      case "/bash": {
+        // Pi returns bash output synchronously in the ack's data.output — no streaming events.
+        if (!state.ready || !state.proc) { respond(res, 503, { error: "pi not ready" }); return; }
+        var bashId = "b" + Date.now();
+        var bashTimer = setTimeout(function() {
+          if (state.pendingCmds[bashId]) {
+            delete state.pendingCmds[bashId];
+            try { res.write("data: " + JSON.stringify({ error: "bash timeout" }) + "\\n\\n"); res.end(); } catch (e) {}
+          }
+        }, 30000);
+        state.pendingCmds[bashId] = { res: res, timer: bashTimer, bash: true };
+        res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", "Connection": "keep-alive" });
+        rpc({ id: bashId, type: "bash", command: data.command || "" });
+        return;
+      }
+
+      case "/abort":
+        // End the active SSE stream immediately, drain the queue, then wait for Pi's ack.
+        state.queue.length = 0;
+        if (state.active) {
+          state.active.res.write("data: [DONE]\\n\\n");
+          state.active.res.end();
+          state.active = null;
+        }
+        rpcWithAck({ id: "a" + Date.now(), type: "abort" }, res);
+        return;
+
+      case "/steer":
+        rpcWithAck({ id: "s" + Date.now(), type: "steer", message: data.message || "" }, res);
+        return;
+
+      case "/follow-up":
+        rpcWithAck({ id: "fu" + Date.now(), type: "follow_up", message: data.message || "" }, res);
+        return;
+
+      case "/new-session":
+        rpcWithAck({ id: "n" + Date.now(), type: "new_session" }, res);
+        return;
+
+      case "/fork":
+        rpcWithAck({ id: "fk" + Date.now(), type: "fork", entryId: data.entryId || "" }, res);
+        return;
+
+      case "/clone":
+        rpcWithAck({ id: "cl" + Date.now(), type: "clone" }, res);
+        return;
+
+      case "/switch-session":
+        rpcWithAck({ id: "ss" + Date.now(), type: "switch_session", sessionPath: data.sessionPath || "" }, res);
+        return;
+
+      case "/set-model":
+        rpcWithAck({ id: "sm" + Date.now(), type: "set_model", provider: data.provider || "", modelId: data.modelId || "" }, res);
+        return;
+
+      case "/cycle-model":
+        rpcWithAck({ id: "cm" + Date.now(), type: "cycle_model" }, res);
+        return;
+
+      case "/set-thinking-level":
+        rpcWithAck({ id: "stl" + Date.now(), type: "set_thinking_level", level: data.level || "medium" }, res);
+        return;
+
+      case "/cycle-thinking-level":
+        rpcWithAck({ id: "ctl" + Date.now(), type: "cycle_thinking_level" }, res);
+        return;
+
+      case "/compact": {
+        var compactMsg = { id: "co" + Date.now(), type: "compact" };
+        if (data.customInstructions) compactMsg.customInstructions = data.customInstructions;
+        rpcWithAck(compactMsg, res);
+        return;
+      }
+
+      case "/set-auto-compaction":
+        rpcWithAck({ id: "sac" + Date.now(), type: "set_auto_compaction", enabled: !!data.enabled }, res);
+        return;
+
+      case "/reload-env":
+        // Merge any inline env the host sent, then restart Pi so it picks up the new env file.
+        if (data.env && typeof data.env === "object") Object.assign(process.env, data.env);
+        startPi();
+        respond(res, 200, { ok: true });
+        return;
+
+      default:
+        res.writeHead(404); res.end("not found");
+    }
+  });
+}).listen(PORT, "0.0.0.0", function() {
+  process.stderr.write("drej-bridge :" + PORT + "\\n");
+});
+`;
+function toShellExports(env) {
+	return Object.entries(env).map(([k, v]) => `export ${k}="${v.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`).join("\n") + "\n";
+}
+function resolveEnv(env) {
+	const result = {};
+	for (const [key, value] of Object.entries(env)) result[key] = value.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] ?? "");
+	return result;
+}
+var PiAdapter = class {
+	_bridgeUrl = null;
+	get bridgeUrl() {
+		if (!this._bridgeUrl) throw new Error("PiAdapter: bridge not started");
+		return this._bridgeUrl;
+	}
+	/** Install Pi CLI and any spec packages. Slow — result is captured by checkpoint(). */
+	async install(sb, spec) {
+		const pkgs = [...new Set(spec.packages ?? [])].filter((p) => p !== "nodejs_22" && p !== "nodejs");
+		if (pkgs.length > 0) await sb.exec(`apt-get update -qq && apt-get install -y --no-install-recommends ${pkgs.join(" ")}`);
+		await sb.exec("npm install -g --ignore-scripts @earendil-works/pi-coding-agent");
+	}
+	/**
+	* Write config files and the bridge script. Always runs on every start (fresh install
+	* and snapshot resume alike) so env values, model/provider, and bridge code stay current.
+	*/
+	async configure(sb, spec, resolvedEnv, opts) {
+		const piConfig = {};
+		if (spec.provider) piConfig.provider = spec.provider;
+		if (spec.model) piConfig.model = spec.model;
+		if (opts?.resume) piConfig.resume = true;
+		await sb.writeFile("/etc/drej-pi.json", JSON.stringify(piConfig));
+		await sb.writeFile("/etc/drej-env", toShellExports(resolvedEnv));
+		await sb.writeFile("/drej-bridge.js", BRIDGE_SCRIPT);
+	}
+	async startBridge(sb) {
+		await sb.exec("node /drej-bridge.js &");
+		const { url } = await sb.proxy(3001);
+		this._bridgeUrl = url;
+	}
+	async waitReady(timeoutMs = 3e4) {
+		const deadline = Date.now() + timeoutMs;
+		while (Date.now() < deadline) {
+			try {
+				const res = await fetch(`${this.bridgeUrl}/health`);
+				if (res.ok) {
+					if ((await res.json()).ok) return;
+				}
+			} catch {}
+			await new Promise((r) => setTimeout(r, 500));
+		}
+		throw new Error(`drej-bridge did not become ready within ${timeoutMs / 1e3}s`);
+	}
+	prompt(message, opts) {
+		return sseStream(this.bridgeUrl, "/prompt", {
+			message,
+			streamingBehavior: opts?.streamingBehavior
+		});
+	}
+	bash(command) {
+		return sseStream(this.bridgeUrl, "/bash", { command });
+	}
+	async steer(message) {
+		const res = await fetch(`${this.bridgeUrl}/steer`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ message })
+		});
+		if (!res.ok) {
+			const body = await res.json().catch(() => ({}));
+			throw new Error(`steer failed: ${body.error ?? res.status}`);
+		}
+	}
+	async abort() {
+		await rpcPost(this.bridgeUrl, "/abort");
+	}
+	async followUp(message) {
+		await rpcPost(this.bridgeUrl, "/follow-up", { message });
+	}
+	async newSession() {
+		await rpcPost(this.bridgeUrl, "/new-session");
+	}
+	async setThinkingLevel(level) {
+		await rpcPost(this.bridgeUrl, "/set-thinking-level", { level });
+	}
+	async setAutoCompaction(enabled) {
+		await rpcPost(this.bridgeUrl, "/set-auto-compaction", { enabled });
+	}
+	async fork(entryId) {
+		return rpcPost(this.bridgeUrl, "/fork", { entryId });
+	}
+	async clone() {
+		return rpcPost(this.bridgeUrl, "/clone");
+	}
+	async switchSession(sessionPath) {
+		return rpcPost(this.bridgeUrl, "/switch-session", { sessionPath });
+	}
+	async setModel(provider, modelId) {
+		return rpcPost(this.bridgeUrl, "/set-model", {
+			provider,
+			modelId
+		});
+	}
+	async cycleModel() {
+		return rpcPost(this.bridgeUrl, "/cycle-model");
+	}
+	async cycleThinkingLevel() {
+		return rpcPost(this.bridgeUrl, "/cycle-thinking-level");
+	}
+	async compact(customInstructions) {
+		return rpcPost(this.bridgeUrl, "/compact", { customInstructions });
+	}
+	async getMessages() {
+		return (await rpcGet(this.bridgeUrl, "/messages")).messages;
+	}
+	async getAvailableModels() {
+		return (await rpcGet(this.bridgeUrl, "/available-models")).models;
+	}
+	async reloadEnv(env) {
+		await rpcPost(this.bridgeUrl, "/reload-env", { env });
+		await this.waitReady();
+	}
+	async getLogs() {
+		return (await fetch(`${this.bridgeUrl}/logs`)).text();
+	}
+};
+async function rpcPost(bridgeUrl, path, body = {}) {
+	const res = await fetch(`${bridgeUrl}${path}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body)
+	});
+	if (!res.ok) {
+		const err = await res.json().catch(() => ({}));
+		throw new Error(`${path} failed: ${err.error ?? res.status}`);
+	}
+	return (await res.json()).data;
+}
+async function rpcGet(bridgeUrl, path) {
+	const res = await fetch(`${bridgeUrl}${path}`);
+	if (!res.ok) throw new Error(`${path} failed: ${res.status}`);
+	return (await res.json()).data;
+}
+async function* sseStream(bridgeUrl, path, body) {
+	const res = await fetch(`${bridgeUrl}${path}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body)
+	});
+	if (!res.ok || !res.body) throw new Error(`Bridge ${path} error: ${res.status}`);
+	const reader = res.body.getReader();
+	const decoder = new TextDecoder();
+	let buf = "";
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		buf += decoder.decode(value, { stream: true });
+		const lines = buf.split("\n");
+		buf = lines.pop();
+		for (const line of lines) {
+			if (!line.startsWith("data: ")) continue;
+			const payload = line.slice(6).trim();
+			if (payload === "[DONE]") return;
+			const raw = JSON.parse(payload);
+			if (raw.error) throw new Error(`Bridge error: ${raw.error}`);
+			yield raw;
+		}
+	}
+}
+//#endregion
+//#region src/snapshots.ts
+/**
+* Hash of the fields that require re-installing the agent CLI:
+* cli, cliVersion, and packages. Excludes env (hot-reloadable),
+* model/provider (CLI flags only), and cosmetic fields.
+*/
+function computeSetupHash(spec) {
+	return createHash("sha256").update(JSON.stringify({
+		cli: spec.cli,
+		cliVersion: spec.cliVersion ?? "latest",
+		packages: [...spec.packages ?? []].sort(),
+		setup: spec.setup ?? []
+	})).digest("hex").slice(0, 12);
+}
+/** Derive the agent-snapshots.json path from the ledger adapter path. */
+function snapshotsPath(adapterPath) {
+	return `${dirname(adapterPath)}/agent-snapshots.json`;
+}
+/** File-backed store for agent snapshot records, keyed by specName + setupHash. */
+var AgentSnapshotStore = class {
+	path;
+	constructor(path) {
+		this.path = path;
+	}
+	async _read() {
+		try {
+			return JSON.parse(await readFile(this.path, "utf-8"));
+		} catch {
+			return {};
+		}
+	}
+	async _write(data) {
+		await mkdir(dirname(this.path), { recursive: true });
+		await writeFile(this.path, JSON.stringify(data, null, 2));
+	}
+	_key(specName, setupHash) {
+		return `${specName}:${setupHash}`;
+	}
+	async get(specName, setupHash) {
+		return (await this._read())[this._key(specName, setupHash)] ?? null;
+	}
+	async save(record) {
+		const data = await this._read();
+		for (const k of Object.keys(data)) if (data[k].specName === record.specName) delete data[k];
+		data[this._key(record.specName, record.setupHash)] = record;
+		await this._write(data);
+	}
+	/** Remove all snapshot records for the given spec name. */
+	async delete(specName) {
+		const data = await this._read();
+		for (const k of Object.keys(data)) if (data[k].specName === specName) delete data[k];
+		await this._write(data);
+	}
+	async list() {
+		return Object.values(await this._read());
+	}
+};
+//#endregion
+//#region src/agent.ts
+function elapsed(t) {
+	return `${Date.now() - t}ms`;
+}
+/**
+* A live AI coding agent running inside an OpenSandbox container.
+*
+* Wraps a Pi CLI process (`pi --mode rpc --approve`) in an HTTP bridge so the
+* host can send prompts and receive streamed responses over a stable API,
+* while Pi manages its own tool use, file writes, and code execution inside the
+* sandbox.
+*
+* Create an agent with `Agent.load(specPath)`. Always call `close()` when done
+* to release the underlying sandbox container.
+*
+* @example
+* ```ts
+* import { Agent } from "@drej/agent";
+*
+* const agent = await Agent.load("./agents/my-agent.json");
+* try {
+*   for await (const chunk of agent.prompt("Explain this codebase")) {
+*     process.stdout.write(chunk);
+*   }
+* } finally {
+*   await agent.close();
+* }
+* ```
+*/
+var Agent = class Agent {
+	/** OpenSandbox container ID for this agent's sandbox. */
+	sandboxId;
+	name;
+	/**
+	* Direct access to the underlying `Sandbox` — full drej Sandbox API, bypasses Pi.
+	* Use this to read or write files, run shell commands, or inspect container state
+	* independently of the Pi conversation.
+	*/
+	sandbox;
+	/**
+	* `true` when this agent was loaded from a cached snapshot (fast path).
+	* `false` on the first load for a given spec, or after `{ rebuild: true }`.
+	*/
+	fromSnapshot;
+	_adapter;
+	_env;
+	constructor(sandbox, spec, env, adapter, fromSnapshot) {
+		this.sandbox = sandbox;
+		this.sandboxId = sandbox.sandboxId;
+		this.name = spec.name;
+		this._adapter = adapter;
+		this._env = env;
+		this.fromSnapshot = fromSnapshot;
+	}
+	/**
+	* Load an agent spec from disk and return a fully initialised `Agent`.
+	*
+	* On first load the Pi CLI is installed inside a `node:22` sandbox, then
+	* the sandbox is checkpointed. Subsequent `load()` calls for the same spec
+	* restore from that snapshot — skipping the install and starting in ~3s instead
+	* of ~90s.
+	*
+	* Pass `{ rebuild: true }` to force a full reinstall (e.g. after changing
+	* the spec's `packages` or `cliVersion`).
+	*
+	* Logs timing for each phase to stdout via `[agent]` prefixed lines.
+	*/
+	static async load(specPath, opts) {
+		const t0 = Date.now();
+		const spec = validateAgentSpec(await Bun.file(specPath).json());
+		const config = await readProjectConfig();
+		const resolvedEnv = resolveEnv(spec.env ?? {});
+		const resources = {
+			...config.defaults.resources,
+			...spec.resources ?? {}
+		};
+		const client = new Drej({
+			baseUrl: config.serverUrl,
+			apiKey: config.apiKey,
+			adapter: new SQLiteAdapter(config.adapterPath),
+			useServerProxy: config.useServerProxy
+		});
+		const store = new AgentSnapshotStore(snapshotsPath(config.adapterPath));
+		const setupHash = computeSetupHash(spec);
+		const adapter = new PiAdapter();
+		let sb;
+		let fromSnapshot = false;
+		if (!opts?.rebuild) {
+			const record = await store.get(spec.name, setupHash);
+			if (record) try {
+				console.log(`[agent] restoring from snapshot...`);
+				const t1 = Date.now();
+				sb = await client.restoreSnapshot(record.snapshotId, spec.name, resources);
+				console.log(`[agent] snapshot ready  ${elapsed(t1)} (${sb.sandboxId})`);
+				fromSnapshot = true;
+			} catch {
+				console.log(`[agent] snapshot stale, rebuilding...`);
+				await store.delete(spec.name);
+			}
+		}
+		if (!fromSnapshot) {
+			console.log(`[agent] starting sandbox (${spec.name})...`);
+			const t1 = Date.now();
+			sb = await client.sandbox({
+				image: "node:22",
+				resources,
+				name: spec.name,
+				env: resolvedEnv
+			});
+			console.log(`[agent] sandbox ready   ${elapsed(t1)} (${sb.sandboxId})`);
+			console.log(`[agent] installing Pi CLI...`);
+			const t2 = Date.now();
+			await adapter.install(sb, spec);
+			console.log(`[agent] Pi CLI ready    ${elapsed(t2)}`);
+			for (const step of spec.setup ?? []) {
+				console.log(`[agent] setup: ${step.name}...`);
+				const ts = Date.now();
+				const cmd = step.cwd ? `cd ${step.cwd} && ${step.run}` : step.run;
+				await sb.exec(cmd);
+				console.log(`[agent] setup done      ${elapsed(ts)} (${step.name})`);
+			}
+			console.log(`[agent] checkpointing...`);
+			const t3 = Date.now();
+			const snapshotId = await sb.checkpoint();
+			await store.save({
+				specName: spec.name,
+				setupHash,
+				snapshotId,
+				createdAt: Date.now()
+			});
+			console.log(`[agent] checkpoint done ${elapsed(t3)}`);
+		}
+		await adapter.configure(sb, spec, resolvedEnv);
+		console.log(`[agent] starting bridge...`);
+		const t4 = Date.now();
+		await adapter.startBridge(sb);
+		await adapter.waitReady();
+		console.log(`[agent] bridge ready    ${elapsed(t4)}`);
+		console.log(`[agent] total           ${elapsed(t0)}${fromSnapshot ? " (from snapshot)" : ""}`);
+		return new Agent(sb, spec, resolvedEnv, adapter, fromSnapshot);
+	}
+	/**
+	* Reconnect to a previously-created agent whose host process has exited.
+	*
+	* The sandbox container must still be running. Pi and any installed packages
+	* are already present — only the bridge process needs to be restarted.
+	* Pi is started with `--continue` so it resumes the most recent session.
+	*
+	* @param sandboxId  The sandbox ID returned by the original `Agent.load()`.
+	* @param opts.specPath  Path to the agent spec JSON. If omitted, the ledger
+	*   is queried for the sandbox name and the spec is loaded from
+	*   `./agents/<name>.json`.
+	*
+	* @example
+	* ```ts
+	* // Original process:
+	* const agent = await Agent.load("./agents/hello-agent.json");
+	* console.log(agent.sandboxId); // save this
+	* // ... process exits ...
+	*
+	* // New process:
+	* const agent = await Agent.resume(savedSandboxId);
+	* for await (const chunk of agent.prompt("What did we discuss earlier?")) {
+	*   process.stdout.write(chunk);
+	* }
+	* await agent.close();
+	* ```
+	*/
+	static async resume(sandboxId, opts) {
+		const t0 = Date.now();
+		const config = await readProjectConfig();
+		const client = new Drej({
+			baseUrl: config.serverUrl,
+			apiKey: config.apiKey,
+			adapter: new SQLiteAdapter(config.adapterPath),
+			useServerProxy: config.useServerProxy
+		});
+		let spec;
+		if (opts?.specPath) spec = validateAgentSpec(await Bun.file(opts.specPath).json());
+		else {
+			const session = (await client.sandboxes.list()).find((s) => s.sandboxId === sandboxId);
+			if (!session) throw new Error(`No ledger record for sandbox ${sandboxId} — pass opts.specPath explicitly`);
+			spec = validateAgentSpec(await Bun.file(`./agents/${session.name}.json`).json());
+		}
+		const resolvedEnv = resolveEnv(spec.env ?? {});
+		console.log(`[agent] reconnecting to ${sandboxId}...`);
+		const t1 = Date.now();
+		const sb = await client.connect(sandboxId, spec.name);
+		console.log(`[agent] connected       ${elapsed(t1)}`);
+		await sb.exec("pkill -f 'node /drej-bridge.js' 2>/dev/null; sleep 0.1; true", { strict: false });
+		const adapter = new PiAdapter();
+		await adapter.configure(sb, spec, resolvedEnv, { resume: true });
+		console.log(`[agent] starting bridge...`);
+		const t2 = Date.now();
+		await adapter.startBridge(sb);
+		await adapter.waitReady();
+		console.log(`[agent] bridge ready    ${elapsed(t2)}`);
+		console.log(`[agent] total           ${elapsed(t0)}`);
+		return new Agent(sb, spec, resolvedEnv, adapter, false);
+	}
+	/** Send a prompt to Pi and stream the response. Pi manages its own session context. */
+	prompt(message, opts) {
+		return this._adapter.prompt(message, opts);
+	}
+	/** Run a shell command inside Pi's working context and stream stdout. */
+	bash(command) {
+		return this._adapter.bash(command);
+	}
+	/** Steer Pi's current response mid-flight. Waits for Pi's RPC acknowledgment. */
+	async steer(message) {
+		return this._adapter.steer(message);
+	}
+	/** Abort Pi's current operation. */
+	async abort() {
+		return this._adapter.abort();
+	}
+	/** Queue a message to be sent to Pi after it finishes its current task. */
+	async followUp(message) {
+		return this._adapter.followUp(message);
+	}
+	/** Start a fresh Pi session, clearing all prior context. */
+	async newSession() {
+		return this._adapter.newSession();
+	}
+	/** Set Pi's reasoning level (for models that support extended thinking). */
+	async setThinkingLevel(level) {
+		return this._adapter.setThinkingLevel(level);
+	}
+	/** Enable or disable Pi's automatic context compaction. */
+	async setAutoCompaction(enabled) {
+		return this._adapter.setAutoCompaction(enabled);
+	}
+	/**
+	* Fork Pi's session at the given entry ID, creating a new branch.
+	* Returns the text of the forked message and whether the fork was cancelled.
+	*/
+	async fork(entryId) {
+		return this._adapter.fork(entryId);
+	}
+	/** Clone the current Pi session into a new branch at the current position. */
+	async clone() {
+		return this._adapter.clone();
+	}
+	/** Switch Pi to a different session file on disk. */
+	async switchSession(sessionPath) {
+		return this._adapter.switchSession(sessionPath);
+	}
+	/** Switch Pi to a specific model. Returns the activated model. */
+	async setModel(provider, modelId) {
+		return this._adapter.setModel(provider, modelId);
+	}
+	/** Cycle Pi to the next available model. Returns null if only one model is configured. */
+	async cycleModel() {
+		return this._adapter.cycleModel();
+	}
+	/** Cycle Pi's thinking level. Returns null if the current model doesn't support thinking. */
+	async cycleThinkingLevel() {
+		return this._adapter.cycleThinkingLevel();
+	}
+	/** Manually trigger Pi's context compaction. */
+	async compact(customInstructions) {
+		return this._adapter.compact(customInstructions);
+	}
+	/** Retrieve Pi's full conversation history for the current session. */
+	async getMessages() {
+		return this._adapter.getMessages();
+	}
+	/** List all models available to Pi under the current provider configuration. */
+	async getAvailableModels() {
+		return this._adapter.getAvailableModels();
+	}
+	/**
+	* Set or update env vars in the running container. Writes to /etc/drej-env and restarts
+	* the Pi subprocess so it picks up the new env. Waits until Pi is ready before returning.
+	*/
+	async setEnv(vars) {
+		this._env = {
+			...this._env,
+			...vars
+		};
+		await this.sandbox.writeFile("/etc/drej-env", toShellExports(this._env));
+		await this._adapter.reloadEnv(this._env);
+	}
+	/** Retrieve recent bridge logs (ring-buffered, last 200 entries). */
+	async getLogs() {
+		return this._adapter.getLogs();
+	}
+	/** Delete the sandbox container and release all resources. Always call in a `finally` block. */
+	async close() {
+		await this.sandbox.close();
+	}
+};
+//#endregion
+//#region src/types.ts
+/** Filter an `AgentStream` down to just text chunks. */
+async function* textOnly(stream) {
+	for await (const ev of stream) if (ev.type === "text") yield ev.text;
+}
+//#endregion
+export { Agent, AgentSnapshotStore, computeSetupHash, snapshotsPath, textOnly, validateAgentSpec };