palbase 0.13.2 → 0.14.0

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

@@ -1,20 +1,58 @@
 import { type Reply, type Transport } from '../transport.js';
 /**
- * A named agent of the project.
+ * An agent of the project's. One its backend defines (source code) is its build's: it is changed in the code, and here is what its last turn was defined as. One the project keeps (source platform) is changed as a draft, and its chats talk to the version published.
  */
 export type Agent = {
-    definition: AgentDefinition;
+    /**
+     * Code: when its last turn was defined (absent: none yet).
+     */
+    defined_at?: string;
+    definition?: AgentDefinition;
+    /**
+     * What it is for: the published version's (a draft's, before one is), or a code agent's last turn's.
+     */
+    description?: string;
+    draft?: AgentDefinition;
+    /**
+     * Code: the instructions its last turn was told are not shown to this caller — a member of the project's team: a backend writes them from the turn's context, which may carry its user's words.
+     */
+    instructions_hidden?: boolean;
+    /**
+     * Code: the backend machine whose build defines it.
+     */
+    machine?: string;
     /**
      * Its name.
      */
     name: string;
+    published?: AgentDefinition;
     /**
-     * When it was last put.
+     * Platform: the version published; null: none yet, and a chat started by its name is refused (agent_not_published).
      */
-    updated_at: string;
+    published_version?: number | null;
+    /**
+     * Platform: the draft's revision, which a change to it names (PUT …?revision=) so that a change made meanwhile is not lost.
+     */
+    revision?: number;
+    /**
+     * code: its backend's build defines it; platform: the project keeps it (Studio, the CLI, the API).
+     */
+    source: "code" | "platform";
+    /**
+     * Platform: the draft is not the version published.
+     */
+    unpublished_changes?: boolean;
+    /**
+     * Platform: when its draft was last saved.
+     */
+    updated_at?: string;
+    /**
+     * Platform: who saved it last — a developer's id, or server for the secret key's.
+     */
+    updated_by?: 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.
+ * What an agent is: its instructions, model, tools and subagents, and the shape of its one-shot answers — or, for one the project's backend defined at every turn's start before its build's contract said so, the machine to ask (backend), alone.
  */
 export type AgentDefinition = {
     /**
@@ -25,6 +63,10 @@ export type AgentDefinition = {
      * The window, in tokens, the turn works in (the model's standard one unless said; more is billed as its provider bills it — GET /ai/models, context_window and max_input_tokens).
      */
     context_window?: number;
+    /**
+     * What it is for, in a sentence or two: the people who pick an agent read it, and so does the agent a subagent works for.
+     */
+    description?: string;
     /**
      * How hard the model thinks: none, minimal, low, medium, high, xhigh, max — which rungs a model takes is its catalogue entry's (GET /ai/models, efforts). Left out: the platform's.
      */
@@ -45,6 +87,12 @@ export type AgentDefinition = {
      * A role (fast, default, strong) or a catalogue model.
      */
     model?: string;
+    /**
+     * A JSON Schema a one-shot answer of the agent's is a document of (POST /ai/responses naming the agent): the same keywords a response's schema takes. A chat's turns answer in text.
+     */
+    output?: {
+        [key: string]: unknown;
+    };
     /**
      * Its subagents (16 at most).
      */
@@ -59,14 +107,94 @@ export type AgentDefinition = {
     tools?: ToolRef[];
 };
 /**
- * The project's named agents.
+ * An agent described: what it is for, who it talks to, what it may do.
+ */
+export type AgentDraftRequest = {
+    /**
+     * The agent, in words.
+     */
+    description: string;
+    /**
+     * The name it is to have (left out: one is suggested).
+     */
+    name?: string;
+};
+/**
+ * The project's agents.
  */
 export type AgentList = {
     /**
-     * By name.
+     * By name: its backend's (in the builds that serve) and those it keeps. A name two machines' builds define is neither's, and is not here.
      */
     agents: Agent[];
 };
+/**
+ * What to publish: the draft as it is.
+ */
+export type AgentPublish = {
+    /**
+     * The draft's revision as it was looked at: when another was saved since, the publish is refused (draft_changed). Left out: the draft as it is now.
+     */
+    revision?: number;
+};
+/**
+ * The version its chats are to talk to again.
+ */
+export type AgentRollback = {
+    /**
+     * The draft's revision as it was looked at: going back drops a change of the draft not published, and one saved since is not dropped unseen (draft_changed).
+     */
+    revision?: number;
+    /**
+     * A version it had.
+     */
+    version: number;
+};
+/**
+ * An agent written from a description: kept nowhere until it is put (PUT /ai/agents/{name}).
+ */
+export type AgentSuggestion = {
+    definition: AgentDefinition;
+    /**
+     * Its name: the one asked for, or one suggested that no agent of the project has.
+     */
+    name: string;
+};
+/**
+ * A published version of an agent the project keeps: it never changes. It goes with the agent; one made again under its name numbers its versions after it, and a chat on a gone one is told so (agent_version_not_found).
+ */
+export type AgentVersion = {
+    definition: AgentDefinition;
+    /**
+     * When it was published.
+     */
+    published_at: string;
+    /**
+     * Who published it — a developer's id, or server.
+     */
+    published_by: string;
+    /**
+     * Its number: 1, then each publish one more.
+     */
+    version: number;
+};
+/**
+ * An agent's versions, newest first.
+ */
+export type AgentVersionList = {
+    /**
+     * The cursor of the next page; absent on the last.
+     */
+    next_cursor?: string;
+    /**
+     * The version its chats talk to; null: none.
+     */
+    published_version: number | null;
+    /**
+     * Newest first.
+     */
+    versions: AgentVersion[];
+};
 /**
  * A conversation of the project's users with one of its agents.
  */
@@ -75,6 +203,10 @@ export type Chat = {
      * The agent it talks to.
      */
     agent: string;
+    /**
+     * The version of the agent it stays on (agent@N); absent: the published one, at each turn.
+     */
+    agent_version?: number;
     /**
      * When it was started.
      */
@@ -347,7 +479,7 @@ export type ChatRepo = {
  */
 export type ChatRequest = {
     /**
-     * The agent it talks to: a named agent of the project's — or, with a definition of the chat's own, the server's name for it.
+     * The agent it talks to: one of the project's by name — its backend's, or one it keeps, whose published version each turn takes, or name@N to stay on version N — or, with a definition of the chat's own, the server's name for it.
      */
     agent: string;
     definition?: AgentDefinition;
@@ -1501,6 +1633,10 @@ export type ResponseEventError = {
  * A question for a model: input, or messages.
  */
 export type ResponseRequest = {
+    /**
+     * An agent of the project's — its name (the version published), or name@N (version N): its instructions, model, tools and output shape the answer. A field this request names replaces the agent's for this answer alone; the agent is not changed.
+     */
+    agent?: string;
     /**
      * Answer at once; the response's end is the event ai.response.completed or ai.response.failed.
      */
@@ -1728,6 +1864,37 @@ export type TextModel = {
      */
     role: string;
 };
+/**
+ * A tool an agent of the project's may be given, as a ToolRef names it.
+ */
+export type Tool = {
+    /**
+     * Every call waits for a person's yes.
+     */
+    approval: boolean;
+    /**
+     * What it does.
+     */
+    description: string;
+    /**
+     * backend, client: the machine whose build declares it.
+     */
+    machine?: string;
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * What it takes, as a JSON Schema (an MCP server says its own when it is called).
+     */
+    parameters?: {
+        [key: string]: unknown;
+    };
+    /**
+     * backend: the backend's function; client: the app answers it; https, mcp: an endpoint of the project's; platform: the platform's.
+     */
+    source: "backend" | "client" | "https" | "mcp" | "platform";
+};
 /**
  * A part of what a tool returned.
  */
@@ -1749,6 +1916,15 @@ export type ToolContent = {
      */
     type: "text" | "image";
 };
+/**
+ * The tools the project's agents may be given.
+ */
+export type ToolList = {
+    /**
+     * The backend's (its builds that serve), the project's endpoints, then the platform's.
+     */
+    tools: Tool[];
+};
 /**
  * What an app's tool returned (1 MiB of text and 4 images at most).
  */
@@ -2406,29 +2582,52 @@ export interface Events {
 /** Palbase ai */
 export declare function client(t: Transport): {
     /**
-     * The project's named agents
+     * Write an agent from a description
      *
-     * Every agent the project named, by name.
+     * A definition written from a description: instructions, a model, the project's own tools that fit (named by their name: the agent follows the code), subagents and an output shape where the description calls for them. Nothing is kept: put it (PUT /ai/agents/{name}) to have it. It is a person's (a developer's session or token: 403 person_required for the secret key), the platform pays for it, and it is bounded (429 too_many_drafts): 20 an hour by a person in a project, 60 by its people, 40 by a person across their projects — and the platform's day (429 drafts_paused).
+     */
+    draftAgent(input: {
+        body: AgentDraftRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, AgentSuggestion>>;
+    /**
+     * The project's agents
+     *
+     * The agents the project keeps and its backend's — each one the build its machine serves defines (its contract's x-palbase-agents) — by name. A name the project keeps is that agent's, whatever a build declares.
      */
     listAgents(input?: {
         signal?: AbortSignal;
     }): Promise<Reply<200, AgentList>>;
     /**
-     * Name an agent
+     * An agent
+     *
+     * One the project keeps: its draft, the version published and its revision. One its backend defines: its machine, and what its last turn was defined as.
+     */
+    getAgent(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<200, Agent>>;
+    /**
+     * Save an agent's draft
      *
-     * An agent a chat the server starts by its name talks to: its definition, or the backend machine that defines it at each turn.
+     * Saves the draft of an agent the project keeps — a new one's first. What its chats talk to changes only once the draft is published. revision names the draft the change was made to: when another was saved since, it is refused (409 draft_changed) and nothing is lost; left out, the last save wins. A name its backend's build defines is refused (409 agent_defined_in_code): that agent is changed in the code. A definition of backend alone names the machine that defines the agent at each turn — the framework's agents before their build's contract said so — and is kept as it is, with no draft.
      */
     putAgent(input: {
         path: {
             name: string;
         };
+        query?: {
+            revision?: number;
+        };
         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.
+     * An agent the project keeps, its versions with it — an agent made again under its name numbers its versions after them, and a chat on one of them is told it is gone — or a backend's put the old way. Its chats stay; a message to one of them is refused (agent_not_found) until an agent of that name is there again. One its backend's build declares goes with the code (409 agent_defined_in_code).
      */
     deleteAgent(input: {
         path: {
@@ -2436,6 +2635,45 @@ 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>>;
+    /**
+     * Publish an agent's draft
+     *
+     * Makes the draft a version, the next number, and the one its chats talk to from their next turn on. A draft that is the version published is refused (409 nothing_to_publish); an agent keeps 1000 versions (409 too_many_versions).
+     */
+    publishAgent(input: {
+        path: {
+            name: string;
+        };
+        body: AgentPublish; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Agent>>;
+    /**
+     * Go back to a version
+     *
+     * Makes a version it had the one its chats talk to, and its draft that version: a change of the draft not published is dropped.
+     */
+    rollbackAgent(input: {
+        path: {
+            name: string;
+        };
+        body: AgentRollback; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Agent>>;
+    /**
+     * An agent's versions
+     *
+     * The versions an agent the project keeps was published as, newest first.
+     */
+    listAgentVersions(input: {
+        path: {
+            name: string;
+        };
+        query?: {
+            limit?: number; /** The next_cursor of the previous page. */
+            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, AgentVersionList>>;
     /**
      * The chats
      *
@@ -3074,6 +3312,14 @@ export declare function client(t: Transport): {
         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>>;
+    /**
+     * The tools an agent may be given
+     *
+     * The backend's tools (each one the build its machine serves declares: its contract's x-palbase-ai-tools), the project's endpoints, and the platform's.
+     */
+    listTools(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, ToolList>>;
     /**
      * What the project's use of models cost
      *

package/dist/chunks/2DBSGJ7Z.js

@@ -1,2 +0,0 @@
-/*! palbase 0.13.2 — Palbase SDK License (see LICENSE) */
-import{a as d,b as u}from"./7ZSVOQFN.js";var p={too_many_chats:()=>"this user is in as many chats as they may be (100): delete or leave one before starting another",too_many_endpoints:()=>"the project holds as many tool endpoints as it may (32): delete one (ai.endpoints.delete) before putting another",too_many_messages:t=>`this user has sent as many messages this minute as the project allows${t.retryAfter!==void 0?`: write again in ${t.retryAfter} s`:""}`,history_full:()=>"the project keeps as much chat history as it may: delete chats to write again",not_your_turn:()=>"this turn is another member's: only the member who started it (or the project's server) answers its tools and decides its approvals",not_a_member:()=>"the member the server acts as (as) is not in this chat: put them in it first (chats.members.put), or act as the server",goal_lapsed:()=>"the goal was set as a member who no longer stands where they stood then (out of the chat, or the chat no longer theirs alone): it is not resumed \u2014 clear it, or set another for the chat as it is now",goal_achieved:()=>"the goal is achieved: set a new one (chats.goal.set) to work on",turn_running:()=>"the chat's agent is at work on a turn: fork it once the turn has ended, or stop it first (chats.stop)",fork_too_large:()=>"what came before that message is more than a fork begins with (512 KiB): fork it before an earlier message",too_many_voices:t=>`this user has started as many voices this hour as the project allows (5)${t.retryAfter!==void 0?`: start again in ${t.retryAfter} s`:""}`,voice_active:()=>"another member's voice is live in this chat \u2014 one voice talks in a chat at a time: wait for it to end",not_your_voice:()=>"this voice is another member's: only its member \u2014 or the server as itself \u2014 reads, tells and closes it",voice_closed:()=>"the voice has ended: start a new one (chats.voice.start)",no_workspace:()=>"this chat works in no workspace, and files go into one: start the chat with a workspace, or send pictures as images",attachment_not_found:()=>"a picture or a file given is not one its writer may attach: a file of the project's storage \u2014 for a member, their own or a public bucket's",attachment_too_large:()=>"an attachment is past its bound: 5 MiB a picture, 15 MiB a file",attachment_changed:()=>"a file changed while it was being attached: send the message again",unsupported_image:()=>"a picture is not png, jpeg, webp or gif by its bytes: send it as a file",image_not_found:()=>"a picture given is not a file of the project's storage: upload it first (storage.from(bucket).upload(path, file)) and give that bucket and path",storage_unavailable:t=>`the project's storage did not answer when the model was to read a picture${t.retryAfter!==void 0?`: try again in ${t.retryAfter} s`:"; try again shortly"}`},g=new WeakSet;function c(t){if(!(t instanceof u)||g.has(t))return t;let r=p[t.code];if(!r)return t;let s=new u({op:t.op,status:t.status,code:t.code,message:`${r(t)} (${t.op}: ${t.status} ${t.code})`,requestId:t.requestId,retryAfter:t.retryAfter,body:t.body,cause:t});return g.add(s),s}function h(t){return t.catch(r=>{throw c(r)})}function _(t){if(typeof t!="object"||t===null)return;let r=t,s=r.data;if(typeof r.type!="string"||typeof s!="object"||s===null||Array.isArray(s))return;let e=d(s),i=typeof r.id=="number"&&Number.isSafeInteger(r.id)?r.id:0;switch(r.type){case"message":return typeof e.client_id=="string"?{type:"message",seq:i,message:e}:void 0;case"turn":{if(typeof e.response_id!="string"||typeof e.status!="string")return;let n={...e,type:"turn",seq:i};return n.waiting??=null,n.error??=null,n}case"text":{let n=e.offset;return typeof e.response_id!="string"||typeof n!="number"||!Number.isInteger(n)||n<0?void 0:{type:"text",response_id:e.response_id,offset:n,text:typeof e.text=="string"?e.text:""}}case"reset":{let n=e.offset;return typeof e.response_id!="string"||typeof n!="number"||!Number.isInteger(n)||n<0?void 0:{type:"reset",response_id:e.response_id,offset:n}}case"tool":{if(typeof e.call_id!="string"||typeof e.response_id!="string")return;let n=e.omitted_bytes;return{...e,type:"tool",seq:i,omittedBytes:typeof n=="number"&&Number.isSafeInteger(n)&&n>0?n:0,outputTruncated:e.output_truncated===!0}}case"agent":return typeof e.parent_response_id=="string"?{...e,type:"agent",seq:i}:void 0;case"thinking":{if(typeof e.response_id!="string")return;let n=typeof e.run_id=="string"?e.run_id:"";return e.unavailable===!0?{type:"thinking",seq:i,response_id:e.response_id,run_id:n,text:"",unavailable:!0,model:typeof e.model=="string"?e.model:"",reason:typeof e.reason=="string"?e.reason:""}:typeof e.text!="string"?void 0:{type:"thinking",seq:i,response_id:e.response_id,run_id:n,...typeof e.step_id=="string"&&e.step_id!==""?{step_id:e.step_id}:{},text:e.text}}case"goal":{if(typeof e.goal_id!="string"||typeof e.kind!="string")return;let{seq:n,...o}=e;return{...o,type:"goal",seq:i,...typeof n=="number"?{turn:n}:{}}}case"history":{if(!Array.isArray(e.items)||typeof e.part!="number"||!Number.isInteger(e.part)||e.part<0)return;let n=e.items.filter(a=>typeof a=="object"&&a!==null&&(a.role==="user"||a.role==="assistant")&&typeof a.text=="string"),o=e.forked_from;return{type:"history",forked_from:o&&typeof o.chat_id=="string"?o:null,part:e.part,parts:typeof e.parts=="number"?e.parts:e.part+1,items:n}}case"voice":return typeof e.voice_id!="string"||e.voice_id===""||typeof e.status!="string"?void 0:{...e,type:"voice",seq:i,user_id:typeof e.user_id=="string"?e.user_id:null};case"transcript":return typeof e.id!="string"||e.id===""||typeof e.text!="string"?void 0:{type:"transcript",seq:i,id:e.id,voice_id:typeof e.voice_id=="string"?e.voice_id:"",role:typeof e.role=="string"?e.role:"",user_id:typeof e.user_id=="string"?e.user_id:null,author_name:typeof e.author_name=="string"?e.author_name:"",text:e.text,final:e.final!==!1,created_at:typeof e.created_at=="string"?e.created_at:""};default:return}}function b(t){let r=0;for(let s=0;s<t.length;s++){let e=t.charCodeAt(s);e<128?r+=1:e<2048?r+=2:e>=55296&&e<=56319&&s+1<t.length&&(t.charCodeAt(s+1)&64512)===56320?(r+=4,s++):r+=3}return r}function l(t,r){if(r<=0)return 0;let s=0;for(let e=0;e<t.length;e++){let i=t.charCodeAt(e),n=3,o=1;if(i<128?n=1:i<2048?n=2:i>=55296&&i<=56319&&e+1<t.length&&(t.charCodeAt(e+1)&64512)===56320&&(n=4,o=2),s+=n,s>=r)return e+o;e+=o-1}return t.length}function v(t,r){return t.slice(l(t,r))}export{h as a,_ as b,b as c,l as d,v as e};