@wenathlan/devthink 2.0.12 → 2.0.14

package/tests/backgroundruns.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import {
+  backgroundqueueentryof,
+  backgroundrunattention,
+  backgroundrunsview,
+  backgroundtrayrows,
+  beginbackgroundrun,
+  cancelbackgroundentry,
+  enqueuebackgroundrun,
+  finishbackgroundrun,
+  nextbackgroundrun,
+  resumebackgroundqueue,
+} from "../run.js";
+import { backgroundrungate } from "../policy.js";
+
+const now = 1_800_000_000_000;
+
+describe("background run queue", () => {
+  it("enqueues reviewed workflows in order and picks the oldest first", () => {
+    const first = backgroundqueueentryof({ workflowid: "wf-a", summary: "run a", now });
+    const queue = enqueuebackgroundrun({ queue: [first], workflowid: "wf-b", summary: "run b", now: now + 1000 });
+    expect(queue).toHaveLength(2);
+    expect(nextbackgroundrun(queue)?.workflowid).toBe("wf-a");
+    expect(nextbackgroundrun([])).toBeUndefined();
+    expect(() => backgroundqueueentryof({ workflowid: " ", summary: "", now })).toThrow(/workflow id/);
+  });
+
+  it("holds the keepalive signal for the whole run behind the background run gate", () => {
+    const entry = backgroundqueueentryof({ workflowid: "wf-a", summary: "run a", now });
+    const begun = beginbackgroundrun(entry, now, true);
+    expect(begun.gate.allowed).toBe(true);
+    expect(begun.entry.state).toBe("running");
+    expect(begun.entry.keepaliveheld).toBe(true);
+    expect(begun.entry.startedat).toBe(now);
+    const refused = beginbackgroundrun(entry, now, false);
+    expect(refused.gate.allowed).toBe(false);
+    expect(refused.entry.state).toBe("queued");
+    expect(backgroundrungate({ reviewed: false, keepaliveheld: true }).allowed).toBe(false);
+    expect(backgroundrungate({ reviewed: true, keepaliveheld: false }).allowed).toBe(false);
+    expect(backgroundrungate({ reviewed: true, keepaliveheld: true }).allowed).toBe(true);
+  });
+
+  it("finishes runs, releases the hold and feeds the attentionfeed on failure", () => {
+    const entry = beginbackgroundrun(
+      backgroundqueueentryof({ workflowid: "wf-a", summary: "run a", now }),
+      now,
+      true,
+    ).entry;
+    const done = finishbackgroundrun(entry, "done", now + 4000);
+    expect(done.state).toBe("done");
+    expect(done.keepaliveheld).toBe(false);
+    expect(done.endedat).toBe(now + 4000);
+    expect(backgroundrunattention(done, "https://example.com")).toBeUndefined();
+    const failed = finishbackgroundrun(entry, "failed", now + 4000);
+    const attention = backgroundrunattention(failed, "https://example.com");
+    expect(attention?.cause).toBe("failure");
+    expect(attention?.summary).toMatch(/failed/);
+    const queued = backgroundqueueentryof({ workflowid: "wf-b", summary: "run b", now });
+    expect(backgroundrunattention(queued, "https://example.com")?.cause).toBe("deferral");
+  });
+
+  it("requeues interrupted running entries for restart recovery", () => {
+    const running = beginbackgroundrun(
+      backgroundqueueentryof({ workflowid: "wf-a", summary: "run a", now }),
+      now,
+      true,
+    ).entry;
+    const done = finishbackgroundrun(
+      beginbackgroundrun(backgroundqueueentryof({ workflowid: "wf-b", summary: "run b", now }), now, true).entry,
+      "done",
+      now + 1000,
+    );
+    const recovered = resumebackgroundqueue([running, done], now + 5000);
+    expect(recovered.requeued).toEqual([running.id]);
+    expect(recovered.queue[0]?.state).toBe("queued");
+    expect(recovered.queue[0]?.keepaliveheld).toBe(false);
+    expect(recovered.queue[1]?.state).toBe("done");
+  });
+
+  it("renders the dashboard view, the recenttray background section and cancels queued entries only", () => {
+    const queued = backgroundqueueentryof({ workflowid: "wf-a", summary: "run a", now });
+    const running = beginbackgroundrun(
+      backgroundqueueentryof({ workflowid: "wf-b", summary: "run b", now: now + 1 }),
+      now,
+      true,
+    ).entry;
+    const view = backgroundrunsview([queued, running]);
+    expect(view[0]?.progress).toMatch(/Queued/);
+    expect(view[1]?.progress).toMatch(/keepalive signal held/);
+    const tray = backgroundtrayrows([finishbackgroundrun(running, "done", now + 100)], "https://example.com");
+    expect(tray[0]?.outcome).toBe("completed");
+    expect(tray[0]?.reopenable).toBe(true);
+    const cancelled = cancelbackgroundentry([queued, running], queued.id);
+    expect(cancelled.cancelled).toEqual([queued.id]);
+    expect(cancelled.queue).toHaveLength(1);
+    const notcancelled = cancelbackgroundentry([queued, running], running.id);
+    expect(notcancelled.cancelled).toHaveLength(0);
+    expect(notcancelled.queue).toHaveLength(2);
+  });
+});

package/tests/batchscheduling.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import {
+  adaptivepollnext,
+  advancelane,
+  batchbackpressuresignal,
+  cadenceunderpressure,
+  coalescefanout,
+  coalescequeries,
+  domainlanesfor,
+  politedelayfor,
+} from "../perf.js";
+import { adaptivepollvalid, batchwindowvalid, domainlimitsvalid, politedelayvalid } from "../policy.js";
+
+const now = 1_800_000_000_000;
+
+describe("batch backpressure", () => {
+  it("pauses enqueueing when the downstream steps fall behind past the user window and never drops a queued step", () => {
+    const paused = batchbackpressuresignal({ runid: "run1", enqueued: 10, completed: 3, window: 5, now });
+    expect(paused).toEqual({ runid: "run1", enqueued: 10, completed: 3, behind: 7, paused: true, window: 5, at: now });
+    const open = batchbackpressuresignal({ runid: "run1", enqueued: 10, completed: 8, window: 5, now });
+    expect(open.paused).toBe(false);
+    const unbounded = batchbackpressuresignal({ runid: "run1", enqueued: 10, completed: 0, now });
+    expect(unbounded.paused).toBe(false);
+    expect(unbounded.window).toBeUndefined();
+    expect(() => batchbackpressuresignal({ runid: " ", enqueued: 1, completed: 0, now })).toThrow(/run id/i);
+    expect(batchwindowvalid({ window: 5 }).allowed).toBe(true);
+    expect(batchwindowvalid({ window: 5 }).reason).toMatch(/never drops a queued step/i);
+    expect(batchwindowvalid({}).reason).toMatch(/never pauses/i);
+    expect(batchwindowvalid({ window: 0 }).allowed).toBe(false);
+  });
+});
+
+describe("domain limits", () => {
+  it("caps concurrent steps per domain at the user chosen slots and queues the overflow per lane", () => {
+    const steps = [
+      { id: "a1", domain: "example.com" },
+      { id: "a2", domain: "example.com" },
+      { id: "a3", domain: "example.com" },
+      { id: "b1", domain: "shop.example" },
+    ];
+    const lanes = domainlanesfor({ steps, limits: { "example.com": 2 } });
+    expect(lanes).toHaveLength(2);
+    const example = lanes.find((lane) => lane.domain === "example.com");
+    expect(example?.slots).toBe(2);
+    expect(example?.running).toEqual(["a1", "a2"]);
+    expect(example?.queued).toEqual(["a3"]);
+    const shop = lanes.find((lane) => lane.domain === "shop.example");
+    expect(shop?.running).toEqual(["b1"]);
+    expect(shop?.queued).toEqual([]);
+    const afterone = { ...example!, running: example!.running.slice(0, 1) };
+    const advanced = advancelane(afterone, 1);
+    expect(advanced.running).toEqual(["a1", "a3"]);
+    expect(advanced.queued).toEqual([]);
+    const overadvanced = advancelane(advanced, 5);
+    expect(overadvanced.running).toHaveLength(2);
+    expect(domainlimitsvalid({ domain: "example.com", slots: 2 }).allowed).toBe(true);
+    expect(domainlimitsvalid({ domain: "example.com" }).reason).toMatch(/unbounded/i);
+    expect(domainlimitsvalid({ domain: "example.com", slots: 0 }).allowed).toBe(false);
+  });
+});
+
+describe("politedelay", () => {
+  it("spaces batch requests per domain with jitter and honors the per domain floors", () => {
+    expect(politedelayfor({ domain: "example.com", base: 500, jitter: 200, roll: 0.5 })).toBe(600);
+    expect(politedelayfor({ domain: "example.com", base: 500, jitter: 200, roll: 0 })).toBe(500);
+    expect(politedelayfor({ domain: "example.com", base: 100, floor: 400, jitter: 0, roll: 1 })).toBe(400);
+    expect(politedelayfor({ domain: "example.com", base: 0, roll: 0 })).toBe(0);
+    expect(() => politedelayfor({ domain: " ", base: 1, roll: 0 })).toThrow(/domain/i);
+    expect(politedelayvalid({ domain: "example.com", base: 500, jitter: 200 }).allowed).toBe(true);
+    expect(politedelayvalid({ domain: "example.com" }).reason).toMatch(/unspaced/i);
+    expect(politedelayvalid({ domain: "example.com", base: -1 }).allowed).toBe(false);
+  });
+});
+
+describe("adaptivepoll", () => {
+  it("widens the interval while observations stay unchanged and narrows it when changes resume", () => {
+    const window = { floor: 100, ceiling: 1600, growth: 2 };
+    expect(adaptivepollnext({ interval: 100, window, changed: false })).toBe(200);
+    expect(adaptivepollnext({ interval: 1600, window, changed: false })).toBe(1600);
+    expect(adaptivepollnext({ interval: 400, window, changed: true })).toBe(200);
+    expect(adaptivepollnext({ interval: 100, window, changed: true })).toBe(100);
+    expect(adaptivepollnext({ interval: 500, window: { ...window, growth: 1 }, changed: false })).toBe(500);
+    expect(adaptivepollvalid({ window }).allowed).toBe(true);
+    expect(adaptivepollvalid({}).reason).toMatch(/fixed/i);
+    expect(adaptivepollvalid({ window: { floor: 200, ceiling: 100, growth: 2 } }).allowed).toBe(false);
+    expect(adaptivepollvalid({ window: { floor: 100, ceiling: 200, growth: 1 } }).allowed).toBe(false);
+  });
+});
+
+describe("requestcoalesce", () => {
+  it("merges identical pending queries into one dispatch and fans the single result out to every waiter", () => {
+    const merged = coalescequeries({
+      requests: [
+        { key: "run1:https://example.com/data", waiter: "s1" },
+        { key: "run1:https://example.com/data", waiter: "s2" },
+        { key: "run1:https://example.com/data", waiter: "s2" },
+        { key: "run1:https://example.com/other", waiter: "s3" },
+      ],
+    });
+    expect(merged).toHaveLength(2);
+    const first = merged.find((entry) => entry.key === "run1:https://example.com/data");
+    expect(first?.waiters).toEqual(["s1", "s2"]);
+    expect(first?.dispatched).toBe(true);
+    const fanout = coalescefanout(first!, { ok: true });
+    expect(fanout).toEqual([
+      { waiter: "s1", result: { ok: true } },
+      { waiter: "s2", result: { ok: true } },
+    ]);
+  });
+});
+
+describe("cadence under memory pressure", () => {
+  it("lowers the snapshot frequency under memory pressure and restores it when the pressure clears", () => {
+    const base = { base: 500, current: 500, pressure: false };
+    const pressured = cadenceunderpressure({ control: base, pressure: true, widening: 2 });
+    expect(pressed(pressured));
+    expect(pressured.current).toBe(1000);
+    expect(pressured.pressure).toBe(true);
+    const held = cadenceunderpressure({ control: pressured, pressure: true, widening: 2 });
+    expect(held.current).toBe(1000);
+    const cleared = cadenceunderpressure({ control: pressured, pressure: false, widening: 2 });
+    expect(cleared.current).toBe(500);
+    expect(cleared.pressure).toBe(false);
+    const nowidening = cadenceunderpressure({ control: base, pressure: true });
+    expect(nowidening.current).toBe(500);
+  });
+});
+
+function pressed(control: { base: number; current: number; pressure: boolean }): boolean {
+  return control.current >= control.base;
+}

package/tests/blackboard.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it } from "vitest";
+import {
+  blackboardsections,
+  boardsummary,
+  emptyboard,
+  entryfresh,
+  inheritconsent,
+  postentry,
+  readentries,
+  retireentries,
+  retireentry,
+} from "../swarm.js";
+import type { blackboard } from "../types.js";
+
+const now = 1_800_000_000_000;
+
+/** Builds one board fixture with the four shared sections. */
+function board(over: Partial<blackboard> = {}): blackboard {
+  return { sections: [...blackboardsections], entries: [], ...over };
+}
+
+describe("blackboard post and read", () => {
+  it("posts an entry to a section with the author and the consent class", () => {
+    const posted = postentry({
+      board: board(),
+      id: "e1",
+      key: "pricing.url",
+      value: "https://example.com/pricing",
+      section: "facts",
+      author: "a1",
+      now,
+    });
+    expect(posted.entries).toHaveLength(1);
+    expect(posted.entries[0]).toMatchObject({
+      key: "pricing.url",
+      author: "a1",
+      section: "facts",
+      consentclass: "read",
+      valuekind: "text",
+    });
+  });
+
+  it("refuses entries without a key, a value, an author or with a json value that does not parse", () => {
+    expect(() =>
+      postentry({ board: board(), id: "e1", key: " ", value: "v", section: "facts", author: "a1", now }),
+    ).toThrow(/key/i);
+    expect(() =>
+      postentry({ board: board(), id: "e1", key: "k", value: " ", section: "facts", author: "a1", now }),
+    ).toThrow(/value/i);
+    expect(() =>
+      postentry({ board: board(), id: "e1", key: "k", value: "v", section: "facts", author: " ", now }),
+    ).toThrow(/author/i);
+    expect(() =>
+      postentry({ board: board(), id: "e1", key: "k", value: "v", section: "secret" as never, author: "a1", now }),
+    ).toThrow(/sections/i);
+    expect(() =>
+      postentry({
+        board: board(),
+        id: "e1",
+        key: "k",
+        value: "{not json",
+        section: "facts",
+        author: "a1",
+        valuekind: "json",
+        now,
+      }),
+    ).toThrow(/json/i);
+    const valid = postentry({
+      board: board(),
+      id: "e1",
+      key: "rows",
+      value: "[1,2]",
+      section: "findings",
+      author: "a1",
+      valuekind: "json",
+      now,
+    });
+    expect(valid.entries[0]?.valuekind).toBe("json");
+  });
+
+  it("reads the entries of one section with the freshness filter", () => {
+    let state = postentry({
+      board: board(),
+      id: "e1",
+      key: "goal",
+      value: "Extract the pricing",
+      section: "goals",
+      author: "user",
+      now,
+    });
+    state = postentry({
+      board: state,
+      id: "e2",
+      key: "fact",
+      value: "The table has 40 rows",
+      section: "facts",
+      author: "a1",
+      now: now + 1_000,
+    });
+    state = postentry({
+      board: state,
+      id: "e3",
+      key: "late",
+      value: "Found the totals",
+      section: "findings",
+      author: "a2",
+      now: now + 10_000,
+    });
+    expect(readentries({ board: state, now: now + 20_000 })).toHaveLength(3);
+    expect(readentries({ board: state, section: "facts", now: now + 20_000 }).map((entry) => entry.key)).toEqual([
+      "fact",
+    ]);
+    const fresh = readentries({ board: state, now: now + 20_000, freshness: 11_000 });
+    expect(fresh.map((entry) => entry.key)).toEqual(["late"]);
+    expect(entryfresh(state.entries[0]!, now + 20_000, 5_000)).toBe(false);
+    expect(entryfresh(state.entries[0]!, now + 20_000, 15_000)).toBe(true);
+    expect(entryfresh(state.entries[0]!, now + 20_000)).toBe(true);
+  });
+});
+
+describe("blackboard retirement", () => {
+  it("retires the stale entries by the user configured window and never without one", () => {
+    let state = postentry({
+      board: board({ retirementwindow: 10_000 }),
+      id: "e1",
+      key: "old",
+      value: "Stale fact",
+      section: "facts",
+      author: "a1",
+      now,
+    });
+    state = postentry({
+      board: state,
+      id: "e2",
+      key: "new",
+      value: "Fresh fact",
+      section: "facts",
+      author: "a1",
+      now: now + 15_000,
+    });
+    const outcome = retireentries({ board: state, now: now + 20_000 });
+    expect(outcome.retired).toEqual(["e1"]);
+    expect(outcome.board.entries.find((entry) => entry.id === "e1")?.retiredat).toBe(now + 20_000);
+    expect(readentries({ board: outcome.board, now: now + 20_000 }).map((entry) => entry.id)).toEqual(["e2"]);
+    const kept = retireentries({ board: board(), now: now + 100_000 });
+    expect(kept.retired).toEqual([]);
+  });
+
+  it("retires one entry by its id while the stored entry stays for the audit trail", () => {
+    let state = postentry({
+      board: board(),
+      id: "e1",
+      key: "scratch.note",
+      value: "Try the second page",
+      section: "scratch",
+      author: "a1",
+      now,
+    });
+    state = retireentry({ board: state, entryid: "e1", now: now + 1_000 });
+    expect(state.entries[0]?.retiredat).toBe(now + 1_000);
+    expect(readentries({ board: state, now: now + 2_000 })).toHaveLength(0);
+    expect(() => retireentry({ board: state, entryid: "e1", now: now + 3_000 })).toThrow(/already retired/i);
+    expect(() => retireentry({ board: state, entryid: "missing", now })).toThrow(/does not exist/i);
+  });
+});
+
+describe("blackboard cross agent visibility and consent", () => {
+  it("makes the writes of one agent visible to every agent of the swarm", () => {
+    let state = postentry({
+      board: board(),
+      id: "e1",
+      key: "goal",
+      value: "Extract the pricing",
+      section: "goals",
+      author: "a1",
+      now,
+    });
+    state = postentry({
+      board: state,
+      id: "e2",
+      key: "finding",
+      value: "The table paginates",
+      section: "findings",
+      author: "a2",
+      now: now + 1,
+    });
+    const readera = readentries({ board: state, now });
+    const readerb = readentries({ board: state, now });
+    expect(readera).toEqual(readerb);
+    expect(readera.map((entry) => entry.author)).toEqual(["a2", "a1"]);
+  });
+
+  it("inherits the consent class of the source extraction into the entry", () => {
+    const posted = postentry({
+      board: board(),
+      id: "e1",
+      key: "form.values",
+      value: "The form carried the address",
+      section: "findings",
+      author: "a1",
+      consentclass: "sensitive",
+      now,
+    });
+    expect(posted.entries[0]?.consentclass).toBe("sensitive");
+    const inherited = inheritconsent(posted.entries[0]!, "interaction");
+    expect(inherited.consentclass).toBe("interaction");
+    expect(posted.entries[0]?.consentclass).toBe("sensitive");
+  });
+
+  it("summarizes the sections with the authors and the freshest posting time", () => {
+    let state = postentry({
+      board: board(),
+      id: "e1",
+      key: "goal",
+      value: "Extract",
+      section: "goals",
+      author: "user",
+      now,
+    });
+    state = postentry({
+      board: state,
+      id: "e2",
+      key: "fact",
+      value: "40 rows",
+      section: "facts",
+      author: "a1",
+      now: now + 1_000,
+    });
+    const summary = boardsummary(state, now + 2_000);
+    expect(summary.find((section) => section.section === "goals")).toMatchObject({
+      entries: 1,
+      authors: ["user"],
+      freshestat: now,
+    });
+    expect(summary.find((section) => section.section === "facts")?.authors).toEqual(["a1"]);
+    expect(summary.find((section) => section.section === "scratch")).toMatchObject({ entries: 0, authors: [] });
+  });
+});