palbase 0.5.2 → 0.7.0

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

@@ -0,0 +1,250 @@
+import type { realtime } from '../../internal/src/modules/index.js';
+import { type StandardSchemaV1 } from './decorators.js';
+import { type SignedUser } from './platform-calls.js';
+export declare const GATEWAY: unique symbol;
+export declare const GATEWAY_HOOKS: unique symbol;
+/** The moments a gateway's methods are told of. */
+export type GatewayHook = 'authorize' | 'first' | 'connect' | 'disconnect' | 'empty';
+export interface GatewayOptions {
+    /**
+     * Who may join, decided by realtime: 'owner' — the pattern's one {param}
+     * is the joining user's id; 'public' — any signed-in user. Left out, an
+     * @Authorize method decides.
+     */
+    access?: 'owner' | 'public';
+    /**
+     * Members broadcast to each other, as realtime carries it — a gateway of
+     * no method only: one with methods takes its members' messages itself
+     * (@Subscribe).
+     */
+    publish?: boolean;
+    /**
+     * Keeps what it sends: true a day, or { keepSeconds } (1 to 604800). A
+     * member that was away is sent what it missed, in order, once — a chat's
+     * stream that a phone walking out of range does not lose.
+     */
+    durable?: boolean | {
+        keepSeconds: number;
+    };
+    /**
+     * How long it is held after its last member left before it is empty
+     * (@OnEmpty), in milliseconds: 60000 unless said.
+     */
+    graceMs?: number;
+    /**
+     * It carries a chat of the project's agents (ctx.pipe(Palbase.ai.chats.events(id))):
+     * its event `chat` is the platform's — the chat's parts — and every
+     * generated client holds the chat's state for its view (messages, the
+     * answer as it is written, tools, approvals). Kept a day unless durable
+     * says how long: a member that comes later, or was away, has the chat.
+     */
+    chat?: boolean;
+}
+/**
+ * Something the platform writes into a gateway's channel itself, the backend
+ * not in it: a chat's stream (Palbase.ai.chats.events(id)).
+ */
+export interface PipeSource {
+    pipe(topic: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/** The platform's event of a chat-carrying gateway: one part of the chat (its type, the journal's number, its data). */
+export declare const ChatPart: StandardSchemaV1<{
+    type: string;
+    id?: number;
+    data: Record<string, unknown>;
+}>;
+/**
+ * Thrown by a @Subscribe: the member's message is refused, with this reason —
+ * the client's GatewayError.reason, a word the app chose for its own app to
+ * act on ('not_your_turn', 'too_many_messages'). What the method wrote is
+ * rolled back. Anything else a method throws is the app's log's: its words
+ * could carry anything, and the member is told handler_failed.
+ */
+export declare class GatewayRefusal extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** What a gateway class declares its events with: `static readonly events = { name: schema }`. */
+export interface GatewayEvents {
+    readonly events?: Readonly<Record<string, StandardSchemaV1>>;
+}
+/** A gateway as its decorators declare it. */
+export interface GatewayDeclaration {
+    /** The class's name: its client's, in every generated client. */
+    name: string;
+    pattern: string;
+    access?: 'owner' | 'public';
+    publish: boolean;
+    /** How long it keeps what it sends, in seconds: 0 keeps nothing. */
+    logKeepSeconds: number;
+    /** It carries a chat (GatewayOptions.chat): its event `chat` is the chat's parts. */
+    chat: boolean;
+    events: Record<string, StandardSchemaV1>;
+    graceMs: number;
+    /** Each moment, the method told of it. */
+    hooks: Partial<Record<GatewayHook, string>>;
+    /** Each message a member may send: its method, its payload's schema, and its ack's when said — an object of no prototype, whatever the names. */
+    messages: Record<string, {
+        fn: string;
+        schema: StandardSchemaV1;
+        reply?: StandardSchemaV1;
+    }>;
+}
+/** Whether the machine serves it — a method of it is told of something — or realtime decides it alone. */
+export declare const servedByTheApp: (g: GatewayDeclaration) => boolean;
+/** Who a member is, to a gateway's methods. */
+export interface GatewayUser {
+    /** The user's id; "" in @OnFirst and @OnEmpty, which no one in particular caused. */
+    id: string;
+}
+/** What @Authorize is given: who asks to join, and the channel's parameters. */
+export interface GatewayAuthorizeContext {
+    user: GatewayUser;
+    params: Readonly<Record<string, string>>;
+}
+/**
+ * What @Authorize answers: true lets the user in to hear and to send; an
+ * object says which — { read: false } is no way in, { write: false } a
+ * listener who may not send; null, undefined or false keep the user out. So
+ * does any other answer, and a method that throws: only a grant lets anyone
+ * in, and the app's log says what was answered instead.
+ */
+export type GatewayGrant = boolean | null | undefined | {
+    read?: boolean;
+    write?: boolean;
+};
+/** What a gateway's moments are given (@OnFirst, @OnConnect, @OnDisconnect, @OnEmpty). */
+export interface GatewayContext {
+    /** The channel: "chat:42". */
+    channel: string;
+    /** The pattern's parameters: { chatId: "42" }. */
+    params: Readonly<Record<string, string>>;
+    /**
+     * The channel's own: aborted when it empties (before @OnEmpty runs), or
+     * when owner.release() gives it up — what @OnFirst started stops on it.
+     */
+    signal: AbortSignal;
+    /** Its members now, across realtime's replicas; 0 in a @Subscribe. */
+    count: number;
+    user: GatewayUser;
+    /**
+     * An event to the channel's members — in @OnConnect, to the member who
+     * joined alone. Sent in the order emitted, and never thrown: what could
+     * not be sent is in the app's log.
+     */
+    emit(event: string, payload?: unknown): void;
+    /**
+     * The platform writes `source` into this channel from now on — a chat's
+     * stream: `ctx.pipe(Palbase.ai.chats.events(chatId))`. The backend is not
+     * in the stream after; the gateway's members hear it.
+     */
+    pipe(source: PipeSource): Promise<void>;
+    owner: {
+        /** Runs `work` past the method, until the channel's signal aborts: an upstream's loop. Its failure is logged, never the app's crash. */
+        hold(work: (signal: AbortSignal) => unknown): void;
+        /** Gives the channel up now: its signal aborts, and the next member to come finds it unheld (@OnFirst again). */
+        release(): void;
+    };
+}
+/** What a @Subscribe is given: the channel's context, the member, and the payload as its schema made it. */
+export interface GatewayMessageContext<P = unknown> extends GatewayContext {
+    payload: P;
+}
+/** v2 held a room a minute after its last member: twice the slowest client's heartbeat, and margin. */
+export declare const DEFAULT_GRACE_MS = 60000;
+/** A durable gateway keeps what it sends a day unless it says; a week at most. */
+export declare const DEFAULT_KEEP_SECONDS = 86400;
+export declare const MAX_KEEP_SECONDS = 604800;
+/** The most a @Subscribe's ack carries (realtime's roomReplyMax). */
+export declare const MAX_REPLY_BYTES: number;
+/**
+ * Why `pattern` is no gateway's, or undefined. A pattern is a channel's: ':'
+ * segments, a "{name}" segment taking exactly one — and realtime takes a
+ * pattern it cannot decide for no channel at all, silently: the gateway
+ * would compile, ship and never be joined. So everything it would not take is
+ * refused here, by name, while someone is looking.
+ */
+export declare function patternProblem(pattern: string): string | undefined;
+/**
+ * A class whose methods manage the channels `pattern` names (see the top of
+ * this file). It is a provider a module lists (its constructor injected as
+ * any provider's), built once: what @OnFirst starts and @OnEmpty stops lives
+ * in it. Its events are its class's `static readonly events`.
+ */
+export declare function Gateway(pattern: string, options?: GatewayOptions): ClassDecorator;
+/** Who may join: answers a GatewayGrant (GatewayAuthorizeContext) — for a gateway with no access of realtime's. */
+export declare const Authorize: () => MethodDecorator;
+/**
+ * The channel is occupied and held by no one: start what it needs. Told once
+ * across realtime's replicas when its first member comes — before that
+ * member is answered — and again only after it emptied.
+ */
+export declare const OnFirst: () => MethodDecorator;
+/** A member joined (after it was answered): what it emits goes to that member alone. */
+export declare const OnConnect: () => MethodDecorator;
+/** A member left. */
+export declare const OnDisconnect: () => MethodDecorator;
+/** Nobody has been on the channel for its graceMs: stop what @OnFirst started. Its signal is aborted already. */
+export declare const OnEmpty: () => MethodDecorator;
+/**
+ * A message a member sends, `name`, its payload checked against `schema`
+ * before the method runs (GatewayMessageContext): a payload that does not
+ * fit never reaches it, and the member hears why. What the method returns
+ * is the member's ack — `reply` its schema in every generated client.
+ */
+export declare function Subscribe(name: string, schema: StandardSchemaV1, options?: {
+    reply?: StandardSchemaV1;
+}): MethodDecorator;
+/** The gateway a class declares, or undefined: a gateway is one by its decorator, never its name. */
+export declare function gatewayOf(cls: Function): GatewayDeclaration | undefined;
+/** A gateway's channel's parameters, or undefined when the channel is not one of its. */
+export declare function matchChannel(pattern: string, channel: string): Record<string, string> | undefined;
+/** The channel of a gateway's parameters: each named by its pattern, a whole segment — or why not. */
+export declare function channelOf(pattern: string, params: Readonly<Record<string, unknown>>): string | {
+    problem: string;
+};
+/** One event to a gateway's members, as realtime's broadcast takes it: its channel (topic), and conn_id for one membership alone. */
+type GatewayBroadcast = realtime.BroadcastMessage;
+export interface GatewayDeps {
+    /**
+     * `work` as the platform's caller names it — in a transaction as `user`,
+     * or as the app itself when the moment is no one's (first, empty) —
+     * committed unless it throws, or the platform hung up before it ended.
+     */
+    run<T>(user: SignedUser | undefined, where: string, signal: AbortSignal | undefined, work: () => Promise<T>): Promise<T>;
+    /** realtime's POST /realtime/broadcast, as the app (its secret key). */
+    broadcast(messages: GatewayBroadcast[]): Promise<unknown>;
+    /** The platform's infrastructure, not the method, failed: the call is answered 503, and realtime asks again. */
+    isOutage(e: unknown): boolean;
+}
+/** What a gateway's call is answered: JSON, nothing (204), or a refusal. */
+export type GatewayAnswer = {
+    status: 200;
+    body: unknown;
+} | {
+    status: 204;
+} | {
+    status: number;
+    code: string;
+    message: string;
+    retryAfter?: number;
+};
+export interface Gateways {
+    readonly declarations: readonly GatewayDeclaration[];
+    /** The platform's call about a gateway — authorize, message or lifecycle — its JSON body. */
+    serve(kind: string, body: unknown, signal?: AbortSignal): Promise<GatewayAnswer>;
+    /** An event to a gateway's channel from anywhere in the app (Palbase.gateways.to). */
+    emit(cls: Function, params: Readonly<Record<string, unknown>>, event: string, payload: unknown): void;
+    /** A source piped into a gateway's channel from anywhere in the app (Palbase.gateways.to(…).pipe). */
+    pipe(cls: Function, params: Readonly<Record<string, unknown>>, source: PipeSource): Promise<void>;
+    /** Every channel let go: what was held is aborted (the app is stopping). */
+    close(): void;
+}
+/** The app's gateways, served: `classes` its providers that are gateways, each with its instance. */
+export declare function createGateways(classes: {
+    cls: Function;
+    instance: object;
+}[], deps: GatewayDeps): Gateways;
+export {};

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

@@ -1,9 +1,9 @@
 import 'reflect-metadata';
 export { Body, Client, Controller, Delete, Get, getRegisteredControllers, getRoutes, Headers, Cron, Injectable, Module, On, OptionalUser, Param, Patch, Post, Put, Query, QueryParams, Req, RequestId, Resolve, TraceId, User, Webhook, type AuthConfig, type AuthSpec, type ControllerOptions, type EventHandler, type CronMeta, type CronOptions, type ModuleDef, type OnOptions, type ParamResolver, type RateLimitConfig, type ResolveContext, type RouteInfo, type RouteOptions, type SignatureSpec, type StandardSchemaV1, type Token, type WebhookOptions, type WebhookProvider, } from './decorators.js';
 export { Task, TaskFailure, Tasks, type EnqueueOptions, type PayloadOf, type QueuedTask, type TaskClass, type TaskMeta, type TaskOptions, type TasksService } from './tasks.js';
-export { defineChannels, ownerOnly, publicChannel, type ChannelAuthorizeCtx, type ChannelEntry, type ChannelGrant, type ChannelsDef, type ChannelsInput } from './channels.js';
 export { Upload, UploadedObject, type UploadConfig } from './upload.js';
-export { OnAuthorize, OnEmpty, OnFirst, OnJoin, OnLeave, OnMessage, Room, type RoomAuthorizeContext, type RoomContext, type RoomGrant, type RoomMessageContext, type RoomOptions, type RoomUser, } from './rooms.js';
+export { Authorize, ChatPart, Gateway, GatewayRefusal, OnConnect, OnDisconnect, OnEmpty, OnFirst, Subscribe, type GatewayAuthorizeContext, type GatewayContext, type GatewayEvents, type GatewayGrant, type GatewayMessageContext, type GatewayOptions, type GatewayUser, type PipeSource, } from './gateways.js';
+export type { GatewaysApi, GatewayTarget } from './runtime.js';
 export { getWebhookManifest, type WebhookEventHandler, type WebhookMeta } from './webhooks.js';
 export { DiError, type DiErrorKind } from './container.js';
 export { BadRequest, Conflict, DeadlockDetected, Forbidden, HttpError, NotFound, PalError, SerializationFailure, TooManyRequests, Unauthorized, UniqueViolation, defineError, type DefinedError, type DefinedErrorWithData, type Envelope, type FieldIssue, } from './errors.js';

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

@@ -1,7 +1,6 @@
 import type { RateLimitConfig, StandardSchemaV1 } from './decorators.js';
 import type { RegisteredError } from './errors.js';
-import type { ChannelRow } from './channels.js';
-import type { RoomDeclaration } from './rooms.js';
+import { type GatewayDeclaration } from './gateways.js';
 import type { Route } from './router.js';
 /** Where the platform delivers the project's events to the app. */
 export declare const PLATFORM_EVENTS_PATH = "/webhooks/palbase";
@@ -33,10 +32,8 @@ export interface ContractOptions {
     routes?: (route: Route) => RouteContract | undefined;
     /** The release's errors by wire code (defineError's registry): what a thrown code is typed as. */
     errors?: ReadonlyMap<string, RegisteredError>;
-    /** The app's @Room classes, as their decorators declare them. */
-    rooms?: readonly RoomDeclaration[];
-    /** The owner and public channels defineChannels declares, in its order: x-palbase-channels, decided by realtime itself. */
-    channels?: readonly ChannelRow[];
+    /** The app's @Gateway classes, as their decorators declare them. */
+    gateways?: readonly GatewayDeclaration[];
 }
 /** What a route answers and throws, as its source declares. */
 export interface RouteContract {

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. */