deepdebug-local-agent 1.9.0 → 1.10.0

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

@@ -0,0 +1,288 @@
+// F3-10 (L3): job.assign `options` (contract 2.1, capability job.options), the review's LOW findings on the LA side and the orphan-cancel rules.
+// Normalizer in isolation; the supervisor with a fake session and scripted runners (options reach the runner, a runner without supportsOptions is
+// refused, dryRun/createPullRequest are never ignored silently, maxIterations is clamped); cancel with a bad id, idempotent cancel of an unknown/finished/
+// cancelling job, a cancel before the assign; readFile of an abandoned job; admission under a synchronous burst (atomic limits).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createJobManager } from "../../src/la-protocol-v2/jobs/manager.js";
+import { resolveJobsConfig } from "../../src/la-protocol-v2/jobs/config.js";
+import { normalizeJobOptions, OPTION_KEYS } from "../../src/la-protocol-v2/jobs/options.js";
+import { ProtocolError } from "../../src/la-protocol-v2/errors.js";
+
+const noop = () => {};
+const uuid = () => crypto.randomUUID();
+const tick = (ms = 5) => new Promise((r) => setTimeout(r, ms));
+const until = async (cond, ms = 3000) => { const t0 = Date.now(); while (!cond()) { if (Date.now() - t0 > ms) throw new Error("until: timed out"); await tick(5); } };
+const CFG = { maxIterations: 25 };
+
+function fakeSession() {
+    const frames = [];
+    return { frames, enqueue: async (type, payload, opts) => { frames.push({ type, payload, workspaceId: opts?.workspaceId }); return { acked: Promise.resolve() }; },
+        of: (jobId, type) => frames.filter((f) => f.payload.jobId === jobId && (!type || f.type === type)) };
+}
+const params = (over = {}) => ({ jobId: uuid(), kind: "implement", 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: "ab".repeat(32) }, inputs: [], ...over });
+const ctxOf = (p, workspaceId = "ws-1") => ({ type: "job.assign", params: p, workspaceId });
+
+function gatedRunner(over = {}) {
+    const calls = { started: [], cancelled: [], jobs: new Map(), ctxs: new Map() };
+    const gates = new Map();
+    return {
+        calls, gates, name: "gated", needsLlm: false, supportsOptions: true,
+        start(job, ctx) {
+            calls.started.push(job.jobId); calls.jobs.set(job.jobId, job); calls.ctxs.set(job.jobId, ctx);
+            return new Promise((resolve, reject) => { gates.set(job.jobId, { resolve, reject }); ctx.signal.addEventListener("abort", () => { if (!over.ignoreAbort) reject(new Error("aborted")); }, { once: true }); });
+        },
+        cancel(jobId) { calls.cancelled.push(jobId); },
+        ...over,
+    };
+}
+function mgr({ runner = gatedRunner(), env = {}, readFile = null, audit } = {}) {
+    const session = fakeSession();
+    const config = resolveJobsConfig({ LOCAL_AGENT_JOBS: "true", LOCAL_AGENT_JOBS_EVENT_MIN_MS: "50", LOCAL_AGENT_JOBS_CANCEL_GRACE_MS: "100", LOCAL_AGENT_JOBS_TERMINAL_RETRY_MS: "10", ...env }, noop);
+    const m = createJobManager({ session, tenantId: "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f", resolveWorkspace: (id) => (id === "ws-1" ? { root: "/w/ws-1" } : null), config,
+        env: { LOCAL_AGENT_DLP_MODE: "enforce" }, runner, readFile, log: { warn: noop }, ...(audit ? { audit } : {}) });
+    return { m, session, runner, config };
+}
+
+// ------------------------------------------------------------------------------------------------------ the normalizer
+
+test("options: absent = the agent's defaults (branch + PR on, no dry run, the local iteration ceiling); frozen; effects follow the flags conservatively", () => {
+    const r = normalizeJobOptions(undefined, CFG);
+    assert.equal(r.ok, true);
+    assert.deepEqual(r.options, { createBranch: true, createPullRequest: true, dryRun: false, maxIterations: 25, effects: { createBranch: true, push: true, openPullRequest: true } });
+    assert.ok(Object.isFrozen(r.options) && Object.isFrozen(r.options.effects));
+    assert.deepEqual(r.present, []);
+    const all = normalizeJobOptions({ ticketKey: "KAN-28", branchName: "vh/KAN-28-fix", createBranch: true, createPullRequest: false, dryRun: false, maxIterations: 10 }, CFG);
+    assert.deepEqual(all.options, { ticketKey: "KAN-28", branchName: "vh/KAN-28-fix", createBranch: true, createPullRequest: false, dryRun: false, maxIterations: 10, effects: { createBranch: true, push: true, openPullRequest: false } });
+    assert.deepEqual(all.present, [...OPTION_KEYS].sort());
+    // dryRun: no effect at all, whatever else is asked
+    assert.deepEqual(normalizeJobOptions({ dryRun: true, createBranch: true, createPullRequest: true }, CFG).options.effects, { createBranch: false, push: false, openPullRequest: false });
+    // createBranch:false: work on repoRef.branch, never push to it, no PR
+    assert.deepEqual(normalizeJobOptions({ createBranch: false, createPullRequest: true }, CFG).options.effects, { createBranch: false, push: false, openPullRequest: false });
+});
+
+test("options: maxIterations is clamped to the local ceiling (never widened) and only lowered by the job", () => {
+    assert.equal(normalizeJobOptions({ maxIterations: 100 }, { maxIterations: 8 }).options.maxIterations, 8);
+    assert.equal(normalizeJobOptions({ maxIterations: 3 }, { maxIterations: 8 }).options.maxIterations, 3);
+    assert.equal(normalizeJobOptions({ dryRun: true }, { maxIterations: 8 }).options.maxIterations, 8);
+});
+
+test("options: malformed objects are refused (closed, minProperties 1, types, ranges, branch/ticket patterns)", () => {
+    const bad = [null, [], "x", 5, {}, { extra: 1 }, { token: "ghp_x" }, { dryRun: "true" }, { dryRun: 1 }, { createBranch: null }, { createPullRequest: "no" },
+        { maxIterations: 0 }, { maxIterations: 101 }, { maxIterations: 1.5 }, { maxIterations: "5" }, { maxIterations: Infinity },
+        { ticketKey: "" }, { ticketKey: "-x" }, { ticketKey: "a".repeat(65) }, { ticketKey: "KAN 28" }, { ticketKey: 28 },
+        { branchName: "" }, { branchName: "a..b" }, { branchName: "a//b" }, { branchName: "a/.b" }, { branchName: "a." }, { branchName: "a/" }, { branchName: "x.lock" }, { branchName: "a/x.lock/b" },
+        { branchName: "-rf" }, { branchName: ".hidden" }, { branchName: "a b" }, { branchName: "a;rm" }, { branchName: "a$(x)" }, { branchName: "a\nb" }, { branchName: "a".repeat(256) }, { branchName: "/abs" }, { branchName: 5 }];
+    for (const b of bad) assert.deepEqual(normalizeJobOptions(b, CFG), { ok: false }, JSON.stringify(b));
+    for (const good of [{ branchName: "vh/KAN-28_fix.1" }, { branchName: "a" }, { branchName: "a".repeat(255) }, { ticketKey: "KAN-28" }, { ticketKey: "a" }, { maxIterations: 1 }, { maxIterations: 100 }]) {
+        assert.equal(normalizeJobOptions(good, CFG).ok, true, JSON.stringify(good));
+    }
+});
+
+// ------------------------------------------------------------------------------------------------------ options reach the runner
+
+test("job.assign with options: the runner gets job.options (normalized, frozen, clamped); without options it still gets the defaults; the audit lists keys, not values", async () => {
+    const entries = [];
+    const audit = { record: (e) => { entries.push(e); return e; }, tail: () => entries };
+    const { m, runner, session } = mgr({ env: { LOCAL_AGENT_JOBS_MAX_CONCURRENT: "2", LOCAL_AGENT_JOBS_MAX_ITERATIONS: "7" }, audit });
+    const a = params({ options: { ticketKey: "KAN-28", branchName: "vh/secret-branch-name", dryRun: true, maxIterations: 50 } });
+    const b = params();
+    assert.deepEqual(m.handleAssign(ctxOf(a)), { accept: true });
+    assert.deepEqual(m.handleAssign(ctxOf(b)), { accept: true });
+    await until(() => runner.calls.started.length === 2);
+    const oa = runner.calls.jobs.get(a.jobId).options;
+    assert.deepEqual(oa, { ticketKey: "KAN-28", branchName: "vh/secret-branch-name", createBranch: true, createPullRequest: true, dryRun: true, maxIterations: 7, effects: { createBranch: false, push: false, openPullRequest: false } });
+    assert.ok(Object.isFrozen(oa) && Object.isFrozen(runner.calls.jobs.get(a.jobId)));
+    assert.deepEqual(runner.calls.jobs.get(b.jobId).options, { createBranch: true, createPullRequest: true, dryRun: false, maxIterations: 7, effects: { createBranch: true, push: true, openPullRequest: true } });
+    const acc = entries.find((e) => e.event === "job_accepted" && e.options?.length);
+    assert.deepEqual(acc.options, ["branchName", "dryRun", "maxIterations", "ticketKey"]);
+    const dump = JSON.stringify([entries, session.frames]);
+    assert.ok(!dump.includes("vh/secret-branch-name") && !dump.includes("KAN-28"), "values of options are not in the audit or on the wire");
+    m.cancelAll();
+});
+
+test("a runner that did not declare supportsOptions is refused any options (protocol_unsupported): dryRun / createPullRequest:false are never ignored silently", async () => {
+    const r = gatedRunner({ supportsOptions: undefined });
+    const { m } = mgr({ runner: r });
+    for (const options of [{ dryRun: true }, { createPullRequest: false }, { maxIterations: 3 }, { ticketKey: "KAN-1" }]) {
+        assert.deepEqual(m.handleAssign(ctxOf(params({ options }))), { reject: "protocol_unsupported" }, JSON.stringify(options));
+    }
+    assert.equal(r.calls.started.length, 0);
+    assert.equal(m.stats.optionsUnsupported, 4);
+    assert.equal(m.activeCount, 0); assert.equal(m.reservedBytes, 0);
+    // without options the same runner works as before
+    const p = params();
+    assert.deepEqual(m.handleAssign(ctxOf(p)), { accept: true });
+    await until(() => r.calls.started.length === 1);
+    assert.deepEqual(r.calls.jobs.get(p.jobId).options.effects, { createBranch: true, push: true, openPullRequest: true });
+    m.cancelAll();
+});
+
+test("malformed options that got past the session -> rejected schema_violation, nothing reserved, nothing started", () => {
+    const { m, runner } = mgr();
+    for (const options of [{}, { dryRun: "yes" }, { extra: true }, { branchName: "../x" }, null]) assert.deepEqual(m.handleAssign(ctxOf(params({ options }))), { reject: "schema_violation" }, JSON.stringify(options));
+    assert.equal(m.stats.optionsInvalid, 5);
+    assert.equal(m.activeCount, 0); assert.equal(m.reservedBytes, 0); assert.equal(runner.calls.started.length, 0);
+});
+
+test("a duplicate job id with different options is still idempotent: acked, not started again, the first options stand", async () => {
+    const { m, runner } = mgr();
+    const p = params({ options: { dryRun: true } });
+    m.handleAssign(ctxOf(p));
+    assert.deepEqual(m.handleAssign(ctxOf({ ...p, options: { dryRun: false } })), { accept: true });
+    await until(() => runner.calls.started.length === 1);
+    await tick(20);
+    assert.equal(runner.calls.started.length, 1);
+    assert.equal(runner.calls.jobs.get(p.jobId).options.dryRun, true);
+    m.cancelAll();
+});
+
+// ------------------------------------------------------------------------------------------------------ cancel
+
+test("cancel with an id that is not a UUID: rejected schema_violation, no lookup, no state change, no frame, nothing echoed in the audit", async () => {
+    const entries = [];
+    const audit = { record: (e) => { entries.push(e); return e; }, tail: () => entries };
+    const { m, session, runner } = mgr({ audit });
+    const live = params();
+    m.handleAssign(ctxOf(live));
+    await until(() => runner.calls.started.length === 1);
+    const ECHO = "../../etc/passwd-ECHO";
+    for (const bad of [ECHO, "", "not-a-uuid", live.jobId.toUpperCase(), `${live.jobId} `, 42, null, undefined, {}, [live.jobId]]) {
+        assert.deepEqual(m.handleCancel({ params: { jobId: bad, reason: "user" } }), { reject: "schema_violation" }, String(bad));
+    }
+    assert.deepEqual(m.handleCancel({ params: null }), { reject: "schema_violation" });
+    assert.equal(m.stats.cancelInvalid, 11);
+    assert.equal(m.stats.cancels, 0, "no lookup counted");
+    assert.equal(m.running, 1); assert.equal(runner.calls.cancelled.length, 0);
+    await tick(20);
+    assert.equal(session.of(live.jobId, "job.event").at(-1).payload.state, "running", "the live job is untouched");
+    assert.ok(!JSON.stringify(entries).includes("ECHO"));
+    // and the real cancel still works
+    assert.deepEqual(m.handleCancel({ params: { jobId: live.jobId, reason: "user" } }), { accept: true });
+    await until(() => session.of(live.jobId, "job.result").length === 1);
+    m.cancelAll();
+});
+
+test("cancel is idempotent: twice on a running job, while it is being abandoned, after it finished, for an unknown id: always accepted, one result, one runner.cancel", async () => {
+    const stubborn = mgr({ runner: gatedRunner({ ignoreAbort: true }) });
+    const p = params();
+    stubborn.m.handleAssign(ctxOf(p));
+    await until(() => stubborn.runner.calls.started.length === 1);
+    for (let i = 0; i < 3; i++) assert.deepEqual(stubborn.m.handleCancel({ params: { jobId: p.jobId, reason: "timeout" } }), { accept: true });
+    assert.deepEqual(stubborn.runner.calls.cancelled, [p.jobId], "the runner is told once");
+    await until(() => stubborn.session.of(p.jobId, "job.result").length === 1, 2000);
+    const n = stubborn.session.frames.length;
+    for (let i = 0; i < 3; i++) assert.deepEqual(stubborn.m.handleCancel({ params: { jobId: p.jobId, reason: "timeout" } }), { accept: true });
+    assert.deepEqual(stubborn.m.handleCancel({ params: { jobId: uuid(), reason: "timeout" } }), { accept: true });
+    await tick(30);
+    assert.equal(stubborn.session.frames.length, n, "no frame, no oracle");
+    assert.equal(stubborn.session.of(p.jobId, "job.result").length, 1);
+    assert.equal(stubborn.m.running, 0); assert.equal(stubborn.m.reservedBytes, 0);
+});
+
+test("an orphan the CP gave up: job.cancel before the job.assign -> the assign that arrives later is acked accepted and NOT run; a finished job's id is not turned into a tombstone", async () => {
+    const { m, runner, session } = mgr();
+    const orphan = params();
+    assert.deepEqual(m.handleCancel({ params: { jobId: orphan.jobId, reason: "timeout" } }), { accept: true });
+    assert.deepEqual(m.handleAssign(ctxOf(orphan)), { accept: true });
+    await tick(30);
+    assert.equal(runner.calls.started.length, 0);
+    assert.equal(m.activeCount, 0); assert.equal(m.reservedBytes, 0); assert.equal(m.running, 0);
+    assert.equal(session.frames.length, 0, "nothing was sent for it");
+    assert.equal(m.stats.cancelledBeforeAssign, 1);
+    // another job is unaffected
+    const ok = params();
+    m.handleAssign(ctxOf(ok));
+    await until(() => runner.calls.started.length === 1);
+    m.cancelAll();
+});
+
+test("the tombstones are bounded: a flood of cancels for unknown ids forgets the oldest, never grows without limit", () => {
+    const { m } = mgr();
+    const first = uuid();
+    m.handleCancel({ params: { jobId: first, reason: "user" } });
+    for (let i = 0; i < 300; i++) m.handleCancel({ params: { jobId: uuid(), reason: "user" } });
+    // the oldest was evicted: its assign is no longer suppressed
+    assert.deepEqual(m.handleAssign(ctxOf(params({ jobId: first }))), { accept: true });
+    assert.equal(m.stats.cancelledBeforeAssign, 0);
+    assert.equal(m.activeCount, 1);
+    m.cancelAll();
+});
+
+// ------------------------------------------------------------------------------------------------------ readFile of an abandoned job
+
+test("readFile: after cancel / timeout / abandonment the runner reads nothing (no call to the reader), and the result of a read in flight is dropped", async () => {
+    let reads = 0;
+    const live = [];
+    const readFile = async ({ signal }) => { reads++; live.push(signal); await tick(40); return { ok: true, text: "SECRET-FILE-TEXT" }; };
+    const { m, runner } = mgr({ runner: gatedRunner({ ignoreAbort: true }), readFile });
+    const p = params();
+    m.handleAssign(ctxOf(p));
+    await until(() => runner.calls.started.length === 1);
+    const ctx = runner.calls.ctxs.get(p.jobId);
+    assert.deepEqual(await ctx.readFile("r"), { ok: true, text: "SECRET-FILE-TEXT" });
+    const inflight = ctx.readFile("r");                       // in flight when the cancel arrives
+    m.handleCancel({ params: { jobId: p.jobId, reason: "user" } });
+    assert.deepEqual(await inflight, { ok: false, status: "cancelled" }, "the text of a read finished after the cancel is not handed over");
+    assert.equal(reads, 2);
+    assert.deepEqual(await ctx.readFile("r"), { ok: false, status: "cancelled" });
+    assert.equal(reads, 2, "no new read after the cancel");
+    await until(() => m.running === 0, 2000);                 // abandoned after the grace: the slot and the memory are free
+    assert.deepEqual(await ctx.readFile("r"), { ok: false, status: "cancelled" });
+    assert.equal(reads, 2, "nor after the runner was abandoned");
+    assert.equal(live.at(-1).aborted, true, "the signal handed to the reader is aborted: the descriptor is released by the reader");
+    assert.equal(m.reservedBytes, 0);
+});
+
+test("readFile: a job that ended on its own (the runner returned) also closes the signal, so a lingering read is released", async () => {
+    const signals = [];
+    const readFile = async ({ signal }) => { signals.push(signal); await tick(30); return { ok: true, text: "x" }; };
+    const runner = { name: "leaky", needsLlm: false, supportsOptions: true, cancel: noop, async start(job, ctx) { ctx.readFile("r").catch(noop); return { outcome: "no_change" }; } };
+    const { m, session } = mgr({ runner, readFile });
+    const p = params();
+    m.handleAssign(ctxOf(p));
+    await until(() => session.of(p.jobId, "job.result").length === 1);
+    assert.equal(signals.length, 1);
+    assert.equal(signals[0].aborted, true);
+    assert.equal(m.running, 0);
+    assert.equal(m.stats.finished.succeeded, 1, "the aborted signal did not turn a success into a failure");
+});
+
+// ------------------------------------------------------------------------------------------------------ atomic limits
+
+test("limits under a synchronous burst: 200 job.assign in one tick -> exactly maxConcurrent run, exactly maxQueued wait, the rest rate_limited; counters never exceed the limits", async () => {
+    const { m, runner } = mgr({ env: { LOCAL_AGENT_JOBS_MAX_CONCURRENT: "3", LOCAL_AGENT_JOBS_MAX_QUEUED: "5" } });
+    const verdicts = [];
+    for (let i = 0; i < 200; i++) verdicts.push(m.handleAssign(ctxOf(params())));
+    assert.equal(verdicts.filter((v) => v.accept).length, 8);
+    assert.equal(verdicts.filter((v) => v.reject === "rate_limited").length, 192);
+    assert.equal(m.running, 3); assert.equal(m.activeCount, 8);
+    await until(() => runner.calls.started.length === 3);
+    await tick(30);
+    assert.equal(runner.calls.started.length, 3, "never more than maxConcurrent started");
+    // finish them one by one: the queue drains in order, running never exceeds 3
+    let maxRunning = 0;
+    for (let guard = 0; guard < 20 && m.activeCount > 0; guard++) {
+        maxRunning = Math.max(maxRunning, m.running);
+        for (const [id, gate] of [...runner.gates]) { gate.resolve({ outcome: "no_change" }); runner.gates.delete(id); }
+        await tick(15);
+    }
+    assert.equal(runner.calls.started.length, 8);
+    assert.ok(maxRunning <= 3);
+    assert.equal(m.activeCount, 0); assert.equal(m.running, 0); assert.equal(m.reservedBytes, 0);
+});
+
+test("limits: cancelling the waiting job frees its place in the queue; the queue keeps its order", async () => {
+    const { m, runner } = mgr({ env: { LOCAL_AGENT_JOBS_MAX_CONCURRENT: "1", LOCAL_AGENT_JOBS_MAX_QUEUED: "1" } });
+    const [a, b, c] = [params(), params(), params()];
+    m.handleAssign(ctxOf(a)); m.handleAssign(ctxOf(b));
+    assert.deepEqual(m.handleAssign(ctxOf(c)), { reject: "rate_limited" });
+    await until(() => runner.calls.started.length === 1);
+    m.handleCancel({ params: { jobId: b.jobId, reason: "user" } });
+    assert.deepEqual(m.handleAssign(ctxOf(c)), { accept: true }, "b's place is free again");
+    runner.gates.get(a.jobId).resolve({ outcome: "no_change" });
+    await until(() => runner.calls.started.length === 2);
+    assert.deepEqual(runner.calls.started, [a.jobId, c.jobId], "b never ran, c took its turn");
+    m.cancelAll();
+});