@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/src/mcp/cloudflare-bundles.js

@@ -0,0 +1,225 @@
+/**
+ * Cloudflare-hosted MCP portal servers (tool bundles), not OAuth clients.
+ *
+ * Each entry is an MCP *server* you can register with `agentsam mcp add <name>`.
+ * OAuth consent stays granular via feature packs / capability ids — never the
+ * full ~315-scope catalog. Managing portals themselves needs mcp-portals.*.
+ */
+
+import {
+  scopesForCapabilities,
+  scopesForFeaturePacks,
+} from '../../packages/connectors/cloudflare/src/capabilities.js';
+
+/**
+ * @typedef {object} CloudflareMcpBundle
+ * @property {string} name
+ * @property {string} display_name
+ * @property {string} url
+ * @property {'none'|'bearer'|'cloudflare_portal_oauth'|'user_oauth_cloudflare'} auth_type
+ * @property {'streamable_http'|'sse'} protocol
+ * @property {string[]} feature_packs — AgentSam CF feature pack ids for AgentSam-side upgrade
+ * @property {string[]} capability_ids — finer granulation than packs
+ * @property {string[]} portal_manage_scopes — scopes to create/manage this portal via CF API
+ * @property {string} description
+ */
+
+/** @type {readonly CloudflareMcpBundle[]} */
+export const CLOUDFLARE_MCP_SERVER_BUNDLES = Object.freeze([
+  {
+    name: 'cloudflare-api',
+    display_name: 'Cloudflare API (Code Mode)',
+    url: 'https://mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: [],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Full CF API via search/execute tools — Cloudflare hosts OAuth for this portal',
+  },
+  {
+    name: 'cloudflare-docs',
+    display_name: 'Cloudflare Docs',
+    url: 'https://docs.mcp.cloudflare.com/mcp',
+    auth_type: 'none',
+    protocol: 'streamable_http',
+    feature_packs: [],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read'],
+    description: 'Cloudflare developer documentation reference',
+  },
+  {
+    name: 'cloudflare-bindings',
+    display_name: 'Cloudflare Workers Bindings',
+    url: 'https://bindings.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['data', 'compute', 'ai'],
+    capability_ids: [
+      'cloudflare.workers',
+      'cloudflare.d1',
+      'cloudflare.kv',
+      'cloudflare.r2',
+      'cloudflare.workers_ai',
+    ],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Workers storage, AI, and compute bindings',
+  },
+  {
+    name: 'cloudflare-builds',
+    display_name: 'Cloudflare Workers Builds',
+    url: 'https://builds.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['compute'],
+    capability_ids: ['cloudflare.workers'],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Workers Builds / CI insights (workers-ci.*)',
+  },
+  {
+    name: 'cloudflare-observability',
+    display_name: 'Cloudflare Observability',
+    url: 'https://observability.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['compute'],
+    capability_ids: ['cloudflare.workers'],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Workers observability / logs / analytics',
+  },
+  {
+    name: 'cloudflare-browser',
+    display_name: 'Cloudflare Browser Rendering',
+    url: 'https://browser.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['compute'],
+    capability_ids: ['cloudflare.browser_rendering'],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Fetch pages, markdown, screenshots',
+  },
+  {
+    name: 'cloudflare-logs',
+    display_name: 'Cloudflare Logpush',
+    url: 'https://logs.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['analytics'],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Logpush job health',
+  },
+  {
+    name: 'cloudflare-ai-gateway',
+    display_name: 'Cloudflare AI Gateway',
+    url: 'https://ai-gateway.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['ai'],
+    capability_ids: ['cloudflare.workers_ai'],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'AI Gateway request logs',
+  },
+  {
+    name: 'cloudflare-audit-logs',
+    display_name: 'Cloudflare Audit Logs',
+    url: 'https://auditlogs.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['analytics'],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Account audit log reports',
+  },
+  {
+    name: 'cloudflare-dns-analytics',
+    display_name: 'Cloudflare DNS Analytics',
+    url: 'https://dns-analytics.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['dns', 'analytics'],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'DNS performance analytics',
+  },
+  {
+    name: 'cloudflare-graphql',
+    display_name: 'Cloudflare GraphQL',
+    url: 'https://graphql.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['analytics'],
+    capability_ids: [],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Analytics via GraphQL',
+  },
+  {
+    name: 'cloudflare-containers',
+    display_name: 'Cloudflare Container Sandbox',
+    url: 'https://containers.mcp.cloudflare.com/mcp',
+    auth_type: 'cloudflare_portal_oauth',
+    protocol: 'streamable_http',
+    feature_packs: ['compute'],
+    capability_ids: ['cloudflare.containers'],
+    portal_manage_scopes: ['mcp-portals.read', 'mcp-portals.write'],
+    description: 'Ephemeral sandboxed containers',
+  },
+]);
+
+export function listCloudflareMcpBundles() {
+  return [...CLOUDFLARE_MCP_SERVER_BUNDLES];
+}
+
+export function getCloudflareMcpBundle(name) {
+  const key = String(name || '').trim().toLowerCase();
+  if (!key) return null;
+  return CLOUDFLARE_MCP_SERVER_BUNDLES.find((b) => b.name === key) || null;
+}
+
+/**
+ * Scopes AgentSam should request (or upgrade) so a CF-connected user can
+ * manage / use the portal surface — not Cloudflare's own portal OAuth dance.
+ */
+export function scopesForCloudflareMcpBundle(name, options = {}) {
+  const bundle = getCloudflareMcpBundle(name);
+  if (!bundle) return [];
+
+  const set = new Set();
+  if (options.includePortalManage !== false) {
+    for (const s of bundle.portal_manage_scopes || []) set.add(s);
+  }
+  for (const s of scopesForFeaturePacks(bundle.feature_packs || [], bundle.capability_ids || [])) {
+    set.add(s);
+  }
+  if (options.includeBaseline === false) {
+    // scopesForFeaturePacks always includes baseline; strip if caller asks
+    for (const s of ['account-settings.read', 'user-details.read', 'memberships.read', 'offline_access']) {
+      // keep offline_access — refresh still needed
+      if (s !== 'offline_access') set.delete(s);
+    }
+  }
+  return [...set];
+}
+
+/** Catalog rows for MCP authority (server presets). */
+export function cloudflareBundlesAsServerCatalog() {
+  return CLOUDFLARE_MCP_SERVER_BUNDLES.map((b) => ({
+    name: b.name,
+    display_name: b.display_name,
+    url: b.url,
+    auth_type: b.auth_type,
+    protocol: b.protocol,
+    defaultClients: ['cursor'],
+    health_status: 'unknown',
+    avg_latency_ms: null,
+    error_rate: null,
+    description: b.description,
+    feature_packs: b.feature_packs,
+    capability_ids: b.capability_ids,
+    portal_manage_scopes: b.portal_manage_scopes,
+    provider: 'cloudflare',
+    kind: 'mcp_portal_bundle',
+  }));
+}
+
+export { scopesForCapabilities, scopesForFeaturePacks };

package/src/mcp/index.js

@@ -22,6 +22,8 @@ export {
   DEFAULT_CLIENT_REGISTRY_URL,
   CLIENT_REGISTRY_CACHE_SCHEMA,
   SEED_EXTERNAL_CLIENT_REGISTRY,
+  SEED_OFFERABLE_MCP_SERVER_CONNECTIONS,
+  listOfferableMcpServerConnections,
   fetchExternalClientRegistry,
   listRegisteredClients,
   isClientRegistered,
@@ -37,8 +39,18 @@ export {
   pingMcpServer,
   listMcpTools,
   callMcpTool,
+  withMcpClient,
+  buildHeaders,
 } from './client.js';
 
+export {
+  CLOUDFLARE_MCP_SERVER_BUNDLES,
+  listCloudflareMcpBundles,
+  getCloudflareMcpBundle,
+  scopesForCloudflareMcpBundle,
+  cloudflareBundlesAsServerCatalog,
+} from './cloudflare-bundles.js';
+
 export {
   recordToolReceipt,
   getSessionToolReceipts,

package/src/models/ai-access-onboarding.js

@@ -0,0 +1,112 @@
+/**
+ * Onboarding guidance when a user has no usable AI path yet.
+ *
+ * Paths (any one unlocks AgentSam model options):
+ *   1. Local Ollama + at least one model
+ *   2. Provider API key (OpenAI / Anthropic / Gemini / …) → their allotted models
+ *   3. Signed-in Local Studio identity + Cloudflare OAuth (Workers AI / account tools)
+ */
+
+export const LOCAL_STUDIO_ORIGIN = 'https://agentsam.inneranimalmedia.com';
+
+/** Identity login (Sign in with Cloudflare) — PKCE public client. */
+export const CF_OAUTH_LOGIN_START = `${LOCAL_STUDIO_ORIGIN}/api/oauth/cloudflare/start?next=/agentsam`;
+
+/** Resource connector (MCP / Workers / D1) — same CF OAuth client, different callback. */
+export const CF_OAUTH_CONNECT_START = `${LOCAL_STUDIO_ORIGIN}/api/connections/cloudflare/start`;
+
+/** Login portal with explicit next (desktop / CLI). */
+export const LOCAL_STUDIO_LOGIN = `${LOCAL_STUDIO_ORIGIN}/auth/login?next=/agentsam`;
+
+/**
+ * Redirect URIs that must be registered on the Cloudflare OAuth client
+ * "AgentSam Local Studio" (PKCE, Token Authentication Method = None).
+ */
+export const CF_OAUTH_REQUIRED_REDIRECTS = Object.freeze([
+  `${LOCAL_STUDIO_ORIGIN}/api/oauth/cloudflare/callback`,
+  `${LOCAL_STUDIO_ORIGIN}/api/connections/cloudflare/callback`,
+  'http://localhost:3000/api/connections/cloudflare/callback',
+  'http://localhost:3000/api/oauth/cloudflare/callback',
+]);
+
+/**
+ * @param {{ inventory?: object, ollama?: object, providers?: object[] }} discovered
+ *   Shape compatible with discoverIngestModelOptions() / collectModelsStatus().
+ */
+export function assessAiAccess(discovered = {}) {
+  const providers = discovered.inventory?.providers
+    || discovered.providers
+    || [];
+  const configuredProviders = providers.filter((p) => p?.configured === true);
+  const ollamaOnline = Boolean(discovered.ollama?.online || discovered.inventory?.local?.online);
+  const ollamaModels = discovered.ollama?.models || discovered.inventory?.local?.models || [];
+  const hasOllamaModels = ollamaOnline && Array.isArray(ollamaModels) && ollamaModels.length > 0;
+  const hasProviderKeys = configuredProviders.length > 0;
+  const embedOptions = Array.isArray(discovered.options)
+    ? discovered.options.filter((o) => o.value && o.value !== 'none')
+    : [];
+
+  const ready = hasOllamaModels || hasProviderKeys || embedOptions.length > 0;
+
+  return {
+    ready,
+    hasOllamaModels,
+    hasProviderKeys,
+    configuredProviders: configuredProviders.map((p) => p.id),
+    ollamaOnline,
+    ollamaModelCount: hasOllamaModels ? ollamaModels.length : 0,
+    embedOptionCount: embedOptions.length,
+  };
+}
+
+/**
+ * Human-readable onboarding block for CLI notes / stderr.
+ * @param {ReturnType<typeof assessAiAccess>} access
+ * @param {{ wantCloudAi?: boolean }} [opts]
+ */
+export function formatAiAccessOnboarding(access, opts = {}) {
+  const lines = [];
+  if (access.ready) {
+    lines.push('AI access: ready');
+    if (access.hasProviderKeys) {
+      lines.push(`  providers  ${access.configuredProviders.join(', ')}`);
+    }
+    if (access.hasOllamaModels) {
+      lines.push(`  ollama     online · ${access.ollamaModelCount} model(s)`);
+    }
+    if (access.embedOptionCount) {
+      lines.push(`  embed menu ${access.embedOptionCount} option(s)`);
+    }
+    return lines.join('\n');
+  }
+
+  lines.push('AI access: not configured yet');
+  lines.push('');
+  lines.push('Pick ONE path to unlock AgentSam model options:');
+  lines.push('');
+  lines.push('  1) Local models (Ollama) — free, offline');
+  lines.push('       https://ollama.com/download');
+  lines.push('       ollama pull mxbai-embed-large');
+  lines.push('       ollama pull qwen2.5-coder');
+  lines.push('       agentsam ollama status');
+  lines.push('');
+  lines.push('  2) Provider API key — use models your key is allotted');
+  lines.push('       agentsam providers');
+  lines.push('       (OpenAI · Anthropic · Gemini · Cursor · xAI · Cloudflare token)');
+  lines.push('');
+  lines.push('  3) Local Studio identity + Cloudflare OAuth');
+  lines.push('       (Workers AI / account tools / MCP connector)');
+  lines.push(`       Login:  ${LOCAL_STUDIO_LOGIN}`);
+  lines.push(`       CF sign-in: ${CF_OAUTH_LOGIN_START}`);
+  lines.push(`       CF connect: ${CF_OAUTH_CONNECT_START}`);
+  if (opts.wantCloudAi) {
+    lines.push('');
+    lines.push('  Cloudflare OAuth client must allow these redirect URIs:');
+    for (const uri of CF_OAUTH_REQUIRED_REDIRECTS) {
+      lines.push(`       • ${uri}`);
+    }
+  }
+  lines.push('');
+  lines.push('AST/text-only indexing still works with embedding: none ($0).');
+  return lines.join('\n');
+}

package/src/models/discovery.js

@@ -315,11 +315,19 @@ export async function discoverCloudflareModels(apiToken, accountId, fetchImpl =
       .map((row) => {
         const id = clean(row?.name);
         const task = cloudflareTaskName(row?.task);
-        if (!id || task.toLowerCase() !== 'text generation') return null;
+        const taskLower = task.toLowerCase();
+        // Text Generation = chat/agent pool. Text Embeddings = Vectorize / Workers AI embed pool.
+        // Never drop embeddings here — chat allowlisting happens in inventory curation only.
+        if (!id || (taskLower !== 'text generation' && taskLower !== 'text embeddings')) return null;
+        const isEmbed = taskLower === 'text embeddings';
         return baseRecord('cloudflare', id, {
           label: id,
           source_url: url,
-          capabilities: { workers_ai: true },
+          capabilities: {
+            workers_ai: true,
+            embeddings: isEmbed,
+            agent_runtime: !isEmbed,
+          },
           metadata: {
             task,
             author: clean(row?.author) || null,

package/src/models/inventory-core.js

@@ -42,7 +42,15 @@ export function providerIdForService(serviceName) {
 
 export function filterWorkersAiCurated(models = [], options = {}) {
   if (options.curated === false) return [...models];
-  return models.filter((row) => CURATED.has(String(row?.provider_model_id || row?.model_id || '')));
+  // Chat/agent pool: curated allowlist. Embedding models always pass —
+  // Vectorize / Workers AI embed lanes must not be limited by the chat allowlist.
+  return models.filter((row) => {
+    const id = String(row?.provider_model_id || row?.model_id || '');
+    const caps = row?.capabilities || {};
+    const task = String(row?.metadata?.task || '').toLowerCase();
+    if (caps.embeddings === true || task === 'text embeddings' || /embed/i.test(id)) return true;
+    return CURATED.has(id);
+  });
 }
 
 /**

package/src/plugins/cloudflare.js

@@ -19,7 +19,7 @@ export const AGENTSAM_MCP_PLUGIN_MANIFEST = normalizePluginManifest({
     { capability_key: 'cloudflare.api.execute', domain: 'cloudflare', verb: 'execute', description: 'Execute a bounded Cloudflare API Code Mode program.', is_mutating: true },
   ],
   tool_lanes: ['typed', 'mcp', 'api', 'codemode'],
-  resource_scope: { owner: 'account', oauth_connection_table: 'agentsam_cloudflare_connections' },
+  resource_scope: { owner: 'account', oauth_connection_table: 'user_oauth_tokens' },
   config: {
     oauth_authority: 'cloudflare',
     oauth_client_id: 'c0704bd7a7aab7216b362603e1985499',

package/src/providers/ollama-chat.js

@@ -1,5 +1,6 @@
 import { createAgentEvent, createUsageSnapshot } from '../telemetry/index.js';
 import { diagnosticFromError } from '../errors/index.js';
+import { resolveOllamaEndpoint } from '../../packages/agentsam-knowledge/src/providers/ollama-endpoint.js';
 
 function clean(value) { return value == null ? '' : String(value).trim(); }
 function integer(value) { const n = Number(value ?? 0); return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0; }
@@ -28,7 +29,7 @@ function callsFromMessage(message = {}) {
 
 export function createOllamaChatAdapter(options = {}) {
   const fetchImpl = options.fetchImpl || fetch;
-  const endpoint = clean(options.endpoint || process.env.OLLAMA_BASE_URL || 'http://127.0.0.1:11434').replace(/\/$/, '');
+  const endpoint = resolveOllamaEndpoint({ endpoint: options.endpoint, env: options.env || process.env });
 
   async function send(messages, params = {}) {
     const record = params.modelRecord || options.modelRecord;

package/src/sam/activity/index.js

@@ -0,0 +1,183 @@
+/**
+ * AgentSam activity event stream — one run, many surfaces (Studio / CLI / desktop).
+ * Scene/status/progress come ONLY from these events — never demo timers.
+ */
+
+export const ACTIVITY_SCHEMA = 'agentsam.activity.v1';
+
+export const ACTIVITY_PHASES = Object.freeze([
+  'boot',
+  'observe',
+  'context',
+  'plan',
+  'execute',
+  'verify',
+  'compact',
+  'waiting',
+  'recover',
+  'complete',
+]);
+
+export const ACTIVITY_EVENTS = Object.freeze([
+  'run.started',
+  'phase.changed',
+  'step.started',
+  'step.progress',
+  'step.completed',
+  'decision.made',
+  'tool.started',
+  'tool.completed',
+  'artifact.created',
+  'file.changed',
+  'approval.required',
+  'input.required',
+  'verification.completed',
+  'run.failed',
+  'run.completed',
+]);
+
+/** User-facing labels — never expose choose/score/check as primary copy. */
+export const DECISION_ACTIVITY_LABELS = Object.freeze({
+  terminal_lane: 'Selecting execution path',
+  retrieval_mode: 'Choosing retrieval path',
+  change_risk: 'Assessing change risk',
+  requires_approval: 'Checking approval requirements',
+  security_review_required: 'Checking security review requirements',
+  verification_scope: 'Selecting verification scope',
+  skill_candidate: 'Selecting skill',
+});
+
+/**
+ * @param {object} partial
+ */
+export function createActivityEvent(partial = {}) {
+  const phase = partial.phase || 'execute';
+  const event = partial.event || 'step.progress';
+  if (!ACTIVITY_PHASES.includes(phase)) {
+    const err = new Error(`invalid_activity_phase:${phase}`);
+    err.code = 'invalid_activity_phase';
+    throw err;
+  }
+  if (!ACTIVITY_EVENTS.includes(event)) {
+    const err = new Error(`invalid_activity_event:${event}`);
+    err.code = 'invalid_activity_event';
+    throw err;
+  }
+  return Object.freeze({
+    schema: ACTIVITY_SCHEMA,
+    run_id: String(partial.run_id || ''),
+    seq: Number.isInteger(partial.seq) ? partial.seq : 0,
+    timestamp: partial.timestamp || new Date().toISOString(),
+    phase,
+    event,
+    step_id: partial.step_id ?? null,
+    parent_id: partial.parent_id ?? null,
+    label: String(partial.label || ''),
+    detail: partial.detail ?? null,
+    progress: normalizeProgress(partial.progress),
+    source: partial.source
+      ? {
+          kind: partial.source.kind || 'sam',
+          name: partial.source.name ?? null,
+        }
+      : { kind: 'sam', name: null },
+    evidence: partial.evidence && typeof partial.evidence === 'object'
+      ? { ...partial.evidence }
+      : null,
+  });
+}
+
+function normalizeProgress(progress) {
+  if (progress == null) return null;
+  if (typeof progress !== 'object') return null;
+  const current = Number(progress.current);
+  const total = Number(progress.total);
+  if (!Number.isFinite(current) || !Number.isFinite(total) || total <= 0) return null;
+  return { current, total };
+}
+
+/**
+ * Map a decision answer to a user-visible activity event (primitives stay in evidence).
+ * @param {object} opts
+ */
+export function activityFromDecision(opts = {}) {
+  const questionId = opts.question_id || opts.answer?.question_id;
+  const answer = opts.answer || {};
+  const label = DECISION_ACTIVITY_LABELS[questionId]
+    || opts.label
+    || 'Making a structured decision';
+  const valueText = formatAnswerValue(answer);
+  return createActivityEvent({
+    run_id: opts.run_id,
+    seq: opts.seq,
+    phase: opts.phase || 'plan',
+    event: 'decision.made',
+    step_id: opts.step_id ?? null,
+    label,
+    detail: valueText,
+    source: { kind: 'sam', name: answer.evaluator?.kind || 'decision' },
+    evidence: {
+      decision_id: opts.decision_id ?? null,
+      question_id: questionId,
+      question_type: answer.type ?? null,
+      value: answer.value ?? null,
+      confidence_estimate: answer.confidence_estimate ?? null,
+      support: answer.support ?? null,
+      receipt_id: opts.decision_id ?? null,
+    },
+  });
+}
+
+function formatAnswerValue(answer) {
+  if (!answer || answer.value == null) return null;
+  if (answer.type === 'check') return answer.value ? 'Required' : 'Not required';
+  if (answer.type === 'score') {
+    const n = Number(answer.value);
+    return Number.isFinite(n) ? (n < 2 ? 'Bounded' : n < 3.5 ? 'Elevated' : 'High') : String(answer.value);
+  }
+  return String(answer.value);
+}
+
+/**
+ * In-memory run activity store — Studio SideStage and CLI subscribe to the same seq stream.
+ */
+export function createActivityStore(runId) {
+  const id = String(runId || `run_${Date.now().toString(36)}`);
+  /** @type {object[]} */
+  const events = [];
+  /** @type {Set<(e: object) => void>} */
+  const listeners = new Set();
+  let seq = 0;
+
+  function emit(partial) {
+    const event = createActivityEvent({
+      ...partial,
+      run_id: id,
+      seq: ++seq,
+    });
+    events.push(event);
+    for (const fn of listeners) {
+      try {
+        fn(event);
+      } catch {
+        /* subscriber errors must not break the run */
+      }
+    }
+    return event;
+  }
+
+  return {
+    run_id: id,
+    emit,
+    on(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    snapshot() {
+      return [...events];
+    },
+    latest() {
+      return events[events.length - 1] || null;
+    },
+  };
+}