lumniverse 0.3.1 → 0.4.0

package/README.md

@@ -8,6 +8,7 @@ npx lumniverse --domain acme.com    # run it on a server, with HTTPS at app.acme
 npx lumniverse --ip 203.0.113.7     # on a server without a domain yet
 npx lumniverse init                 # connect the agent in this folder (opens your browser)
 npx lumniverse demo                 # the console on a made-up day: no Docker, no account
+npx lumniverse try                  # sample agents act out twelve problems in your workspace
 ```
 
 `npx lumniverse` runs the same installer as `curl -fsSL https://get.lumniverse.com | sh`, with the files bundled in this package. It writes `~/lumni`: the Compose file, a `.env` with secrets generated on your machine (kept on later runs), and a `./lumni` helper. Then it starts the API, console, worker and Postgres, and opens the console, where the first visit creates the owner account.

package/assets/console/device.html

@@ -93,6 +93,7 @@ async function show(code) {
   if (l.status === 'denied') return ended('This login was cancelled', 'Nothing was connected. Run the command again if you meant to connect.');
   if (l.status !== 'pending') return connected(l, false);
 
+  if (l.purpose === 'try') return showTry(l);
   box.innerHTML = `${head('Is this you?', 'A terminal is asking to connect to your Lumni workspace.')}
     ${codeChip(l.user_code)}
     <div class="match">Check it matches the code in your terminal</div>
@@ -124,6 +125,42 @@ async function show(code) {
   };
 }
 
+/** lumniverse try: sample agents, with a key that can do everything until the run ends. */
+function showTry(l) {
+  box.innerHTML = `${head('Run the sample agents here?', 'A terminal wants to act out twelve short scenarios in this workspace, so you can see Lumni at work.')}
+    ${codeChip(l.user_code)}
+    <div class="match">Check it matches the code in your terminal</div>
+    <dl class="facts">
+      <div><dt>Machine</dt><dd>${E(l.host ?? 'Not given')}</dd></div>
+      <div><dt>From</dt><dd>lumniverse try${l.address && l.address !== 'peer' ? `<small>${E(l.address)}</small>` : ''}</dd></div>
+      <div><dt>Asked</dt><dd>${ago(l.created_at)}<small>${left(l.expires_at)}</small></dd></div>
+    </dl>
+    <p class="muted" style="margin-top:14px">About a dozen sample agents (a refund agent, a price setter, a quote bot…) and one sample person will appear in this workspace with their actions, a checker and a research limit. Only demo apps are touched. The run gets a <b>full-access key</b> that the command revokes when it finishes.</p>
+    <div class="acts"><button class="btn accent go" id="ok">Run them</button><button class="btn" id="no">Cancel</button></div>
+    <div class="warn"><span>⚠︎</span><span><b>Only approve a command you just ran.</b> If someone sent you this link, cancel: approving gives their machine full access to your workspace.</span></div>
+    <div class="err" id="err"></div>`;
+  $('#ok').onclick = async () => {
+    $('#ok').disabled = $('#no').disabled = true;
+    $('#ok').textContent = 'Starting…';
+    const out = await Shell.write('POST', `/v1/console/device/${encodeURIComponent(l.user_code)}/approve`, {}, { reload: false });
+    if (!out) {
+      $('#ok').disabled = $('#no').disabled = false;
+      $('#ok').textContent = 'Run them';
+      $('#err').textContent = Shell.lastError?.message ?? 'It couldn’t be started.';
+      return;
+    }
+    box.innerHTML = `<div class="done">
+      <div class="tick"><svg viewBox="0 0 40 40" fill="none"><path d="M10 21l7 7 13-15" stroke="#fff" stroke-width="4.5" stroke-linecap="round" stroke-linejoin="round"/></svg></div>
+      <h1>Running</h1>
+      <p class="muted" style="margin-top:8px">The sample agents are starting in your terminal. Watch them arrive.</p>
+      <div class="acts"><a class="btn accent" href="/today">Watch Today</a><a class="btn" href="/flow">Flow</a></div></div>`;
+  };
+  $('#no').onclick = async () => {
+    await Shell.write('POST', `/v1/console/device/${encodeURIComponent(l.user_code)}/deny`, {}, { reload: false });
+    ended('Cancelled', 'Nothing ran. The command in your terminal stops.');
+  };
+}
+
 function connected(l, now) {
   box.innerHTML = `<div class="done">
     <div class="tick"><svg viewBox="0 0 40 40" fill="none"><path d="M10 21l7 7 13-15" stroke="#fff" stroke-width="4.5" stroke-linecap="round" stroke-linejoin="round"/></svg></div>

package/assets/console/start.html

@@ -388,8 +388,9 @@ async function watchCode() {
   if (!S.codeId) {
     if (S.key) return;
     try {
-      const r = await Shell.api.get(`/v1/console/device?since=${S.since - 60_000}`);
+      const r = await Shell.api.get(`/v1/console/device?since=${S.since - 10 * 60_000}`);
       const l = (r.items ?? []).at(-1);
+      if (l) S.login = { at: Date.parse(l.at), project: l.project };
       if (l) tick('ran', `${l.host ? `On ${l.host}` : 'On your machine'}${l.project ? `, in ${l.project}` : ''}, connected in the browser`);
     } catch {}
     return;
@@ -477,8 +478,15 @@ async function pollOnce() {
     const from = encodeURIComponent(new Date(S.since - 120_000).toISOString());
     const actors = (await Shell.api.get(S.baseline ? `/v1/actors?from=${from}&type=AGENT&limit=200` : '/v1/actors?limit=1000')).items ?? [];
     if (!S.baseline) {
-      S.baseline = new Set(actors.map((a) => a.id));
-      $('#listen-meta').innerHTML = actors.length ? `<a class="linky" href="/flow" title="Already set up? See them on Flow">${actors.length} ${actors.length === 1 ? 'agent' : 'agents'} already here</a>` : '';
+      // The command may have finished before this page opened: the agent it
+      // named after the folder, made around that login, is this one, not an old one.
+      const named = S.login?.project && S.login.project.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-|-$/g, '');
+      const justMade = (a) => named && a.id === named && (!a.created_at || Date.parse(a.created_at) >= S.login.at - 10 * 60_000);
+      S.baseline = new Set(actors.filter((a) => !justMade(a)).map((a) => a.id));
+      // Its hello check came then too, so look for checks from the login on.
+      if (actors.some(justMade)) S.since = Math.min(S.since, S.login.at);
+      const old = S.baseline.size;
+      $('#listen-meta').innerHTML = old ? `<a class="linky" href="/flow" title="Already set up? See them on Flow">${old} ${old === 1 ? 'agent' : 'agents'} already here</a>` : '';
     }
     const fresh = actors.filter((a) => !S.baseline.has(a.id) && a.type !== 'HUMAN');
     if (fresh.length && !S.done.agent) {
@@ -489,7 +497,8 @@ async function pollOnce() {
       tick('agent', `${S.agentName}${a.runtime ? `, ${a.runtime}` : ''}`);
     }
     if (S.done.agent) {
-      const rows = ((await Shell.api.get(`/v1/actions?actor_id=${encodeURIComponent(S.agentId)}&from=${from}&limit=20`)).items ?? []).filter((r) => r.actor_id === S.agentId);
+      const since = encodeURIComponent(new Date(S.since - 120_000).toISOString());
+      const rows = ((await Shell.api.get(`/v1/actions?actor_id=${encodeURIComponent(S.agentId)}&from=${since}&limit=20`)).items ?? []).filter((r) => r.actor_id === S.agentId);
       for (const r of rows.slice(0, 5).reverse()) {
         if (S.seen.has(r.id)) continue;
         S.seen.add(r.id);
@@ -608,7 +617,7 @@ function reset() {
   S.timers.forEach(clearTimeout);
   S.timers = [];
   clearTimeout(S.pollTimer);
-  Object.assign(S, { madeBy: null, code: null, codeId: null, codeExp: 0, key: null, prefix: null, done: {}, at: {}, feed: [], seen: new Set(), baseline: null, since: Date.now(), agentName: null, agentId: null, cinematic: false });
+  Object.assign(S, { login: null, madeBy: null, code: null, codeId: null, codeExp: 0, key: null, prefix: null, done: {}, at: {}, feed: [], seen: new Set(), baseline: null, since: Date.now(), agentName: null, agentId: null, cinematic: false });
   $('#feed').innerHTML = '';
   $('#listen').classList.remove('connected', 'done');
   $('#s1').classList.remove('done');

package/assets/deploy/install.sh

@@ -148,7 +148,13 @@ case "${1:-help}" in
   backup)
     stamp=$(date +%Y%m%d-%H%M%S)
     dc exec -T postgres pg_dump -U lumni -d lumni | gzip > "backups/postgres-$stamp.sql.gz"
-    dc exec -T console sh -c 'cat /data/console.db' > "backups/console-$stamp.db"
+    # A snapshot of the accounts database (copying the live file could catch it
+    # mid-write). Consoles from before 0.4 lack the script: copy the file there.
+    dc exec -T console sh -c 'if [ -f scripts/backup-db.ts ]; then bun scripts/backup-db.ts /tmp/console-backup.db && cat /tmp/console-backup.db && rm -f /tmp/console-backup.db; else cat /data/console.db; fi' > "backups/console-$stamp.db"
+    if ! gzip -t "backups/postgres-$stamp.sql.gz" 2>/dev/null || [ "$(gzip -dc "backups/postgres-$stamp.sql.gz" | head -c 1 | wc -c)" -eq 0 ] || [ ! -s "backups/console-$stamp.db" ]; then
+      rm -f "backups/postgres-$stamp.sql.gz" "backups/console-$stamp.db"
+      echo "The backup failed; nothing was kept." >&2; exit 1
+    fi
     echo "Saved backups/postgres-$stamp.sql.gz and backups/console-$stamp.db" ;;
   url) url ;;
   *) echo "./lumni up | down | update | status | logs [service] | backup | url" ;;

package/assets/fleet/apps.mjs

@@ -0,0 +1,145 @@
+// Pretend apps the agents change: Stripe, Salesforce, a billing system,
+// Zendesk and a web-research API. They live in memory, nothing here calls a
+// real service, and they write down every problem a real app would have, so
+// you can see what Lumni prevented (or, in watch-only mode, didn't).
+
+import { writeFileSync } from 'node:fs';
+
+const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+const now = () => new Date().toISOString();
+/** $42, or $40.85 when there are cents. */
+export const usd = (n) => `$${Number.isInteger(n) ? n.toLocaleString('en-US') : n.toFixed(2)}`;
+
+/** `kept`: what a previous run left (the price list), so versions keep moving forward. */
+export function createApps(kept = {}) {
+  const state = {
+    stripe: { refunds: [], charges: [] },
+    salesforce: { priceList: kept.priceList ?? { name: 'Enterprise', seatPrice: 42, version: 1, history: [] }, accounts: { Globex: { edits: [] } }, opportunities: {} },
+    billing: { subscriptions: { sub_umbrella: { customer: 'Umbrella', plan: 'Pro', status: 'active' }, sub_initech: { customer: 'Initech', plan: 'Pro', status: 'active' } } },
+    zendesk: { replies: [], closed: [] },
+    quotes: [],
+    research: { calls: 0, maxAtOnce: 0, inFlight: 0 },
+    /** Things that went wrong, in plain words. */
+    problems: [],
+  };
+  const problem = (scenario, text) => state.problems.push({ scenario, text, at: now() });
+  let editing = 0;
+
+  const customers = () => ({ sub_umbrella: { customer: 'Umbrella', plan: 'Pro', status: 'active' }, sub_initech: { customer: 'Initech', plan: 'Pro', status: 'active' } });
+  state.billing.subscriptions = customers();
+
+  return {
+    state,
+
+    /** Each round, the customers are back on Pro and active. */
+    resetCustomers() {
+      state.billing.subscriptions = customers();
+    },
+
+    stripe: {
+      /** `drop`: Stripe says yes and loses it (the false-completion case). */
+      async refund({ charge, amount, by, drop = false, ms = 150, scenario }) {
+        await pause(ms);
+        const id = `re_${state.stripe.refunds.length + 1}`;
+        if (drop) return { id, charge, amount, status: 'succeeded' };
+        if (state.stripe.refunds.some((r) => r.charge === charge)) problem(scenario, `${charge} was refunded twice`);
+        state.stripe.refunds.push({ id, charge, amount, by, at: now() });
+        return { id, charge, amount, status: 'succeeded' };
+      },
+      refundsFor: (charge) => state.stripe.refunds.filter((r) => r.charge === charge),
+      async charge({ customer, amount }) {
+        await pause(150);
+        const c = { id: `ch_${state.stripe.charges.length + 1}`, customer, amount, at: now() };
+        state.stripe.charges.push(c);
+        return c;
+      },
+    },
+
+    salesforce: {
+      readPriceList() {
+        const p = state.salesforce.priceList;
+        return { seatPrice: p.seatPrice, version: `v${p.version}` };
+      },
+      /** `read`: the version the writer based this on; writing over a newer one loses a change. */
+      async setSeatPrice(price, by, read, scenario) {
+        await pause(120);
+        const p = state.salesforce.priceList;
+        if (read && read !== `v${p.version}`) problem(scenario, `${by} wrote ${usd(price)} over a price list that changed after it read it`);
+        p.history.push({ from: p.seatPrice, to: price, by, version: p.version + 1, at: now() });
+        p.seatPrice = price;
+        p.version += 1;
+        return { seatPrice: price, version: `v${p.version}` };
+      },
+      async editAccount(account, field, value, by, scenario) {
+        editing++;
+        if (editing === 2) problem(scenario, `Two agents edited ${account} at the same time`);
+        await pause(300);
+        state.salesforce.accounts[account] ??= { edits: [] };
+        state.salesforce.accounts[account].edits.push({ field, value, by, at: now() });
+        editing--;
+      },
+      /** `fail`: Salesforce is down (the partial-completion case). */
+      async closeOpportunity(id, { fail = false } = {}) {
+        await pause(150);
+        if (fail) throw new Error('Salesforce answered 503');
+        state.salesforce.opportunities[id] = { stage: 'Closed Won', at: now() };
+        return { id, stage: 'Closed Won' };
+      },
+    },
+
+    billing: {
+      subscription: (id) => ({ ...state.billing.subscriptions[id] }),
+      async upgrade(id, plan, scenario) {
+        await pause(150);
+        const s = state.billing.subscriptions[id];
+        if (s.status !== 'active') problem(scenario, `${s.customer} was upgraded to ${plan} while cancelling`);
+        s.plan = plan;
+        return { ...s };
+      },
+      async cancel(id, ms = 900) {
+        const s = state.billing.subscriptions[id];
+        s.status = 'cancelling';
+        await pause(ms);
+        s.status = 'cancelled';
+        return { ...s };
+      },
+    },
+
+    zendesk: {
+      async reply(ticket, text) {
+        await pause(80);
+        state.zendesk.replies.push({ ticket, text, at: now() });
+      },
+      async close(ticket, { refundFor, scenario } = {}) {
+        await pause(80);
+        if (refundFor && !state.stripe.refunds.some((r) => r.charge === refundFor)) problem(scenario, `Ticket #${ticket} was closed before its refund landed`);
+        state.zendesk.closed.push({ ticket, at: now() });
+      },
+    },
+
+    quotes: {
+      async send(account, kind, by, scenario) {
+        await pause(100);
+        if (state.quotes.some((q) => q.account === account && q.kind === kind)) problem(scenario, `${account} got the same ${kind} quote twice`);
+        state.quotes.push({ account, kind, by, at: now() });
+      },
+    },
+
+    research: {
+      async fetch(topic, cap, scenario) {
+        const r = state.research;
+        r.calls++;
+        r.inFlight++;
+        r.maxAtOnce = Math.max(r.maxAtOnce, r.inFlight);
+        if (r.inFlight === (cap ?? 5) + 1) problem(scenario, `More than ${cap ?? 5} research calls ran at once`);
+        await pause(500);
+        r.inFlight--;
+        return { topic, pages: 3 };
+      },
+    },
+
+    save(file) {
+      writeFileSync(file, JSON.stringify(state, null, 2) + '\n');
+    },
+  };
+}

package/assets/fleet/lumni.mjs

@@ -0,0 +1,193 @@
+// How every agent in this fleet talks to Lumni.
+//
+// The rule from docs/sdk.md, in one place (`guard`):
+//   ALLOW, WARN and every WOULD_*  go ahead (WOULD_* means watch-only mode)
+//   WAIT                           wait retry_after_ms, then ask again
+//   REPLAN                         read the thing again, then ask again;
+//                                  or stop, when the work itself was superseded
+//   REQUIRE_APPROVAL               wait for a person, then ask again
+//   DEDUPLICATE                    it's already done: don't do it twice
+//   REJECT                         don't do it
+
+import { existsSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** The published SDK when it's installed; until then, the one in this repository. */
+async function loadSdk() {
+  try {
+    return await import('@lumniverse/sdk');
+  } catch {
+    return import('../../sdk/typescript/dist/index.js');
+  }
+}
+const sdk = await loadSdk();
+export const { LumniClient, shouldExecute } = sdk;
+
+/** KEY=value lines from .env, which `lumni init` writes. The environment wins. */
+export function settings(env = process.env, dir = here) {
+  const file = join(dir, '.env');
+  const dot = {};
+  if (existsSync(file)) {
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+      const m = /^\s*([A-Z0-9_]+)\s*=\s*(.*?)\s*$/.exec(line);
+      if (m) dot[m[1]] = m[2].replace(/^['"]|['"]$/g, '');
+    }
+  }
+  return {
+    url: (env.LUMNI_URL ?? dot.LUMNI_URL ?? 'http://localhost:8080').replace(/\/+$/, ''),
+    key: env.LUMNI_API_KEY ?? dot.LUMNI_API_KEY ?? '',
+  };
+}
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const shortId = () => randomUUID().slice(0, 8);
+
+/** Why, in plain words. */
+const WHY = {
+  LEASE_BUSY: 'another agent is working on it',
+  CONFLICTING_ACTIVE_MUTATION: 'another agent is changing it',
+  WRITE_WRITE_CONFLICT: 'another agent is changing it',
+  DELETE_WRITE_CONFLICT: 'another agent is deleting it',
+  DOMAIN_OPERATION_CONFLICT: 'it clashes with work already under way',
+  CONCURRENCY_LIMIT: 'as many as you allow are already running',
+  RATE_LIMITED: 'it hit the rate you set',
+  BUDGET_PACING: 'it’s spending ahead of the daily limit',
+  STALE_OBSERVATION: 'what it read is out of date',
+  VERSION_SOURCE_CHANGED: 'it read the thing from somewhere else',
+  EXACT_EFFECT_ALREADY_COMMITTED: 'it was already done',
+  EXACT_DUPLICATE_ACTIVE: 'the same thing is already under way',
+  DEPENDENCY_INCOMPLETE: 'what it depends on isn’t finished',
+  ACTION_RESULT_UNKNOWN: 'an earlier try may have done it; Lumni is finding out',
+  WORK_SUPERSEDED: 'the work it was doing was superseded',
+  WORK_CANCELLED: 'the work it was doing was cancelled',
+  ACTION_SUPERSEDED: 'this step was superseded',
+  ACTOR_PAUSED: 'you paused this agent',
+  POLICY_REJECTED: 'a rule doesn’t allow it',
+  APPROVAL_DENIED: 'a person said no',
+  APPROVAL_EXPIRED: 'nobody answered in time',
+};
+export const why = (code) => WHY[code] ?? String(code ?? 'no reason given').toLowerCase().replace(/_/g, ' ');
+
+const WOULD = {
+  WAIT: 'would have made it wait',
+  REPLAN: 'would have sent it back',
+  DEDUPLICATE: 'would have stopped it',
+  REQUIRE_APPROVAL: 'would have asked a person first',
+  REJECT: 'would have refused it',
+};
+/** REPLAN reasons that mean the work is no longer wanted: stop, don't re-read. */
+const GONE = new Set(['WORK_SUPERSEDED', 'WORK_CANCELLED', 'ACTION_SUPERSEDED']);
+
+/**
+ * Check an action with Lumni, and do it only when Lumni says so.
+ *
+ *   input     what the agent wants to do (actor_id, work_id, operation, resources, …)
+ *   act       the side effect, run once Lumni allows it; its return value is reported as the result
+ *   onReplan  re-read what went stale; returns the new input
+ *   seen      a Set that collects each decision ("ALLOW", "WAIT:LEASE_BUSY", …)
+ *
+ * Waits (WAIT) are bounded by time, since a queue or a dependency can take a
+ * while; everything else by a count.
+ *
+ * Resolves with { done, skipped?, refused?, superseded?, output?, decision }.
+ */
+export async function guard(lumni, input, act, { say = () => {}, onReplan, seen, approvalWaitMs = 120_000, pollMs = 3000, waitBudgetMs = 90_000, maxTries = 8 } = {}) {
+  let ask = { ...input, action_id: input.action_id ?? `${input.actor_id}-${shortId()}` };
+  const until = Date.now() + waitBudgetMs;
+  let tries = 0;
+  let lastWait = '';
+  while (tries < maxTries) {
+    const d = await lumni.checkAction(ask);
+    const raw = String(d.decision);
+    const kind = raw.replace(/^WOULD_/, '');
+    seen?.add(raw === 'ALLOW' ? 'ALLOW' : `${raw}:${d.reason_code}`);
+
+    if (shouldExecute(d)) {
+      if (raw.startsWith('WOULD_') && WOULD[kind]) say(`Lumni ${WOULD[kind]}: ${why(d.reason_code)} (watch-only, so it goes ahead)`);
+      if (kind === 'WARN') say(`Lumni warns: ${why(d.reason_code)}`);
+      return { done: true, output: await perform(lumni, d, act, say), decision: d };
+    }
+    if (kind === 'DEDUPLICATE') {
+      say(`Lumni stopped it: ${why(d.reason_code || 'EXACT_EFFECT_ALREADY_COMMITTED')}`);
+      return { done: false, skipped: true, decision: d };
+    }
+    if (kind === 'WAIT') {
+      if (Date.now() > until) break;
+      // Say it once per reason, not on every retry.
+      if (lastWait !== d.reason_code) say(`Lumni says wait: ${why(d.reason_code)}`);
+      lastWait = d.reason_code;
+      await sleep(Math.min(5_000, Math.max(300, d.retry_after_ms ?? 1000)));
+      continue;
+    }
+    tries++;
+    if (kind === 'REPLAN') {
+      if (GONE.has(d.reason_code)) {
+        say(`Lumni stopped it: ${why(d.reason_code)}`);
+        return { done: false, superseded: true, decision: d };
+      }
+      say(`Lumni sent it back: ${why(d.reason_code)}. Reading again`);
+      if (!onReplan) return { done: false, refused: true, decision: d };
+      ask = { ...(await onReplan(ask)), action_id: `${input.actor_id}-${shortId()}` };
+      continue;
+    }
+    if (kind === 'REQUIRE_APPROVAL') {
+      say('Waiting for a person to decide (open Needs you in the console)');
+      const status = await waitForPerson(lumni, d.approval_id, approvalWaitMs, pollMs);
+      if (status !== 'APPROVED') {
+        say(status === 'DENIED' ? 'A person said no. Not doing it' : 'Nobody decided in time. Not doing it');
+        return { done: false, refused: true, decision: d };
+      }
+      say('A person approved it');
+      continue; // the same action_id, checked again, is now allowed
+    }
+    say(`Lumni refused it: ${why(d.reason_code)}`);
+    return { done: false, refused: true, decision: d };
+  }
+  say('Gave up waiting');
+  return { done: false, refused: true };
+}
+
+async function waitForPerson(lumni, approvalId, waitMs, pollMs) {
+  if (!approvalId) return 'UNKNOWN';
+  const until = Date.now() + waitMs;
+  while (Date.now() < until) {
+    const a = await lumni.approval(approvalId).catch(() => null);
+    const status = String(a?.status ?? 'PENDING').toUpperCase();
+    if (status !== 'PENDING') return status;
+    await sleep(pollMs);
+  }
+  return 'TIMED_OUT';
+}
+
+/** Start, do it, and say how it went. A thrown error is reported as FAILED. */
+async function perform(lumni, d, act, say) {
+  const lease = d.lease_token;
+  await lumni.startAction(d.action_id, lease).catch((e) => say(`(couldn’t mark it started: ${e.message})`));
+  try {
+    const output = await act(d);
+    await lumni.reportResult(d.action_id, { status: 'SUCCEEDED', lease_token: lease, output: output ?? {} }).catch((e) => say(`(couldn’t report the result: ${e.message})`));
+    return output;
+  } catch (e) {
+    await lumni.reportResult(d.action_id, { status: 'FAILED', lease_token: lease, output: { error: e.message } }).catch(() => {});
+    return { failed: e.message };
+  }
+}
+
+/** Lumni's id for a thing, so its version can be recorded. */
+export async function resourceId(lumni, ref) {
+  const r = await lumni.request('POST', '/v1/resources/resolve', ref, true);
+  return r.id;
+}
+
+/** What a model call cost, so Lumni's FinOps can tell useful spend from waste. */
+export function spend(lumni, { actor, work, action, usd, model = 'gpt-4.1', tokens = 0 }) {
+  return lumni.recordCost({
+    actor_id: actor, work_id: work, ...(action ? { action_id: action } : {}),
+    provider: 'openai', model, cost_type: 'MODEL', input_units: tokens, output_units: Math.round(tokens / 4),
+    amount_micros_usd: Math.round(usd * 1e6),
+  }).catch(() => {});
+}