palbase 0.13.1 → 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
      *