@possibl/rcrt-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to `@possibl/rcrt-sdk` are documented here. The
+format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this package follows [SemVer](https://semver.org/spec/v2.0.0.html) once
+published.
+
+## [0.1.0] — 2026-04-30
+
+First public release. Drops the `-alpha.1` suffix; signals the SDK is
+ready for frontend consumption (canonical RCRT mobile + web template
+imports it directly).
+
+### Added — modules
+
+- **`FilesModule`** (`client.files`) — multipart upload, list, get,
+  signed-URL download, server-side text extraction, soft delete.
+  Defaults to `tenant` scope; supports `org` / `user` for cross-
+  workspace assets.
+- **`SessionsModule`** (`client.sessions`) — `getConstellation()`
+  graph view of related sessions, `listParticipants` /
+  `addParticipant` / `removeParticipant` for multi-agent sessions.
+- **`CapabilitiesModule`** (`client.capabilities`) — `list(type)` for
+  tools / agents / services / knowledge, plus `getChattableAgents()`
+  helper that filters `interpret:promptable` to entries tagged
+  `interface:chat` / `interface:chat-default`.
+- **`IdentityModule.getUserProfile` / `updateUserProfile`** — workspace-
+  scoped editable profile breadcrumb. Returns `null` (instead of
+  throwing) when no profile has been written yet.
+- **`GrantsModule.resolveService(name)`** — server-side credential
+  resolution for tools that need to act on behalf of a workspace's
+  active service grant.
+
+### Notes
+
+- `IdentityModule.listPendingInvitations` / `acceptInvitation` /
+  `declineInvitation` were already shipped in the alpha — no change.
+- Global-events SSE (`/v1/events`) is exposed as `chat.globalStream`
+  rather than its own module — an extra module would have meant a
+  duplicate config builder.
+- Tenant admin endpoints (members, resource overrides) deliberately
+  out of scope for `0.1.0`. Will land in a `0.2.x` once a consumer
+  needs them.
+
+### Dependencies
+
+- No runtime deps. The SDK is fetch + EventSource + plain TS. Bring
+  your own `EventSource` polyfill on React Native (see README).
+
+### Compatibility
+
+- Node 18+ (native fetch + WHATWG URL).
+- Browsers with `fetch`, `URL`, `URLSearchParams`, `EventSource`.
+- React Native — pass an `eventSource` constructor in
+  `chat.sessionStream({ eventSource })` and bring a fetch polyfill if
+  using a runtime older than RN 0.74.

package/README.md

@@ -0,0 +1,154 @@
+# @possibl/rcrt-sdk
+
+TypeScript client for the [RCRT](https://github.com/possibl-ai/rcrt-v2)
+multi-tenant AI BaaS. Isomorphic — works in browsers, Node 18+, and
+React Native with a small polyfill.
+
+## Install
+
+```bash
+npm install @possibl/rcrt-sdk
+# or pnpm / yarn / bun
+```
+
+## Quickstart
+
+```ts
+import { RcrtClient, staticTokenProvider } from '@possibl/rcrt-sdk';
+
+const rcrt = new RcrtClient({
+  apiUrl: 'https://rcrt-api-gateway-<hash>.run.app',
+  tokenProvider: staticTokenProvider(process.env.WORKSPACE_API_KEY!),
+});
+
+// 1. Resolve workspace (for tests — UI apps go through Firebase):
+const { tenants } = await rcrt.auth.me().then((m) => ({ tenants: m.tenants }));
+rcrt.setTenantId(tenants[0].id);
+
+// 2. Send a chat:
+const { session_id } = await rcrt.chat.send({
+  message: 'Summarise my inbox',
+  target_agent: 'life-coordinator',
+});
+
+// 3. Stream the reply:
+const stream = rcrt.chat.sessionStream(session_id, {
+  onDelta: ({ delta }) => process.stdout.write(delta),
+  onMessage: (bc) => {
+    if (bc.tags.includes('interpret:pending-action')) {
+      const card = extractCard(bc);
+      console.log('card', card?.layout, card?.header.title);
+    }
+  },
+});
+
+// 4. When the user taps an action on a card:
+await rcrt.cards.resolve(cardBreadcrumbId, { status: 'approved' });
+
+stream.close();
+```
+
+## Browser + Firebase
+
+```ts
+import { getAuth } from 'firebase/auth';
+import { RcrtClient, TokenProvider } from '@possibl/rcrt-sdk';
+
+const auth = getAuth();
+const tokenProvider: TokenProvider = {
+  async getIdToken() {
+    const user = auth.currentUser;
+    if (!user) throw new Error('not signed in');
+    return user.getIdToken(false);
+  },
+};
+
+const rcrt = new RcrtClient({
+  apiUrl: import.meta.env.VITE_RCRT_API,
+  tokenProvider,
+});
+```
+
+## React Native
+
+React Native has no built-in `EventSource`. Install a polyfill and
+pass it through:
+
+```bash
+npm install react-native-sse
+```
+
+```ts
+import EventSource from 'react-native-sse';
+
+const stream = rcrt.chat.sessionStream(sessionId, handlers, {
+  eventSource: EventSource,
+  useHeaderAuth: true, // RN polyfill supports custom headers
+});
+```
+
+## What's exported
+
+| Symbol | Purpose |
+| --- | --- |
+| `RcrtClient` | The client. One instance per workspace session. |
+| `TokenProvider` | Interface — wire any IdP. |
+| `staticTokenProvider` | Static-token convenience (tests, `tk_*` workspace keys). |
+| `ApiError`, `SdkError` | Error classes. Typed + discriminable by `.status` and `.detail.code`. |
+| `Breadcrumb`, `Card`, `Row`, `ChartSpec`, ... | Every public type from the RCRT contract. Re-exportable as your UI types. |
+
+Browse `src/index.ts` for the full re-export list.
+
+### Module surface on `RcrtClient`
+
+```ts
+const rcrt = new RcrtClient({ apiUrl, tokenProvider });
+
+rcrt.auth          // identity, tenants, invitations, user profile
+rcrt.breadcrumbs   // CRUD + tag query + semantic search
+rcrt.chat          // send + sessionStream (per-session SSE) + globalStream (/v1/events)
+rcrt.cards         // JIT-UI card resolve + helpers
+rcrt.grants        // OAuth grants + initiate + resolveService
+rcrt.files         // upload / list / get / signed download / text extract / delete
+rcrt.sessions      // constellation + participants
+rcrt.capabilities  // tools / agents / services / knowledge discovery
+```
+
+## Design notes
+
+- **Isomorphic**: zero DOM or Node-only APIs in the core. The only
+  platform-touching code is the SSE client, and it takes an
+  `EventSource` constructor through config.
+- **Token provider is the seam**: the SDK never touches Firebase /
+  Auth0 / Clerk directly. You bring a `TokenProvider` and it asks.
+- **Everything is a breadcrumb**: `rcrt.breadcrumbs.*` is the
+  fundamental CRUD surface; all other modules build on it. `cards`,
+  `grants`, `auth` are conveniences.
+- **Optimistic locking just works**: `breadcrumbs.update(id, req, {
+  autoRetryConflict: true })` and `cards.resolve(...)` both refetch
+  and retry on 409.
+- **Errors are normalised**: the backend is mid-migration from
+  `{"error": "string"}` to a typed `{"error": {"code", "message",
+  "details"}}` envelope. `ApiError.detail.code` is set either way.
+
+## Matching docs
+
+Full narrative + concepts + operations playbook in
+[`packages/docs/`](../docs/). Start with:
+
+- [`docs/guides/01-quickstart.md`](../docs/guides/01-quickstart.md)
+- [`docs/concepts/05-jit-ui.md`](../docs/concepts/05-jit-ui.md)
+- [`docs/openapi/v1.yaml`](../docs/openapi/v1.yaml)
+
+## Status
+
+**0.1.0** — first public release. Used by `possibl-ai/rcrt-template-mobile`
+and downstream apps (e.g. `possibl-ai/ritual-app`, `possibl-ai/properlii-mobile`)
+as their canonical RCRT client. Surface stable; minor adjustments
+possible before 1.0.
+
+See [`CHANGELOG.md`](./CHANGELOG.md) for what's new in this release.
+
+## Licence
+
+MIT.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@possibl/rcrt-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the RCRT multi-tenant AI BaaS — isomorphic (web + node + React Native)",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./types": {
+      "types": "./src/types/index.ts",
+      "default": "./src/types/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "rcrt",
+    "ai",
+    "baas",
+    "agents",
+    "jit-ui",
+    "typescript",
+    "sdk"
+  ],
+  "author": "Possibl (https://possibl.ai)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/possibl-ai/rcrt-v2",
+    "directory": "packages/rcrt-sdk"
+  },
+  "homepage": "https://github.com/possibl-ai/rcrt-v2/tree/development/packages/docs",
+  "bugs": "https://github.com/possibl-ai/rcrt-v2/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit && tsc --noEmit -p tsconfig.tests.json",
+    "build": "tsc",
+    "test": "tsx --test tests/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "~5.6.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,56 @@
+/**
+ * TokenProvider — the seam between RCRT and your identity source.
+ *
+ * The SDK never talks to Firebase / Auth0 / Clerk directly. You wire
+ * up whichever IdP you use by implementing this interface once. On
+ * every request the SDK calls `getIdToken()` to get a fresh bearer.
+ *
+ * The provider owns refresh. If your IdP supports it (Firebase does),
+ * it should return a token that's valid for at least the next ~60s;
+ * the SDK doesn't track expiry itself.
+ *
+ * Example Firebase (web):
+ *
+ *     import { getAuth } from 'firebase/auth';
+ *     const auth = getAuth();
+ *     const tokenProvider: TokenProvider = {
+ *       async getIdToken() {
+ *         const u = auth.currentUser;
+ *         if (!u) throw new SdkError('NOT_SIGNED_IN', 'Sign in first');
+ *         return u.getIdToken(false);
+ *       },
+ *     };
+ *
+ * Example test stub:
+ *
+ *     const tokenProvider: TokenProvider = {
+ *       async getIdToken() { return 'tk_test_workspace_api_key'; },
+ *     };
+ */
+
+import { SdkError } from './errors.js';
+
+export interface TokenProvider {
+  /**
+   * Return a bearer token for the next request. Throws or rejects if
+   * the user isn't signed in / the key is missing.
+   *
+   * Implementations SHOULD refresh transparently if they know the
+   * token is close to expiry. The SDK calls this per-request and
+   * doesn't cache.
+   */
+  getIdToken(): Promise<string>;
+
+  /** Optional hook: called on 401. Implementations can force a refresh. */
+  onUnauthorized?(): Promise<void>;
+}
+
+/** Convenience: a provider that returns a static string. For workspace API keys or tests. */
+export function staticTokenProvider(token: string): TokenProvider {
+  if (!token) throw new SdkError('EMPTY_TOKEN', 'staticTokenProvider called with empty token');
+  return {
+    async getIdToken() {
+      return token;
+    },
+  };
+}

package/src/authn.ts

@@ -0,0 +1,159 @@
+/**
+ * Identity module — `/v1/auth/*` endpoints.
+ *
+ * Distinct from the TokenProvider abstraction: this is the server-side
+ * identity surface that runs _after_ you've presented a bearer token.
+ * See `packages/docs/guides/02-auth.md`.
+ */
+
+import type { FetchContext } from './internal/fetch.js';
+import { request } from './internal/fetch.js';
+
+export interface MeResponse {
+  user: {
+    id: string;
+    email: string;
+    name?: string;
+    picture?: string;
+  };
+  is_platform_admin: boolean;
+  organizations: Array<{ id: string; name: string; role: string }>;
+  tenants: Array<{ id: string; name: string; role: string }>;
+  active_tenant?: { id: string; name: string; role: string };
+  permissions?: string[];
+  grants?: unknown[];
+}
+
+export interface Tenant {
+  id: string;
+  name: string;
+  org_id?: string;
+  role?: string;
+}
+
+export interface PendingInvitation {
+  id: string;
+  org_id?: string | null;
+  tenant_id?: string | null;
+  email: string;
+  role: string;
+  status: 'pending' | 'accepted' | 'declined' | 'expired' | 'cancelled';
+  expires_at: string;
+  invited_by?: { id: string; name?: string };
+}
+
+export class IdentityModule {
+  constructor(private readonly ctx: FetchContext) {}
+
+  /**
+   * `GET /v1/auth/me` — returns identity + all accessible workspaces.
+   *
+   * Creates the user row on first sign-in. Call this before any other
+   * RCRT endpoint for brand-new Firebase users.
+   */
+  async me(): Promise<MeResponse> {
+    return request<MeResponse>(this.ctx, '/v1/auth/me', { skipTenant: true });
+  }
+
+  /** List workspaces the current user is a member of. */
+  async listTenants(): Promise<Tenant[]> {
+    const res = await request<Tenant[] | { tenants: Tenant[] }>(this.ctx, '/v1/auth/tenants', {
+      skipTenant: true,
+    });
+    return Array.isArray(res) ? res : (res.tenants ?? []);
+  }
+
+  /** Confirm workspace membership. Client code is still responsible for setting X-Tenant-ID. */
+  async selectTenant(tenantId: string): Promise<void> {
+    await request<void>(this.ctx, `/v1/auth/tenants/${tenantId}/select`, {
+      method: 'POST',
+      skipTenant: true,
+    });
+  }
+
+  /** `POST /v1/auth/logout` — server-side no-op; included for symmetry + audit. */
+  async logout(): Promise<void> {
+    await request<void>(this.ctx, '/v1/auth/logout', {
+      method: 'POST',
+      skipTenant: true,
+    });
+  }
+
+  /**
+   * `POST /v1/auth/delete-account` — cascading account deletion.
+   *
+   * **NOT YET ON `development`** at publish time — pending a follow-up
+   * PR. The SDK method exists so consumer code can compile against the
+   * intended shape; invoking it against a gateway that lacks the
+   * handler returns 404.
+   */
+  async deleteAccount(): Promise<void> {
+    await request<void>(this.ctx, '/v1/auth/delete-account', {
+      method: 'POST',
+      skipTenant: true,
+    });
+  }
+
+  /** Pending invitations keyed by the caller's email. */
+  async listPendingInvitations(): Promise<PendingInvitation[]> {
+    const res = await request<
+      PendingInvitation[] | { invitations: PendingInvitation[]; total?: number }
+    >(this.ctx, '/v1/invitations/pending');
+    return Array.isArray(res) ? res : (res.invitations ?? []);
+  }
+
+  async acceptInvitation(token: string): Promise<void> {
+    await request<void>(this.ctx, '/v1/invitations/accept', {
+      method: 'POST',
+      body: { token },
+    });
+  }
+
+  async declineInvitation(invitationId: string): Promise<void> {
+    await request<void>(this.ctx, `/v1/invitations/${invitationId}/decline`, {
+      method: 'POST',
+    });
+  }
+
+  /**
+   * `GET /v1/user/profile` — workspace-scoped user profile breadcrumb.
+   *
+   * Distinct from `me()` — this is the user's editable profile content
+   * (name, timezone, preferences) rather than their identity envelope.
+   * Returns `null` when no profile has been written yet (404 swallowed).
+   */
+  async getUserProfile(): Promise<UserProfileBreadcrumb | null> {
+    try {
+      return await request<UserProfileBreadcrumb>(this.ctx, '/v1/user/profile');
+    } catch (err) {
+      // 404 is the no-profile-yet case — caller renders the onboarding flow.
+      if (err && typeof err === 'object' && 'status' in err && (err as { status: number }).status === 404) {
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * `PUT /v1/user/profile` — upsert. Body fields land on the
+   * underlying breadcrumb's `content` payload.
+   */
+  async updateUserProfile(
+    patch: Record<string, unknown>,
+  ): Promise<UserProfileBreadcrumb> {
+    return request<UserProfileBreadcrumb>(this.ctx, '/v1/user/profile', {
+      method: 'PUT',
+      body: patch,
+    });
+  }
+}
+
+export interface UserProfileBreadcrumb {
+  id: string;
+  title?: string;
+  content: Record<string, unknown>;
+  tags: string[];
+  version: number;
+  created_at?: string;
+  updated_at?: string;
+}

package/src/breadcrumbs.ts

@@ -0,0 +1,111 @@
+/**
+ * Breadcrumbs module — CRUD + tag query + semantic search.
+ *
+ * See `packages/docs/guides/04-breadcrumbs.md` for the narrative
+ * description of each operation.
+ */
+
+import type { FetchContext } from './internal/fetch.js';
+import { request } from './internal/fetch.js';
+import type {
+  Breadcrumb,
+  BreadcrumbResponse,
+  CreateBreadcrumbRequest,
+  UpdateBreadcrumbRequest,
+  QueryByTagsOptions,
+  SemanticSearchOptions,
+} from './types/breadcrumb.js';
+import { ApiError, SdkError } from './errors.js';
+
+export class BreadcrumbsModule {
+  constructor(private readonly ctx: FetchContext) {}
+
+  /** `POST /v1/breadcrumbs` */
+  async create(req: CreateBreadcrumbRequest): Promise<Breadcrumb> {
+    const res = await request<BreadcrumbResponse | Breadcrumb>(this.ctx, '/v1/breadcrumbs', {
+      method: 'POST',
+      body: req,
+    });
+    return 'breadcrumb' in (res as BreadcrumbResponse)
+      ? (res as BreadcrumbResponse).breadcrumb
+      : (res as Breadcrumb);
+  }
+
+  /** `GET /v1/breadcrumbs?tags=...` — AND semantics. */
+  async queryByTags(tags: string[], options: QueryByTagsOptions = {}): Promise<Breadcrumb[]> {
+    if (tags.length === 0) {
+      throw new SdkError('EMPTY_TAGS', 'queryByTags requires at least one tag');
+    }
+    const res = await request<Breadcrumb[] | { breadcrumbs: Breadcrumb[] }>(this.ctx, '/v1/breadcrumbs', {
+      query: {
+        tags: tags.join(','),
+        limit: options.limit,
+        offset: options.offset,
+        name: options.name,
+        order: options.order,
+      },
+    });
+    return Array.isArray(res) ? res : (res.breadcrumbs ?? []);
+  }
+
+  /** `GET /v1/breadcrumbs/search?q=...` — cosine-similarity semantic search. */
+  async search(q: string, options: SemanticSearchOptions = {}): Promise<Breadcrumb[]> {
+    const query: Record<string, string | number | undefined> = {
+      q,
+      limit: options.limit,
+    };
+    if (options.tags?.length) query.tags = options.tags.join(',');
+    const res = await request<Breadcrumb[] | { breadcrumbs: Breadcrumb[] }>(this.ctx, '/v1/breadcrumbs/search', { query });
+    return Array.isArray(res) ? res : (res.breadcrumbs ?? []);
+  }
+
+  /** `GET /v1/breadcrumbs/{id}` */
+  async get(id: string): Promise<Breadcrumb> {
+    return request<Breadcrumb>(this.ctx, `/v1/breadcrumbs/${id}`);
+  }
+
+  /**
+   * `PATCH /v1/breadcrumbs/{id}` — optimistic-locking update.
+   *
+   * If `req.version` is wrong, the server returns 409. Pass
+   * `autoRetryConflict: true` to have the SDK refetch + retry once.
+   */
+  async update(
+    id: string,
+    req: UpdateBreadcrumbRequest,
+    opts: { autoRetryConflict?: boolean } = {},
+  ): Promise<Breadcrumb> {
+    const refetchBeforeRetry = opts.autoRetryConflict
+      ? async () => {
+          const fresh = await this.get(id);
+          return {
+            body: {
+              ...req,
+              version: fresh.version,
+            } satisfies UpdateBreadcrumbRequest,
+          };
+        }
+      : undefined;
+
+    const res = await request<BreadcrumbResponse | Breadcrumb>(this.ctx, `/v1/breadcrumbs/${id}`, {
+      method: 'PATCH',
+      body: req,
+      ...(refetchBeforeRetry
+        ? { maxConflictRetries: 2, refetchBeforeRetry }
+        : {}),
+    });
+    return 'breadcrumb' in (res as BreadcrumbResponse)
+      ? (res as BreadcrumbResponse).breadcrumb
+      : (res as Breadcrumb);
+  }
+
+  /** `DELETE /v1/breadcrumbs/{id}` — soft delete. */
+  async delete(id: string): Promise<void> {
+    try {
+      await request<void>(this.ctx, `/v1/breadcrumbs/${id}`, { method: 'DELETE' });
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 404) return; // idempotent
+      throw err;
+    }
+  }
+}

package/src/capabilities.ts

@@ -0,0 +1,93 @@
+/**
+ * Capabilities module — discover what the current workspace can do.
+ *
+ * In RCRT, capabilities are breadcrumbs tagged with `interpret:*`:
+ *   - `interpret:executable` — tools (functions an agent can call)
+ *   - `interpret:promptable` — agents (entities the user / other
+ *     agents can `chat.send()` to)
+ *   - `interpret:service-def` — connectable services (Gmail, Notion,
+ *     etc.) with their OAuth metadata
+ *   - `interpret:knowledge` — static knowledge bases attached to the
+ *     workspace
+ *
+ * This module is a thin convenience layer over `breadcrumbs.queryByTags`
+ * that maps the `type` argument to the right tag.
+ */
+
+import type { FetchContext } from './internal/fetch.js';
+import { request } from './internal/fetch.js';
+import type { Breadcrumb } from './types/breadcrumb.js';
+
+export type CapabilityType = 'tools' | 'agents' | 'services' | 'knowledge';
+
+const TAG_BY_TYPE: Record<CapabilityType, string> = {
+  tools: 'interpret:executable',
+  agents: 'interpret:promptable',
+  services: 'interpret:service-def',
+  knowledge: 'interpret:knowledge',
+};
+
+export interface ChattableAgent {
+  /** The id you pass to `chat.send({ target_agent: ... })`. */
+  id: string;
+  name: string;
+  description: string;
+  /** True when this agent has the `interface:chat-default` tag. */
+  isDefault: boolean;
+}
+
+export class CapabilitiesModule {
+  constructor(private readonly ctx: FetchContext) {}
+
+  /**
+   * List every capability of every type. Useful when surfacing the
+   * full toolbelt + agent roster to a debug / admin view.
+   */
+  async listAll(limit: number = 200): Promise<Breadcrumb[]> {
+    const res = await request<Breadcrumb[] | { breadcrumbs: Breadcrumb[] }>(
+      this.ctx,
+      '/v1/breadcrumbs',
+      { query: { tags: TAG_BY_TYPE.tools, limit } },
+    );
+    return Array.isArray(res) ? res : (res.breadcrumbs ?? []);
+  }
+
+  /** List capabilities of one specific type. */
+  async list(type: CapabilityType, limit: number = 200): Promise<Breadcrumb[]> {
+    const tag = TAG_BY_TYPE[type];
+    const res = await request<Breadcrumb[] | { breadcrumbs: Breadcrumb[] }>(
+      this.ctx,
+      '/v1/breadcrumbs',
+      { query: { tags: tag, limit } },
+    );
+    return Array.isArray(res) ? res : (res.breadcrumbs ?? []);
+  }
+
+  /**
+   * Convenience: agents the user can chat with directly.
+   *
+   * Filters `interpret:promptable` to those tagged `interface:chat`
+   * or `interface:chat-default`. Falls back to all promptables when
+   * no agents have a chat interface tag (older deploys).
+   */
+  async getChattableAgents(limit: number = 50): Promise<ChattableAgent[]> {
+    const promptables = await this.list('agents', limit);
+    const chatAgents = promptables.filter((bc) =>
+      bc.tags?.some(
+        (t) => t === 'interface:chat' || t === 'interface:chat-default',
+      ),
+    );
+    const source = chatAgents.length > 0 ? chatAgents : promptables;
+    return source.map<ChattableAgent>((bc) => {
+      const content = (bc.content ?? {}) as Record<string, unknown>;
+      const id = (bc as { name?: string }).name ?? bc.id;
+      const name =
+        (content.name as string | undefined) ??
+        (bc as { title?: string }).title ??
+        id;
+      const description = (content.description as string | undefined) ?? '';
+      const isDefault = !!bc.tags?.includes('interface:chat-default');
+      return { id, name, description, isDefault };
+    });
+  }
+}