aimeat 2.0.0 → 2.1.0

package/dist/static/sdk-libs/_core/config.js

@@ -0,0 +1,52 @@
+/**
+ * @file config.js
+ * @description Shared SDK-libs core — resolves the node URL, apex URL, node id and heartbeat
+ *   interval for every served AIMEAT browser helper library. Replaces the NODE_URL / APEX_URL /
+ *   NODE_ID bootstrap that was copy-pasted (as JS-inside-a-template-string) into ~13 libs. The
+ *   node-URL resolution order is preserved EXACTLY from the legacy libs:
+ *   `<meta name="aimeat-node">` → `location.origin` (http/https) → the node-provided fallback,
+ *   which is now injected as `window.__AIMEAT_SDK_CFG__` by a tiny prelude the route prepends at
+ *   serve time (in place of the old build-time `${config.baseUrl}` interpolation).
+ * @structure resolveNodeUrl() · NODE_URL · APEX_URL · NODE_ID · HEARTBEAT_MS
+ * @usage import { NODE_URL, APEX_URL, NODE_ID } from '../_core/config.js';
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — Initial: extracted from the per-lib inline bootstrap (SDK-libs migration Phase 0).
+ */
+
+/**
+ * @typedef {Object} SdkConfig
+ * @property {string} nodeId    Node id baked by the serving node.
+ * @property {string} baseUrl   Apex base URL baked by the serving node.
+ * @property {number} [heartbeatMs] Personal-node heartbeat interval, in ms.
+ */
+
+/** @returns {SdkConfig} The serve-time config prelude, or empty defaults if absent. */
+function cfg() {
+  return window.__AIMEAT_SDK_CFG__ || { nodeId: '', baseUrl: '' };
+}
+
+/**
+ * Resolve the node URL this library talks to. Order is unchanged from the legacy per-lib bootstrap:
+ *   1. `<meta name="aimeat-node" content="…">` (trailing slash trimmed)
+ *   2. `location.origin` on http/https
+ *   3. the node-provided baseUrl fallback (serve-time prelude)
+ * @returns {string}
+ */
+export function resolveNodeUrl() {
+  const meta = document.querySelector('meta[name="aimeat-node"]');
+  if (meta) return (meta.getAttribute('content') || '').replace(/\/$/, '');
+  if (location.protocol === 'http:' || location.protocol === 'https:') return location.origin;
+  return cfg().baseUrl;
+}
+
+/** The resolved node URL, evaluated once at load — same timing as the legacy IIFE bootstrap. */
+export const NODE_URL = resolveNodeUrl();
+
+/** The apex base URL baked by the serving node (used for the H-2 app-origin bridge). */
+export const APEX_URL = cfg().baseUrl;
+
+/** The serving node's id. */
+export const NODE_ID = cfg().nodeId;
+
+/** Personal-node heartbeat interval in ms (default 30000 — matches lib-tunnel's legacy default). */
+export const HEARTBEAT_MS = cfg().heartbeatMs || 30000;

package/dist/static/sdk-libs/_core/http.js

@@ -0,0 +1,52 @@
+/**
+ * @file http.js
+ * @description Shared SDK-libs core — the envelope-aware fetch helpers every library rolled its
+ *   own copy of. `api()` performs a JSON fetch against the resolved node URL, unwraps the AIMEAT
+ *   response envelope, and — critically — preserves the machine-readable `err.code` / `err.details`
+ *   on the thrown Error (the sign-in modal branches on `EMAIL_NOT_VERIFIED` etc. rather than
+ *   matching on message text). `authApi()` adds a bearer token. Behavior is identical to the
+ *   `api()` / `authApi()` that lived inline in auth-lib-part1.
+ * @structure api(path, opts) · authApi(path, jwt, opts)
+ * @usage import { api, authApi } from '../_core/http.js';
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — Initial: extracted from the per-lib inline fetch helpers (SDK-libs migration Phase 0).
+ */
+import { NODE_URL } from './config.js';
+
+/**
+ * An Error carrying the envelope's machine-readable code + details.
+ * @typedef {Error & { code?: string, details?: unknown }} ApiError
+ */
+
+/**
+ * Fetch `path` on the node, parse the JSON envelope, throw on `!ok` (preserving code/details).
+ * @param {string} path                 Path beginning with `/` (joined onto NODE_URL).
+ * @param {RequestInit} [opts]          Standard fetch options; JSON content-type is added.
+ * @returns {Promise<any>}              The full parsed envelope (`{ ok, data, error, … }`).
+ */
+export async function api(path, opts = {}) {
+  const url = NODE_URL + path;
+  const headers = { 'Content-Type': 'application/json', ...opts.headers };
+  const resp = await fetch(url, { ...opts, headers });
+  const data = await resp.json();
+  if (!data.ok) {
+    // Preserve the machine-readable code + details on the thrown Error so callers can branch
+    // (e.g. EMAIL_NOT_VERIFIED → open the email-completion flow) instead of matching on text.
+    const err = /** @type {ApiError} */ (new Error(data.error?.message || 'API error'));
+    err.code = data.error?.code;
+    err.details = data.error?.details;
+    throw err;
+  }
+  return data;
+}
+
+/**
+ * As {@link api}, with an `Authorization: Bearer <jwt>` header.
+ * @param {string} path
+ * @param {string} jwt
+ * @param {RequestInit} [opts]
+ * @returns {Promise<any>}
+ */
+export async function authApi(path, jwt, opts = {}) {
+  return api(path, { ...opts, headers: { ...opts.headers, 'Authorization': 'Bearer ' + jwt } });
+}

package/dist/static/sdk-libs/_core/namespace.js

@@ -0,0 +1,33 @@
+/**
+ * @file namespace.js
+ * @description Shared SDK-libs core — the idempotent `window.AIMEAT` attach that ~21 libs each
+ *   re-implemented as `if (!global.AIMEAT) global.AIMEAT = {}; global.AIMEAT.x = x;`. `namespace()`
+ *   returns the (lazily created) global object; `attach(key, value)` mounts one library surface
+ *   onto it. Serving each bundle as a self-contained IIFE means load order between libs never
+ *   matters — whichever runs first creates `window.AIMEAT`, the rest extend it.
+ * @structure namespace() · attach(key, value)
+ * @usage import { attach } from '../_core/namespace.js';  attach('speech', speech);
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — Initial: extracted from the per-lib inline global attach (SDK-libs migration Phase 0).
+ */
+
+/**
+ * The global `window.AIMEAT` object, created on first use.
+ * @returns {Record<string, any>}
+ */
+export function namespace() {
+  if (!window.AIMEAT) window.AIMEAT = {};
+  return window.AIMEAT;
+}
+
+/**
+ * Mount one library surface onto `window.AIMEAT` (idempotent — last writer wins, as before).
+ * @param {string} key    The namespace key (e.g. `'speech'`, `'data'`).
+ * @param {any} value     The library object to expose.
+ * @returns {Record<string, any>}  The `window.AIMEAT` object.
+ */
+export function attach(key, value) {
+  const ns = namespace();
+  ns[key] = value;
+  return ns;
+}

package/dist/static/sdk-libs/_core/sdk-globals.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file sdk-globals.d.ts
+ * @description Ambient declarations for the browser globals the served SDK libraries touch that
+ *   are not on TypeScript's stock lib.dom `Window` — the webkit-prefixed / non-standard APIs
+ *   (webkitAudioContext, SpeechRecognition, webkitSpeechRecognition) plus the serve-time config
+ *   prelude (window.__AIMEAT_SDK_CFG__) and the window.AIMEAT namespace. Declaring them here keeps
+ *   checkJs honest at those exact call sites instead of erasing type-safety with per-site `any`
+ *   casts, and is shared by every lib (e.g. audio also needs webkitAudioContext).
+ * @usage Picked up by tsconfig.sdk.json (its include globs the sdk-libs .d.ts files). No runtime effect.
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — Initial: webkit audio/speech globals + SDK config prelude + AIMEAT namespace.
+ */
+
+interface Window {
+  // The AIMEAT namespace is assembled dynamically across ~21 libs (each attaches its own surface);
+  // there is no single static shape, so `any` is the honest type for cross-lib member access.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  AIMEAT?: Record<string, any>;
+  /** aimeat-agentface also exposes its surface under the convention's spec name. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  AIMEATAgentFace?: Record<string, any>;
+  /** Serve-time config prelude prepended to each bundle (see _core/config.js + libs/sdk-serve.ts). */
+  __AIMEAT_SDK_CFG__?: { nodeId: string; baseUrl: string; heartbeatMs?: number };
+  /** aimeat-auth's extra serve-time prelude: the OIDC providers enabled on the node (server-computed). */
+  __AIMEAT_AUTH_CFG__?: { providers: Array<{ id: string; label: string; i18nKey: string }> };
+  /** aimeat-header's idempotency guard (mounts the canonical nav at most once). */
+  __AIMEAT_HEADER_MOUNTED__?: boolean;
+  /** aimeat-auth version marker exposed globally. */
+  version?: string;
+  /** aimeat-auth password-reset flow: the username carried from step 1 to step 2. */
+  __aimeatResetUser?: string;
+  // Rich-renderer CDN globals loaded on demand by aimeat-markdown (markdown-it + plugins, DOMPurify,
+  // highlight.js, mermaid) — untyped external libraries, hence `any`.
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  markdownit?: any;
+  markdownitTaskLists?: any;
+  markdownitFootnote?: any;
+  DOMPurify?: any;
+  hljs?: any;
+  mermaid?: any;
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+  /** Safari's prefixed AudioContext. */
+  webkitAudioContext?: typeof AudioContext;
+  // SpeechRecognition / webkitSpeechRecognition have no lib.dom type; the instance API is accessed
+  // dynamically (lang/continuous/onresult/…), so the constructed value is intentionally `any`.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  SpeechRecognition?: new () => any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  webkitSpeechRecognition?: new () => any;
+}

package/dist/static/sdk-libs/_core/session.js

@@ -0,0 +1,66 @@
+/**
+ * @file session.js
+ * @description Shared SDK-libs core — the `AIMEAT.auth` session glue that data/storage/social/…
+ *   each re-implemented. `getSession()` asserts aimeat-auth.js is loaded and the user is signed in,
+ *   returning the live session object; `authFetch()` delegates to `session.fetch` (which injects the
+ *   bearer token, refreshes on 401, and self-heals scope drift). Behavior matches the inline
+ *   `getSession()` / `authFetch()` of the legacy libs.
+ * @structure getSession(libLabel?) · authFetch(path, opts, libLabel?) · makeSession(libLabel)
+ * @usage const { authFetch } = makeSession('aimeat-wallet.js'); // names the lib in the auth-missing error
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — Initial: extracted from the per-lib inline session glue (SDK-libs migration Phase 0).
+ *   v1.1.0 — 2026-07-20 — makeSession(libLabel) restores each lib's specific "before aimeat-<name>.js" auth-guard error (agent-locatable), preserving DRY.
+ */
+
+/**
+ * The live AIMEAT session object exposed by aimeat-auth.js. Only the members libs actually read
+ * are declared; it carries more (see aimeat-auth's createSession).
+ * @typedef {Object} AimeatSession
+ * @property {(path: string, opts?: RequestInit) => Promise<any>} fetch  Authed fetch → parsed envelope.
+ * @property {string} [jwt]
+ * @property {string} [ghii]   Full GHII/GAII of the signed-in principal.
+ * @property {string} [owner]  Bare owner name.
+ * @property {string} [displayName]
+ * @property {string[]} [roles]
+ */
+
+/**
+ * Return the current signed-in session, or throw a descriptive error. `libLabel` (the served
+ * filename, e.g. 'aimeat-wallet.js') is named in the "include aimeat-auth.js first" error so the
+ * message points at the exact lib — the locator an agent/dev needs to fix the load order.
+ * @param {string} [libLabel]
+ * @returns {AimeatSession}
+ */
+export function getSession(libLabel) {
+  const auth = window.AIMEAT && window.AIMEAT.auth;
+  if (!auth) {
+    throw new Error('AIMEAT.auth is required. Include aimeat-auth.js before ' + (libLabel || 'this library'));
+  }
+  const s = auth.getSession();
+  if (!s) throw new Error('Not logged in. Call AIMEAT.auth.login() first.');
+  return s;
+}
+
+/**
+ * Authed fetch against the node — delegates to the session's own `fetch` (token + refresh + heal).
+ * @param {string} path
+ * @param {RequestInit} [opts]
+ * @param {string} [libLabel]  The served filename, named in the auth-missing error.
+ * @returns {Promise<any>}  The parsed response envelope.
+ */
+export function authFetch(path, opts, libLabel) {
+  return getSession(libLabel).fetch(path, opts);
+}
+
+/**
+ * Bind the per-lib served filename once so each lib's auth-guard error names the specific file
+ * (e.g. "…before aimeat-wallet.js") instead of a generic "this library". Call sites stay unchanged.
+ * @param {string} libLabel  The served filename, e.g. 'aimeat-wallet.js'.
+ * @returns {{ getSession: () => AimeatSession, authFetch: (path: string, opts?: RequestInit) => Promise<any> }}
+ */
+export function makeSession(libLabel) {
+  return {
+    getSession: () => getSession(libLabel),
+    authFetch: (path, opts) => authFetch(path, opts, libLabel),
+  };
+}

package/dist/static/sdk-libs/agentface/index.js

@@ -0,0 +1,102 @@
+/**
+ * @file agentface/index.js
+ * @description The aimeat-agentface library (SDK-libs migration Phase 1). Publishes an app's Agent
+ *   Face — the markdown read-surface agents get on the app URL via Accept: text/markdown — in one
+ *   call from inside the running app: publish() composes markdown (raw string or { title, sections }),
+ *   infers the app filename (opts.app > <meta name="aimeat-app"> > the /v1/apps/{owner}/{file} path),
+ *   and writes the public record apps.{filename}.agentface via the authenticated memory API. Exposed
+ *   as BOTH AIMEAT.agentface (house convention) and AIMEATAgentFace (spec name). Componentized ESM
+ *   source esbuild bundles to the IIFE served, unchanged, at /v1/libs/aimeat-agentface.js. Ported
+ *   verbatim from lib-agentface.ts — the bespoke auth-guard messages are preserved (they teach the
+ *   app-owner-only serving rule), so getSession stays inline rather than using _core/session.
+ * @structure imports attach (namespace); getSession/compose/inferFilename; the `agentface` object
+ *   (key/compose/publish); attach('agentface', …) + window.AIMEATAgentFace.
+ * @usage <script src="/v1/libs/aimeat-auth.js"></script><script src="/v1/libs/aimeat-agentface.js"></script>
+ *   await AIMEATAgentFace.publish('# My app\n\n…', { app: 'my-app.html' });
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — Migrated from src/routes/lib-agentface.ts (SDK-libs migration Phase 1).
+ */
+import { attach } from '../_core/namespace.js';
+
+const MAX_BYTES = 256 * 1024; // the convention cap — the node treats an oversize face as absent
+
+function getSession() {
+  const auth = window.AIMEAT && window.AIMEAT.auth;
+  if (!auth) {
+    throw new Error('AIMEAT.auth is required. Include aimeat-auth.js before aimeat-agentface.js');
+  }
+  const s = auth.getSession();
+  if (!s) {
+    throw new Error('Not signed in. AIMEATAgentFace.publish writes the face as the signed-in user — call AIMEAT.auth.login() first. Note: the node serves only the record written by the APP OWNER; another user\'s publish lands in their own namespace and is never served.');
+  }
+  return s;
+}
+
+/** Compose { title, sections: [{ heading, body }] } into a markdown document. */
+function compose(doc) {
+  if (!doc || typeof doc !== 'object') {
+    throw new Error('compose expects { title, sections: [{ heading, body }] }');
+  }
+  const parts = [];
+  if (doc.title) parts.push('# ' + String(doc.title).trim());
+  const sections = Array.isArray(doc.sections) ? doc.sections : [];
+  for (const s of sections) {
+    if (!s || typeof s.heading !== 'string' || !s.heading.trim()) {
+      throw new Error('Every section needs a non-empty string heading');
+    }
+    parts.push('## ' + s.heading.trim() + '\n\n' + (typeof s.body === 'string' ? s.body.trim() : ''));
+  }
+  if (parts.length === 0) throw new Error('Nothing to compose — provide a title and/or sections');
+  return parts.join('\n\n') + '\n';
+}
+
+/** Derive this app's filename: <meta name="aimeat-app">, else the /v1/apps/{owner}/{file} path. */
+function inferFilename() {
+  const meta = typeof document !== 'undefined' && document.querySelector('meta[name="aimeat-app"]');
+  const fromMeta = meta && meta.getAttribute('content');
+  if (fromMeta && fromMeta.trim()) return fromMeta.trim();
+  const m = typeof location !== 'undefined' && location.pathname.match(/\/v1\/apps\/[^/]+\/([^/?#]+\.html?)$/i);
+  if (m) return decodeURIComponent(m[1]);
+  return null;
+}
+
+const agentface = {
+  /** The convention memory key the face lives under. */
+  key(filename) { return 'apps.' + filename + '.agentface'; },
+
+  /** The markdown composer (exposed so an app can preview what publish() will write). */
+  compose: compose,
+
+  /**
+   * Publish this app's agent face: a markdown string, or { title, sections: [{ heading, body }] }.
+   * opts.app names the app filename explicitly (e.g. 'my-app.html') and overrides inference —
+   * pass it on per-app subdomain origins, where the filename is not derivable from the URL.
+   * Writes the public record apps.{filename}.agentface via the authenticated memory API.
+   */
+  async publish(input, opts) {
+    opts = opts || {};
+    const markdown = typeof input === 'string' ? input : compose(input);
+    if (!markdown.trim()) throw new Error('AIMEATAgentFace.publish: the markdown content is empty');
+    if (new TextEncoder().encode(markdown).length > MAX_BYTES) {
+      throw new Error('Agent face exceeds the 256 KB cap — the node would treat it as absent. Publish a summary and link out to records instead.');
+    }
+    const filename = typeof opts.app === 'string' && opts.app.trim() ? opts.app.trim() : inferFilename();
+    if (!filename) {
+      throw new Error('Cannot derive the app filename on this origin — pass { app: "your-file.html" } or add <meta name="aimeat-app" content="your-file.html"> to the page');
+    }
+    const session = getSession();
+    const key = agentface.key(filename);
+    const res = await session.fetch('/v1/memory', {
+      method: 'POST',
+      body: JSON.stringify({ key: key, value: markdown, visibility: 'public' }),
+    });
+    if (!res.ok) {
+      throw new Error((res.error && res.error.message) || 'Failed to publish the agent face');
+    }
+    return { key: key, app: filename, version: res.data && res.data.version, visibility: 'public' };
+  },
+};
+
+// ── Expose globally: house convention + the convention's spec name ──
+attach('agentface', agentface);
+window.AIMEATAgentFace = agentface;

package/dist/static/sdk-libs/agents/index.js

@@ -0,0 +1,267 @@
+/**
+ * @file agents/index.js
+ * @description The aimeat-agents library (SDK-libs migration Phase 1). Exposes AIMEAT.agents — the
+ *   owner-side helper an AIMEAT app uses to commission and observe the owner's agents: list/get,
+ *   createTask/run, getTask/tasks/events, watch (SSE + poll fallback), deliverable/memory,
+ *   pendingPrompts/answerPrompt, and cooperative cancelTask/cancelRun/cancelledTaskIds. All over the
+ *   AIMEAT.auth session. Componentized ESM source esbuild bundles to the IIFE served, unchanged, at
+ *   /v1/libs/aimeat-agents.js. Ported verbatim from lib-agents.ts.
+ * @structure imports authFetch (session) + attach (namespace); unwrap() envelope helper; the
+ *   `agents` object; attach('agents', …). Errors throw with a `.code` (NOT_FOUND/FORBIDDEN/UNKNOWN/TIMEOUT).
+ * @usage <script src="/v1/libs/aimeat-auth.js"></script><script src="/v1/libs/aimeat-agents.js"></script>
+ *   const { task, deliverable } = await AIMEAT.agents.run('my-agent', { description: '…' });
+ * @version-history
+ *   v1.0.0 — 2026-07-19 — Migrated from src/routes/lib-agents.ts (SDK-libs migration Phase 1).
+ */
+import { makeSession } from '../_core/session.js';
+const { authFetch } = makeSession('aimeat-agents.js');
+import { attach } from '../_core/namespace.js';
+
+var enc = encodeURIComponent;
+
+// session.fetch returns the parsed AIMEAT envelope { ok, data, error }.
+function unwrap(r, action) {
+  if (!r || !r.ok) {
+    var err = /** @type {Error & { code?: string }} */ (new Error((r && r.error && r.error.message) || (action + ' failed')));
+    err.code = (r && r.error && r.error.code) || 'UNKNOWN';
+    throw err;
+  }
+  return r.data;
+}
+
+// 30s cache for list() so apps can call it on every render cheaply.
+var _agentsCache = null;
+// 10s cache for the cancelled-task-id set.
+var _cancelSetCache = null;
+
+var agents = {
+  /** List the owner's agents. opts.activeOnly filters to ones seen recently.
+   *  opts.fresh bypasses the 30s cache. */
+  async list(opts) {
+    var now = Date.now();
+    if (!(opts && opts.fresh) && _agentsCache && (now - _agentsCache.t) < 30000) return _agentsCache.v;
+    var data = unwrap(await authFetch('/v1/agents'), 'list agents');
+    var v = data.agents || [];
+    _agentsCache = { v: v, t: now };
+    return (opts && opts.activeOnly) ? v.filter(function (a) { return !!a.last_seen; }) : v;
+  },
+
+  /** One agent by name (or GAII), or null. */
+  async get(name) {
+    var all = await agents.list();
+    return all.find(function (a) { return a.name === name || a.gaii === name; }) || null;
+  },
+
+  /** Commission a task for an agent. Returns the created task ({ id, status, ... }).
+   *  Created 'queued' by default; task-runner agents auto-activate it. */
+  async createTask(name, task) {
+    if (!task || !task.description) throw new Error('createTask requires { description }');
+    var body = {
+      title: task.title || task.description.slice(0, 80),
+      description: task.description,
+      status: task.status || 'queued',
+    };
+    var data = unwrap(await authFetch('/v1/agents/' + enc(name) + '/tasks', {
+      method: 'POST', body: JSON.stringify(body),
+    }), 'create task');
+    return data.task;
+  },
+
+  /** Get a single task. */
+  async getTask(name, id) {
+    return unwrap(await authFetch('/v1/agents/' + enc(name) + '/tasks/' + enc(id)), 'get task').task;
+  },
+
+  /** List an agent's tasks. opts.status filters (queued|active|done|failed|...). */
+  async tasks(name, opts) {
+    var q = '?per_page=100' + (opts && opts.status ? ('&status=' + enc(opts.status)) : '');
+    return unwrap(await authFetch('/v1/agents/' + enc(name) + '/tasks' + q), 'list tasks').tasks || [];
+  },
+
+  /** The task's event log (oldest-first). */
+  async events(name, id) {
+    return unwrap(await authFetch('/v1/agents/' + enc(name) + '/tasks/' + enc(id) + '/events'), 'list events').events || [];
+  },
+
+  /** Live-watch a task: calls onUpdate(task, events) on every server change
+   *  (SSE) plus a periodic poll as a safety net. Returns an unsubscribe fn. */
+  watch(name, id, onUpdate, opts) {
+    var stopped = false, es = null, pollTimer = null, debTimer = null;
+    var pollMs = (opts && opts.pollMs) || 15000;
+    async function refresh() {
+      if (stopped) return;
+      try {
+        var task = await agents.getTask(name, id);
+        var events = await agents.events(name, id);
+        if (!stopped && typeof onUpdate === 'function') onUpdate(task, events);
+      } catch { /* transient; the poll/next tick retries */ }
+    }
+    function debounced() { clearTimeout(debTimer); debTimer = setTimeout(refresh, 400); }
+    refresh();
+    pollTimer = setInterval(refresh, pollMs);
+    (async function () {
+      try {
+        var tk = unwrap(await authFetch('/v1/events/ticket', { method: 'POST' }), 'open event stream');
+        if (stopped || !tk || !tk.ticket) return;
+        es = new EventSource('/v1/events?ticket=' + enc(tk.ticket));
+        es.onmessage = debounced;
+      } catch { /* SSE unavailable — poll fallback already running */ }
+    })();
+    return function unsubscribe() {
+      stopped = true;
+      if (es) { try { es.close(); } catch { /* already closed */ } es = null; }
+      clearInterval(pollTimer); clearTimeout(debTimer);
+    };
+  },
+
+  /** Read the task's published deliverable (task.deliverableKey) from the
+   *  agent's memory. Returns { key, value } | { key, gone:true } | null. */
+  async deliverable(name, id) {
+    var task = await agents.getTask(name, id);
+    var key = task && task.deliverableKey;
+    if (!key) return null;
+    var data = unwrap(await authFetch('/v1/memory?agent=' + enc(task.agentGaii) + '&prefix=' + enc(key) + '&per_page=20'), 'read deliverable');
+    var items = data.items || [];
+    var found = items.find(function (i) { return i.key === key; });
+    return found ? { key: key, value: found.value } : { key: key, gone: true };
+  },
+
+  /** Read a specific memory entry under an agent's namespace (or null). */
+  async memory(name, key) {
+    var a = await agents.get(name);
+    var gaii = (a && a.gaii) || name;
+    var data = unwrap(await authFetch('/v1/memory?agent=' + enc(gaii) + '&prefix=' + enc(key) + '&per_page=20'), 'read agent memory');
+    var items = data.items || [];
+    var found = items.find(function (i) { return i.key === key; });
+    return found ? found.value : null;
+  },
+
+  /** Agent questions awaiting an answer: outbound option-prompts with no reply
+   *  yet. Each is { message_id, prompt_id, question, options, allow_other }. */
+  async pendingPrompts(name) {
+    var data = unwrap(await authFetch('/v1/agents/' + enc(name) + '/messages?per_page=100'), 'list messages');
+    var msgs = data.messages || [];
+    var answered = {};
+    msgs.forEach(function (m) {
+      var pa = m.metadata && (m.metadata.promptAnswer || m.metadata.prompt_answer);
+      var pid = pa && (pa.promptId || pa.prompt_id);
+      if (pid) answered[pid] = true;
+    });
+    var out = [];
+    msgs.forEach(function (m) {
+      if (m.direction !== 'outbound') return;
+      var p = m.metadata && m.metadata.prompt;
+      if (!p) return;
+      var pid = p.promptId || p.prompt_id;
+      if (!pid || answered[pid]) return;
+      out.push({
+        message_id: m.id,
+        prompt_id: pid,
+        question: p.question,
+        options: p.options || [],
+        allow_other: (p.allowOther != null ? p.allowOther : p.allow_other) !== false,
+      });
+    });
+    return out;
+  },
+
+  /** Answer an agent's option-prompt (owner -> agent). choice is the chosen
+   *  option text, or free text when is_other is true. */
+  async answerPrompt(name, ans) {
+    if (!ans || !ans.prompt_id || !ans.choice) throw new Error('answerPrompt requires { prompt_id, choice }');
+    return unwrap(await authFetch('/v1/agents/' + enc(name) + '/messages', {
+      method: 'POST',
+      body: JSON.stringify({
+        content: ans.choice,
+        direction: 'inbound',
+        metadata: { prompt_answer: { prompt_id: ans.prompt_id, choice: ans.choice, is_other: !!ans.is_other } },
+      }),
+    }), 'answer prompt');
+  },
+
+  /** Commission + watch until done/failed/stalled, then resolve
+   *  { task, deliverable }. Best for task-runner agents (which auto-activate).
+   *  opts: { onProgress(task, events), timeoutMs, pollMs }. */
+  async run(name, task, opts) {
+    var created = await agents.createTask(name, task);
+    var id = created.id;
+    return await new Promise(function (resolve, reject) {
+      var done = false, to = null;
+      var stop = agents.watch(name, id, async function (t, events) {
+        if (opts && opts.onProgress) { try { opts.onProgress(t, events); } catch { /* progress callback errors are non-fatal */ } }
+        if (!done && (t.status === 'done' || t.status === 'failed' || t.status === 'stalled')) {
+          done = true; if (to) clearTimeout(to); stop();
+          var deliverable = t.status === 'done' ? await agents.deliverable(name, id).catch(function () { return null; }) : null;
+          resolve({ task: t, deliverable: deliverable });
+        }
+      }, opts);
+      if (opts && opts.timeoutMs > 0) {
+        to = setTimeout(function () {
+          if (!done) { done = true; stop(); var e = /** @type {Error & { code?: string, taskId?: string }} */ (new Error('run() timed out')); e.code = 'TIMEOUT'; e.taskId = id; reject(e); }
+        }, opts.timeoutMs);
+      }
+    });
+  },
+
+  /** Cooperative-cancel a task. Writes a cancel marker the worker daemon
+   *  honours before its next kickoff (so abandoned/speculative subtasks never
+   *  start), AND, for immediate effect, natively pauses an active task or
+   *  deletes a queued one (owner-only ops; best-effort). Returns
+   *  { marked:true, native:'paused'|'deleted'|null }. */
+  async cancelTask(name, taskId, opts) {
+    await authFetch('/v1/memory', { method: 'POST', body: JSON.stringify({
+      key: 'agents.cancel.task.' + taskId,
+      value: [taskId],
+      visibility: 'owner',
+    }) });
+    var native = null;
+    try {
+      var t = await agents.getTask(name, taskId);
+      var st = t && t.status;
+      if (st === 'active') {
+        var r = await authFetch('/v1/agents/' + enc(name) + '/tasks/' + enc(taskId) + '/pause', { method: 'POST' });
+        if (r && r.ok) native = 'paused';
+      } else if (st === 'queued' || st === 'draft') {
+        var r2 = await authFetch('/v1/agents/' + enc(name) + '/tasks/' + enc(taskId), { method: 'DELETE' });
+        if (r2 && r2.ok) native = 'deleted';
+      }
+    } catch { /* native stop is best-effort; the marker still applies */ }
+    if (opts && opts.invalidate !== false) _cancelSetCache = null;
+    return { marked: true, native: native };
+  },
+
+  /** Cancel a whole run/batch: write one marker listing many task ids
+   *  (key agents.cancel.run.<run>). Workers union all agents.cancel.* markers. */
+  async cancelRun(run, taskIds) {
+    if (!run || !Array.isArray(taskIds)) throw new Error('cancelRun requires (run, taskIds[])');
+    await authFetch('/v1/memory', { method: 'POST', body: JSON.stringify({
+      key: 'agents.cancel.run.' + run,
+      value: taskIds.map(String),
+      visibility: 'owner',
+    }) });
+    _cancelSetCache = null;
+    return { marked: true, count: taskIds.length };
+  },
+
+  /** The set (array) of task ids cancelled via any agents.cancel.* marker
+   *  visible to the owner. 10s cache. */
+  async cancelledTaskIds(opts) {
+    var now = Date.now();
+    if (!(opts && opts.fresh) && _cancelSetCache && (now - _cancelSetCache.t) < 10000) return _cancelSetCache.v;
+    var data = unwrap(await authFetch('/v1/memory?owner_scope=true&prefix=' + enc('agents.cancel.') + '&per_page=100'), 'read cancel markers');
+    var set = {};
+    (data.items || []).forEach(function (it) {
+      var v = it.value;
+      if (Array.isArray(v)) v.forEach(function (x) { set[String(x)] = true; });
+      else if (v && typeof v === 'object') Object.keys(v).forEach(function (k) { set[k] = true; });
+    });
+    var v = Object.keys(set);
+    _cancelSetCache = { v: v, t: now };
+    return v;
+  },
+
+  /** Clear the cached agent list (call after creating/deleting an agent). */
+  invalidateCache() { _agentsCache = null; _cancelSetCache = null; },
+};
+
+attach('agents', agents);