lumniverse 0.3.0 → 0.4.0

package/assets/fleet/run.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// Run the fleet: twelve scenarios, one for each problem Lumni coordinates,
+// acted out by small agents that check with Lumni before they change anything.
+//
+//   node run.mjs                              every scenario, once
+//   node run.mjs --admin-key KEY              also the ones that need an admin key
+//   node run.mjs --scenario stale-reasoning   one scenario (comma-separate for more)
+//   node run.mjs --list                       what's here
+//   node run.mjs --rounds 3 | --forever       again and again (Ctrl-C to stop)
+//
+// Reads LUMNI_URL and LUMNI_API_KEY from the environment or ./.env (lumni init writes it).
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { LumniClient, guard, settings, shortId, sleep as wait, spend, why } from './lumni.mjs';
+import { createApps } from './apps.mjs';
+import { recordPriceVersion } from './scenarios/kit.mjs';
+import { scenario as s01 } from './scenarios/01-duplicate-effect.mjs';
+import { scenario as s02 } from './scenarios/02-stale-reasoning.mjs';
+import { scenario as s03 } from './scenarios/03-human-collision.mjs';
+import { scenario as s04 } from './scenarios/04-resource-contention.mjs';
+import { scenario as s05 } from './scenarios/05-cross-agent-conflict.mjs';
+import { scenario as s06 } from './scenarios/06-superseded-work.mjs';
+import { scenario as s07 } from './scenarios/07-duplicate-work.mjs';
+import { scenario as s08 } from './scenarios/08-dependency.mjs';
+import { scenario as s09 } from './scenarios/09-false-completion.mjs';
+import { scenario as s10 } from './scenarios/10-partial-completion.mjs';
+import { scenario as s11 } from './scenarios/11-cost-waste.mjs';
+import { scenario as s12 } from './scenarios/12-runaway-fleet.mjs';
+import { scenario as loop } from './scenarios/extra-retry-loop.mjs';
+import { scenario as approval } from './scenarios/extra-approval.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+export const SCENARIOS = [s01, s02, s03, s04, s05, s06, s07, s08, s09, s10, s11, s12, loop, approval];
+
+function args(argv) {
+  const o = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (!argv[i].startsWith('--')) continue;
+    const k = argv[i].slice(2);
+    if (argv[i + 1] && !argv[i + 1].startsWith('--')) o[k] = argv[++i];
+    else o[k] = true;
+  }
+  return o;
+}
+
+const tty = process.stdout.isTTY;
+const paint = (code, s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : s);
+const PALETTE = [99, 214, 39, 170, 76, 203, 45, 141, 208, 118];
+const colorOf = new Map();
+const tag = (actor) => {
+  if (!colorOf.has(actor)) colorOf.set(actor, PALETTE[colorOf.size % PALETTE.length]);
+  return paint(`38;5;${colorOf.get(actor)}`, actor.padEnd(18));
+};
+
+/** "WAIT:LEASE_BUSY" → "wait (another agent is working on it)". */
+const decisionWords = (s) => {
+  const [d, r] = s.split(':');
+  return `${d.replace(/^WOULD_/, '').toLowerCase().replace(/_/g, ' ')}${r ? ` (${why(r)})` : ''}`;
+};
+
+/** What happened in one scenario, from Lumni's decisions, its own notes and the apps' problems. */
+export function verdict(sc, seen, notes, problems) {
+  const real = [...seen].filter((s) => s !== 'ALLOW' && !s.startsWith('WOULD_'));
+  const would = [...seen].filter((s) => s.startsWith('WOULD_'));
+  const noted = notes.find((n) => n.kind === 'stepped-in' || n.kind === 'joined' || n.kind === 'noted');
+  let kind;
+  let text;
+  if (real.length) {
+    kind = 'stepped-in';
+    text = `Lumni stepped in: ${[...new Set(real.map(decisionWords))].join(', ')}`;
+  } else if (noted) {
+    kind = noted.kind;
+    text = noted.text;
+  } else if (would.length) {
+    kind = 'would-have';
+    text = `Watch-only, so it went ahead. Lumni would have said: ${[...new Set(would.map(decisionWords))].join(', ')}`;
+  } else {
+    kind = 'nothing';
+    text = notes.find((n) => n.kind === 'no-limit')?.text ?? 'Nothing for Lumni to do';
+  }
+  if (noted && real.length) text += `; ${noted.text}`;
+  if (problems.length) text += `. ${problems.length} ${problems.length === 1 ? 'problem' : 'problems'} in the apps`;
+  return { kind, text };
+}
+
+export async function main(argv, env = process.env, { fetchFn = fetch, log = console.log, sleep = wait, dir = here } = {}) {
+  const o = args(argv);
+  if (o.help) {
+    log('node run.mjs [--scenario a,b] [--admin-key KEY] [--rounds N | --forever] [--list]');
+    return 0;
+  }
+  if (o.list) {
+    for (const s of SCENARIOS) log(`${s.id.padEnd(22)} ${s.problem.padEnd(26)} ${s.story}${s.needsAdmin ? '  (needs --admin-key)' : ''}${s.onlyWhenAsked ? '  (only with --scenario)' : ''}`);
+    return 0;
+  }
+  const { url, key } = settings(env, dir);
+  if (!key) {
+    log('No Lumni key here. In the console, open Start, press Make a code, and run its command in this folder.');
+    log('Or set LUMNI_URL and LUMNI_API_KEY.');
+    return 1;
+  }
+  const lumni = new LumniClient(url, key, undefined, fetchFn);
+  try {
+    await lumni.request('GET', '/v1/actors?limit=1');
+  } catch (e) {
+    log(e.status === 401 || e.status === 403 ? `Lumni at ${url} doesn’t accept this key (${e.message}).` : `Lumni can’t be reached at ${url}: ${e.message}`);
+    return 1;
+  }
+  const admin = o['admin-key'] ? new LumniClient(url, String(o['admin-key']), undefined, fetchFn) : null;
+
+  const asked = typeof o.scenario === 'string' ? o.scenario.split(',').map((s) => s.trim()) : null;
+  const chosen = asked ? SCENARIOS.filter((s) => asked.includes(s.id)) : SCENARIOS.filter((s) => !s.onlyWhenAsked);
+  if (!chosen.length) {
+    log(`No scenario called ${o.scenario}. Run with --list to see them.`);
+    return 1;
+  }
+  const rounds = o.forever ? Infinity : Math.max(1, Math.min(100, Number(o.rounds ?? 1) || 1));
+  // The apps remember their price list between runs (state.json), as real ones would.
+  let kept = {};
+  try {
+    if (!o.fresh && existsSync(join(dir, 'state.json'))) kept = { priceList: JSON.parse(readFileSync(join(dir, 'state.json'), 'utf8')).salesforce?.priceList };
+  } catch {}
+  const apps = createApps(kept);
+
+  const actors = new Map();
+  for (const s of chosen) for (const a of s.actors) actors.set(a.id, a);
+  for (const a of actors.values()) {
+    await lumni.request('POST', '/v1/actors', { id: a.id, type: a.type ?? 'AGENT', display_name: a.name, runtime: a.type === 'HUMAN' ? undefined : 'node', metadata: { source: 'agent-fleet' } });
+  }
+  await recordPriceVersion(lumni, apps.salesforce.readPriceList());
+  const people = [...actors.values()].filter((a) => a.type === 'HUMAN').length;
+  log(`${actors.size - people} agents${people ? ` and ${people} ${people === 1 ? 'person' : 'people'}` : ''}, ${chosen.length} scenarios, checked by Lumni at ${url}.${admin ? '' : ' (No --admin-key: scenarios that need one are skipped.)'}`);
+
+  let stop = false;
+  const onStop = () => { stop = true; log('\nStopping after this scenario…'); };
+  if (o.forever) process.once('SIGINT', onStop);
+
+  const results = [];
+  for (let round = 0; round < rounds && !stop; round++) {
+    const runTag = shortId().slice(0, 4);
+    apps.resetCustomers();
+    if (rounds > 1) log(paint('1', `\n═══ Round ${round + 1}${rounds === Infinity ? '' : ` of ${rounds}`} ═══`));
+    for (const sc of chosen) {
+      if (stop) break;
+      log(`\n${paint('1', `▸ ${sc.problem}`)}  ${paint('2', sc.story)}`);
+      if (sc.needsAdmin && !admin) {
+        log(`  ${paint('2', 'Skipped: needs --admin-key (the checker posts evidence with the verification scope)')}`);
+        results.push({ sc, kind: 'skipped', text: 'Skipped: needs --admin-key' });
+        continue;
+      }
+      const seen = new Set();
+      const notes = [];
+      const before = apps.state.problems.length;
+      const say = (actor, text) => log(`  ${tag(actor)} ${text}`);
+      const ctx = {
+        lumni, admin, apps, say,
+        // Fresh ids each run, so a second run against the same Lumni tells the same story.
+        run: runTag,
+        note: (kind, text) => notes.push({ kind, text }),
+        spend: (x) => spend(lumni, x),
+        // Lumni identifies a change by its operation, target and arguments, so the same
+        // change in a later run would rightly be "already done". Each run's changes carry
+        // the run, the way real work carries a request or ticket id; repeats within a run
+        // are still repeats.
+        guard: (input, act, opts = {}) => guard(lumni, { ...input, arguments: { ...(input.arguments ?? {}), batch: runTag } }, act, { seen, ...opts, say: opts.quietWaits ? () => {} : (t) => say(input.actor_id, t) }),
+      };
+      try {
+        await sc.run.call(sc, ctx);
+      } catch (e) {
+        say('fleet', paint('31', `failed: ${e.message}`));
+        notes.push({ kind: 'noted', text: `Failed: ${e.message}` });
+      }
+      const problems = apps.state.problems.slice(before);
+      for (const p of problems) log(`  ${paint('31', '✗')} ${p.text}`);
+      const v = verdict(sc, seen, notes, problems);
+      log(`  ${v.kind === 'stepped-in' || v.kind === 'joined' ? paint('38;5;99', '●') : paint('2', '○')} ${v.text}`);
+      results.push({ sc, ...v, problems: problems.length });
+    }
+    if (round + 1 < rounds && !stop) await sleep(o.forever ? 20_000 : 3000);
+  }
+  process.off?.('SIGINT', onStop);
+
+  // The table, once per scenario (the last round's verdict).
+  const last = new Map(results.map((r) => [r.sc.id, r]));
+  log(paint('1', '\nCoverage'));
+  for (const r of last.values()) {
+    const mark = r.kind === 'stepped-in' || r.kind === 'joined' ? paint('38;5;99', '●') : r.kind === 'skipped' ? paint('2', '–') : paint('2', '○');
+    log(`  ${mark} ${r.sc.problem.padEnd(26)} ${r.text}`);
+  }
+  const all = apps.state.problems;
+  log(paint('1', `\nProblems in the apps: ${all.length ? all.length : 'none'}`));
+  for (const p of all) log(`  ${paint('31', '✗')} ${p.text}`);
+  if (!o['no-save']) {
+    apps.save(join(dir, 'state.json'));
+    log(paint('2', '\nEverything the apps saw is in state.json. The console shows Lumni’s side: Today, Needs you, Tower, Context, Runtime, Money.'));
+  }
+  return 0;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  main(process.argv.slice(2)).then((c) => process.exit(c), (e) => {
+    console.error(e.message);
+    process.exit(1);
+  });
+}

package/assets/fleet/scenarios/01-duplicate-effect.mjs

@@ -0,0 +1,39 @@
+// Duplicate effect: two agents refund the same payment.
+//
+// The refund agent refunds a disputed charge, Stripe times out, and it tries
+// again. Meanwhile the billing bot, working the same dispute from the finance
+// queue, refunds it too. Each refund names its effect ("refund this charge"),
+// so Lumni can tell all three are one refund and lets only the first through.
+
+import { shortId } from '../lumni.mjs';
+import { startWork } from './kit.mjs';
+
+export const scenario = {
+  id: 'duplicate-effect',
+  problem: 'Duplicate effect',
+  story: 'Two agents refund the same payment.',
+  expect: 'DEDUPLICATE',
+  actors: [{ id: 'refund-agent', name: 'Refund agent' }, { id: 'billing-bot', name: 'Billing bot' }],
+  async run({ lumni, apps, guard, say }) {
+    const charge = `ch_${shortId()}`;
+    const refund = (actor, work, key) => ({
+      work_id: work, actor_id: actor, operation: 'stripe.refund', risk: 'MEDIUM',
+      arguments: { charge, amount: 60 },
+      idempotency_key: key,
+      effect_key: `stripe.refund:${charge}`,
+      resources: [{ type: 'charge', namespace: 'stripe', external_id: charge, mode: 'WRITE' }],
+      metadata: { summary: `Refund $60 on ${charge}`, customer: 'Hooli' },
+    });
+    const w1 = await startWork(lumni, 'refund-agent', `Refund the disputed charge ${charge}`);
+    const key = `refund-agent:${charge}`;
+    if ((await guard(refund('refund-agent', w1, key), () => apps.stripe.refund({ charge, amount: 60, by: 'refund-agent', scenario: this.id }))).done) say('refund-agent', `Refunded $60 on ${charge}`);
+    say('refund-agent', 'Stripe timed out (pretend), so it tries the same refund again');
+    if ((await guard(refund('refund-agent', w1, key), () => apps.stripe.refund({ charge, amount: 60, by: 'refund-agent', scenario: this.id }))).done) say('refund-agent', 'Refunded it again');
+
+    const w2 = await startWork(lumni, 'billing-bot', `Resolve the dispute on ${charge}`);
+    say('billing-bot', `Working the same dispute from the finance queue: refunding ${charge}`);
+    if ((await guard(refund('billing-bot', w2, `billing-bot:${charge}`), () => apps.stripe.refund({ charge, amount: 60, by: 'billing-bot', scenario: this.id }))).done) say('billing-bot', 'Refunded it too');
+    await lumni.completeWork(w1).catch(() => {});
+    await lumni.completeWork(w2).catch(() => {});
+  },
+};

package/assets/fleet/scenarios/02-stale-reasoning.mjs

@@ -0,0 +1,70 @@
+// Stale reasoning: the agent decides on reality from a second ago.
+//
+// The price setter reads the Enterprise price list (v41, say), thinks, and
+// writes a 5% discount. While it thought, pricing sync copied the supplier's
+// new cost in (v42). Lumni sees it read an old version and sends it back.
+
+import { sleep } from '../lumni.mjs';
+import { usd } from '../apps.mjs';
+import { priceListWrite, recordPriceVersion, startWork } from './kit.mjs';
+
+export const scenario = {
+  id: 'stale-reasoning',
+  problem: 'Stale reasoning',
+  story: 'The agent decides using reality from a moment ago.',
+  expect: 'REPLAN',
+  actors: [{ id: 'price-setter', name: 'Price setter' }, { id: 'pricing-sync', name: 'Pricing sync' }],
+  async run(ctx) {
+    await Promise.all([discount(ctx, 'Hooli', this.id), supplierSync(ctx)]);
+  },
+};
+
+/** Also used by the human-collision scenario. */
+export async function discount({ lumni, apps, guard, say }, account, scenario) {
+  const work = await startWork(lumni, 'price-setter', `5% off for ${account}`);
+  const ask = (read) => {
+    const price = Math.round(read.seatPrice * 0.95 * 100) / 100;
+    return {
+      work_id: work, actor_id: 'price-setter', operation: 'salesforce.update_price', risk: 'MEDIUM',
+      arguments: { price_list: 'Enterprise', account, seat_price: price, change_pct: -5 },
+      resources: [priceListWrite(read)],
+      metadata: { summary: `5% off for ${account}: seat price ${usd(price)}`, customer: account },
+    };
+  };
+  let read = apps.salesforce.readPriceList();
+  say('price-setter', `Read the price list: ${usd(read.seatPrice)} (${read.version}). Thinking…`);
+  await sleep(1500);
+  const r = await guard(ask(read), async (d) => {
+    const price = Math.round(read.seatPrice * 0.95 * 100) / 100;
+    const after = await apps.salesforce.setSeatPrice(price, 'price-setter', read.version, scenario);
+    await recordPriceVersion(lumni, after, 'price-setter', d.action_id);
+    return after;
+  }, {
+    onReplan: async () => {
+      read = apps.salesforce.readPriceList();
+      say('price-setter', `Read it again: ${usd(read.seatPrice)} (${read.version})`);
+      return ask(read);
+    },
+  });
+  if (r.done) say('price-setter', `${account} gets ${usd(Math.round(read.seatPrice * 0.95 * 100) / 100)} a seat`);
+  await lumni.completeWork(work).catch(() => {});
+}
+
+async function supplierSync({ lumni, apps, guard, say }) {
+  const work = await startWork(lumni, 'pricing-sync', 'Copy supplier costs');
+  await sleep(500);
+  const read = apps.salesforce.readPriceList();
+  const next = read.seatPrice + 1;
+  const r = await guard({
+    work_id: work, actor_id: 'pricing-sync', operation: 'salesforce.update_price', risk: 'LOW',
+    arguments: { price_list: 'Enterprise', seat_price: next, change_pct: Math.round((1 / read.seatPrice) * 1000) / 10 },
+    resources: [priceListWrite(read)],
+    metadata: { summary: `Supplier cost: Enterprise seat price to ${usd(next)}` },
+  }, async (d) => {
+    const after = await apps.salesforce.setSeatPrice(next, 'pricing-sync', read.version);
+    await recordPriceVersion(lumni, after, 'pricing-sync', d.action_id);
+    return after;
+  });
+  if (r.done) say('pricing-sync', `Supplier cost changed: seat price is now ${usd(next)}`);
+  await lumni.completeWork(work).catch(() => {});
+}

package/assets/fleet/scenarios/03-human-collision.mjs

@@ -0,0 +1,30 @@
+// Human/agent collision: a person fixes something while an AI is still on it.
+//
+// Jess, in sales ops, corrects the Enterprise seat price in Salesforce by hand
+// while the price setter is thinking. Salesforce tells Lumni about the new
+// version, and the agent is sent back instead of writing over her fix.
+
+import { sleep } from '../lumni.mjs';
+import { usd } from '../apps.mjs';
+import { recordPriceVersion } from './kit.mjs';
+import { discount } from './02-stale-reasoning.mjs';
+
+export const scenario = {
+  id: 'human-collision',
+  problem: 'Human/agent collision',
+  story: 'A human fixes something while an AI is still trying to fix it.',
+  expect: 'REPLAN',
+  actors: [{ id: 'price-setter', name: 'Price setter' }, { id: 'jess', name: 'Jess Park', type: 'HUMAN' }],
+  async run(ctx) {
+    const jess = async () => {
+      await sleep(600);
+      const read = ctx.apps.salesforce.readPriceList();
+      const fixed = read.seatPrice + 3;
+      const after = await ctx.apps.salesforce.setSeatPrice(fixed, 'jess', read.version);
+      // Salesforce's webhook tells Lumni; no agent involved.
+      await recordPriceVersion(ctx.lumni, after, 'jess');
+      ctx.say('jess', `(a person) Corrected the seat price in Salesforce to ${usd(fixed)}`);
+    };
+    await Promise.all([discount(ctx, 'Initech', this.id), jess()]);
+  },
+};

package/assets/fleet/scenarios/04-resource-contention.mjs

@@ -0,0 +1,37 @@
+// Resource contention: five agents start editing the same account.
+//
+// The SDR bot, renewal bot, support agent, billing bot and enrichment bot all
+// update the Globex account in Salesforce at once. Lumni lets one in at a
+// time, so no edit is lost.
+
+import { startWork } from './kit.mjs';
+
+const EDITORS = [
+  ['sdr-bot', 'SDR bot', 'next_step', 'Book a demo'],
+  ['renewal-bot', 'Renewal bot', 'renewal_date', '2027-01-01'],
+  ['support-agent', 'Support agent', 'health', 'At risk'],
+  ['billing-bot', 'Billing bot', 'billing_email', 'ap@globex.example'],
+  ['enrich-bot', 'Enrichment bot', 'employees', '1,240'],
+];
+
+export const scenario = {
+  id: 'resource-contention',
+  problem: 'Resource contention',
+  story: 'Five agents start editing the same account.',
+  expect: 'WAIT',
+  actors: EDITORS.map(([id, name]) => ({ id, name })),
+  async run({ lumni, apps, guard, say }) {
+    await Promise.all(EDITORS.map(async ([actor, , field, value], i) => {
+      const work = await startWork(lumni, actor, `Update Globex: ${field}`);
+      await new Promise((r) => setTimeout(r, i * 40));
+      const r = await guard({
+        work_id: work, actor_id: actor, operation: 'salesforce.update_account', risk: 'LOW',
+        arguments: { account: 'Globex', field, value },
+        resources: [{ type: 'account', namespace: 'salesforce', external_id: 'globex', mode: 'WRITE' }],
+        metadata: { summary: `Globex ${field.replace(/_/g, ' ')}: ${value}`, customer: 'Globex' },
+      }, () => apps.salesforce.editAccount('Globex', field, value, actor, this.id));
+      if (r.done) say(actor, `Updated Globex ${field.replace(/_/g, ' ')}`);
+      await lumni.completeWork(work).catch(() => {});
+    }));
+  },
+};

package/assets/fleet/scenarios/05-cross-agent-conflict.mjs

@@ -0,0 +1,50 @@
+// Cross-agent conflict: two agents change the same customer differently.
+//
+// Umbrella asks to cancel. The churn agent starts cancelling their
+// subscription, and at the same moment the upsell agent tries to upgrade it.
+// Lumni makes the upgrade wait until the cancellation is done; the upsell
+// agent then sees the subscription is cancelled and drops the upgrade.
+
+import { sleep } from '../lumni.mjs';
+import { startWork } from './kit.mjs';
+
+const SUB = 'sub_umbrella';
+const subscription = { type: 'subscription', namespace: 'billing', external_id: SUB, mode: 'WRITE' };
+
+export const scenario = {
+  id: 'cross-agent-conflict',
+  problem: 'Cross-agent conflict',
+  story: 'Two agents try to change the same customer differently.',
+  expect: 'WAIT',
+  actors: [{ id: 'churn-agent', name: 'Churn agent' }, { id: 'upsell-agent', name: 'Upsell agent' }],
+  async run({ lumni, apps, guard, say }) {
+    const cancel = async () => {
+      const work = await startWork(lumni, 'churn-agent', 'Umbrella asked to cancel');
+      const r = await guard({
+        work_id: work, actor_id: 'churn-agent', operation: 'billing.cancel_subscription', risk: 'HIGH',
+        arguments: { subscription: SUB }, resources: [subscription],
+        metadata: { summary: 'Cancel Umbrella’s subscription', customer: 'Umbrella' },
+      }, () => apps.billing.cancel(SUB));
+      if (r.done) say('churn-agent', 'Cancelled Umbrella’s subscription');
+      await lumni.completeWork(work).catch(() => {});
+    };
+    const upgrade = async () => {
+      const work = await startWork(lumni, 'upsell-agent', 'Upgrade Umbrella to Enterprise');
+      await sleep(200);
+      const r = await guard({
+        work_id: work, actor_id: 'upsell-agent', operation: 'billing.change_plan', risk: 'MEDIUM',
+        arguments: { subscription: SUB, plan: 'Enterprise' }, resources: [subscription],
+        metadata: { summary: 'Upgrade Umbrella to Enterprise', customer: 'Umbrella' },
+      }, async () => {
+        // It acts on the subscription as it is now, which is why waiting matters.
+        const now = apps.billing.subscription(SUB);
+        if (now.status === 'cancelled') return { dropped: 'cancelled' };
+        return apps.billing.upgrade(SUB, 'Enterprise', this.id);
+      });
+      if (r.output?.dropped) say('upsell-agent', 'Umbrella has cancelled, so it drops the upgrade');
+      else if (r.done) say('upsell-agent', 'Upgraded Umbrella to Enterprise');
+      await lumni.completeWork(work).catch(() => {});
+    };
+    await Promise.all([cancel(), upgrade()]);
+  },
+};

package/assets/fleet/scenarios/06-superseded-work.mjs

@@ -0,0 +1,52 @@
+// Superseded work: the customer changes their mind while the agent works.
+//
+// The upsell agent spends a while researching an upgrade offer for Initech.
+// Initech cancels first. The churn agent cancels them and tells Lumni the
+// upgrade work is superseded, so when the upsell agent comes to apply it,
+// Lumni stops it.
+
+import { sleep } from '../lumni.mjs';
+import { startWork } from './kit.mjs';
+
+const SUB = 'sub_initech';
+
+export const scenario = {
+  id: 'superseded-work',
+  problem: 'Superseded work',
+  story: 'The customer changes their mind while the agent is still working.',
+  expect: 'REPLAN (work superseded)',
+  actors: [{ id: 'upsell-agent', name: 'Upsell agent' }, { id: 'churn-agent', name: 'Churn agent' }],
+  async run({ lumni, apps, guard, say, spend }) {
+    const upgradeWork = await startWork(lumni, 'upsell-agent', 'Upgrade Initech to Enterprise');
+    const upsell = async () => {
+      say('upsell-agent', 'Researching an upgrade offer for Initech…');
+      await spend({ actor: 'upsell-agent', work: upgradeWork, usd: 1.8, tokens: 60_000 });
+      await sleep(1500);
+      const r = await guard({
+        work_id: upgradeWork, actor_id: 'upsell-agent', operation: 'billing.change_plan', risk: 'MEDIUM',
+        arguments: { subscription: SUB, plan: 'Enterprise' },
+        resources: [{ type: 'subscription', namespace: 'billing', external_id: SUB, mode: 'WRITE' }],
+        metadata: { summary: 'Upgrade Initech to Enterprise', customer: 'Initech' },
+      }, () => apps.billing.upgrade(SUB, 'Enterprise', this.id));
+      if (r.done) say('upsell-agent', 'Upgraded Initech to Enterprise');
+    };
+    const churn = async () => {
+      await sleep(300);
+      const work = await startWork(lumni, 'churn-agent', 'Initech asked to cancel');
+      const r = await guard({
+        work_id: work, actor_id: 'churn-agent', operation: 'billing.cancel_subscription', risk: 'HIGH',
+        arguments: { subscription: SUB },
+        resources: [{ type: 'subscription', namespace: 'billing', external_id: SUB, mode: 'WRITE' }],
+        metadata: { summary: 'Cancel Initech’s subscription', customer: 'Initech' },
+      }, async () => {
+        const out = await apps.billing.cancel(SUB, 400);
+        // Anything still working toward an upgrade is now pointless.
+        await lumni.request('POST', `/v1/work/${encodeURIComponent(upgradeWork)}/supersede`, {});
+        return out;
+      });
+      if (r.done) say('churn-agent', 'Cancelled Initech, and marked the upgrade work superseded');
+      await lumni.completeWork(work).catch(() => {});
+    };
+    await Promise.all([upsell(), churn()]);
+  },
+};

package/assets/fleet/scenarios/07-duplicate-work.mjs

@@ -0,0 +1,45 @@
+// Duplicate work: two agents unknowingly solve the same problem.
+//
+// One email about a damaged order lands in two inboxes. The support agent and
+// the triage agent both pick it up. Both name the work after the goal
+// ("refund order 8812"), so the second one finds the first already owns it in
+// Lumni, and joins it instead of starting again.
+//
+// Lumni's part is the shared record of who is on what (the work id). Joining
+// is the agent's choice; the API has no JOIN decision. If it didn't join,
+// the refund's effect key would still stop the second refund (duplicate effect).
+
+import { sleep } from '../lumni.mjs';
+
+const ORDER = 8812;
+
+export const scenario = {
+  id: 'duplicate-work',
+  problem: 'Duplicate work',
+  story: 'Two agents unknowingly solve the same problem.',
+  expect: 'JOIN (shared work id)',
+  actors: [{ id: 'support-agent', name: 'Support agent' }, { id: 'triage-agent', name: 'Triage agent' }],
+  async run({ lumni, apps, guard, say, note, run }) {
+    const workId = `order-${ORDER}-refund-${run}`;
+    const handle = async (actor, delay) => {
+      await sleep(delay);
+      const w = await lumni.startWork({ id: workId, actor_id: actor, goal: `Refund damaged order #${ORDER}`, risk: 'MEDIUM' });
+      if (w.actor_id && w.actor_id !== actor) {
+        say(actor, `${w.actor_id} already owns “Refund damaged order #${ORDER}”: joining instead of starting again`);
+        note('joined', `${actor} joined ${w.actor_id}’s work instead of doing it twice`);
+        return;
+      }
+      say(actor, `Picked up order #${ORDER}`);
+      const charge = `ch_order_${ORDER}_${run}`;
+      const r = await guard({
+        work_id: workId, actor_id: actor, operation: 'stripe.refund', risk: 'MEDIUM',
+        arguments: { charge, amount: 45 }, effect_key: `stripe.refund:${charge}`,
+        resources: [{ type: 'charge', namespace: 'stripe', external_id: charge, mode: 'WRITE' }],
+        metadata: { summary: `Refund damaged order #${ORDER}`, customer: 'Soylent' },
+      }, () => apps.stripe.refund({ charge, amount: 45, by: actor, scenario: this.id }));
+      if (r.done) say(actor, `Refunded order #${ORDER}`);
+    };
+    await Promise.all([handle('support-agent', 0), handle('triage-agent', 250)]);
+    await lumni.completeWork(workId).catch(() => {});
+  },
+};

package/assets/fleet/scenarios/08-dependency.mjs

@@ -0,0 +1,49 @@
+// Dependency: one agent finishes step 3 before another finishes step 2.
+//
+// A customer is owed a refund on ticket #5120. The support agent wants to
+// close the ticket, but only once the refund agent's refund is done. It tells
+// Lumni its work depends on the refund work, and Lumni holds the close until
+// the refund completes.
+
+import { shortId, sleep } from '../lumni.mjs';
+import { startWork } from './kit.mjs';
+
+const TICKET = 5120;
+
+export const scenario = {
+  id: 'dependency',
+  problem: 'Dependency',
+  story: 'One agent finishes step 3 before another finishes step 2.',
+  expect: 'WAIT (dependency)',
+  actors: [{ id: 'refund-agent', name: 'Refund agent' }, { id: 'support-agent', name: 'Support agent' }],
+  async run({ lumni, apps, guard, say }) {
+    const charge = `ch_ticket_${TICKET}_${shortId()}`;
+    const refundWork = await startWork(lumni, 'refund-agent', `Refund for ticket #${TICKET}`);
+    const closeWork = await startWork(lumni, 'support-agent', `Close ticket #${TICKET}`);
+    await lumni.request('POST', '/v1/dependencies', { id: `dep_${closeWork}`, entity_type: 'work', source_id: closeWork, target_id: refundWork, relationship: 'DEPENDS_ON' });
+    say('support-agent', `Told Lumni: closing #${TICKET} depends on the refund`);
+
+    const refund = async () => {
+      const r = await guard({
+        work_id: refundWork, actor_id: 'refund-agent', operation: 'stripe.refund', risk: 'MEDIUM',
+        arguments: { charge, amount: 120 }, effect_key: `stripe.refund:${charge}`,
+        resources: [{ type: 'charge', namespace: 'stripe', external_id: charge, mode: 'WRITE' }],
+        metadata: { summary: `Refund $120 for ticket #${TICKET}`, customer: 'Hooli' },
+      }, () => apps.stripe.refund({ charge, amount: 120, by: 'refund-agent', ms: 1200, scenario: this.id }));
+      if (r.done) say('refund-agent', 'Refunded $120 (Stripe was slow)');
+      await lumni.completeWork(refundWork).catch(() => {});
+    };
+    const close = async () => {
+      await sleep(200);
+      const r = await guard({
+        work_id: closeWork, actor_id: 'support-agent', operation: 'zendesk.close_ticket', risk: 'LOW',
+        arguments: { ticket: TICKET },
+        resources: [{ type: 'ticket', namespace: 'zendesk', external_id: String(TICKET), mode: 'WRITE' }],
+        metadata: { summary: `Close ticket #${TICKET}` },
+      }, () => apps.zendesk.close(TICKET, { refundFor: charge, scenario: this.id }));
+      if (r.done) say('support-agent', `Closed ticket #${TICKET}`);
+      await lumni.completeWork(closeWork).catch(() => {});
+    };
+    await Promise.all([refund(), close()]);
+  },
+};

package/assets/fleet/scenarios/09-false-completion.mjs

@@ -0,0 +1,48 @@
+// False completion: the agent says “done”, the app says no.
+//
+// The refund agent refunds $75. Stripe answers “succeeded”, then loses it.
+// The agent reports success, as it should. A checker (Stripe's webhook, in
+// real life) reads Stripe afterwards, finds no refund, and tells Lumni, which
+// opens an incident. A second refund that did land is marked verified.
+//
+// Needs --admin-key: registering the checker and posting what it found need
+// the `verification` scope, which agent keys don't have.
+
+import { shortId } from '../lumni.mjs';
+import { ensureVerifier, evidence, startWork } from './kit.mjs';
+
+export const scenario = {
+  id: 'false-completion',
+  problem: 'False completion',
+  story: 'The agent says “done.” The app says “no.”',
+  expect: 'INCIDENT (outcome mismatch)',
+  needsAdmin: true,
+  actors: [{ id: 'refund-agent', name: 'Refund agent' }],
+  async run({ lumni, admin, apps, guard, say, note }) {
+    await ensureVerifier(admin, 'stripe-refunds', 'Stripe refunds (agent fleet)');
+    const work = await startWork(lumni, 'refund-agent', 'Refund two late deliveries');
+    for (const [amount, lost] of [[75, true], [30, false]]) {
+      const charge = `ch_${shortId()}`;
+      const r = await guard({
+        work_id: work, actor_id: 'refund-agent', operation: 'stripe.refund', risk: 'MEDIUM',
+        arguments: { charge, amount }, effect_key: `stripe.refund:${charge}`,
+        resources: [{ type: 'charge', namespace: 'stripe', external_id: charge, mode: 'WRITE' }],
+        verification: { verifier_id: 'stripe-refunds', expected: { charge, amount } },
+        metadata: { summary: `Refund $${amount} on ${charge}`, customer: 'Hooli' },
+      }, () => apps.stripe.refund({ charge, amount, by: 'refund-agent', drop: lost, scenario: this.id }));
+      if (!r.done) continue;
+      say('refund-agent', `Stripe said the $${amount} refund succeeded. Reported it done`);
+      // The checker reads Stripe itself.
+      const found = apps.stripe.refundsFor(charge);
+      if (found.length) {
+        await evidence(admin, r.decision.action_id, 'VERIFIED', { refunds: found.map((x) => x.id) }, 'Stripe shows the refund');
+        say('stripe-checker', `Checked Stripe: the $${amount} refund is there. Verified`);
+      } else {
+        await evidence(admin, r.decision.action_id, 'MISMATCH', { refunds: [] }, 'Stripe has no refund for this charge');
+        say('stripe-checker', `Checked Stripe: there is no $${amount} refund. Lumni opens an incident`);
+        note('stepped-in', 'Lumni opened an incident for the lost refund; the real one is verified');
+      }
+    }
+    await lumni.completeWork(work).catch(() => {});
+  },
+};