Agent 1.0.0: polls the Hub for signed jobs, runs crosscode, sends reports and stats

apps/agent (docs/AGENT-1.0-PLAN.md §3-4, §10): listens on nothing; checks
every job (pinned Hub key, server, time window, replays for 90 days,
type per mode, strict arguments) before running crosscode with an
argument array; opens the sealed config into a root-only file only for
the job; redacts log lines; keeps unsent reports in an outbox; encrypts
exports before upload; check-ports on the central server (read-only);
self-update with automatic revert. One bundled dist/cli.js, a systemd
unit and the install script that joins a server with a one-time token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 12:58:08 +02:00
co-authored by Claude Opus 5.5
parent e9e9b5a97f
commit 1eeaf4d94f
28 changed files with 1771 additions and 2 deletions
+36
View File
@@ -0,0 +1,36 @@
import { agent } from "@crosscode/contracts";
import { crosscodeArgs } from "../src/command";
import { job } from "./helpers";
const parsed = (over: Record<string, unknown>) => agent.agentJobSchema.parse(job(over));
describe("crosscode arguments for each job", () => {
it("install: behind frp with the Hub's ports and the release", () => {
expect(crosscodeArgs(parsed({
type: "install",
args: { church: "hope", products: ["events"], versions: { events: "events@2.4.1" }, domains: { events: "events.hope.co.za" }, ports: { events: { web: 20010, api: 20011 } } },
}))).toEqual(["install", "hope", "--products", "events", "--domain", "hope.co.za", "--events-domain", "events.hope.co.za", "--api-port", "20011", "--web-port", "20010", "--frp", "--version", "events@2.4.1"]);
});
it("deploy, adopt, restart, uninstall, purge, status", () => {
expect(crosscodeArgs(parsed({}))).toEqual(["deploy", "hope", "events", "--version", "events@2.4.1"]);
expect(crosscodeArgs(parsed({ args: { church: "hope", products: ["events"], check: true } }))).toEqual(["deploy", "hope", "events", "--check"]);
expect(crosscodeArgs(parsed({ type: "adopt", args: { church: "hope", eventsDir: "/var/www/hope-events", version: "events@2.2.0" } })))
.toEqual(["adopt", "hope", "--events-dir", "/var/www/hope-events", "--version", "events@2.2.0"]);
expect(crosscodeArgs(parsed({ type: "adopt-undo", args: { church: "hope" } }))).toEqual(["adopt", "hope", "--undo"]);
expect(crosscodeArgs(parsed({ type: "restart", args: { church: "hope" } }))).toEqual(["restart", "hope"]);
expect(crosscodeArgs(parsed({ type: "uninstall", args: { church: "hope" } }))).toEqual(["uninstall", "hope", "--confirm", "hope"]);
expect(crosscodeArgs(parsed({ type: "purge", args: { church: "hope" } }))).toEqual(["purge", "hope", "--confirm", "hope"]);
expect(crosscodeArgs(parsed({ type: "status", args: {} }))).toEqual(["status", "--no-fetch"]);
});
it("export writes to the file the agent gives", () => {
const j = parsed({ type: "export", args: { church: "hope", exportId: "exp_abcdefgh" } });
expect(crosscodeArgs(j, { exportFile: "/var/lib/crosscode-agent/exports/exp_abcdefgh.zip" })).toEqual(["export", "hope", "--out", "/var/lib/crosscode-agent/exports/exp_abcdefgh.zip"]);
});
it("the agent's own jobs run no crosscode command", () => {
expect(crosscodeArgs(parsed({ type: "check-ports", args: { ports: [20010] } }))).toBeNull();
expect(crosscodeArgs(parsed({ type: "update-agent", args: { version: "agent@1.0.1" } }))).toBeNull();
});
});
+44
View File
@@ -0,0 +1,44 @@
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { generateEd25519, generateX25519, signJob } from "@crosscode/contracts/signing";
import type { AgentConfig } from "../src/config";
export const hubKeys = generateEd25519();
export const serverKeys = { ed25519: generateEd25519(), x25519: generateX25519() };
export const config: AgentConfig = {
hubUrl: "https://hub.test",
serverId: "srv_test00001",
mode: "church",
hubJobKey: hubKeys.publicKey,
pollSeconds: 30,
statsSeconds: 60,
joinedAt: "2026-11-20T00:00:00.000Z",
};
export const NOW = new Date("2026-11-20T12:05:00.000Z");
let n = 0;
export function job(over: Record<string, unknown> = {}, key = hubKeys.privateKeyPem) {
n++;
return signJob({
schema: "crosscode.agent-job/1",
id: `job_test${String(n).padStart(6, "0")}`,
serverId: config.serverId,
type: "deploy",
args: { church: "hope", products: ["events"], versions: ["events@2.4.1"] },
config: null,
notBefore: "2026-11-20T12:00:00.000Z",
expiresAt: "2026-11-20T12:15:00.000Z",
...over,
}, key);
}
/** A temporary state folder per test file. */
export function tempState(): string {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-test-"));
process.env.CROSSCODE_AGENT_STATE_DIR = dir;
process.env.CROSSCODE_AGENT_RUN_DIR = path.join(dir, "run");
return dir;
}
+112
View File
@@ -0,0 +1,112 @@
import fs from "node:fs";
import path from "node:path";
import { agent } from "@crosscode/contracts";
import { decryptExport } from "@crosscode/contracts/signing";
import { HubRequestError, type HubClient } from "../src/hub";
import { Agent } from "../src/loop";
import type { RunResult } from "../src/runner";
import { SeenJobs } from "../src/verify";
import { config, job, NOW, serverKeys, tempState } from "./helpers";
const state = tempState();
function fakeHub(jobs: unknown[]) {
const posts: { path: string; body: unknown }[] = [];
const puts: { path: string; body: Uint8Array }[] = [];
let down = false;
const hub: HubClient = {
async post(p, body) {
if (down) throw new HubRequestError("down", 0, "HUB_UNREACHABLE");
posts.push({ path: p, body });
if (p === "/api/agent/v1/poll") return { jobs: jobs.splice(0), pollSeconds: 30 };
return null;
},
async put(p, body) {
puts.push({ path: p, body });
return null;
},
};
return { hub, posts, puts, setDown: (v: boolean) => { down = v; } };
}
const ok = (over: Partial<RunResult> = {}): RunResult => ({ status: "succeeded", steps: [{ name: "x", startedAt: NOW.toISOString(), finishedAt: NOW.toISOString(), outcome: "ok" }], result: {}, log: ["==> done"], startedAt: NOW.toISOString(), finishedAt: NOW.toISOString(), ...over });
type Run = (args: string[], job: agent.AgentJob) => Promise<RunResult>;
function make(jobs: unknown[], run: jest.Mock<ReturnType<Run>, Parameters<Run>> = jest.fn<ReturnType<Run>, Parameters<Run>>(async () => ok())) {
const h = fakeHub(jobs);
const a = new Agent({ config, keys: { ed25519Pem: serverKeys.ed25519.privateKeyPem, x25519Pem: serverKeys.x25519.privateKeyPem }, hub: h.hub, seen: new SeenJobs(path.join(state, `seen-${Math.random()}.json`)), run, now: () => NOW });
return { a, run, ...h };
}
const reports = (posts: { path: string; body: unknown }[]) => posts.filter((p) => p.path === "/api/agent/v1/report").map((p) => p.body as agent.AgentReport);
describe("the agent loop", () => {
it("runs a valid job once and reports it", async () => {
const j = job();
const { a, run, posts } = make([j, j]);
await a.pollOnce();
expect(run).toHaveBeenCalledTimes(1);
expect(run.mock.calls[0]).toEqual([["deploy", "hope", "events", "--version", "events@2.4.1"], expect.objectContaining({ id: j.id })]);
// The second copy is a replay: refused quietly (the first one's report already went).
const rs = reports(posts);
expect(rs.map((r) => [r.jobId, r.status])).toEqual([[j.id, "succeeded"]]);
expect(agent.agentReportSchema.safeParse(rs[0]).success).toBe(true);
});
it("reports refused and expired jobs without running them", async () => {
const forged = { ...job(), signature: "A".repeat(86) };
const late = job({ expiresAt: "2026-11-20T12:01:00.000Z", notBefore: "2026-11-20T11:00:00.000Z" });
const { a, run, posts } = make([forged, late]);
await a.pollOnce();
expect(run).not.toHaveBeenCalled();
expect(reports(posts).map((r) => r.status)).toEqual(["refused", "expired"]);
});
it("keeps a report it can't send and sends it on the next poll", async () => {
const j = job();
let setDownLater: (v: boolean) => void = () => {};
const { a, posts, setDown } = make([j], jest.fn<ReturnType<Run>, Parameters<Run>>(async () => { setDownLater(true); return ok(); }));
setDownLater = setDown;
await a.pollOnce();
expect(reports(posts)).toEqual([]);
expect(fs.readdirSync(path.join(state, "outbox"))).toContain(`${j.id}.json`);
setDown(false);
await a.pollOnce();
expect(reports(posts).map((r) => r.jobId)).toEqual([j.id]);
expect(fs.readdirSync(path.join(state, "outbox"))).toEqual([]);
});
it("backs off while the Hub is unreachable", async () => {
const { a, setDown } = make([]);
setDown(true);
expect(await a.pollOnce()).toBe(60);
expect(await a.pollOnce()).toBe(120);
setDown(false);
expect(await a.pollOnce()).toBe(30);
});
it("export: encrypts the ZIP, uploads it, and only the report carries the key", async () => {
const j = job({ type: "export", args: { church: "hope", exportId: "exp_abcdefgh" } });
const run = jest.fn<ReturnType<Run>, Parameters<Run>>(async (args: string[]) => {
fs.writeFileSync(args[3]!, "PK zip bytes");
return ok({ result: { file: args[3], bytes: 12 } });
});
const { a, puts, posts } = make([j], run);
await a.pollOnce();
expect(puts).toHaveLength(1);
expect(puts[0]!.path).toBe("/api/agent/v1/exports/exp_abcdefgh");
const r = reports(posts)[0]!;
expect(r.status).toBe("succeeded");
const key = r.result.key as string;
expect(decryptExport(puts[0]!.body, key).toString()).toBe("PK zip bytes");
expect(Buffer.from(puts[0]!.body).includes(Buffer.from("PK zip"))).toBe(false);
expect(fs.readdirSync(path.join(state, "exports"))).toEqual([]);
});
it("a job that throws is reported as failed", async () => {
const { a, posts } = make([job()], jest.fn<ReturnType<Run>, Parameters<Run>>(async () => { throw new Error("boom"); }));
await a.pollOnce();
expect(reports(posts)[0]).toMatchObject({ status: "failed", message: "boom" });
});
});
@@ -0,0 +1,72 @@
import { spawn } from "node:child_process";
import fs from "node:fs";
import http from "node:http";
import os from "node:os";
import path from "node:path";
import { config, serverKeys } from "./helpers";
/**
* AGENT-1.0-PLAN §2 rule 1: the agent listens on nothing. Starts the built agent (dist/cli.js)
* against a fake Hub served by this test, lets it poll, then compares the agent's open sockets
* with every listening TCP socket the kernel knows (/proc/net/tcp, tcp6). Linux only (the
* servers); run `npm run build -w apps/agent` first.
*/
const cli = path.join(__dirname, "..", "dist", "cli.js");
const linux = process.platform === "linux" && fs.existsSync(cli);
const maybe = linux ? it : it.skip;
function listeningInodes(): Set<string> {
const out = new Set<string>();
for (const f of ["/proc/net/tcp", "/proc/net/tcp6"]) {
let text: string;
try { text = fs.readFileSync(f, "utf8"); } catch { continue; }
for (const line of text.split("\n").slice(1)) {
const cols = line.trim().split(/\s+/);
if (cols[3] === "0A") out.add(cols[9]!); // 0A = LISTEN
}
}
return out;
}
function socketInodes(pid: number): Set<string> {
const out = new Set<string>();
for (const fd of fs.readdirSync(`/proc/${pid}/fd`)) {
try {
const m = /^socket:\[(\d+)\]$/.exec(fs.readlinkSync(`/proc/${pid}/fd/${fd}`));
if (m) out.add(m[1]!);
} catch { /* closed meanwhile */ }
}
return out;
}
describe("the running agent", () => {
maybe("has no listening socket", async () => {
let polls = 0;
const hub = http.createServer((req, res) => {
if (req.url === "/api/agent/v1/poll") polls++;
res.setHeader("content-type", "application/json");
res.end(req.url === "/api/agent/v1/poll" ? JSON.stringify({ jobs: [], pollSeconds: 5 }) : "{}");
});
await new Promise<void>((r) => hub.listen(0, "127.0.0.1", r));
const port = (hub.address() as { port: number }).port;
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-nolisten-"));
fs.writeFileSync(path.join(dir, "agent.json"), JSON.stringify({ ...config, hubUrl: `http://127.0.0.1:${port}`, pollSeconds: 5, statsSeconds: 15 }));
fs.writeFileSync(path.join(dir, "agent-ed25519.pem"), serverKeys.ed25519.privateKeyPem);
fs.writeFileSync(path.join(dir, "agent-x25519.pem"), serverKeys.x25519.privateKeyPem);
const child = spawn(process.execPath, [cli, "run"], {
env: { ...process.env, CROSSCODE_AGENT_CONFIG_DIR: dir, CROSSCODE_AGENT_STATE_DIR: path.join(dir, "state"), CROSSCODE_AGENT_ALLOW_NON_ROOT: "1", CROSSCODE_SITES: path.join(dir, "sites") },
stdio: "ignore",
});
try {
for (let i = 0; i < 40 && polls === 0; i++) await new Promise((r) => setTimeout(r, 250));
expect(polls).toBeGreaterThan(0);
const listening = listeningInodes();
const mine = [...socketInodes(child.pid!)].filter((inode) => listening.has(inode));
expect(mine).toEqual([]);
} finally {
child.kill("SIGTERM");
hub.close();
}
}, 30_000);
});
+79
View File
@@ -0,0 +1,79 @@
import { checkPorts, parseFrpsIni, parseSs, portAllowed } from "../src/central";
import { LogTail, redact } from "../src/redact";
import { churchProcesses, cpuPercent, parseMeminfo } from "../src/stats";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
describe("log lines are redacted before they leave the server", () => {
it.each([
["Error: connect postgresql://hope_events:Zx81kLmQ@localhost:5432/hope_events", "postgresql://hope_events:***@localhost"],
["JWT_SECRET=abcdefghijklmnop", "JWT_SECRET=***"],
['DB_PASSWORD: "hunter2 x"', "DB_PASSWORD: ***"],
["Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.payload.sig", "Authorization: Bearer ***"],
["licence CEH-7K2M-9QXA-P4RT-WD8C refused", "CEH-****"],
["token a3f9c1d27b8e4f60a3f9c1d27b8e4f60a3f9c1d2", "token ***"],
])("%s", (line, expected) => {
const out = redact(line);
expect(out).toContain(expected);
});
it("keeps ordinary lines", () => {
expect(redact("==> events: migrations")).toBe("==> events: migrations");
});
it("keeps only the last lines", () => {
const t = new LogTail(3);
t.push("1\n2\n3\n4");
t.push("\n5\n");
expect(t.end()).toEqual(["3", "4", "5"]);
});
});
describe("central server checks", () => {
const ini = "[common]\nbind_port = 7000\nproxy_bind_addr = 127.0.0.1\nallow_ports = 20000-29999,3000\n\n[web]\nproxy_bind_addr = 0.0.0.0\n";
it("reads [common] only", () => {
expect(parseFrpsIni(ini)).toEqual({ proxyBindAddr: "127.0.0.1", allowPorts: "20000-29999,3000" });
});
it("allow_ports ranges", () => {
expect(portAllowed(20010, "20000-29999,3000")).toBe(true);
expect(portAllowed(3000, "20000-29999,3000")).toBe(true);
expect(portAllowed(5000, "20000-29999,3000")).toBe(false);
expect(portAllowed(5000, null)).toBe(true);
});
it("ports must be allowed, open and bound to 127.0.0.1 only", () => {
const ss = "LISTEN 0 4096 127.0.0.1:20010 0.0.0.0:*\nLISTEN 0 4096 0.0.0.0:20011 0.0.0.0:*\nLISTEN 0 4096 [::1]:20012 [::]:*\n";
const res = checkPorts([20010, 20011, 20012, 20013], parseFrpsIni(ini), parseSs(ss));
expect(res.ports.map((p) => [p.port, p.ok])).toEqual([[20010, true], [20011, false], [20012, true], [20013, false]]);
expect(res.warnings.join(" ")).toMatch(/20011 is open on more than 127.0.0.1/);
expect(res.warnings.join(" ")).toMatch(/20013 isn't open/);
});
it("warns when proxy_bind_addr is missing", () => {
const res = checkPorts([20010], parseFrpsIni("[common]\nbind_port = 7000\n"), parseSs("LISTEN 0 1 127.0.0.1:20010 0.0.0.0:*"));
expect(res.warnings.join(" ")).toMatch(/proxy_bind_addr is not set/);
});
});
describe("stats", () => {
it("RAM from /proc/meminfo", () => {
const r = parseMeminfo("MemTotal: 4000000 kB\nMemFree: 100 kB\nMemAvailable: 1000000 kB\nSwapTotal: 2000 kB\nSwapFree: 500 kB\n");
expect(r).toEqual({ totalBytes: 4096000000, usedBytes: 3072000000, availableBytes: 1024000000, swapTotalBytes: 2048000, swapUsedBytes: 1536000 });
});
it("CPU % between two readings", () => {
expect(cpuPercent("cpu 100 0 100 700 100 0 0 0", "cpu 150 0 150 750 150 0 0 0")).toBe(50);
});
it("PM2 processes are matched to churches through church.env", () => {
const sites = fs.mkdtempSync(path.join(os.tmpdir(), "sites-"));
fs.mkdirSync(path.join(sites, "hope"));
fs.writeFileSync(path.join(sites, "hope", "church.env"), 'CHURCH=hope\nEVENTS_USER=cc-hope\nEVENTS_PM2="hope-events-backend hope-events-frontend"\n');
fs.mkdirSync(path.join(sites, "Bad Name"));
const map = churchProcesses(sites);
expect([...map.entries()]).toEqual([["cc-hope", [{ church: "hope", product: "events", names: ["hope-events-backend", "hope-events-frontend"] }]]]);
});
});
+61
View File
@@ -0,0 +1,61 @@
import path from "node:path";
import { generateEd25519 } from "@crosscode/contracts/signing";
import { checkJob, SeenJobs } from "../src/verify";
import { config, job, NOW, tempState } from "./helpers";
const dir = tempState();
const fresh = () => new SeenJobs(path.join(dir, `seen-${Math.random()}.json`));
describe("checking a job (AGENT-1.0-PLAN §4)", () => {
it("accepts a signed job for this server, in its window", () => {
expect(checkJob(job(), config, fresh(), NOW)).toMatchObject({ ok: true });
});
it("refuses a job signed with another key", () => {
expect(checkJob(job({}, generateEd25519().privateKeyPem), config, fresh(), NOW)).toMatchObject({ ok: false, status: "refused", message: expect.stringContaining("signature") });
});
it("refuses a job whose content was changed after signing", () => {
const j = job();
expect(checkJob({ ...j, args: { ...j.args, church: "other" } }, config, fresh(), NOW)).toMatchObject({ ok: false, status: "refused" });
});
it("refuses a job for another server", () => {
expect(checkJob(job({ serverId: "srv_other0001" }), config, fresh(), NOW)).toMatchObject({ ok: false, message: expect.stringContaining("not this server") });
});
it("reports an expired job as expired, and never runs it", () => {
expect(checkJob(job(), config, fresh(), new Date("2026-11-20T12:16:00.000Z"))).toMatchObject({ ok: false, status: "expired" });
});
it("refuses a job that isn't due yet (beyond a minute of clock difference)", () => {
expect(checkJob(job(), config, fresh(), new Date("2026-11-20T11:58:00.000Z"))).toMatchObject({ ok: false, status: "refused" });
expect(checkJob(job(), config, fresh(), new Date("2026-11-20T11:59:30.000Z"))).toMatchObject({ ok: true });
});
it("refuses a replayed job, also after a restart", () => {
const file = path.join(dir, "seen-replay.json");
const seen = new SeenJobs(file);
const j = job();
expect(checkJob(j, config, seen, NOW)).toMatchObject({ ok: true });
seen.add(j.id);
expect(checkJob(j, config, seen, NOW)).toMatchObject({ ok: false, message: expect.stringContaining("replay") });
expect(checkJob(j, config, new SeenJobs(file), NOW)).toMatchObject({ ok: false, message: expect.stringContaining("replay") });
});
it("refuses an unknown type, and arguments with shell characters", () => {
expect(checkJob(job({ type: "shell", args: { command: "id" } }), config, fresh(), NOW)).toMatchObject({ ok: false, message: expect.stringContaining("Unknown job type") });
expect(checkJob(job({ args: { church: "hope;reboot", products: ["events"] } }), config, fresh(), NOW)).toMatchObject({ ok: false, message: expect.stringContaining("isn't valid") });
expect(checkJob(job({ type: "adopt", args: { church: "hope", eventsDir: "/var/www/$(id)" } }), config, fresh(), NOW)).toMatchObject({ ok: false });
});
it("a central agent only runs check-ports, status and update-agent", () => {
const central = { ...config, mode: "central" as const };
expect(checkJob(job(), central, fresh(), NOW)).toMatchObject({ ok: false, message: expect.stringContaining("central") });
expect(checkJob(job({ type: "check-ports", args: { ports: [20010, 20011] } }), central, fresh(), NOW)).toMatchObject({ ok: true });
});
it("refuses things that aren't jobs", () => {
for (const raw of [null, "job", [], { id: "nope" }]) expect(checkJob(raw, config, fresh(), NOW)).toMatchObject({ ok: false, status: "refused" });
});
});