palbase 0.6.2 → 0.7.0

package/types/backend/src/runtime.d.ts

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { type AI } from '../../ai/src/index.js';
 import type { PalbaseServer } from '../../server/src/index.js';
 import type { AtomicDatabase as AtomicOf, EnvTypedDatabase } from 'palgres';
 import type { Schemas, Tables } from './db-env.js';
@@ -29,8 +30,43 @@ export declare function scoped<T extends object>(name: string, impl: T): T;
  */
 export declare function serviceOf<T extends object>(name: string, key: PropertyKey, impl: T): T;
 export declare const requestScope: AsyncLocalStorage<RequestScope>;
-/** The project's modules: auth, storage, notify, secrets, flags, analytics, realtime, machines. */
-export declare const Palbase: PalbaseServer;
+type GatewayEventsOf<G> = G extends {
+    readonly events: infer E;
+} ? E : Record<never, never>;
+type GatewayPayloadOf<S> = S extends {
+    readonly '~standard': {
+        readonly types?: {
+            readonly input: infer I;
+        };
+    };
+} ? I : unknown;
+/** A gateway's channel, to send its events to (Palbase.gateways.to). */
+export interface GatewayTarget<G> {
+    /**
+     * `event` to every member of the channel, its payload as the gateway's
+     * static events type it. Sent in the order emitted, never thrown: what could
+     * not be sent is in the app's log. A durable gateway keeps it.
+     */
+    emit<K extends keyof GatewayEventsOf<G> & string>(event: K, payload: GatewayPayloadOf<GatewayEventsOf<G>[K]>): void;
+    /** The platform writes `source` into the channel from now on: a chat's stream (Palbase.ai.chats.events(id)). */
+    pipe(source: {
+        pipe(topic: string): Promise<void>;
+    }): Promise<void>;
+}
+/** The app's gateways, from any service: Palbase.gateways.to(ChatGateway, { chatId }).emit('token', { text }). */
+export interface GatewaysApi {
+    to<G extends Function>(gateway: G, params: Readonly<Record<string, string>>): GatewayTarget<G>;
+}
+/**
+ * The project as the app's server reaches it: its modules — auth, storage, notify, secrets, flags, analytics,
+ * realtime, machines — its models and agents (Palbase.ai: ask, generate, stream, embed, tools, agents, chats), and
+ * the app's gateways (Palbase.gateways).
+ */
+export type PalbaseApp = Omit<PalbaseServer, 'ai'> & {
+    readonly ai: AI;
+    readonly gateways: GatewaysApi;
+};
+export declare const Palbase: PalbaseApp;
 /**
  * The request's database, as v2's: `Database.public.<table>`, `$query`,
  * `$transaction`, `$atomic`, `$asService()`. It is the request's own
@@ -54,3 +90,4 @@ export declare const Log: {
     warn: (message: string, fields?: Record<string, unknown>) => void;
     error: (message: string, fields?: Record<string, unknown>) => void;
 };
+export {};

package/types/internal/src/chat.d.ts

@@ -88,46 +88,14 @@ export interface AgentEvent {
     reason?: string;
     [field: string]: unknown;
 }
-/** The chat's live voice: what was said either way (transcript), when it began and ended, and a task it handed over. */
-export interface VoiceEvent {
-    type: 'voice';
-    seq: number;
-    voice_session_id: string;
-    kind: 'transcript' | 'started' | 'closed' | 'delegated';
-    /** A transcript's: the member speaking (user) or the voice answering (assistant). */
-    role?: 'user' | 'assistant';
-    text?: string;
-    /** A delegated task's: answer it with the voice's speak and this id. */
-    delegation_id?: string;
-    task?: string;
-    reason?: string;
-    seconds?: number;
-    [field: string]: unknown;
-}
-export type ChatEvent = MessageEvent | TurnEvent | TextEvent | ResetEvent | ToolEvent | AgentEvent | VoiceEvent;
-/** Where a reader is: what it hands the stream to go on from there. */
-export interface ChatPosition {
-    /** The id of the last journal event held. */
-    after?: number;
-    /** The response whose answer is being read, and the bytes of it held. */
-    response?: string;
-    offset?: number;
-}
-export interface FollowChatOptions extends ChatPosition {
-    signal?: AbortSignal;
-    /** How long a stream that keeps being cut is followed again before the reader is told (default 2 minutes). */
-    resumeFor?: number;
-    /** A stream with no byte for this long is taken for cut (default 45 s; the module's heartbeat is more often). */
-    idleFor?: number;
-}
-/** The stream's events; its position is where a reader that stops now would go on from. */
-export interface ChatStream extends AsyncIterable<ChatEvent> {
-    readonly position: ChatPosition;
-}
-/** Opens the stream from a point: the generated client's followChat, through the caller's transport. */
-export type OpenChatStream = (query: ChatPosition, signal: AbortSignal) => Promise<globalThis.Response>;
+export type ChatEvent = MessageEvent | TurnEvent | TextEvent | ResetEvent | ToolEvent | AgentEvent;
 /** A chat refusal of the module's, said in words its caller can act on; anything else (or one said already) as it was. */
 export declare function chatRefusal(e: unknown): unknown;
 /** The same promise, its chat refusals said as chatRefusal says them. */
 export declare function told<T>(p: Promise<T>): Promise<T>;
-export declare function followChat(open: OpenChatStream, options?: FollowChatOptions): ChatStream;
+/**
+ * One part of a chat's channel (the payload of its "chat" event) as a chat
+ * event — undefined for one this runtime does not read: a newer module's
+ * part, or one that is not a part at all.
+ */
+export declare function chatPart(payload: unknown): ChatEvent | undefined;

package/types/internal/src/modules/ai.d.ts

@@ -21,10 +21,6 @@ export type AgentDefinition = {
      * The project's machine that defines the agent at each turn.
      */
     backend?: string;
-    /**
-     * The app's users start chats with this named agent themselves (when the project lets them talk to its agents): an agent the server alone uses is not one they reach.
-     */
-    clients?: boolean;
     /**
      * Its instructions.
      */
@@ -68,7 +64,7 @@ export type Chat = {
      */
     created_at: string;
     /**
-     * The user who started it; null: the project's server.
+     * Null: the project's server started it, as it starts every chat (a user's id: a chat a user started before chats were the server's alone).
      */
     created_by: string | null;
     /**
@@ -153,6 +149,28 @@ export type ChatMessage = {
      */
     text: string;
 };
+/**
+ * Where a chat's stream is written.
+ */
+export type ChatPipe = {
+    /**
+     * A channel of the project's realtime (not one of the platform's: roles:, flags:, purchases:, messaging:, debug:, nor phoenix, realtime's heartbeat).
+     */
+    topic: string;
+};
+/**
+ * A chat's pipe.
+ */
+export type ChatPipeResult = {
+    /**
+     * The chat's id.
+     */
+    chat_id: string;
+    /**
+     * The channel its stream is written into.
+     */
+    topic: string;
+};
 /**
  * One repository of a chat's workspace.
  */
@@ -167,11 +185,11 @@ export type ChatRepo = {
     repo: string;
 };
 /**
- * A chat to start.
+ * A chat to start: the project's server's alone.
  */
 export type ChatRequest = {
     /**
-     * The agent it talks to: a named agent of the project's — or, from the server with a definition of the chat's own, its name for it.
+     * The agent it talks to: a named agent of the project's — or, with a definition of the chat's own, the server's name for it.
      */
     agent: string;
     definition?: AgentDefinition;
@@ -185,10 +203,6 @@ export type ChatRequest = {
     metadata?: {
         [key: string]: string;
     };
-    /**
-     * A user who starts a chat is in it as its owner, under this name.
-     */
-    name?: string;
     /**
      * Its title (256 bytes at most).
      */
@@ -229,6 +243,10 @@ export type DecisionRequest = {
      * Yes, or no.
      */
     approve: boolean;
+    /**
+     * The member the project's server acts as: held to that member's rules — their turn (403 not_your_turn) — and the decision is theirs (the server's alone: a user sending it is answered 400; one who is not a member of the chat, 403 not_a_member). Left out, the server acts as itself.
+     */
+    as?: string;
     /**
      * Why (told to the agent; 1024 bytes at most).
      */
@@ -634,7 +652,7 @@ export type MessagePage = {
  */
 export type MessageRequest = {
     /**
-     * The member the server writes as (the server's alone).
+     * The member the server writes as (the server's alone: a user sending it is answered 400; one who is not a member of the chat, 403 not_a_member): the message is theirs, and counts toward their messages a minute (429 too_many_messages, as theirs would).
      */
     as?: string;
     budget?: TurnBudget;
@@ -928,6 +946,10 @@ export type RunMessageAccepted = {
  * A message for a subagent at work.
  */
 export type RunMessageRequest = {
+    /**
+     * The member the project's server acts as: held to that member's rules — their messages a minute (429 too_many_messages) — and the message is theirs (the server's alone: a user sending it is answered 400; one who is not a member of the chat, 403 not_a_member). Left out, the server acts as itself.
+     */
+    as?: string;
     /**
      * The writer's id for it.
      */
@@ -942,7 +964,7 @@ export type RunMessageRequest = {
  */
 export type Settings = {
     /**
-     * Whether the app's users talk to the project's agents with their own session: start a chat with a named agent, write to the chats they are in.
+     * Whether the app's users talk to the project's agents with their own session: read and write to the chats they are in (the project's server starts them).
      */
     clients: boolean;
     /**
@@ -1051,6 +1073,10 @@ export type ToolContent = {
  * What an app's tool returned (1 MiB of text and 4 images at most).
  */
 export type ToolOutput = {
+    /**
+     * The member the project's server acts as: held to that member's rules — their turn (403 not_your_turn) (the server's alone: a user sending it is answered 400; one who is not a member of the chat, 403 not_a_member). Left out, the server acts as itself.
+     */
+    as?: string;
     /**
      * The tool failed; the output says why.
      */
@@ -1322,7 +1348,7 @@ export declare function client(t: Transport): {
     /**
      * Name an agent
      *
-     * An agent a chat started from the app — or by name from the server — talks to: its definition, or the backend machine that defines it at each turn.
+     * An agent a chat the server starts by its name talks to: its definition, or the backend machine that defines it at each turn.
      */
     putAgent(input: {
         path: {
@@ -1356,7 +1382,7 @@ export declare function client(t: Transport): {
     /**
      * Start a chat
      *
-     * The server starts a chat with a named agent or a definition of its own, and names its members; a signed-in user (when the project lets them) starts one with a named agent, as its owner.
+     * The project's server's alone: its backend, with the secret key, starts a chat with a named agent or a definition of its own, and names its members. A signed-in user is answered 403 server_only, whatever the project lets them (settings.clients is what they do in the chats they are in).
      */
     createChat(input: {
         body: ChatRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
@@ -1387,7 +1413,7 @@ export declare function client(t: Transport): {
     /**
      * Decide a tool call
      *
-     * A tool call that waits for a person's yes: approved it is made; denied, the agent is told, with the reason, and goes on.
+     * A tool call that waits for a person's yes: approved it is made; denied, the agent is told, with the reason, and goes on. Decided by the member whose message began the turn (403 not_your_turn for any other) — or by the project's server, for any turn, or as that member (as).
      */
     decideChatApproval(input: {
         path: {
@@ -1440,7 +1466,7 @@ export declare function client(t: Transport): {
     /**
      * Write to a chat
      *
-     * A message for the agent: a turn of its own when none runs; while one does, at its next step (next) or cutting the step it is in (now). The same client_id again is the same message. A user sends user_messages_per_minute a minute (429 too_many_messages); past the history the project keeps a message is refused (409 history_full).
+     * A message for the agent: a turn of its own when none runs; while one does, at its next step (next) or cutting the step it is in (now). The same client_id again is the same message. A user sends user_messages_per_minute a minute — and so does the server writing as them (429 too_many_messages); past the history the project keeps a message is refused (409 history_full).
      */
     sendChatMessage(input: {
         path: {
@@ -1449,10 +1475,33 @@ export declare function client(t: Transport): {
         body: MessageRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, ChatMessage> | Reply<202, ChatMessage>>;
+    /**
+     * Pipe the chat into a channel
+     *
+     * Writes the chat's stream into a channel of the project's realtime from now on — a gateway's, durable — as the platform: the members' messages, the turns, the answer as it is written (gathered into a few writes a second), the tools and subagents, each the channel's event `chat` {type, id?, data}, under an id of its own so a retry is kept once. The types: `message` (a ChatMessage, as the agent got it), `turn` ({response_id, status: running|waiting|completed|failed|canceled|timed_out|budget_exceeded, user_id, solo, waiting: {reason: approval|tool_output|subagents|message, text_offset, approval_id, tool_call_id, tool_name, input}, error}), `text` ({response_id, offset, text}: the agent's answer as it is written, at its byte offset), `reset` ({response_id, offset}: discard the answer past offset), `tool` ({response_id, run_id, call_id, name, status: running|awaiting_output|awaiting_approval|approved|denied|expired|completed|failed|canceled, text_offset, input, output, image_count, is_error, approval_id, agent_response_id, …}), `agent` ({run_id, response_id, parent_response_id, name, required, status, text_offset}: a subagent at work), `voice` ({voice_session_id, kind: transcript|started|closed|delegated, role: user|assistant, text, delegation_id, task}: the chat's live voice — what was said either way), and `seen` (the journal moved past what was handed already). Every type but text and reset has the journal's sequence as its id; text_offset says where in the answer a tool or subagent part happened. The project's backend is not in the stream: the gateway's members hear the chat from realtime, and one that was away is given what it missed there. Put again with the same channel it goes on where it is — one realtime refused is tried again; with another, from the chat's start, and nothing more is written into the one before. The project's server's alone.
+     */
+    putChatPipe(input: {
+        path: {
+            chat_id: string;
+        };
+        body: ChatPipe; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, ChatPipeResult>>;
+    /**
+     * Take the chat's pipe away
+     *
+     * The chat's stream is written nowhere from now on. The project's server's alone.
+     */
+    deleteChatPipe(input: {
+        path: {
+            chat_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
     /**
      * Write to a subagent at work
      *
-     * A message for one of the agent's subagents, at its next step.
+     * A message for one of the agent's subagents, at its next step: a message of the chat like any other — its writer's (or the member's the server writes as) messages a minute (429 too_many_messages), the history the project keeps (409 history_full).
      */
     sendSubagentMessage(input: {
         path: {
@@ -1473,26 +1522,10 @@ export declare function client(t: Transport): {
         }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, StopResult>>;
-    /**
-     * Follow a chat
-     *
-     * What happens in the chat as typed parts, as it happens.
-     */
-    followChat(input: {
-        path: {
-            chat_id: string;
-        };
-        query?: {
-            after?: number; /** The response whose answer the reader was reading. */
-            response?: string; /** The bytes of that answer the reader holds. */
-            offset?: number;
-        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
-        signal?: AbortSignal;
-    }): Promise<Reply<200, Response>>;
     /**
      * Answer an app's tool call
      *
-     * The answer of a client tool's call, made by the app's code: the turn waiting for it goes on. The first answer is the one.
+     * The answer of a client tool's call, made by the app's code: the turn waiting for it goes on. The first answer is the one. Given by the app of the member whose message began the turn (403 not_your_turn for any other) — or by the project's server, for any turn, or as that member (as).
      */
     answerChatToolCall(input: {
         path: {

package/types/internal/src/modules/realtime.d.ts

@@ -56,6 +56,14 @@ export type ChannelRule = {
      * A public channel's subscribers may write its state.
      */
     state_write?: boolean;
+    /**
+     * The channel keeps its broadcasts, numbered, and a member that was away is given what it missed, in order and once, when it rejoins after the number it had (phx_join config.log.after; the join's reply says the number it starts after, log_seq). A broadcast's number (seq) is its channel's own — the time it was written, in microseconds, rising in the channel — and says nothing of other channels. Kept a day unless log_keep_seconds says how long. What a project's durable channels write is held to a budget an hour, each message weighed by the hours it is kept: past it a durable broadcast is refused (log_budget) until the next hour.
+     */
+    durable?: boolean;
+    /**
+     * How long a durable channel keeps its broadcasts, in seconds: 1 to 604800 (a week). Naming it makes the channel durable.
+     */
+    log_keep_seconds?: number;
 };
 export type ChannelSubscribers = {
     /**
@@ -255,7 +263,7 @@ export declare function client(t: Transport): {
     /**
      * Broadcast as the server
      *
-     * Publishes events on the project's channels, to every subscriber on every replica, as the project's server (1 to 100 events). Delivered at most once, like every broadcast.
+     * Publishes events on the project's channels, to every subscriber on every replica, as the project's server (1 to 100 events). Delivered at most once, like every broadcast — but on a durable channel, kept and given to its members in order and once. A durable channel's event past the project's hourly budget is refused with 429 log_budget and when to try again (Retry-After); the events before it were published.
      */
     broadcast(input: {
         body: BroadcastBatch; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */

package/types/web/src/backends.d.ts

@@ -1,6 +1,6 @@
 import type { Transport } from '../../internal/src/transport.js';
 import { BackendError } from './backend-error.js';
-import { type RoomDescriptor, type RoomEvent, type RoomHandle } from './rooms.js';
+import { type GatewayDescriptor, type GatewayEvent, type JoinedGateway, type JoinOptions } from './gateways.js';
 import type { RealtimeSocket } from './socket.js';
 export interface CallOptions {
     headers?: Record<string, string>;
@@ -59,22 +59,29 @@ export interface BackendBase {
      */
     call<O = unknown>(name: string, input?: unknown, options?: CallOptions): Promise<O>;
     /**
-     * Joins a room the backend declared with `@Room` — `room` is the generated
-     * module's, `params` its pattern's `{param}` values: resolves once the
-     * backend let the user in, with the handle its events arrive on and its
-     * messages go through; rejects with a RoomError (its reason) when it did not.
+     * Joins a gateway the backend declared with `@Gateway` — `gateway` is the
+     * generated module's, `params` its pattern's `{param}` values: resolves once
+     * the backend let the user in, with the handle its events arrive on and its
+     * messages go through (each answered with its ack); rejects with a
+     * GatewayError (its reason) when it did not. A durable gateway's handle is
+     * sent what it keeps first, unless `{ history: false }`; a chat gateway's
+     * holds the chat its server piped there (`handle.chat`).
      *
-     *     const room = await pb.api.join(AiSessionIdRoom, { sessionId });
-     *     room.on('token', (t) => transcript.push(t.text));
-     *     await room.send('say', { text: 'hello' });
-     *     room.leave();
+     *     const chat = await pb.api.join(ChatGateway, { chatId });
+     *     chat.chat.subscribe((s) => render(s.items));
+     *     const { id } = await chat.send('say', { text: 'hello' });
+     *     chat.leave();
      */
-    join<E extends RoomEvent, S, P extends readonly string[]>(room: RoomDescriptor<E, S, P>, params: Record<P[number], string>): Promise<RoomHandle<E, S>>;
+    join<E extends GatewayEvent, S, R, P extends readonly string[], C extends boolean = false>(gateway: GatewayDescriptor<E, S, R, P, C>, params: Record<P[number], string>, options?: JoinOptions): Promise<JoinedGateway<E, S, R, C>>;
 }
 /** What every client createClient makes inherits: one getter per registered backend name. */
 export declare const clientBase: object;
-/** Gives a client made by createClient its project's origin, its way to the machines, its project's transport (an upload's way, through storage) and its socket (a room's). */
-export declare function bindMachines(client: object, project: string, machine: (url: string) => Transport, storage: Transport, socket: RealtimeSocket): void;
+/**
+ * Gives a client made by createClient its project's origin, its way to the
+ * machines, its project's transport (an upload's way, through storage), its
+ * socket (a gateway's) and its signed-in user (a chat gateway's own turns).
+ */
+export declare function bindMachines(client: object, project: string, machine: (url: string) => Transport, storage: Transport, socket: RealtimeSocket, me?: () => string | undefined): void;
 /**
  * Registers a backend under `client` for the clients of `project` (the
  * address createClient is given) — the machine `machine`, at `url` — called

package/types/web/src/chat.d.ts

@@ -0,0 +1,118 @@
+import { type AgentEvent, type ChatEvent, type ToolEvent, type TurnEvent } from '../../internal/src/chat.js';
+export type { AgentEvent, ChatEvent, ToolEvent, TurnEvent } from '../../internal/src/chat.js';
+/** A member's (or the server's) message, as the agent got it. */
+export interface ChatMessageView {
+    /** The writer's id for it: the same id is the same message. */
+    clientId: string;
+    id: string | null;
+    text: string;
+    /** The member who wrote it; null: the project's server. */
+    author: string | null;
+    authorName: string;
+    delivery: string;
+    /** pending until the agent has it, delivered once it does, failed when it could not be given. */
+    status: 'pending' | 'delivered' | 'failed';
+    /** Why it failed: the module's code. */
+    error: string | null;
+    /** The turn it started or reached. */
+    responseId: string | null;
+    createdAt: string;
+    /** The signed-in user wrote it. */
+    mine: boolean;
+}
+/** A piece of an answer, in order: its text, split where a tool was called or a subagent handed work. */
+export type ChatPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool';
+    tool: ToolEvent;
+} | {
+    type: 'agent';
+    agent: AgentEvent;
+};
+/** One answer of the agent's (or of one of its subagents). */
+export interface ChatResponse {
+    id: string;
+    status: TurnEvent['status'] | null;
+    waiting: TurnEvent['waiting'];
+    error: TurnEvent['error'];
+    /** The whole answer so far. */
+    text: string;
+    parts: ChatPart[];
+    /** A subagent's: its run, its name, and the response that handed it the work. */
+    runId: string | null;
+    agent: string | null;
+    parentId: string | null;
+    /** The member whose turn it is (a subagent's: its turn's); null: the project's server's, or the engine's. */
+    startedBy: string | null;
+    /** The signed-in user's own turn. */
+    mine: boolean;
+}
+export type ChatItem = {
+    type: 'message';
+    message: ChatMessageView;
+} | {
+    type: 'response';
+    response: ChatResponse;
+};
+export interface ChatState {
+    /** The conversation in order: the members' messages and the agent's answers (a subagent's is in its parent's parts). */
+    items: ChatItem[];
+    messages: ChatMessageView[];
+    /** Every answer, the subagents' too, as they began. */
+    responses: ChatResponse[];
+    /** The last turn's state. */
+    turn: TurnEvent | null;
+    /**
+     * What waits for the signed-in user: the tool calls of their own turns
+     * waiting for their yes, and the client tool calls of their own turns
+     * waiting for their app's answer — each said back through the gateway's
+     * own messages, its backend deciding. Another member's turn is theirs.
+     */
+    waiting: {
+        approvals: ToolEvent[];
+        outputs: ToolEvent[];
+    };
+}
+/** A gateway's chat: its state now, and told each time it changes. */
+export interface GatewayChat extends AsyncIterable<ChatState> {
+    /** The chat as the channel holds it now: the same object until it changes. */
+    readonly state: ChatState;
+    /** Told each time the state changes (at most once a microtask); returns the unsubscribe. */
+    subscribe(listener: (state: ChatState) => void): () => void;
+}
+/**
+ * A chat folded from its channel's parts. It holds no connection: a part is
+ * handed to take() as the channel gives it — once, in order — and the state
+ * is built from them; me is the signed-in user, read as the state is built.
+ */
+export declare class ChatLog implements GatewayChat {
+    private readonly me;
+    private readonly messages;
+    private readonly responses;
+    private readonly order;
+    private turn;
+    private readonly calls;
+    private readonly listeners;
+    /** The iterations waiting for a change: woken when the gateway is left. */
+    private readonly enders;
+    private snapshot;
+    private told;
+    private ended;
+    constructor(me?: () => string | undefined);
+    get state(): ChatState;
+    subscribe(listener: (state: ChatState) => void): () => void;
+    /** The state now, then each time it changes, until the gateway is left. */
+    [Symbol.asyncIterator](): AsyncGenerator<ChatState, void, undefined>;
+    /** The gateway was left: an iteration ends, and no part is taken any more. */
+    end(): void;
+    /** One payload of the channel's "chat" event; one that is no part this runtime reads is let be. */
+    takePayload(payload: unknown): void;
+    take(e: ChatEvent): void;
+    private heard;
+    private place;
+    private response;
+    private changed;
+    private build;
+}

package/types/web/src/client.d.ts

@@ -5,7 +5,6 @@ import { type RefreshMode, type SessionStore } from './session.js';
 import { RealtimeSocket } from './socket.js';
 import { Analytics, type AnalyticsOptions } from './analytics.js';
 import { Purchases } from './purchases.js';
-import { AI } from './ai.js';
 export interface ClientOptions {
     /** The project's address: https://<ref>.<domain> */
     url: string;
@@ -63,7 +62,5 @@ export interface PalbaseClient {
     analytics: Analytics;
     /** What the signed-in customer has (live, onCustomerInfo), the paywall's catalog, and buying on the web. */
     purchases: Purchases;
-    /** The project's agents, for the signed-in user (when the project lets its users talk to them): their chats, followed as typed parts. */
-    ai: AI;
 }
 export declare function createClient(opts: ClientOptions): PalbaseClient;

package/types/web/src/gateways.d.ts

@@ -0,0 +1,89 @@
+import { type GatewayChat } from './chat.js';
+import type { RealtimeSocket } from './socket.js';
+/** One event of a gateway, as a generated module's union has it. */
+export type GatewayEvent = {
+    event: string;
+    payload: unknown;
+};
+/**
+ * A gateway, as the generator writes one. `send`, `reply` and `event` carry
+ * types alone — their values are never read: `gateway.send('say', { … })` is
+ * checked against the message's shape and resolves with its ack's, and a
+ * handler's event against the gateway's events.
+ */
+export interface GatewayDescriptor<E extends GatewayEvent, S, R = Record<keyof S, unknown>, P extends readonly string[] = readonly string[], C extends boolean = false> {
+    /** The backend's class: `ChatGateway`. */
+    name?: string;
+    /** The channel pattern the backend declared: `chat:{chatId}`. */
+    pattern: string;
+    /** It keeps what it sends: a join is sent what it keeps, and a dropped socket misses nothing. */
+    durable?: boolean;
+    /** Its server pipes a chat into it: the handle holds the chat's state (`handle.chat`). */
+    chat?: C;
+    /** The `{param}` names, in the pattern's order: a join takes exactly these. */
+    params: P;
+    /** The declared event names: what a handle listens to. */
+    events: readonly string[];
+    /** The declared message names: what a handle sends. */
+    messages: readonly string[];
+    send: S;
+    reply?: R;
+    event: E;
+}
+/** How a gateway is joined. */
+export interface JoinOptions {
+    /** A durable gateway's: sent what it keeps first (true, the default), or only what comes after the join (false). */
+    history?: boolean;
+}
+/** What `on` returns: called, it stops that callback (`off` does the same). */
+export type GatewaySubscription = () => void;
+/** A live gateway. Hold it for as long as the view is on screen, and `leave` it when the view goes: an occupied gateway is one its backend is still running for. */
+export interface GatewayHandle<E extends GatewayEvent, S, R = Record<keyof S, unknown>> {
+    /** The channel this handle is on: `chat:42`. */
+    readonly topic: string;
+    /** A durable gateway's number of the last event the handle was sent: what a dropped socket joins again after. */
+    readonly seq: number | undefined;
+    /** Every event the gateway declares, as a union to switch over. */
+    on(handler: (event: E) => void): GatewaySubscription;
+    /** One event by its name, its payload typed. */
+    on<K extends E['event']>(event: K, handler: (payload: Extract<E, {
+        event: K;
+    }>['payload']) => void): GatewaySubscription;
+    /** Stops one callback. */
+    off(subscription: GatewaySubscription): void;
+    /**
+     * Sends one declared message and waits for the gateway's backend to take
+     * it: resolves with its ack (what its @Subscribe returned), rejects with a
+     * GatewayError — its reason — when it did not.
+     */
+    send<K extends keyof S & string>(message: K, payload: S[K]): Promise<K extends keyof R ? R[K] : unknown>;
+    /** Drops every callback of this handle and lets go of the gateway; the channel is left with its last handle. */
+    leave(): void;
+}
+/** A chat gateway's handle: the chat its server piped into the channel, as its state. */
+export interface ChatGatewayHandle<E extends GatewayEvent, S, R = Record<keyof S, unknown>> extends GatewayHandle<E, S, R> {
+    /** The chat from its start (the channel keeps it), and each change as the platform writes it. */
+    readonly chat: GatewayChat;
+}
+/** What a join resolves with: a chat gateway's handle holds its chat. */
+export type JoinedGateway<E extends GatewayEvent, S, R, C> = [C] extends [true] ? ChatGatewayHandle<E, S, R> : GatewayHandle<E, S, R>;
+/**
+ * Why a gateway did not do what was asked. `reason` is the server's: for a join,
+ * `unauthorized` (the backend did not let the user in) or `unavailable` (it
+ * could not be asked: try again); for a message, the reason the backend gave,
+ * `forbidden` when it gave none or the user may only listen, `rate_limited`,
+ * `unavailable`. When no answer came it is `no reply` or `socket closed` —
+ * the message may have been taken — and `not joined` when nothing was sent:
+ * the handle left, its socket closed (a sign-out, another user's sign-in), or
+ * the socket dropped and is being opened again.
+ */
+export declare class GatewayError extends Error {
+    readonly reason: string;
+    constructor(message: string, reason: string);
+}
+/**
+ * Joins `gateway` on `socket`: resolves once the backend let the user in,
+ * rejects with a GatewayError when it did not. me is the signed-in user: a
+ * chat's turns and messages that are theirs.
+ */
+export declare function joinGateway<E extends GatewayEvent, S, R, P extends readonly string[], C extends boolean = false>(socket: RealtimeSocket, gateway: GatewayDescriptor<E, S, R, P, C>, params: Record<P[number], string>, options?: JoinOptions, me?: () => string | undefined): Promise<JoinedGateway<E, S, R, C>>;

package/types/web/src/index.d.ts

@@ -1,9 +1,9 @@
 export { createClient, type ClientOptions, type PalbaseClient } from './client.js';
 export type { Auth, CredentialsLike, SignInResult, User } from './auth.js';
 export { localStore, memoryStore, SessionChangedError, type AuthEvent, type RefreshMode, type Session, type SessionStore } from './session.js';
-export { Channel, RealtimeSocket, type PushReply } from './socket.js';
+export { Channel, RealtimeSocket, type ChannelOptions, type PushReply } from './socket.js';
 export { Analytics, type AnalyticsOptions } from './analytics.js';
-export { AI, ChatSession, type AgentEvent, type Chat, type ChatEvent, type ChatItem, type ChatMessageView, type ChatOptions, type ChatPart, type ChatResponse, type ChatState, type ChatVoice, type ClientToolHandlers, type ToolEvent, type ToolResult, type TurnEvent, type VoiceEvent, } from './ai.js';
+export type { AgentEvent, ChatEvent, ChatItem, ChatMessageView, ChatPart, ChatResponse, ChatState, GatewayChat, ToolEvent, TurnEvent } from './chat.js';
 export { Purchases, type CustomerInfo, type CustomerInfoListener, type MergeGrant, type Offerings } from './purchases.js';
 export type { Paywall, PaywallRenderOptions } from './paywall/placement.js';
 export type { PaywallAttribute } from './paywall/attributes.js';
@@ -11,5 +11,5 @@ export type { PaywallPackage, PaywallView } from './paywall/render.js';
 export { PalbaseError } from '../../internal/src/transport.js';
 export { BackendError, isBackendError, type BackendErrorKind, type FieldError } from './backend-error.js';
 export type { BackendBase, CallOptions, UploadOptions, UploadProgress } from './backends.js';
-export { RoomError, type RoomDescriptor, type RoomEvent, type RoomHandle, type RoomSubscription } from './rooms.js';
+export { GatewayError, type ChatGatewayHandle, type GatewayDescriptor, type GatewayEvent, type GatewayHandle, type GatewaySubscription, type JoinedGateway, type JoinOptions } from './gateways.js';
 export type { RetryPolicy } from '../../internal/src/retry.js';