@possibl/rcrt-sdk 0.1.2 → 0.5.0

package/dist/breadcrumbs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 type { Breadcrumb, CreateBreadcrumbRequest, UpdateBreadcrumbRequest, QueryByTagsOptions, SemanticSearchOptions } from './types/breadcrumb.js';
+export declare class BreadcrumbsModule {
+    private readonly ctx;
+    constructor(ctx: FetchContext);
+    /** `POST /v1/breadcrumbs` */
+    create(req: CreateBreadcrumbRequest): Promise<Breadcrumb>;
+    /** `GET /v1/breadcrumbs?tags=...` — AND semantics. */
+    queryByTags(tags: string[], options?: QueryByTagsOptions): Promise<Breadcrumb[]>;
+    /** `GET /v1/breadcrumbs/search?q=...` — cosine-similarity semantic search. */
+    search(q: string, options?: SemanticSearchOptions): Promise<Breadcrumb[]>;
+    /** `GET /v1/breadcrumbs/{id}` */
+    get(id: string): Promise<Breadcrumb>;
+    /**
+     * `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.
+     */
+    update(id: string, req: UpdateBreadcrumbRequest, opts?: {
+        autoRetryConflict?: boolean;
+    }): Promise<Breadcrumb>;
+    /**
+     * Set an agent breadcrumb's `engine_config.model` to a canonical
+     * `route/provider/model` address (the runtime SSOT for LLM selection — see
+     * docs/design/LLM_PROVIDER_MODEL_RESOLUTION.md).
+     *
+     * Fetches the current breadcrumb to preserve the rest of `content` and
+     * `engine_config`, then PATCHes with the supplied optimistic-locking
+     * `version`. The `modelAddress` is NOT validated here beyond non-emptiness;
+     * the backend rejects malformed/unexpanded-tier addresses loudly at runtime.
+     */
+    updateAgentEngineConfig(id: string, modelAddress: string, version: number): Promise<Breadcrumb>;
+    /** `DELETE /v1/breadcrumbs/{id}` — soft delete. */
+    delete(id: string): Promise<void>;
+}
+//# sourceMappingURL=breadcrumbs.d.ts.map

package/dist/breadcrumbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"breadcrumbs.d.ts","sourceRoot":"","sources":["../src/breadcrumbs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EACV,UAAU,EAEV,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAG/B,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,YAAY;IAE9C,6BAA6B;IACvB,MAAM,CAAC,GAAG,EAAE,uBAAuB,GAAG,OAAO,CAAC,UAAU,CAAC;IAU/D,sDAAsD;IAChD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAgB1F,8EAA8E;IACxE,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAUnF,iCAAiC;IAC3B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAI1C;;;;;OAKG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,uBAAuB,EAC5B,IAAI,GAAE;QAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;KAAO,GACzC,OAAO,CAAC,UAAU,CAAC;IAyBtB;;;;;;;;;OASG;IACG,uBAAuB,CAC3B,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,CAAC;IAiBtB,mDAAmD;IAC7C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQxC"}

package/dist/breadcrumbs.js

@@ -0,0 +1,122 @@
+/**
+ * Breadcrumbs module — CRUD + tag query + semantic search.
+ *
+ * See `packages/docs/guides/04-breadcrumbs.md` for the narrative
+ * description of each operation.
+ */
+import { request } from './internal/fetch.js';
+import { ApiError, SdkError } from './errors.js';
+export class BreadcrumbsModule {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** `POST /v1/breadcrumbs` */
+    async create(req) {
+        const res = await request(this.ctx, '/v1/breadcrumbs', {
+            method: 'POST',
+            body: req,
+        });
+        return 'breadcrumb' in res
+            ? res.breadcrumb
+            : res;
+    }
+    /** `GET /v1/breadcrumbs?tags=...` — AND semantics. */
+    async queryByTags(tags, options = {}) {
+        if (tags.length === 0) {
+            throw new SdkError('EMPTY_TAGS', 'queryByTags requires at least one tag');
+        }
+        const res = await request(this.ctx, '/v1/breadcrumbs', {
+            query: {
+                tags,
+                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, options = {}) {
+        const query = {
+            q,
+            limit: options.limit,
+        };
+        if (options.tags?.length)
+            query.tags = options.tags;
+        const res = await request(this.ctx, '/v1/breadcrumbs/search', { query });
+        return Array.isArray(res) ? res : (res.breadcrumbs ?? []);
+    }
+    /** `GET /v1/breadcrumbs/{id}` */
+    async get(id) {
+        return request(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, req, opts = {}) {
+        const refetchBeforeRetry = opts.autoRetryConflict
+            ? async () => {
+                const fresh = await this.get(id);
+                return {
+                    body: {
+                        ...req,
+                        version: fresh.version,
+                    },
+                };
+            }
+            : undefined;
+        const res = await request(this.ctx, `/v1/breadcrumbs/${id}`, {
+            method: 'PATCH',
+            body: req,
+            ...(refetchBeforeRetry
+                ? { maxConflictRetries: 2, refetchBeforeRetry }
+                : {}),
+        });
+        return 'breadcrumb' in res
+            ? res.breadcrumb
+            : res;
+    }
+    /**
+     * Set an agent breadcrumb's `engine_config.model` to a canonical
+     * `route/provider/model` address (the runtime SSOT for LLM selection — see
+     * docs/design/LLM_PROVIDER_MODEL_RESOLUTION.md).
+     *
+     * Fetches the current breadcrumb to preserve the rest of `content` and
+     * `engine_config`, then PATCHes with the supplied optimistic-locking
+     * `version`. The `modelAddress` is NOT validated here beyond non-emptiness;
+     * the backend rejects malformed/unexpanded-tier addresses loudly at runtime.
+     */
+    async updateAgentEngineConfig(id, modelAddress, version) {
+        if (!modelAddress || modelAddress.trim() === '') {
+            throw new SdkError('EMPTY_MODEL_ADDRESS', 'updateAgentEngineConfig requires a non-empty route/provider/model address');
+        }
+        const current = await this.get(id);
+        const content = (current.content ?? {});
+        const engineConfig = (content.engine_config ?? {});
+        const nextContent = {
+            ...content,
+            engine_config: {
+                ...engineConfig,
+                model: modelAddress.trim(),
+            },
+        };
+        return this.update(id, { content: nextContent, version });
+    }
+    /** `DELETE /v1/breadcrumbs/{id}` — soft delete. */
+    async delete(id) {
+        try {
+            await request(this.ctx, `/v1/breadcrumbs/${id}`, { method: 'DELETE' });
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 404)
+                return; // idempotent
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=breadcrumbs.js.map

package/dist/breadcrumbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breadcrumbs.js","sourceRoot":"","sources":["../src/breadcrumbs.ts"],"names":[],"mappings":"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"}

package/dist/cards.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Cards module — resolve an `interpret:pending-action` breadcrumb.
+ *
+ * The card's footer action ids correspond to values the SDK writes
+ * to `content.status`. See
+ * `packages/docs/guides/06-rendering-cards.md`.
+ */
+import type { FetchContext } from './internal/fetch.js';
+import type { Breadcrumb } from './types/breadcrumb.js';
+import type { Card, ResolveRequest } from './types/card.js';
+export declare class CardsModule {
+    private readonly ctx;
+    constructor(ctx: FetchContext);
+    /**
+     * PATCH the card breadcrumb with a resolution. Handles optimistic
+     * locking transparently — refetches + retries on 409.
+     */
+    resolve(breadcrumbId: string, resolution: ResolveRequest): Promise<Breadcrumb>;
+    /** Pending cards for the current user's current workspace. */
+    listPending(limit?: number): Promise<Breadcrumb[]>;
+    /**
+     * Extract the Card object from a breadcrumb's content, normalising
+     * over legacy shapes (old breadcrumbs stored `card.type` + flat
+     * fields instead of `card.layout` + structured body).
+     */
+    static extractCard(bc: Breadcrumb): Card | undefined;
+}
+//# sourceMappingURL=cards.d.ts.map

package/dist/cards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cards.d.ts","sourceRoot":"","sources":["../src/cards.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5D,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,YAAY;IAE9C;;;OAGG;IACG,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IAmCpF,8DAA8D;IACxD,WAAW,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAOpD;;;;OAIG;IACH,MAAM,CAAC,WAAW,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS;CAkBrD"}

package/dist/cards.js

@@ -0,0 +1,105 @@
+/**
+ * Cards module — resolve an `interpret:pending-action` breadcrumb.
+ *
+ * The card's footer action ids correspond to values the SDK writes
+ * to `content.status`. See
+ * `packages/docs/guides/06-rendering-cards.md`.
+ */
+import { request } from './internal/fetch.js';
+export class CardsModule {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * PATCH the card breadcrumb with a resolution. Handles optimistic
+     * locking transparently — refetches + retries on 409.
+     */
+    async resolve(breadcrumbId, resolution) {
+        const current = await request(this.ctx, `/v1/breadcrumbs/${breadcrumbId}`);
+        const nextContent = {
+            ...(current.content ?? {}),
+            status: resolution.status,
+            user_response: resolution.user_response,
+            resolved_at: new Date().toISOString(),
+        };
+        const nextTags = ensureStatusTag(current.tags, resolution.status);
+        return request(this.ctx, `/v1/breadcrumbs/${breadcrumbId}`, {
+            method: 'PATCH',
+            body: {
+                version: current.version,
+                content: nextContent,
+                tags: nextTags,
+            },
+            maxConflictRetries: 2,
+            refetchBeforeRetry: async () => {
+                const fresh = await request(this.ctx, `/v1/breadcrumbs/${breadcrumbId}`);
+                return {
+                    body: {
+                        version: fresh.version,
+                        content: {
+                            ...(fresh.content ?? {}),
+                            status: resolution.status,
+                            user_response: resolution.user_response,
+                            resolved_at: new Date().toISOString(),
+                        },
+                        tags: ensureStatusTag(fresh.tags, resolution.status),
+                    },
+                };
+            },
+        });
+    }
+    /** Pending cards for the current user's current workspace. */
+    async listPending(limit = 50) {
+        const list = await request(this.ctx, '/v1/breadcrumbs', {
+            query: { tags: 'interpret:pending-action,status:pending', limit },
+        });
+        return Array.isArray(list) ? list : (list.breadcrumbs ?? []);
+    }
+    /**
+     * Extract the Card object from a breadcrumb's content, normalising
+     * over legacy shapes (old breadcrumbs stored `card.type` + flat
+     * fields instead of `card.layout` + structured body).
+     */
+    static extractCard(bc) {
+        const content = (bc.content ?? {});
+        const raw = content.card ?? undefined;
+        if (!raw)
+            return undefined;
+        if (typeof raw.layout === 'string')
+            return raw;
+        // Legacy — fall back to a minimal info card.
+        if (typeof raw.type === 'string') {
+            const card = {
+                layout: legacyTypeToLayout(raw.type),
+                header: { title: typeof content.title === 'string' ? content.title : bc.title },
+            };
+            if (typeof content.summary === 'string') {
+                card.body = { text: content.summary };
+            }
+            return card;
+        }
+        return undefined;
+    }
+}
+function ensureStatusTag(existing, status) {
+    const withoutStatus = existing.filter((t) => !t.startsWith('status:'));
+    withoutStatus.push(`status:${status}`);
+    return withoutStatus;
+}
+function legacyTypeToLayout(type) {
+    switch (type) {
+        case 'connect':
+            return 'connect';
+        case 'confirm':
+        case 'choice':
+        case 'multi-choice':
+        case 'approval':
+            return 'decision';
+        case 'text-input':
+            return 'input';
+        default:
+            return 'info';
+    }
+}
+//# sourceMappingURL=cards.js.map

package/dist/cards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cards.js","sourceRoot":"","sources":["../src/cards.ts"],"names":[],"mappings":"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"}

package/dist/chat.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Chat module — `POST /v1/chat` + per-session / global SSE streams.
+ *
+ * See `packages/docs/guides/03-chat-and-sse.md`.
+ */
+import type { FetchContext } from './internal/fetch.js';
+import type { SseConnection, SseConnectConfig, SseHandlers } from './internal/sse.js';
+import type { Breadcrumb } from './types/breadcrumb.js';
+/**
+ * A previously uploaded file attached to a chat turn. Mirrors the api-gateway
+ * `ChatRequest.Attachments` contract (`cmd/api-gateway/main.go::ChatAttachmentRef`).
+ *
+ * `file_breadcrumb_id` is the file breadcrumb's id — the value returned by
+ * `FilesModule.upload(...)` as `FileRecord.id`. The server resolves it to the
+ * object's `gs://` URI + mime type and threads it to a file-capable agent.
+ * `mime_type` is an optional override; the server reads it from the breadcrumb
+ * when omitted. A raw `gs://` URI is NOT accepted here — only a breadcrumb id.
+ */
+export interface ChatAttachmentRef {
+    file_breadcrumb_id: string;
+    mime_type?: string;
+}
+export interface SendChatRequest {
+    message: string;
+    /** The agent to route this turn to. `life-coordinator` by default in the Ritual bundle. */
+    target_agent: string;
+    /** Resume an existing session; omit to start a new one. */
+    session_id?: string;
+    /** Extra tags stamped on the user's message breadcrumb. */
+    extra_tags?: string[];
+    /**
+     * Files (e.g. an uploaded contract PDF or image) to deliver to a file-capable
+     * agent. Upload via `client.files.upload(...)` first, then pass the returned
+     * `FileRecord.id` as `file_breadcrumb_id`. Omit for an ordinary text turn —
+     * the wire body is then unchanged.
+     */
+    attachments?: ChatAttachmentRef[];
+}
+export interface SendChatResponse {
+    id: string;
+    session_id: string;
+}
+export interface SessionParticipant {
+    agent_id: string;
+    name?: string;
+    invited_by?: string;
+    joined_at?: string;
+    [key: string]: unknown;
+}
+/** An agent that can be chatted with / invited into a session. */
+export interface ChattableAgent {
+    /** The id chat routing expects in `target_agent`. */
+    id: string;
+    name: string;
+    description: string;
+    /** Tagged `interface:chat-default` — pick this one when the app has no opinion. */
+    isDefault: boolean;
+}
+export interface SseStreamOptions {
+    /** Override the EventSource constructor (required in React Native). */
+    eventSource?: SseConnectConfig['eventSource'];
+    useHeaderAuth?: boolean;
+    maxBackoffMs?: number;
+    /** Supply a Last-Event-ID-style resume token if your server supports it. */
+    last_event_id?: string;
+}
+export declare class ChatModule {
+    private readonly ctx;
+    constructor(ctx: FetchContext);
+    /**
+     * Send a user message to an agent. Returns immediately with the
+     * breadcrumb id + session id. The agent reply arrives via the SSE
+     * stream — call `stream(session_id)` before posting, not after.
+     */
+    send(req: SendChatRequest): Promise<SendChatResponse>;
+    /** Per-session SSE — just this session's events. Recommended for chat views. */
+    sessionStream(sessionId: string, handlers: SseHandlers, options?: SseStreamOptions): SseConnection;
+    /** Global SSE — everything the user can see. Useful for home feeds / awaiting-you. */
+    globalStream(handlers: SseHandlers, options?: SseStreamOptions): SseConnection;
+    private buildConfig;
+    /**
+     * Clear a session's suspend flag after the loop detector fired.
+     *
+     * @see `packages/docs/operations/loop-detector.md`
+     */
+    resumeSession(sessionId: string): Promise<void>;
+    /** A session's message breadcrumbs (tag query on `session:{id}`). */
+    sessionBreadcrumbs(sessionId: string, limit?: number): Promise<Breadcrumb[]>;
+    /** `GET /v1/sessions/{id}/participants` */
+    sessionParticipants(sessionId: string): Promise<SessionParticipant[]>;
+    /** `POST /v1/sessions/{id}/participants` — invite an agent into the session. */
+    addSessionParticipant(sessionId: string, agentId: string, invitedBy?: string): Promise<void>;
+    /** `DELETE /v1/sessions/{id}/participants/{agentId}` */
+    removeSessionParticipant(sessionId: string, agentId: string): Promise<void>;
+    /**
+     * Agents in the active workspace that can be chatted with / invited.
+     * Derived from `interpret:promptable` breadcrumbs; agents tagged
+     * `interface:chat` (or `interface:chat-default`) are preferred when
+     * any exist.
+     */
+    listAgents(): Promise<ChattableAgent[]>;
+}
+//# sourceMappingURL=chat.d.ts.map

package/dist/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../src/chat.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEtF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,WAAW,CAAC,EAAE,gBAAgB,CAAC,aAAa,CAAC,CAAC;IAC9C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,YAAY;IAE9C;;;;OAIG;IACG,IAAI,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAO3D,gFAAgF;IAChF,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,GAAE,gBAAqB,GAAG,aAAa;IAItG,sFAAsF;IACtF,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,GAAE,gBAAqB,GAAG,aAAa;IAIlF,OAAO,CAAC,WAAW;IAcnB;;;;OAIG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrD,qEAAqE;IAC/D,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAO/E,2CAA2C;IACrC,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAQ3E,gFAAgF;IAC1E,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlG,wDAAwD;IAClD,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQjF;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;CAgB9C"}

package/dist/chat.js

@@ -0,0 +1,105 @@
+/**
+ * Chat module — `POST /v1/chat` + per-session / global SSE streams.
+ *
+ * See `packages/docs/guides/03-chat-and-sse.md`.
+ */
+import { request } from './internal/fetch.js';
+import { connect as sseConnect } from './internal/sse.js';
+export class ChatModule {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * Send a user message to an agent. Returns immediately with the
+     * breadcrumb id + session id. The agent reply arrives via the SSE
+     * stream — call `stream(session_id)` before posting, not after.
+     */
+    async send(req) {
+        return request(this.ctx, '/v1/chat', {
+            method: 'POST',
+            body: req,
+        });
+    }
+    /** Per-session SSE — just this session's events. Recommended for chat views. */
+    sessionStream(sessionId, handlers, options = {}) {
+        return sseConnect(this.buildConfig(`/v1/sessions/${sessionId}/stream`, options), handlers);
+    }
+    /** Global SSE — everything the user can see. Useful for home feeds / awaiting-you. */
+    globalStream(handlers, options = {}) {
+        return sseConnect(this.buildConfig('/v1/events', options), handlers);
+    }
+    buildConfig(path, options) {
+        const config = {
+            apiUrl: this.ctx.apiUrl,
+            path,
+            tenantId: this.ctx.tenantId,
+            getToken: () => this.ctx.tokenProvider.getIdToken(),
+        };
+        if (options.eventSource)
+            config.eventSource = options.eventSource;
+        if (options.useHeaderAuth !== undefined)
+            config.useHeaderAuth = options.useHeaderAuth;
+        if (options.maxBackoffMs !== undefined)
+            config.maxBackoffMs = options.maxBackoffMs;
+        if (options.last_event_id)
+            config.query = { last_event_id: options.last_event_id };
+        return config;
+    }
+    /**
+     * Clear a session's suspend flag after the loop detector fired.
+     *
+     * @see `packages/docs/operations/loop-detector.md`
+     */
+    async resumeSession(sessionId) {
+        await request(this.ctx, `/v1/sessions/${sessionId}/resume`, { method: 'POST' });
+    }
+    // ── Session history + participants ────────────────────────────────
+    /** A session's message breadcrumbs (tag query on `session:{id}`). */
+    async sessionBreadcrumbs(sessionId, limit = 100) {
+        const res = await request(this.ctx, '/v1/breadcrumbs', {
+            query: { tags: [`session:${sessionId}`], limit },
+        });
+        return Array.isArray(res) ? res : (res?.breadcrumbs ?? []);
+    }
+    /** `GET /v1/sessions/{id}/participants` */
+    async sessionParticipants(sessionId) {
+        const res = await request(this.ctx, `/v1/sessions/${sessionId}/participants`);
+        return res?.participants ?? [];
+    }
+    /** `POST /v1/sessions/{id}/participants` — invite an agent into the session. */
+    async addSessionParticipant(sessionId, agentId, invitedBy) {
+        await request(this.ctx, `/v1/sessions/${sessionId}/participants`, {
+            method: 'POST',
+            body: { agent_id: agentId, ...(invitedBy ? { invited_by: invitedBy } : {}) },
+        });
+    }
+    /** `DELETE /v1/sessions/{id}/participants/{agentId}` */
+    async removeSessionParticipant(sessionId, agentId) {
+        await request(this.ctx, `/v1/sessions/${sessionId}/participants/${agentId}`, {
+            method: 'DELETE',
+        });
+    }
+    // ── Agent discovery ───────────────────────────────────────────────
+    /**
+     * Agents in the active workspace that can be chatted with / invited.
+     * Derived from `interpret:promptable` breadcrumbs; agents tagged
+     * `interface:chat` (or `interface:chat-default`) are preferred when
+     * any exist.
+     */
+    async listAgents() {
+        const res = await request(this.ctx, '/v1/breadcrumbs', {
+            query: { tags: ['interpret:promptable'], limit: 100 },
+        });
+        const all = Array.isArray(res) ? res : (res?.breadcrumbs ?? []);
+        const chatTagged = all.filter((bc) => bc.tags?.includes('interface:chat') || bc.tags?.includes('interface:chat-default'));
+        const agents = chatTagged.length > 0 ? chatTagged : all;
+        return agents.map((bc) => ({
+            id: bc.name || bc.id,
+            name: bc.content?.name || bc.title,
+            description: bc.content?.description || '',
+            isDefault: Boolean(bc.tags?.includes('interface:chat-default')),
+        }));
+    }
+}
+//# sourceMappingURL=chat.js.map

package/dist/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../src/chat.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE9C,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAmE1D,MAAM,OAAO,UAAU;IACQ;IAA7B,YAA6B,GAAiB;QAAjB,QAAG,GAAH,GAAG,CAAc;IAAG,CAAC;IAElD;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,GAAoB;QAC7B,OAAO,OAAO,CAAmB,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE;YACrD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,GAAG;SACV,CAAC,CAAC;IACL,CAAC;IAED,gFAAgF;IAChF,aAAa,CAAC,SAAiB,EAAE,QAAqB,EAAE,UAA4B,EAAE;QACpF,OAAO,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,gBAAgB,SAAS,SAAS,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC7F,CAAC;IAED,sFAAsF;IACtF,YAAY,CAAC,QAAqB,EAAE,UAA4B,EAAE;QAChE,OAAO,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,YAAY,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC;IACvE,CAAC;IAEO,WAAW,CAAC,IAAY,EAAE,OAAyB;QACzD,MAAM,MAAM,GAAqB;YAC/B,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM;YACvB,IAAI;YACJ,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ;YAC3B,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,UAAU,EAAE;SACpD,CAAC;QACF,IAAI,OAAO,CAAC,WAAW;YAAE,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QAClE,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS;YAAE,MAAM,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QACtF,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS;YAAE,MAAM,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACnF,IAAI,OAAO,CAAC,aAAa;YAAE,MAAM,CAAC,KAAK,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC;QACnF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,aAAa,CAAC,SAAiB;QACnC,MAAM,OAAO,CAAO,IAAI,CAAC,GAAG,EAAE,gBAAgB,SAAS,SAAS,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,qEAAqE;IAErE,qEAAqE;IACrE,KAAK,CAAC,kBAAkB,CAAC,SAAiB,EAAE,KAAK,GAAG,GAAG;QACrD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAgD,IAAI,CAAC,GAAG,EAAE,iBAAiB,EAAE;YACpG,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,WAAW,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE;SACjD,CAAC,CAAC;QACH,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,2CAA2C;IAC3C,KAAK,CAAC,mBAAmB,CAAC,SAAiB;QACzC,MAAM,GAAG,GAAG,MAAM,OAAO,CACvB,IAAI,CAAC,GAAG,EACR,gBAAgB,SAAS,eAAe,CACzC,CAAC;QACF,OAAO,GAAG,EAAE,YAAY,IAAI,EAAE,CAAC;IACjC,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,qBAAqB,CAAC,SAAiB,EAAE,OAAe,EAAE,SAAkB;QAChF,MAAM,OAAO,CAAO,IAAI,CAAC,GAAG,EAAE,gBAAgB,SAAS,eAAe,EAAE;YACtE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;SAC7E,CAAC,CAAC;IACL,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,wBAAwB,CAAC,SAAiB,EAAE,OAAe;QAC/D,MAAM,OAAO,CAAO,IAAI,CAAC,GAAG,EAAE,gBAAgB,SAAS,iBAAiB,OAAO,EAAE,EAAE;YACjF,MAAM,EAAE,QAAQ;SACjB,CAAC,CAAC;IACL,CAAC;IAED,qEAAqE;IAErE;;;;;OAKG;IACH,KAAK,CAAC,UAAU;QACd,MAAM,GAAG,GAAG,MAAM,OAAO,CAAgD,IAAI,CAAC,GAAG,EAAE,iBAAiB,EAAE;YACpG,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,sBAAsB,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE;SACtD,CAAC,CAAC;QACH,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC;QAChE,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAC3B,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,wBAAwB,CAAC,CAC3F,CAAC;QACF,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC;QACxD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YACzB,EAAE,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE;YACpB,IAAI,EAAG,EAAE,CAAC,OAAO,EAAE,IAAe,IAAI,EAAE,CAAC,KAAK;YAC9C,WAAW,EAAG,EAAE,CAAC,OAAO,EAAE,WAAsB,IAAI,EAAE;YACtD,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,wBAAwB,CAAC,CAAC;SAChE,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

package/dist/client.d.ts

@@ -0,0 +1,85 @@
+/**
+ * RcrtClient — the single entry-point to the SDK.
+ *
+ *     import { RcrtClient, staticTokenProvider } from '@possibl/rcrt-sdk';
+ *
+ *     const rcrt = new RcrtClient({
+ *       apiUrl: 'https://rcrt-api-gateway-<hash>.run.app',
+ *       tokenProvider: firebaseTokenProvider(auth),
+ *     });
+ *
+ *     rcrt.setTenantId(workspaceId);
+ *     const me = await rcrt.auth.me();
+ *     const stream = rcrt.chat.sessionStream(sessionId, { ...handlers });
+ *
+ * Every module on the client shares the same fetch context — one
+ * bearer refresh path, one tenant header, one error envelope.
+ *
+ * For fleet fan-out across workspaces, prefer `forTenant()` over
+ * mutating one client with `setTenantId()`:
+ *
+ *     await Promise.all(workspaces.map((ws) =>
+ *       rcrt.forTenant(ws.id).breadcrumbs.queryByTags(['interpret:alert']),
+ *     ));
+ */
+import type { TokenProvider } from './auth.js';
+import type { RequestOptions } from './internal/fetch.js';
+import { BreadcrumbsModule } from './breadcrumbs.js';
+import { ChatModule } from './chat.js';
+import { CardsModule } from './cards.js';
+import { GrantsModule } from './grants.js';
+import { IdentityModule } from './authn.js';
+import { MarketplaceModule } from './marketplace.js';
+import { OrgModule } from './org.js';
+import { FilesModule } from './files.js';
+import { MembersModule } from './members.js';
+export interface RcrtClientConfig {
+    apiUrl: string;
+    tokenProvider: TokenProvider;
+    /** Optional workspace UUID. Can be set later via `setTenantId()`. */
+    tenantId?: string;
+    /** Optional fetch override (SSR, custom retry, mock). */
+    fetchImpl?: typeof fetch;
+}
+export declare class RcrtClient {
+    private readonly ctx;
+    private readonly config;
+    private readonly tenantClients;
+    readonly auth: IdentityModule;
+    readonly breadcrumbs: BreadcrumbsModule;
+    readonly chat: ChatModule;
+    readonly cards: CardsModule;
+    readonly grants: GrantsModule;
+    readonly marketplace: MarketplaceModule;
+    readonly org: OrgModule;
+    readonly files: FilesModule;
+    readonly members: MembersModule;
+    constructor(config: RcrtClientConfig);
+    /** Switch workspaces. Subsequent requests carry the new `X-Tenant-ID`. */
+    setTenantId(tenantId: string | null): void;
+    /** Read the workspace id this client is currently scoped to. */
+    getTenantId(): string | null;
+    /**
+     * A client permanently bound to `tenantId` — same apiUrl, token
+     * provider and fetch impl, its own tenant header. Instances are
+     * cached per tenant and are just thin header wrappers, so parallel
+     * fleet fan-out is safe and cheap (no shared-client races, no
+     * serialisation through `setTenantId`).
+     */
+    forTenant(tenantId: string): RcrtClient;
+    /**
+     * Typed escape hatch — call any gateway endpoint with the client's
+     * auth + tenant + retry handling. Apps are never blocked on an SDK
+     * release for a new endpoint:
+     *
+     *     const res = await rcrt.request<{ items: Item[] }>('/v1/some/new/endpoint', {
+     *       method: 'POST',
+     *       body: { hello: 'world' },   // plain object — the SDK serialises
+     *     });
+     *
+     * `options.body` is JSON-serialised; use `options.rawBody` for
+     * FormData / binary payloads; `options.query` appends search params.
+     */
+    request<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAExE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,aAAa,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiC;IAE/D,SAAgB,IAAI,EAAE,cAAc,CAAC;IACrC,SAAgB,WAAW,EAAE,iBAAiB,CAAC;IAC/C,SAAgB,IAAI,EAAE,UAAU,CAAC;IACjC,SAAgB,KAAK,EAAE,WAAW,CAAC;IACnC,SAAgB,MAAM,EAAE,YAAY,CAAC;IACrC,SAAgB,WAAW,EAAE,iBAAiB,CAAC;IAC/C,SAAgB,GAAG,EAAE,SAAS,CAAC;IAC/B,SAAgB,KAAK,EAAE,WAAW,CAAC;IACnC,SAAgB,OAAO,EAAE,aAAa,CAAC;gBAE3B,MAAM,EAAE,gBAAgB;IAuCpC,0EAA0E;IAC1E,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI1C,gEAAgE;IAChE,WAAW,IAAI,MAAM,GAAG,IAAI;IAI5B;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU;IAkBvC;;;;;;;;;;;;OAYG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;CAGnF"}