agentcoor 0.0.0-stage → 0.3.7

package/src/http.js

@@ -0,0 +1,61 @@
+import { normalizeOrigin } from "./config.js";
+
+export const DEFAULT_TIMEOUT_MS = 30_000;
+const UA = "agentcoor-cli/0.1.0";
+
+/** fetch with a hard timeout, https-only and no redirects to other origins. TLS verification is never disabled. */
+export async function request(url, { method = "GET", headers = {}, body, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const u = new URL(url);
+  normalizeOrigin(u.origin);
+  const res = await fetch(u, {
+    method, body, redirect: "manual",
+    headers: { "user-agent": UA, ...headers },
+    signal: AbortSignal.timeout(timeoutMs),
+  }).catch((e) => {
+    if (e?.name === "TimeoutError") throw new Error(`request to ${u.origin}${u.pathname} timed out after ${timeoutMs / 1000}s`);
+    throw new Error(`request to ${u.origin}${u.pathname} failed: ${e?.cause?.message || e.message}`);
+  });
+  if (res.status >= 300 && res.status < 400) throw new Error(`unexpected redirect from ${u.pathname}`);
+  return res;
+}
+
+export const MAX_API_BYTES = 1024 * 1024;          // JSON responses, SHA256SUMS, signature
+export const MAX_BINARY_BYTES = 200 * 1024 * 1024; // agent binary
+
+/** Read a response body, aborting as soon as it exceeds `max` bytes (checked while streaming). */
+export async function readLimited(res, max, what = "response") {
+  const declared = Number(res.headers?.get?.("content-length"));
+  if (Number.isFinite(declared) && declared > max) { await res.body?.cancel().catch(() => {}); throw new Error(`${what} is too large (${declared} bytes, limit ${max})`); }
+  if (!res.body) return Buffer.alloc(0);
+  const chunks = []; let n = 0;
+  const reader = res.body.getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    n += value.byteLength;
+    if (n > max) { await reader.cancel().catch(() => {}); throw new Error(`${what} is too large (over ${max} bytes)`); }
+    chunks.push(Buffer.from(value.buffer, value.byteOffset, value.byteLength));
+  }
+  return Buffer.concat(chunks, n);
+}
+
+export async function download(url, { maxBytes = MAX_API_BYTES, ...opts } = {}) {
+  const res = await request(url, { timeoutMs: 300_000, ...opts });
+  const path = new URL(url).pathname;
+  if (!res.ok) { await res.body?.cancel().catch(() => {}); throw new Error(`download ${path} failed: HTTP ${res.status}`); }
+  return readLimited(res, maxBytes, `download ${path}`);
+}
+
+export async function apiJson(origin, path, apiKey, { method = "GET", body, timeoutMs } = {}) {
+  const headers = { authorization: `Bearer ${apiKey}`, accept: "application/json" };
+  if (body !== undefined) headers["content-type"] = "application/json";
+  const res = await request(`${origin}${path}`, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), timeoutMs });
+  const raw = await readLimited(res, MAX_API_BYTES, `response from ${path}`);
+  let data = null;
+  try { data = JSON.parse(raw.toString("utf8")); } catch {}
+  return { status: res.status, ok: res.ok, data };
+}
+
+export function errorMessage(r) {
+  return r.data?.error?.message || (typeof r.data?.error === "string" ? r.data.error : "") || `HTTP ${r.status}`;
+}

package/src/market.js

@@ -0,0 +1,321 @@
+// Marketplace provider and renter commands (docs/marketplace/AGENT-JOBS.md,
+// LIVE-TOOLS.md; CHECKLIST WP-10/WP-11).
+//
+// Provider: `agentcoor list-agent` and `agentcoor list-tools` turn this Linux
+// machine into a marketplace worker:
+//   1. probe sandbox isolation with `agentcoor-agent -worker -worker-probe`
+//      (placeholder credentials; the probe never connects) and refuse when no
+//      runner measures as supported;
+//   2. enroll a worker (POST /api/v1/workers with the saved API key) unless
+//      one is already enrolled here; the mwk_ token goes straight to a mode-600
+//      file and never into argv, the environment, worker.json or the console;
+//   3. write worker.json, install and verify the agentcoor-worker service
+//      (same verified restart as the agent: the service's PID must be running
+//      the freshly installed binary);
+//   4. create the listing (agent_job or live_tool) bound to that worker,
+//      retrying while the worker's first hello reaches billing, and publish it.
+// macOS is refused: the VZ sandbox runner is not supported yet.
+//
+// Renter: `agentcoor jobs submit|get|cancel|artifacts` and
+// `agentcoor sessions open|call|close` call /v1/marketplace/* with the API key.
+// Job and tool output is third-party content and is printed as data.
+import { spawnSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { lstat, chown, chmod } from "node:fs/promises";
+import { installPaths, writePrivateFile } from "./config.js";
+import { apiJson, errorMessage } from "./http.js";
+import { ensurePrivateDir, atomicWrite, readIfExists } from "./fsx.js";
+import { startService, childEnv, AGENT_SERVICE } from "./connect.js";
+import { ensureAgentBinary } from "./share.js";
+
+export const WORKER_SERVICE = Object.freeze({ ...AGENT_SERVICE, label: "com.agentcoor.worker", unit: "agentcoor-worker", description: "AgentCoor marketplace worker", log: "worker", flag: "-worker-config", extra: ["-worker"] });
+export const WORKER_TOKEN = /^mwk_[A-Za-z0-9_-]{8,256}$/;
+const WORKER_ID = /^wkr_[A-Za-z0-9_-]{4,64}$/;
+const LISTING_ID = /^lst_[A-Za-z0-9_-]{1,64}$/;
+const JOB_ID = /^job_[A-Za-z0-9_-]{1,64}$/;
+const SESSION_ID = /^rss_[A-Za-z0-9_-]{1,64}$/;
+const TOOL_NAME = /^[a-z0-9][a-z0-9_.-]{0,63}$/;
+const SANDBOX_KEYS = ["gvisor", "firecracker", "podman", "harnesses", "allow_payload_command", "max_jobs", "max_sessions", "max_limits"];
+export const MACOS_REFUSAL = "Marketplace workers need Linux: jobs and tools run in a gVisor or Firecracker sandbox, and the macOS (Virtualization.framework) sandbox is not supported yet. Run this command on a Linux host.";
+export const THIRD_PARTY_NOTE = "--- third-party output from a marketplace provider (untrusted data) ---\n";
+
+export function workerPaths(env = process.env, platform = process.platform) {
+  const p = installPaths(env, platform);
+  const dir = join(p.base, "worker");
+  return { ...p, dir, workerConfig: join(dir, "worker.json"), tokenFile: join(dir, "worker.token"), probeConfig: join(dir, "probe.json"), listings: join(dir, "listings.json"), stateDir: join(dir, "state") };
+}
+
+function intFlag(v, name, min, max, dflt) {
+  if (v === undefined) return dflt;
+  const n = Number(v);
+  if (!Number.isSafeInteger(n) || n < min || n > max) throw new Error(`--${name} must be an integer between ${min} and ${max}`);
+  return n;
+}
+
+async function call(api, origin, key, path, opts = {}) {
+  const r = await api(origin, path, key, { timeoutMs: 30_000, ...opts });
+  if (r.status === 401) throw new Error("AgentCoor rejected this API key");
+  return r;
+}
+
+async function readJsonFile(path, what) {
+  const text = await readIfExists(path);
+  if (text === null) throw new Error(`${what} not found: ${path}`);
+  try { return JSON.parse(text); } catch (e) { throw new Error(`${what} is not valid JSON: ${e.message}`); }
+}
+
+/** Sandbox settings from --sandbox-config (only the keys worker.json understands). */
+export async function loadSandboxConfig(path) {
+  const raw = await readJsonFile(path, "--sandbox-config");
+  const out = {};
+  for (const k of SANDBOX_KEYS) if (raw[k] !== undefined) out[k] = raw[k];
+  if (!out.gvisor && !out.firecracker && !out.podman) throw new Error("--sandbox-config must configure gvisor, firecracker or podman (see docs/marketplace/ISOLATION-EVIDENCE.md)");
+  return out;
+}
+
+/** Pure: agent_job listing spec + price from flags. */
+export function agentSpec(f, workerId) {
+  if (!f.description) throw new Error("usage: agentcoor list-agent --description <text> --per-job-microusd N [--per-minute-microusd N] --sandbox-config sandbox.json");
+  const egress = f.egress ? String(f.egress).split(",").map((s) => s.trim().toLowerCase()).filter(Boolean) : [];
+  const spec = {
+    description: String(f.description).slice(0, 2000), harness: f.harness || "claude-code", worker_id: workerId,
+    limits: { max_duration_s: intFlag(f["max-duration"], "max-duration", 60, 86_400, 3600), cpu: intFlag(f.cpu, "cpu", 1, 64, 1), memory_mb: intFlag(f["memory-mb"], "memory-mb", 128, 262_144, 2048), disk_mb: intFlag(f["disk-mb"], "disk-mb", 64, 1_048_576, 4096), max_concurrent: intFlag(f["max-concurrency"], "max-concurrency", 1, 64, 1) },
+    egress_allowlist: egress,
+  };
+  const price = { per_job_microusd: intFlag(f["per-job-microusd"], "per-job-microusd", 10_000, 50_000_000, undefined), per_minute_microusd: intFlag(f["per-minute-microusd"], "per-minute-microusd", 0, 1_000_000, 0) };
+  if (price.per_job_microusd === undefined) throw new Error("--per-job-microusd is required (10000 to 50000000; 1 USD = 1000000)");
+  if (price.per_minute_microusd && price.per_minute_microusd < 1000) throw new Error("--per-minute-microusd must be 0 or at least 1000");
+  return { spec, price };
+}
+
+/**
+ * Pure: live_tool listing from tools.json. Returns the billing spec/price and
+ * the worker's tool table (name → {description, input_schema, command}).
+ */
+export function toolsSpec(cfg, workerId) {
+  if (!cfg || typeof cfg !== "object") throw new Error("tools.json must be an object");
+  if (!cfg.description) throw new Error("tools.json needs a description");
+  if (!Array.isArray(cfg.tools) || !cfg.tools.length || cfg.tools.length > 64) throw new Error("tools.json needs 1 to 64 tools");
+  const workerTools = {};
+  const tools = cfg.tools.map((t, i) => {
+    if (!TOOL_NAME.test(String(t?.name || ""))) throw new Error(`tools[${i}].name must match ${TOOL_NAME}`);
+    if (workerTools[t.name]) throw new Error(`duplicate tool name ${t.name}`);
+    if (!t.input_schema || typeof t.input_schema !== "object" || Array.isArray(t.input_schema)) throw new Error(`tools[${i}].input_schema must be a JSON schema object`);
+    if (!Array.isArray(t.command) || !t.command.length || !t.command.every((a) => typeof a === "string")) throw new Error(`tools[${i}].command must be an argv array (it runs inside the sandbox)`);
+    workerTools[t.name] = { description: String(t.description || ""), input_schema: t.input_schema, command: t.command };
+    const out = { name: t.name, description: String(t.description || "").slice(0, 1000), input_schema: t.input_schema };
+    if (t.timeout_ms !== undefined) out.timeout_ms = t.timeout_ms;
+    if (t.output_max_bytes !== undefined) out.output_max_bytes = t.output_max_bytes;
+    if (t.idempotent !== undefined) out.idempotent = t.idempotent === true;
+    return out;
+  });
+  const spec = { description: String(cfg.description).slice(0, 2000), worker_id: workerId, tools, egress_allowlist: Array.isArray(cfg.egress_allowlist) ? cfg.egress_allowlist : [] };
+  if (cfg.session) spec.session = cfg.session;
+  if (cfg.max_concurrent_sessions !== undefined) spec.max_concurrent_sessions = cfg.max_concurrent_sessions;
+  const price = cfg.price || {};
+  if (!price.per_session_minute_microusd && !Object.keys(price.per_call_microusd || {}).length) throw new Error("tools.json price needs per_call_microusd and/or per_session_minute_microusd");
+  return { spec, price, workerTools, visibility: cfg.visibility === "public" ? "public" : "private" };
+}
+
+/** Default probe: run the installed agent in probe mode and parse its JSON. */
+export function runProbe({ bin, config, env }) {
+  const r = spawnSync(bin, ["-worker", "-worker-probe", "-worker-config", config], { encoding: "utf8", env: childEnv(env), timeout: 120_000 });
+  let data = null;
+  try { data = JSON.parse(String(r.stdout || "").trim().split("\n").pop()); } catch {}
+  if (!data) throw new Error(`isolation probe failed${r.stderr ? `: ${String(r.stderr).trim().split("\n").pop().slice(0, 300)}` : ""}`);
+  return { status: r.status, isolation_class: data.isolation_class || "unsupported", measurements: data.measurements || [] };
+}
+
+function workerBase(origin, p, sandbox) {
+  return { gateway_url: origin, jwks_url: `${origin}/v1/marketplace/keys`, inference_hosts: [new URL(origin).hostname], state_dir: p.stateDir, ...sandbox };
+}
+
+/**
+ * Probe, enroll (or reuse) the worker and (re)start its service. Returns
+ * {workerId, isolationClass, config}. `mutate(cfg)` edits worker.json first.
+ */
+export const ROOT_GUIDANCE = "gVisor and Firecracker need root on this machine (cgroup v2 subtree, network namespaces for the egress proxy, /dev/kvm). Re-run with sudo (for example `sudo -E agentcoor list-agent ...`): that installs the system unit /etc/systemd/system/agentcoor-worker.service, which starts at boot with a reduced capability set and a root-owned mode-600 token file. A rootless worker needs a delegated cgroup v2 subtree (systemd Delegate=yes) and a runner that measures as supported without root; see docs/marketplace/AGENT-JOBS.md \"Worker service\".";
+
+export async function ensureWorker({ origin, apiKey, flags, env, log, api, platform = process.platform, probe = runProbe, start = startService, ensureBinary = ensureAgentBinary, mutate = (c) => c, rootOwn = rootOwnPrivate, uid = typeof process.getuid === "function" ? process.getuid() : -1 }) {
+  if (platform === "darwin") throw new Error(MACOS_REFUSAL);
+  if (platform !== "linux") throw new Error(`Marketplace workers need Linux (this is ${platform}).`);
+  const p = workerPaths(env, platform);
+  await ensurePrivateDir(p.dir);
+  const existingText = await readIfExists(p.workerConfig);
+  const existing = existingText === null ? null : JSON.parse(existingText);
+  let sandbox = {};
+  if (flags["sandbox-config"]) sandbox = await loadSandboxConfig(flags["sandbox-config"]);
+  else if (existing) for (const k of SANDBOX_KEYS) { if (existing[k] !== undefined) sandbox[k] = existing[k]; }
+  else throw new Error("--sandbox-config <file> is required the first time (gvisor/firecracker/podman settings; see docs/marketplace/ISOLATION-EVIDENCE.md)");
+
+  await ensureBinary({ origin, p, log });
+  // 1. Probe with placeholder credentials (the probe measures runners and exits; it never dials).
+  await writePrivateFile(p.probeConfig, JSON.stringify({ ...workerBase(origin, p, sandbox), worker_id: "wkr_probe0000", token: "mwk_probe_placeholder_only" }, null, 2) + "\n");
+  const measured = await probe({ bin: p.bin, config: p.probeConfig, env });
+  log(`==> Measured isolation class: ${measured.isolation_class}`);
+  for (const m of measured.measurements || []) log(`    ${m.runner}: ${m.supported ? m.class : "unsupported"}${m.reason ? ` (${m.reason})` : ""}`);
+  if (measured.isolation_class === "unsupported" || measured.status === 3) {
+    throw new Error(`no sandbox runner on this machine measured as supported; fix the sandbox configuration and try again (nothing was enrolled)${uid === 0 ? "" : `. ${ROOT_GUIDANCE}`}`);
+  }
+  // Root installs a system unit; otherwise the measured runner works rootless and a user unit is used.
+  const system = uid === 0;
+  log(system ? "==> Running as root: the worker will be a system service (agentcoor-worker.service)" : "==> The sandbox runner works without root: the worker will be a user service");
+
+  // 2. Enroll once; reuse the worker on later runs (list-tools uses the same worker).
+  let workerId = existing?.worker_id;
+  if (!WORKER_ID.test(String(workerId || "")) || !(await lstat(p.tokenFile).catch(() => null))) {
+    const r = await call(api, origin, apiKey, "/api/v1/workers", { method: "POST", body: {} });
+    if (!r.ok) throw new Error(`enroll worker: ${errorMessage(r)}`);
+    workerId = r.data?.worker_id;
+    const token = r.data?.token;
+    if (!WORKER_ID.test(String(workerId || "")) || !WORKER_TOKEN.test(String(token || ""))) throw new Error("the gateway returned no valid worker credential");
+    await ensurePrivateDir(dirname(p.tokenFile));
+    await atomicWrite(p.tokenFile, `${token}\n`, { mode: 0o600 });
+    log(`==> Enrolled worker ${workerId}; token saved to ${p.tokenFile} (mode 600)`);
+  } else log(`==> Reusing worker ${workerId}`);
+  if (uid === 0) await rootOwn(p.tokenFile);
+
+  // 3. worker.json (no secrets) and the verified service restart.
+  const cfg = mutate({ ...(existing || {}), ...workerBase(origin, p, sandbox), worker_id: workerId, token_file: p.tokenFile });
+  delete cfg.token;
+  await writePrivateFile(p.workerConfig, JSON.stringify(cfg, null, 2) + "\n");
+  log(`==> Worker configuration written to ${p.workerConfig}`);
+  await ensurePrivateDir(p.state); await ensurePrivateDir(p.logs);
+  await start({ bin: p.bin, config: p.workerConfig, logs: p.logs, state: p.state, log, env, service: WORKER_SERVICE, system });
+  return { workerId, isolationClass: measured.isolation_class, config: cfg, paths: p };
+}
+
+/** The root worker's token file must be root-owned and 0600 even if a non-root run created it. */
+async function rootOwnPrivate(path) {
+  const st = await lstat(path);
+  if (!st.isFile()) throw new Error(`${path} is not a regular file`);
+  if (st.uid !== 0 || st.gid !== 0) await chown(path, 0, 0);
+  if ((st.mode & 0o777) !== 0o600) await chmod(path, 0o600);
+}
+
+/** Create + publish a listing, retrying while the worker's hello reaches billing. */
+async function createAndPublish({ api, origin, apiKey, product, visibility, spec, price, log, sleep, tries = 20 }) {
+  let r = await call(api, origin, apiKey, "/v1/marketplace/providers", { method: "POST", body: {} });
+  if (!r.ok && r.status !== 409) throw new Error(`provider profile: ${errorMessage(r)}`);
+  for (let i = 0; ; i++) {
+    r = await call(api, origin, apiKey, "/v1/marketplace/listings", { method: "POST", body: { product, visibility, spec, price } });
+    if (r.ok) break;
+    const code = r.data?.error?.code;
+    if ((code === "worker_not_found" || r.status === 404) && i < tries - 1) { await sleep(3000); continue; }
+    throw new Error(`create listing: ${errorMessage(r)}${code ? ` (${code})` : ""}`);
+  }
+  const listingId = r.data?.listing_id || r.data?.id;
+  if (!LISTING_ID.test(String(listingId || ""))) throw new Error("billing returned no listing id");
+  log(`==> Created ${product} listing ${listingId} (${visibility})`);
+  r = await call(api, origin, apiKey, `/v1/marketplace/listings/${listingId}`, { method: "PATCH", body: { action: "publish" } });
+  if (!r.ok) throw new Error(`publish ${listingId}: ${errorMessage(r)} (withdraw it with: agentcoor withdraw ${listingId})`);
+  log(`==> Published ${listingId}: state ${r.data?.state || r.data?.listing?.state || "probing"}`);
+  return listingId;
+}
+
+async function recordListing(p, kind, listingId) {
+  const text = await readIfExists(p.listings);
+  const all = text ? JSON.parse(text) : {};
+  all[kind] = listingId;
+  await writePrivateFile(p.listings, JSON.stringify(all, null, 2) + "\n");
+}
+
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export async function listAgent({ origin, apiKey, flags, env = process.env, log = () => {}, api = apiJson, sleep = defaultSleep, ...opts }) {
+  agentSpec(flags, "wkr_check"); // validate flags before touching anything
+  const w = await ensureWorker({ origin, apiKey, flags, env, log, api, ...opts });
+  const { spec, price } = agentSpec(flags, w.workerId);
+  const visibility = flags.public ? "public" : "private";
+  const listingId = await createAndPublish({ api, origin, apiKey, product: "agent_job", visibility, spec, price, log, sleep });
+  await recordListing(w.paths, "agent_job", listingId);
+  log(`==> Done. Worker ${w.workerId} (${w.isolationClass}) serves ${listingId}. Renters submit with: agentcoor jobs submit --listing ${listingId} --task "..." --max-spend <microusd>`);
+  return { listingId, workerId: w.workerId, isolationClass: w.isolationClass };
+}
+
+export async function listTools({ origin, apiKey, flags, env = process.env, log = () => {}, api = apiJson, sleep = defaultSleep, ...opts }) {
+  if (!flags["tool-config"]) throw new Error("usage: agentcoor list-tools --tool-config tools.json [--sandbox-config sandbox.json]");
+  const raw = await readJsonFile(flags["tool-config"], "--tool-config");
+  toolsSpec(raw, "wkr_check");
+  let tools;
+  const w = await ensureWorker({ origin, apiKey, flags, env, log, api, ...opts, mutate: (c) => { tools = toolsSpec(raw, c.worker_id); return { ...c, tools: { ...(c.tools || {}), ...tools.workerTools } }; } });
+  const visibility = flags.public ? "public" : tools.visibility;
+  const listingId = await createAndPublish({ api, origin, apiKey, product: "live_tool", visibility, spec: tools.spec, price: tools.price, log, sleep });
+  await recordListing(w.paths, "live_tool", listingId);
+  log(`==> Done. Worker ${w.workerId} (${w.isolationClass}) serves ${listingId}. Renters open a session with: agentcoor sessions open --listing ${listingId} --max-spend <microusd>`);
+  return { listingId, workerId: w.workerId, isolationClass: w.isolationClass };
+}
+
+/* ---------------------------------------------------------------- renter */
+
+async function taskText(f, readFile) {
+  if (f["task-file"]) return String(await readFile(f["task-file"])).trim();
+  return f.task ? String(f.task) : "";
+}
+
+const pretty = (v) => JSON.stringify(v, null, 2) + "\n";
+
+export async function jobsCommand(sub, arg, { origin, apiKey, flags: f, out = () => {}, api = apiJson, readFile }) {
+  switch (sub) {
+    case "submit": {
+      const task = await taskText(f, readFile);
+      const spend = intFlag(f["max-spend"], "max-spend", 1, 1_000_000_000_000, undefined);
+      if (!LISTING_ID.test(String(f.listing || "")) || !task || spend === undefined) throw new Error("usage: agentcoor jobs submit --listing lst_... (--task <text> | --task-file <path>) --max-spend <microusd>");
+      const body = { listing: f.listing, task, attachments: [], max_spend_microusd: spend, idempotency_key: f["idempotency-key"] || `cli-${Date.now()}-${Math.random().toString(36).slice(2, 10)}` };
+      const r = await call(api, origin, apiKey, "/v1/marketplace/jobs", { method: "POST", body });
+      if (r.status === 402) throw new Error(`jobs submit: not enough paid credit (free credit cannot fund jobs). Add credit at ${origin}`);
+      if (!r.ok) throw new Error(`jobs submit: ${errorMessage(r)}`);
+      out(`Job ${r.data?.job_id}: ${r.data?.state || "reserved"}, reserved ${r.data?.reserved_microusd} microusd\nFollow it with: agentcoor jobs get ${r.data?.job_id}\n`);
+      return 0;
+    }
+    case "get": case "cancel": case "artifacts": {
+      if (!JOB_ID.test(String(arg || ""))) throw new Error(`usage: agentcoor jobs ${sub} job_...`);
+      const path = sub === "get" ? `/v1/marketplace/jobs/${arg}` : `/v1/marketplace/jobs/${arg}/${sub}`;
+      const r = await call(api, origin, apiKey, path, sub === "cancel" ? { method: "POST", body: {} } : {});
+      if (r.status === 404) throw new Error(`job ${arg} not found`);
+      if (!r.ok) throw new Error(`jobs ${sub}: ${errorMessage(r)}`);
+      out((sub === "cancel" ? "" : THIRD_PARTY_NOTE) + pretty(r.data));
+      return 0;
+    }
+    default:
+      throw new Error("usage: agentcoor jobs <submit|get|cancel|artifacts>");
+  }
+}
+
+export async function sessionsCommand(sub, arg, { origin, apiKey, flags: f, out = () => {}, api = apiJson, readFile }) {
+  switch (sub) {
+    case "open": {
+      const spend = intFlag(f["max-spend"], "max-spend", 1, 1_000_000_000_000, undefined);
+      if (!LISTING_ID.test(String(f.listing || "")) || spend === undefined) throw new Error("usage: agentcoor sessions open --listing lst_... --max-spend <microusd>");
+      const r = await call(api, origin, apiKey, "/v1/marketplace/sessions", { method: "POST", body: { listing: f.listing, max_spend_microusd: spend }, timeoutMs: 60_000 });
+      if (r.status === 402) throw new Error(`sessions open: not enough paid credit. Add credit at ${origin}`);
+      if (!r.ok) throw new Error(`sessions open: ${errorMessage(r)}`);
+      out(`Session ${r.data?.session_id} open. Tools:\n`);
+      for (const t of r.data?.tools || []) out(`  ${String(t.name)}\n`);
+      out(`Call one with: agentcoor sessions call ${r.data?.session_id} --tool <name> --args '{...}'\n`);
+      return 0;
+    }
+    case "call": {
+      if (!SESSION_ID.test(String(arg || "")) || !f.tool) throw new Error("usage: agentcoor sessions call rss_... --tool <name> [--args '<json>' | --args-file <path>]");
+      let args = {};
+      const rawArgs = f["args-file"] ? String(await readFile(f["args-file"])) : f.args;
+      if (rawArgs) { try { args = JSON.parse(rawArgs); } catch (e) { throw new Error(`--args is not valid JSON: ${e.message}`); } }
+      const r = await call(api, origin, apiKey, `/v1/marketplace/sessions/${arg}/calls`, { method: "POST", body: { tool: f.tool, arguments: args }, timeoutMs: 150_000 });
+      if (r.status === 402) throw new Error("sessions call: the session's reservation cannot cover this call (402); close it and open a new one with a higher --max-spend");
+      if (!r.ok) throw new Error(`sessions call: ${errorMessage(r)}`);
+      out(THIRD_PARTY_NOTE);
+      for (const c of r.data?.content || []) out(c.type === "text" ? `${c.text}\n` : `[${c.type} content]\n`);
+      if (r.data?.isError) out("(the tool reported an error)\n");
+      return r.data?.isError ? 1 : 0;
+    }
+    case "close": {
+      if (!SESSION_ID.test(String(arg || ""))) throw new Error("usage: agentcoor sessions close rss_...");
+      const r = await call(api, origin, apiKey, `/v1/marketplace/sessions/${arg}`, { method: "DELETE" });
+      if (!r.ok) throw new Error(`sessions close: ${errorMessage(r)}`);
+      out(pretty(r.data));
+      return 0;
+    }
+    default:
+      throw new Error("usage: agentcoor sessions <open|call|close>");
+  }
+}

package/src/release-floor.json

@@ -0,0 +1,3 @@
+{
+  "min_epoch": 1794676256
+}

package/src/release.js

@@ -0,0 +1,184 @@
+// Signed release manifest (release.json + release.json.sig) and rollback protection.
+//
+// release.json is produced and signed by scripts/sign-release.sh:
+//   { "schema": 1, "version": "0.1.0", "epoch": 1794600000,
+//     "issued_at": "2026-11-13T00:00:00Z", "expires_at": "2027-05-12T00:00:00Z",
+//     "artifacts": [ { "platform": "linux-amd64", "name": "agentcoor-agent-linux-amd64", "sha256": "<hex>", "size": 123 }, ... ],
+//     "installer": { "name": "install.sh", "sha256": "<hex>", "size": 456 } }
+//
+// A binary is installed only when: the signature verifies against the embedded
+// release key, the manifest has not expired, its epoch is >= MIN_RELEASE_EPOCH
+// AND >= the highest epoch this machine has accepted before (kept in a private
+// 0600 state file shared with install.sh), and the binary matches the listed
+// size and SHA-256. SHA256SUMS may still be published for humans but is never trusted.
+import { open, lstat, unlink } from "node:fs/promises";
+import { constants, readFileSync } from "node:fs";
+import { timingSafeEqual } from "node:crypto";
+import { join } from "node:path";
+import { verifyReleaseSignature, RELEASE_PUBLIC_KEY } from "./signature.js";
+import { sha256Hex } from "./sha.js";
+import { atomicWrite, ensurePrivateDir } from "./fsx.js";
+
+/**
+ * Lowest epoch this CLI accepts. `make release` stamps the epoch it signs into
+ * src/release-floor.json (and install.sh), so every published CLI version refuses
+ * any release older than the one current when it was published, even on a fresh
+ * machine with no install state.
+ */
+export function loadReleaseFloor(text = readFileSync(new URL("./release-floor.json", import.meta.url), "utf8")) {
+  const f = JSON.parse(text);
+  if (!f || !Number.isSafeInteger(f.min_epoch) || f.min_epoch < 1) throw new Error("release-floor.json is invalid");
+  return f.min_epoch;
+}
+export const MIN_RELEASE_EPOCH = loadReleaseFloor();
+export const PLATFORMS = ["darwin-arm64", "darwin-amd64", "linux-amd64", "linux-arm64"];
+export const artifactName = (platform) => `agentcoor-agent-${platform}`;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+const CLOCK_SKEW_MS = 24 * 3600 * 1000;
+
+function parseTime(v, field) {
+  if (typeof v !== "string" || !ISO.test(v)) throw new Error(`release.json: ${field} is not an RFC 3339 UTC timestamp`);
+  const t = Date.parse(v);
+  if (!Number.isFinite(t)) throw new Error(`release.json: ${field} is invalid`);
+  return t;
+}
+
+/**
+ * Verify the signature over the exact manifest bytes, then its structure, expiry and epoch.
+ * Returns the parsed manifest. Throws (fails closed) on anything unexpected.
+ */
+export function verifyManifest(manifestBuf, sigBuf, { publicKey = RELEASE_PUBLIC_KEY, minEpoch = MIN_RELEASE_EPOCH, acceptedEpoch = 0, now = Date.now() } = {}) {
+  verifyReleaseSignature(manifestBuf, sigBuf, publicKey, "release.json");
+  let m;
+  try { m = JSON.parse(Buffer.from(manifestBuf).toString("utf8")); } catch { throw new Error("release.json is not valid JSON: refusing to install"); }
+  if (!m || typeof m !== "object" || Array.isArray(m) || m.schema !== 1) throw new Error("release.json has an unsupported schema: refusing to install");
+  if (typeof m.version !== "string" || !/^[0-9A-Za-z.+-]{1,64}$/.test(m.version)) throw new Error("release.json: invalid version");
+  if (!Number.isSafeInteger(m.epoch) || m.epoch < 1) throw new Error("release.json: invalid epoch");
+  const issued = parseTime(m.issued_at, "issued_at"), expires = parseTime(m.expires_at, "expires_at");
+  if (expires <= issued) throw new Error("release.json: expires_at is before issued_at");
+  if (issued > now + CLOCK_SKEW_MS) throw new Error("release.json is issued in the future (check this machine's clock): refusing to install");
+  if (now >= expires) throw new Error(`release.json expired at ${m.expires_at}: refusing to install a stale release (it may be a rollback)`);
+  if (m.epoch < minEpoch) throw new Error(`release epoch ${m.epoch} is older than the minimum ${minEpoch} this CLI accepts: refusing to install`);
+  if (m.epoch < acceptedEpoch) throw new Error(`release epoch ${m.epoch} is older than epoch ${acceptedEpoch} already installed on this machine: refusing a rollback`);
+  if (!Array.isArray(m.artifacts) || m.artifacts.length !== PLATFORMS.length) throw new Error("release.json: unexpected artifact list");
+  const seen = new Set();
+  for (const a of m.artifacts) {
+    if (!a || !PLATFORMS.includes(a.platform) || a.name !== artifactName(a.platform) || seen.has(a.platform)) throw new Error("release.json: unexpected artifact entry");
+    if (typeof a.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(a.sha256)) throw new Error(`release.json: invalid sha256 for ${a.name}`);
+    if (!Number.isSafeInteger(a.size) || a.size < 1) throw new Error(`release.json: invalid size for ${a.name}`);
+    seen.add(a.platform);
+  }
+  if (m.installer !== undefined) {
+    const i = m.installer;
+    if (!i || typeof i !== "object" || i.name !== "install.sh" || typeof i.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(i.sha256) || !Number.isSafeInteger(i.size) || i.size < 1)
+      throw new Error("release.json: invalid installer entry");
+  }
+  return m;
+}
+
+/** The manifest entry for `name`, or a fail-closed error. */
+export function artifactFor(manifest, name) {
+  const a = manifest.artifacts.find((x) => x.name === name);
+  if (!a) throw new Error(`release.json lists no artifact named ${name}`);
+  return a;
+}
+
+/** The signed install.sh entry ({name, sha256, size}), or a fail-closed error. */
+export function installerFor(manifest) {
+  if (!manifest.installer) throw new Error("release.json does not list install.sh: refusing to trust it");
+  return manifest.installer;
+}
+
+/** Check a downloaded binary against its manifest entry. Returns the hex digest. */
+export function verifyArtifact(buf, entry) {
+  if (buf.length !== entry.size) throw new Error(`size mismatch for ${entry.name}: refusing to install`);
+  const got = sha256Hex(buf);
+  if (!timingSafeEqual(Buffer.from(got), Buffer.from(entry.sha256))) throw new Error(`checksum mismatch for ${entry.name}: refusing to install`);
+  return got;
+}
+
+export const releaseStatePath = (base) => join(base, "release-state.json");
+
+/**
+ * Highest epoch previously accepted on this machine. Missing file = 0. A state file
+ * that is a symlink, not ours, not mode 600, oversized or malformed is an error
+ * (refusing is safer than silently resetting rollback protection).
+ */
+export async function readAcceptedEpoch(base) {
+  const p = releaseStatePath(base);
+  let fh;
+  try { fh = await open(p, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0)); }
+  catch (e) { if (e.code === "ENOENT") return 0; throw new Error(`cannot read ${p}: ${e.code || e.message}`); }
+  try {
+    const st = await fh.stat();
+    if (!st.isFile() || st.size > 4096) throw new Error(`${p} is not a small regular file`);
+    if (typeof process.getuid === "function" && st.uid !== process.getuid()) throw new Error(`${p} is not owned by you`);
+    if (st.mode & 0o077) throw new Error(`${p} must be mode 600`);
+    const buf = Buffer.alloc(4097);
+    const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
+    const s = JSON.parse(buf.subarray(0, bytesRead).toString("utf8"));
+    if (!s || !Number.isSafeInteger(s.epoch) || s.epoch < 0) throw new Error("bad epoch");
+    return s.epoch;
+  } catch (e) {
+    throw new Error(`${p} is unreadable (${e.message}); remove it only if you trust the current release`);
+  } finally { await fh.close(); }
+}
+
+/** Persist max(previous, epoch) in the private state file (0600, atomic). Call it under withInstallLock: the previous value is re-read there and never lowered. */
+export async function recordAcceptedEpoch(base, epoch) {
+  await ensurePrivateDir(base);
+  const prev = await readAcceptedEpoch(base);
+  if (epoch <= prev) return prev;
+  await atomicWrite(releaseStatePath(base), JSON.stringify({ epoch }) + "\n", { mode: 0o600 });
+  return epoch;
+}
+
+export const installLockPath = (base) => join(base, "install.lock");
+
+/**
+ * Run `fn` holding the per-install-dir lock: `<base>/install.lock`, created with
+ * O_CREAT|O_EXCL|O_NOFOLLOW and holding the owner's PID. install.sh uses the same
+ * file and protocol. A lock whose PID is no longer running is stale and removed
+ * (only if it is still the same file we inspected); a live holder is waited for up
+ * to `timeoutMs`, then the install fails rather than racing it.
+ */
+export async function withInstallLock(base, fn, { timeoutMs = 120_000, pollMs = 200, pid = process.pid } = {}) {
+  await ensurePrivateDir(base);
+  const p = installLockPath(base);
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    let fh;
+    try { fh = await open(p, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600); }
+    catch (e) {
+      if (e.code !== "EEXIST") throw new Error(`cannot create ${p}: ${e.code || e.message}`);
+      if (await removeStaleLock(p)) continue;
+      if (Date.now() >= deadline) throw new Error(`another AgentCoor install is running (${p}); wait for it to finish, or remove the file if no install is running`);
+      await new Promise((r) => setTimeout(r, pollMs));
+      continue;
+    }
+    try { await fh.writeFile(`${pid}\n`); await fh.sync(); } finally { await fh.close(); }
+    try { return await fn(); }
+    finally { await unlink(p).catch(() => {}); }
+  }
+}
+
+const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } };
+
+/** Remove `p` if it names a dead (or unparseable, and older than 10 s) holder. Returns true if removed. */
+async function removeStaleLock(p) {
+  let fh;
+  try { fh = await open(p, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0)); }
+  catch (e) { if (e.code === "ENOENT") return true; throw new Error(`${p} is not a regular lock file (${e.code}); remove it`); }
+  let st, text;
+  try {
+    st = await fh.stat();
+    if (!st.isFile() || st.size > 32) throw new Error(`${p} is not a regular lock file; remove it`);
+    text = (await fh.readFile("utf8")).trim();
+  } finally { await fh.close(); }
+  const pid = /^[1-9][0-9]{0,9}$/.test(text) ? Number(text) : 0;
+  if (pid ? pidAlive(pid) : Date.now() - st.mtimeMs < 10_000) return false;
+  const now = await lstat(p).catch(() => null);
+  if (!now || now.ino !== st.ino || now.dev !== st.dev) return !now;
+  await unlink(p).catch(() => {});
+  return true;
+}

package/src/sha.js

@@ -0,0 +1,24 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
+export function sha256Hex(buf) { return createHash("sha256").update(buf).digest("hex"); }
+
+/** Find the checksum for `name` in a SHA256SUMS file (accepts "hash  name" and "hash *name"). */
+export function expectedSum(sumsText, name) {
+  let found = null;
+  for (const line of String(sumsText).split(/\r?\n/)) {
+    const m = line.trim().match(/^([0-9a-fA-F]{64})\s+\*?(\S+)$/);
+    if (!m || m[2] !== name) continue;
+    if (found && found !== m[1].toLowerCase()) throw new Error(`conflicting checksums published for ${name}`);
+    found = m[1].toLowerCase();
+  }
+  return found;
+}
+
+/** Fail closed: throws unless a checksum is published for `name` and matches `buf`. */
+export function verifySha256(buf, sumsText, name) {
+  const want = expectedSum(sumsText, name);
+  if (!want) throw new Error(`no checksum published for ${name}`);
+  const got = sha256Hex(buf);
+  if (!timingSafeEqual(Buffer.from(got), Buffer.from(want))) throw new Error(`checksum mismatch for ${name}`);
+  return got;
+}