aimeat 2.1.0 → 2.3.0

package/dist/static/sdk-libs/dist/aimeat-live.js

@@ -238,12 +238,64 @@
       hadHiddenUpdate = false;
     }
   }
-  function subscribe(domains, fn) {
+  function subscribe(domains, fn, opts) {
     if (typeof domains === "function") {
+      opts = fn;
       fn = domains;
       domains = null;
     }
-    var entry = { domains: domains ? new Set(domains) : null, fn };
+    opts = opts || {};
+    var prefixes = opts.keyPrefix ? Array.isArray(opts.keyPrefix) ? opts.keyPrefix.slice() : [opts.keyPrefix] : null;
+    var minInterval = opts.minIntervalMs > 0 ? opts.minIntervalMs : 0;
+    var counts = /* @__PURE__ */ Object.create(null);
+    var lastCall = 0;
+    var probing = false;
+    var primed = !prefixes;
+    function pass(dset) {
+      lastCall = Date.now();
+      try {
+        fn(dset);
+      } catch {
+      }
+    }
+    function gate(dset) {
+      if (minInterval && Date.now() - lastCall < minInterval) return;
+      if (!prefixes) {
+        pass(dset);
+        return;
+      }
+      if (probing) return;
+      probing = true;
+      Promise.all(prefixes.map(function(p) {
+        var qs = "count=true&prefix=" + encodeURIComponent(p) + (opts.agent ? "&agent=" + encodeURIComponent(opts.agent) : opts.ownerScope ? "&owner_scope=true" : "");
+        return getSession2().fetch("/v1/memory?" + qs).then(function(r) {
+          var c = r && r.data && typeof r.data.count === "number" ? r.data.count : null;
+          return { prefix: p, count: c };
+        }).catch(function() {
+          return { prefix: p, count: null };
+        });
+      })).then(function(res) {
+        probing = false;
+        var changed = false;
+        res.forEach(function(r) {
+          if (r.count == null) return;
+          if (counts[r.prefix] !== r.count) {
+            changed = true;
+            counts[r.prefix] = r.count;
+          }
+        });
+        if (!primed) {
+          primed = true;
+          if (res.every(function(r) {
+            return r.count != null;
+          })) return;
+        }
+        if (changed) pass(dset);
+      }).catch(function() {
+        probing = false;
+      });
+    }
+    var entry = { domains: domains ? new Set(domains) : null, fn: gate };
     subscribers.push(entry);
     connect();
     return function() {

package/dist/static/sdk-libs/dist/aimeat-markdown.js

@@ -598,5 +598,36 @@
     (document.head || document.documentElement).appendChild(s);
   }
   injectCss();
-  attach("md", { render, renderToString, renderRich, sanitizeHref, sanitizeImgSrc });
+  var CITE_URL_RE = /https?:\/\/[^\s,;)\]}"'【】]+/g;
+  var SHORTENERS = ["lnkd.in", "bit.ly", "t.co", "ow.ly", "tinyurl.com", "buff.ly", "goo.gl", "is.gd", "rb.gy"];
+  function citations(text, opts) {
+    var strip = !opts || opts.stripInline !== false;
+    var body = String(text == null ? "" : text);
+    var seen = /* @__PURE__ */ Object.create(null);
+    var out = [];
+    function push(u) {
+      u = String(u).replace(/[.,;:]+$/, "");
+      if (!u || seen[u]) return;
+      seen[u] = 1;
+      var host;
+      try {
+        host = new URL(u).hostname.replace(/^www\./, "");
+      } catch {
+        host = "";
+      }
+      out.push({ url: u, host, shortened: SHORTENERS.indexOf(host) >= 0 });
+    }
+    body = body.replace(/【\s*(https?:\/\/[^】\s]+)\s*】/g, function(m, u) {
+      push(u);
+      return strip ? "" : m;
+    });
+    body = body.replace(/^[ \t]*Sources?[ \t]*:[ \t]*(.*)$/gim, function(m, rest) {
+      (String(rest).match(CITE_URL_RE) || []).forEach(push);
+      return strip ? "" : m;
+    });
+    (body.match(CITE_URL_RE) || []).forEach(push);
+    if (strip) body = body.replace(/[ \t]+$/gm, "").replace(/\n{3,}/g, "\n\n").trim();
+    return { body, sources: out };
+  }
+  attach("md", { render, renderToString, renderRich, sanitizeHref, sanitizeImgSrc, citations });
 })();

package/dist/static/sdk-libs/dist/aimeat-webmcp.js

@@ -94,6 +94,27 @@
       return asContent(res.ok ? res.data : res);
     };
   }
+  function aboutTool(ref, surface, toolCount) {
+    const s = surface || {};
+    const label = s.name || ref.appId;
+    const parts = [];
+    if (toolCount) parts.push(toolCount + " callable tool" + (toolCount === 1 ? "" : "s"));
+    if ((s.skills || []).length) parts.push(s.skills.length + " bound skill" + (s.skills.length === 1 ? "" : "s"));
+    if ((s.bundled_agents || []).length) parts.push(s.bundled_agents.length + " bundled agent" + (s.bundled_agents.length === 1 ? "" : "s"));
+    const offers = ((s.exchange || {}).offerings || []).length;
+    if (offers) parts.push(offers + " EXCHANGE listing" + (offers === 1 ? "" : "s"));
+    const carries = parts.length ? " Carries " + parts.join(", ") + "." : "";
+    return {
+      name: "about-this-app",
+      description: 'What "' + label + '" (' + ref.owner + "/" + ref.appId + ") offers an agent: its app id, declared scopes, the SKILL.md packs bound to it, the agent crews it ships, and what it sells on the AIMEAT EXCHANGE, with prices." + carries,
+      inputSchema: { type: "object", properties: {} },
+      async execute() {
+        if (surface) return asContent(surface);
+        const listing = await fetchListing(ref.owner, ref.appId);
+        return asContent(listing.app_surface || { app: ref.owner + "/" + ref.appId });
+      }
+    };
+  }
   var webmcp = {
     /** Every tool descriptor this page has registered (introspection + provideContext resends). */
     tools: [],
@@ -116,9 +137,15 @@
     /**
      * Expose an app's declared tools (apps.{appId}.tools manifest) to the in-browser agent.
      * Descriptions of priced tools carry the price tag so the agent can tell the user the cost.
+     *
+     * Every app also gets `about-this-app`, built from the listing's `app_surface`: the SKILL.md
+     * packs bound to the app, the crew-defs it ships, its declared scopes and its live EXCHANGE
+     * listings. An app that sells nothing still exposes that one, so an agent that lands on any
+     * app page can ask what it is looking at instead of reading 200 kB of minified source.
      */
     async exposeAppTools(ref) {
       const listing = await fetchListing(ref.owner, ref.appId);
+      const surface = listing.app_surface || null;
       const tools = (listing.tools || []).map(function(entry) {
         let desc = entry.description || entry.name;
         if (entry.payment && entry.payment.required) {
@@ -135,6 +162,7 @@
           execute: buildExecute(ref.owner, ref.appId, entry)
         };
       });
+      tools.unshift(aboutTool(ref, surface, tools.length));
       await webmcp.register(tools);
       return { surface: webmcp.surface, tools: tools.map(function(t) {
         return t.name;
@@ -169,6 +197,18 @@
     }
   };
   attach("webmcp", webmcp);
+  function appRefFromPage(el) {
+    const ds = el && el.dataset || {};
+    if (ds.owner && ds.app) return { owner: ds.owner, appId: ds.app };
+    try {
+      const node = document.getElementById("aimeat-app-ref");
+      if (!node) return null;
+      const ref = JSON.parse(node.textContent || "{}");
+      if (ref.owner && ref.app_id) return { owner: ref.owner, appId: ref.app_id };
+    } catch {
+    }
+    return null;
+  }
   try {
     const el = (
       /** @type {any} */
@@ -181,6 +221,12 @@
         webmcp.exposeNodeTools().catch(function() {
         });
       }, 0);
+    } else if (expose === "app") {
+      const ref = appRefFromPage(el);
+      if (ref) setTimeout(function() {
+        webmcp.exposeAppTools(ref).catch(function() {
+        });
+      }, 0);
     }
   } catch {
   }

package/dist/static/sdk-libs/exchange/browse.js

@@ -0,0 +1,81 @@
+/**
+ * @file exchange/browse.js
+ * @description The BROWSE half of AIMEAT.exchange — reading the market. Every call here maps to a
+ *   route the node publishes without authentication, so an app can render the catalogue, one
+ *   listing's full decision context, and its ODPS v4.1 descriptor to a signed-out visitor. The
+ *   session is sent when there is one (see client.js `maybe`) purely so a seller's own projections
+ *   are fresh; it changes what is CURRENT, never what is VISIBLE.
+ * @structure info() · list(filter) · search(q, filter) · get(id) · odps(id) · odpsYaml(id)
+ * @usage const { offerings } = await AIMEAT.exchange.list({ q: 'company', stats: true });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+import { pub, pubText, maybe, qs } from './client.js';
+
+const enc = encodeURIComponent;
+
+/**
+ * The marketplace's public economics: `{ rake_percent, rake_note, units, morsel_note }` — what the
+ * platform takes on each metered call, set by the node operator. Show it BEFORE a seller prices
+ * something, so the split is stated rather than discovered on the first sale.
+ * @returns {Promise<any>}
+ */
+export function info() {
+  return pub('/v1/exchange/info', 'Failed to read the EXCHANGE economics');
+}
+
+/**
+ * Browse listed offerings. Every supplied filter NARROWS, independently.
+ * @param {{ ext?: string, action?: string, q?: string, stats?: boolean }} [filter]
+ *   `q` free-text over title/description/coordinate/tags; `stats: true` folds each listing's usage
+ *   (contracts, calls, consumers, settled units, observed p50/p95) into the row.
+ * @returns {Promise<{ offerings: any[], count: number }>}
+ */
+export function list(filter) {
+  const f = filter || {};
+  const query = qs({ ext: f.ext, action: f.action, q: f.q, stats: f.stats ? '1' : null });
+  return maybe('/v1/exchange/offerings' + query, 'Failed to browse the marketplace');
+}
+
+/**
+ * Free-text search — the same route as {@link list}, named for what an app's search box does.
+ * @param {string} q
+ * @param {{ ext?: string, action?: string, stats?: boolean }} [filter]
+ * @returns {Promise<{ offerings: any[], count: number }>}
+ */
+export function search(q, filter) {
+  return list({ ...(filter || {}), q });
+}
+
+/**
+ * One offering in FULL: `{ offering, capability, call_recipe, stats, pacing, odps }` — the I/O
+ * schema, how to call it (the contract IS the access; no API key is issued), what it costs per call
+ * in morsels burned for pacing on top of the price, the observed usage, and a pointer to the ODPS
+ * document. One call, so an app need not stitch four.
+ * @param {string} id  Offering id (`off-…`).
+ * @returns {Promise<any>}
+ */
+export function get(id) {
+  return pub('/v1/exchange/offerings/' + enc(id), 'No such offering');
+}
+
+/**
+ * The offering as an Open Data Product Specification v4.1 document (JSON) — the interoperable
+ * descriptor an outside catalogue or a negotiating agent reads without knowing anything about
+ * AIMEAT. Derived on read, so it cannot drift from the listing it describes.
+ * @param {string} id
+ * @returns {Promise<{ odps_version: string, odps: any }>}
+ */
+export function odps(id) {
+  return pub('/v1/exchange/offerings/' + enc(id) + '/odps', 'No such offering');
+}
+
+/**
+ * The same ODPS v4.1 document in the spec's native YAML, as raw text — what you hand to a catalogue
+ * that expects the file, or show in a "copy this descriptor" box.
+ * @param {string} id
+ * @returns {Promise<string>}
+ */
+export function odpsYaml(id) {
+  return pubText('/v1/exchange/offerings/' + enc(id) + '/odps.yaml', 'No such offering');
+}

package/dist/static/sdk-libs/exchange/client.js

@@ -0,0 +1,131 @@
+/**
+ * @file exchange/client.js
+ * @description Shared fetch plumbing for the aimeat-exchange library. EXCHANGE is a two-sided market
+ *   whose read surface is deliberately PUBLIC (browsing a listing, its ODPS document and its stats
+ *   needs no account) while every write and every "mine" read is authorised. So there are three call
+ *   shapes rather than one: `pub` (never sends a session), `authed` (requires one — the auth guard
+ *   names this library in its error) and `maybe` (sends the session when there is one). `maybe` is not
+ *   a convenience: GET /v1/exchange/offerings reconciles the CALLER's own projections before it
+ *   answers, so a signed-in seller browsing the market sees their own listings up to date, and a
+ *   signed-out visitor still gets the market.
+ *   SECURITY: this file carries no credentials of its own. It sends the aimeat-auth session and
+ *   renders what comes back — who may see what is the server's decision, never this library's.
+ * @structure exchangeError(res, fallback) · qs(params) · pub(path) · authed(path, opts) ·
+ *   maybe(path) · hasSession()
+ * @usage import { authed, pub, qs, exchangeError } from './client.js';
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+import { APEX_URL } from '../_core/config.js';
+import { makeSession } from '../_core/session.js';
+
+const NODE_URL = APEX_URL;
+const { authFetch } = makeSession('aimeat-exchange.js');
+
+/**
+ * Build an Error from a failed envelope, preserving the machine-readable code so callers can branch
+ * on it (`SOURCE_MANAGED`, `SCHEMA_REQUIRED`, `USAGE_TERMS_REQUIRED`, `NOT_PRICED`, `BUDGET_TOO_LOW`
+ * …) instead of matching on message text. EXCHANGE refusals are mostly *actionable* — they say which
+ * field the provider must publish — so the message is kept verbatim.
+ * @param {any} res            The parsed envelope.
+ * @param {string} fallback    Message to use when the envelope carries none.
+ * @returns {Error & { code?: string, details?: unknown }}
+ */
+export function exchangeError(res, fallback) {
+  const e = /** @type {Error & { code?: string, details?: unknown }} */ (
+    new Error((res && res.error && res.error.message) || fallback));
+  e.code = res && res.error && res.error.code;
+  e.details = res && res.error && res.error.details;
+  return e;
+}
+
+/**
+ * Serialise a query object, dropping null/undefined/'' so an unset filter is not sent as an empty
+ * one (the offerings route treats every supplied filter as a NARROWING term).
+ * @param {Record<string, string|number|boolean|null|undefined>} [params]
+ * @returns {string}  `?a=1&b=2`, or '' when nothing is set.
+ */
+export function qs(params) {
+  const parts = [];
+  for (const k of Object.keys(params || {})) {
+    const v = params[k];
+    if (v === null || v === undefined || v === '') continue;
+    parts.push(encodeURIComponent(k) + '=' + encodeURIComponent(String(v)));
+  }
+  return parts.length ? '?' + parts.join('&') : '';
+}
+
+/** True when aimeat-auth is loaded AND someone is signed in — never throws. */
+export function hasSession() {
+  try {
+    const auth = window.AIMEAT && window.AIMEAT.auth;
+    return !!(auth && auth.getSession());
+  } catch { return false; }
+}
+
+/**
+ * A PUBLIC read — no session, ever. Used for the browse surface so a signed-out visitor sees the
+ * market exactly as the node publishes it.
+ * @param {string} path
+ * @param {string} fallback  Error message when the envelope carries none.
+ * @returns {Promise<any>}   The envelope's `data`.
+ */
+export async function pub(path, fallback) {
+  const r = await fetch(NODE_URL + path);
+  const res = await r.json();
+  if (!res.ok) throw exchangeError(res, fallback);
+  return res.data;
+}
+
+/** A PUBLIC read that returns raw text rather than an envelope (the ODPS `.yaml` projection). */
+export async function pubText(path, fallback) {
+  const r = await fetch(NODE_URL + path);
+  const text = await r.text();
+  if (!r.ok) {
+    let parsed = null;
+    try { parsed = JSON.parse(text); } catch { /* a non-envelope error body — fall through */ }
+    throw exchangeError(parsed, fallback);
+  }
+  return text;
+}
+
+/**
+ * An AUTHORISED call — the session's own fetch (bearer token, refresh on 401, scope self-heal).
+ * @param {string} path
+ * @param {RequestInit} [opts]
+ * @param {string} [fallback]
+ * @returns {Promise<any>}  The envelope's `data`.
+ */
+export async function authed(path, opts, fallback) {
+  const res = await authFetch(path, opts);
+  if (!res.ok) throw exchangeError(res, fallback || 'EXCHANGE request failed');
+  return res.data;
+}
+
+/**
+ * A public read that SENDS the session when there is one. Signed in, the offerings route brings the
+ * caller's own projections up to date before answering; signed out, the same call still returns the
+ * public market.
+ * @param {string} path
+ * @param {string} fallback
+ * @returns {Promise<any>}
+ */
+export async function maybe(path, fallback) {
+  if (!hasSession()) return pub(path, fallback);
+  try {
+    return await authed(path, undefined, fallback);
+  } catch (e) {
+    // A stale or scope-short session must never turn a PUBLIC surface into an error page.
+    if (e && (e.code === 'UNAUTHORIZED' || e.code === 'FORBIDDEN')) return pub(path, fallback);
+    throw e;
+  }
+}
+
+/** POST/DELETE helper: JSON body, authorised. */
+export function send(path, method, body, fallback) {
+  const opts = /** @type {RequestInit} */ ({ method });
+  if (body !== undefined) opts.body = JSON.stringify(body);
+  return authed(path, opts, fallback);
+}
+
+export { NODE_URL };

package/dist/static/sdk-libs/exchange/contracts.js

@@ -0,0 +1,228 @@
+/**
+ * @file exchange/contracts.js
+ * @description The BUY half of AIMEAT.exchange — accepting a contract, seeing what it has consumed,
+ *   turning it off, renegotiating it, and (for agent-work) starting and receiving a task.
+ *
+ *   A contract here is a metered entitlement: the consumer chooses only their BUDGET, the per-call
+ *   price is read authoritatively from the provider. That is why `accept` takes an offering id and a
+ *   cap rather than a price — a price sent from a browser would be a price a buyer set for a seller.
+ * @structure contracts() · accept(offeringId, opts) · off(contract, opts) · history() · spend() ·
+ *   proposals() · propose(spec) · acceptProposal/declineProposal/withdrawProposal ·
+ *   startWork(spec) · deliverWork(id, spec) · work(opts) · coordinateOf
+ * @usage const c = await AIMEAT.exchange.accept('off-abc123', { capUnits: 500 });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+import { authed, send, qs, exchangeError } from './client.js';
+import { get as getOffering } from './browse.js';
+
+const enc = encodeURIComponent;
+
+function compact(obj) {
+  const out = {};
+  for (const k of Object.keys(obj)) if (obj[k] !== undefined) out[k] = obj[k];
+  return out;
+}
+function pick(...vals) {
+  for (const v of vals) if (v !== undefined && v !== null) return v;
+  return undefined;
+}
+
+/**
+ * Every contract the caller's OWNER holds, with what each has consumed: budget cap, spent, calls
+ * remaining, the pricing model, the pacing toll it was signed at, the rake, and `callers` — which
+ * of the owner's principals ran it up.
+ * @returns {Promise<{ entitlements: any[] }>}
+ */
+export function contracts() {
+  return authed('/v1/exchange/entitlements', undefined, 'Failed to read your contracts');
+}
+
+/**
+ * Accept a contract for a listed offering → mint the durable entitlement the metered gateway then
+ * honours on every call. You choose the budget; the provider's price is authoritative.
+ * @param {string} offeringId
+ * @param {{ capUnits?: number|null, appId?: string, planId?: string, contractRef?: string,
+ *           escrowParty?: 'consumer'|'provider' }} [opts]
+ *   `capUnits` is YOUR spend ceiling in the offering's unit (money micro-units or morsels); omit for
+ *   uncapped. Below one charge it is refused with `BUDGET_TOO_LOW` rather than minted unusable.
+ *   `planId` picks a provider-declared bundle/subscription plan.
+ * @returns {Promise<any>}  The minted contract.
+ */
+export async function accept(offeringId, opts) {
+  const o = /** @type {Record<string, any>} */ (opts || {});
+  const d = await send('/v1/exchange/entitlements', 'POST', compact({
+    offering_id: offeringId,
+    cap_units: pick(o.capUnits, o.cap_units),
+    app_id: pick(o.appId, o.app_id),
+    plan_id: pick(o.planId, o.plan_id),
+    contract_ref: pick(o.contractRef, o.contract_ref),
+    escrow_party: pick(o.escrowParty, o.escrow_party),
+  }), 'Failed to accept the contract');
+  return d.entitlement;
+}
+
+/**
+ * Resolve whatever an app is holding — a contract row, an offering detail, an offering id, or a
+ * plain `{ ext, action }` — into the metered coordinate the off-switch and proposals key on.
+ * @param {any} contract
+ * @returns {Promise<{ ext: string, action: string }>}
+ */
+export async function coordinateOf(contract) {
+  if (typeof contract === 'string') {
+    // An offering id (`off-…`); anything else cannot be resolved without a coordinate.
+    const d = await getOffering(contract);
+    return { ext: d.offering.ext, action: d.offering.action };
+  }
+  const c = contract || {};
+  const ext = c.ext || (c.offering && c.offering.ext);
+  const action = c.action || (c.offering && c.offering.action);
+  if (!ext || !action) {
+    throw exchangeError({ error: { code: 'BAD_REQUEST', message:
+      'Name the contract by its capability coordinate ({ ext, action }), a contract row from contracts(), or an offering id.' } },
+    'Unresolvable contract reference');
+  }
+  return { ext, action };
+}
+
+/**
+ * The consumer's OFF-SWITCH. `pause` is reversible (re-accepting resumes it and carries the spend
+ * forward); `revoke` is terminal. Only the contract's own consumer may.
+ * @param {any} contract  A contract row, an offering id, or `{ ext, action }`.
+ * @param {{ mode?: 'pause'|'revoke' }} [opts]  Default `pause`.
+ * @returns {Promise<any>}
+ */
+export async function off(contract, opts) {
+  const { ext, action } = await coordinateOf(contract);
+  return send('/v1/exchange/entitlements/off', 'POST', {
+    ext, action, mode: (opts && opts.mode) === 'revoke' ? 'revoke' : 'pause',
+  }, 'Failed to switch the contract off');
+}
+
+/**
+ * Your PAST (archived / superseded) contracts as a CONSUMER — the terms a renegotiation replaced.
+ * @returns {Promise<{ history: any[], count: number }>}
+ */
+export function history() {
+  return authed('/v1/exchange/entitlements/history', undefined, 'Failed to read your contract history');
+}
+
+/**
+ * What you have spent OUTBOUND, per provider and per unit. DERIVED, not a server endpoint: the node
+ * aggregates the SELLER's side (offering stats, consumer lineage, earnings) and exposes the buyer's
+ * side only per app (`GET /v1/apps/cost?app_id=…`), so this folds the caller's own contracts — the
+ * same records the per-app view reads — into one figure. It therefore counts exactly what the
+ * caller's OWNER holds a contract for, and nothing about another of their accounts.
+ * @returns {Promise<{ byProvider: any[], byUnit: Record<string, { spentUnits: number, calls: number, contracts: number }>,
+ *                     totalCalls: number, totalContracts: number }>}
+ */
+export async function spend() {
+  const { entitlements } = await contracts();
+  const byUnit = /** @type {Record<string, { spentUnits: number, calls: number, contracts: number }>} */ ({});
+  const providers = /** @type {Record<string, any>} */ ({});
+  let totalCalls = 0;
+  for (const e of entitlements || []) {
+    const rail = e.unit === 'money' ? (e.currency || 'EUR') : 'morsels';
+    const u = byUnit[rail] || (byUnit[rail] = { spentUnits: 0, calls: 0, contracts: 0 });
+    u.spentUnits += e.budget ? e.budget.spent_units : 0;
+    u.calls += e.budget ? e.budget.calls : 0;
+    u.contracts += 1;
+    totalCalls += e.budget ? e.budget.calls : 0;
+
+    const key = e.provider + '|' + rail;
+    const p = providers[key] || (providers[key] = {
+      provider: e.provider, unit: rail, spentUnits: 0, calls: 0, contracts: 0, capabilities: [],
+    });
+    p.spentUnits += e.budget ? e.budget.spent_units : 0;
+    p.calls += e.budget ? e.budget.calls : 0;
+    p.contracts += 1;
+    if (p.capabilities.indexOf(e.capability) === -1) p.capabilities.push(e.capability);
+  }
+  const byProvider = Object.keys(providers).map(k => providers[k])
+    .sort((a, b) => b.spentUnits - a.spentUnits);
+  return { byProvider, byUnit, totalCalls, totalContracts: (entitlements || []).length };
+}
+
+// ── Renegotiation ────────────────────────────────────────────────────────────
+
+/**
+ * Every contract-change proposal you are party to (incoming and outgoing).
+ * @returns {Promise<{ proposals: any[], count: number }>}
+ */
+export function proposals() {
+  return authed('/v1/exchange/proposals', undefined, 'Failed to read proposals');
+}
+
+/**
+ * Propose new terms on a live contract. Either party may: a consumer renegotiates their own, a
+ * provider renegotiates a named consumer's (`consumerGaii`). Nothing changes until the counterparty
+ * accepts; they are notified in Profile > Messages.
+ * @param {{ ext?: string, action?: string, contract?: any, consumerGaii?: string,
+ *           newPricePerCall?: number, newCapUnits?: number, note?: string }} spec
+ * @returns {Promise<any>}  The pending proposal.
+ */
+export async function propose(spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  const { ext, action } = await coordinateOf(s.contract || { ext: s.ext, action: s.action });
+  const d = await send('/v1/exchange/proposals', 'POST', compact({
+    ext, action,
+    consumer_gaii: pick(s.consumerGaii, s.consumer_gaii),
+    new_price_per_call: pick(s.newPricePerCall, s.new_price_per_call),
+    new_cap_units: pick(s.newCapUnits, s.new_cap_units),
+    note: s.note,
+  }), 'Failed to propose new terms');
+  return d.proposal;
+}
+
+/** The COUNTERPARTY accepts → the old contract is archived and a new one minted at the new terms. */
+export function acceptProposal(id) {
+  return send('/v1/exchange/proposals/' + enc(id) + '/accept', 'POST', {}, 'Failed to accept the proposal');
+}
+/** The counterparty declines — the contract is unchanged. */
+export function declineProposal(id) {
+  return send('/v1/exchange/proposals/' + enc(id) + '/decline', 'POST', {}, 'Failed to decline the proposal');
+}
+/** The PROPOSER withdraws their own pending proposal. */
+export function withdrawProposal(id) {
+  return send('/v1/exchange/proposals/' + enc(id) + '/withdraw', 'POST', {}, 'Failed to withdraw the proposal');
+}
+
+// ── Agent work (the async surface — settled per delivered task) ───────────────
+
+/**
+ * Start a task under an agent-work contract. Nothing is charged yet: the per-task price is metered
+ * when the provider DELIVERS. Without an active contract this is refused with `NO_CONTRACT` (402).
+ * @param {{ offeringId: string, input?: any, note?: string }} spec
+ * @returns {Promise<any>}  The open work item.
+ */
+export async function startWork(spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  const d = await send('/v1/exchange/work', 'POST', compact({
+    offering_id: pick(s.offeringId, s.offering_id), input: s.input, note: s.note,
+  }), 'Failed to start the work');
+  return d.work;
+}
+
+/**
+ * Deliver a task you were commissioned for → settle on delivery (the consumer is charged, you are
+ * credited its cut, the rake routed, the budget decremented).
+ * @param {string} id
+ * @param {{ output?: any, note?: string }} [spec]
+ * @returns {Promise<any>}  The delivered work item.
+ */
+export async function deliverWork(id, spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  const d = await send('/v1/exchange/work/' + enc(id) + '/deliver', 'POST',
+    compact({ output: s.output, note: s.note }), 'Failed to deliver the work');
+  return d.work;
+}
+
+/**
+ * Your agent-work items. `{ role: 'provider' }` for work commissioned FROM you; default is work you
+ * commissioned.
+ * @param {{ role?: 'consumer'|'provider' }} [opts]
+ * @returns {Promise<{ work: any[], count: number, role: string }>}
+ */
+export function work(opts) {
+  return authed('/v1/exchange/work' + qs({ role: opts && opts.role }), undefined, 'Failed to read your work items');
+}