palbase 0.43.2 → 0.44.1

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

@@ -1,6 +1,6 @@
 import type * as modules from '../../internal/src/modules/index.js';
 import { type ToolResult } from '../../internal/src/tool-output.js';
-import { type AgentDefinitionInput, type BackendAgent, type BackendRepo } from './tools.js';
+import { type AgentDefinitionInput, type BackendAgent, type BackendRepo, type WorkspaceTree } from './tools.js';
 type Module = ReturnType<typeof modules.ai.client>;
 export type Chat = modules.ai.Chat;
 export type ChatMessage = modules.ai.ChatMessage;
@@ -51,6 +51,15 @@ export interface EndpointInput {
     parameters?: Record<string, unknown>;
     /** Every call waits for a person's yes. */
     approval?: boolean;
+    /**
+     * 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, manifestId and seq), and the tree its answer names is waited for. Left out
+     * (false): any server's address — a third party's API or MCP server — told nothing of the chat's workspace (an https
+     * tool is told the turn's chatId as ever), a tree it answers ignored. An endpoint put before https tools took the
+     * setting is told nothing until it is put again with it. The backend's own tools are told the workspace always.
+     */
+    workspace?: boolean;
 }
 export interface MemberInput {
     userId: string;
@@ -106,6 +115,12 @@ export interface CreateChat {
          */
         trailers?: CommitTrailer[];
     };
+    /**
+     * The project's runner pool its workspace runs on (ai.pools), by its id or its name: its sessions run on the
+     * project's own machines enrolled there, a Mac or a Linux box. Left out, the platform's own Linux machines. A chat
+     * that names one works in a workspace; one the project has not is refused (400).
+     */
+    pool?: string;
     signal?: AbortSignal;
 }
 /** A repository the project's chats work in, as the module keeps it. */
@@ -495,7 +510,72 @@ export interface Voices {
         signal?: AbortSignal;
     }): Promise<ChatVoice>;
 }
-/** A chat's workspace, from its server: a file of a tree it published, a repository put in it at work. */
+/** What a write of a chat's workspace left: the tree it is at now — what a tool answers with ai.answer(output, { workspaceTree }). */
+export interface WorkspaceWrite {
+    /** The file. */
+    path: string;
+    /** The tree the workspace is at now: a file of it is read by it (workspace.file's manifest). */
+    manifestId: string;
+    /** Its place in the workspace's history. */
+    seq: number;
+}
+/** A token of a chat's workspace, never said again: what it may do, what it is for, when it expires. */
+export interface WorkspaceToken {
+    /** Its id: revoked by it. */
+    id: string;
+    /** read: the workspace followed; write: followed and written, both ways. */
+    access: 'read' | 'write' | (string & {});
+    /** What it is for — the machine's name: a conflict names its writer by it. */
+    label?: string;
+    expiresAt: string;
+    /** The workspace's id in the store. */
+    workspaceId: string;
+}
+/**
+ * A workspace token as it is minted: the token and where it syncs, said once — on the machine,
+ * `PALAI_WORKSPACE_TOKEN=<token> palai workspace sync --url <syncUrl> <dir>`, or the token on standard input with
+ * `--token-file -`; never on the command line (palai has no --token: any process on the machine could read it).
+ */
+export interface WorkspaceTokenMinted extends WorkspaceToken {
+    /** The token, said once: given palai workspace sync in PALAI_WORKSPACE_TOKEN, or on its standard input (--token-file -). */
+    token: string;
+    /** Where the workspace's token routes are, at the project's own address: `palai workspace sync --url <syncUrl> <dir>`. */
+    syncUrl: string;
+}
+/**
+ * The tokens of a chat's workspace, from its server: a machine of the customer's — a developer's computer, a CI
+ * runner — syncs the workspace with one (palai workspace sync), live and both ways (write) or followed (read). While
+ * one lives the chat's workspace events are told (ai.workspace.published, ai.workspace.conflict).
+ */
+export interface WorkspaceTokens {
+    /**
+     * Mints one, said once: it lives ttlSeconds (1 to 604 800; an hour when left out) — no longer than an environment's
+     * token it is minted with — and answers at the project's own address alone (syncUrl). A member who mints one (the
+     * project letting its app's users in) mints it for an hour at most; it is theirs alone, and stops answering when they
+     * leave the chat or the project turns clients off. A chat whose first turn has not opened its workspace has it opened
+     * now; a chat of no workspace: 409 no_workspace.
+     */
+    create(id: string, token: {
+        access: 'read' | 'write';
+        ttlSeconds?: number;
+        label?: string;
+        signal?: AbortSignal;
+    }): Promise<WorkspaceTokenMinted>;
+    /** Its tokens — access, label, when each expires — none of them said again: the server's every one, a member's their own. */
+    list(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceToken[]>;
+    /** Revoked at once: every token route refuses it from then, and an event stream open with it ends. A member revokes their own. */
+    revoke(id: string, tokenId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/**
+ * A file's bytes as a workspace write takes them: text (written as UTF-8), bytes, a Blob, or a stream of bytes — a
+ * stream is read here whole first (64 MiB at most), so the write says its length, as the workspace's store asks.
+ */
+export type WorkspaceFileBody = string | Uint8Array | Blob | ReadableStream<Uint8Array>;
+/** A chat's workspace, from its server: a file of a tree it published, written or removed, a repository put in it at work, its sync tokens. */
 export interface Workspaces {
     /**
      * A file of the chat's workspace, its bytes: from the tree it is at now, or from the one an ai.workspace.published
@@ -516,6 +596,26 @@ export interface Workspaces {
         branch?: string;
         signal?: AbortSignal;
     }): Promise<Chat>;
+    /**
+     * Writes one file of the chat's workspace, its bytes the body (64 MiB at most: a larger one is refused here, before it
+     * is sent — a stream as soon as it passes the bound — and by the module, 413 file_too_large): published over
+     * whatever the workspace's head holds — the write is deliberate, no conflict is made of it — and synced to every
+     * machine that holds the workspace, the session's own before the agent's next command; it is told as
+     * ai.workspace.published. path is relative to its root (repo/src/config.json): 1 to 2048 bytes, each segment 255 at
+     * most. A stream body is read whole before the write is sent, so it says its length. A backend tool that writes answers
+     * the tree it left: ai.answer(output, { workspaceTree: written }). A chat whose first turn has not opened its
+     * workspace has it opened now; a chat of no workspace: 409 no_workspace.
+     */
+    write(id: string, path: string, body: WorkspaceFileBody, options?: {
+        contentType?: string;
+        signal?: AbortSignal;
+    }): Promise<WorkspaceWrite>;
+    /** Removes one file of the chat's workspace, as a write is made: synced to every machine that holds it. */
+    remove(id: string, path: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceWrite>;
+    /** The tokens a machine of the customer's syncs the workspace with (palai workspace sync). */
+    readonly tokens: WorkspaceTokens;
 }
 export interface Chats {
     create(chat: CreateChat): Promise<Chat>;
@@ -638,11 +738,15 @@ export interface Chats {
      * The answer of a client tool's call (a tool event's call_id): true when it is the one taken, false when another came
      * first. As a member (as): the app of the member whose turn it is answers it (403 not_your_turn otherwise). A
      * backend tool that returned ai.deferred() — its ToolContext's chatId and callId — is answered here too, by the
-     * server as itself (never as a member), within the while it named.
+     * server as itself (never as a member), within the while it named. A tool that wrote the chat's workspace names the
+     * tree its writes left (workspaceTree: chats.workspace.write's answer, { manifestId, seq }, either or both), as an
+     * answer given at once does (ai.answer(output, { workspaceTree })): the agent's next command waits for the session's
+     * machine to have it.
      */
     answer(id: string, callId: string, output: ToolResult, options?: {
         isError?: boolean;
         as?: string;
+        workspaceTree?: WorkspaceTree;
     }): Promise<boolean>;
     /** A message for one of the agent's subagents at work (an agent event's run_id, a tool call's ctx.runId), at its next step — as a member, held to their rules. */
     sendToSubagent(id: string, runId: string, text: string, options?: {

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

@@ -4,7 +4,8 @@ export { AISchemaError, prepare } from './schema.js';
 export { ToolError } from './tools.js';
 export type { Infer, StandardSchema } from './schema.js';
 export { partial } from './partial.js';
-export type { AISettings, Agent, AgentTool, AgentVersion, Agents, Chat, ChatEvents, ChatGoal, ChatMessage, ChatStreamPart, ChatToolCall, ChatVoice, Chats, CommitTrailer, CreateChat, Decision, Endpoint, EndpointInput, Endpoints, ForkChat, GoalChange, Goals, MemberInput, MessageAttachment, MessageFile, MessageImage, Repo, Repos, SendMessage, SetGoal, Settings, StartVoice, TurnAdvisorCost, TurnArtifact, TurnCost, TurnRunCost, TurnToolCall, VoiceCommand, Voices, Workspaces, } from './chats.js';
-export type { AdvisorDefinition, AgentContext, AgentDefinitionInput, BackendAgent, BackendAgentOptions, BackendRepo, BackendTool, BackendToolOptions, ChatContext, ClientTool, ClientToolOptions, DeferredAnswer, Effort, HttpsToolRef, McpToolRef, PlatformToolName, PlatformToolRef, PreparedOutput, RepoTokenContext, RepoTokens, SubagentDefinition, Thinking, Tool, ToolAnswer, ToolContext, TurnDefinition, TurnMessage, } from './tools.js';
+export type { AISettings, Agent, AgentTool, AgentVersion, Agents, Chat, ChatEvents, ChatGoal, ChatMessage, ChatStreamPart, ChatToolCall, ChatVoice, Chats, CommitTrailer, CreateChat, Decision, Endpoint, EndpointInput, Endpoints, ForkChat, GoalChange, Goals, MemberInput, MessageAttachment, MessageFile, MessageImage, Repo, Repos, SendMessage, SetGoal, Settings, StartVoice, TurnAdvisorCost, TurnArtifact, TurnCost, TurnRunCost, TurnToolCall, VoiceCommand, Voices, WorkspaceFileBody, WorkspaceToken, WorkspaceTokenMinted, WorkspaceTokens, WorkspaceWrite, Workspaces, } from './chats.js';
+export type { EnvVariable, EnvVariables, Pool, PoolKey, PoolKeyEnroll, PoolKeyMinted, PoolKeys, PoolMachine, PoolMachines, PoolState, Pools } from './pools.js';
+export type { AdvisorDefinition, AgentContext, AgentDefinitionInput, BackendAgent, BackendAgentOptions, BackendRepo, BackendTool, BackendToolOptions, ChatContext, ClientTool, ClientToolOptions, DeferredAnswer, Effort, HttpsToolRef, McpToolRef, PlatformToolName, PlatformToolRef, PreparedOutput, RepoTokenContext, RepoTokens, SubagentDefinition, Thinking, Tool, ToolAnswer, ToolContext, ToolReply, ToolWorkspace, TurnDefinition, TurnMessage, WorkspaceTree, } from './tools.js';
 export type { AgentEvent, ChatEvent, GoalEvent, GoalKind, HistoryEvent, HistoryItem, MessageEvent, Publication, ResetEvent, TextEvent, ThinkingEvent, ToolEvent, ToolStatus, TranscriptEvent, TurnEnd, TurnEvent, TurnStatus, VoiceEvent, WaitingReason, } from '../../internal/src/chat.js';
 export type { ToolPart, ToolResult } from '../../internal/src/tool-output.js';

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

@@ -0,0 +1,177 @@
+import type * as modules from '../../internal/src/modules/index.js';
+type Module = ReturnType<typeof modules.ai.client>;
+/** A runner pool of the project's: its machines of one type — an operating system and an architecture. */
+export interface Pool {
+    /** Its id: named by it, or by its name. */
+    id: string;
+    name: string;
+    os: 'linux' | 'macos' | (string & {});
+    arch: 'amd64' | 'arm64' | (string & {});
+    createdAt?: string;
+    /** A listed pool's: how many machines it has. */
+    machines?: number;
+    /** A listed pool's: how many sessions its machines take at once, and hold now. */
+    capacityTotal?: number;
+    capacityUsed?: number;
+    /** A listed pool's: how many sessions wait for a place. */
+    waiting?: number;
+}
+/** A pool's single-use enrolment key: never said again once it is minted. */
+export interface PoolKey {
+    /** Its id: revoked by it. */
+    id: string;
+    label?: string;
+    createdAt?: string;
+    /** When it can no longer be used. */
+    expiresAt?: string;
+    /** When a machine last enrolled with it. */
+    lastUsedAt?: string;
+    revokedAt?: string;
+}
+/**
+ * Where a machine enrols, said with a key as it is minted: `palai enroll --url <url> --key-file <file>`, with
+ * `--server-name <serverName>` when the door's certificate names another host, and `--ca-file <file>` holding
+ * caCertificate when the door's certificate is not publicly trusted.
+ */
+export interface PoolKeyEnroll {
+    url: string;
+    serverName?: string;
+    /** The CA the door's certificate is signed by (PEM): saved to a file, palai enroll --ca-file. */
+    caCertificate?: string;
+}
+/** A key as it is minted: the key, said once, and where a machine enrols with it. */
+export interface PoolKeyMinted extends PoolKey {
+    key: string;
+    /** The enrolment address: palai enroll --url. */
+    enrollUrl?: string;
+    enroll?: PoolKeyEnroll;
+}
+/** A machine of a pool: what it takes and holds, and whether it takes a new session. */
+export interface PoolMachine {
+    /** Its id: cordoned, resumed and deleted by it (ai.machines). */
+    id: string;
+    /** online, offline, or cordoned (it takes no new session). */
+    state: 'online' | 'offline' | 'cordoned' | (string & {});
+    /** How many sessions it takes at once (palai enroll --capacity), and holds now. */
+    capacity: number;
+    used: number;
+    /** Its label, as it enrolled. */
+    label?: string;
+    os?: string;
+    arch?: string;
+    /** Since when it holds none; null: it holds one. */
+    idleSince: string | null;
+    lastSeenAt: string | null;
+    registeredAt: string | null;
+}
+/** A pool's state: what the project's own scaling loop reads to add a machine or take one away. */
+export interface PoolState {
+    pool: {
+        id: string;
+        name: string;
+        os: string;
+        arch: string;
+    };
+    capacityTotal: number;
+    capacityUsed: number;
+    /** How many sessions wait for a place, and since when the oldest waits (null: none waits). */
+    waiting: number;
+    oldestWaitingSince: string | null;
+    machines: PoolMachine[];
+}
+/** A pool's enrolment keys: a machine enrols with one once (`palai enroll --url <enrollUrl> --key-file <file> --capacity <n>`). */
+export interface PoolKeys {
+    /**
+     * Mints one, said once — here, never again — with where a machine enrols (enrollUrl, enroll): saved to a file on the
+     * machine, `palai enroll --url <enrollUrl> --key-file <file> --capacity <n>` (and --server-name, --ca-file when enroll
+     * says them) — never on a command line, where any process on the machine could read it; n is how many sessions the
+     * machine runs at once (1 or more, default 1). A machine enrolled with it serves the project's sessions once whoever
+     * minted it is gone: it is never minted for an environment's token.
+     */
+    create(pool: string, options?: {
+        label?: string;
+        signal?: AbortSignal;
+    }): Promise<PoolKeyMinted>;
+    /** Its keys, none said. */
+    list(pool: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<PoolKey[]>;
+    /** No machine enrols with it any more. */
+    revoke(keyId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/** The project's runner pools: machines of its own its chats' workspaces run on, managed — and scaled — by the project. */
+export interface Pools {
+    /** Makes one, of one type: its machines' os (linux, macos) and arch (amd64, arm64). A name taken already: 409 pool_exists. */
+    create(pool: {
+        name: string;
+        os: 'linux' | 'macos';
+        arch: 'amd64' | 'arm64';
+        signal?: AbortSignal;
+    }): Promise<Pool>;
+    /** Every pool of the project's, with what its machines hold and how many sessions wait. */
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<Pool[]>;
+    /**
+     * Deletes a pool with no machine left in it, by its id or its name: cordon each machine, delete it once it holds no
+     * session (ai.machines.delete), then the pool. One with machines: 409 pool_not_empty.
+     */
+    delete(pool: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** What its owner's scaling loop reads: its machines, the sessions they take and hold, and how many wait. */
+    state(pool: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<PoolState>;
+    readonly keys: PoolKeys;
+}
+/** The machines of the project's pools, by their id (a pool's state names them). */
+export interface PoolMachines {
+    /** It takes no new session; the sessions it holds go on. */
+    cordon(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** A cordoned machine takes sessions again. */
+    resume(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** A cordoned machine that holds no session leaves its pool, its palai agent refused from then (409 machine_not_cordoned, machine_busy). */
+    delete(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+/** One of the project's variables: its name, never its value. */
+export interface EnvVariable {
+    key: string;
+    /** Whether it is a secret (said so in the list); every value is masked in a transcript either way. */
+    secret: boolean;
+    updatedAt: string;
+}
+/**
+ * The project's variables: every command of every session of its agents begun from now has them — on the platform's
+ * Linux machines and on its own pools — beside an agent's own (its definition's env), masked in a transcript. A value
+ * is sealed where the sessions run: never answered, never logged.
+ */
+export interface EnvVariables {
+    /** Sets one, or sets it anew: a value of 1 byte to 32 KiB, no NUL; a secret unless secret: false. */
+    set(key: string, value: string, options?: {
+        secret?: boolean;
+        signal?: AbortSignal;
+    }): Promise<EnvVariable>;
+    /** Sessions begun from now no longer have it. */
+    unset(key: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Their names, sorted — whether each is a secret, and when it was set: never a value. */
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<EnvVariable[]>;
+}
+export declare function poolsOf(module: Module): {
+    pools: Pools;
+    machines: PoolMachines;
+    env: EnvVariables;
+};
+export {};

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

@@ -47,6 +47,30 @@ export interface ToolContext extends ChatContext {
     runId: string;
     /** The subagent that made the call, by its name; null: the agent itself. */
     subagent: string | null;
+    /**
+     * The chat's workspace as the session last wrote it, its writes flushed before the call — absent when the chat
+     * works in none. Read a file of it at that tree (chats.workspace.file(chatId, path, { manifest: manifestId })); a
+     * tool that writes the workspace (chats.workspace.write) answers the tree its writes left with ai.answer(output, {
+     * workspaceTree }), and the agent's next command sees it.
+     */
+    workspace?: ToolWorkspace;
+}
+/** The tree of a chat's workspace a tool is called at: what the session had written, flushed before the call. */
+export interface ToolWorkspace {
+    /** The chat whose workspace it is. */
+    chatId: string;
+    /** The tree: a file of it is read by it (chats.workspace.file's manifest). */
+    manifestId?: string;
+    /** Its place in the workspace's history. */
+    seq?: number;
+}
+/**
+ * The tree a tool's writes left a chat's workspace at — what chats.workspace.write answered ({ manifestId, seq }),
+ * either or both: the session's machine takes it before the agent's next command.
+ */
+export interface WorkspaceTree {
+    manifestId?: string;
+    seq?: number;
 }
 /** The message that opened a turn, as the backend that defines its agent is told of it. */
 export interface TurnMessage {
@@ -93,7 +117,7 @@ export interface BackendToolOptions<S extends StandardSchema> {
      * takes longer returns ai.deferred() at once — a chat's call waits, and the
      * project's server answers it later with chats.answer(ctx.chatId, ctx.callId, output).
      */
-    run(input: Infer<S>, ctx: ToolContext): ToolResult | DeferredAnswer | Promise<ToolResult | DeferredAnswer>;
+    run(input: Infer<S>, ctx: ToolContext): ToolResult | DeferredAnswer | ToolReply | Promise<ToolResult | DeferredAnswer | ToolReply>;
     /** Every call waits for a person's yes (a member of the chat, or the server). */
     approval?: boolean;
     /** The project's machine it runs on (default backend). */
@@ -111,14 +135,20 @@ export interface BackendTool<S extends StandardSchema = StandardSchema> {
     /** The run, its input checked first: what the framework answers the platform's call with — an answer, or one to come (deferred). */
     call(input: unknown, ctx: ToolContext): Promise<ToolAnswer>;
 }
-/** A backend tool's answer as the platform takes it: now (output), or later — the project's server gives it (chats.answer). */
+/** A backend tool's answer as the platform takes it: now (output, and the tree its writes left the workspace at), or later — the project's server gives it (chats.answer). */
 export type ToolAnswer = {
     output: ToolContent[];
     is_error: boolean;
+    workspace_tree?: WireWorkspaceTree;
 } | {
     deferred: true;
     expires_in_seconds?: number;
 };
+/** A workspace's tree as the platform takes it in a tool's answer. */
+export type WireWorkspaceTree = {
+    manifest_id?: string;
+    seq?: number;
+};
 declare const DEFERRED: unique symbol;
 /** What a backend tool's run returns when its answer comes later: ai.deferred(). */
 export interface DeferredAnswer {
@@ -136,6 +166,23 @@ export interface DeferredAnswer {
 export declare function deferred(options?: {
     expiresInSeconds?: number;
 }): DeferredAnswer;
+declare const REPLY: unique symbol;
+/** What a backend tool's run returns with what it says beside its output: ai.answer(output, { workspaceTree }). */
+export interface ToolReply {
+    readonly [REPLY]: true;
+    readonly output: ToolResult;
+    readonly workspaceTree?: WorkspaceTree;
+}
+/** The tree a tool says its writes left, as the platform takes it — refused here when the platform would drop it. */
+export declare function workspaceTreeOf(t: unknown, what: string): WireWorkspaceTree;
+/**
+ * A backend tool's output with the tree its writes left the chat's workspace at (chats.workspace.write's answer):
+ * the session's machine takes that tree before the agent's next command, so the agent sees what the tool wrote. A
+ * tool that wrote and then failed says it with its ToolError (new ToolError(message, { workspaceTree })).
+ */
+export declare function answer(output: ToolResult, options: {
+    workspaceTree: WorkspaceTree;
+}): ToolReply;
 export interface ClientToolOptions<S extends StandardSchema> {
     name: string;
     description: string;
@@ -252,6 +299,15 @@ export interface AgentDefinitionInput {
     thinking?: Thinking;
     /** The language of the person the turn works for, a BCP 47 tag (tr, en-GB): the model writes to them in it on every step, and so do its subagents. */
     language?: string;
+    /**
+     * The agent's own variables, name → value (64 at most; a name upper-case letters, digits and _, a letter first, not
+     * PALAI_…; a value 32 KiB at most): every command of its sessions has them, on every pool, beside the project's
+     * (ai.env.set), masked in a transcript. A value is never read back — a definition read says each name with '' — and a
+     * name written with '' keeps the value it has.
+     */
+    env?: Record<string, string>;
+    /** 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;
     /**
      * The shape of its one-shot answers (ai.generate({ agent, prompt })): a zod (valibot, arktype) object schema, or
      * ai.schema(name, schema) — checked as generate's schema is, here, when the definition is written. A chat's turns
@@ -327,9 +383,17 @@ export interface DeclaredAI {
  * may name what the chat is not to read); the whole of it is in the app's log.
  */
 export declare class ToolError extends Error {
-    constructor(message: string);
+    /** The tree the tool's writes left the chat's workspace at before it failed: what it wrote, the agent sees all the same. */
+    readonly workspaceTree?: WorkspaceTree;
+    constructor(message: string, options?: {
+        workspaceTree?: WorkspaceTree;
+    });
 }
 export declare const AGENT_NAME: RegExp;
+export declare const POOL_REF: RegExp;
+export declare const LABEL_RULE = "128 bytes at most, no control, format (bidi, zero-width) or line-separator character";
+/** Whether a label is one the module takes: 128 bytes at most, shown as it was written. */
+export declare function shownAsWritten(label: unknown): label is string;
 /** The input's JSON Schema: an object, written out (no references), as a provider takes a tool's parameters. */
 export declare function parametersOf(schema: StandardSchema | undefined, what: string): Record<string, unknown>;
 export declare function backendTool<S extends StandardSchema>(o: BackendToolOptions<S>): BackendTool<S>;
@@ -375,6 +439,10 @@ export declare function backendAgentOf(v: unknown): {
 export declare function toolRef(t: Tool, what: string): ToolRef;
 /** The most tool calls a turn or a one-shot answer makes: the engine's own bound. */
 export declare const MAX_TOOL_CALLS = 10000;
+export declare const ENV_KEY: RegExp;
+export declare const MAX_ENV_VALUE_BYTES: number;
+/** Whether a name is one a variable may have: never one of PALAI_…, the engine's own. */
+export declare function envKeyOk(key: unknown): key is string;
 /** The shape of an agent's one-shot answers as the module takes it: the JSON Schema generate's schema is sent as. */
 export declare function outputOf(v: StandardSchema | PreparedOutput, what: string): Record<string, unknown>;
 /** A definition's bound on its tool calls, refused here as the module would refuse it. */

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

@@ -206,7 +206,7 @@ export type Machine = {
      */
     health_path?: string;
     /**
-     * How many copies of the machine run while it is awake, up to 100 (one on Free), over two nodes at least and no node holding more than half of them: a request is sent to one of them, a copy or a node that goes leaves the others serving, and the cluster takes one of them away at a time at most. Every copy is of the machine's size and counts as such against the project's limits and its machine time (a minute in which the number changed is counted at the most it was). What a copy keeps in its own memory or on its own disk the others do not see — a session, a counter, a cache, a timer: a machine with more than one keeps those where every copy reaches them. The machine finds the number in PALBASE_REPLICAS. A long-lived connection (a WebSocket) stays with the copy that took it.
+     * How many copies of the machine run while it is awake, up to 100 (one on Free), over two nodes at least and a few to a node (each of up to three on a node of its own, at most 29 of a hundred on one): a request is sent to one of them, a copy or a node that goes leaves the others serving, the cluster takes one of them away at a time at most (a tenth of ten or more), and a new version comes up a quarter of them at a time beside the copies that serve. Every copy is of the machine's size and counts as such against the project's limits and its machine time (a minute in which the number changed is counted at the most it was). What a copy keeps in its own memory or on its own disk the others do not see — a session, a counter, a cache, a timer: a machine with more than one keeps those where every copy reaches them. The machine finds the number in PALBASE_REPLICAS. A long-lived connection (a WebSocket) stays with the copy that took it.
      */
     replicas: number;
     /**
@@ -306,7 +306,7 @@ export type MachineCreate = {
      */
     health_path?: string;
     /**
-     * How many copies of the machine run while it is awake, up to 100 (one on Free), over two nodes at least and no node holding more than half of them: a request is sent to one of them, a copy or a node that goes leaves the others serving, and the cluster takes one of them away at a time at most. Every copy is of the machine's size and counts as such against the project's limits and its machine time (a minute in which the number changed is counted at the most it was). What a copy keeps in its own memory or on its own disk the others do not see — a session, a counter, a cache, a timer: a machine with more than one keeps those where every copy reaches them. The machine finds the number in PALBASE_REPLICAS. A long-lived connection (a WebSocket) stays with the copy that took it. One when left out.
+     * How many copies of the machine run while it is awake, up to 100 (one on Free), over two nodes at least and a few to a node (each of up to three on a node of its own, at most 29 of a hundred on one): a request is sent to one of them, a copy or a node that goes leaves the others serving, the cluster takes one of them away at a time at most (a tenth of ten or more), and a new version comes up a quarter of them at a time beside the copies that serve. Every copy is of the machine's size and counts as such against the project's limits and its machine time (a minute in which the number changed is counted at the most it was). What a copy keeps in its own memory or on its own disk the others do not see — a session, a counter, a cache, a timer: a machine with more than one keeps those where every copy reaches them. The machine finds the number in PALBASE_REPLICAS. A long-lived connection (a WebSocket) stays with the copy that took it. One when left out.
      */
     replicas?: number;
     /**
@@ -663,11 +663,11 @@ export type DatabaseUpdate = {
      */
     size?: "dedicated-1x" | "dedicated-2x" | "free" | "hobby" | "standard-16x" | "standard-1x" | "standard-2x" | "standard-32x" | "standard-4x" | "standard-8x" | "starter";
     /**
-     * What it holds, grown, in GB: more than it holds, 1 or a multiple of 5, up to 4,000 — never less (409 `storage_shrinks`), and six hours at least after it last grew (409 `storage_grew_recently`, Retry-After). It grows where it is, serving on; it holds the same through a change of size.
+     * What it holds, grown, in GB: more than it holds, 1 or a multiple of 5, up to 4,000 — never less (409 `storage_shrinks`), and six hours at least after it last grew (409 `storage_grew_recently`, Retry-After) — at once, though, when its organization's owners were told it is 90% full or full at what it holds (`database.storage_warning`, `database.storage_full`). It grows where it is, serving on; it holds the same through a change of size.
      */
     storage_gb?: number;
     /**
-     * Whether it grows by itself: 90% full, by half, to the next multiple of 5 GB, six hours at least after it last grew; off when left out. Of a size on a disk of its own.
+     * Whether it grows by itself: 90% full, by half, to the next multiple of 5 GB, six hours at least after it last grew; as it was when left out. Of a size on a disk of its own.
      */
     storage_autoscaling?: boolean;
 };