deepdebug-local-agent 1.9.0 → 1.10.0

package/test/la-protocol-v2/contract.test.js

@@ -82,10 +82,10 @@ for (const file of vectorFiles) {
     }
 }
 
-test("vectors: counts (294 frames = 67 valid + 227 invalid in this copy (contract 2.1), plus the bodies of file.list)", () => {
-    assert.equal(valid + invalid, 294);
-    assert.equal(valid, 67);
-    assert.equal(invalid, 227);
+test("vectors: counts (317 frames = 72 valid + 245 invalid in this copy (contract 2.1, with job.assign options), plus the bodies of file.list)", () => {
+    assert.equal(valid + invalid, 317);
+    assert.equal(valid, 72);
+    assert.equal(invalid, 245);
     assert.equal(bodyVectors, 54, "file.list.body.vectors.json (F3-07c): 54 bodies");
 });
 

package/test/la-protocol-v2/helpers/fake-llm.js

@@ -0,0 +1,64 @@
+// A fake OpenAI-compatible server (chat/completions, JSON and SSE) on 127.0.0.1, plus the fetch that points the https endpoint of the key at it.
+// It records what it was sent (method, url, headers, parsed body) so the tests can prove what left the agent and what did not.
+import http from "node:http";
+import crypto from "node:crypto";
+
+export const sha = (s) => crypto.createHash("sha256").update(Buffer.from(s, "utf8")).digest("hex");
+export const mkKey = (tag = "A") => `sk-CANARY-LLMKEY-${tag}-${crypto.randomBytes(12).toString("hex")}`;
+export const FUTURE = (ms = 3_600_000) => new Date(Date.now() + ms).toISOString();
+export const keySet = (key, over = {}) => ({ op: "set", keyId: sha(key), endpoint: "https://ai.visionhammer.io/litellm", key, models: ["vh-claude-sonnet", "vh-embed"], expiresAt: FUTURE(), ...over });
+
+export const okJson = (content = "ok", { promptTokens = 12, completionTokens = 5, cost, model = "vh-claude-sonnet" } = {}) => (req, res) => {
+    const body = JSON.stringify({ id: "cmpl-1", object: "chat.completion", model, choices: [{ index: 0, message: { role: "assistant", content }, finish_reason: "stop" }], usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: promptTokens + completionTokens } });
+    res.writeHead(200, { "content-type": "application/json", ...(cost !== undefined ? { "x-litellm-response-cost": String(cost) } : {}) });
+    res.end(body);
+};
+
+export const okSse = (deltas, { promptTokens = 20, completionTokens = 7, gapMs = 0 } = {}) => async (req, res) => {
+    res.writeHead(200, { "content-type": "text/event-stream" });
+    for (const d of deltas) {
+        res.write(`data: ${JSON.stringify({ choices: [{ index: 0, delta: { content: d } }] })}\n\n`);
+        if (gapMs) await new Promise((r) => setTimeout(r, gapMs));
+    }
+    res.write(`data: ${JSON.stringify({ choices: [{ index: 0, delta: {}, finish_reason: "stop" }] })}\n\n`);
+    res.write(`data: ${JSON.stringify({ choices: [], usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens } })}\n\n`);
+    res.end("data: [DONE]\n\n");
+};
+
+export const status = (code, body = "") => (req, res) => { res.writeHead(code, { "content-type": "application/json" }); res.end(body); };
+
+/** @param {Function|Function[]} behavior one handler for every request, or a list used in order (the last one repeats) */
+const OPEN = new Set();
+/** Closes every fake server a failed test left open (so a red test never hangs the run). */
+export async function closeAllFakes() { await Promise.all([...OPEN].map((f) => f.close())); }
+
+export async function startFakeLlm(behavior = okJson()) {
+    const requests = [];
+    let list = Array.isArray(behavior) ? behavior : [behavior];
+    const sockets = new Set();
+    const server = http.createServer((req, res) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf8");
+            let body = null;
+            try { body = JSON.parse(raw); } catch { /* keep null */ }
+            const entry = { method: req.method, url: req.url, headers: req.headers, raw, body };
+            requests.push(entry);
+            const h = list[Math.min(requests.length - 1, list.length - 1)];
+            Promise.resolve(h(req, res, entry)).catch(() => { try { res.destroy(); } catch { /* gone */ } });
+        });
+    });
+    server.on("connection", (s) => { sockets.add(s); s.on("close", () => sockets.delete(s)); });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const port = server.address().port;
+    const fake = {
+        port, requests,
+        set(b) { list = Array.isArray(b) ? b : [b]; },
+        /** the fetch the holder uses: the https origin of the key's endpoint is pointed at this server, everything else is untouched */
+        fetchImpl: (url, init) => fetch(String(url).replace(/^https:\/\/[^/]+/, `http://127.0.0.1:${port}`), init),
+        async close() { OPEN.delete(fake); for (const s of sockets) s.destroy(); await new Promise((r) => server.close(r)); },
+    };
+    OPEN.add(fake);
+    return fake;
+}

package/test/la-protocol-v2/jobs-e2e.test.js

@@ -0,0 +1,405 @@
+// F3-10 end to end, in process: the REAL v2 session (signed frames, schemas, acks) against the ReferenceCp, buildV2Link with every flag, the content
+// registry, the LLM key holder, the LLM client and the smoke runner, talking to a FAKE OpenAI-compatible server. What it proves: job.assign ->
+// ack -> job.event running ... succeeded + job.result, metadata only; the file goes to the LLM masked and the key only in a header; cancel reaches the
+// in-flight LLM call; budget, DLP, file gate and workspace/tenant isolation; flags off = nothing. NOT proven: the real LiteLLM, a real CP, the real
+// gateway dispatch (F3-10 gateway side) - only the reference CP and a fake LLM server.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import { ReferenceCp, TENANT, AGENT, uuid, waitFor } from "./helpers/reference-cp.js";
+import { signingFor } from "./helpers/la-rig.js";
+import { write, tmpDir } from "./helpers/content-rig.js";
+import { startFakeLlm, closeAllFakes, okJson, okSse, status, sha, mkKey, keySet } from "./helpers/fake-llm.js";
+import { buildV2Link } from "../../src/la-protocol-v2/runtime.js";
+import { SMOKE_QUESTION } from "../../src/la-protocol-v2/jobs/smoke-runner.js";
+
+after(closeAllFakes);
+
+const GH = "ghp_" + "A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8";
+const FILE_CANARY = "FILE-CANARY-9931";
+const INLINE_CANARY = "TICKET-CANARY-4417";
+const ANSWER = "ANSWER-CANARY-2208 this file prints a greeting.";
+const ALL_ON = { LOCAL_AGENT_DLP_MODE: "enforce", LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_CLIENT: "true", LOCAL_AGENT_JOBS: "true",
+    LOCAL_AGENT_JOBS_RUNNER: "smoke", LOCAL_AGENT_LLM_BACKOFF_MS: "0", LOCAL_AGENT_JOBS_EVENT_MIN_MS: "50", LOCAL_AGENT_JOBS_CANCEL_GRACE_MS: "500" };
+
+async function rig({ env = ALL_ON, behavior = okJson(ANSWER, { promptTokens: 40, completionTokens: 11, cost: "0.0042" }), files, tenantWs, setKey = true, jobRunner } = {}) {
+    const root = tmpDir("f310-");
+    write(root, "src/hello.js", files?.hello ?? `// ${FILE_CANARY}\nconst token = "${GH}";\nconsole.log("hello");\n`);
+    write(root, ".env", "DB_PASSWORD=hunter2-CANARY\n");
+    const other = tmpDir("f310b-");
+    write(other, "src/other.js", "OTHER-WS-CANARY\n");
+    const fake = await startFakeLlm(behavior);
+    const cp = new ReferenceCp();
+    const logs = [];
+    const errors = [];
+    const log = { info: (m) => logs.push(m), log: (m) => logs.push(m), warn: (m) => logs.push(m), error: (m) => errors.push(m) };
+    const wsManager = { list: () => [{ id: "ws-1", root, tenantId: tenantWs ?? TENANT }, { id: "ws-2", root: other, tenantId: TENANT }, { id: "ws-x", root: other, tenantId: "9d1f6a2c-0000-4000-8000-000000000000" }] };
+    const results = [];
+    const link = await buildV2Link({ tenantId: TENANT, agentId: AGENT, signing: signingFor({ keyId: cp.keyId, publicKeyRaw: cp.publicKeyRaw }, "enforce"), wsManager,
+        getWorkspaceRoot: () => root, log, env, llmFetch: fake.fetchImpl, onJobResult: (r) => results.push(r), ...(jobRunner ? { jobRunner } : {}) });
+    const transport = { send: (t) => cp.feed(t), close() {}, bufferedAmount: () => 0 };
+    cp.attach((t) => queueMicrotask(() => link.session.handleText(t, transport)), () => {});
+    link.session.attach(transport);
+    await waitFor(() => link.session.state === "ready");
+    const key = mkKey("E2E");
+    if (setKey && link.llm) {
+        cp.sendData("config.update", { llmKey: keySet(key) });
+        await waitFor(() => cp.acksFromLa.length >= 1);
+    }
+    const refOf = (rel, workspaceId = "ws-1") => link.content?.mintRef({ workspaceId, kind: "file", rel })?.id ?? "A".repeat(43);
+    const ack0 = () => cp.acksFromLa.length;
+    const r = {
+        cp, link, fake, root, other, key, logs, errors, results, refOf,
+        assign(over = {}, workspaceId = "ws-1") {
+            const p = { jobId: uuid(), kind: "quality", repoRef: { provider: "github", org: "acme", repo: "app", branch: "main" }, policy: { operationMode: "assist", automationLevel: 2, ceiling: "assist" },
+                budget: { tokens: 50_000, seconds: 60 }, llm: { alias: "vh-claude-sonnet", keyRef: sha(key) }, inputs: [{ ref: refOf("src/hello.js") }], ...over };
+            const n = ack0();
+            cp.sendData("job.assign", p, { workspaceId });
+            return { p, acked: () => waitFor(() => cp.acksFromLa.length > n).then(() => cp.acksFromLa[n]) };
+        },
+        frames: (jobId, type) => cp.received.filter((f) => (!type || f.type === type) && f.payload.jobId === jobId),
+        done: (jobId) => waitFor(() => r.frames(jobId, "job.result").length === 1, 6000),
+        everything: () => JSON.stringify([cp.received, logs, errors, link.jobs?.audit.tail(1000), link.llm?.client?.audit.tail(1000), link.llm?.audit.tail(1000), link.llm?.client?.stats, link.jobs?.stats]),
+        async stop() { link.close(); await fake.close(); fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(other, { recursive: true, force: true }); },
+    };
+    return r;
+}
+
+// ------------------------------------------------------------------------------------------------------ flags
+
+test("flags off (default, or any LLM/JOBS combination that is not complete): no job capability, no client, job.assign is acked `rejected protocol_unsupported`", async () => {
+    const cases = [
+        { env: {} },
+        { env: { LOCAL_AGENT_JOBS: "true", LOCAL_AGENT_DLP_MODE: "enforce" } },                                                           // no runner
+        { env: { ...ALL_ON, LOCAL_AGENT_DLP_MODE: "warn" }, err: /DLP_MODE is not enforce/ },                                              // DLP not enforce
+        { env: { ...ALL_ON, LOCAL_AGENT_LLM_KEY: "false" }, err: /LOCAL_AGENT_LLM_KEY is not true/ },                                       // client without a holder -> jobs without a client
+        { env: { ...ALL_ON, LOCAL_AGENT_LLM_CLIENT: "false" }, err: /needs the LLM client/ },                                              // smoke without the client
+    ];
+    for (const c of cases) {
+        const r = await rig({ ...c, setKey: false });
+        assert.equal(r.link.jobs, undefined, JSON.stringify(c.env));
+        assert.equal(r.link.llm?.client, undefined);
+        assert.ok(!r.cp.registers[0].capabilities.includes("job.assign"));
+        assert.ok(!r.cp.registers[0].capabilities.includes("job.options"), "no job.options without job.assign");
+        if (c.err) assert.ok(r.errors.some((e) => c.err.test(e)), `expected an ERROR log for ${JSON.stringify(c.env)}`);
+        const a = r.assign({ inputs: [] });
+        const ack = await a.acked();
+        assert.deepEqual([ack.status, ack.errorCode], ["rejected", "protocol_unsupported"], JSON.stringify(c.env));
+        assert.equal(r.fake.requests.length, 0);
+        await r.stop();
+    }
+});
+
+test("flags on: `job.assign` is announced (only with a runner), nothing else changes in register/hello", async () => {
+    const r = await rig();
+    assert.ok(r.cp.registers[0].capabilities.includes("job.assign"));
+    assert.ok(r.cp.hellos[0].capabilities.includes("job.assign"));
+    assert.ok(r.cp.registers[0].capabilities.includes("job.options") && r.cp.hellos[0].capabilities.includes("job.options"), "the smoke runner understands options");
+    assert.ok(r.link.llm.client && r.link.jobs && r.link.jobs.runner.name === "smoke");
+    await r.stop();
+});
+
+// ------------------------------------------------------------------------------------------------------ the smoke job, end to end
+
+test("smoke job: ack accepted -> job.event running -> LLM call (file masked, key in the header only, tags) -> job.event succeeded (tokens, cost) -> job.result no_change; the answer stays local", async () => {
+    const r = await rig();
+    const a = r.assign({ inputs: [{ ref: r.refOf("src/hello.js") }, { inline: `${INLINE_CANARY} please look`, transient: true }] });
+    const ack = await a.acked();
+    assert.equal(ack.status, "accepted");
+    assert.equal(ack.errorCode, undefined);
+    await r.done(a.p.jobId);
+    const evs = r.frames(a.p.jobId, "job.event");
+    assert.equal(evs[0].payload.state, "running");
+    const last = evs.at(-1).payload;
+    assert.deepEqual({ state: last.state, phase: last.phase, errorCode: last.errorCode, tokensIn: last.tokensIn, tokensOut: last.tokensOut, costUsd: last.costUsd, filesRead: last.filesRead },
+        { state: "succeeded", phase: "done", errorCode: "none", tokensIn: 40, tokensOut: 11, costUsd: 0.0042, filesRead: 1 });
+    assert.ok(Number.isInteger(last.durationMs));
+    assert.deepEqual(r.frames(a.p.jobId, "job.result")[0].payload, { jobId: a.p.jobId, outcome: "no_change" });
+    // what reached the AI gateway
+    assert.equal(r.fake.requests.length, 1);
+    const q = r.fake.requests[0];
+    assert.equal(q.headers.authorization, `Bearer ${r.key}`);
+    assert.equal(q.body.model, "vh-claude-sonnet");
+    assert.deepEqual(q.body.metadata.tags, [`vh-tenant:${TENANT}`, `vh-la:${AGENT}`, `vh-job:${a.p.jobId}`, "vh-agent:smoke"]);
+    const prompt = q.body.messages.map((m) => m.content).join("\n");
+    assert.ok(prompt.includes(SMOKE_QUESTION) && prompt.includes(FILE_CANARY), "the (allowed) file is the subject of the fixed question");
+    assert.ok(!q.raw.includes(GH), "the token inside the file was masked BEFORE leaving");
+    assert.match(prompt, /\[REDACTED:/);
+    assert.ok(!q.raw.includes(r.key) && !q.raw.includes(INLINE_CANARY));
+    // the answer is local
+    assert.equal(r.results.length, 1);
+    assert.equal(r.results[0].answer, ANSWER);
+    assert.equal(r.results[0].state, "succeeded");
+    // nothing client-side on the wire, in logs or audits
+    const dump = r.everything();
+    for (const secret of [r.key, sha(r.key), FILE_CANARY, GH, INLINE_CANARY, ANSWER, SMOKE_QUESTION, r.root, "hello.js", "hunter2"]) assert.ok(!dump.includes(secret), `leaked: ${secret.slice(0, 14)}`);
+    for (const f of r.cp.received.filter((x) => x.type === "job.event")) assert.ok(Object.keys(f.payload).every((k) => ["jobId", "state", "phase", "iteration", "filesRead", "filesChanged", "tokensIn", "tokensOut", "costUsd", "durationMs", "errorCode"].includes(k)));
+    await r.stop();
+});
+
+test("a gateway that answers the non-streaming smoke request with an SSE stream is a bad_response: the job fails llm_error (no partial result)", async () => {
+    const r = await rig({ behavior: okSse(["x"]) });
+    const a = r.assign();
+    await r.done(a.p.jobId);
+    assert.equal(r.frames(a.p.jobId, "job.event").at(-1).payload.state, "failed");
+    assert.equal(r.frames(a.p.jobId, "job.event").at(-1).payload.errorCode, "llm_error");
+    await r.stop();
+});
+
+test("the file gate: a denied file (.env), an id of ANOTHER workspace, an unknown id -> the job fails, NO LLM call is made, nothing of the file is anywhere", async () => {
+    const r = await rig();
+    const cases = [
+        [r.refOf(".env"), null],                         // the registry itself refuses to mint an id for a sensitive path
+        [r.refOf("src/other.js", "ws-2"), "ws-2 id"],    // an id of a sibling workspace, used in a job for ws-1
+        ["A".repeat(43), "unknown id"],
+    ];
+    for (const [ref] of cases) {
+        const a = r.assign({ inputs: [{ ref: ref ?? "B".repeat(43) }] });
+        assert.equal((await a.acked()).status, "accepted");
+        await r.done(a.p.jobId);
+        assert.equal(r.frames(a.p.jobId, "job.event").at(-1).payload.state, "failed");
+        assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "failed");
+    }
+    assert.equal(r.fake.requests.length, 0);
+    const noInput = r.assign({ inputs: [] });
+    await r.done(noInput.p.jobId);
+    assert.equal(r.frames(noInput.p.jobId, "job.event").at(-1).payload.errorCode, "unknown");
+    assert.ok(!r.everything().includes("OTHER-WS-CANARY") && !r.everything().includes("hunter2"));
+    await r.stop();
+});
+
+test("isolation: a workspace this agent does not serve, or one that belongs to ANOTHER tenant, is rejected `unauthorized` at the ack; nothing runs", async () => {
+    const r = await rig();
+    for (const ws of ["ws-unknown", "ws-x"]) {
+        const a = r.assign({ inputs: [] }, ws);
+        const ack = await a.acked();
+        assert.equal(ack.status, "rejected", ws);
+        assert.equal(ack.errorCode, "unauthorized", ws);
+    }
+    assert.equal(r.link.jobs.stats.accepted, 0);
+    assert.equal(r.fake.requests.length, 0);
+    await r.stop();
+    const t = await rig({ tenantWs: "9d1f6a2c-0000-4000-8000-000000000000" });
+    const a = t.assign({ inputs: [] });
+    assert.equal((await a.acked()).errorCode, "unauthorized");
+    await t.stop();
+});
+
+test("the job names a key that is not the held one (or there is no key): accepted, then failed llm_error; no LLM call", async () => {
+    const r = await rig();
+    const a = r.assign({ llm: { alias: "vh-claude-sonnet", keyRef: sha("another key") } });
+    assert.equal((await a.acked()).status, "accepted");
+    await r.done(a.p.jobId);
+    assert.equal(r.frames(a.p.jobId, "job.event").at(-1).payload.errorCode, "llm_error");
+    const b = r.assign({ llm: { alias: "vh-claude-sonnet", keyRef: sha(r.key).slice(0, 8) } });
+    await r.done(b.p.jobId);
+    assert.equal(r.frames(b.p.jobId, "job.event").at(-1).payload.state, "succeeded", "the 8-hex key_short names the held key");
+    assert.equal(r.fake.requests.length, 1);
+    await r.stop();
+    const n = await rig({ setKey: false });
+    const c = n.assign();
+    await n.done(c.p.jobId);
+    assert.equal(n.frames(c.p.jobId, "job.event").at(-1).payload.errorCode, "llm_error");
+    await n.stop();
+});
+
+test("an alias outside the key's models is policy_denied (no call); a gateway outage is llm_error after the bounded retries (3 calls)", async () => {
+    const r = await rig();
+    const a = r.assign({ llm: { alias: "vh-drael", keyRef: sha(r.key) } });
+    await r.done(a.p.jobId);
+    assert.equal(r.frames(a.p.jobId, "job.event").at(-1).payload.errorCode, "policy_denied");
+    assert.equal(r.fake.requests.length, 0);
+    await r.stop();
+    const down = await rig({ behavior: status(503) });
+    const b = down.assign();
+    await down.done(b.p.jobId);
+    assert.equal(down.frames(b.p.jobId, "job.event").at(-1).payload.errorCode, "llm_error");
+    assert.equal(down.fake.requests.length, 3, "1 + 2 retries, then the code");
+    await down.stop();
+});
+
+test("budget: a token budget too small for the prompt fails the job budget_exceeded BEFORE any call; the local ceiling clamps what the job asked", async () => {
+    const r = await rig({ env: { ...ALL_ON, LOCAL_AGENT_JOBS_MAX_TOKENS: "20" } });
+    const a = r.assign({ budget: { tokens: 9_000_000, seconds: 60 } });   // clamped to 20 tokens: the prompt alone does not fit
+    await r.done(a.p.jobId);
+    assert.equal(r.frames(a.p.jobId, "job.event").at(-1).payload.errorCode, "budget_exceeded");
+    assert.equal(r.fake.requests.length, 0);
+    await r.stop();
+});
+
+test("cancel: job.cancel while the LLM call is in flight -> the call is aborted, job.event cancelled + job.result cancelled, the slot is free for the next job", async () => {
+    let hangs = true;
+    const r = await rig({ behavior: (q, s, e) => (hangs ? new Promise(() => {}) : okJson("fine")(q, s, e)) });
+    const a = r.assign();
+    assert.equal((await a.acked()).status, "accepted");
+    await waitFor(() => r.fake.requests.length === 1);
+    r.cp.sendData("job.cancel", { jobId: a.p.jobId, reason: "user" });
+    await r.done(a.p.jobId);
+    assert.equal(r.frames(a.p.jobId, "job.event").at(-1).payload.state, "cancelled");
+    assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "cancelled");
+    assert.equal(r.link.llm.client.active, 0, "the in-flight call was released");
+    hangs = false;
+    const b = r.assign();
+    await r.done(b.p.jobId);
+    assert.equal(r.frames(b.p.jobId, "job.event").at(-1).payload.state, "succeeded");
+    assert.equal(r.cp.acksFromLa.filter((x) => x.status === "rejected").length, 0, "job.cancel was acked accepted");
+    await r.stop();
+});
+
+test("limits: concurrency 1 / queue 0 -> the 2nd job.assign is rejected rate_limited while the 1st runs; duplicates of the same job id are accepted and run once", async () => {
+    let release;
+    const gate = new Promise((x) => { release = x; });
+    const r = await rig({ env: { ...ALL_ON, LOCAL_AGENT_JOBS_MAX_QUEUED: "0" }, behavior: async (q, s, e) => { await gate; okJson("late")(q, s, e); } });
+    const a = r.assign();
+    assert.equal((await a.acked()).status, "accepted");
+    await waitFor(() => r.fake.requests.length === 1);
+    const b = r.assign();
+    const ackB = await b.acked();
+    assert.deepEqual([ackB.status, ackB.errorCode], ["rejected", "rate_limited"]);
+    const dup = r.assign({ jobId: a.p.jobId });
+    assert.equal((await dup.acked()).status, "accepted");
+    release();
+    await r.done(a.p.jobId);
+    assert.equal(r.fake.requests.length, 1, "the duplicate did not start a second run");
+    assert.equal(r.frames(a.p.jobId, "job.result").length, 1);
+    await r.stop();
+});
+
+test("the contract is closed: a git token (or any extra field) in job.assign is a schema violation at the session - no runner, no call, no token in a log", async () => {
+    const r = await rig();
+    const evil = "ghp_" + "Z".repeat(36);
+    r.cp.sendData("job.assign", { jobId: uuid(), kind: "fix", repoRef: { provider: "github", org: "a", repo: "b", branch: "main" }, policy: { operationMode: "assist", automationLevel: 2, ceiling: "assist" },
+        budget: { tokens: 1000, seconds: 60 }, llm: { alias: "vh-claude-sonnet", keyRef: sha(r.key) }, gitToken: evil });
+    await waitFor(() => r.cp.peerErrors.length >= 1);
+    assert.deepEqual(r.cp.peerErrors, ["schema_violation"]);
+    assert.equal(r.link.jobs.stats.received, 0);
+    assert.equal(r.fake.requests.length, 0);
+    assert.ok(!r.everything().includes(evil));
+    await r.stop();
+});
+
+test("a pluggable runner: an injected one replaces the smoke runner (job.assign needs no LOCAL_AGENT_JOBS_RUNNER), gets the job + ctx, and its metadata goes back", async () => {
+    const seen = [];
+    const runner = { name: "loop", needsLlm: false, cancel() {}, async start(job, ctx) { seen.push(job.kind, job.inputs.length, Object.keys(ctx).sort()); ctx.progress({ phase: "edit", filesChanged: 2 }); return { outcome: "pr_opened", prUrl: "https://git.example/a/b/pull/1", branch: "vh/x", commitSha: "abcdef1234", filesChangedCount: 2, answer: "local" }; } };
+    const { LOCAL_AGENT_JOBS_RUNNER, LOCAL_AGENT_LLM_CLIENT, ...env } = ALL_ON;
+    const r = await rig({ env, jobRunner: runner, setKey: false });
+    assert.ok(r.cp.registers[0].capabilities.includes("job.assign"));
+    const a = r.assign({ inputs: [{ inline: INLINE_CANARY, transient: true }] });
+    await r.done(a.p.jobId);
+    assert.deepEqual(seen, ["quality", 1, ["budget", "llm", "progress", "readFile", "signal", "workspace"]]);
+    assert.deepEqual(r.frames(a.p.jobId, "job.result")[0].payload, { jobId: a.p.jobId, outcome: "pr_opened", prUrl: "https://git.example/a/b/pull/1", branch: "vh/x", commitSha: "abcdef1234", filesChangedCount: 2 });
+    assert.ok(!r.everything().includes(INLINE_CANARY));
+    await r.stop();
+});
+
+// ------------------------------------------------------------------------------------------------------ job.options (contract 2.1) and the cancel rules
+
+test("job.options: announced only for a runner that declared supportsOptions (the smoke one does); an injected runner without it is not offered options and refuses them", async () => {
+    const { LOCAL_AGENT_JOBS_RUNNER, LOCAL_AGENT_LLM_CLIENT, ...env } = ALL_ON;
+    const plain = { name: "plain", needsLlm: false, cancel() {}, async start() { return { outcome: "no_change" }; } };
+    const r = await rig({ env, jobRunner: plain, setKey: false });
+    assert.ok(r.cp.registers[0].capabilities.includes("job.assign"));
+    assert.ok(!r.cp.registers[0].capabilities.includes("job.options") && !r.cp.hellos[0].capabilities.includes("job.options"));
+    const a = r.assign({ options: { dryRun: true } });
+    const ack = await a.acked();
+    assert.deepEqual([ack.status, ack.errorCode], ["rejected", "protocol_unsupported"], "a dry run is never run as a real job");
+    assert.equal(r.link.jobs.stats.optionsUnsupported, 1);
+    await r.stop();
+    const seen = [];
+    const aware = { name: "aware", needsLlm: false, supportsOptions: true, cancel() {}, async start(job) { seen.push(job.options); return { outcome: "no_change" }; } };
+    const r2 = await rig({ env, jobRunner: aware, setKey: false });
+    assert.ok(r2.cp.registers[0].capabilities.includes("job.options") && r2.cp.hellos[0].capabilities.includes("job.options"));
+    const b = r2.assign({ options: { branchName: "vh/KAN-28-fix", createPullRequest: false, maxIterations: 4 } });
+    assert.equal((await b.acked()).status, "accepted");
+    await r2.done(b.p.jobId);
+    assert.deepEqual(seen, [{ branchName: "vh/KAN-28-fix", createBranch: true, createPullRequest: false, dryRun: false, maxIterations: 4, effects: { createBranch: true, push: true, openPullRequest: false } }]);
+    await r2.stop();
+});
+
+test("smoke job with options (dryRun, createPullRequest:false, maxIterations): accepted, one LLM call, no_change, no branch/PR in the result, the option values are on no frame, log or audit", async () => {
+    const r = await rig();
+    const BRANCH = "vh/OPT-CANARY-branch";
+    const a = r.assign({ options: { ticketKey: "KAN-OPT", branchName: BRANCH, dryRun: true, createPullRequest: false, maxIterations: 1 } });
+    assert.equal((await a.acked()).status, "accepted");
+    await r.done(a.p.jobId);
+    assert.deepEqual(r.frames(a.p.jobId, "job.result")[0].payload, { jobId: a.p.jobId, outcome: "no_change" });
+    assert.equal(r.fake.requests.length, 1, "a dry run still runs the loop (one question)");
+    assert.equal(Math.max(...r.frames(a.p.jobId, "job.event").map((f) => f.payload.iteration ?? 0)), 1);
+    const dump = r.everything();
+    for (const v of [BRANCH, "KAN-OPT"]) assert.ok(!dump.includes(v), `leaked: ${v}`);
+    assert.ok(!r.fake.requests[0].raw.includes(BRANCH));
+    await r.stop();
+});
+
+test("options the contract refuses never reach the receiver: a token, an unknown key, an empty object, a bad branch name are schema violations at the session (fatal for that connection, as for any closed-schema breach)", async () => {
+    for (const options of [{ token: "ghp_" + "Z".repeat(36) }, {}, { dryRun: "true" }, { branchName: "a/../b" }, { maxIterations: 101 }, { createBranch: true, extra: 1 }]) {
+        const r = await rig();
+        r.cp.sendData("job.assign", { jobId: uuid(), kind: "fix", repoRef: { provider: "github", org: "a", repo: "b", branch: "main" }, policy: { operationMode: "assist", automationLevel: 2, ceiling: "assist" },
+            budget: { tokens: 1000, seconds: 60 }, llm: { alias: "vh-claude-sonnet", keyRef: sha(r.key) }, options });
+        await waitFor(() => r.cp.peerErrors.length >= 1);
+        assert.deepEqual(r.cp.peerErrors, ["schema_violation"], JSON.stringify(options));
+        assert.equal(r.link.jobs.stats.received, 0);
+        assert.equal(r.fake.requests.length, 0);
+        assert.ok(!r.everything().includes("ZZZZZZ"));
+        await r.stop();
+    }
+});
+
+test("cancel with an id that is not a UUID: a schema_violation error from the session (clear, nothing echoed), no lookup, the running job is untouched", async () => {
+    for (const jobId of ["../../etc/passwd-ECHO", "not-a-uuid", "", "0".repeat(37)]) {
+        const r = await rig({ behavior: () => new Promise(() => {}) });
+        const a = r.assign();
+        assert.equal((await a.acked()).status, "accepted");
+        await waitFor(() => r.fake.requests.length === 1);
+        r.cp.sendData("job.cancel", { jobId, reason: "timeout" });
+        await waitFor(() => r.cp.peerErrors.length >= 1);
+        assert.equal(r.cp.peerErrors.length, 1);
+        assert.match(r.cp.peerErrors[0], /^(schema_violation|payload_too_large)$/, JSON.stringify(jobId));   // an over-long id breaks the size limit first
+        assert.equal(r.link.jobs.running, 1, "the job did not notice");
+        assert.equal(r.link.jobs.stats.cancels, 0, "no lookup");
+        assert.equal(r.link.jobs.stats.cancelInvalid, 0, "the session refused it first");
+        assert.ok(!r.everything().includes("ECHO"));
+        await r.stop();
+    }
+});
+
+test("cancel of an unknown or a finished job is acked accepted and does nothing; of a running one it cancels it", async () => {
+    let hangs = false;
+    const r = await rig({ behavior: (q, s, e) => (hangs ? new Promise(() => {}) : okJson("fine")(q, s, e)) });
+    const done = r.assign();
+    await r.done(done.p.jobId);
+    hangs = true;
+    const live = r.assign();
+    assert.equal((await live.acked()).status, "accepted");
+    await waitFor(() => r.fake.requests.length === 2);
+    const frames = r.cp.received.length;
+    for (const jobId of [uuid(), done.p.jobId]) {
+        const n = r.cp.acksFromLa.length;
+        r.cp.sendData("job.cancel", { jobId, reason: "timeout" });
+        await waitFor(() => r.cp.acksFromLa.length > n);
+        assert.equal(r.cp.acksFromLa[n].status, "accepted");
+    }
+    await new Promise((x) => setTimeout(x, 60));
+    assert.equal(r.link.jobs.running, 1);
+    assert.ok(r.cp.received.slice(frames).filter((f) => f.payload.jobId === live.p.jobId).every((f) => f.type === "job.event" && f.payload.state === "running"), "the live job saw nothing but its own progress");
+    r.cp.sendData("job.cancel", { jobId: live.p.jobId, reason: "user" });
+    await r.done(live.p.jobId);
+    assert.equal(r.frames(live.p.jobId, "job.result")[0].payload.outcome, "cancelled");
+    assert.equal(r.frames(done.p.jobId, "job.result").length, 1, "the finished one has no second result");
+    await r.stop();
+});
+
+test("an orphan the CP gave up (job.cancel first, job.assign later): the assign is acked accepted and no LLM call, no event, no result", async () => {
+    const r = await rig();
+    const jobId = uuid();
+    const n = r.cp.acksFromLa.length;
+    r.cp.sendData("job.cancel", { jobId, reason: "timeout" });
+    await waitFor(() => r.cp.acksFromLa.length > n);
+    const a = r.assign({ jobId });
+    assert.equal((await a.acked()).status, "accepted");
+    await new Promise((x) => setTimeout(x, 100));
+    assert.equal(r.fake.requests.length, 0);
+    assert.equal(r.frames(jobId).length, 0);
+    assert.equal(r.link.jobs.activeCount, 0);
+    await r.stop();
+});