palbase 0.6.2 → 0.8.0

package/types/ai/src/tools.d.ts

@@ -25,12 +25,58 @@ export interface ChatContext {
     metadata: Record<string, string>;
     /** Ended when the platform stops waiting for the answer. */
     signal: AbortSignal;
+    /**
+     * The app's instance of a provider — a class a module of the app lists in
+     * its providers, built once by its container with its constructor's
+     * dependencies — as a constructor's parameter of that type is given it:
+     * ctx.inject(Orders). The app that serves the call gives it; a class no
+     * module provides is refused, by name.
+     */
+    inject<T extends object>(provider: abstract new (...args: never[]) => T): T;
 }
 export interface ToolContext extends ChatContext {
     /** The call's id: the same call is the same id, whatever copy of the machine it reaches. */
     callId: string;
+    /** The turn the call is made in: its own response's id — a subagent's call's too. */
+    turnId: string;
+    /**
+     * The run that made the call: the agent's own, or a subagent's at work. A
+     * tool that answers later — it asks a person, and gives their answer to
+     * whoever asked — answers that run: chats.sendToSubagent(chatId, runId, …).
+     */
+    runId: string;
+    /** The subagent that made the call, by its name; null: the agent itself. */
+    subagent: string | null;
+}
+/** The message that opened a turn, as the backend that defines its agent is told of it. */
+export interface TurnMessage {
+    id: string;
+    clientId: string;
+    /** The member who wrote it; null: the project's server. */
+    author: string | null;
+    authorName: string;
+    text: string;
+    delivery: 'next' | 'now' | (string & {});
+    /**
+     * Its writer's labels for it (chats.send({ metadata })) — what an app's
+     * choice for the turn rides on: a model, an effort, the files it names. A
+     * member may write them: the caller's word, not an authority.
+     */
+    metadata: Record<string, string>;
+}
+/** What the backend that defines an agent is told of the turn: the chat's context, and what opened the turn. */
+export interface AgentContext extends ChatContext {
+    /** The message that opened the turn; null: a turn of no message (the chat's voice, its goal). */
+    message: TurnMessage | null;
+    /**
+     * The chat's goal the agent is defined for (chats.goal.set): every turn the
+     * goal opens is the agent defined now. Null: a turn of a message.
+     */
+    goal: {
+        objective: string;
+        rubric: string;
+    } | null;
 }
-export type AgentContext = ChatContext;
 export interface BackendToolOptions<S extends StandardSchema> {
     /** What the agent calls it by: letters, digits, _ and -, starting with a letter, at most 64. */
     name: string;
@@ -43,9 +89,11 @@ export interface BackendToolOptions<S extends StandardSchema> {
      * (`{ mediaType, bytes }`), or a list of them — 4 MiB at most in all. A
      * throw is the tool's failure: a ToolError's message (or the framework's
      * own refusals', NotFound('…')) is told to the agent, anything else as
-     * "The tool failed".
+     * "The tool failed". A tool answers within 110 seconds; one whose work
+     * takes longer returns ai.deferred() at once — a chat's call waits, and the
+     * project's server answers it later with chats.answer(ctx.chatId, ctx.callId, output).
      */
-    run(input: Infer<S>, ctx: ToolContext): ToolResult | Promise<ToolResult>;
+    run(input: Infer<S>, ctx: ToolContext): ToolResult | DeferredAnswer | Promise<ToolResult | DeferredAnswer>;
     /** Every call waits for a person's yes (a member of the chat, or the server). */
     approval?: boolean;
     /** The project's machine it runs on (default backend). */
@@ -60,12 +108,34 @@ export interface BackendTool<S extends StandardSchema = StandardSchema> {
     readonly parameters: Record<string, unknown>;
     readonly approval: boolean;
     readonly machine?: string;
-    /** The run, its input checked first: what the framework answers the platform's call with. */
-    call(input: unknown, ctx: ToolContext): Promise<{
-        output: ToolContent[];
-        is_error: boolean;
-    }>;
+    /** The run, its input checked first: what the framework answers the platform's call with — an answer, or one to come (deferred). */
+    call(input: unknown, ctx: ToolContext): Promise<ToolAnswer>;
 }
+/** A backend tool's answer as the platform takes it: now (output), or later — the project's server gives it (chats.answer). */
+export type ToolAnswer = {
+    output: ToolContent[];
+    is_error: boolean;
+} | {
+    deferred: true;
+    expires_in_seconds?: number;
+};
+declare const DEFERRED: unique symbol;
+/** What a backend tool's run returns when its answer comes later: ai.deferred(). */
+export interface DeferredAnswer {
+    readonly [DEFERRED]: true;
+    /** How long the call waits for its answer: a minute to a day; left out, an hour. */
+    readonly expiresInSeconds?: number;
+}
+/**
+ * The answer comes later: a chat's call waits for it — the turn too, as for
+ * an app's tool — and the project's server gives it with chats.answer(chatId,
+ * callId, output) within expiresInSeconds (a minute to a day; an hour). A
+ * call nobody answers by then is told to the agent as unanswered; no member
+ * answers it. A one-shot answer (ai.ask with tools) waits for no call.
+ */
+export declare function deferred(options?: {
+    expiresInSeconds?: number;
+}): DeferredAnswer;
 export interface ClientToolOptions<S extends StandardSchema> {
     name: string;
     description: string;
@@ -73,7 +143,7 @@ export interface ClientToolOptions<S extends StandardSchema> {
     input?: S;
     approval?: boolean;
 }
-/** A tool the app's code answers (pb.ai.chat(id).tools({ name: fn })): the turn waits for its answer. */
+/** A tool the app answers — through its gateway, whose backend gives the answer (chats.answer): the turn waits for it. */
 export interface ClientTool {
     readonly source: 'client';
     readonly name: string;
@@ -94,7 +164,23 @@ export interface McpToolRef {
     only?: string[];
     approval?: boolean;
 }
-export type Tool = BackendTool<StandardSchema> | ClientTool | HttpsToolRef | McpToolRef;
+/** One of the platform's own tools, by name. */
+export type PlatformToolName = 'web.search' | 'web.fetch' | 'workspace.fetch_archive';
+/**
+ * One of the platform's own tools: web.search (the web searched), web.fetch
+ * (a page of it read), workspace.fetch_archive (an archive at a URL unpacked
+ * into the chat's workspace — a workspace's chat has it already). The
+ * agent's alone: its subagents work with the agent's; a one-shot answer has none.
+ */
+export interface PlatformToolRef {
+    source: 'platform';
+    name: PlatformToolName;
+}
+export type Tool = BackendTool<StandardSchema> | ClientTool | HttpsToolRef | McpToolRef | PlatformToolRef;
+/** How hard a model thinks; which rungs a model takes is its catalogue entry's (ai.models(): chat[].efforts). */
+export type Effort = NonNullable<AgentDefinition['effort']>;
+/** Whether a model's reasoning is shown in the chat's stream (thinking parts) or not asked for at all. */
+export type Thinking = NonNullable<AgentDefinition['thinking']>;
 export interface SubagentDefinition {
     /** Unique among the agent's subagents. */
     name: string;
@@ -105,6 +191,12 @@ export interface SubagentDefinition {
     tools?: Tool[];
     /** The turn fails if this subagent's part fails. */
     required?: boolean;
+    /** Left out: the agent's, when it runs on the agent's model (another model's rungs mean other things). */
+    effort?: Effort;
+    /** The window, in tokens, it works in. Left out: the agent's, when it runs on the agent's model. */
+    contextWindow?: number;
+    /** Left out: the agent's. Its reasoning is never in the chat's stream: only the turn's own is. */
+    thinking?: Thinking;
 }
 /** What an agent is for a turn. */
 export interface AgentDefinitionInput {
@@ -114,27 +206,55 @@ export interface AgentDefinitionInput {
     tools?: Tool[];
     /** 16 at most. */
     subagents?: SubagentDefinition[];
-    /** How many tool calls a turn makes at most (1–200): past it the agent is told it has no tools left and answers. */
+    /**
+     * How many tool calls a turn makes at most (1–10 000, the engine's own bound): past it the agent is told it has no
+     * tools left and answers. What a turn spends is its budget's to bound (chats.send({ budget })), not this.
+     */
     maxToolCalls?: number;
-    /** A named agent's: the app's users start chats with it themselves (when the project lets them). Left out, the server's alone. */
-    clients?: boolean;
+    /** How hard the model thinks (none … max). Left out: the platform's. */
+    effort?: Effort;
+    /**
+     * The window, in tokens, the turn works in: the model's standard one unless said; more is billed as its provider
+     * bills it (ai.models(): chat[].context_window and max_input_tokens).
+     */
+    contextWindow?: number;
+    /** visible: the model's reasoning is in the chat's stream, as thinking parts (the turn's own); hidden: not asked for. Left out: the platform's. */
+    thinking?: Thinking;
+    /** The language of the person the turn works for, a BCP 47 tag (tr, en-GB): the model writes to them in it on every step, and so do its subagents. */
+    language?: string;
 }
-/** What a backend's agent is for one turn: whether users reach it is the named agent's, said when it is put. */
-export type TurnDefinition = Omit<AgentDefinitionInput, 'clients'>;
+/** What a backend's agent is for one turn. */
+export type TurnDefinition = AgentDefinitionInput;
 /** An agent the backend defines at each turn's start: put with ai.agents.put(agent), its chats' turns ask its machine. */
 export interface BackendAgent {
     readonly kind: 'agent';
     readonly name: string;
     /** The project's machine that defines it (default backend). */
     readonly machine?: string;
-    /** The app's users start chats with it themselves (put with it). */
-    readonly clients: boolean;
     /** The definition for a turn, said as the platform takes it, with the backend tools it hands out. */
     resolve(ctx: AgentContext): Promise<{
         definition: AgentDefinition;
         tools: BackendTool[];
     }>;
 }
+/** What one clone or one push of a chat's workspace asks a repository's token with: an ai.repo's token, ai.repoTokens' give. */
+export interface RepoTokenContext {
+    /** The repository's name in the project (ai.repos.put). */
+    repo: string;
+    /** The GitHub repository, owner/name. */
+    repository: string;
+    /** Ended when the platform stops waiting for the token. */
+    signal: AbortSignal;
+    /**
+     * The app's instance of a provider, as a tool's run is given it
+     * (ChatContext.inject): a token a service of the app's mints — its GitHub
+     * App's, its sealed credentials' — from the container of the app that
+     * serves the ask. A class no module provides is refused, by name.
+     */
+    inject<T extends object>(provider: abstract new (...args: never[]) => T): T;
+}
+/** What gives a repository's token when no ai.repo of its name was made: ai.repoTokens(give). */
+export type RepoTokens = (ctx: RepoTokenContext) => string | null | undefined | Promise<string | null | undefined>;
 /** A repository a chat's workspace works in, whose tokens the backend gives (ai.repo). */
 export interface BackendRepo {
     readonly kind: 'repo';
@@ -145,18 +265,16 @@ export interface BackendRepo {
     /** The project's machine that gives its tokens (default backend). */
     readonly machine?: string;
     /** A token for one clone or one push of it: asked at each — a GitHub App's installation token, minted then. */
-    token(ctx: {
-        repo: string;
-        repository: string;
-        signal: AbortSignal;
-    }): Promise<string>;
+    token(ctx: RepoTokenContext): Promise<string>;
 }
 /** What this process declared, for the framework to serve. */
 export interface DeclaredAI {
     tools: Map<string, BackendTool>;
     agents: Map<string, BackendAgent>;
     repos: Map<string, BackendRepo>;
-    /** Names declared twice (tool:<name>, agent:<name>): the framework refuses to start with one. */
+    /** The tokens of a repository put by name at run time, which no ai.repo of this process names. */
+    repoTokens?: RepoTokens;
+    /** Names declared twice (tool:<name>, agent:<name>, repoTokens): the framework refuses to start with one. */
     twice: Set<string>;
 }
 /**
@@ -185,18 +303,32 @@ export declare function backendRepo(options: {
     repository: string;
     defaultBranch?: string;
     machine?: string;
-    token: (ctx: {
-        repo: string;
-        repository: string;
-        signal: AbortSignal;
-    }) => string | Promise<string>;
+    token: (ctx: RepoTokenContext) => string | Promise<string>;
 }): BackendRepo;
+/**
+ * The tokens of the project's repositories put by name at run time
+ * (ai.repos.put(name, { repository, backend })) — one a product makes for
+ * itself — which no ai.repo of this backend names: each clone and each push
+ * of a chat's workspace asks this machine, and give answers with a token for
+ * that one operation, or null for a repository it gives none for (the
+ * workspace is refused it). An ai.repo of the name answers for its own
+ * repository first. Given once, at a module's top level.
+ */
+export declare function repoTokens(give: RepoTokens): void;
 export declare function backendAgent(name: string, define: (ctx: AgentContext) => TurnDefinition | Promise<TurnDefinition>, options?: {
     machine?: string;
-    clients?: boolean;
 }): BackendAgent;
+/** A backend's agent (an ai.agent's value) — its name and machine — or undefined for anything else. */
+export declare function backendAgentOf(v: unknown): {
+    readonly name: string;
+    readonly machine?: string;
+} | undefined;
 /** A tool as the platform takes it (ToolRef). */
 export declare function toolRef(t: Tool, what: string): ToolRef;
+/** The most tool calls a turn or a one-shot answer makes: the engine's own bound. */
+export declare const MAX_TOOL_CALLS = 10000;
+/** A definition's bound on its tool calls, refused here as the module would refuse it. */
+export declare function maxToolCallsOf(n: unknown, what: string): number;
 /** A definition as the platform takes it (AgentDefinition). */
 export declare function definitionOf(d: AgentDefinitionInput, what: string): AgentDefinition;
 export {};

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

@@ -70,3 +70,11 @@ export declare class MigrationRunEnded extends Error {
     readonly code: number;
     constructor(code: number);
 }
+/**
+ * The app's CORS joined to the origins of its project's web apps, as the
+ * platform starts it with them (PALBASE_WEB_ORIGINS, comma-separated): a
+ * browser on one of them may call it without the app naming it. Any origin
+ * ("*") stays any. An origin CORS cannot hold (an address in brackets) is
+ * left out, and said.
+ */
+export declare function withWebOrigins(own: CorsOptions | undefined, given: string | undefined, warn?: (message: string) => void): CorsOptions | undefined;

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

@@ -14,6 +14,8 @@ export declare class Container {
     private readonly owner;
     private readonly defs;
     private readonly instances;
+    /** The classes the modules list as providers (not controllers): what ctx.inject may be given. */
+    private readonly providers;
     /** Construction order: dependencies before their dependents. */
     readonly order: object[];
     readonly controllers: {
@@ -28,8 +30,8 @@ export declare class Container {
     readonly cronProviders: Ctor[];
     /** The providers that are @Task classes: the platform runs them as their tasks come due. */
     readonly taskProviders: Ctor[];
-    /** The providers that are @Room classes. */
-    readonly rooms: Ctor[];
+    /** The providers that are @Gateway classes. */
+    readonly gateways: Ctor[];
     constructor(modules: Function[]);
     private collect;
     private validate;
@@ -41,6 +43,13 @@ export declare class Container {
      * a route's @Resolve, by its controller — under a constructor's rules.
      */
     dependencyOf<T extends object>(consumer: abstract new (...args: never[]) => object, dep: abstract new (...args: never[]) => T, at: string): T;
+    /**
+     * The built instance of a provider, asked for by code no module owns — a
+     * tool's run, an agent's function (ctx.inject) — so any module's provider,
+     * exported or not: the class itself, or the one provider that extends it,
+     * as a constructor's parameter of that type finds it. `at` says who asked.
+     */
+    provider<T extends object>(cls: abstract new (...args: never[]) => T, at: string): T;
     private reachable;
     private target;
     /** onStart() of every instance, in construction order; a throw stops the boot after the started ones are shut down. */

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

@@ -54,7 +54,7 @@ export interface DatabaseConfig {
  * nothing — `palbase db:plan` and `db:status` ask the app's own Palgres what a
  * start would do and what the database's ledger says.
  */
-export type MigrateMode = 'start' | 'complete' | 'rollback' | 'plan' | 'status';
+export type MigrateMode = 'start' | 'complete' | 'rollback' | 'plan' | 'status' | 'types';
 /** What the deploy asked of this run: a migration step, or nothing (serve). */
 export declare function migrateModeOf(env: Record<string, string | undefined>): MigrateMode | undefined;
 /**
@@ -106,9 +106,24 @@ export type MigrationExit = 0 | 1 | 75;
  * given to such a machine with its migrations on is refused as its release
  * starts, and the release's rollback then ends — the machine is not held by it.
  */
-export declare function migrateWithoutDatabase(mode: MigrateMode): MigrationExit;
+export declare function migrateWithoutDatabase(mode: MigrateMode): Promise<MigrationExit>;
+/**
+ * The app's tables as types (palbase db:types): each table's row, insert, unique keys and relations both ways —
+ * across its schema files, which a schema's own type cannot see (TablesOf) — as the block the CLI writes into
+ * palbase/palbase-env.d.ts. No database is asked: the schema files say it all.
+ */
+export declare function writeTypes(config: DatabaseConfig | undefined, out?: AnswerOut): Promise<MigrationExit>;
 /** The deploy's migration step. */
 export declare function runMigration(config: DatabaseConfig, env: Record<string, string | undefined>, mode: MigrateMode): Promise<MigrationExit>;
+/** Where the step's answer is written: the standard output's stream, done once what it was given is out. */
+export type AnswerOut = (text: string, done: () => void) => void;
+/**
+ * The step's answer, as one line on stdout the CLI reads: {"palbase_migrate": mode, "result": …} — out, and every
+ * log line before it, when this resolves: the run exits right after, and on a pipe what the stream still held went
+ * with the process (a large plan's line was cut at what the pipe took: the CLI read "Unterminated string in JSON at
+ * position 131072"). One stream, in order: a log line is never cut by it.
+ */
+export declare function said(mode: MigrateMode, result: unknown, out?: AnswerOut): Promise<void>;
 export interface OpenDatabase {
     model: Schema;
     binding: Binding;

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

@@ -1,7 +1,6 @@
 import { type PalbaseServer, type TokenUser, type TokenVerifier, type WebhookEvent } from '../../server/src/index.js';
 import { type AuthSpec, type RateLimitConfig } from './decorators.js';
 import { type ContractOptions } from './openapi.js';
-import { type ChannelsDef } from './channels.js';
 import { type StringsTable } from './i18n.js';
 import type { RequestTelemetry } from './requests.js';
 /** The signed-in user, as @User() gives it. */
@@ -63,8 +62,6 @@ export interface AppOptions {
     cors?: CorsOptions;
     /** The framework's own handlers of the platform's events (user.deleted → forget), run before the app's @On. */
     events?: Record<string, ((event: WebhookEvent) => Promise<unknown>)[]>;
-    /** The app's channels; the ones defineChannels declared in this process unless given (a test's own). */
-    channels?: ChannelsDef;
     /** The app's database: each request (and each delivery) one transaction, as its caller or as the service role. */
     database?: {
         app: RequestDatabases;
@@ -104,7 +101,7 @@ export interface AppOptions {
      *   never to be done (TaskFailure, or a payload its schema refuses), or the
      *   failure the platform tries again;
      * - its @Upload routes' two steps, from storage (upload.ts), and its
-     *   @Room classes' joins, messages and moments, from realtime (rooms.ts):
+     *   @Gateway classes' joins, messages and moments, from realtime (gateways.ts):
      *   platform-calls.ts;
      * - its ai tools and agents (@palbase/ai's ai.tool and ai.agent), from the
      *   ai module: POST /_palbase/ai/tools runs the tool an agent called (its
@@ -141,3 +138,5 @@ export interface App {
 }
 export declare const MAX_BODY_BYTES: number;
 export declare function createApp(opts: AppOptions): App;
+/** An origin CORS holds: https://host[:port], http only for localhost, no path. */
+export declare function corsOrigin(origin: string): boolean;

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

@@ -0,0 +1,269 @@
+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;
+};
+/** Whose memberships of a gateway's channel are decided again, and whether the channel is over. */
+export interface RevalidateOptions {
+    /** Only this user's membership: the member taken out. */
+    user?: string;
+    /** The channel is over: every member dropped without being asked, its log forgotten — one channel's, every value given. */
+    end?: boolean;
+}
+/**
+ * What realtime is asked to decide again for a gateway's channels: the one channel when every capture of its pattern
+ * has a value, every channel of the pattern with the values given when some do not — or what is wrong with it, as
+ * realtime would refuse it.
+ */
+export declare function revalidationOf(pattern: string, params: Readonly<Record<string, unknown>>, options: RevalidateOptions): realtime.Revalidation | {
+    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>;
+    /** realtime's POST /realtime/revalidate, as the app: the memberships it names decided again, on every replica. */
+    revalidate(body: realtime.Revalidation): 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>;
+    /** A gateway's channel — or its channels of the values given — decided again (Palbase.gateways.to(…).revalidate). */
+    revalidate(cls: Function, params: Readonly<Record<string, unknown>>, options?: RevalidateOptions): 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 {};