palbase 0.3.2 → 0.4.0

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

@@ -0,0 +1,167 @@
+import type { ai as wire } from '../../internal/src/modules/index.js';
+type AgentDefinition = wire.AgentDefinition;
+type ToolContent = wire.ToolContent;
+type ToolRef = wire.ToolRef;
+import { type ToolResult } from '../../internal/src/tool-output.js';
+import type { Infer, StandardSchema } from './schema.js';
+/** A role, or a catalogue model as provider:model. */
+type Model = 'fast' | 'default' | 'strong' | (string & {});
+/** The chat a tool call or a turn is of, as the platform names it in its signed call. */
+export interface ChatContext {
+    /** The chat; '' for a call of a one-shot answer's (ai.ask with tools), which is of no chat. */
+    chatId: string;
+    /** The agent's name in the chat. */
+    agent: string;
+    /** The member whose message the turn answers; null: the project's server, or a turn nobody wrote. */
+    user: {
+        id: string;
+        name: string;
+    } | null;
+    /**
+     * The chat's own labels — set by whoever started it, and a user may start
+     * one: what they say is the caller's word, not an authority (never a name
+     * of something they may then reach).
+     */
+    metadata: Record<string, string>;
+    /** Ended when the platform stops waiting for the answer. */
+    signal: AbortSignal;
+}
+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;
+}
+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;
+    /** What it does: the agent reads it to choose. */
+    description: string;
+    /** What it takes: a zod (valibot, arktype) object schema — the agent is shown it, and its input is checked against it. */
+    input: S;
+    /**
+     * What the call does: a string, an object (said as JSON), pictures
+     * (`{ 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".
+     */
+    run(input: Infer<S>, ctx: ToolContext): ToolResult | Promise<ToolResult>;
+    /** 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). */
+    machine?: string;
+}
+export interface BackendTool<S extends StandardSchema = StandardSchema> {
+    readonly source: 'backend';
+    readonly name: string;
+    readonly description: string;
+    readonly input: S;
+    /** The input's JSON Schema, as the agent is shown it. */
+    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;
+    }>;
+}
+export interface ClientToolOptions<S extends StandardSchema> {
+    name: string;
+    description: string;
+    /** What it takes; none: an empty object. */
+    input?: S;
+    approval?: boolean;
+}
+/** A tool the app's code answers (pb.ai.chat(id).tools({ name: fn })): the turn waits for its answer. */
+export interface ClientTool {
+    readonly source: 'client';
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly approval: boolean;
+}
+/** An HTTPS tool the project put (ai.endpoints.put(name, { kind: 'https', … })). */
+export interface HttpsToolRef {
+    source: 'https';
+    name: string;
+    approval?: boolean;
+}
+/** An MCP server the project put: its tools, or the ones named in only. */
+export interface McpToolRef {
+    source: 'mcp';
+    name: string;
+    only?: string[];
+    approval?: boolean;
+}
+export type Tool = BackendTool<StandardSchema> | ClientTool | HttpsToolRef | McpToolRef;
+export interface SubagentDefinition {
+    /** Unique among the agent's subagents. */
+    name: string;
+    /** What it is for: the agent reads it to choose. */
+    description: string;
+    instructions?: string;
+    model?: Model;
+    tools?: Tool[];
+    /** The turn fails if this subagent's part fails. */
+    required?: boolean;
+}
+/** What an agent is for a turn. */
+export interface AgentDefinitionInput {
+    instructions?: string;
+    model?: Model;
+    /** 64 at most, with its MCP servers'. */
+    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. */
+    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;
+}
+/** 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'>;
+/** 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 this process declared, for the framework to serve. */
+export interface DeclaredAI {
+    tools: Map<string, BackendTool>;
+    agents: Map<string, BackendAgent>;
+    /** Names declared twice (tool:<name>, agent:<name>): the framework refuses to start with one. */
+    twice: Set<string>;
+}
+/**
+ * A tool's failure in its own words: thrown from run, its message is what
+ * the agent — and the chat's members, who see the call — are told. Any other
+ * throw is told as "The tool failed" (a library's or the database's words
+ * may name what the chat is not to read); the whole of it is in the app's log.
+ */
+export declare class ToolError extends Error {
+    constructor(message: string);
+}
+export declare const AGENT_NAME: RegExp;
+/** The input's JSON Schema: an object, written out (no references), as a provider takes a tool's parameters. */
+export declare function parametersOf(schema: StandardSchema | undefined, what: string): Record<string, unknown>;
+export declare function backendTool<S extends StandardSchema>(o: BackendToolOptions<S>): BackendTool<S>;
+export declare function clientTool<S extends StandardSchema>(o: ClientToolOptions<S>): ClientTool;
+export declare function backendAgent(name: string, define: (ctx: AgentContext) => TurnDefinition | Promise<TurnDefinition>, options?: {
+    machine?: string;
+    clients?: boolean;
+}): BackendAgent;
+/** A tool as the platform takes it (ToolRef). */
+export declare function toolRef(t: Tool, what: string): ToolRef;
+/** A definition as the platform takes it (AgentDefinition). */
+export declare function definitionOf(d: AgentDefinitionInput, what: string): AgentDefinition;
+export {};

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

@@ -1,6 +1,7 @@
 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 StringsTable } from './i18n.js';
 import type { RequestTelemetry } from './requests.js';
 /** The signed-in user, as @User() gives it. */
 export interface UserT {
@@ -66,6 +67,12 @@ export interface AppOptions {
         app: RequestDatabases;
         requests: 'caller' | 'service';
     };
+    /**
+     * The app's strings (palbase/strings/, loadStringsTable): t() answers each request in the first of its
+     * Accept-Language's languages the table has, the source language otherwise, and the answer says which
+     * (Content-Language) and that it depends on them (Vary: Accept-Language).
+     */
+    strings?: StringsTable;
     /**
      * Built to write its contract and nothing else (PALBASE_CONTRACT_OUT): its
      * webhooks' secrets are not read, and whether it declares a database says
@@ -90,7 +97,11 @@ export interface AppOptions {
      *   and answers 204, 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):
-     *   platform-calls.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
+     *   body's tool), POST /_palbase/ai/agents answers the definition of the
+     *   agent a turn is of (its body's agent) — ai-calls.ts.
      */
     platform?: {
         secret: string;

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

@@ -1,14 +1,13 @@
-/** The app's strings: its source language, its languages, and each key's cell per language. */
+/**
+ * The app's strings (palbase/strings/, loadStringsTable): its source language, the languages it has files for, and
+ * each key's translation by language — an empty one is not translated yet, and the key itself answers.
+ */
 export interface StringsTable {
-    version: 1;
     source: string;
     locales: string[];
-    strings: Record<string, Record<string, {
-        value: string;
-        state: 'translated' | 'needs_review' | 'missing';
-    }>>;
+    strings: Record<string, Record<string, string>>;
 }
-/** The languages a request asks for, best first — each tag and then its base language — and the source last. */
+/** The languages a request asks for, best first — each tag, then the shorter ones a table may name — and the source last. */
 export declare function chainFromAcceptLanguage(header: string | null, source: string | undefined): string[];
 /** The key's text in the first language of the chain that has it — the key itself in the source language. */
 export declare function lookup(table: StringsTable, key: string, chain: readonly string[]): {
@@ -17,5 +16,7 @@ export declare function lookup(table: StringsTable, key: string, chain: readonly
 };
 /** {{name}} filled from vars ({{{name}}} left as it is); a value not given is empty. */
 export declare function interpolate(text: string, vars?: Record<string, unknown>): string;
+/** The app started without a table at `root`'s palbase/strings: the first t() says so. */
+export declare function stringsMissingAt(root: string | undefined): void;
 /** The sentence `key` (written in the source language) in the caller's language, {{name}} filled. */
 export declare function t(key: string, vars?: Record<string, string | number | boolean | null | undefined>): string;

package/types/backend/src/strings-files.d.ts

@@ -1,3 +1,30 @@
 import type { StringsTable } from './i18n.js';
-/** The table under `root` (the app's directory), or undefined when it has none. */
+export declare const STRINGS_DIR = "palbase/strings";
+/** The format this writes and the running app reads. */
+export declare const STRINGS_FORMAT = 3;
+/** A language tag as Intl writes it (en, en-US, zh-Hans): the form a request's languages are matched in. */
+export declare function canonicalLanguage(tag: string): string | undefined;
+/** The files as they are: their format, the source language, and each language's translations by key. */
+export interface StringsFiles {
+    format: number;
+    source: string;
+    languages: Map<string, Map<string, string>>;
+}
+/**
+ * palbase/strings/ under `root` read as it is — this format, or the earlier one (its cells' values; a missing one
+ * is empty) — every file checked: a file that breaks a rule is named, with the rule. Undefined when there is none.
+ */
+export declare function readStringsFiles(root: string, formats?: readonly number[]): Promise<StringsFiles | undefined>;
+/** The table under `root` (the app's directory) the running app answers t() from, or undefined when it has none. */
 export declare function loadStringsTable(root: string): Promise<StringsTable | undefined>;
+/** One language file's text: its sentences in order, each with its translation, as JSON written for people to edit. */
+export declare function stringsFileText(translations: ReadonlyMap<string, string>, order: readonly string[]): string;
+/**
+ * palbase/strings/ under `root` written as `source` and `languages` (each with every key of `order`, in that
+ * order), each file written beside itself and renamed into place, a language file no longer in `languages`
+ * removed. A run cut short leaves a table the next one reads: a new table's _meta.json is written first (its
+ * language files come with it), an existing one's last (a conversion from the earlier format reads the files it
+ * already wrote — readStringsFiles takes a plain translation there too). The files whose text changed, by name;
+ * a file that differs only in its line endings (a checkout's CRLF) is not one.
+ */
+export declare function writeStringsFiles(root: string, source: string, languages: ReadonlyMap<string, ReadonlyMap<string, string>>, order: readonly string[]): Promise<string[]>;

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

@@ -0,0 +1,117 @@
+import type { ChatMessage } 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';
+/** A member's (or the server's) message, as the agent got it. */
+export interface MessageEvent {
+    type: 'message';
+    /** The journal's sequence. */
+    seq: number;
+    message: ChatMessage;
+}
+/** A turn's state: started, waiting (and why), or ended. */
+export interface TurnEvent {
+    type: 'turn';
+    seq: number;
+    response_id: string;
+    /** The member who started it; null: the project's server's turn, or one the engine started from late messages. */
+    user_id?: string | null;
+    /** 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. */
+    waiting: {
+        reason: WaitingReason;
+        text_offset: number;
+        approval_id?: string;
+        tool_call_id?: string;
+        tool_name?: string;
+        input?: unknown;
+    } | null;
+    error: {
+        code?: string;
+        message?: string;
+    } | string | null;
+}
+/** The agent's answer as it is written: new text only, at its byte offset. */
+export interface TextEvent {
+    type: 'text';
+    response_id: string;
+    /** Where the text goes, in bytes of the answer (UTF-8). */
+    offset: number;
+    text: string;
+}
+/** Discard the answer past offset (bytes): the model went back. */
+export interface ResetEvent {
+    type: 'reset';
+    response_id: string;
+    offset: number;
+}
+/** A tool call, each time its state changes. */
+export interface ToolEvent {
+    type: 'tool';
+    seq: number;
+    response_id: string;
+    /** The subagent's run that made it; absent or null: the agent's own. */
+    run_id?: string | null;
+    call_id: string;
+    name: string;
+    status: ToolStatus;
+    /** Where in its response's answer it happened, in bytes. */
+    text_offset: number;
+    input?: unknown;
+    output?: unknown;
+    /** Set while it waits for a person's yes (awaiting_approval). */
+    approval_id?: string | null;
+    /** The output's pictures. */
+    image_count?: number;
+    is_error?: boolean;
+    /** The subagent's response that made the call, when one did. */
+    agent_response_id?: string | null;
+    [field: string]: unknown;
+}
+/** A subagent at work — or one the agent asked for and was refused (status denied, with its reason). */
+export interface AgentEvent {
+    type: 'agent';
+    seq: number;
+    /** The subagent's run; '' for a refused one, which never ran. */
+    run_id: string;
+    /** The subagent's own response; '' for a refused one. */
+    response_id: string;
+    /** The response that handed it the work: its text_offset is in that one's answer. */
+    parent_response_id: string;
+    name: string;
+    required: boolean;
+    status: string;
+    text_offset: number;
+    /** Why it was refused, or why it ended as it did. */
+    reason?: string;
+    [field: string]: unknown;
+}
+export type ChatEvent = MessageEvent | TurnEvent | TextEvent | ResetEvent | ToolEvent | AgentEvent;
+/** 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>;
+/** 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;

package/types/internal/src/tool-output.d.ts

@@ -0,0 +1,20 @@
+import type { ToolContent } from './modules/ai.js';
+export type ToolPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mediaType: string;
+    data: Uint8Array | string;
+} | {
+    type: 'image';
+    media_type: string;
+    data: string;
+} | {
+    mediaType: string;
+    bytes: Uint8Array;
+};
+/** Anything a tool returns: its parts, a string, or a value said as JSON. */
+export type ToolResult = string | ToolPart | readonly ToolPart[] | object | number | boolean | null | undefined;
+export declare function toolOutput(value: unknown): ToolContent[];
+export declare function base64(bytes: Uint8Array): string;

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

@@ -0,0 +1,201 @@
+import { type AgentEvent, type ToolEvent, type TurnEvent } 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 { 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 {
+    /** The writer's id for it: the same id is the same message. */
+    clientId: string;
+    /** The module's id; null until it answered. */
+    id: string | null;
+    text: string;
+    /** The member who wrote it; null: the project's server (or, for one this client sent, not yet answered — mine says it is the user's). */
+    author: string | null;
+    authorName: string;
+    delivery: string;
+    /** pending until the agent has it, delivered once it does, failed when it could not be given (or sent). */
+    status: 'pending' | 'delivered' | 'failed';
+    /** Why it failed: the module's code. */
+    error: string | null;
+    /** The turn it started or reached. */
+    responseId: string | null;
+    createdAt: string;
+    /** Sent from this client. */
+    mine: boolean;
+}
+/** A piece of an answer, in order: its text, split where a tool was called or a subagent handed work. */
+export type ChatPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool';
+    tool: ToolEvent;
+} | {
+    type: 'agent';
+    agent: AgentEvent;
+};
+/** One answer of the agent's (or of one of its subagents). */
+export interface ChatResponse {
+    id: string;
+    status: TurnEvent['status'] | null;
+    waiting: TurnEvent['waiting'];
+    error: TurnEvent['error'];
+    /** The whole answer so far. */
+    text: string;
+    parts: ChatPart[];
+    /** A subagent's: its run, its name, and the response that handed it the work. */
+    runId: string | null;
+    agent: string | null;
+    parentId: string | null;
+    /** The member whose turn it is (a subagent's: its turn's); null: the project's server's, or the engine's. */
+    startedBy: string | null;
+    /** The signed-in user's own turn: theirs alone to answer its client tools and decide its approvals. */
+    mine: boolean;
+    /** The chat has had one member all its life, as its turn last said (null until it did): only then does this app answer its client tools by itself. */
+    solo: boolean | null;
+}
+export type ChatItem = {
+    type: 'message';
+    message: ChatMessageView;
+} | {
+    type: 'response';
+    response: ChatResponse;
+};
+export interface ChatState {
+    /** idle until the chat is first used; live while its stream is open; failed when the stream was refused (error says why). */
+    status: 'idle' | 'connecting' | 'live' | 'failed' | 'closed';
+    error: unknown;
+    /** The conversation in order: the members' messages and the agent's answers (a subagent's is in its parent's parts). */
+    items: ChatItem[];
+    messages: ChatMessageView[];
+    /** Every answer, the subagents' too, as they began. */
+    responses: ChatResponse[];
+    /** The last turn's state. */
+    turn: TurnEvent | null;
+    /**
+     * What waits for this user: tool calls of their own turns waiting for
+     * their yes (approve/deny), and client tool calls of their own turns
+     * waiting for their app's answer. Another member's turn is theirs to
+     * decide — its calls are in its parts, not here.
+     */
+    waiting: {
+        approvals: ToolEvent[];
+        outputs: ToolEvent[];
+    };
+}
+export interface ChatOptions {
+    /** The journal id to follow from (default 0: the chat from its start). */
+    after?: number;
+    /** How long a stream that keeps being cut is followed again before the chat fails (default 2 minutes). */
+    resumeFor?: number;
+}
+/** A client tool's answer, by the tool's name: what it returns is shown to the agent; a throw is the tool's failure. */
+export type ClientToolHandlers = Record<string, (input: unknown, call: ToolEvent) => ToolResult | Promise<ToolResult>>;
+/** One chat, followed: its state, its changes, and what the user does in it. */
+export declare class ChatSession implements AsyncIterable<ChatState> {
+    readonly id: string;
+    private readonly api;
+    private readonly session;
+    private readonly options;
+    private status;
+    private error;
+    private readonly messages;
+    private readonly responses;
+    private readonly order;
+    private turn;
+    private readonly calls;
+    private readonly handlers;
+    private readonly answering;
+    private readonly listeners;
+    private following;
+    /** Where the stream is: a chat followed again (after a failure) goes on from there, not from its start. */
+    private position;
+    private snapshot;
+    private told;
+    constructor(api: ReturnType<typeof aiModule.client>, id: string, options?: ChatOptions, session?: SessionManager);
+    /** The chat as this client holds it now: the same object until it changes. */
+    get state(): ChatState;
+    /** Told the state each time it changes (at most once a microtask); returns the unsubscribe. The chat is followed from now on. */
+    subscribe(listener: (state: ChatState) => void): () => void;
+    /** The state now, then each time it changes; a break leaves the chat followed (close() ends it). */
+    [Symbol.asyncIterator](): AsyncGenerator<ChatState, void, undefined>;
+    /**
+     * Writes to the chat: the message is in the state at once, pending, and
+     * delivered when the agent has it (the stream says so); failed when it
+     * could not be sent — the promise rejects with why (429
+     * too_many_messages, 409 history_full). The same clientId again (a
+     * failed message sent again) is the same message.
+     */
+    send(text: string, options?: {
+        delivery?: 'next' | 'now';
+        clientId?: string;
+    }): Promise<ChatMessageView>;
+    /**
+     * The client tools this app answers by itself, by name: a call of one of
+     * them that waits for its output (a tool part, awaiting_output) is
+     * answered with what the function returns — in a turn the signed-in user
+     * started, of a chat that is theirs alone (solo). In a chat with other
+     * members a message of theirs may have asked for it (a location, a
+     * photo), and they see the answer: the call stays in waiting.outputs for
+     * the app to ask its user and answer (answer()). A call in another
+     * member's turn is theirs: it never runs on this device (the module
+     * refuses another's answer, 403 not_your_turn). Returns the function that
+     * takes them back.
+     */
+    tools(handlers: ClientToolHandlers): () => void;
+    /**
+     * Answers a client tool's call of the user's own turn (a tool part's
+     * call_id, awaiting_output) — what tools() does by itself in a chat that is
+     * theirs alone, and the app does here when it is not, once its user said
+     * yes. True when this answer is the one; false when the call was answered
+     * already or waits no more.
+     */
+    answer(callId: string, output: ToolResult, options?: {
+        isError?: boolean;
+    }): Promise<boolean>;
+    /** A call that waits for a person's yes (a tool part's approval_id): made. */
+    approve(approvalId: string, reason?: string): Promise<void>;
+    /** Not made: the agent is told, with the reason, and goes on. */
+    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>;
+    /** 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. */
+    close(): void;
+    private follow;
+    private take;
+    private heard;
+    private response;
+    private autoAnswer;
+    /** The signed-in user started this response's turn (its turn event said so). */
+    private mine;
+    private changed;
+    private build;
+}
+/** The project's agents for the signed-in user. */
+export declare class AI {
+    /** Every client operation of the ai contract, through the session's transport. */
+    readonly api: ReturnType<typeof aiModule.client>;
+    private readonly session;
+    /** The chats the user is in: started with a named agent the project opened to its users (as its owner), listed, read, deleted (an owner's). */
+    readonly chats: {
+        /** A chat with a named agent (clients: true), the user its owner under `name`. A user's chat carries no metadata: that is the server's to write. */
+        create(chat: {
+            agent: string;
+            name?: string;
+            title?: string;
+        }): Promise<Chat>;
+        /** The chats the user is in, the newest first (100 at most). */
+        list(): Promise<Chat[]>;
+        get(id: string): Promise<Chat>;
+        delete(id: string): Promise<void>;
+    };
+    constructor(transport: Transport, session?: SessionManager);
+    /** A chat the user is in, to follow and write to. */
+    chat(chatId: string, options?: ChatOptions): ChatSession;
+}

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

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

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

@@ -3,6 +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 { 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';

package/dist/chunks/QA3GIZMI.js

@@ -1,4 +0,0 @@
-/*! palbase 0.3.2 — Palbase SDK License (see LICENSE) */
-import{AsyncLocalStorage as g}from"node:async_hooks";function b(e,r){return new Proxy(r,{get(t,n,s){if(d.getStore()?.services===void 0)return Reflect.get(t,n,s);let o=f(e,n,t),a=o[n];return typeof a=="function"?a.bind(o):a}})}function f(e,r,t){let n=d.getStore()?.services;if(n===void 0)return t;let s=n[e];if(s!==void 0)return s;if(e==="Log"||typeof r=="symbol"||r==="then")return t;throw new Error(`${e}.${String(r)} was read, but this test did not provide ${e}. Pass it: withServices({ ${e}: \u2026 }, () => \u2026)`)}var p=Symbol.for("palbase.backend.requestScope"),d=globalThis[p]??=new g,u;function S(e){u=e}var m=new Proxy({},{get(e,r){if(!u)throw new Error(`Palbase.${String(r)} is reached before the app is served (serve() binds it)`);return u[r]}}),v=new Proxy({},{get(e,r){let t=d.getStore(),n=t?.database;if(!n)throw new Error(t?.services?`Database.${String(r)} was read, and this test gave no Database: withServices({ Database: fake.raw }, \u2026)`:t?`Database.${String(r)}: this app declares no database \u2014 PalbaseFactory.create(\u2026, { db: { schemas } })`:`Database.${String(r)} is reached outside a request: it is the request's transaction, reached from a handler, a service it calls or an @On`);let s=n[r];return typeof s=="function"?s.bind(n):s}});function c(e,r,t){let n={time:new Date().toISOString(),level:e,msg:r},s=d.getStore();if(s&&(n.request_id=s.requestId),t)for(let[a,i]of Object.entries(t))n[a]=i instanceof Error?{name:i.name,message:i.message,stack:i.stack}:i;let o=w(n);e==="error"||e==="warn"?process.stderr.write(`${o}
-`):process.stdout.write(`${o}
-`)}function w(e){try{return JSON.stringify(e)}catch{let r=new WeakSet;try{return JSON.stringify(e,(t,n)=>{if(typeof n=="bigint")return n.toString();if(typeof n=="object"&&n!==null){if(r.has(n))return"[circular]";r.add(n)}return n})}catch{return JSON.stringify({time:e.time,level:e.level,msg:e.msg,request_id:e.request_id,unwritable:"a field of this line could not be written"})}}}var y=b("Log",{debug:(e,r)=>c("debug",e,r),info:(e,r)=>c("info",e,r),warn:(e,r)=>c("warn",e,r),error:(e,r)=>c("error",e,r)});export{b as a,f as b,d as c,S as d,m as e,v as f,y as g};

package/dist/chunks/QD5XLRIJ.js

@@ -1,2 +0,0 @@
-/*! palbase 0.3.2 — Palbase SDK License (see LICENSE) */
-import{c as f}from"./QA3GIZMI.js";var A=512,b=8,x=64,O=/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/,p={"i-klingon":"tlh","en-gb-oed":"en-GB-oxendict","sgn-be-fr":"sfb","zh-cmn-hans":"cmn-Hans","zh-yue":"yue","hy-arevela":"hy-arevela"};function m(e){let n=e.indexOf("-");return n>0?e.slice(0,n):e}function _(e){let n=e.split("-"),r=(n[0]??"").toLowerCase();return r==="mo"&&n.length===1?"ro-MD":r==="tl"?(n[0]="fil",n.join("-")):r==="sh"?(n[0]="sr",n.length>1&&/^[A-Za-z]{4}$/.test(n[1]??"")||n.splice(1,0,"Latn"),n.join("-")):e}function E(e){let n=e.trim().replaceAll("_","-");if(n===""||n==="*"||n.length>x)return;let r=n.toLowerCase(),s=Object.hasOwn(p,r)?p[r]:void 0;if(s===void 0){try{s=Intl.getCanonicalLocales(_(n))[0]}catch{return}if(s===void 0)return}let i=m(s);if(!(i===""||i==="und"||i==="mul"))return s}function S(e,n){let r=[],s=i=>{i!==""&&!r.includes(i)&&r.push(i)};if(e!==null&&e.length<=A){let i=[];for(let o of e.split(",")){let t=o.trim();if(t==="")continue;let c=1,u=t.indexOf(";");if(u>=0){let l=t.slice(u+1);t=t.slice(0,u).trim();let a=l.indexOf("q=");if(a>=0){let d=l.slice(a+2).trim();if(O.test(d)){let g=Number(d);Number.isFinite(g)&&(c=g)}}}c>0&&i.push({tag:t,q:c,at:i.length})}i.sort((o,t)=>t.q-o.q||o.at-t.at);for(let{tag:o}of i.slice(0,b)){let t=E(o);t!==void 0&&(s(t),s(m(t)))}}return n!==void 0&&n!==""&&s(n),r}function L(e,n,r){let s=e.strings??{},i=Object.hasOwn(s,n),o=i?s[n]:null;for(let t of r){if(t===e.source){if(i)return{text:n,locale:t};continue}let c=o!=null&&Object.hasOwn(o,t)?o[t]:void 0;if(c!=null&&c.state!=="missing")return{text:c.value,locale:t}}return{text:n,locale:e.source}}var w=/\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;function h(e,n){return e.replace(w,(r,s,i,o)=>{if(o[i-1]==="{"||o[i+r.length]==="}")return r;let t=n!==void 0&&Object.hasOwn(n,s)?n[s]:void 0;return t==null?"":String(t)})}function T(e,n){let r=f.getStore(),s=r?.strings;if(s===void 0)return h(e,n);let{text:i,locale:o}=L(s,e,r?.locales??[s.source]),t=r?.usedLocales;return t!==void 0&&!t.includes(o)&&t.push(o),h(i,n)}export{S as a,T as b};