onbuzz 4.7.2 → 4.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "4.7.2",
+  "version": "4.8.0",
   "description": "Loxia OnBuzz - Your AI Fleet",
   "type": "module",
   "main": "src/index.js",

package/scripts/grounding-bench/bench.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/**
+ * Grounding-model benchmark harness.
+ *
+ * Runs every adapter × every reasoning-effort × every case (N trials)
+ * and aggregates accuracy, latency, token usage, and cost. Outputs:
+ *
+ *   - human-readable table on stdout
+ *   - machine-readable JSON file at --out (default: bench-results-<ts>.json)
+ *
+ * Usage:
+ *   FOUNDRY_ENDPOINT=https://...services.ai.azure.com/ \
+ *   FOUNDRY_KEY=<key> \
+ *     node scripts/grounding-bench/bench.mjs \
+ *       --model kimi-k2.6 \
+ *       --effort none,low,medium,high \
+ *       --trials 3 \
+ *       --case all \
+ *       --out bench-$(date +%Y%m%d-%H%M).json
+ *
+ *   # Dry run against the mock (no spend, validates wiring):
+ *     node scripts/grounding-bench/bench.mjs --model mock --effort low --trials 2
+ *
+ * The bench script is the ONLY consumer of the grounding subsystem
+ * for Phase 0. Same imports the future DesktopTool will use — proves
+ * the surface from day 1.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { performance } from 'node:perf_hooks';
+
+import {
+  createGroundingModel,
+  isRegistered,
+  REASONING_EFFORT_VALUES,
+  ModelId,
+  ErrorCode,
+  parseCoords,
+  distance,
+  pointInRect,
+  summarise,
+} from '../../src/services/grounding/index.js';
+import { buildScreenshot, buttonCenter } from './imageBuilder.js';
+import { CASES } from './cases.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT  = resolve(__dirname, '..', '..');
+
+const DEFAULT_TRIALS = 3;
+const DEFAULT_MODEL_ID = ModelId.KIMI_K2_6;
+
+// ─── argv parsing (no `commander` dep — keep this script self-contained) ────
+
+function parseArgs(argv) {
+  const args = {
+    model:   DEFAULT_MODEL_ID,
+    effort:  ['low'],
+    trials:  DEFAULT_TRIALS,
+    cases:   'all',
+    out:     null,
+  };
+  for (let i = 2; i < argv.length; i += 2) {
+    const flag = argv[i];
+    const val  = argv[i + 1];
+    switch (flag) {
+      case '--model':  args.model = val; break;
+      case '--effort': args.effort = val.split(',').map(s => s.trim()).filter(Boolean); break;
+      case '--trials': args.trials = parseInt(val, 10); break;
+      case '--case':
+      case '--cases':  args.cases = val; break;
+      case '--out':    args.out = val; break;
+      case '--help':
+      case '-h':       printHelpAndExit(0);
+      default:
+        console.error(`unknown flag: ${flag}`);
+        printHelpAndExit(1);
+    }
+  }
+  return args;
+}
+
+function printHelpAndExit(code) {
+  console.log(`grounding bench — usage:
+  node scripts/grounding-bench/bench.mjs [--model id] [--effort csv] [--trials N] [--case id|all] [--out path]
+
+  --model    grounding model id (default: ${DEFAULT_MODEL_ID}; also: ${ModelId.MOCK})
+  --effort   comma-separated reasoning_effort values to sweep
+             (any of: ${REASONING_EFFORT_VALUES.join(', ')})
+  --trials   trials per (model, effort, case) cell — default ${DEFAULT_TRIALS}
+  --case     case id from cases.js, or "all" — default all
+  --out      results JSON path — default ./bench-results-<ts>.json
+
+  ENV (required when --model is not 'mock'):
+    FOUNDRY_ENDPOINT  https://<account>.services.ai.azure.com/
+    FOUNDRY_KEY       Foundry account key
+`);
+  process.exit(code);
+}
+
+// ─── adapter construction ────────────────────────────────────────────
+
+function makeAdapter(modelId) {
+  if (!isRegistered(modelId)) {
+    console.error(`unknown model id: ${modelId}`);
+    process.exit(2);
+  }
+  if (modelId === ModelId.MOCK) {
+    // Mock returns a stable wrong-but-near coord — useful for verifying
+    // the runner machinery without API spend.
+    return createGroundingModel(modelId, {
+      responses: {},
+      latencyMs: 50,
+      tokens: 100,
+    });
+  }
+  const endpoint = process.env.FOUNDRY_ENDPOINT;
+  const apiKey   = process.env.FOUNDRY_KEY;
+  if (!endpoint || !apiKey) {
+    console.error('FOUNDRY_ENDPOINT and FOUNDRY_KEY env vars are required for live model runs');
+    process.exit(3);
+  }
+  return createGroundingModel(modelId, { endpoint, apiKey });
+}
+
+// ─── trial execution ─────────────────────────────────────────────────
+
+async function runOneTrial({ adapter, kase, effort }) {
+  const target = kase.buttons.find(b => b.id === kase.target_button_id);
+  if (!target) throw new Error(`case ${kase.id}: no target_button_id ${kase.target_button_id}`);
+
+  const screenshot = await buildScreenshot({
+    width: kase.width, height: kase.height, buttons: kase.buttons,
+  });
+
+  const intent = kase.intent_template(target);
+  const truthCenter = buttonCenter(target);
+
+  const t0 = performance.now();
+  let result;
+  let errorCode = null;
+  try {
+    result = await adapter.ground({
+      screenshot,
+      intent,
+      imageSize: { width: kase.width, height: kase.height },
+      knobs: { reasoning_effort: effort },
+    });
+  } catch (err) {
+    errorCode = err.code || ErrorCode.PROVIDER_ERROR;
+    const elapsedMs = performance.now() - t0;
+    return { hit: false, err: null, elapsedMs, tokens: 0, errorCode, pred: null, truthCenter };
+  }
+  const elapsedMs = performance.now() - t0;
+
+  // Prefer coords parsed by the adapter; fall back to a raw-answer reparse
+  // in case the adapter implementation changes in the future.
+  const pred = result.coords || parseCoords(result.answer);
+  const hit  = pred ? pointInRect(pred, target.rect) : false;
+  const err  = pred ? distance(pred, truthCenter) : null;
+  const tokens = (result.usage?.input_tokens || 0) + (result.usage?.output_tokens || 0);
+
+  return { hit, err, elapsedMs, tokens, errorCode: null, pred, truthCenter };
+}
+
+// ─── orchestration ───────────────────────────────────────────────────
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const adapter = makeAdapter(args.model);
+
+  const selectedCases = args.cases === 'all'
+    ? CASES.slice()
+    : CASES.filter(c => c.id === args.cases);
+  if (selectedCases.length === 0) {
+    console.error(`no cases matched "${args.cases}". Available: ${CASES.map(c => c.id).join(', ')}`);
+    process.exit(4);
+  }
+
+  // Validate efforts up-front against the adapter so failures surface early.
+  validateEfforts(args.effort);
+
+  printHeader(args, selectedCases);
+
+  /** @type {Array<{model: string, effort: string, caseId: string, trials: any[]}>} */
+  const cells = [];
+
+  for (const effort of args.effort) {
+    for (const kase of selectedCases) {
+      const trials = [];
+      for (let t = 0; t < args.trials; t++) {
+        const trial = await runOneTrial({ adapter, kase, effort });
+        trials.push(trial);
+        process.stdout.write(formatTrialLine({ effort, kase, t, trial }));
+      }
+      cells.push({ model: args.model, effort, caseId: kase.id, trials });
+      printCellSummary({ effort, kase, trials });
+    }
+  }
+
+  await writeReport(cells, args);
+}
+
+// ─── presentation helpers ────────────────────────────────────────────
+
+function validateEfforts(efforts) {
+  for (const e of efforts) {
+    if (!REASONING_EFFORT_VALUES.includes(e)) {
+      console.error(`unknown effort "${e}". Valid: ${REASONING_EFFORT_VALUES.join(', ')}`);
+      process.exit(5);
+    }
+  }
+}
+
+function printHeader(args, cases) {
+  console.log('───────────────────────────────────────────────────────────────────────');
+  console.log(`Grounding bench`);
+  console.log(`  model:   ${args.model}`);
+  console.log(`  efforts: ${args.effort.join(', ')}`);
+  console.log(`  trials:  ${args.trials} per cell`);
+  console.log(`  cases:   ${cases.map(c => c.id).join(', ')}`);
+  console.log('───────────────────────────────────────────────────────────────────────');
+}
+
+function formatTrialLine({ effort, kase, t, trial }) {
+  const status = trial.errorCode
+    ? `ERR(${trial.errorCode})`
+    : trial.hit ? 'HIT' : 'MISS';
+  const errStr = trial.err == null ? '  --  ' : `${trial.err.toFixed(0).padStart(4)}px`;
+  return `  [${effort.padEnd(6)}|${kase.id.padEnd(28)}|#${t}] ` +
+         `${status.padEnd(12)} err=${errStr} ${trial.elapsedMs.toFixed(0).padStart(5)}ms tok=${String(trial.tokens).padStart(5)}\n`;
+}
+
+function printCellSummary({ effort, kase, trials }) {
+  const s = summarise(trials);
+  const hitsPct = (s.hitRate * 100).toFixed(0).padStart(3);
+  console.log(`  ──> [${effort.padEnd(6)}|${kase.id.padEnd(28)}]  ${hitsPct}% hit  ` +
+              `mean err ${s.meanErrPx.toFixed(0).padStart(4)}px  ` +
+              `p50 ${(s.p50LatencyMs / 1000).toFixed(1)}s  ` +
+              `p95 ${(s.p95LatencyMs / 1000).toFixed(1)}s  ` +
+              `mean tok ${s.meanTokens.toFixed(0)}\n`);
+}
+
+async function writeReport(cells, args) {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const outPath = args.out
+    ? resolve(args.out)
+    : join(REPO_ROOT, `bench-results-${ts}.json`);
+
+  // Aggregate at multiple grouping levels for easy downstream analysis.
+  const report = {
+    runAt: new Date().toISOString(),
+    args,
+    cells: cells.map(c => ({ ...c, summary: summarise(c.trials) })),
+    byEffort: groupAndSummarise(cells, c => c.effort),
+    byCase:   groupAndSummarise(cells, c => c.caseId),
+  };
+
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, JSON.stringify(report, null, 2), 'utf8');
+
+  console.log('───────────────────────────────────────────────────────────────────────');
+  console.log('Aggregate summaries\n');
+  console.log('By effort:');
+  for (const e of report.byEffort) printAggLine(e);
+  console.log('\nBy case:');
+  for (const c of report.byCase) printAggLine(c);
+  console.log(`\nFull report: ${outPath}`);
+}
+
+function groupAndSummarise(cells, keyFn) {
+  const groups = new Map();
+  for (const c of cells) {
+    const key = keyFn(c);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(...c.trials);
+  }
+  return [...groups.entries()].map(([key, trials]) => ({
+    key, ...summarise(trials),
+  }));
+}
+
+function printAggLine({ key, n, hitRate, meanErrPx, p50LatencyMs, p95LatencyMs, meanTokens }) {
+  console.log(
+    `  ${key.padEnd(30)} n=${String(n).padStart(3)}  ` +
+    `hit=${(hitRate * 100).toFixed(0).padStart(3)}%  ` +
+    `err=${meanErrPx.toFixed(0).padStart(4)}px  ` +
+    `p50=${(p50LatencyMs / 1000).toFixed(1)}s  p95=${(p95LatencyMs / 1000).toFixed(1)}s  ` +
+    `tok=${meanTokens.toFixed(0)}`
+  );
+}
+
+// ─── go ──────────────────────────────────────────────────────────────
+
+main().catch(err => {
+  console.error('\nBench failed:', err.code || '', err.message);
+  if (process.env.DEBUG) console.error(err.stack);
+  process.exit(1);
+});

package/scripts/grounding-bench/cases.js

@@ -0,0 +1,173 @@
+/**
+ * Benchmark case definitions.
+ *
+ * Each case is a deterministic synthetic UI + an `intent` string +
+ * the ground-truth target button id. The bench runs every adapter ×
+ * every knob combo × every case (N trials) and aggregates.
+ *
+ * Add new cases here. The bench reflects them automatically.
+ *
+ * Design notes:
+ *   - Cases are GRADED: easy (one big button), medium (a few buttons
+ *     with a description hint), hard (dense grid + small target).
+ *   - Colours are picked to be distinct so the model can ground by
+ *     colour as well as position — separates "find object" failures
+ *     from "ground coords" failures.
+ *   - Positions are chosen to exercise corners, edges, centre, and
+ *     to span both major axes.
+ *
+ * @typedef {import('./imageBuilder.js').ButtonSpec} ButtonSpec
+ * @typedef {{
+ *   id: string,
+ *   description: string,
+ *   width: number,
+ *   height: number,
+ *   buttons: ButtonSpec[],
+ *   target_button_id: string,
+ *   intent_template: (target: ButtonSpec) => string,
+ *   difficulty: 'easy'|'medium'|'hard',
+ * }} BenchCase
+ */
+
+// Standard resolutions worth measuring; named for reuse.
+const RES = Object.freeze({
+  HD_720P:  { width: 1280, height: 720 },
+  FHD_1080P: { width: 1920, height: 1080 },
+  SMALL:    { width:  400, height: 300 },
+});
+
+// Reusable colour palette. RGB triplets, distinct + reasonably accessible.
+const COLOR = Object.freeze({
+  BLUE:        [60, 130, 240],
+  GREEN:       [60, 180,  90],
+  RED:         [220, 60,  60],
+  ORANGE:      [255, 140,  0],
+  LIGHT_GRAY:  [230, 230, 230],
+  DARK_GRAY:   [80,   80,  80],
+  YELLOW:      [240, 200,  40],
+  PURPLE:      [150, 80, 200],
+});
+
+/** @type {BenchCase[]} */
+export const CASES = Object.freeze([
+
+  // ─── Easy: small canvas, single big centered button ───────────────
+  {
+    id: 'easy-centered-button',
+    description: 'Single red button in the centre of a 400x300 canvas',
+    ...RES.SMALL,
+    buttons: [
+      { id: 'btn-go', rect: { x: 150, y: 125, width: 100, height: 50 }, color: COLOR.RED },
+    ],
+    target_button_id: 'btn-go',
+    intent_template: () => 'Find the red button and respond with its pixel center as: x=<int>, y=<int>',
+    difficulty: 'easy',
+  },
+
+  // ─── Medium: 720p dialog with 4 distinct-colour buttons + hint ────
+  {
+    id: 'medium-dialog-4-buttons',
+    description: '720p dialog with 4 colour-distinct buttons; intent names the target by colour',
+    ...RES.HD_720P,
+    buttons: [
+      { id: 'ok',      rect: { x: 560, y: 480, width: 160, height: 50 }, color: COLOR.BLUE },
+      { id: 'cancel',  rect: { x: 380, y: 480, width: 160, height: 50 }, color: COLOR.LIGHT_GRAY },
+      { id: 'save_as', rect: { x: 740, y: 480, width: 160, height: 50 }, color: COLOR.GREEN },
+      { id: 'delete',  rect: { x: 1100, y:  50, width: 140, height: 40 }, color: COLOR.RED },
+    ],
+    target_button_id: 'delete',
+    intent_template: (target) =>
+      `There are 4 buttons (blue=OK, light-gray=Cancel, green=Save As, red=Delete). ` +
+      `Click the ${target.id.toUpperCase()} button. Respond with its pixel center as: x=<int>, y=<int>`,
+    difficulty: 'medium',
+  },
+
+  // ─── Hard: 1080p with a small button among many distractors ──────
+  {
+    id: 'hard-1080p-grid-distractor',
+    description: '1080p with a 4x3 grid of distractor buttons and one small orange target in the bottom-right',
+    ...RES.FHD_1080P,
+    // 4x3 grid of alternating blue/light-gray buttons at the centre…
+    buttons: [
+      ...gridButtons({
+        startX: 300, startY: 350,
+        cols: 4, rows: 3,
+        buttonWidth: 200, buttonHeight: 50,
+        gapX: 50, gapY: 20,
+        colors: [COLOR.BLUE, COLOR.LIGHT_GRAY],
+      }),
+      // …and one tiny orange target in the bottom-right.
+      { id: 'submit', rect: { x: 1700, y: 980, width: 160, height: 40 }, color: COLOR.ORANGE },
+    ],
+    target_button_id: 'submit',
+    intent_template: () =>
+      'Find the small ORANGE button and respond with its pixel center as: x=<int>, y=<int>',
+    difficulty: 'hard',
+  },
+
+  // ─── Hard: 1080p, corner buttons (test edge-of-screen grounding) ──
+  {
+    id: 'hard-1080p-corner-yellow',
+    description: '1080p with one small yellow button in the top-left corner; otherwise empty',
+    ...RES.FHD_1080P,
+    buttons: [
+      { id: 'home', rect: { x: 40, y: 40, width: 120, height: 40 }, color: COLOR.YELLOW },
+      // Distractor far away so the model can't just "blob detect"
+      { id: 'noise', rect: { x: 1700, y: 980, width: 100, height: 30 }, color: COLOR.DARK_GRAY },
+    ],
+    target_button_id: 'home',
+    intent_template: () =>
+      'Click the YELLOW button. Respond with its pixel center as: x=<int>, y=<int>',
+    difficulty: 'hard',
+  },
+
+  // ─── Medium: 720p, position-only description (no colour hint) ────
+  {
+    id: 'medium-position-only',
+    description: '720p with 3 buttons of the same colour; intent only describes position',
+    ...RES.HD_720P,
+    buttons: [
+      { id: 'top',    rect: { x: 540, y:  60, width: 200, height: 60 }, color: COLOR.PURPLE },
+      { id: 'middle', rect: { x: 540, y: 330, width: 200, height: 60 }, color: COLOR.PURPLE },
+      { id: 'bottom', rect: { x: 540, y: 600, width: 200, height: 60 }, color: COLOR.PURPLE },
+    ],
+    target_button_id: 'middle',
+    intent_template: () =>
+      'There are three identical purple buttons stacked vertically (top, middle, bottom). ' +
+      'Click the MIDDLE one. Respond with its pixel center as: x=<int>, y=<int>',
+    difficulty: 'medium',
+  },
+]);
+
+// ── helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Generate a 2-D grid of distractor buttons. Used by hard cases.
+ *
+ * @param {Object} opts
+ * @param {number} opts.startX, opts.startY
+ * @param {number} opts.cols, opts.rows
+ * @param {number} opts.buttonWidth, opts.buttonHeight
+ * @param {number} opts.gapX, opts.gapY
+ * @param {[number,number,number][]} opts.colors    - cycled
+ * @returns {ButtonSpec[]}
+ */
+function gridButtons({ startX, startY, cols, rows, buttonWidth, buttonHeight, gapX, gapY, colors }) {
+  /** @type {ButtonSpec[]} */
+  const out = [];
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      out.push({
+        id: `grid-${r}-${c}`,
+        rect: {
+          x: startX + c * (buttonWidth + gapX),
+          y: startY + r * (buttonHeight + gapY),
+          width:  buttonWidth,
+          height: buttonHeight,
+        },
+        color: colors[(r + c) % colors.length],
+      });
+    }
+  }
+  return out;
+}

package/scripts/grounding-bench/imageBuilder.js

@@ -0,0 +1,119 @@
+/**
+ * Synthetic-screenshot builder for the grounding bench.
+ *
+ * Generates deterministic PNGs of fake desktop UIs (buttons, dialogs,
+ * grids) with KNOWN button bounds. The bench scores adapter accuracy
+ * against these known truths.
+ *
+ * Why not use real screenshots: ground-truth coords for real screens
+ * change with theme, DPI, OS rendering. Synthetic images are reproducible
+ * across CI / dev / production, and the bench numbers are comparable
+ * over time.
+ *
+ * Why `sharp` (already in Loxia's deps): it can synthesize raw images
+ * from a buffer + composite primitives in pure Node, no native canvas
+ * library required.
+ *
+ * @typedef {{ x: number, y: number, width: number, height: number }} Rect
+ * @typedef {{
+ *   id: string,
+ *   rect: Rect,
+ *   color: [number, number, number],
+ *   label?: string,
+ * }} ButtonSpec
+ */
+
+import sharp from 'sharp';
+
+/** Default canvas background — light gray, like most OSes' window chrome. */
+const DEFAULT_BACKGROUND = { r: 245, g: 245, b: 247 };
+
+/** Channel count for the raw RGB buffer sharp consumes. */
+const RGB_CHANNELS = 3;
+
+/**
+ * Build a single-frame synthetic UI screenshot.
+ *
+ * @param {Object} spec
+ * @param {number}        spec.width
+ * @param {number}        spec.height
+ * @param {ButtonSpec[]}  spec.buttons
+ * @param {{r:number,g:number,b:number}} [spec.background]
+ * @returns {Promise<Buffer>} PNG buffer
+ */
+export async function buildScreenshot({ width, height, buttons, background = DEFAULT_BACKGROUND }) {
+  validateDimensions(width, height);
+  validateButtons(buttons, width, height);
+
+  // Start with a solid background canvas.
+  const base = sharp({
+    create: { width, height, channels: RGB_CHANNELS, background },
+  });
+
+  // Each button → a solid-colour overlay rectangle composited at its
+  // known position. Sharp accepts an array of overlays in one call;
+  // we batch for performance.
+  const overlays = buttons.map(b => ({
+    input: rectBuffer(b.rect.width, b.rect.height, b.color),
+    raw: { width: b.rect.width, height: b.rect.height, channels: RGB_CHANNELS },
+    top:  b.rect.y,
+    left: b.rect.x,
+  }));
+
+  return base.composite(overlays).png().toBuffer();
+}
+
+/** True center of a button — used by the bench to score predictions. */
+export function buttonCenter(button) {
+  return {
+    x: button.rect.x + Math.floor(button.rect.width / 2),
+    y: button.rect.y + Math.floor(button.rect.height / 2),
+  };
+}
+
+// ── helpers (private to this module) ────────────────────────────────
+
+/**
+ * Construct a raw RGB buffer for a solid-colour rectangle. sharp
+ * composites these onto the base canvas.
+ */
+function rectBuffer(width, height, [r, g, b]) {
+  const buf = Buffer.alloc(width * height * RGB_CHANNELS);
+  for (let i = 0; i < buf.length; i += RGB_CHANNELS) {
+    buf[i]     = r;
+    buf[i + 1] = g;
+    buf[i + 2] = b;
+  }
+  return buf;
+}
+
+function validateDimensions(w, h) {
+  if (!Number.isInteger(w) || !Number.isInteger(h) || w < 1 || h < 1) {
+    throw new Error(`buildScreenshot: width/height must be positive integers, got ${w}x${h}`);
+  }
+}
+
+function validateButtons(buttons, canvasW, canvasH) {
+  if (!Array.isArray(buttons) || buttons.length === 0) {
+    throw new Error('buildScreenshot: at least one button is required');
+  }
+  buttons.forEach((b, i) => {
+    if (!b.id || typeof b.id !== 'string') {
+      throw new Error(`button[${i}]: id (string) is required`);
+    }
+    if (!b.rect || !b.color) {
+      throw new Error(`button[${i}]: rect and color are required`);
+    }
+    const { x, y, width: w, height: h } = b.rect;
+    if (!Number.isInteger(x) || !Number.isInteger(y) ||
+        !Number.isInteger(w) || !Number.isInteger(h) ||
+        w < 1 || h < 1 || x < 0 || y < 0 ||
+        x + w > canvasW || y + h > canvasH) {
+      throw new Error(`button[${i}] (${b.id}): rect ${JSON.stringify(b.rect)} out of canvas ${canvasW}x${canvasH}`);
+    }
+    if (!Array.isArray(b.color) || b.color.length !== 3 ||
+        !b.color.every(c => Number.isInteger(c) && c >= 0 && c <= 255)) {
+      throw new Error(`button[${i}] (${b.id}): color must be [r,g,b] ints in 0..255`);
+    }
+  });
+}

package/src/core/__tests__/agentScheduler.test.js

@@ -657,6 +657,80 @@ describe('AgentScheduler', () => {
       await scheduler.stopAgentExecution('agent-abort');
       expect(scheduler.aiService.abortRequest).toHaveBeenCalledWith('agent-abort');
     });
+
+    // ─── REGRESSION: stop-mid-flight wedge ─────────────────────────────
+    // Background: in production a user's agent was found stuck with
+    //   activity = { active:false, reason:'stop-requested' }
+    //   stopRequested = true (in memory + persisted)
+    //   mode = chat (transition flipped, then…)
+    // …and the scheduler skipping it every cycle forever. Root cause:
+    // stopAgentExecution set stopRequested=true BEFORE awaiting
+    // _transitionMode and only cleared it AFTER. If the await threw or
+    // the process restarted between the two, the flag was never cleared
+    // and persisted state carried the wedge across reboots — a one-way
+    // trap for the agent's schedulability.
+    //
+    // These tests lock the invariant: stopRequested MUST always end at
+    // false after stopAgentExecution returns, whether _transitionMode
+    // succeeded, threw a sync error, or rejected asynchronously. The
+    // cleared state must also be persisted before the function returns.
+
+    test('clears stopRequested even when _transitionMode throws synchronously', async () => {
+      const agent = makeAgent({ id: 'wedge-sync', mode: 'agent' });
+      agentPool.getAgent.mockResolvedValue(agent);
+      // Inject a transition that throws synchronously inside the await.
+      scheduler._transitionMode = jest.fn(() => {
+        throw new Error('boom-sync');
+      });
+
+      // We don't care if stopAgentExecution itself throws — what matters
+      // is that the flag is cleared regardless. Catch and assert state.
+      await scheduler.stopAgentExecution('wedge-sync').catch(() => {});
+
+      expect(agent.stopRequested).toBe(false);
+      // Persisted at least once after the clear so a process crash
+      // immediately after this point can't re-wedge on reload.
+      expect(agentPool.persistAgentState).toHaveBeenCalledWith('wedge-sync');
+    });
+
+    test('clears stopRequested even when _transitionMode rejects asynchronously', async () => {
+      const agent = makeAgent({ id: 'wedge-async', mode: 'agent' });
+      agentPool.getAgent.mockResolvedValue(agent);
+      scheduler._transitionMode = jest.fn().mockRejectedValue(new Error('ws-broadcast-hung'));
+
+      await scheduler.stopAgentExecution('wedge-async').catch(() => {});
+
+      expect(agent.stopRequested).toBe(false);
+      expect(agentPool.persistAgentState).toHaveBeenCalledWith('wedge-async');
+    });
+
+    test('clears stopRequested on the happy path too (no regression)', async () => {
+      const agent = makeAgent({ id: 'happy', mode: 'agent' });
+      agentPool.getAgent.mockResolvedValue(agent);
+      // The default _transitionMode on the real scheduler does I/O we
+      // don't want here; stub a no-op success.
+      scheduler._transitionMode = jest.fn().mockResolvedValue(undefined);
+
+      const result = await scheduler.stopAgentExecution('happy');
+      expect(result.success).toBe(true);
+      expect(agent.stopRequested).toBe(false);
+    });
+
+    test('a persist failure during recovery does NOT re-throw or leave flag set', async () => {
+      // Even when both the transition AND the recovery persist fail, the
+      // in-memory flag MUST end up cleared. The recovery persist failure
+      // is logged but suppressed (the in-memory clear is what the next
+      // scheduler cycle reads, and the next normal persist will save it).
+      const agent = makeAgent({ id: 'wedge-double-fail', mode: 'agent' });
+      agentPool.getAgent.mockResolvedValue(agent);
+      scheduler._transitionMode = jest.fn().mockRejectedValue(new Error('transition-failed'));
+      // Persist fails too.
+      agentPool.persistAgentState.mockRejectedValueOnce(new Error('disk-full'));
+
+      await scheduler.stopAgentExecution('wedge-double-fail').catch(() => {});
+
+      expect(agent.stopRequested).toBe(false);
+    });
   });
 
   // ─── isAgentInScheduler ───────────────────────────────────────────────