palbase 0.5.0 → 0.5.1

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

@@ -1,5 +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 { Route } from './router.js';
 /** Where the platform delivers the project's events to the app. */
@@ -34,6 +35,8 @@ export interface ContractOptions {
     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[];
 }
 /** What a route answers and throws, as its source declares. */
 export interface RouteContract {

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

@@ -89,6 +89,16 @@ export interface RoomContext {
 export interface RoomMessageContext<P = unknown> extends RoomContext {
     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;
+/**
+ * Why `pattern` is no room'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 room at all, silently: the room 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 room `pattern` names. It is a provider a
  * module lists (its constructor injected as any provider's), built once: what

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

@@ -88,7 +88,23 @@ export interface AgentEvent {
     reason?: string;
     [field: string]: unknown;
 }
-export type ChatEvent = MessageEvent | TurnEvent | TextEvent | ResetEvent | ToolEvent | AgentEvent;
+/** 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. */

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

@@ -93,6 +93,7 @@ export type Chat = {
      * Its title.
      */
     title: string;
+    workspace?: ChatWorkspace;
 };
 /**
  * Chats, the newest first (100 at most).
@@ -152,6 +153,19 @@ export type ChatMessage = {
      */
     text: string;
 };
+/**
+ * One repository of a chat's workspace.
+ */
+export type ChatRepo = {
+    /**
+     * The branch it is checked out at and pushed to (the repository's default unless said).
+     */
+    branch?: string;
+    /**
+     * The project's name for the repository (PUT /ai/repos/{name}).
+     */
+    repo: string;
+};
 /**
  * A chat to start.
  */
@@ -179,6 +193,20 @@ export type ChatRequest = {
      * Its title (256 bytes at most).
      */
     title?: string;
+    workspace?: ChatWorkspace;
+};
+/**
+ * The project's repositories a chat works in, each at a branch: its turns run on a machine of the platform's with them checked out, and what its agent commits is pushed to that branch.
+ */
+export type ChatWorkspace = {
+    /**
+     * Lets the agent push its commits to the branches without a person's yes — the server's choice for the chat: its members' messages then reach the repository. Without it a push waits for a member's approval.
+     */
+    auto_push?: boolean;
+    /**
+     * 1 to 8 of the project's repositories, each once.
+     */
+    repos: ChatRepo[];
 };
 /**
  * A decision made.
@@ -609,6 +637,7 @@ export type MessageRequest = {
      * The member the server writes as (the server's alone).
      */
     as?: string;
+    budget?: TurnBudget;
     /**
      * The writer's own id for it: sent again — a retry, a second tab — it is the same message, delivered once.
      */
@@ -687,6 +716,54 @@ export type ProviderList = {
      */
     providers: Provider[];
 };
+/**
+ * A GitHub repository the project's chats work in, by the project's name for it; the project's backend gives its tokens (the framework's ai.repo), asked at each clone and each push.
+ */
+export type Repo = {
+    /**
+     * The project's machine that gives its tokens.
+     */
+    backend: string;
+    /**
+     * When it was put first.
+     */
+    created_at: string;
+    /**
+     * The branch a workspace takes when it names none.
+     */
+    default_branch: string;
+    /**
+     * The project's name for it.
+     */
+    name: string;
+    /**
+     * The GitHub repository, owner/name.
+     */
+    repository: string;
+};
+/**
+ * The project's repositories.
+ */
+export type RepoPage = {
+    repos: Repo[];
+};
+/**
+ * A repository the project's chats work in.
+ */
+export type RepoRequest = {
+    /**
+     * The project's machine whose framework gives the repository's tokens (backend unless said).
+     */
+    backend?: string;
+    /**
+     * The branch a workspace takes when it names none (main unless said).
+     */
+    default_branch?: string;
+    /**
+     * The GitHub repository, owner/name.
+     */
+    repository: string;
+};
 /**
  * A response.
  */
@@ -1027,6 +1104,83 @@ export type ToolRef = {
      */
     source: "backend" | "https" | "mcp" | "client";
 };
+/**
+ * One artifact a turn's agent published.
+ */
+export type TurnArtifact = {
+    /**
+     * Its digest (sha256:<hex>).
+     */
+    checksum: string;
+    /**
+     * When it was published.
+     */
+    created_at: string;
+    /**
+     * The artifact.
+     */
+    id: string;
+    /**
+     * What it is to the engine, when it says.
+     */
+    logical_type?: string;
+    /**
+     * Its media type, as published.
+     */
+    media_type: string;
+    /**
+     * Its size.
+     */
+    size_bytes: number;
+};
+/**
+ * A turn's artifacts.
+ */
+export type TurnArtifacts = {
+    artifacts: TurnArtifact[];
+};
+/**
+ * What the turn a message starts may cost at most, its subagents' spend counted (the server's alone): past it the engine stops the turn. A message delivered into a turn already running takes that turn's.
+ */
+export type TurnBudget = {
+    /**
+     * US dollars, more than 0 and at most 100000; rounded up to the cent.
+     */
+    max_cost_usd: number;
+};
+/**
+ * What one turn of a chat cost so far: its model calls and its subagents', at the engine's frozen rates.
+ */
+export type TurnCost = {
+    /**
+     * The chat.
+     */
+    chat_id: string;
+    /**
+     * What they cost, in billionths of a US dollar.
+     */
+    cost_nano_usd: number;
+    /**
+     * Nothing more of the turn's use can be settled: false while it or a subagent of it runs.
+     */
+    final: boolean;
+    /**
+     * Input tokens of the turn and its subagents.
+     */
+    input_tokens: number;
+    /**
+     * Output tokens of the turn and its subagents.
+     */
+    output_tokens: number;
+    /**
+     * The turn.
+     */
+    response_id: string;
+    /**
+     * A model of the turn has no price: the cost is a lower bound.
+     */
+    unpriced: boolean;
+};
 /**
  * A page of uses.
  */
@@ -1089,6 +1243,61 @@ export type Use = {
      */
     response_id: string | null;
 };
+/**
+ * Text for the voice.
+ */
+export type VoiceCommand = {
+    /**
+     * The delegated voice part this answers (speak).
+     */
+    delegation_id?: string;
+    /**
+     * What it is given (16 KiB at most).
+     */
+    text: string;
+    /**
+     * speak (say this), know (keep it in mind) or instruct (behave so).
+     */
+    type: "speak" | "know" | "instruct";
+};
+/**
+ * Starts the chat's live voice.
+ */
+export type VoiceRequest = {
+    /**
+     * The app's WebRTC offer (an SDP).
+     */
+    sdp: string;
+    /**
+     * The voice (the provider's default unless said).
+     */
+    voice?: string;
+};
+/**
+ * A chat's live voice.
+ */
+export type VoiceSession = {
+    /**
+     * The chat.
+     */
+    chat_id: string;
+    /**
+     * The voice session.
+     */
+    id: string;
+    /**
+     * The provider's WebRTC answer, for the app's peer connection (on start).
+     */
+    sdp?: string;
+    /**
+     * How long it lasted (on close).
+     */
+    seconds: number;
+    /**
+     * active, or closed.
+     */
+    status?: string;
+};
 /** The events this module sends the project's webhooks (x-palbase-events), by type: each one's payload, the event's data. */
 export interface Events {
     /**
@@ -1293,6 +1502,80 @@ export declare function client(t: Transport): {
         body: ToolOutput; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, ToolOutputAccepted>>;
+    /**
+     * A turn's artifacts
+     *
+     * What the turn's agent published as its output (palai.artifact.publish) — a build's product from the workspace's Mac, a screenshot, a report — kept in the project's own storage. The chat's members and the project's server read it, as they read the chat.
+     */
+    listChatTurnArtifacts(input: {
+        path: {
+            chat_id: string; /** The turn: a message's response_id, or a turn event's. */
+            response_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, TurnArtifacts>>;
+    /**
+     * An artifact of a turn
+     *
+     * One artifact of the turn, its bytes as the agent published them (an attachment, never a page). One the turn did not publish is not found (404 artifact_not_found).
+     */
+    getChatTurnArtifact(input: {
+        path: {
+            chat_id: string; /** The turn: a message's response_id, or a turn event's. */
+            response_id: string; /** The artifact: an id of the turn's artifacts. */
+            artifact_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Response>>;
+    /**
+     * What a turn of a chat cost
+     *
+     * What a turn of the chat cost so far, its subagents' calls counted — while it runs too (final false) — or what one subagent's work in it cost (an agent event's response_id). The project's server's: a member's key is refused (403 server_only).
+     */
+    getChatTurnCost(input: {
+        path: {
+            chat_id: string; /** The turn: a message's response_id, or a turn event's. */
+            response_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, TurnCost>>;
+    /**
+     * Start a chat's voice
+     *
+     * Starts the chat's live voice: the app's WebRTC offer in, the answer out — the audio then goes between the app and the platform's voice provider. What is said either way is in the chat's stream as voice parts (transcripts); a task the voice hands over is a voice part of kind delegated. One voice a chat at a time (409 voice_active). A user starts at most 5 voices an hour in the project's chats (429 too_many_voices, with Retry-After) — each is the project's spend while it lasts; the server's starts are not counted.
+     */
+    startChatVoice(input: {
+        path: {
+            chat_id: string;
+        };
+        body: VoiceRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, VoiceSession>>;
+    /**
+     * Close a chat's voice
+     *
+     * Ends the chat's voice; the answer says how long it lasted.
+     */
+    closeChatVoice(input: {
+        path: {
+            chat_id: string; /** The voice session. */
+            voice_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, VoiceSession>>;
+    /**
+     * Tell a chat's voice
+     *
+     * The server's alone (a member is answered 403 server_only): a member's words would be the agent's own to every other member of the chat. Gives the chat's voice text: speak says it, know keeps it in mind, instruct changes how it behaves — speak with a delegation_id answers a task it handed over.
+     */
+    commandChatVoice(input: {
+        path: {
+            chat_id: string; /** The voice session. */
+            voice_id: string;
+        };
+        body: VoiceCommand; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<202, VoiceSession>>;
     /**
      * Turn texts into vectors
      *
@@ -1407,6 +1690,37 @@ 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<204, undefined>>;
+    /**
+     * The project's repositories
+     *
+     * The repositories the project's chats work in.
+     */
+    listRepos(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, RepoPage>>;
+    /**
+     * Put a repository
+     *
+     * Puts a GitHub repository the project's chats work in. Its tokens come from the project's backend (the framework's ai.repo), asked at each clone and each push — none is kept.
+     */
+    putRepo(input: {
+        path: {
+            name: string;
+        };
+        body: RepoRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Repo>>;
+    /**
+     * Delete a repository
+     *
+     * A chat's workspace checks it out no more.
+     */
+    deleteRepo(input: {
+        path: {
+            name: 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>>;
     /**
      * Ask a model
      *

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

@@ -5262,7 +5262,7 @@ export declare function client(t: Transport): {
             to?: string; /** The periods: day, week (ISO, Monday to Sunday) or month; day unless said. */
             resolution?: "day" | "week" | "month"; /** Count the stores' test purchases too (Apple's sandbox, Stripe's test mode); segment or filter by sandbox to tell them apart. */
             sandbox?: boolean; /** Split the chart by a dimension (a segmentable chart's). */
-            segment?: "store" | "platform" | "country" | "product" | "plan" | "duration" | "sandbox" | "paywall" | "experiment"; /** Keep what has, for each dimension named, one of the values given: one dimension:value a parameter, repeated for more (filter=store:apple&filter=country:TR&filter=country:DE), at most 20; the value is everything after the first colon (commas and colons are the value's). A segmentable chart's. */
+            segment?: "store" | "platform" | "country" | "product" | "plan" | "duration" | "sandbox" | "paywall" | "experiment"; /** Keep what has, for each dimension named, one of the values given: one dimension:value a parameter, repeated for more (filter=store:app_store&filter=country:TR&filter=country:DE), at most 20; the value is everything after the first colon (commas and colons are the value's). A segmentable chart's. */
             filter?: string[]; /** The currency to report money in, for this answer: one the European Central Bank publishes a reference rate for. The project's reporting currency (settings) unless said. */
             currency?: string; /** What of the money a monetary chart counts: gross (what customers paid), net_of_taxes, or proceeds (net of taxes and the store's commission); gross unless said. What the ledger does not state is estimated, and the answer says so (estimated). */
             revenue_type?: "gross" | "net_of_taxes" | "proceeds"; /** The conversion charts' conversion timeframe and the lifetime charts' customer lifetime, in days from a customer's first day (0: that day); to now unless said. */

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

@@ -291,7 +291,7 @@ export type StorageObject = {
  */
 export type StorageStats = {
     /**
-     * Every bucket of the project, by name; an empty one with zeros. A platform module's own bucket is listed with its share too, though the project does not reach it otherwise: _ai holds the pictures its agents' tools returned, deleted with their chat (or once a one-shot answer is answered) — counted in the project's storage as its other files are.
+     * Every bucket of the project, by name; an empty one with zeros. A platform module's own bucket is listed with its share too, though the project does not reach it otherwise: _ai holds the pictures its agents' tools returned and, under palai/, its chats' workspaces — their files, their runs' checkpoints and the artifacts their agents published — each deleted with its chat (or once a one-shot answer is answered); counted in the project's storage as its other files are.
      */
     buckets: StorageStatsBucket[];
     /**

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

@@ -1,10 +1,10 @@
-import { type AgentEvent, type ToolEvent, type TurnEvent } from '../../internal/src/chat.js';
+import { type AgentEvent, type ToolEvent, type TurnEvent, type VoiceEvent } from '../../internal/src/chat.js';
 import { ai as aiModule } from '../../internal/src/modules/index.js';
 import { type ToolResult } from '../../internal/src/tool-output.js';
 import { type Transport } from '../../internal/src/transport.js';
 import type { SessionManager } from './session.js';
 export type Chat = aiModule.Chat;
-export type { AgentEvent, ChatEvent, ToolEvent, TurnEvent } from '../../internal/src/chat.js';
+export type { AgentEvent, ChatEvent, ToolEvent, TurnEvent, VoiceEvent } from '../../internal/src/chat.js';
 export type { ToolResult } from '../../internal/src/tool-output.js';
 /** A member's message as this client holds it: one it sent is here at once, pending until the agent has it. */
 export interface ChatMessageView {
@@ -86,6 +86,18 @@ export interface ChatState {
         approvals: ToolEvent[];
         outputs: ToolEvent[];
     };
+    /** The chat's live voice as it went: what was said either way, in order, and when it began, ended or handed a task over. */
+    voice: VoiceEvent[];
+}
+/**
+ * A chat's live voice this app started (startVoice): its id, its peer connection, and stop. What the voice is
+ * told besides what it hears is the app's server's to say (the server SDK), never a member's.
+ */
+export interface ChatVoice {
+    readonly id: string;
+    readonly peer: RTCPeerConnection;
+    /** Ends the voice; how long it lasted, in seconds. */
+    stop(): Promise<number>;
 }
 export interface ChatOptions {
     /** The journal id to follow from (default 0: the chat from its start). */
@@ -108,6 +120,7 @@ export declare class ChatSession implements AsyncIterable<ChatState> {
     private readonly order;
     private turn;
     private readonly calls;
+    private readonly voiceParts;
     private readonly handlers;
     private readonly answering;
     private readonly listeners;
@@ -163,6 +176,16 @@ export declare class ChatSession implements AsyncIterable<ChatState> {
     deny(approvalId: string, reason?: string): Promise<void>;
     /** Stops the turn the agent is working on: what it wrote stays. Its response's id, or null when none ran. */
     stop(): Promise<string | null>;
+    /**
+     * Starts the chat's live voice from the microphone's stream: the voice's
+     * audio plays in audio (a new element unless given), and what is said
+     * either way comes into the state's voice parts. One voice a chat at a time.
+     */
+    startVoice(options: {
+        stream: MediaStream;
+        voice?: string;
+        audio?: HTMLAudioElement;
+    }): Promise<ChatVoice>;
     /** A message for one of the agent's subagents at work (an agent part's run_id), at its next step. */
     sendToSubagent(runId: string, text: string): Promise<void>;
     /** Stops following the chat. */

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

@@ -3,7 +3,7 @@ export type { Auth, CredentialsLike, SignInResult, User } from './auth.js';
 export { localStore, memoryStore, SessionChangedError, type AuthEvent, type Session, type SessionStore } from './session.js';
 export { Channel, RealtimeSocket, 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 ClientToolHandlers, type ToolEvent, type ToolResult, type TurnEvent, } from './ai.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 { 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';