palbase 0.43.1 → 0.44.0

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

@@ -73,7 +73,7 @@ export type Agent = {
     updated_by?: string;
 };
 /**
- * What an agent is: its instructions, model, tools and subagents, and the shape of its one-shot answers.
+ * What an agent is: its instructions, model, tools and subagents, its own variables and setup script, and the shape of its one-shot answers.
  */
 export type AgentDefinition = {
     advisor?: Advisor;
@@ -89,6 +89,12 @@ export type AgentDefinition = {
      * 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.
      */
     effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    /**
+     * The agent's own variables, name → value (names: upper-case letters, digits and _, not PALAI_…; 64 at most; a value 32 KiB at most): every command of its sessions has them, on every pool, beside the project's (PUT /ai/env/{key}), masked in a transcript. A value is never answered again: a definition read back says each name with an empty value, and a name written with an empty value keeps the value it has.
+     */
+    env?: {
+        [key: string]: string;
+    };
     /**
      * Its instructions.
      */
@@ -111,6 +117,10 @@ export type AgentDefinition = {
     output?: {
         [key: string]: unknown;
     };
+    /**
+     * A shell script each of its sessions runs once at its start, before the agent's first command, on every pool (64 KiB at most).
+     */
+    setup?: string;
     /**
      * Its subagents (16 at most).
      */
@@ -252,6 +262,10 @@ export type Chat = {
     metadata: {
         [key: string]: string;
     };
+    /**
+     * The project's runner pool its workspace runs on, by its id; absent: the platform's own Linux machines. A fork runs on its chat's.
+     */
+    pool?: string;
     /**
      * Its title.
      */
@@ -511,6 +525,10 @@ export type ChatRequest = {
     metadata?: {
         [key: string]: string;
     };
+    /**
+     * The project's runner pool its workspace runs on (GET /ai/pools), by its id or its name; one the project has not: 400. None: the platform's own Linux machines. A chat that names one works in a workspace.
+     */
+    pool?: string;
     /**
      * Its title (256 bytes at most).
      */
@@ -732,6 +750,10 @@ export type Endpoint = {
      * Its address.
      */
     url: string;
+    /**
+     * The endpoint — an MCP server or an HTTPS tool — is the project's own, reading or writing a chat's workspace: each call tells it the tree it is made at (an MCP server in its _meta palbase/workspace, an HTTPS tool in its context.workspace: the chat's id and the tree), and the tree its answer names is waited for. False: it is told nothing of the chat's workspace (an HTTPS tool is told the turn's chat_id as ever). The project's backend's tools are told the workspace always.
+     */
+    workspace: boolean;
 };
 /**
  * The project's endpoints.
@@ -768,6 +790,49 @@ export type EndpointRequest = {
      * An https:// address on the public internet.
      */
     url: string;
+    /**
+     * True for an endpoint of the project's own — an MCP server or an HTTPS tool — that reads or writes a chat's workspace: each call tells it the tree it is made at (an MCP server in its _meta palbase/workspace, an HTTPS tool in its context.workspace: the chat's id, manifest_id and seq), and the tree its answer names (an MCP result's _meta palbase/workspace_tree, an HTTPS answer's workspace_tree) is waited for. False (the default, which every endpoint put before an HTTPS tool took the setting has): any server's address — a third party's API or MCP server — told nothing of the chat's workspace, a tree it answers ignored. The project's backend's tools are told the workspace always.
+     */
+    workspace?: boolean;
+};
+/**
+ * The project's variables.
+ */
+export type EnvList = {
+    /**
+     * Their names, sorted.
+     */
+    variables: EnvVar[];
+};
+/**
+ * A variable's value.
+ */
+export type EnvRequest = {
+    /**
+     * Whether it is a secret (the default): said so in the list. Every value is masked in a transcript either way.
+     */
+    secret?: boolean;
+    /**
+     * Its value: 1 byte to 32 KiB, no NUL. Sealed, never answered, never logged.
+     */
+    value: string;
+};
+/**
+ * One of the project's variables: its name, never its value.
+ */
+export type EnvVar = {
+    /**
+     * Its name.
+     */
+    key: string;
+    /**
+     * Whether it is a secret.
+     */
+    secret: boolean;
+    /**
+     * When it was last set.
+     */
+    updated_at: string;
 };
 export type ErrorResponse = {
     /**
@@ -1430,6 +1495,238 @@ export type NewMember = {
      */
     user_id: string;
 };
+/**
+ * A runner pool of the project's.
+ */
+export type Pool = {
+    /**
+     * Its machines' architecture: amd64 or arm64.
+     */
+    arch: string;
+    /**
+     * How many sessions its machines take at once (listed pools).
+     */
+    capacity_total?: number;
+    /**
+     * How many they hold now (listed pools).
+     */
+    capacity_used?: number;
+    /**
+     * When it was made.
+     */
+    created_at?: string;
+    /**
+     * Its id.
+     */
+    id: string;
+    /**
+     * How many machines it has (listed pools).
+     */
+    machines?: number;
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * Its machines' operating system: linux or macos.
+     */
+    os: string;
+    /**
+     * How many sessions wait for a place on the pool's machines: parked until one of them has room (listed pools).
+     */
+    waiting?: number;
+};
+/**
+ * A pool's single-use enrolment key.
+ */
+export type PoolKey = {
+    /**
+     * When it was minted.
+     */
+    created_at?: string;
+    enroll?: PoolKeyEnroll;
+    /**
+     * The enrolment address (enroll.url), said with the key as it is minted: `palai enroll --url`.
+     */
+    enroll_url?: string;
+    /**
+     * When it can no longer be used.
+     */
+    expires_at?: string;
+    /**
+     * Its id: revoke it by it.
+     */
+    id: string;
+    /**
+     * The key, said once — as it is minted, never again: saved to a file on the machine, `palai enroll --url <enroll_url> --key-file <file> --capacity <n>`.
+     */
+    key?: string;
+    /**
+     * What it is for.
+     */
+    label?: string;
+    /**
+     * When a machine last enrolled with it.
+     */
+    last_used_at?: string;
+    /**
+     * When it was revoked.
+     */
+    revoked_at?: string;
+};
+/**
+ * Where a machine enrols with it, said with the key as it is minted (never in a list): `palai enroll --url <url> --key-file <file>`, with `--server-name <server_name>` when the door's certificate names another host, and `--ca-file <file>` holding ca_certificate when the door's certificate is not publicly trusted.
+ */
+export type PoolKeyEnroll = {
+    /**
+     * The CA the door's certificate is signed by (PEM), when it is not publicly trusted: saved to a file, `palai enroll --ca-file`.
+     */
+    ca_certificate?: string;
+    /**
+     * The name the door's certificate carries, when it differs from the address's host: `palai enroll --server-name`.
+     */
+    server_name?: string;
+    /**
+     * The enrolment address: `palai enroll --url`.
+     */
+    url: string;
+};
+/**
+ * A pool's enrolment keys.
+ */
+export type PoolKeyList = {
+    /**
+     * The keys, none said.
+     */
+    keys: PoolKey[];
+};
+/**
+ * An enrolment key to mint.
+ */
+export type PoolKeyRequest = {
+    /**
+     * What it is for — the machine it enrols: 128 bytes of UTF-8 at most (maxLength counts characters, so a label of fewer may still be too long), with no control character, no format character (a bidi override or isolate, a zero-width space or joiner, a byte order mark) and no line or paragraph separator — a label is shown as it was written.
+     */
+    label?: string;
+};
+/**
+ * The project's runner pools.
+ */
+export type PoolList = {
+    /**
+     * The pools.
+     */
+    pools: Pool[];
+};
+/**
+ * A machine of a pool.
+ */
+export type PoolMachine = {
+    /**
+     * Its architecture.
+     */
+    arch?: string;
+    /**
+     * How many sessions it takes at once (--capacity).
+     */
+    capacity: number;
+    /**
+     * Its id: cordon, resume or delete it by it.
+     */
+    id: string;
+    /**
+     * Since when it holds none (null: it holds one).
+     */
+    idle_since?: string | null;
+    /**
+     * Its label, as it enrolled.
+     */
+    label?: string;
+    /**
+     * When it was last heard from.
+     */
+    last_seen_at?: string | null;
+    /**
+     * Its operating system.
+     */
+    os?: string;
+    /**
+     * When it enrolled.
+     */
+    registered_at?: string | null;
+    /**
+     * online, offline, or cordoned (it takes no new session).
+     */
+    state: "online" | "offline" | "cordoned";
+    /**
+     * How many it holds now.
+     */
+    used: number;
+};
+/**
+ * A runner pool to make: of one type.
+ */
+export type PoolRequest = {
+    /**
+     * Its machines' architecture.
+     */
+    arch: "amd64" | "arm64";
+    /**
+     * Its name: lowercase letters, digits, _ and -, starting with a letter, at most 64; the project's once.
+     */
+    name: string;
+    /**
+     * Its machines' operating system.
+     */
+    os: "linux" | "macos";
+};
+/**
+ * A pool's state: what its owner's scaling loop reads.
+ */
+export type PoolState = {
+    /**
+     * How many sessions its machines take at once.
+     */
+    capacity_total: number;
+    /**
+     * How many they hold now.
+     */
+    capacity_used: number;
+    /**
+     * Its machines.
+     */
+    machines: PoolMachine[];
+    /**
+     * Since when the oldest waits (null: none waits).
+     */
+    oldest_waiting_since?: string | null;
+    pool: PoolStateOf;
+    /**
+     * How many sessions wait for a place on the pool's machines: parked until one of them has room — what a scaling loop adds a machine for.
+     */
+    waiting: number;
+};
+/**
+ * The pool a state is of.
+ */
+export type PoolStateOf = {
+    /**
+     * amd64 or arm64.
+     */
+    arch: string;
+    /**
+     * Its id.
+     */
+    id: string;
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * linux or macos.
+     */
+    os: string;
+};
 /**
  * A provider the project connected with its own key.
  */
@@ -1923,125 +2220,365 @@ export type Subagent = {
     tools?: ToolRef[];
 };
 /**
- * A role a text model is chosen by.
+ * One path as a writer changed it.
  */
-export type TextModel = {
-    /**
-     * What it is for.
-     */
-    description: string;
+export type SyncChange = {
+    now?: SyncEntry;
     /**
-     * The role.
+     * The path.
      */
-    role: string;
+    path: string;
+    previous?: SyncEntry;
 };
 /**
- * The support line's answer: what to do, and whether it was logged as something Palbase lacks — then with the case it was logged under.
+ * A writer's changes.
  */
-export type SupportAnswer = {
+export type SyncChangeSet = {
     /**
-     * The answer, in the question's language, naming the documentation it is taken from.
+     * Its changes, each with what it last knew of its path.
      */
-    answer: string;
+    changes: SyncChange[];
     /**
-     * The case's id (sup_…), given only when the question was logged: what the asker holds of it, and what the mail sent when it is closed names. An answer that logged nothing has no case.
+     * The head the writer last applied in full.
      */
-    case?: string;
+    known_seq: number;
     /**
-     * Whether the question was logged as something Palbase lacks: the asker is mailed when it is closed.
+     * Why it publishes.
      */
-    logged: boolean;
+    reason?: string;
 };
 /**
- * A question to Palbase's support line.
+ * The store's answer to a publish.
  */
-export type SupportQuestion = {
-    /**
-     * What the asker's project shows (at most 32768 characters): its machines, their last builds, a failed build's log. Credential-shaped values are masked before the model or anyone else reads it.
-     */
-    context?: string;
+export type SyncChangeSetResult = {
     /**
-     * The question, in any language. Credential-shaped values are masked before the model or anyone else reads it.
+     * The paths applied.
      */
-    question: string;
-};
-/**
- * A tool an agent of the project's may be given, as a ToolRef names it.
- */
-export type Tool = {
+    applied?: string[];
     /**
-     * Every call waits for a person's yes.
+     * What changed since known_seq that the writer has not seen.
      */
-    approval: boolean;
+    catch_up?: SyncPathState[];
     /**
-     * What it does.
+     * known_seq is older than the kept history: catch_up is the whole tree.
      */
-    description: string;
+    catch_up_full?: boolean;
     /**
-     * backend, client: the machine whose build declares it.
+     * The changes that lost.
      */
-    machine?: string;
+    conflicts?: SyncConflict[];
     /**
-     * Its name.
+     * The head's tree now.
      */
-    name: string;
+    manifest_id: string;
     /**
-     * What it takes, as a JSON Schema (an MCP server says its own when it is called).
+     * The head's sequence now.
      */
-    parameters?: {
-        [key: string]: unknown;
-    };
+    seq: number;
     /**
-     * backend: the backend's function; client: the app answers it; https, mcp: an endpoint of the project's; platform: the platform's.
+     * Its checksum.
      */
-    source: "backend" | "client" | "https" | "mcp" | "platform";
+    tree_checksum?: string;
 };
 /**
- * A part of what a tool returned.
+ * What changed since a sequence, as it is at the head (none: the head alone).
  */
-export type ToolContent = {
+export type SyncChanges = {
     /**
-     * An image as base64 (5 MiB at most).
+     * Each changed path, as it is at the head.
      */
-    data?: string;
+    changes?: SyncPathState[];
     /**
-     * An image's type: image/png, image/jpeg, image/webp or image/gif.
+     * since is older than the kept history (or 0): changes is the whole tree.
      */
-    media_type?: string;
+    full?: boolean;
     /**
-     * The text.
+     * The head's tree.
      */
-    text?: string;
+    manifest_id: string;
     /**
-     * text or image.
+     * The head's sequence.
      */
-    type: "text" | "image";
+    seq: number;
+    /**
+     * The sequence asked from.
+     */
+    since?: number;
+    /**
+     * The head's tree's checksum.
+     */
+    tree_checksum?: string;
 };
 /**
- * The tools the project's agents may be given.
+ * A change that lost: the path had changed in the store since the writer saw it.
  */
-export type ToolList = {
+export type SyncConflict = {
     /**
-     * The backend's (its builds that serve), the project's endpoints, then the platform's.
+     * The conflict: read it by it (GET /ai/workspace-sync/conflicts/{conflict_id}).
      */
-    tools: Tool[];
+    id: string;
+    lost?: SyncEntry;
+    /**
+     * The path.
+     */
+    path: string;
+    winner?: SyncEntry;
 };
 /**
- * What an app's tool returned (1 MiB of text and 4 images at most).
+ * A conflict as the workspace's history keeps it.
  */
-export type ToolOutput = {
+export type SyncConflictDetail = {
     /**
-     * The member the project's server acts as: held to that member's rules — their turn (403 not_your_turn) (the server's alone: a user sending it is answered 400; one who is not a member of the chat, 403 not_a_member). Left out, the server acts as itself.
+     * When it lost.
      */
-    as?: string;
+    created_at?: string;
     /**
-     * The tool failed; the output says why.
+     * The conflict.
      */
-    is_error?: boolean;
+    id: string;
+    lost?: SyncEntry;
     /**
-     * Text and images: the agent is shown both.
+     * The tree the store was at.
      */
-    output: ToolContent[];
+    manifest_id?: string;
+    /**
+     * The path.
+     */
+    path: string;
+    read?: SyncGrant;
+    winner?: SyncEntry;
+    /**
+     * Who wrote the version that lost.
+     */
+    writer?: string;
+};
+/**
+ * What a path is in a tree: a file (its digest, size and mode) or a directory.
+ */
+export type SyncEntry = {
+    /**
+     * A file's bytes' digest: sha256:<hex>.
+     */
+    digest?: string;
+    /**
+     * file or dir.
+     */
+    kind: "file" | "dir";
+    /**
+     * A file's mode.
+     */
+    mode?: number;
+    /**
+     * A file's size in bytes.
+     */
+    size?: number;
+};
+/**
+ * One presigned request.
+ */
+export type SyncGrant = {
+    /**
+     * The headers it is made with.
+     */
+    headers?: {
+        [key: string]: string;
+    };
+    /**
+     * Its method.
+     */
+    method: string;
+    /**
+     * Its address, signed.
+     */
+    url: string;
+};
+/**
+ * The blobs to transfer, by their digests.
+ */
+export type SyncGrantRequest = {
+    /**
+     * Blobs it will read.
+     */
+    get?: string[];
+    /**
+     * Blobs the writer will upload.
+     */
+    put?: string[];
+};
+/**
+ * Each digest asked for, and its grant (a put the store holds already is absent).
+ */
+export type SyncGrants = {
+    /**
+     * Reads, by digest.
+     */
+    get?: {
+        [key: string]: SyncGrant;
+    };
+    /**
+     * Uploads, by digest.
+     */
+    put?: {
+        [key: string]: SyncGrant;
+    };
+};
+/**
+ * A path as it is at a head (state null: absent).
+ */
+export type SyncPathState = {
+    /**
+     * The path, relative to the workspace's root.
+     */
+    path: string;
+    state: SyncEntry;
+};
+/**
+ * The store's refusal (RFC 9457).
+ */
+export type SyncProblem = {
+    /**
+     * Its stable code.
+     */
+    code?: string;
+    /**
+     * Its sentence.
+     */
+    detail?: string;
+    /**
+     * Its status.
+     */
+    status?: number;
+    /**
+     * Its title.
+     */
+    title?: string;
+    /**
+     * Its type.
+     */
+    type?: string;
+    [key: string]: unknown;
+};
+/**
+ * A role a text model is chosen by.
+ */
+export type TextModel = {
+    /**
+     * What it is for.
+     */
+    description: string;
+    /**
+     * The role.
+     */
+    role: string;
+};
+/**
+ * The support line's answer: what to do, and whether it was logged as something Palbase lacks — then with the case it was logged under.
+ */
+export type SupportAnswer = {
+    /**
+     * The answer, in the question's language, naming the documentation it is taken from.
+     */
+    answer: string;
+    /**
+     * The case's id (sup_…), given only when the question was logged: what the asker holds of it, and what the mail sent when it is closed names. An answer that logged nothing has no case.
+     */
+    case?: string;
+    /**
+     * Whether the question was logged as something Palbase lacks: the asker is mailed when it is closed.
+     */
+    logged: boolean;
+};
+/**
+ * A question to Palbase's support line.
+ */
+export type SupportQuestion = {
+    /**
+     * What the asker's project shows (at most 32768 characters): its machines, their last builds, a failed build's log. Credential-shaped values are masked before the model or anyone else reads it.
+     */
+    context?: string;
+    /**
+     * The question, in any language. Credential-shaped values are masked before the model or anyone else reads it.
+     */
+    question: 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.
+ */
+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";
+};
+/**
+ * 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).
+ */
+export type ToolOutput = {
+    /**
+     * The member the project's server acts as: held to that member's rules — their turn (403 not_your_turn) (the server's alone: a user sending it is answered 400; one who is not a member of the chat, 403 not_a_member). Left out, the server acts as itself.
+     */
+    as?: string;
+    /**
+     * The tool failed; the output says why.
+     */
+    is_error?: boolean;
+    /**
+     * Text and images: the agent is shown both.
+     */
+    output: ToolContent[];
+    workspace_tree?: WorkspaceTree;
 };
 /**
  * An app's answer the turn was given.
@@ -2572,6 +3109,91 @@ export type WorkspaceChange = {
      */
     size_bytes: number;
 };
+/**
+ * The path both wrote.
+ */
+export type WorkspaceConflict = {
+    /**
+     * The conflict: the version that lost is kept in the workspace's history 30 days, read by it (GET /ai/workspace-sync/conflicts/{conflict_id}).
+     */
+    id: string;
+    lost: WorkspaceEntry;
+    /**
+     * The path.
+     */
+    path: string;
+    winner: WorkspaceEntry;
+};
+/**
+ * A writer's change of the chat's workspace that lost: the path had changed in the store since the writer saw it — the first to reach the store wins.
+ */
+export type WorkspaceConflictEvent = {
+    /**
+     * The chat.
+     */
+    chat_id: string;
+    conflict: WorkspaceConflict;
+    /**
+     * The tree the store was at when it kept the change aside.
+     */
+    manifest_id: string;
+    /**
+     * The chat's labels.
+     */
+    metadata: {
+        [key: string]: string;
+    };
+    /**
+     * Its sequence.
+     */
+    seq: number;
+    /**
+     * Who wrote the version that lost: the session's machine, a machine syncing the workspace (its token's label), the project's backend.
+     */
+    writer: string;
+};
+/**
+ * What a path is in a tree: a file or a directory (null: absent).
+ */
+export type WorkspaceEntry = {
+    /**
+     * A file's digest (sha256:<hex>).
+     */
+    digest?: string;
+    /**
+     * file or dir.
+     */
+    kind: string;
+    /**
+     * A file's mode.
+     */
+    mode?: number;
+    /**
+     * A file's size in bytes.
+     */
+    size?: number;
+};
+/**
+ * A file's bytes.
+ */
+export type WorkspaceFileBytes = Blob;
+/**
+ * What a write of a workspace's file left.
+ */
+export type WorkspaceFileWritten = {
+    /**
+     * The tree the workspace is at now: read a file of it by it (GET …/workspace/files?manifest=).
+     */
+    manifest_id: string;
+    /**
+     * The file.
+     */
+    path: string;
+    /**
+     * Its place in the workspace's history.
+     */
+    seq: number;
+};
 /**
  * A tree the chat's workspace published: its machine publishes whenever the files are quiet for a moment — mid-turn, as a build writes its product — and once more as it lets the workspace go.
  */
@@ -2667,6 +3289,103 @@ export type WorkspaceRepoRequest = {
      */
     repo: string;
 };
+/**
+ * A workspace token, not said.
+ */
+export type WorkspaceToken = {
+    /**
+     * read or write.
+     */
+    access: string;
+    /**
+     * When it expires.
+     */
+    expires_at: string;
+    /**
+     * Its id: revoke it by it.
+     */
+    id: string;
+    /**
+     * What it is for.
+     */
+    label?: string;
+    /**
+     * The workspace's id in the store.
+     */
+    workspace_id: string;
+};
+/**
+ * A chat's workspace's tokens.
+ */
+export type WorkspaceTokenList = {
+    /**
+     * The tokens, none said.
+     */
+    tokens: WorkspaceToken[];
+};
+/**
+ * A workspace token as it is minted: said once.
+ */
+export type WorkspaceTokenMinted = {
+    /**
+     * read or write.
+     */
+    access: string;
+    /**
+     * When it expires.
+     */
+    expires_at: string;
+    /**
+     * Its id: revoke it by it.
+     */
+    id: string;
+    /**
+     * What it is for.
+     */
+    label?: string;
+    /**
+     * Where the workspace's token routes are, at the project's own address: `palai workspace sync --url <sync_url> <dir>`.
+     */
+    sync_url: string;
+    /**
+     * The token, said once: given `palai workspace sync` in its environment (PALAI_WORKSPACE_TOKEN) or on its standard input (--token-file -), never on its command line.
+     */
+    token: string;
+    /**
+     * The workspace's id in the store.
+     */
+    workspace_id: string;
+};
+/**
+ * A workspace token to mint.
+ */
+export type WorkspaceTokenRequest = {
+    /**
+     * read: the workspace followed; write: followed and written, both ways.
+     */
+    access: "read" | "write";
+    /**
+     * What it is for — the machine's name, say: a conflict names its writer by it. 128 bytes of UTF-8 at most (maxLength counts characters, so a label of fewer may still be too long), with no control character, no format character (a bidi override or isolate, a zero-width space or joiner, a byte order mark) and no line or paragraph separator — a label is shown as it was written.
+     */
+    label?: string;
+    /**
+     * How long it lives: 1 to 604800 (none: an hour) — a member's 1 to 3600; no longer than an environment's token it is minted with.
+     */
+    ttl_seconds?: number;
+};
+/**
+ * The tree the tool's writes left the chat's workspace at, as a write of it answered them (PUT /ai/chats/{chat_id}/workspace/files): its manifest, its place in the workspace's history, either or both. A call that answered later names it as one answered at once does (workspace_tree): the agent's next command waits for the session's machine to have it. Left out: the tool wrote nothing there.
+ */
+export type WorkspaceTree = {
+    /**
+     * The tree's manifest (a write's manifest_id).
+     */
+    manifest_id?: string;
+    /**
+     * Its place in the workspace's history (a write's seq).
+     */
+    seq?: number;
+};
 /** The events this module sends the project's webhooks (x-palbase-events), by type: each one's payload, the event's data. */
 export interface Events {
     /**
@@ -2697,6 +3416,10 @@ export interface Events {
      * ai.voice.started: a chat's voice began.
      */
     "ai.voice.started": VoiceEvent;
+    /**
+     * ai.workspace.conflict: a writer's change of a chat's workspace lost — the path had changed since the writer saw it; the version that lost is kept 30 days in the workspace's history.
+     */
+    "ai.workspace.conflict": WorkspaceConflictEvent;
     /**
      * ai.workspace.published: a chat's workspace published a tree — what its files are now, with the files it changed; read one of them by the tree (GET /ai/chats/{chat_id}/workspace/files?manifest=).
      */
@@ -3096,7 +3819,7 @@ export declare function client(t: Transport): {
     /**
      * 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. Given by the app of the member whose message began the turn (403 not_your_turn for any other) — or by the project's server, for any turn, or as that member (as). A call of the project's backend (or an HTTPS tool of its) that answered {"deferred": true} — its work outlasts a call — is answered here too, by the project's server as itself, within the while it named (a minute to a day; an hour), and by no member.
+     * 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. Given by the app of the member whose message began the turn (403 not_your_turn for any other) — or by the project's server, for any turn, or as that member (as). A call of the project's backend (or an HTTPS tool of its) that answered {"deferred": true} — its work outlasts a call — is answered here too, by the project's server as itself, within the while it named (a minute to a day; an hour), and by no member. An answer whose tool wrote the chat's workspace names the tree its writes left (workspace_tree), as an answer given at once does: the agent's next command waits for the session's machine to have it (400 for one that names no tree).
      */
     answerChatToolCall(input: {
         path: {
@@ -3109,7 +3832,7 @@ export declare function client(t: Transport): {
     /**
      * A turn's artifacts
      *
-     * What the turn's agent published as its output (palai.artifact.publish) — a build's product from the workspace's Mac, a screenshot, a report — kept in the project's own storage. The chat's members and the project's server read it, as they read the chat.
+     * What the turn's agent published as its output (palai.artifact.publish) — a build's product, a screenshot, a report — kept in the project's own storage. The chat's members and the project's server read it, as they read the chat.
      */
     listChatTurnArtifacts(input: {
         path: {
@@ -3201,7 +3924,7 @@ export declare function client(t: Transport): {
     /**
      * A file of the chat's workspace
      *
-     * A file of the chat's workspace, its bytes (an attachment, never a page): from the tree the workspace is at now, or from the one an ai.workspace.published event named (manifest) — a build's product as that publish left it. Read by the chat's members and the project's server, as they read the chat. Served up to 64 MiB (413 file_too_large past it: publish a larger one as the turn's artifact); its digest is Content-Digest. A project reads 4 files at once (429 too_many_reads, Retry-After), and a file is written for no longer than its bytes take at 256 KiB/s and a minute more. A chat that works in no workspace yet, a tree of another workspace, a path its tree does not name: 404 file_not_found.
+     * A file of the chat's workspace, its bytes (an attachment, never a page): from the tree the workspace is at now, or from the one an ai.workspace.published event named (manifest) — a build's product as that publish left it. Read by the chat's members and the project's server, as they read the chat. Served up to 64 MiB (413 file_too_large past it: publish a larger one as the turn's artifact); its digest is Content-Digest. Each of the module's servers reads 4 of a project's files at once (429 too_many_reads, Retry-After), and a file is written for no longer than its bytes take at 256 KiB/s and a minute more. A chat that works in no workspace yet, a tree of another workspace, a path its tree does not name: 404 file_not_found.
      */
     getChatWorkspaceFile(input: {
         path: {
@@ -3213,6 +3936,36 @@ 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>>;
+    /**
+     * Write a file of the chat's workspace
+     *
+     * The customer's backend writes one file of the chat's workspace, its bytes the body (64 MiB at most: 413 file_too_large; each of the module's servers writes 2 of a project's at once, more are told to ask again: 429 too_many_reads): published over whatever the workspace's head holds — the write is deliberate, no conflict is made of it — and synced from there to every machine that holds the workspace, the session's own before the agent's next command. A body that says its length (Content-Length) is forwarded as it arrives; one sent in chunks is read whole first, to the same 64 MiB. What it published is told as ai.workspace.published. A chat whose first turn has not opened its workspace has it opened now. The project's server's, and a member's who may write the chat; a chat that works in no workspace: 409 no_workspace.
+     */
+    putChatWorkspaceFile(input: {
+        path: {
+            chat_id: string;
+        };
+        query: {
+            path: string;
+        };
+        body: BodyInit;
+        contentType?: string; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, WorkspaceFileWritten>>;
+    /**
+     * Remove a file of the chat's workspace
+     *
+     * The customer's backend removes one file of the chat's workspace, as a write is (PUT): synced to every machine that holds it. The project's server's, and a member's who may write the chat.
+     */
+    deleteChatWorkspaceFile(input: {
+        path: {
+            chat_id: string;
+        };
+        query: {
+            path: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, WorkspaceFileWritten>>;
     /**
      * Put a repository in the chat's workspace
      *
@@ -3225,6 +3978,41 @@ export declare function client(t: Transport): {
         body: WorkspaceRepoRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, Chat>>;
+    /**
+     * The workspace's tokens
+     *
+     * Its tokens — access, label, when each expires — none of them said again: the project's server's answer is every token of the workspace, a member's the ones they minted.
+     */
+    listChatWorkspaceTokens(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, WorkspaceTokenList>>;
+    /**
+     * Mint a workspace token
+     *
+     * A token of the chat's workspace for a machine of the customer's to sync it with — `PALAI_WORKSPACE_TOKEN=<token> palai workspace sync --url <sync_url> <dir>` (or the token on standard input: `--token-file -`; never on the command line): live and always both ways (write), or followed (read) — said once, here. It lives ttl_seconds (an hour when none, 7 days at most) — no longer than an environment's token it is minted with — and answers at the project's own address alone (sync_url, the workspace's token routes). While one lives the chat's workspace events are told (ai.workspace.published, ai.workspace.conflict). A chat whose first turn has not opened its workspace has it opened now. The project's server's, and a member's who may write the chat: a member's token lives an hour at most, is theirs alone to list and revoke, and answers only while they are in the chat and the project lets its users talk to its agents (settings.clients) — taking them out, or turning clients off, revokes it. A chat that works in no workspace: 409 no_workspace.
+     */
+    createChatWorkspaceToken(input: {
+        path: {
+            chat_id: string;
+        };
+        body: WorkspaceTokenRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, WorkspaceTokenMinted>>;
+    /**
+     * Revoke a workspace token
+     *
+     * Revoked at once: every token route refuses it from then, an open event stream with it ends. The project's server revokes any token of the workspace; a member, one they minted (another's is not found).
+     */
+    revokeChatWorkspaceToken(input: {
+        path: {
+            chat_id: string; /** The token's id. */
+            token: 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>>;
     /**
      * Turn texts into vectors
      *
@@ -3245,7 +4033,7 @@ export declare function client(t: Transport): {
     /**
      * Put a tool endpoint
      *
-     * A tool at an HTTPS address of the project's — called with a signed POST {tool, call_id, input, context: {chat_id, agent, user, metadata, turn_id, run_id, subagent} — the turn, and the run that called: the agent's own, or a subagent's at work (subagent names which, null for the agent)} 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.
+     * A tool at an HTTPS address of the project's — called with a signed POST {tool, call_id, input, context: {chat_id, agent, user, metadata, turn_id, run_id, subagent, workspace} — the turn, the run that called: the agent's own, or a subagent's at work (subagent names which, null for the agent), and, in a chat that works in a workspace, the workspace as the session last wrote it, flushed before the call: workspace {chat_id, manifest_id, seq} (read its files at that tree, GET /ai/chats/{chat_id}/workspace/files?manifest=)} — and answered {output, is_error, workspace_tree?} or plain text: a tool that wrote the workspace (PUT /ai/chats/{chat_id}/workspace/files) answers workspace_tree {manifest_id, seq} — the tree its writes left, either or both — and the agent's next command sees it — or an MCP server, whose tools an agent may use: when the project says it is its own (workspace: true), told the same tree in its tools/call's _meta (palbase/workspace), answering it in its result's _meta (palbase/workspace_tree); a third party's server is told nothing of a chat or its workspace. The answer says an https tool's signing secret, once.
      */
     putEndpoint(input: {
         path: {
@@ -3265,6 +4053,37 @@ export declare function client(t: Transport): {
         }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<204, undefined>>;
+    /**
+     * The project's variables
+     *
+     * Their names, whether each is a secret, and when each was set: never a value.
+     */
+    listEnv(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, EnvList>>;
+    /**
+     * Set a variable
+     *
+     * One of the project's variables or secrets, set or set anew: every command of every session of its agents begun from now has it — on the platform's Linux machines and on the project's own pools, Linux and Mac — beside the agent's own (its definition's env), masked wherever a transcript would show it. The value is sealed where the sessions run and never answered, nor logged; a refusal never repeats it.
+     */
+    putEnv(input: {
+        path: {
+            key: string;
+        };
+        body: EnvRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, EnvVar>>;
+    /**
+     * Remove a variable
+     *
+     * Sessions begun from now no longer have it.
+     */
+    deleteEnv(input: {
+        path: {
+            key: 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
      *
@@ -3300,6 +4119,39 @@ 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>>;
+    /**
+     * Delete a machine
+     *
+     * A cordoned machine that holds no session leaves its pool; its `palai` agent is refused from then. One not cordoned: 409 machine_not_cordoned; one that holds a session: 409 machine_busy.
+     */
+    deleteMachine(input: {
+        path: {
+            machine: 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>>;
+    /**
+     * Cordon a machine
+     *
+     * The machine takes no new session; the sessions it holds run on. Delete it once it holds none (its state says used 0).
+     */
+    cordonMachine(input: {
+        path: {
+            machine: 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>>;
+    /**
+     * Resume a machine
+     *
+     * A cordoned machine takes sessions again.
+     */
+    resumeMachine(input: {
+        path: {
+            machine: 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>>;
     /**
      * What a project may name
      *
@@ -3308,6 +4160,79 @@ export declare function client(t: Transport): {
     listModels(input?: {
         signal?: AbortSignal;
     }): Promise<Reply<200, Models>>;
+    /**
+     * Revoke an enrolment key
+     *
+     * No machine enrols with it any more; the machines enrolled with it before are not touched (cordon and delete one: /ai/machines/{machine}).
+     */
+    revokePoolKey(input: {
+        path: {
+            key: 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 project's runner pools
+     *
+     * Every pool of the project's, with what its machines hold: how many machines, the sessions they take and take now (capacity_total, capacity_used), and how many sessions wait for a place (waiting).
+     */
+    listPools(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, PoolList>>;
+    /**
+     * Make a runner pool
+     *
+     * A pool of one type — its machines' operating system (linux or macos) and architecture (amd64 or arm64) — that the project's own machines enrol into with the `palai` agent and a single-use key (POST /ai/pools/{pool}/keys). A chat that names it (POST /ai/chats {pool}) runs its workspace's sessions there. Managed through the API, the SDK and the CLI (palbase ai pools): the project scales it itself, reading its state (GET /ai/pools/{pool}/state). A name taken already: 409 pool_exists.
+     */
+    createPool(input: {
+        body: PoolRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, Pool>>;
+    /**
+     * Delete a runner pool
+     *
+     * A pool with no machine left in it: cordon each machine, delete it once it holds no session (DELETE /ai/machines/{machine}), then the pool. One with machines: 409 pool_not_empty.
+     */
+    deletePool(input: {
+        path: {
+            pool: 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 pool's enrolment keys
+     *
+     * Its single-use enrolment keys — when each was made, used, revoked, and when it expires — none of them said again.
+     */
+    listPoolKeys(input: {
+        path: {
+            pool: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, PoolKeyList>>;
+    /**
+     * Mint an enrolment key
+     *
+     * A single-use key a machine of the project's enrols into the pool with (saved to a file on the machine: `palai enroll --key-file <file> --capacity <n>` — never on a command line), said once, here. A machine enrolled with it serves the project's sessions once whoever minted it is gone: never minted for an environment's token.
+     */
+    createPoolKey(input: {
+        path: {
+            pool: string;
+        };
+        body: PoolKeyRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, PoolKey>>;
+    /**
+     * A runner pool's state
+     *
+     * What the project's own scaling loop reads — no webhook tells it: each machine (online, offline or cordoned; the sessions it takes and holds; since when it is idle; when it was last seen), the pool's capacity and what it holds, how many sessions wait for a place and since when the oldest has waited. Scale up by enrolling machines; scale down by cordoning one (it takes no new session) and deleting it once it holds none.
+     */
+    getPoolState(input: {
+        path: {
+            pool: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, PoolState>>;
     /**
      * The project's own provider keys
      *
@@ -3478,5 +4403,61 @@ 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, UsagePage>>;
+    /**
+     * What changed since a sequence
+     *
+     * Every path whose state at the head differs from its state at since, as it is at the head (since 0, or older than the kept history: the whole tree, full). Called with the workspace token alone (Authorization: Bearer), at the project's own address — forwarded as it came to the workspace's store, whose answer it is (its refusals are its own problem documents, application/problem+json); a token this project did not mint, revoked or expired is refused here (401 invalid_token). This is the wire `palai workspace sync` speaks: its shapes are the store's.
+     */
+    getWorkspaceSyncChanges(input?: {
+        query?: {
+            since?: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, SyncChanges>>;
+    /**
+     * Publish the writer's changes
+     *
+     * The writer's changes, each with what it last knew of its path (previous): applied only while the path still is that — the first to reach the store wins; a change that lost is kept aside as a conflict, in the workspace's history for 30 days (ai.workspace.conflict) — answered with the head, what was applied, what lost, and what changed since known_seq that the writer has not seen (catch_up). A write token's alone. Called with the workspace token alone (Authorization: Bearer), at the project's own address — forwarded as it came to the workspace's store, whose answer it is (its refusals are its own problem documents, application/problem+json); a token this project did not mint, revoked or expired is refused here (401 invalid_token). This is the wire `palai workspace sync` speaks: its shapes are the store's.
+     */
+    createWorkspaceSyncChangeSet(input: {
+        body: SyncChangeSet; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, SyncChangeSetResult>>;
+    /**
+     * A conflict, and the version that lost
+     *
+     * A conflict as the workspace's history keeps it (30 days): the path, the version that lost with a signed request to read its bytes (read), the one that won, the tree and the writer. Called with the workspace token alone (Authorization: Bearer), at the project's own address — forwarded as it came to the workspace's store, whose answer it is (its refusals are its own problem documents, application/problem+json); a token this project did not mint, revoked or expired is refused here (401 invalid_token). This is the wire `palai workspace sync` speaks: its shapes are the store's.
+     */
+    getWorkspaceSyncConflict(input: {
+        path: {
+            conflict_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, SyncConflictDetail>>;
+    /**
+     * The workspace's events, as they happen
+     *
+     * An event stream (text/event-stream), passed on unbuffered: `event: head` when the head moves ({workspace_id, manifest_id, seq}) and `event: conflict` when a writer's change lost ({id, path, lost, winner}), with a comment line every 15 seconds. Each of the module's servers that answer the project's address holds 4 streams of a token open at once, 16 of a workspace, 64 of a project's tokens together — apart from the project's response streams (429 too_many_streams): the bounds are a server's, not the project's whole; a stream ends when its token is revoked, expires, or is a member's whose member left the chat. Called with the workspace token alone (Authorization: Bearer), at the project's own address — forwarded as it came to the workspace's store, whose answer it is (its refusals are its own problem documents, application/problem+json); a token this project did not mint, revoked or expired is refused here (401 invalid_token). This is the wire `palai workspace sync` speaks: its shapes are the store's.
+     */
+    getWorkspaceSyncEvents(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Response>>;
+    /**
+     * Signed transfers of the workspace's blobs
+     *
+     * Presigned requests for the blobs the writer will upload (put) and read (get), by their digests: a blob the store holds already is not in put — nothing to upload. Called with the workspace token alone (Authorization: Bearer), at the project's own address — forwarded as it came to the workspace's store, whose answer it is (its refusals are its own problem documents, application/problem+json); a token this project did not mint, revoked or expired is refused here (401 invalid_token). This is the wire `palai workspace sync` speaks: its shapes are the store's.
+     */
+    createWorkspaceSyncGrants(input: {
+        body: SyncGrantRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, SyncGrants>>;
+    /**
+     * Where the workspace's head is
+     *
+     * The tree the workspace is at: its manifest, its sequence and its checksum. Called with the workspace token alone (Authorization: Bearer), at the project's own address — forwarded as it came to the workspace's store, whose answer it is (its refusals are its own problem documents, application/problem+json); a token this project did not mint, revoked or expired is refused here (401 invalid_token). This is the wire `palai workspace sync` speaks: its shapes are the store's.
+     */
+    getWorkspaceSyncHead(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, SyncChanges>>;
 };
 export type Client = ReturnType<typeof client>;