palbase 0.6.2 → 0.8.0

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

@@ -1,9 +1,10 @@
 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 type { AgentContext, ToolContext, TurnDefinition, TurnMessage } from '../../ai/src/index.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,55 @@ 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>;
+    /**
+     * Who may be on the channel is decided again now, on every replica of realtime — a decision the gateway made may no
+     * longer hold: a member taken out of a chat, a team changed. A member it would no longer let in (its access, its
+     * @Authorize) is dropped, their client told the channel closed; their rejoin is decided on the merits. Params may
+     * leave captures out: every channel of the gateway with the values given. user: only that user's membership. end:
+     * the channel is over — every member dropped without being asked, its log forgotten (one channel, no user).
+     */
+    revalidate(options?: {
+        user?: string;
+        end?: boolean;
+    }): Promise<void>;
+}
+/** The app's gateways, from any service: Palbase.gateways.to(ChatGateway, { chatId }).emit('token', { text }). */
+export interface GatewaysApi {
+    /** A gateway's channel, by its pattern's values — some left out, for revalidate alone: the gateway's channels of the values given. */
+    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 +102,4 @@ export declare const Log: {
     warn: (message: string, fields?: Record<string, unknown>) => void;
     error: (message: string, fields?: Record<string, unknown>) => void;
 };
+export {};

package/types/backend/src/testing/unit.d.ts

@@ -4,7 +4,7 @@ import { type FakeClient, type RecordedQuery } from 'palgres/testing';
 import type { CacheClient } from '../cache.js';
 import type { Schemas, Tables } from '../db-env.js';
 import type { Token } from '../decorators.js';
-import { type Logger } from '../runtime.js';
+import { type GatewaysApi, type Logger } from '../runtime.js';
 import type { Flags, Notifications, Realtime, Secrets, StorageService } from '../services.js';
 import { type StringsTable } from '../i18n.js';
 export type { RecordedQuery };
@@ -18,6 +18,8 @@ export interface RuntimeServices {
     Notifications: typeof Notifications;
     Flags: typeof Flags;
     Realtime: typeof Realtime;
+    /** Palbase.gateways: what a service sends a gateway's channel through (to(Gateway, params).emit, .pipe). */
+    Gateways: GatewaysApi;
 }
 /**
  * Runs `fn` with these stand-ins: Database is the client given (its typed

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

@@ -1,7 +1,28 @@
-import type { ChatMessage } from './modules/ai.js';
+import type { ChatMessage, MessageAttachment } from './modules/ai.js';
 export type TurnStatus = 'running' | 'waiting' | 'completed' | 'failed' | 'canceled' | 'timed_out' | 'budget_exceeded';
 export type WaitingReason = 'approval' | 'tool_output' | 'subagents' | 'message';
 export type ToolStatus = 'running' | 'awaiting_output' | 'awaiting_approval' | 'approved' | 'denied' | 'expired' | 'completed' | 'failed' | 'canceled';
+/** How a turn ended, in the chat's words — as its event (ai.response.completed / failed) says it. */
+export type TurnEnd = 'completed' | 'failed' | 'stopped' | 'budget_exceeded';
+/**
+ * A push, a pull request or a merge the agent asked for (a tool part named push, pull_request or merge), and what a
+ * person decides it by: the repository, the branch it writes, the base it targets, the commit it carries.
+ */
+export interface Publication {
+    /** The engine's word: push_branch, open_pull_request, merge_pull_request. */
+    operation: string;
+    /** owner/name. */
+    repository: string;
+    /** The remote as the engine names it. */
+    remote: string;
+    branch: string;
+    /** The branch a pull request targets, or a merge goes into ('' for a push). */
+    base: string;
+    /** The commit it carries. */
+    commit: string;
+    /** The engine's own sentence of it. */
+    display: string;
+}
 /** A member's (or the server's) message, as the agent got it. */
 export interface MessageEvent {
     type: 'message';
@@ -19,7 +40,16 @@ export interface TurnEvent {
     /** On running and waiting: the chat has had one member all its life, as it is now (once a second has been added, never again). */
     solo?: boolean;
     status: TurnStatus;
-    /** Why it waits, and where in its answer — and, for a tool call, which: null unless status is waiting. */
+    /** A turn the chat's goal opened: the goal, the turn's role (work, or verify: the check of a claimed completion) and its number. */
+    goal?: {
+        goal_id: string;
+        role: 'work' | 'verify' | (string & {});
+        seq: number;
+    };
+    /**
+     * Why it waits, and where in its answer — and, for a tool call, which: null unless status is waiting. A publication
+     * waiting on a person's yes names its part (tool_call_id, tool_name push|pull_request|merge) and what it does.
+     */
     waiting: {
         reason: WaitingReason;
         text_offset: number;
@@ -27,8 +57,17 @@ export interface TurnEvent {
         tool_call_id?: string;
         tool_name?: string;
         input?: unknown;
+        expires_at?: string;
+        publication?: Publication;
     } | null;
+    /** How it ended, once it has: completed, failed, stopped (a member or the server, or the chat went), budget_exceeded. */
+    end?: TurnEnd | (string & {});
+    /** Why, when it did not complete and was not stopped — and whether asking again may go otherwise. */
     error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    } | {
         code?: string;
         message?: string;
     } | string | null;
@@ -47,6 +86,92 @@ export interface ResetEvent {
     response_id: string;
     offset: number;
 }
+/**
+ * The model's reasoning as it thinks, when the agent shows it (thinking: visible): a window of a step's at a time,
+ * each after the one before — the turn's own, never a subagent's.
+ */
+export interface ThinkingEvent {
+    type: 'thinking';
+    seq: number;
+    response_id: string;
+    run_id: string;
+    /** The model step it is of: its windows go together, its reasoning before what the step writes. */
+    step_id?: string;
+    text: string;
+    /**
+     * The model's provider would not give its reasoning (an OpenAI organization not verified for reasoning
+     * summaries): said once for the turn, with the model and the provider's reason — and no text.
+     */
+    unavailable?: true;
+    model?: string;
+    reason?: string;
+}
+export type GoalKind = 'set' | 'updated' | 'turn_started' | 'judged' | 'verified' | 'status_changed' | 'cleared';
+/** A word of the chat's goal: set, changed, a turn of it begun, a turn judged, a claimed completion checked, its status, cleared. */
+export interface GoalEvent {
+    type: 'goal';
+    /** The journal's sequence. */
+    seq: number;
+    goal_id: string;
+    kind: GoalKind | (string & {});
+    /** set and updated: the goal as it is now. */
+    goal?: {
+        objective: string;
+        rubric: string;
+        status: string;
+        stop_code: string;
+        stop_reason: string;
+        phase: string;
+        max_turns?: number | null;
+        max_cost_usd?: number | null;
+    };
+    /** updated: what changed. */
+    changed?: unknown;
+    /** turn_started: the turn's role (work, verify), its number among the goal's turns (the part's seq), its response. */
+    role?: string;
+    turn?: number;
+    response_id?: string;
+    run_id?: string;
+    /** judged and verified: the evaluator's word, and why; verified: what is missing. */
+    verdict?: string;
+    reason?: string;
+    missing?: unknown;
+    /** status_changed: from what to what, and the stop's code (cleared: reason too). */
+    from?: string;
+    to?: string;
+    code?: string;
+}
+/** One message or answer of what a fork began with. */
+export interface HistoryItem {
+    /** user: a member's message, or the server's; assistant: the agent's answer. */
+    role: 'user' | 'assistant';
+    message_id?: string;
+    client_id?: string;
+    author?: string | null;
+    author_name?: string;
+    text: string;
+    metadata?: Record<string, string>;
+    created_at?: string;
+    /** An answer's response, in the chat it was forked from. */
+    response_id?: string;
+    /** Its text here is the first of a longer one: the fork's model read it whole. */
+    text_truncated?: boolean;
+    /** A message's pictures and files ([] or absent for none), as the chat it was forked from had them. */
+    attachments?: MessageAttachment[];
+}
+/** What a fork began with: the chat's messages and its agent's answers before the message it was cut before, a few to a part — written first in the fork's channel. */
+export interface HistoryEvent {
+    type: 'history';
+    /** The chat it was forked from, and the message it was cut before. */
+    forked_from: {
+        chat_id: string;
+        before_message: string;
+    } | null;
+    /** This part's place among the history's parts, and how many there are. */
+    part: number;
+    parts: number;
+    items: HistoryItem[];
+}
 /** A tool call, each time its state changes. */
 export interface ToolEvent {
     type: 'tool';
@@ -68,6 +193,16 @@ export interface ToolEvent {
     is_error?: boolean;
     /** The subagent's response that made the call, when one did. */
     agent_response_id?: string | null;
+    /** A publication's part (named push, pull_request or merge, its call_id the publication's id): what it does and where. */
+    publication?: Publication;
+    /** When its approval lapses, while it waits for one. */
+    expires_at?: string;
+    /**
+     * Its answer is shown by its end (output: its last 16 KiB): how many bytes before it were left out, and that the
+     * part was cut to fit the channel — the whole answer is read by its call (chatToolCall).
+     */
+    omittedBytes: number;
+    outputTruncated: boolean;
     [field: string]: unknown;
 }
 /** A subagent at work — or one the agent asked for and was refused (status denied, with its reason). */
@@ -88,46 +223,44 @@ 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. */
+/** The chat's live voice began, or ended: whose it is, what becomes of what is asked of it, how long it lasted, why it ended. */
 export interface VoiceEvent {
     type: 'voice';
+    /** The journal's sequence of its start; 0 for its end, told from the module's record under the voice's id. */
     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;
+    voice_id: string;
+    /** Its member; null: the server's own. */
+    user_id: string | null;
+    /** chat: what the person asks for is a turn of the chat; events: the backend's to do (ai.voice.delegated). */
+    delegation: 'chat' | 'events' | (string & {});
+    status: 'started' | 'closed' | (string & {});
+    /** On closed: how long it lasted, and why it ended (close_requested, member_removed, chat_deleted, replaced, lost, …). */
     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;
+    close_reason?: string;
 }
-/** 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;
+/** A line said in the chat's voice — the person's (user) or the voice's (assistant): a message of kind voice of its history. */
+export interface TranscriptEvent {
+    type: 'transcript';
+    seq: number;
+    /** The line's id: its message's in the chat's history. */
+    id: string;
+    voice_id: string;
+    role: 'user' | 'assistant' | (string & {});
+    /** The member who said it; null: the voice. */
+    user_id: string | null;
+    author_name: string;
+    text: string;
+    final: boolean;
+    created_at: string;
 }
-/** 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 | ThinkingEvent | ToolEvent | AgentEvent | GoalEvent | HistoryEvent | VoiceEvent | TranscriptEvent;
 /** 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;