@ludi-uni/ludi-agent-kit 0.1.0

package/tests/activity.test.mjs

@@ -0,0 +1,252 @@
+// Public run-activity snapshots: atomic client file, live invocation events, and the
+// significant-vs-high-frequency trace policy. All stubs — no pi process, no provider calls.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, existsSync, readFileSync, renameSync, readdirSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { DEFAULT_POLICY } from '../lib/orchestrator/policy.mjs';
+import { openStore } from '../lib/orchestrator/store.mjs';
+import { orchestrate } from '../lib/orchestrator/orchestrator.mjs';
+import { createAgentRunner } from '../lib/orchestrator/runner.mjs';
+import { runPiSubagent } from '../adapters/pi/lib/subagent.mjs';
+import { createActivityTracker, activityFileName, readActivitySnapshot, sanitizeInvocationEvent, publishActivitySnapshot } from '../lib/orchestrator/activity.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const routing = loadRouting(join(kit, 'routing/routing.json'));
+const { agents } = loadAgents(join(kit, 'agents'), routing);
+const REG = { version: 1, backends: { local: { provider: 'pl', model: 'ml', thinking: 'off' } } };
+const spec = (id, agent, dependencies = []) => ({ id, title: `task ${id}`, goal: `goal ${id}`, agent, dependencies, acceptance: ['done'] });
+const completed = (task) => ({ ok: true, structured: true, modelId: 'fake', result: {
+  status: 'completed', summary: `did ${task.id}`, artifacts: [], verification: ['checked'],
+  acceptance: [{ id: 'A1', met: true, evidence: 'observed' }], remainingIssues: [], decisions: [], newTasks: [] } });
+const tmpKit = () => mkdtempSync(join(tmpdir(), 'ludi-activity-'));
+
+test('snapshot file is written atomically on bind and carries version+clientContext', () => {
+  const dir = tmpKit();
+  const activity = createActivityTracker({ kit: dir, clientContext: { kind: 'pi-web', sessionId: 'abc-123' } });
+  activity.bindRun({ runId: 'run-1', repoRoot: '/repo' });
+  const file = join(dir, '.orchestration', 'activity', 'clients', 'pi-web-abc-123.json');
+  assert.equal(activityFileName({ kind: 'pi-web', sessionId: 'abc-123' }), 'pi-web-abc-123.json');
+  assert.equal(activity.file, file);
+  const doc = readActivitySnapshot(file);
+  assert.equal(doc.version, 1);
+  assert.deepEqual(doc.clientContext, { kind: 'pi-web', sessionId: 'abc-123' });
+  assert.equal(doc.runId, 'run-1');
+  assert.equal(doc.repoRoot, '/repo');
+  assert.equal(doc.activity.runId, 'run-1');
+  assert.equal(doc.activity.state, 'running');
+});
+
+test('Windows sharing violation retries atomic replacement and keeps the prior document readable', () => {
+  const dir = tmpKit(), file = join(dir, 'snapshot.json');
+  publishActivitySnapshot(file, { runId: 'old' });
+  let attempts = 0;
+  const waits = [];
+  publishActivitySnapshot(file, { runId: 'new' }, { windows: true, wait: ms => waits.push(ms), rename: (src, dest) => {
+    attempts++;
+    if (attempts < 3) {
+      assert.equal(readActivitySnapshot(dest).runId, 'old');
+      throw Object.assign(new Error('locked by reader'), { code: 'EPERM' });
+    }
+    renameSync(src, dest);
+  } });
+  assert.equal(readActivitySnapshot(file).runId, 'new');
+  assert.deepEqual(waits, [10, 20]);
+  assert.deepEqual(readdirSync(dir), ['snapshot.json']);
+});
+
+test('persistent snapshot failure does not fail a persisted run or strand temporary files', () => {
+  const dir = tmpKit();
+  const activity = createActivityTracker({ kit: dir, clientContext: { kind: 'pi-web', sessionId: 'locked' } });
+  mkdirSync(activity.file, { recursive: true }); // a directory at the destination makes replacement impossible
+  const warnings = [], originalWarn = console.warn;
+  try {
+    console.warn = message => warnings.push(message);
+    assert.doesNotThrow(() => activity.bindRun({ runId: 'run-1', repoRoot: dir }));
+    assert.equal(activity.getRunActivity('run-1').runId, 'run-1');
+    assert.equal(warnings.length, 1);
+    assert.deepEqual(readdirSync(dirname(activity.file)).filter(name => name.endsWith('.tmp')), []);
+  } finally { console.warn = originalWarn; }
+  rmSync(activity.file, { recursive: true });
+  activity.syncTasks({ runId: 'run-1', tasks: [] });
+  assert.equal(readActivitySnapshot(activity.file).runId, 'run-1');
+});
+
+test('orchestrator still completes and persists when its optional snapshot is locked', async () => {
+  const dir = tmpKit(), session = openStore(join(dir, 'state.db'));
+  const activity = createActivityTracker({ kit: dir, clientContext: { kind: 'pi-web', sessionId: 'busy-reader' } });
+  mkdirSync(activity.file, { recursive: true });
+  const originalWarn = console.warn;
+  try {
+    console.warn = () => {};
+    const result = await orchestrate({ request: 'fixture', plan: [spec('t1', 'scout')], agents, routing, registry: REG,
+      policy: DEFAULT_POLICY, runner: { run: async task => completed(task) }, session, activity, repoRoot: dir });
+    assert.equal(result.status, 'completed');
+    assert.equal(session.getRun(result.runId).status, 'completed');
+  } finally { console.warn = originalWarn; session.close(); }
+});
+
+test('live invocation events update activeInvocations keyed runId+taskId+invocationId', () => {
+  const activity = createActivityTracker({ kit: tmpKit(), clientContext: { kind: 'pi-web', sessionId: 's1' } });
+  activity.bindRun({ runId: 'r1', repoRoot: null });
+  activity.emit('invocation-start', { runId: 'r1', taskId: 't1', invocationId: 'i1', agent: 'coder', modelId: 'm1' });
+  activity.emit('invocation-start', { runId: 'r1', taskId: 't1', invocationId: 'i2', agent: 'coder', modelId: 'm2' });
+  let a = activity.getRunActivity('r1');
+  assert.equal(a.activeInvocations.length, 2);
+  activity.emit('invocation-turn', { runId: 'r1', taskId: 't1', invocationId: 'i1', turn: 3, turnCap: 12 });
+  activity.emit('invocation-end', { runId: 'r1', taskId: 't1', invocationId: 'i1', status: 'finished' });
+  a = activity.getRunActivity('r1');
+  assert.equal(a.activeInvocations.length, 1);
+  assert.equal(a.activeInvocations[0].invocationId, 'i2');
+});
+
+test('subscribeRunActivity notifies and getRunActivityByClient resolves the bound run', () => {
+  const activity = createActivityTracker({ kit: tmpKit(), clientContext: { kind: 'pi-web', sessionId: 'sess' } });
+  const seen = [];
+  activity.subscribeRunActivity('rX', a => seen.push(a));
+  activity.bindRun({ runId: 'rX', repoRoot: '/r' });
+  activity.syncTasks({ runId: 'rX', tasks: [{ id: 't1', title: 'x', assignedAgent: 'coder', status: 'running', attempts: 1 }] });
+  assert.ok(seen.length >= 2);
+  const byClient = activity.getRunActivityByClient('pi-web', 'sess');
+  assert.equal(byClient.runId, 'rX');
+  assert.equal(byClient.totalTasks, 1);
+  assert.equal(byClient.activeAgents, 1);
+  const restarted = createActivityTracker({ kit: activity.file.split('.orchestration')[0], clientContext: { kind: 'pi-web', sessionId: 'sess' } });
+  assert.equal(restarted.getRunActivityByClient('pi-web', 'sess')?.runId, 'rX');
+  assert.equal(activity.getRunActivityByClient('pi-web', 'other'), null);
+});
+
+test('orchestrate emits significant invocation events to trace but not high-frequency turns', async () => {
+  const dir = tmpKit();
+  const session = openStore(join(dir, 'state.db'));
+  const activity = createActivityTracker({ kit: dir, clientContext: { kind: 'pi-web', sessionId: 'z9' } });
+  const runner = { async run(t, ctx) {
+    ctx.onEvent?.('invocation-start', { taskId: t.id, invocationId: 'i1', agent: 'coder', modelId: 'm' });
+    ctx.onEvent?.('invocation-turn', { taskId: t.id, invocationId: 'i1', turn: 1 });
+    ctx.onEvent?.('invocation-tool', { taskId: t.id, invocationId: 'i1', tool: { name: 'read', file: 'a.mjs' } });
+    ctx.onEvent?.('invocation-end', { taskId: t.id, invocationId: 'i1', status: 'finished' });
+    return completed(t);
+  } };
+  const r = await orchestrate({
+    request: 'do', plan: [spec('a', 'coder')], agents, routing, registry: REG,
+    policy: DEFAULT_POLICY, session, runner, activity,
+  });
+  assert.equal(r.status, 'completed');
+  const types = session.loadTrace(r.runId).map(e => e.type);
+  for (const k of ['invocation-start', 'invocation-tool', 'invocation-end']) assert.ok(types.includes(k), k);
+  assert.ok(!types.includes('invocation-turn'), 'turns must not persist to trace');
+  const doc = readActivitySnapshot(join(dir, '.orchestration', 'activity', 'clients', 'pi-web-z9.json'));
+  assert.equal(doc.runId, r.runId);
+  assert.equal(doc.activity.completedTasks, 1);
+  assert.equal(doc.activity.state, 'completed');
+  session.close();
+});
+
+test('parallel live progress, safe recent tools, extension and candidate change survive snapshots', () => {
+  const a = createActivityTracker({ kit: tmpKit(), clientContext: { kind: 'pi-web', sessionId: 'session-a' } });
+  a.bindRun({ runId: 'r', repoRoot: '/repo-a' });
+  a.syncTasks({ runId: 'r', tasks: [{ id: 't1', status: 'running' }, { id: 't2', status: 'running' }] });
+  a.emit('invocation-start', { runId: 'r', taskId: 't1', invocationId: 'i1', agent: 'scout', modelId: 'qoder/Qwen' });
+  a.emit('invocation-start', { runId: 'r', taskId: 't2', invocationId: 'i2', agent: 'scout', modelId: 'freetoken/Free' });
+  a.emit('invocation-turn', { runId: 'r', taskId: 't1', invocationId: 'i1', turn: 8, turnCap: 24, toolCalls: 7 });
+  a.emit('invocation-tool', { runId: 'r', taskId: 't1', invocationId: 'i1', tool: { name: 'read', file: 'D:/repo/src/app.js', args: 'SECRET' } });
+  a.emit('invocation-extension', { runId: 'r', taskId: 't1', invocationId: 'i1', oldLimit: 24, newLimit: 32 });
+  a.emit('candidate-changed', { runId: 'r', taskId: 't2', invocationId: 'i2', fromModel: 'qoder/Qwen', toModel: 'freetoken/Free', reason: 'MALFORMED_RESULT' });
+  const live = a.getRunActivity('r');
+  assert.equal(live.activeAgents, 2);
+  assert.equal(live.activeInvocations.find(i => i.invocationId === 'i1').turnLimit, 32);
+  assert.equal(live.activeInvocations.find(i => i.invocationId === 'i1').turnsUsed, 8);
+  assert.equal(live.activeInvocations.find(i => i.invocationId === 'i1').toolCalls, 7);
+  assert.deepEqual(live.activeInvocations.find(i => i.invocationId === 'i1').recentTools, [{ tool: 'read', summary: 'app.js' }]);
+  assert.equal(live.activeInvocations.find(i => i.invocationId === 'i2').toModel, 'freetoken/Free');
+  a.syncTasks({ runId: 'r', tasks: [{ id: 't1', status: 'running' }, { id: 't2', status: 'running' }] });
+  assert.equal(a.getRunActivity('r').tasks.find(t => t.taskId === 't2').fallbackTo, 'freetoken/Free');
+  a.emit('fallback', { runId: 'r', taskId: 't2', from: 'cheap-code', to: 'strong-code' });
+  assert.equal(a.getRunActivity('r').tasks.find(t => t.taskId === 't2').capability, 'strong-code');
+  assert.equal(createActivityTracker({ kit: tmpKit(), clientContext: { kind: 'pi-web', sessionId: 'session-b' } }).getRunActivityByClient('pi-web', 'session-b'), null);
+  a.emit('invocation-end', { runId: 'r', taskId: 't1', invocationId: 'i1', status: 'finished' });
+  assert.equal(a.getRunActivity('r').activeInvocations.length, 1);
+  a.syncTasks({ runId: 'r', tasks: [{ id: 't1', status: 'completed' }, { id: 't2', status: 'running' }] });
+  assert.equal(a.getRunActivity('r').completedTasks, 1);
+  a.finishRun('r');
+  assert.equal(a.getRunActivity('r').activeInvocations.length, 0);
+});
+
+test('stub E2E: binding appears at send, model/tool/turn update before completion, unrelated session stays hidden', async () => {
+  const dir = tmpKit();
+  const session = openStore(join(dir, 'state.db'));
+  const activity = createActivityTracker({ kit: dir, clientContext: { kind: 'pi-web', sessionId: 'owner-uuid' } });
+  const started = Promise.withResolvers();
+  const release = Promise.withResolvers();
+  const runner = createAgentRunner({ agents, routing, registry: { version: 1, backends: { qoder: { provider: 'qoder', model: 'Qwen3.8-Flash', thinking: 'low' } } }, repoRoot: dir,
+    invoke: async () => { throw new Error('unexpected oneshot'); },
+    runSubagent: async req => {
+      req.onEvent('invocation-turn', { turn: 8, turnCap: 24, toolCalls: 7 });
+      req.onEvent('invocation-tool', { tool: { name: 'read', file: join(dir, 'src', 'small.js') } });
+      started.resolve(req.modelId);
+      await release.promise;
+      return { ok: true, text: '```json\n{"status":"completed","summary":"done","acceptance":[{"id":"A1","met":true,"evidence":"checked"}]}\n```', child: { turns: 8, toolCalls: 7 } };
+    },
+  });
+  const running = orchestrate({ request: 'small read-only fixture', plan: [spec('t1', 'scout')], agents, routing,
+    registry: { version: 1, backends: { qoder: { provider: 'qoder', model: 'Qwen3.8-Flash', thinking: 'low' } } }, policy: DEFAULT_POLICY, runner, session, activity, repoRoot: dir });
+  const modelId = await started.promise;
+  const id = session.listRuns()[0].id;
+  const bound = readActivitySnapshot(activity.file);
+  assert.equal(bound.runId, id);
+  assert.equal(bound.activity.state, 'running');
+  assert.equal(bound.activity.activeInvocations[0].modelId, modelId);
+  assert.equal(bound.activity.activeInvocations[0].turnsUsed, 8);
+  assert.equal(bound.activity.activeInvocations[0].turnLimit, 24);
+  assert.deepEqual(bound.activity.activeInvocations[0].recentTools, [{ tool: 'read', summary: 'small.js' }]);
+  const other = createActivityTracker({ kit: dir, clientContext: { kind: 'pi-web', sessionId: 'other-uuid' } });
+  assert.equal(other.getRunActivityByClient('pi-web', 'other-uuid'), null);
+  release.resolve();
+  const result = await running;
+  assert.equal(result.status, 'completed');
+  assert.equal(readActivitySnapshot(activity.file).activity.activeInvocations.length, 0);
+  assert.equal(readActivitySnapshot(activity.file).activity.completedTasks, 1);
+  session.close();
+});
+
+test('pi JSON tool/turn events propagate while child is still running', async () => {
+  const observed = [];
+  const spawnImpl = () => {
+    const proc = new EventEmitter();
+    proc.stdout = new PassThrough(); proc.stderr = new PassThrough(); proc.kill = () => {};
+    setImmediate(() => {
+      proc.stdout.write(JSON.stringify({ type: 'tool_execution_start', toolCallId: 'c1', toolName: 'read', args: { path: 'src/a.js', secret: 'HIDDEN' } }) + '\n');
+      proc.stdout.write(JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'toolCall', name: 'read', arguments: { path: 'src/a.js' } }] } }) + '\n');
+      proc.stdout.write(JSON.stringify({ type: 'tool_execution_end', toolCallId: 'c1', toolName: 'read', result: { text: 'HIDDEN' } }) + '\n');
+      proc.stdout.write(JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'done' }] } }) + '\n');
+      proc.emit('close', 0);
+    });
+    return proc;
+  };
+  const result = await runPiSubagent({ modelId: 'stub/model', cwd: tmpKit(), toolNames: ['read'], prompt: 'fixture', limits: { max_turns: 8 }, onEvent: (type, data) => observed.push({ type, data }) }, { piEntry: 'fake-cli', spawnImpl });
+  assert.equal(result.ok, true);
+  assert.ok(observed.some(e => e.type === 'invocation-tool' && e.data.tool.name === 'read'));
+  assert.ok(observed.some(e => e.type === 'invocation-tool-completed'));
+  assert.ok(observed.some(e => e.type === 'invocation-turn' && e.data.turn === 2 && e.data.toolCalls === 1));
+  assert.ok(!JSON.stringify(observed).includes('HIDDEN'));
+});
+
+test('sanitizeInvocationEvent drops payload details and bounds strings', () => {
+  const e = sanitizeInvocationEvent('invocation-tool', {
+    runId: 'r', taskId: 't', invocationId: 'i',
+    tool: { name: 'exec', file: 'x.mjs', arguments: { command: 'rm -rf /' } },
+    raw: 'SECRET', prompt: 'PROMPT', text: 'OUTPUT',
+  });
+  assert.equal(e.tool.name, 'exec');
+  assert.equal(e.tool.file, 'x.mjs');
+  assert.equal(e.tool.arguments, undefined);
+  assert.equal(e.raw, undefined);
+  assert.equal(e.prompt, undefined);
+  assert.equal(e.text, undefined);
+});

package/tests/attempt-budget.test.mjs

@@ -0,0 +1,102 @@
+// Attempt-budget and candidate-progression regressions for run-muf7i8e2-48e3c7.
+// Only ACTUAL invocations consume max_total_attempts_per_task — health skips,
+// unavailable candidates, already-tried skips and enumeration do not.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { DEFAULT_POLICY, mergePolicy } from '../lib/orchestrator/policy.mjs';
+import { createAgentRunner } from '../lib/orchestrator/runner.mjs';
+import { orchestrate } from '../lib/orchestrator/orchestrator.mjs';
+import { createScriptedInvoker } from '../adapters/pi/lib/invoke.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const routing = loadRouting(join(kit, 'routing/routing.json'));
+const { agents } = loadAgents(join(kit, 'agents'), routing);
+// cheap-code: cheap(pc/mc) -> local(pl/ml) -> sol(ps/ms); strong-code adds codex(px/mx).
+const REG = { version: 1, backends: {
+  local: { provider: 'pl', model: 'ml', thinking: 'off' },
+  cheap: { provider: 'pc', model: 'mc', thinking: 'low' },
+  sol:   { provider: 'ps', model: 'ms', thinking: 'high' },
+  codex: { provider: 'px', model: 'mx', thinking: 'high' },
+} };
+const policyWith = over => mergePolicy(DEFAULT_POLICY, over ?? {});
+const jsonReply = obj => `notes\n\n\`\`\`json\n${JSON.stringify(obj)}\n\`\`\``;
+const okReply = jsonReply({ status: 'completed', summary: 'done', acceptance: [{ id: 'A1', met: true, evidence: 'e' }] });
+const spec = (id, agent, dependencies = [], extra = {}) => ({ id, title: `task ${id}`, goal: `goal ${id}`, agent, dependencies, acceptance: ['done'], ...extra });
+
+// Health monitor stub: skip returns a reason for the listed modelIds (no invocation).
+const healthSkip = (skipIds) => ({ skip: c => (skipIds.includes(c.modelId) ? 'usage_exhausted until later' : null), report() {} });
+
+// Run one scout task with a scripted invoker; runner gets the SAME resolved policy
+// so the invocations budget is enforced inside withEscalation.
+async function runScenario(script, { policy: over = {}, health = null } = {}) {
+  const policy = policyWith(over);
+  const calls = [];
+  const invoke = createScriptedInvoker(script, calls);
+  const runner = createAgentRunner({ invoke, agents, routing, registry: REG, policy, health });
+  const r = await orchestrate({ request: 'r', plan: [spec('a', 'scout')], agents, routing, registry: REG, policy, runner });
+  return { r, calls };
+}
+
+// A: protocol failure on Qwen consumes 1 invocation; a health-skipped candidate consumes 0.
+test('A: health-skipped candidate does not consume the attempt budget', async () => {
+  const { r, calls } = await runScenario({ '*': req => req.modelId.startsWith('pc/') ? 'Done' : okReply }, { health: healthSkip(['pl/ml:off']) });
+  assert.equal(r.status, 'completed');
+  assert.deepEqual(calls.map(c => c.modelId), ['pc/mc:low', 'ps/ms:high']); // pl/ml skipped, never invoked
+  const resultEvent = r.trace.find(e => e.type === 'result');
+  assert.equal(resultEvent.counters.candidatesSkipped >= 1, true);
+});
+
+// B: after a protocol failure the NEXT untried candidate (FreeToken/local) is invocable.
+test('B: protocol failure advances to the next untried candidate', async () => {
+  const { r, calls } = await runScenario({ '*': req => req.modelId.startsWith('pc/') ? 'Done' : okReply });
+  assert.equal(r.status, 'completed');
+  assert.deepEqual(calls.map(c => c.modelId), ['pc/mc:low', 'pl/ml:off']);
+});
+
+// C: cheap-code exhausted -> strong-code escalation -> first eligible candidate runs.
+test('C: escalation to strong-code re-resolves candidates (codex reachable)', async () => {
+  const { r, calls } = await runScenario({ '*': req => req.modelId.startsWith('px/') ? okReply : 'Done' }, { policy: { limits: { max_retries: 4, model_attempts_per_task: 3, max_total_attempts_per_task: 8 } } });
+  assert.equal(r.status, 'completed');
+  assert.ok(calls.some(c => c.modelId === 'px/mx:high'), 'reached strong-code-only candidate');
+});
+
+// D: two health-skipped candidates consume zero budget.
+test('D: skipped candidates do not increment invocationsStarted', async () => {
+  const { r, calls } = await runScenario({ '*': req => req.modelId.startsWith('ps/') ? okReply : 'Done' }, { health: healthSkip(['pl/ml:off']) });
+  assert.equal(r.status, 'completed');
+  assert.deepEqual(calls.map(c => c.modelId), ['pc/mc:low', 'ps/ms:high']); // only 2 real invocations
+});
+
+// E: budget counts real invocations; the N+1th real invoke is never started.
+test('E: max_total_attempts_per_task stops before the N+1th real invocation', async () => {
+  const { r, calls } = await runScenario({ '*': () => 'Done' }, { policy: { limits: { max_retries: 6, model_attempts_per_task: 3, max_total_attempts_per_task: 4 } } });
+  assert.equal(r.tasks[0].status, 'failed');
+  assert.ok(calls.length <= 4, `real invocations ${calls.length} exceeded budget 4`);
+});
+
+// F: considered > invoked -> budget display uses invocationsStarted.
+test('F: budget reflects invocationsStarted, not candidatesConsidered', async () => {
+  const { r } = await runScenario({ '*': req => req.modelId.startsWith('pc/') ? 'Done' : okReply }, { health: healthSkip(['pl/ml:off', 'ps/ms:high']) });
+  const resultEvent = r.trace.find(e => e.type === 'result');
+  assert.equal(resultEvent.counters.invocationsStarted, 1);
+  assert.ok(resultEvent.counters.candidatesConsidered >= resultEvent.counters.invocationsStarted);
+});
+
+// G: a model tried on cheap-code may be already-tried on strong-code, but a fresh
+//    strong-code-only candidate (codex) is NOT wrongly excluded.
+test('G: escalation resets attemptedModels so new-capability candidates run', async () => {
+  const { r, calls } = await runScenario({ '*': req => req.modelId.startsWith('px/') ? okReply : 'Done' }, { policy: { limits: { max_retries: 4, model_attempts_per_task: 3, max_total_attempts_per_task: 8 } } });
+  assert.equal(r.status, 'completed');
+  assert.ok(calls.filter(c => c.modelId === 'px/mx:high').length >= 1, 'codex invoked after escalation');
+});
+
+// H: candidate identity is per-modelId — failing one model never marks a different
+//    provider's model as tried.
+test('H: candidate identity is per modelId, not per provider/backend', async () => {
+  const { calls } = await runScenario({ '*': req => req.modelId.startsWith('pc/') ? 'Done' : okReply });
+  assert.ok(calls.some(c => c.modelId === 'pl/ml:off'), 'pl/ml invoked despite pc/mc failure');
+});

package/tests/browser.test.mjs

@@ -0,0 +1,121 @@
+// Browser capability: routing resolution, agent binding, wrapper command construction,
+// action classification, failure normalization, and argv integrity (no shell mangling).
+// These tests never launch a real browser; the opt-in real E2E is tests/e2e-browser.mjs.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { resolveCapability, resolveAgents } from '../lib/resolve.mjs';
+import { COMMANDS, ACTION_KINDS, classify, buildArgs, runBrowser, locateAgentBrowser } from '../adapters/pi/browser/agent-browser.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const routing = loadRouting(join(kit, 'routing/routing.json'));
+const { agents, errors } = loadAgents(join(kit, 'agents'), routing);
+
+const REG = { version: 1, backends: {
+  sol:   { provider: 'ps', model: 'ms', thinking: 'high' },
+  codex: { provider: 'px', model: 'mx', thinking: 'high' },
+} };
+
+// ---------- capability resolution ----------
+test('browser capability resolves through routing like any other', () => {
+  const r = resolveCapability(routing, REG, 'browser');
+  assert.equal(r.capability, 'browser');
+  assert.deepEqual(r.chain, ['sol', 'codex']);
+  assert.deepEqual(r.candidates.map(c => c.modelId), ['ps/ms:high', 'px/mx:high']);
+  assert.deepEqual(r.unbound, []);
+});
+
+test('browser agent binds to the browser capability and never names a model', () => {
+  assert.deepEqual(errors, []);
+  const browser = agents.find(a => a.meta.name === 'browser');
+  assert.ok(browser, 'agents/browser.md must exist');
+  assert.equal(browser.meta.capability, 'browser');
+  assert.equal(browser.meta.model, undefined);
+  assert.equal(browser.meta.provider, undefined);
+  const resolved = resolveAgents(agents, routing, REG);
+  assert.equal(resolved.browser.capability, 'browser');
+  assert.equal(resolved.browser.candidates[0].backend, 'sol');
+});
+
+// ---------- command construction ----------
+test('buildArgs produces the documented agent-browser argv', () => {
+  assert.deepEqual(buildArgs('open', { url: 'https://example.com' }), ['open', 'https://example.com']);
+  assert.deepEqual(buildArgs('navigate', { url: 'https://example.com' }), ['open', 'https://example.com']);
+  assert.deepEqual(buildArgs('snapshot'), ['snapshot', '-i']);
+  assert.deepEqual(buildArgs('snapshot', { interactive: false, compact: true, depth: 3 }), ['snapshot', '-c', '-d', '3']);
+  assert.deepEqual(buildArgs('click', { ref: '@e2' }), ['click', '@e2']);
+  assert.deepEqual(buildArgs('fill', { ref: '@e3', text: 'hello' }), ['fill', '@e3', 'hello']);
+  assert.deepEqual(buildArgs('press', { key: 'Enter' }), ['press', 'Enter']);
+  assert.deepEqual(buildArgs('getText', { ref: '@e1' }), ['get', 'text', '@e1']);
+  assert.deepEqual(buildArgs('getValue', { ref: '@e3' }), ['get', 'value', '@e3']);
+  assert.deepEqual(buildArgs('getUrl'), ['get', 'url']);
+  assert.deepEqual(buildArgs('isVisible', { ref: '@e4' }), ['is', 'visible', '@e4']);
+  assert.deepEqual(buildArgs('wait', { ms: 500 }), ['wait', '500']);
+  assert.deepEqual(buildArgs('wait', { ref: '#done' }), ['wait', '#done']);
+  assert.deepEqual(buildArgs('screenshot', { path: 'p.png', annotate: true }), ['screenshot', 'p.png', '--annotate']);
+  assert.deepEqual(buildArgs('close'), ['close']);
+});
+
+test('unknown commands are rejected before spawn', () => {
+  assert.throws(() => buildArgs('deleteEverything'), /unknown command/);
+  assert.equal(classify('deleteEverything'), null);
+});
+
+// ---------- action classification (metadata for a future approval policy) ----------
+test('every command has a safety kind and the kinds match the agreed tiers', () => {
+  for (const [name, spec] of Object.entries(COMMANDS)) {
+    assert.ok(ACTION_KINDS.includes(spec.kind), `${name} kind ${spec.kind}`);
+  }
+  for (const c of ['open', 'snapshot', 'getText', 'getValue', 'getUrl', 'getTitle', 'isVisible', 'isChecked', 'wait', 'screenshot']) {
+    // open navigates (state change) but is trivially reversible -> low-risk, not read-only
+    if (c === 'open') assert.equal(classify(c), 'low-risk');
+    else assert.equal(classify(c), 'read-only', c);
+  }
+  for (const c of ['click', 'navigate', 'hover', 'scroll', 'close']) assert.equal(classify(c), 'low-risk', c);
+  for (const c of ['fill', 'type', 'press', 'select', 'check', 'uncheck']) assert.equal(classify(c), 'write', c);
+  for (const c of ['eval', 'submit']) assert.equal(classify(c), 'high-impact', c);
+});
+
+// ---------- argv integrity: no shell, values with spaces/quotes stay one arg ----------
+test('argv round-trip: spaces, quotes and Windows paths survive without a shell', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ludi-ab-argv-'));
+  const echo = join(dir, 'echo.mjs');
+  writeFileSync(echo, 'console.log(JSON.stringify(process.argv.slice(2)))');
+  const env = { ...process.env, LUDI_AGENT_BROWSER_ENTRY: echo };
+  const url = 'file:///D:/my folder/page "one".html';
+  const r = await runBrowser('open', { url }, { env, session: 's1' });
+  assert.equal(r.ok, true, r.error ?? r.stderr);
+  assert.deepEqual(JSON.parse(r.stdout.trim()), ['--session', 's1', 'open', url]);
+});
+
+// ---------- failure normalization ----------
+test('nonzero exit becomes {ok:false,error} without throwing', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ludi-ab-fail-'));
+  const fail = join(dir, 'fail.mjs');
+  writeFileSync(fail, 'console.error("boom: no such ref"); process.exit(3)');
+  const env = { ...process.env, LUDI_AGENT_BROWSER_ENTRY: fail };
+  const r = await runBrowser('click', { ref: '@e99' }, { env });
+  assert.equal(r.ok, false);
+  assert.equal(r.status, 3);
+  assert.match(r.error, /exit 3/);
+  assert.match(r.stderr, /boom: no such ref/);
+  assert.equal(r.kind, 'low-risk'); // classification survives failures
+});
+
+test('missing binary throws a clear install error', () => {
+  const env = { ...process.env, PATH: '', Path: '', LUDI_AGENT_BROWSER_ENTRY: '', LUDI_AGENT_BROWSER_BIN: '' };
+  assert.equal(locateAgentBrowser(env), null);
+  assert.throws(() => runBrowser('snapshot', {}, { env }), /agent-browser not found/);
+});
+
+// ---------- real binary presence (informational; not a browser launch) ----------
+test('installed agent-browser binary is locatable on this machine', () => {
+  const located = locateAgentBrowser();
+  assert.ok(located, 'agent-browser should be installed for the browser capability');
+  assert.ok(['js', 'bin'].includes(located.kind));
+});

package/tests/context-pack.test.mjs

@@ -0,0 +1,98 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseContextPackMarkdown, validateContextPack, loadContextPack, toMarkdown, REQUIRED_FIELDS } from '../lib/context-pack.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const example = resolve(kit, 'context-pack/examples/example-fix.md');
+const schema = JSON.parse(readFileSync(resolve(kit, 'context-pack/context-pack.schema.json'), 'utf8'));
+
+test('schema file parses and lists the same required fields as the validator', () => {
+  assert.deepEqual([...schema.required].sort(), [...REQUIRED_FIELDS].sort());
+  for (const f of ['task', 'goal', 'constraints', 'relevant_files', 'relevant_snippets', 'repo_rules', 'observed_errors', 'test_commands', 'previous_attempts', 'expected_output']) {
+    assert.ok(schema.properties[f], `schema missing ${f}`);
+  }
+});
+
+test('example markdown parses, validates and round-trips', () => {
+  const pack = loadContextPack(example);
+  assert.equal(pack.task, 'Fix crash when saving an empty project');
+  assert.deepEqual(pack.relevant_files[0], { path: 'src/save.ts', lines: '40-88', reason: 'serialization entry point' });
+  assert.equal(pack.relevant_snippets[0].language, 'ts');
+  assert.match(pack.relevant_snippets[0].content, /export function save/);
+  assert.match(pack.observed_errors[0], /TypeError/);
+  assert.deepEqual(pack.test_commands, ['npm test -- save']);
+  assert.deepEqual(pack.previous_attempts[0], { summary: 'Added a null check in `save()`', outcome: 'tests pass but empty file is still invalid.' });
+  const again = parseContextPackMarkdown(toMarkdown(pack));
+  assert.deepEqual(again, pack);
+});
+
+test('missing required sections are reported', () => {
+  const errs = validateContextPack(parseContextPackMarkdown('# Context Pack\n\n## task\nx\n'));
+  for (const f of ['goal', 'constraints', 'relevant_files', 'expected_output']) assert.ok(errs.some(e => e.includes(`"${f}"`)), f);
+});
+
+test('unknown and duplicate sections are rejected', () => {
+  assert.throws(() => parseContextPackMarkdown('# Context Pack\n## task\na\n## bogus\nb\n'), /unknown section/);
+  assert.throws(() => parseContextPackMarkdown('# Context Pack\n## task\na\n## task\nb\n'), /duplicate section/);
+  assert.throws(() => parseContextPackMarkdown('## task\na\n'), /missing "# Context Pack"/);
+});
+
+test('relevant_files must be non-empty, relative, with valid line ranges', () => {
+  const ok = { task: 't', goal: 'g', constraints: [], relevant_files: [{ path: 'a.ts' }], expected_output: 'e' };
+  assert.deepEqual(validateContextPack(ok), []);
+  assert.ok(validateContextPack({ ...ok, relevant_files: [] }).some(e => e.includes('at least one')));
+  assert.ok(validateContextPack({ ...ok, relevant_files: [{ path: 'C:\\Users\\someone\\a.ts' }] }).some(e => e.includes('repository-relative')));
+  assert.ok(validateContextPack({ ...ok, relevant_files: [{ path: 'a.ts', lines: '10' }] }).some(e => e.includes('start-end')));
+});
+
+test('unknown fields and bad metadata are rejected', () => {
+  const ok = { task: 't', goal: 'g', constraints: [], relevant_files: [{ path: 'a' }], expected_output: 'e' };
+  assert.ok(validateContextPack({ ...ok, extra: 1 }).some(e => e.includes('unknown field')));
+  assert.ok(validateContextPack({ ...ok, version: 2 }).some(e => e.includes('version')));
+  assert.ok(validateContextPack({ ...ok, capability: 'Bad' }).some(e => e.includes('capability')));
+  assert.ok(validateContextPack({ ...ok, budget: { max_tokens: 0 } }).some(e => e.includes('max_tokens')));
+  assert.deepEqual(validateContextPack({ ...ok, version: 1, capability: 'strong-code', budget: { max_tokens: 8000 } }), []);
+});
+
+test('v1.1: discovery.status=none permits empty relevant_files; create flag round-trips; v1.0 packs unchanged', () => {
+  const base = { task: 't', goal: 'g', constraints: [], relevant_files: [], expected_output: 'e' };
+  assert.ok(validateContextPack(base).some(e => e.includes('at least one')));
+  assert.deepEqual(validateContextPack({ ...base, discovery: { status: 'none', note: 'greenfield' } }), []);
+  assert.ok(validateContextPack({ ...base, discovery: { status: 'partial' } }).some(e => e.includes('at least one')));
+  assert.ok(validateContextPack({ ...base, discovery: { status: 'maybe' } }).some(e => e.includes('discovery.status')));
+  const withCreate = { ...base, relevant_files: [{ path: 'src/new.js', create: true, reason: 'new module' }, { path: 'a.js' }] };
+  assert.deepEqual(validateContextPack(withCreate), []);
+  const md = toMarkdown({ ...withCreate, discovery: { status: 'partial', note: 'only tests exist' } });
+  assert.match(md, /## discovery\npartial — only tests exist/);
+  assert.match(md, /- `src\/new.js` — \(new\) new module/);
+  const back = parseContextPackMarkdown(md);
+  assert.deepEqual(back.discovery, { status: 'partial', note: 'only tests exist' });
+  assert.deepEqual(back.relevant_files[0], { path: 'src/new.js', reason: 'new module', create: true });
+  assert.deepEqual(validateContextPack(loadContextPack(example)), []); // v1.0 example still valid
+  assert.equal(schema.properties.relevant_files.minItems, undefined);
+  assert.equal(schema.else.properties.relevant_files.minItems, 1);
+});
+
+test('lenient parsing accepts real scout output shapes; strict parsing does not', () => {
+  const loose = 'Preamble text.\n\n## task\nt\n## goal\ng\n## constraints\n- a\n  - nested detail\n## relevant_files\n- `src/math.js:1-12` — impl\n- `test/x.js:6`\n## relevant_snippets\n- `src/math.js:9-12`\n  ```js\n  code\n  ```\n## expected_output\ne\n';
+  assert.throws(() => parseContextPackMarkdown(loose), /missing "# Context Pack"/);
+  const p = parseContextPackMarkdown(loose, { lenient: true });
+  assert.deepEqual(p.constraints, ['a nested detail']);
+  assert.deepEqual(p.relevant_files, [{ path: 'src/math.js', lines: '1-12', reason: 'impl' }, { path: 'test/x.js', lines: '6-6' }]);
+  assert.equal(p.relevant_snippets[0].path, 'src/math.js');
+  assert.equal(p.relevant_snippets[0].lines, '9-12');
+  assert.equal(p.relevant_snippets[0].language, 'js');
+  assert.deepEqual(validateContextPack(p), []);
+  // Windows drive letters are not line refs
+  assert.equal(parseContextPackMarkdown('# Context Pack\n## relevant_files\n- `C:\\r\\a.js`\n', { lenient: true }).relevant_files[0].path, 'C:\\r\\a.js');
+});
+
+test('headings inside fenced code blocks do not start sections', () => {
+  const md = '# Context Pack\n## task\nt\n## goal\ng\n## constraints\n## relevant_files\n- `a.md`\n## observed_errors\n```\n## not a heading\n```\n## expected_output\ne\n';
+  const pack = parseContextPackMarkdown(md);
+  assert.deepEqual(pack.observed_errors, ['## not a heading']);
+  assert.deepEqual(validateContextPack(pack), []);
+});