@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/packages/agentsam-workbench/src/terminal/index.ts

@@ -0,0 +1 @@
+export * from './TerminalSurface';

package/packages/agentsam-workbench/src/timeline/GanttBoard.tsx

@@ -0,0 +1,258 @@
+import { useMemo, useState } from 'react';
+
+export type GanttStatus = 'planned' | 'ready' | 'active' | 'blocked' | 'complete' | 'cancelled';
+export type GanttKind = 'phase' | 'task' | 'milestone';
+
+export interface GanttActor {
+  id?: string;
+  name: string;
+  role?: string;
+}
+
+export interface GanttItem {
+  id: string;
+  title: string;
+  kind?: GanttKind;
+  status?: GanttStatus | string;
+  owner?: GanttActor | string | null;
+  start?: string | null;
+  end?: string | null;
+  baselineStart?: string | null;
+  baselineEnd?: string | null;
+  progress?: number | null;
+  parentId?: string | null;
+  dependencies?: string[];
+  blockedReason?: string | null;
+  estimateMinutes?: number | null;
+  actualMinutes?: number | null;
+  artifactCount?: number;
+  evidenceCount?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface GanttGroup {
+  id: string;
+  title: string;
+  start?: string | null;
+  end?: string | null;
+  progress?: number | null;
+}
+
+export interface GanttBoardProps {
+  title: string;
+  subtitle?: string;
+  items: GanttItem[];
+  groups: GanttGroup[];
+  rangeStart: string;
+  rangeEnd: string;
+  today?: string;
+  selectedId?: string | null;
+  onSelect?: (item: GanttItem | null) => void;
+  onCreateTask?: () => void;
+}
+
+const DAY = 86_400_000;
+
+function dayKey(value: string | Date) {
+  const date = value instanceof Date ? value : new Date(`${value}T00:00:00Z`);
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+
+function spanFor(start: string | null | undefined, end: string | null | undefined, rangeStart: string, count: number) {
+  if (!start) return { offset: 0, span: 1 };
+  const range = dayKey(rangeStart);
+  const s = Math.max(0, Math.round((dayKey(start) - range) / DAY));
+  const e = end ? Math.round((dayKey(end) - range) / DAY) : s;
+  return { offset: Math.min(count - 1, s), span: Math.max(1, Math.min(count - s, e - s + 1)) };
+}
+
+function formatOwner(owner: GanttItem['owner']) {
+  if (!owner) return 'Unassigned';
+  return typeof owner === 'string' ? owner : owner.name;
+}
+
+function formatDateShort(value?: string | null) {
+  if (!value) return '—';
+  return new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric', timeZone: 'UTC' }).format(new Date(`${value}T00:00:00Z`));
+}
+
+function formatMinutes(value?: number | null) {
+  if (value == null) return '—';
+  const hours = Math.floor(value / 60);
+  const minutes = value % 60;
+  return hours ? `${hours}h ${minutes}m` : `${minutes}m`;
+}
+
+export function GanttBoard({
+  title,
+  subtitle,
+  items,
+  groups,
+  rangeStart,
+  rangeEnd,
+  today,
+  selectedId,
+  onSelect,
+  onCreateTask,
+}: GanttBoardProps) {
+  const [hideCompleted, setHideCompleted] = useState(false);
+  const [zoom, setZoom] = useState<'Day' | 'Week'>('Day');
+
+  const days = useMemo(() => {
+    const start = dayKey(rangeStart);
+    const end = dayKey(rangeEnd);
+    const result: Date[] = [];
+    for (let value = start; value <= end; value += DAY) result.push(new Date(value));
+    return result;
+  }, [rangeStart, rangeEnd]);
+
+  const visible = hideCompleted ? items.filter((item) => item.status !== 'complete') : items;
+  const byGroup = new Map(groups.map((group) => [group.id, visible.filter((item) => item.parentId === group.id)]));
+  const selected = items.find((item) => item.id === selectedId) ?? null;
+  const todayIndex = today ? Math.round((dayKey(today) - dayKey(rangeStart)) / DAY) : -1;
+
+  return (
+    <section className="as-gantt-shell">
+      <header className="as-gantt-project-header">
+        <div>
+          <p className="as-kicker">PROJECT</p>
+          <h1>{title}</h1>
+          {subtitle ? <p>{subtitle}</p> : null}
+        </div>
+        <div className="as-gantt-project-actions">
+          <button type="button" className="as-button">Share</button>
+          <button type="button" className="as-button as-button--primary" onClick={onCreateTask}>+ Add task</button>
+        </div>
+      </header>
+
+      <nav className="as-view-tabs" aria-label="Project views">
+        {['Gantt', 'List', 'Calendar', 'Discussions'].map((tab) => <button key={tab} type="button" data-active={tab === 'Gantt' || undefined}>{tab}</button>)}
+        <button type="button">More ▾</button>
+      </nav>
+
+      <div className="as-gantt-toolbar">
+        <div className="as-gantt-toolbar__group">
+          <button type="button">Menu ▾</button>
+          <button type="button">View ▾</button>
+          <button type="button" onClick={() => setZoom((value) => value === 'Day' ? 'Week' : 'Day')}>Zoom · {zoom}</button>
+          <button type="button">Filter ▾</button>
+          <label><input type="checkbox" checked={hideCompleted} onChange={(event) => setHideCompleted(event.target.checked)} /> Hide completed</label>
+        </div>
+        <div className="as-gantt-toolbar__group as-gantt-toolbar__group--right">
+          <span>{formatDateShort(rangeStart)} – {formatDateShort(rangeEnd)}</span>
+          <button type="button">Today</button>
+        </div>
+      </div>
+
+      <div className="as-gantt-layout" data-inspector={selected ? 'open' : 'closed'}>
+        <div className="as-gantt-main">
+          <div className="as-gantt-scroll">
+            <div className="as-gantt-table" style={{ '--as-day-count': days.length } as React.CSSProperties}>
+              <div className="as-gantt-header as-gantt-task-col">Workstream</div>
+              <div className="as-gantt-header as-gantt-owner-col">Owner</div>
+              <div className="as-gantt-days">
+                {days.map((day) => (
+                  <div className="as-gantt-day" key={day.toISOString()}>
+                    <span>{day.toLocaleDateString('en-US', { month: day.getUTCDate() === 1 || day.getTime() === days[0]?.getTime() ? 'short' : undefined, timeZone: 'UTC' })}</span>
+                    <strong>{day.getUTCDate()}</strong>
+                    <small>{day.toLocaleDateString('en-US', { weekday: 'narrow', timeZone: 'UTC' })}</small>
+                  </div>
+                ))}
+                {todayIndex >= 0 && todayIndex < days.length ? <span className="as-today-line" style={{ left: `${((todayIndex + 0.5) / days.length) * 100}%` }}><em>Today</em></span> : null}
+              </div>
+
+              {groups.flatMap((group) => {
+                const groupItems = byGroup.get(group.id) ?? [];
+                const phase = spanFor(group.start, group.end, rangeStart, days.length);
+                const phaseProgress = typeof group.progress === 'number' ? Math.max(0, Math.min(1, group.progress)) : null;
+                return [
+                  <div className="as-gantt-group as-gantt-task-col" key={`${group.id}-label`}>
+                    <span className="as-disclosure">⌄</span><strong>{group.title}</strong>
+                  </div>,
+                  <div className="as-gantt-group as-gantt-owner-col" key={`${group.id}-owner`} />,
+                  <div className="as-gantt-group as-gantt-timeline-cell" key={`${group.id}-timeline`}>
+                    <div className="as-phase-track" style={{ left: `${phase.offset / days.length * 100}%`, width: `${phase.span / days.length * 100}%` }}>
+                      {phaseProgress != null ? <span style={{ width: `${phaseProgress * 100}%` }} /> : null}
+                    </div>
+                  </div>,
+                  ...groupItems.flatMap((item) => {
+                    const span = spanFor(item.start, item.end, rangeStart, days.length);
+                    const progress = typeof item.progress === 'number' ? Math.max(0, Math.min(1, item.progress)) : null;
+                    return [
+                      <button className="as-gantt-row as-gantt-task-col" data-selected={item.id === selectedId || undefined} key={`${item.id}-label`} onClick={() => onSelect?.(item)}>
+                        <span className="as-task-dot" data-status={item.status ?? 'planned'} />
+                        <span className="as-task-title">{item.title}</span>
+                        {progress != null && item.kind !== 'milestone' ? <span className="as-task-percent">{Math.round(progress * 100)}%</span> : null}
+                      </button>,
+                      <button className="as-gantt-row as-gantt-owner-col" data-selected={item.id === selectedId || undefined} key={`${item.id}-owner`} onClick={() => onSelect?.(item)}>{formatOwner(item.owner)}</button>,
+                      <button className="as-gantt-row as-gantt-timeline-cell" data-selected={item.id === selectedId || undefined} key={`${item.id}-timeline`} onClick={() => onSelect?.(item)}>
+                        {item.kind === 'milestone' ? (
+                          <span className="as-milestone" title={item.title} style={{ left: `${((span.offset + 0.5) / days.length) * 100}%` }} />
+                        ) : (
+                          <>
+                            {item.baselineStart ? (() => {
+                              const baseline = spanFor(item.baselineStart, item.baselineEnd, rangeStart, days.length);
+                              return <span className="as-baseline" style={{ left: `${baseline.offset / days.length * 100}%`, width: `${baseline.span / days.length * 100}%` }} />;
+                            })() : null}
+                            <span className="as-task-bar" data-status={item.status ?? 'planned'} style={{ left: `${span.offset / days.length * 100}%`, width: `${span.span / days.length * 100}%` }}>
+                              {progress != null ? <span className="as-task-bar__progress" style={{ width: `${progress * 100}%` }} /> : null}
+                              <strong>{item.title}</strong>
+                            </span>
+                          </>
+                        )}
+                      </button>,
+                    ];
+                  }),
+                ];
+              })}
+            </div>
+          </div>
+        </div>
+
+        {selected ? (
+          <aside className="as-work-inspector">
+            <button className="as-work-inspector__close" type="button" onClick={() => onSelect?.(null)} aria-label="Close inspector">×</button>
+            <span className="as-status-pill" data-status={selected.status ?? 'planned'}>{selected.status ?? 'planned'}</span>
+            <h2>{selected.title}</h2>
+            <p className="as-work-inspector__summary">{String(selected.metadata?.summary ?? 'WorkGraph item projected into the schedule. The timeline is not the source of truth.')}</p>
+
+            <dl className="as-inspector-grid">
+              <div><dt>Owner</dt><dd>{formatOwner(selected.owner)}</dd></div>
+              <div><dt>Status</dt><dd>{selected.status ?? 'planned'}</dd></div>
+              <div><dt>Start</dt><dd>{formatDateShort(selected.start)}</dd></div>
+              <div><dt>Due</dt><dd>{formatDateShort(selected.end)}</dd></div>
+            </dl>
+
+            <section>
+              <h3>Progress</h3>
+              {typeof selected.progress === 'number' ? (
+                <>
+                  <div className="as-progress-track"><span style={{ width: `${Math.round(selected.progress * 100)}%` }} /></div>
+                  <p className="as-inspector-note">{Math.round(selected.progress * 100)}% · {formatMinutes(selected.actualMinutes)} actual / {formatMinutes(selected.estimateMinutes)} estimated</p>
+                </>
+              ) : <p className="as-inspector-note">Progress denominator is not known yet.</p>}
+            </section>
+
+            <section>
+              <h3>Dependencies</h3>
+              {selected.dependencies?.length ? selected.dependencies.map((dependency) => <div className="as-inspector-line" key={dependency}>← {dependency}</div>) : <p className="as-inspector-note">No dependencies</p>}
+            </section>
+
+            <section>
+              <h3>Artifacts & evidence</h3>
+              <div className="as-inspector-line">{selected.artifactCount ?? 0} artifacts</div>
+              <div className="as-inspector-line">{selected.evidenceCount ?? 0} evidence records</div>
+            </section>
+
+            {selected.blockedReason ? <section><h3>Blocker</h3><div className="as-inspector-line as-inspector-line--danger">{selected.blockedReason}</div></section> : null}
+
+            <div className="as-work-inspector__actions">
+              <button className="as-button" type="button">Open tickets</button>
+              <button className="as-button as-button--primary" type="button">Open work</button>
+            </div>
+          </aside>
+        ) : null}
+      </div>
+    </section>
+  );
+}

package/packages/agentsam-workbench/src/timeline/index.ts

@@ -0,0 +1 @@
+export * from './GanttBoard';

package/packages/agentsam-workbench/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/packages/connectors/cloudflare/OAUTH_STORAGE_AUDIT.md

@@ -0,0 +1,53 @@
+# Cloudflare connector — OAuth storage (SSOT)
+
+## Single store
+
+**`user_oauth_tokens`** (`provider = 'cloudflare'`) is the only connection credential table.
+
+Legacy `agentsam_cloudflare_connections` is no longer written or read on the hot path.
+A one-shot migrate in `routes.ensureTables` copies any remaining `status='connected'`
+legacy rows into `user_oauth_tokens` (when vault can decrypt), then marks them superseded.
+
+## Field mapping (former legacy columns)
+
+| Legacy (`agentsam_cloudflare_connections`) | SSOT (`user_oauth_tokens`) |
+|---|---|
+| `cloudflare_account_id` | `account_identifier` + `metadata_json.cloudflare_account_id` |
+| `scopes` | `scopes` / `scope` |
+| `status` (`connected` / `superseded` / `revoked`) | `is_active` + `revoked_at` + `metadata_json.status` |
+| `access_token_encrypted` | `access_token_encrypted` (connector AAD) or IAM-encrypted via host decrypt |
+| `connection_id` | row `id` (or account_identifier for seed keys) |
+
+No provider-specific columns added to `user_oauth_tokens` — it stays multi-provider.
+
+## Three auth concerns (do not flatten)
+
+| Lane | Tables | Purpose |
+|---|---|---|
+| AgentSam AS | `oauth_clients`, `oauth_access_tokens`, … | Tokens AgentSam **issues** to clients |
+| Provider connections | `user_oauth_tokens` | Tokens Cloudflare/Google/GitHub **issue** to the user |
+| Identity login | `identity_oauth_states` | Sign-in to AgentSam |
+| OAuth CSRF/PKCE | `oauth_state_nonces` | Multi-provider, encrypted `code_verifier` |
+
+## Readers / writers (SDK)
+
+| Path | Behavior |
+|---|---|
+| `credential.js` | Reads `user_oauth_tokens` only |
+| `oauth-persist.js` | Canonical writer — scope union, supersede siblings, vault seal when available |
+| `routes.js` | Callback / disconnect / status → spine only; optional legacy migrate |
+| Host app | Passes `defaultCapabilities` into `handleCloudflareConnectionRequest` |
+
+## Provenance (`metadata_json`)
+
+- `connected_via_client_id` — real Cloudflare OAuth client_id only
+- `granted_at_capability_set` — optional capability ids that drove the request
+- `cloudflare_account_id`
+- `status` — `connected` | `superseded` | `revoked`
+
+## Callback lanes (both kept — different jobs)
+
+| Path | Job |
+|---|---|
+| `/api/connections/cloudflare/callback` | Resource connect → `user_oauth_tokens` |
+| `/api/oauth/cloudflare/callback` | Identity login (Sign in with Cloudflare) |

package/packages/connectors/cloudflare/package.json

@@ -1,10 +1,22 @@
 {
   "name": "@inneranimalmedia/agentsam-connector-cloudflare",
-  "version": "0.1.0",
-  "private": true,
+  "version": "2.6.7",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
-    ".": "./src/index.js"
-  }
+    ".": "./src/index.js",
+    "./capabilities": "./src/capabilities.js",
+    "./api-client": "./src/api-client.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamPrimeaux/agentsam-sdk.git",
+    "directory": "packages/connectors/cloudflare"
+  },
+  "files": [
+    "src"
+  ]
 }

package/packages/connectors/cloudflare/src/api-client.js

@@ -0,0 +1,280 @@
+/**
+ * Cloudflare API v4 client for AgentSam CLI / connector families.
+ *
+ * Prefer createCloudflareApiClient() so OAuth + API-token lanes share one transport.
+ * Constructor remains sync for direct-token / test injection — no hidden DB I/O.
+ */
+
+import { cloudflarePermissionRemediation, getCloudflareCapability } from './capabilities.js';
+import { resolveCloudflareCredential, credentialSafeMeta } from './credential.js';
+
+const API_BASE = 'https://api.cloudflare.com/client/v4';
+
+/**
+ * Env-only sync helper for CLI.
+ * Does NOT fall back to CLOUDFLARE_IMAGES_API_TOKEN (Images-family only).
+ */
+export function resolveCloudflareApiAuth(env = process.env) {
+  const apiToken = String(env.CLOUDFLARE_API_TOKEN || '').trim();
+  const accountId = String(env.CLOUDFLARE_ACCOUNT_ID || '').trim();
+  return {
+    apiToken,
+    accountId,
+    configured: Boolean(apiToken),
+    account_resolved: Boolean(accountId),
+  };
+}
+
+export class CloudflareApiError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'CloudflareApiError';
+    this.code = details.code || 'cloudflare_api_error';
+    this.httpStatus = details.httpStatus || null;
+    this.providerErrors = details.providerErrors || [];
+    this.capabilityId = details.capabilityId || null;
+    this.operation = details.operation || null;
+    this.path = details.path || null;
+    this.remediation = details.remediation || null;
+  }
+
+  toJSON() {
+    return {
+      ok: false,
+      error: this.code,
+      message: this.message,
+      http_status: this.httpStatus,
+      provider_errors: this.providerErrors,
+      capability_id: this.capabilityId,
+      operation: this.operation,
+      path: this.path,
+      remediation: this.remediation,
+    };
+  }
+}
+
+export class CloudflareApiClient {
+  constructor({
+    apiToken = '',
+    accountId = '',
+    authSource = 'api_token',
+    connectionId = null,
+    grantedScopes = [],
+    capabilityId = null,
+    fetchImpl = globalThis.fetch,
+    env = process.env,
+  } = {}) {
+    const auth = resolveCloudflareApiAuth(env);
+    this.apiToken = String(apiToken || auth.apiToken || '').trim();
+    this.accountId = String(accountId || auth.accountId || '').trim();
+    this.authSource = authSource || (this.apiToken ? 'api_token' : 'missing');
+    this.connectionId = connectionId;
+    this.grantedScopes = Array.isArray(grantedScopes) ? grantedScopes : [];
+    this.capabilityId = capabilityId;
+    this.fetchImpl = fetchImpl;
+  }
+
+  authMeta() {
+    return credentialSafeMeta({
+      source: this.authSource,
+      accountId: this.accountId,
+      connectionId: this.connectionId,
+      grantedScopes: this.grantedScopes,
+      capabilityId: this.capabilityId,
+      status: this.apiToken ? 'ready' : 'token_required',
+    });
+  }
+
+  requireToken(operation = 'cloudflare.api') {
+    if (!this.apiToken) {
+      throw new CloudflareApiError('Cloudflare credential required (OAuth connection or CLOUDFLARE_API_TOKEN)', {
+        code: 'cloudflare_credential_required',
+        operation,
+        capabilityId: this.capabilityId,
+        remediation: {
+          actions: [
+            'Connect Cloudflare via Local Studio OAuth',
+            'Or set CLOUDFLARE_API_TOKEN for CLI/CI',
+          ],
+          authorize_hint: 'agentsam cloudflare status',
+        },
+      });
+    }
+  }
+
+  requireAccount(operation = 'cloudflare.api') {
+    this.requireToken(operation);
+    if (!this.accountId) {
+      throw new CloudflareApiError('CLOUDFLARE_ACCOUNT_ID / connected account required', {
+        code: 'cloudflare_account_id_required',
+        operation,
+        remediation: {
+          actions: ['Set CLOUDFLARE_ACCOUNT_ID', 'Or reconnect Cloudflare OAuth so account_identifier is stored'],
+          authorize_hint: 'export CLOUDFLARE_ACCOUNT_ID=…',
+        },
+      });
+    }
+  }
+
+  async request(method, path, opts = {}) {
+    const operation = opts.operation || `${method} ${path}`;
+    const capabilityId = opts.capabilityId || this.capabilityId;
+    this.requireToken(operation);
+
+    let url;
+    if (/^https?:\/\//i.test(path)) {
+      url = new URL(path);
+    } else {
+      url = new URL(path.startsWith('/') ? path : `/${path}`, `${API_BASE}/`);
+    }
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) {
+        if (v == null || v === '') continue;
+        url.searchParams.set(k, String(v));
+      }
+    }
+
+    const headers = {
+      Accept: 'application/json',
+      ...(opts.headers || {}),
+      Authorization: `Bearer ${this.apiToken}`,
+    };
+    let body;
+    if (opts.body != null && method !== 'GET' && method !== 'HEAD') {
+      if (opts.body instanceof FormData || typeof opts.body === 'string' || Buffer.isBuffer(opts.body)) {
+        body = opts.body;
+      } else {
+        if (!headers['Content-Type'] && !headers['content-type']) headers['Content-Type'] = 'application/json';
+        body = JSON.stringify(opts.body);
+      }
+    }
+
+    let res;
+    let json = null;
+    try {
+      res = await this.fetchImpl(url.toString(), { method, headers, body });
+      const ct = String(res.headers.get('content-type') || '');
+      if (opts.raw || ct.includes('image/') || ct.includes('octet-stream') || ct.includes('text/html')) {
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (!res.ok) throw this.#fail(res, null, { ...opts, capabilityId }, operation, url.pathname);
+        return { ok: true, http_status: res.status, headers: Object.fromEntries(res.headers), body: buf };
+      }
+      const text = await res.text();
+      try {
+        json = text ? JSON.parse(text) : null;
+      } catch {
+        json = null;
+      }
+    } catch (err) {
+      if (err instanceof CloudflareApiError) throw err;
+      throw new CloudflareApiError(String(err?.message || err), {
+        code: 'cloudflare_network_error',
+        operation,
+        path,
+        capabilityId,
+      });
+    }
+
+    if (!res.ok || json?.success === false) {
+      throw this.#fail(res, json, { ...opts, capabilityId }, operation, url.pathname);
+    }
+
+    return {
+      ok: true,
+      http_status: res.status,
+      success: json?.success !== false,
+      result: json?.result ?? json,
+      result_info: json?.result_info || null,
+      errors: json?.errors || [],
+      messages: json?.messages || [],
+      auth: this.authMeta(),
+      raw: json,
+    };
+  }
+
+  #fail(res, json, opts, operation, path) {
+    const providerErrors = json?.errors || [];
+    const message = providerErrors[0]?.message
+      || `Cloudflare API ${res.status} for ${operation}`;
+    const remediation = (res.status === 403 || res.status === 401)
+      ? cloudflarePermissionRemediation({
+        capabilityId: opts.capabilityId,
+        operation,
+        httpStatus: res.status,
+        providerMessage: message,
+      })
+      : null;
+    return new CloudflareApiError(message, {
+      code: res.status === 403 || res.status === 401
+        ? 'cloudflare_permission_denied'
+        : 'cloudflare_api_error',
+      httpStatus: res.status,
+      providerErrors,
+      capabilityId: opts.capabilityId,
+      operation,
+      path,
+      remediation,
+    });
+  }
+
+  accountPath(suffix) {
+    this.requireAccount();
+    return `/accounts/${encodeURIComponent(this.accountId)}${suffix.startsWith('/') ? suffix : `/${suffix}`}`;
+  }
+
+  zonePath(zoneId, suffix) {
+    this.requireToken();
+    if (!zoneId) {
+      throw new CloudflareApiError('zone_id required', { code: 'zone_id_required' });
+    }
+    return `/zones/${encodeURIComponent(zoneId)}${suffix.startsWith('/') ? suffix : `/${suffix}`}`;
+  }
+}
+
+/** Async factory — OAuth or API token without sync DB work in constructor. */
+export async function createCloudflareApiClient(opts = {}) {
+  const cred = await resolveCloudflareCredential(opts);
+  if (!cred.bearerToken) {
+    throw new CloudflareApiError('Cloudflare credential required', {
+      code: cred.status === 'token_required' ? 'cloudflare_token_required' : 'cloudflare_authorization_required',
+      capabilityId: opts.capabilityId || null,
+      remediation: {
+        actions: cred.status === 'token_required'
+          ? ['Set CLOUDFLARE_API_TOKEN']
+          : ['Authorize Cloudflare capability', 'Or set CLOUDFLARE_API_TOKEN'],
+        authorize_hint: opts.capabilityId
+          ? `/api/connections/cloudflare/start?capabilities=${encodeURIComponent(opts.capabilityId)}`
+          : 'agentsam cloudflare status',
+        auth_status: cred.status,
+      },
+    });
+  }
+  return new CloudflareApiClient({
+    apiToken: cred.bearerToken,
+    accountId: cred.accountId || opts.explicitAccountId || '',
+    authSource: cred.source,
+    connectionId: cred.connectionId,
+    grantedScopes: cred.grantedScopes,
+    capabilityId: opts.capabilityId || null,
+    fetchImpl: opts.fetchImpl,
+    env: {},
+  });
+}
+
+export function receipt(capabilityId, action, payload = {}) {
+  const cap = getCloudflareCapability(capabilityId);
+  const safe = { ...payload };
+  delete safe.bearerToken;
+  delete safe.apiToken;
+  delete safe.accessToken;
+  return {
+    schema: 'agentsam.cloudflare.receipt.v1',
+    provider: 'cloudflare',
+    capability_id: capabilityId,
+    capability_label: cap?.label || capabilityId,
+    action,
+    ok: payload.ok !== false,
+    auth: payload.auth ? (credentialSafeMeta(payload.auth) || payload.auth) : null,
+    ...safe,
+  };
+}