palbase 0.1.0 → 0.3.0

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

@@ -1,4 +1,211 @@
 import { type Reply, type Transport } from '../transport.js';
+/**
+ * A named agent of the project.
+ */
+export type Agent = {
+    definition: AgentDefinition;
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * When it was last put.
+     */
+    updated_at: string;
+};
+/**
+ * What an agent is for a turn: its instructions, model, tools and subagents — or, for one the project's backend defines at every turn's start (the framework's ai.agent), the machine to ask (backend), alone.
+ */
+export type AgentDefinition = {
+    /**
+     * The project's machine that defines the agent at each turn.
+     */
+    backend?: string;
+    /**
+     * The app's users start chats with this named agent themselves (when the project lets them talk to its agents): an agent the server alone uses is not one they reach.
+     */
+    clients?: boolean;
+    /**
+     * Its instructions.
+     */
+    instructions?: string;
+    /**
+     * How many tool calls a turn makes at most: past it the agent is told it has no tools left and answers.
+     */
+    max_tool_calls?: number;
+    /**
+     * A role (fast, default, strong) or a catalogue model.
+     */
+    model?: string;
+    /**
+     * Its subagents (16 at most).
+     */
+    subagents?: Subagent[];
+    /**
+     * Its tools (64 at most, with its MCP servers').
+     */
+    tools?: ToolRef[];
+};
+/**
+ * The project's named agents.
+ */
+export type AgentList = {
+    /**
+     * By name.
+     */
+    agents: Agent[];
+};
+/**
+ * A conversation of the project's users with one of its agents.
+ */
+export type Chat = {
+    /**
+     * The agent it talks to.
+     */
+    agent: string;
+    /**
+     * When it was started.
+     */
+    created_at: string;
+    /**
+     * The user who started it; null: the project's server.
+     */
+    created_by: string | null;
+    /**
+     * What it keeps of the project's history.
+     */
+    history_bytes: number;
+    /**
+     * The chat's id.
+     */
+    id: string;
+    /**
+     * Who reads it and writes to it.
+     */
+    members: Member[];
+    /**
+     * The caller's own labels (16 at most, snake_case keys).
+     */
+    metadata: {
+        [key: string]: string;
+    };
+    /**
+     * Its title.
+     */
+    title: string;
+};
+/**
+ * Chats, the newest first (100 at most).
+ */
+export type ChatList = {
+    /**
+     * The chats.
+     */
+    chats: Chat[];
+};
+/**
+ * A member's (or the server's) message.
+ */
+export type ChatMessage = {
+    /**
+     * The member who wrote it; null: the server.
+     */
+    author: string | null;
+    /**
+     * Their name.
+     */
+    author_name: string;
+    /**
+     * The chat.
+     */
+    chat_id: string;
+    /**
+     * The writer's id for it.
+     */
+    client_id: string;
+    /**
+     * When it was written.
+     */
+    created_at: string;
+    /**
+     * next or now.
+     */
+    delivery: string;
+    /**
+     * Why it failed.
+     */
+    error: string | null;
+    /**
+     * Its id.
+     */
+    id: string;
+    /**
+     * The turn it started or reached.
+     */
+    response_id: string | null;
+    /**
+     * pending until the agent has it, delivered once it does, failed when it could not be given to it.
+     */
+    status: string;
+    /**
+     * What they wrote.
+     */
+    text: string;
+};
+/**
+ * A chat to start.
+ */
+export type ChatRequest = {
+    /**
+     * The agent it talks to: a named agent of the project's — or, from the server with a definition of the chat's own, its name for it.
+     */
+    agent: string;
+    definition?: AgentDefinition;
+    /**
+     * Who is in it (the server's to say; 64 at most).
+     */
+    members?: NewMember[];
+    /**
+     * The caller's own labels (16 at most, snake_case keys).
+     */
+    metadata?: {
+        [key: string]: string;
+    };
+    /**
+     * A user who starts a chat is in it as its owner, under this name.
+     */
+    name?: string;
+    /**
+     * Its title (256 bytes at most).
+     */
+    title?: string;
+};
+/**
+ * A decision made.
+ */
+export type Decision = {
+    /**
+     * The approval.
+     */
+    approval_id: string;
+    /**
+     * Yes, or no.
+     */
+    approved: boolean;
+};
+/**
+ * A decision on a tool call that waits for a person.
+ */
+export type DecisionRequest = {
+    /**
+     * Yes, or no.
+     */
+    approve: boolean;
+    /**
+     * Why (told to the agent; 1024 bytes at most).
+     */
+    reason?: string;
+};
 /**
  * An embedding model.
  */
@@ -62,6 +269,81 @@ export type EmbeddingsRequest = {
      */
     model?: string;
 };
+/**
+ * A tool at an HTTPS address of the project's (any backend's, not only this platform's), or an MCP server.
+ */
+export type Endpoint = {
+    /**
+     * Every call waits for a person's yes.
+     */
+    approval: boolean;
+    /**
+     * What an https tool does.
+     */
+    description: string;
+    /**
+     * https or mcp.
+     */
+    kind: "https" | "mcp";
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * A JSON Schema of type object: what the tool takes.
+     */
+    parameters?: {
+        [key: string]: unknown;
+    };
+    /**
+     * The secret an https tool's calls are signed with (the Palbase-Signature header: t=<unix>,v1=<hex HMAC-SHA256 of "t.body">), said once: when the endpoint is put. Putting it again gives a new one.
+     */
+    signing_secret?: string;
+    /**
+     * When it was last put.
+     */
+    updated_at: string;
+    /**
+     * Its address.
+     */
+    url: string;
+};
+/**
+ * The project's endpoints.
+ */
+export type EndpointList = {
+    /**
+     * By name.
+     */
+    endpoints: Endpoint[];
+};
+/**
+ * An endpoint to put.
+ */
+export type EndpointRequest = {
+    /**
+     * Every call waits for a person's yes.
+     */
+    approval?: boolean;
+    /**
+     * What an https tool does (an MCP server says its own).
+     */
+    description?: string;
+    /**
+     * https (a tool at that address) or mcp (an MCP server: streamable HTTP).
+     */
+    kind: "https" | "mcp";
+    /**
+     * A JSON Schema of type object: what the tool takes.
+     */
+    parameters?: {
+        [key: string]: unknown;
+    };
+    /**
+     * An https:// address on the public internet.
+     */
+    url: string;
+};
 export type ErrorResponse = {
     /**
      * Machine-readable error code (snake_case)
@@ -246,6 +528,53 @@ export type ImageUsage = ({
      */
     output_tokens: number;
 }) | null;
+/**
+ * A picture a question is about: a file of the project's storage (bucket and path), read by the model through a URL signed for the while it is answered, or an https address the model reads it from. Nothing of it is kept by the module.
+ */
+export type InputImage = {
+    /**
+     * The project's storage bucket the picture is in (with path).
+     */
+    bucket?: string;
+    /**
+     * The picture's path in the bucket.
+     */
+    path?: string;
+    /**
+     * An https address the model reads the picture from (2048 characters at most), instead of bucket and path.
+     */
+    url?: string;
+};
+/**
+ * A user in a chat.
+ */
+export type Member = {
+    /**
+     * How the agent and the others are told who wrote.
+     */
+    name: string;
+    /**
+     * The owner deletes the chat.
+     */
+    owner: boolean;
+    /**
+     * The user's id.
+     */
+    user_id: string;
+};
+/**
+ * A user to put in a chat.
+ */
+export type MemberRequest = {
+    /**
+     * Their name in it.
+     */
+    name?: string;
+    /**
+     * Whether they own it.
+     */
+    owner?: boolean;
+};
 /**
  * One turn of the conversation so far.
  */
@@ -259,6 +588,40 @@ export type Message = {
      */
     role: "user" | "assistant";
 };
+/**
+ * A page of a chat's messages, the newest first.
+ */
+export type MessagePage = {
+    /**
+     * The messages.
+     */
+    messages: ChatMessage[];
+    /**
+     * Pages on (cursor=); absent on the last page.
+     */
+    next_cursor?: string;
+};
+/**
+ * A message for a chat.
+ */
+export type MessageRequest = {
+    /**
+     * The member the server writes as (the server's alone).
+     */
+    as?: string;
+    /**
+     * The writer's own id for it: sent again — a retry, a second tab — it is the same message, delivered once.
+     */
+    client_id: string;
+    /**
+     * While the agent works on a turn: next gives it the message at its next step (the default), now cuts the step it is in. When no turn runs, a message starts one.
+     */
+    delivery?: "next" | "now";
+    /**
+     * The message (64 KiB at most).
+     */
+    text: string;
+};
 /**
  * What a project may name.
  */
@@ -276,6 +639,23 @@ export type Models = {
      */
     text: TextModel[];
 };
+/**
+ * A user to put in a chat as it starts.
+ */
+export type NewMember = {
+    /**
+     * How the agent and the others are told who wrote.
+     */
+    name?: string;
+    /**
+     * Whether they own it.
+     */
+    owner?: boolean;
+    /**
+     * The user's id.
+     */
+    user_id: string;
+};
 /**
  * A provider the project connected with its own key.
  */
@@ -392,6 +772,10 @@ export type ResponseRequest = {
      * Answer at once; the response's end is the event ai.response.completed or ai.response.failed.
      */
     background?: boolean;
+    /**
+     * Pictures the question is about, shown to the model with it (4 at most).
+     */
+    images?: InputImage[];
     /**
      * The question (2 MB at most). Give this, or messages.
      */
@@ -400,6 +784,10 @@ export type ResponseRequest = {
      * How the model should answer (256 KB at most).
      */
     instructions?: string;
+    /**
+     * How many tool calls the answer makes at most: past it the model is told it has no tools left and answers.
+     */
+    max_tool_calls?: number;
     /**
      * The conversation so far instead of one question (500 turns at most); its last turn is the user's.
      */
@@ -428,6 +816,10 @@ export type ResponseRequest = {
      * Answer with the response's live view (text/event-stream).
      */
     stream?: boolean;
+    /**
+     * What the model may call to answer: the project's backend's functions, its HTTPS tools and MCP servers (an app's own tools are a chat's).
+     */
+    tools?: ToolRef[];
 };
 /**
  * What a response used.
@@ -442,6 +834,108 @@ export type ResponseUsage = {
      */
     output_tokens: number;
 };
+/**
+ * A message a subagent was given.
+ */
+export type RunMessageAccepted = {
+    /**
+     * The writer's id for it.
+     */
+    client_id: string;
+    /**
+     * The subagent's run.
+     */
+    run_id: string;
+};
+/**
+ * A message for a subagent at work.
+ */
+export type RunMessageRequest = {
+    /**
+     * The writer's id for it.
+     */
+    client_id: string;
+    /**
+     * The message.
+     */
+    text: string;
+};
+/**
+ * What the project allows its chats.
+ */
+export type Settings = {
+    /**
+     * Whether the app's users talk to the project's agents with their own session: start a chat with a named agent, write to the chats they are in.
+     */
+    clients: boolean;
+    /**
+     * How much it keeps now.
+     */
+    history_bytes: number;
+    /**
+     * How much chat history the project keeps; a message past it is refused (history_full) until chats are deleted.
+     */
+    history_limit_bytes: number;
+    /**
+     * How many messages one user sends a minute (default 20).
+     */
+    user_messages_per_minute: number;
+};
+/**
+ * A change of what the project allows its chats; a field left out is left as it is.
+ */
+export type SettingsRequest = {
+    /**
+     * Let the app's users talk to the project's agents themselves.
+     */
+    clients?: boolean;
+    /**
+     * At most the plan's (500 MiB): a project may keep less, not more.
+     */
+    history_limit_bytes?: number;
+    /**
+     * 1 to 600.
+     */
+    user_messages_per_minute?: number;
+};
+/**
+ * The turn a stop stopped.
+ */
+export type StopResult = {
+    /**
+     * Its response; null: none was running.
+     */
+    stopped: string | null;
+};
+/**
+ * An agent the agent may hand part of a turn to.
+ */
+export type Subagent = {
+    /**
+     * What it is for: the agent reads it to choose.
+     */
+    description: string;
+    /**
+     * Its instructions.
+     */
+    instructions?: string;
+    /**
+     * Its model: a role (fast, default, strong) or a catalogue model.
+     */
+    model?: string;
+    /**
+     * Its name, unique among the subagents.
+     */
+    name: string;
+    /**
+     * The turn fails if this subagent's part fails.
+     */
+    required?: boolean;
+    /**
+     * Its tools.
+     */
+    tools?: ToolRef[];
+};
 /**
  * A role a text model is chosen by.
  */
@@ -455,6 +949,84 @@ export type TextModel = {
      */
     role: string;
 };
+/**
+ * A part of what a tool returned.
+ */
+export type ToolContent = {
+    /**
+     * An image as base64 (5 MiB at most).
+     */
+    data?: string;
+    /**
+     * An image's type: image/png, image/jpeg, image/webp or image/gif.
+     */
+    media_type?: string;
+    /**
+     * The text.
+     */
+    text?: string;
+    /**
+     * text or image.
+     */
+    type: "text" | "image";
+};
+/**
+ * What an app's tool returned (1 MiB of text and 4 images at most).
+ */
+export type ToolOutput = {
+    /**
+     * The tool failed; the output says why.
+     */
+    is_error?: boolean;
+    /**
+     * Text and images: the agent is shown both.
+     */
+    output: ToolContent[];
+};
+/**
+ * An app's answer the turn was given.
+ */
+export type ToolOutputAccepted = {
+    /**
+     * The tool call.
+     */
+    call_id: string;
+};
+/**
+ * A tool an agent is given, by where it runs: backend (a function of the project's backend, the framework's ai.tool, on its machine), https (an endpoint the project put), mcp (an MCP server the project put: its tools, or the ones named in only), or client (code of the app the chat is open in: the turn waits for its answer).
+ */
+export type ToolRef = {
+    /**
+     * A call waits for a person's yes (a member of the chat, or the server); one denied is told to the agent with the reason.
+     */
+    approval?: boolean;
+    /**
+     * What it does: the agent reads it to choose (backend and client tools; an endpoint says its own).
+     */
+    description?: string;
+    /**
+     * The machine a backend tool runs on (default backend).
+     */
+    machine?: string;
+    /**
+     * The tool (backend, client), or the endpoint's name (https, mcp).
+     */
+    name: string;
+    /**
+     * The MCP server's tools to offer (none: all).
+     */
+    only?: string[];
+    /**
+     * A JSON Schema of type object: what the tool takes.
+     */
+    parameters?: {
+        [key: string]: unknown;
+    };
+    /**
+     * backend, https, mcp or client.
+     */
+    source: "backend" | "https" | "mcp" | "client";
+};
 /**
  * A page of uses.
  */
@@ -530,6 +1102,197 @@ export interface Events {
 }
 /** Palbase ai */
 export declare function client(t: Transport): {
+    /**
+     * The project's named agents
+     *
+     * Every agent the project named, by name.
+     */
+    listAgents(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, AgentList>>;
+    /**
+     * Name an agent
+     *
+     * An agent a chat started from the app — or by name from the server — talks to: its definition, or the backend machine that defines it at each turn.
+     */
+    putAgent(input: {
+        path: {
+            name: string;
+        };
+        body: AgentDefinition; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Agent>>;
+    /**
+     * Forget an agent
+     *
+     * Its chats stay; a message to one of them is refused (agent_not_found) until an agent of that name is put again.
+     */
+    deleteAgent(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>>;
+    /**
+     * The chats
+     *
+     * The server's: every chat, or a member's (member=); a user's: the chats they are in. The newest first, 100 at most.
+     */
+    listChats(input?: {
+        query?: {
+            member?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, ChatList>>;
+    /**
+     * Start a chat
+     *
+     * The server starts a chat with a named agent or a definition of its own, and names its members; a signed-in user (when the project lets them) starts one with a named agent, as its owner.
+     */
+    createChat(input: {
+        body: ChatRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, Chat>>;
+    /**
+     * A chat
+     *
+     * A chat, with its members. A user reads only a chat they are in; any other is not found.
+     */
+    getChat(input: {
+        path: {
+            chat_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Chat>>;
+    /**
+     * Delete a chat
+     *
+     * Its owner or the server deletes it: a turn still running is stopped, and its history no longer counts.
+     */
+    deleteChat(input: {
+        path: {
+            chat_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
+    /**
+     * Decide a tool call
+     *
+     * A tool call that waits for a person's yes: approved it is made; denied, the agent is told, with the reason, and goes on.
+     */
+    decideChatApproval(input: {
+        path: {
+            chat_id: string; /** The approval (a tool event's approval_id). */
+            approval_id: string;
+        };
+        body: DecisionRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Decision>>;
+    /**
+     * Put a user in a chat
+     *
+     * Who is in a chat is the server's to say.
+     */
+    putChatMember(input: {
+        path: {
+            chat_id: string; /** The user's id. */
+            user_id: string;
+        };
+        body: MemberRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Chat>>;
+    /**
+     * Take a user out of a chat
+     *
+     * The server takes anyone out; a user takes themselves out.
+     */
+    deleteChatMember(input: {
+        path: {
+            chat_id: string; /** The user's id. */
+            user_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
+    /**
+     * A chat's messages
+     *
+     * What its members (and the server) wrote, the newest first.
+     */
+    listChatMessages(input: {
+        path: {
+            chat_id: string;
+        };
+        query?: {
+            limit?: number; /** next_cursor of the page before. */
+            cursor?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, MessagePage>>;
+    /**
+     * Write to a chat
+     *
+     * A message for the agent: a turn of its own when none runs; while one does, at its next step (next) or cutting the step it is in (now). The same client_id again is the same message. A user sends user_messages_per_minute a minute (429 too_many_messages); past the history the project keeps a message is refused (409 history_full).
+     */
+    sendChatMessage(input: {
+        path: {
+            chat_id: string;
+        };
+        body: MessageRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, ChatMessage> | Reply<202, ChatMessage>>;
+    /**
+     * Write to a subagent at work
+     *
+     * A message for one of the agent's subagents, at its next step.
+     */
+    sendSubagentMessage(input: {
+        path: {
+            chat_id: string; /** The subagent's run (an agent event's run_id). */
+            run_id: string;
+        };
+        body: RunMessageRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<202, RunMessageAccepted>>;
+    /**
+     * Stop the agent
+     *
+     * Stops the turn it is working on: what it wrote stays; a message after starts the next turn.
+     */
+    stopChat(input: {
+        path: {
+            chat_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, StopResult>>;
+    /**
+     * Follow a chat
+     *
+     * What happens in the chat as typed parts, as it happens.
+     */
+    followChat(input: {
+        path: {
+            chat_id: string;
+        };
+        query?: {
+            after?: number; /** The response whose answer the reader was reading. */
+            response?: string; /** The bytes of that answer the reader holds. */
+            offset?: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Response>>;
+    /**
+     * Answer an app's tool call
+     *
+     * The answer of a client tool's call, made by the app's code: the turn waiting for it goes on. The first answer is the one.
+     */
+    answerChatToolCall(input: {
+        path: {
+            chat_id: string; /** The tool call (a tool event's call_id). */
+            call_id: string;
+        };
+        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>>;
     /**
      * Turn texts into vectors
      *
@@ -539,6 +1302,37 @@ export declare function client(t: Transport): {
         body: EmbeddingsRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, Embeddings>>;
+    /**
+     * The project's tool endpoints
+     *
+     * Its HTTPS tools and MCP servers, by name (their secrets are not said again).
+     */
+    listEndpoints(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, EndpointList>>;
+    /**
+     * Put a tool endpoint
+     *
+     * A tool at an HTTPS address of the project's — called with a signed POST {tool, call_id, input, context} and answered {output, is_error} or plain text — or an MCP server, whose tools an agent may use. The answer says an https tool's signing secret, once.
+     */
+    putEndpoint(input: {
+        path: {
+            name: string;
+        };
+        body: EndpointRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Endpoint>>;
+    /**
+     * Forget a tool endpoint
+     *
+     * An agent naming it can no longer start a turn until it is put again.
+     */
+    deleteEndpoint(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>>;
     /**
      * Make pictures
      *
@@ -661,6 +1455,23 @@ export declare function client(t: Transport): {
         }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, Response>>;
+    /**
+     * What the project allows its chats
+     *
+     * Whether its app's users talk to its agents themselves, how many messages one sends a minute, and how much history it keeps.
+     */
+    getSettings(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Settings>>;
+    /**
+     * Change what the project allows its chats
+     *
+     * A field left out is left as it is. The history kept may be lowered, not raised past the plan's.
+     */
+    putSettings(input: {
+        body: SettingsRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Settings>>;
     /**
      * What the project's use of models cost
      *