palbase 0.6.2 → 0.8.0

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

@@ -1,4 +1,3 @@
-import { type ChatStream, type FollowChatOptions } from '../../internal/src/chat.js';
 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';
@@ -10,12 +9,17 @@ export type Endpoint = modules.ai.Endpoint;
 export type Decision = modules.ai.Decision;
 /** What the project allows its chats. */
 export interface AISettings {
-    /** The app's users talk to the project's agents with their own session: start a chat with a named agent, write to the chats they are in. */
+    /** The app's users reach the chats they are members of with their own session (the server starts every chat). */
     clients: boolean;
     /** How many messages one user sends a minute. */
     userMessagesPerMinute: number;
-    /** How much chat history the project keeps; a message past it is refused (409 history_full) until chats are deleted. */
-    historyLimitBytes: number;
+    /**
+     * How much chat history the project keeps; a message past it is refused
+     * (409 history_full) until chats are deleted. A free project keeps 500 MiB
+     * at most; null: no fixed limit — a project with paid rights keeps all of
+     * it, unless it sets a limit of its own.
+     */
+    historyLimitBytes: number | null;
     /** How much it keeps now. */
     historyBytes: number;
 }
@@ -35,9 +39,22 @@ export interface MemberInput {
     userId: string;
     /** How the agent and the others are told who wrote. */
     name?: string;
+    /**
+     * Their address: what the commits their turns' agent makes in the chat's workspace are written as, with their
+     * name. Kept, never served to the chat's other members; their own session says it again, verified, as they write.
+     * Left out: an address of the platform's that names them and reaches no one.
+     */
+    email?: string;
     /** The owner deletes the chat. */
     owner?: boolean;
 }
+/** A git trailer every commit of a chat's workspace carries at its message's end: PalCore-Task: #12, Co-authored-by: …. */
+export interface CommitTrailer {
+    /** Its token, as git takes one: letters, digits and -, at most 64. */
+    key: string;
+    /** One line, 512 bytes at most. */
+    value: string;
+}
 export interface CreateChat {
     /** A named agent of the project (or a backend's ai.agent, put); with a definition, the chat's name for it (default assistant). */
     agent?: string | BackendAgent;
@@ -61,6 +78,12 @@ export interface CreateChat {
         }[];
         /** The agent pushes its commits without a person's yes (the chat's members' messages then reach the repository); otherwise a push waits for a member's approval. */
         autoPush?: boolean;
+        /**
+         * What each of its commits carries at its message's end (16 at most): a task, a link back to the
+         * conversation, a co-author. A commit is written as the member its turn is for (MemberInput.email); a turn
+         * that is no member's commits as the platform.
+         */
+        trailers?: CommitTrailer[];
     };
     signal?: AbortSignal;
 }
@@ -81,7 +104,14 @@ export interface Repos {
         defaultBranch?: string;
         backend?: string;
     }): Promise<Repo>;
-    list(): Promise<Repo[]>;
+    /** A page of the project's repositories, by name (100 unless said, at most 1000; a project puts 10 000): nextCursor pages on. */
+    list(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        repos: Repo[];
+        nextCursor?: string;
+    }>;
     /** A chat's workspace checks it out no more. */
     delete(name: string): Promise<void>;
 }
@@ -97,8 +127,165 @@ export interface SendMessage {
     budget?: {
         maxCostUsd: number;
     };
+    /**
+     * Its writer's labels for it (16 at most, snake_case keys, values of 512 bytes at most) — what an app draws it by:
+     * the files it names, the kind of row it is, the model its writer chose. Kept with it, shown with it in the chat's
+     * stream and its list, and given to the backend that defines the agent of the turn it opens (AgentContext.message).
+     * Sent again with the same clientId, the first message's stand.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * What the model reads with the message and no member does (64 KiB at most): a document the agent needs, how to
+     * open a file the message names. The agent is told it as the project's own words, apart from the writer's; the
+     * chat's stream and its list never show it.
+     */
+    context?: string;
+    /**
+     * Pictures of the project's storage the model is shown with the message (4 at most; png, jpeg, webp or gif by their
+     * bytes, 5 MiB each). Each is copied for the chat as the message is written — what it carried is what the agent
+     * reads, whatever becomes of the file. The server attaches any file of its storage; a member, and the server writing
+     * as one, their own files and a public bucket's (404 attachment_not_found otherwise).
+     */
+    images?: MessageImage[];
+    /**
+     * Files of the project's storage put in the chat's workspace before the agent reads the message, at
+     * .palbase/attachments/<message id>/<filename> (8 at most, 15 MiB each) — the agent is told where. A chat that works
+     * in no workspace takes none (409 no_workspace). Copied, and who may attach which, as images.
+     */
+    files?: MessageFile[];
+    signal?: AbortSignal;
+}
+/** A picture of the project's storage, for the model to be shown with a message. */
+export interface MessageImage {
+    bucket: string;
+    path: string;
+}
+/** A file of the project's storage, for a message to put in its chat's workspace. */
+export interface MessageFile {
+    bucket: string;
+    path: string;
+    /** Its name in the workspace, and what the message calls it; left out, its path's last segment. */
+    filename?: string;
+    /** What the agent is told it is (a media type); left out, what the project's storage says. */
+    contentType?: string;
+}
+/** A picture or a file a message carries ([] for none), its images first — its place among them is its position. */
+export type MessageAttachment = modules.ai.MessageAttachment;
+/** Where to fork a chat: before one of its messages (chats.fork). */
+export interface ForkChat {
+    /** The message the fork is cut before (a message's id): it, and all that came after it, are not the fork's. */
+    beforeMessage: string;
+    /** The fork's title; left out: the chat's. */
+    title?: string;
+    /** Who is in the fork (64 at most); left out: the chat's members, as they are. */
+    members?: MemberInput[];
+    signal?: AbortSignal;
+}
+/** A chat's goal: what it works toward by itself, a turn at a time, and where it stands. */
+export interface ChatGoal {
+    /** The goal's id: a new goal, a new id. */
+    id: string;
+    chatId: string;
+    objective: string;
+    /** What a claimed completion is checked against. */
+    rubric: string;
+    status: 'active' | 'paused' | 'blocked' | 'budget_limited' | 'achieved' | (string & {});
+    /**
+     * Why it last left active, as a stable code (empty while active): paused_by_person, paused_by_client, turn_stopped,
+     * turns_failed, no_progress, judge_unreadable, check_unreadable, needs_person, credit_hold, not_admitted,
+     * budget_spent, turns_used, time_used, achieved.
+     */
+    stopCode: string;
+    /** Why, in a sentence. */
+    stopReason: string;
+    /** What its next turn is: work, or verify (the check of a completion its agent claimed). */
+    phase: 'work' | 'verify' | (string & {});
+    /** The member it was set as; null: the server. */
+    setBy: string | null;
+    /** The most turns it opens; null: no limit. */
+    maxTurns: number | null;
+    /** What it may cost at most, all its turns and their subagents together; null: no limit. */
+    budget: {
+        maxCostUsd: number;
+    } | null;
+    /** What it has used so far: work turns, checks of a claimed completion, dollars (a lower bound while some use has no price), seconds at work. */
+    usage: {
+        turns: number;
+        verifications: number;
+        costUsd: number;
+        costIsLowerBound: boolean;
+        activeSeconds: number;
+    };
+    /** When it was met; null: not yet. */
+    achievedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SetGoal {
+    /** What the chat works toward, in words (4000 characters at most). */
+    objective: string;
+    /** What a claimed completion is checked against (8000 characters at most); left out: the objective itself. */
+    rubric?: string;
+    /** The most turns it opens (1–10 000); left out: no limit. */
+    maxTurns?: number;
+    /** What all its turns may cost at most, in US dollars, their subagents counted. */
+    budget?: {
+        maxCostUsd: number;
+    };
+    /**
+     * The member it is set as: the goal and its turns are theirs, as their message's turn is — they decide and answer
+     * its turns' approvals and app tools, and change and clear it — while they stand where they stood: in the chat and,
+     * its agent defined for them alone, the chat theirs alone. Left out, the server's.
+     */
+    as?: string;
+    signal?: AbortSignal;
+}
+/** What changes of a chat's goal: a field left out is left as it is. */
+export interface GoalChange {
+    /** paused: the goal waits; active: it goes on, its next turn opened at once when none is at work. */
+    status?: 'paused' | 'active';
+    /** Why it is paused, with status paused (500 characters at most): said in its stopReason and its event. */
+    reason?: string;
+    objective?: string;
+    rubric?: string;
+    /** null: no limit. */
+    maxTurns?: number | null;
+    /** null: no limit. */
+    budget?: {
+        maxCostUsd: number;
+    } | null;
+    /** The member the server changes it as: the one it was set as (403 not_your_turn otherwise). */
+    as?: string;
     signal?: AbortSignal;
 }
+/** A chat's goal, from its server: the engine works the chat toward it by itself, a turn at a time. */
+export interface Goals {
+    /**
+     * Sets the chat's goal — replacing any it had: each of its turns is the chat's agent as it is defined now (a
+     * backend's agent is asked, told of the goal: AgentContext.goal), judged when it ends, a claimed completion checked
+     * against the rubric — until it is met, or maxTurns, the budget or a brake stops it. Its first turn opens at once
+     * when no turn of the chat is at work; a member's message goes before its next one. Its turns are the chat's: in its
+     * stream (a turn part that names the goal), billed, stopped by chats.stop. Each change of its status is the event
+     * ai.goal.updated (@On('ai.goal.updated')), and its words are goal parts of the chat's stream.
+     */
+    set(id: string, goal: SetGoal): Promise<ChatGoal>;
+    /** The chat's goal (a 404 when it has none): its status, why it stopped, its next turn, its limits and its use. */
+    get(id: string, options?: {
+        as?: string;
+        signal?: AbortSignal;
+    }): Promise<ChatGoal>;
+    /**
+     * Pauses it (with a reason) or resumes it, edits its words, or changes a limit. An achieved goal is not changed
+     * (409 goal_achieved: set a new one); one whose member no longer stands where they stood when it was set is not
+     * resumed (409 goal_lapsed: clear it, or set another for the chat as it is now).
+     */
+    update(id: string, change: GoalChange): Promise<ChatGoal>;
+    /** No turn of it opens again; one at work finishes as an ordinary turn. ai.goal.updated says it cleared. */
+    clear(id: string, options?: {
+        as?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
 /** What one turn of a chat cost so far, its subagents' calls counted; final once nothing more of it can be settled. */
 export interface TurnCost {
     chatId: string;
@@ -107,9 +294,77 @@ export interface TurnCost {
     outputTokens: number;
     /** In billionths of a US dollar. */
     costNanoUsd: number;
+    /** costNanoUsd in dollars. */
+    usd: number;
     /** A model of the turn has no price: the cost is a lower bound. */
     unpriced: boolean;
     final: boolean;
+    /** The cost run by run so far — the turn's own and each subagent's, by its name and model: a turn at work is read as it spends. */
+    runs: TurnRunCost[];
+}
+/** What one run of a turn — its own, or a subagent's — cost so far. */
+export interface TurnRunCost {
+    runId: string;
+    /** Its response: the turn's, or the subagent's (an agent part's response_id). */
+    responseId: string;
+    /** The run that started it; null for the turn's own. */
+    parentRunId: string | null;
+    /** The subagent it is; '' for the turn's own run. */
+    subagent: string;
+    /** provider:model. */
+    model: string;
+    /** running, completed, failed… */
+    state: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    costNanoUsd: number;
+    usd: number;
+    /** Some of its use had no rate: the cost is a floor. */
+    unpriced: boolean;
+}
+/** One tool call of a chat, its whole answer: the stream shows its end (its last 16 KiB); read whole, its secret shapes masked. */
+export interface ChatToolCall {
+    callId: string;
+    name: string;
+    /** pending, executing, completed, failed… */
+    status: string;
+    /** The run that made it: the turn's, or a subagent's. */
+    runId: string;
+    /** The turn — or the subagent's work in it — that made it. */
+    responseId: string;
+    /** What the agent called it with; null when its arguments, masked, are no JSON. */
+    input: unknown;
+    /** Its answer's text, whole; null: none yet. */
+    output: string | null;
+    outputBytes: number;
+    /** How many pictures it returned. */
+    imageCount: number;
+    isError: boolean;
+}
+/** A tool call of a turn as the engine committed it: what a diff of the files the turn wrote is made of. */
+export interface TurnToolCall {
+    callId: string;
+    name: string;
+    state: string;
+    createdAt: string;
+    updatedAt: string;
+    /** What the agent called it with, as JSON. */
+    arguments: unknown;
+    /** What it returned, as the engine committed it ({ output: [...], is_error } — a platform tool's own JSON); undefined: nothing yet. */
+    result?: unknown;
+}
+/** One part of a chat's stream as its channel carried it: what a page of the chat's past holds (chats.parts). */
+export interface ChatStreamPart {
+    /** message, turn, text, reset, thinking, tool, agent, goal, voice, transcript, history — as the stream says them. */
+    type: string;
+    /** The journal's sequence it was told at; absent for an answer's text, placed by its offset. */
+    id?: number;
+    /** The id the channel told it under. */
+    partId: string;
+    /** What the part says, as the stream says it. */
+    data: Record<string, unknown>;
 }
 /** One artifact a turn's agent published: a build's product from the workspace's Mac, a screenshot, a report. */
 export interface TurnArtifact {
@@ -121,21 +376,127 @@ export interface TurnArtifact {
     checksum: string;
     createdAt: string;
 }
+/** A chat's voice: whose it is, what becomes of what is asked of it out loud, whether it is live, how long, why it ended. */
+export interface ChatVoice {
+    id: string;
+    chatId: string;
+    /** Its member; null: the server's own. */
+    userId: string | null;
+    /** chat: what the person asks for is a turn of the chat as its member, whose answer the voice says; events: ai.voice.delegated. */
+    delegation: 'chat' | 'events' | (string & {});
+    status: 'active' | 'closed' | (string & {});
+    /** How long it has lasted. */
+    seconds: number;
+    startedAt: string;
+    /** null: live. */
+    closedAt: string | null;
+    /** Why it ended: close_requested, member_removed, chat_deleted, replaced, lost, or the provider's word ('' while live). */
+    closeReason: string;
+}
+export interface StartVoice {
+    /** The app's WebRTC offer (an SDP) — the browser's peer connection's (palbase/web's connectVoice makes it). */
+    sdp: string;
+    /** The voice it speaks in; left out, the provider's default. */
+    voice?: string;
+    /**
+     * What becomes of what the person asks for out loud: chat (the default) — a message of the voice's member to the
+     * chat's agent, a turn of the chat, whose answer the voice says back; events — the event ai.voice.delegated, for the
+     * backend to have done and answer with command({ type: 'speak' | 'tell', delegationId }).
+     */
+    delegation?: 'chat' | 'events';
+    /** The member the server starts it for: the voice is theirs (they read, tell and close it), and counts toward their starts (5 an hour). */
+    as?: string;
+    signal?: AbortSignal;
+}
+export interface VoiceCommand {
+    /**
+     * speak: say this exactly and nothing else — once what the voice is saying ends, in the order they came; tell: say it
+     * in your own words; know: keep it in mind; instruct: behave so from now on.
+     */
+    type: 'speak' | 'tell' | 'know' | 'instruct';
+    /** 16 KiB at most. */
+    text: string;
+    /** speak or tell: the request it answers (ai.voice.delegated's delegation_id). */
+    delegationId?: string;
+    /** speak only: cut what the voice is saying and say the text at once. */
+    interrupt?: boolean;
+    /** The voice's member the server tells it as. */
+    as?: string;
+    signal?: AbortSignal;
+}
+/**
+ * A chat's live voice, from its server: the app's WebRTC offer in, the provider's answer out — the audio then goes
+ * between the app and the platform's voice provider. What is said either way is the chat's: transcript parts of its
+ * stream and messages of kind voice of its history. One voice talks in a chat at a time.
+ */
+export interface Voices {
+    /** Starts it: its id and the answer (sdp) for the app's peer connection. Its start is the event ai.voice.started. */
+    start(id: string, voice: StartVoice): Promise<ChatVoice & {
+        sdp: string;
+    }>;
+    /** The voice: its member's, or the server's (403 not_your_voice). */
+    get(id: string, voiceId: string, options?: {
+        as?: string;
+        signal?: AbortSignal;
+    }): Promise<ChatVoice>;
+    /** Gives it text — the server's alone, as itself or as the voice's member; one that has ended is 409 voice_closed. */
+    command(id: string, voiceId: string, command: VoiceCommand): Promise<ChatVoice>;
+    /** Ends it: how long it lasted and why it ended. Its end is the event ai.voice.closed, once. */
+    close(id: string, voiceId: string, options?: {
+        as?: string;
+        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. */
+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
+     * event named (manifest) — a build's product as that publish left it. 64 MiB at most (413 file_too_large: publish a
+     * larger one as the turn's artifact); its digest is the answer's Content-Digest. Read the Response as it comes.
+     */
+    file(id: string, path: string, options?: {
+        manifest?: string;
+        signal?: AbortSignal;
+    }): Promise<globalThis.Response>;
+    /**
+     * Puts one more of the project's repositories (ai.repos.put — one born at work too) in an open chat's workspace,
+     * beside its others, at a branch (its default unless said): cloned before the chat's next turn, and every chat
+     * working in the workspace has it (a fork too). Put again, the same. A chat of no workspace: 409 no_workspace.
+     */
+    addRepo(id: string, repo: {
+        repo: string | BackendRepo;
+        branch?: string;
+        signal?: AbortSignal;
+    }): Promise<Chat>;
+}
 export interface Chats {
     create(chat: CreateChat): Promise<Chat>;
     get(id: string, options?: {
         signal?: AbortSignal;
     }): Promise<Chat>;
-    /** Every chat (the newest first, 100 at most), or a member's. */
+    /**
+     * A page of the chats, the newest first (100 unless said, at most 100):
+     * every chat, or a member's — and, with metadata, only those labelled with
+     * every one of its labels (a product's chats: { project_id: id }).
+     * nextCursor pages on.
+     */
     list(options?: {
         member?: string;
+        metadata?: Record<string, string>;
+        limit?: number;
+        cursor?: string;
         signal?: AbortSignal;
-    }): Promise<Chat[]>;
+    }): Promise<{
+        chats: Chat[];
+        nextCursor?: string;
+    }>;
     /** A turn still running is stopped; its history no longer counts. */
     delete(id: string): Promise<void>;
     members: {
+        /** Puts a member in, or changes one: a field left out is left as it is (email: what their turns' commits are written as). */
         put(id: string, userId: string, member: {
             name?: string;
+            email?: string;
             owner?: boolean;
         }): Promise<Chat>;
         delete(id: string, userId: string): Promise<void>;
@@ -163,28 +524,126 @@ export interface Chats {
         messages: ChatMessage[];
         nextCursor?: string;
     }>;
-    /** What happens in the chat as typed parts, as it happens, followed again after a cut from where the reader is: read with for await, stopped with break or signal. */
-    stream(id: string, options?: FollowChatOptions): ChatStream;
-    /** Stops the turn it is working on: what it wrote stays. Its response's id, or null when none ran. */
-    stop(id: string): Promise<string | null>;
-    /** A tool call that waits for a person's yes (a tool event's approval_id): made. */
-    approve(id: string, approvalId: string, reason?: string): Promise<Decision>;
+    /**
+     * The chat's past as its stream told it, a page at a time from its newest end back: the same parts, in their
+     * order, each under the id the channel told it (partId) — what a client's chat reads past the day its channel
+     * keeps (palbase/web's chat.loadOlder, given this page through the app's backend). A page reads limit of the
+     * chat's events (1–1000; 300) before the cursor, or before the oldest part the app holds of the channel (before:
+     * that part's id — the first page then does not read again the day the channel told); neither, from the newest
+     * end. The one that reaches the chat's start begins where a fork began.
+     */
+    parts(id: string, options?: {
+        limit?: number;
+        cursor?: string;
+        before?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        parts: ChatStreamPart[];
+        nextCursor?: string;
+    }>;
+    /** One tool call of the chat, its whole answer — the stream shows its end — its secret shapes masked as the stream masks them. */
+    toolCall(id: string, callId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ChatToolCall>;
+    /**
+     * A turn's tool calls as the engine committed them — their arguments and results as they were — in their order,
+     * a page at a time (1–500; 100): turn is a message's responseId, or a turn's or an agent part's (a subagent's work).
+     */
+    toolCalls(id: string, options: {
+        turn: string;
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        toolCalls: TurnToolCall[];
+        nextCursor?: string;
+    }>;
+    /** The chat's workspace: a file of a tree it published, a repository put in it at work. */
+    readonly workspace: Workspaces;
+    /**
+     * What happens in the chat — its messages, its turns, the answer as it is written, the tools and subagents — as a
+     * source a gateway pipes into its channel: `ctx.pipe(Palbase.ai.chats.events(id))`. The platform writes the chat
+     * into the channel itself from then on; the backend is not in the stream, and the gateway's members hear it.
+     */
+    events(id: string): ChatEvents;
+    /** Stops the turn it is working on: what it wrote stays. Its response's id, or null when none ran. As a member (as), or as the server. */
+    stop(id: string, options?: {
+        as?: string;
+        signal?: AbortSignal;
+    }): Promise<string | null>;
+    /**
+     * A tool call that waits for a person's yes (a tool event's approval_id): made — a push, a pull request or a merge the
+     * agent asked for too (a tool part named so, its publication saying what and where). As a member (as), the server is
+     * held to their rules — a turn another member began is not theirs to decide (403 not_your_turn); without it, the
+     * server decides any.
+     */
+    approve(id: string, approvalId: string, options?: {
+        reason?: string;
+        as?: string;
+    }): Promise<Decision>;
     /** Not made: the agent is told, with the reason, and goes on. */
-    deny(id: string, approvalId: string, reason?: string): Promise<Decision>;
-    /** 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. */
+    deny(id: string, approvalId: string, options?: {
+        reason?: string;
+        as?: string;
+    }): Promise<Decision>;
+    /**
+     * 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.
+     */
     answer(id: string, callId: string, output: ToolResult, options?: {
         isError?: boolean;
+        as?: string;
     }): Promise<boolean>;
-    /** A message for one of the agent's subagents at work (an agent event's run_id), at its next step. */
+    /** 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?: {
         clientId?: string;
+        as?: string;
     }): Promise<{
         runId: string;
         clientId: string;
     }>;
+    /**
+     * Stops one subagent at work (an agent event's run_id) — with the subagents it started and its background work:
+     * the agent that started it is told a person stopped it, and not to start that work again unless asked, and the
+     * rest of the turn goes on. As a member (as), or as the server; a run that is not a subagent at work in this chat
+     * is a 404. Asked again, the same stop answers as it did.
+     */
+    stopSubagent(id: string, runId: string, options?: {
+        as?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        runId: string;
+    }>;
+    /**
+     * A new chat that begins where this one was before one of its messages — what a person's "edit this message"
+     * makes: send the edited message into it. Its agent, its labels and (unless members says) its members are the
+     * chat's; it begins with the chat's messages and its agent's answers before that message (its subagents' work left
+     * out), which the model reads with the fork's first turn and its pipe writes first (history parts). A chat whose
+     * agent is at work is not forked (409 turn_running); more than 512 KiB before the message is 409 fork_too_large.
+     */
+    fork(id: string, fork: ForkChat): Promise<Chat>;
+    /** The chat's goal: set, read, paused, resumed, changed, cleared. */
+    readonly goal: Goals;
+    /** The chat's live voice: started from the app's WebRTC offer, read, told, closed. */
+    readonly voice: Voices;
+}
+/** A chat's stream as a gateway pipes it into its channel (gateways' PipeSource). */
+export interface ChatEvents {
+    readonly kind: 'ai.chat';
+    readonly chatId: string;
+    /** Writes the chat into the channel from now on — from its start, for a channel that had not been its own. */
+    pipe(topic: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Writes it nowhere from now on. */
+    unpipe(options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
 }
 export interface Agents {
-    /** Names an agent: its definition, or a backend's ai.agent (its chats' turns ask the backend's machine); clients: true lets the app's users start chats with it. */
+    /** Names an agent: its definition, or a backend's ai.agent (its chats' turns ask the backend's machine). */
     put(name: string, definition: AgentDefinitionInput | BackendAgent): Promise<Agent>;
     put(agent: BackendAgent): Promise<Agent>;
     list(): Promise<Agent[]>;
@@ -200,10 +659,11 @@ export interface Endpoints {
 export interface Settings {
     get(): Promise<AISettings>;
     /** A field left out is left as it is; the history kept may be lowered, not raised past the plan's. */
+    /** A field left out is left as it is; historyLimitBytes null clears the project's own limit (the plan's is kept). */
     put(change: {
         clients?: boolean;
         userMessagesPerMinute?: number;
-        historyLimitBytes?: number;
+        historyLimitBytes?: number | null;
     }): Promise<AISettings>;
 }
 /**

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

@@ -1,10 +1,10 @@
 export { createAI, AIResponseError } from './ai.js';
-export type { AI, AIOptions, Ask, AskImage, AskTool, DeepPartial, Embed, Generate, ImageRequest, Images, Job, Message, Model, ObjectStream, Picture, Response, Schema, TextStream, Uploader, Usage, } from './ai.js';
+export type { AI, AIOptions, Ask, AskImage, AskTool, ChatModel, DeepPartial, Embed, Generate, ImageRequest, Images, Job, Message, Model, Models, ObjectStream, Picture, Response, Schema, TextStream, Uploader, Usage, } from './ai.js';
 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, Agents, Chat, ChatMessage, Chats, CreateChat, Decision, Endpoint, EndpointInput, Endpoints, MemberInput, Repo, Repos, SendMessage, Settings, TurnArtifact, TurnCost } from './chats.js';
-export type { AgentContext, AgentDefinitionInput, BackendAgent, BackendRepo, BackendTool, BackendToolOptions, ChatContext, ClientTool, ClientToolOptions, HttpsToolRef, McpToolRef, SubagentDefinition, Tool, ToolContext, TurnDefinition, } from './tools.js';
-export type { AgentEvent, ChatEvent, ChatPosition, ChatStream, MessageEvent, ResetEvent, TextEvent, ToolEvent, ToolStatus, TurnEvent, TurnStatus, WaitingReason } from '../../internal/src/chat.js';
+export type { AISettings, Agent, 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, TurnArtifact, TurnCost, TurnRunCost, TurnToolCall, VoiceCommand, Voices, Workspaces, } from './chats.js';
+export type { AgentContext, AgentDefinitionInput, BackendAgent, BackendRepo, BackendTool, BackendToolOptions, ChatContext, ClientTool, ClientToolOptions, DeferredAnswer, Effort, HttpsToolRef, McpToolRef, PlatformToolName, PlatformToolRef, RepoTokenContext, RepoTokens, SubagentDefinition, Thinking, Tool, ToolAnswer, ToolContext, TurnDefinition, TurnMessage, } 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';