palbase 0.7.0 → 0.8.0

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

@@ -25,12 +25,58 @@ export interface ChatContext {
     metadata: Record<string, string>;
     /** Ended when the platform stops waiting for the answer. */
     signal: AbortSignal;
+    /**
+     * The app's instance of a provider — a class a module of the app lists in
+     * its providers, built once by its container with its constructor's
+     * dependencies — as a constructor's parameter of that type is given it:
+     * ctx.inject(Orders). The app that serves the call gives it; a class no
+     * module provides is refused, by name.
+     */
+    inject<T extends object>(provider: abstract new (...args: never[]) => T): T;
 }
 export interface ToolContext extends ChatContext {
     /** The call's id: the same call is the same id, whatever copy of the machine it reaches. */
     callId: string;
+    /** The turn the call is made in: its own response's id — a subagent's call's too. */
+    turnId: string;
+    /**
+     * The run that made the call: the agent's own, or a subagent's at work. A
+     * tool that answers later — it asks a person, and gives their answer to
+     * whoever asked — answers that run: chats.sendToSubagent(chatId, runId, …).
+     */
+    runId: string;
+    /** The subagent that made the call, by its name; null: the agent itself. */
+    subagent: string | null;
+}
+/** The message that opened a turn, as the backend that defines its agent is told of it. */
+export interface TurnMessage {
+    id: string;
+    clientId: string;
+    /** The member who wrote it; null: the project's server. */
+    author: string | null;
+    authorName: string;
+    text: string;
+    delivery: 'next' | 'now' | (string & {});
+    /**
+     * Its writer's labels for it (chats.send({ metadata })) — what an app's
+     * choice for the turn rides on: a model, an effort, the files it names. A
+     * member may write them: the caller's word, not an authority.
+     */
+    metadata: Record<string, string>;
+}
+/** What the backend that defines an agent is told of the turn: the chat's context, and what opened the turn. */
+export interface AgentContext extends ChatContext {
+    /** The message that opened the turn; null: a turn of no message (the chat's voice, its goal). */
+    message: TurnMessage | null;
+    /**
+     * The chat's goal the agent is defined for (chats.goal.set): every turn the
+     * goal opens is the agent defined now. Null: a turn of a message.
+     */
+    goal: {
+        objective: string;
+        rubric: string;
+    } | null;
 }
-export type AgentContext = ChatContext;
 export interface BackendToolOptions<S extends StandardSchema> {
     /** What the agent calls it by: letters, digits, _ and -, starting with a letter, at most 64. */
     name: string;
@@ -43,9 +89,11 @@ export interface BackendToolOptions<S extends StandardSchema> {
      * (`{ mediaType, bytes }`), or a list of them — 4 MiB at most in all. A
      * throw is the tool's failure: a ToolError's message (or the framework's
      * own refusals', NotFound('…')) is told to the agent, anything else as
-     * "The tool failed".
+     * "The tool failed". A tool answers within 110 seconds; one whose work
+     * 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 | Promise<ToolResult>;
+    run(input: Infer<S>, ctx: ToolContext): ToolResult | DeferredAnswer | Promise<ToolResult | DeferredAnswer>;
     /** 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). */
@@ -60,12 +108,34 @@ export interface BackendTool<S extends StandardSchema = StandardSchema> {
     readonly parameters: Record<string, unknown>;
     readonly approval: boolean;
     readonly machine?: string;
-    /** The run, its input checked first: what the framework answers the platform's call with. */
-    call(input: unknown, ctx: ToolContext): Promise<{
-        output: ToolContent[];
-        is_error: boolean;
-    }>;
+    /** 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). */
+export type ToolAnswer = {
+    output: ToolContent[];
+    is_error: boolean;
+} | {
+    deferred: true;
+    expires_in_seconds?: number;
+};
+declare const DEFERRED: unique symbol;
+/** What a backend tool's run returns when its answer comes later: ai.deferred(). */
+export interface DeferredAnswer {
+    readonly [DEFERRED]: true;
+    /** How long the call waits for its answer: a minute to a day; left out, an hour. */
+    readonly expiresInSeconds?: number;
+}
+/**
+ * The answer comes later: a chat's call waits for it — the turn too, as for
+ * an app's tool — and the project's server gives it with chats.answer(chatId,
+ * callId, output) within expiresInSeconds (a minute to a day; an hour). A
+ * call nobody answers by then is told to the agent as unanswered; no member
+ * answers it. A one-shot answer (ai.ask with tools) waits for no call.
+ */
+export declare function deferred(options?: {
+    expiresInSeconds?: number;
+}): DeferredAnswer;
 export interface ClientToolOptions<S extends StandardSchema> {
     name: string;
     description: string;
@@ -94,7 +164,23 @@ export interface McpToolRef {
     only?: string[];
     approval?: boolean;
 }
-export type Tool = BackendTool<StandardSchema> | ClientTool | HttpsToolRef | McpToolRef;
+/** One of the platform's own tools, by name. */
+export type PlatformToolName = 'web.search' | 'web.fetch' | 'workspace.fetch_archive';
+/**
+ * One of the platform's own tools: web.search (the web searched), web.fetch
+ * (a page of it read), workspace.fetch_archive (an archive at a URL unpacked
+ * into the chat's workspace — a workspace's chat has it already). The
+ * agent's alone: its subagents work with the agent's; a one-shot answer has none.
+ */
+export interface PlatformToolRef {
+    source: 'platform';
+    name: PlatformToolName;
+}
+export type Tool = BackendTool<StandardSchema> | ClientTool | HttpsToolRef | McpToolRef | PlatformToolRef;
+/** How hard a model thinks; which rungs a model takes is its catalogue entry's (ai.models(): chat[].efforts). */
+export type Effort = NonNullable<AgentDefinition['effort']>;
+/** Whether a model's reasoning is shown in the chat's stream (thinking parts) or not asked for at all. */
+export type Thinking = NonNullable<AgentDefinition['thinking']>;
 export interface SubagentDefinition {
     /** Unique among the agent's subagents. */
     name: string;
@@ -105,6 +191,12 @@ export interface SubagentDefinition {
     tools?: Tool[];
     /** The turn fails if this subagent's part fails. */
     required?: boolean;
+    /** Left out: the agent's, when it runs on the agent's model (another model's rungs mean other things). */
+    effort?: Effort;
+    /** The window, in tokens, it works in. Left out: the agent's, when it runs on the agent's model. */
+    contextWindow?: number;
+    /** Left out: the agent's. Its reasoning is never in the chat's stream: only the turn's own is. */
+    thinking?: Thinking;
 }
 /** What an agent is for a turn. */
 export interface AgentDefinitionInput {
@@ -114,8 +206,22 @@ export interface AgentDefinitionInput {
     tools?: Tool[];
     /** 16 at most. */
     subagents?: SubagentDefinition[];
-    /** How many tool calls a turn makes at most (1–200): past it the agent is told it has no tools left and answers. */
+    /**
+     * How many tool calls a turn makes at most (1–10 000, the engine's own bound): past it the agent is told it has no
+     * tools left and answers. What a turn spends is its budget's to bound (chats.send({ budget })), not this.
+     */
     maxToolCalls?: number;
+    /** How hard the model thinks (none … max). Left out: the platform's. */
+    effort?: Effort;
+    /**
+     * The window, in tokens, the turn works in: the model's standard one unless said; more is billed as its provider
+     * bills it (ai.models(): chat[].context_window and max_input_tokens).
+     */
+    contextWindow?: number;
+    /** visible: the model's reasoning is in the chat's stream, as thinking parts (the turn's own); hidden: not asked for. Left out: the platform's. */
+    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;
 }
 /** What a backend's agent is for one turn. */
 export type TurnDefinition = AgentDefinitionInput;
@@ -131,6 +237,24 @@ export interface BackendAgent {
         tools: BackendTool[];
     }>;
 }
+/** What one clone or one push of a chat's workspace asks a repository's token with: an ai.repo's token, ai.repoTokens' give. */
+export interface RepoTokenContext {
+    /** The repository's name in the project (ai.repos.put). */
+    repo: string;
+    /** The GitHub repository, owner/name. */
+    repository: string;
+    /** Ended when the platform stops waiting for the token. */
+    signal: AbortSignal;
+    /**
+     * The app's instance of a provider, as a tool's run is given it
+     * (ChatContext.inject): a token a service of the app's mints — its GitHub
+     * App's, its sealed credentials' — from the container of the app that
+     * serves the ask. A class no module provides is refused, by name.
+     */
+    inject<T extends object>(provider: abstract new (...args: never[]) => T): T;
+}
+/** What gives a repository's token when no ai.repo of its name was made: ai.repoTokens(give). */
+export type RepoTokens = (ctx: RepoTokenContext) => string | null | undefined | Promise<string | null | undefined>;
 /** A repository a chat's workspace works in, whose tokens the backend gives (ai.repo). */
 export interface BackendRepo {
     readonly kind: 'repo';
@@ -141,18 +265,16 @@ export interface BackendRepo {
     /** The project's machine that gives its tokens (default backend). */
     readonly machine?: string;
     /** A token for one clone or one push of it: asked at each — a GitHub App's installation token, minted then. */
-    token(ctx: {
-        repo: string;
-        repository: string;
-        signal: AbortSignal;
-    }): Promise<string>;
+    token(ctx: RepoTokenContext): Promise<string>;
 }
 /** What this process declared, for the framework to serve. */
 export interface DeclaredAI {
     tools: Map<string, BackendTool>;
     agents: Map<string, BackendAgent>;
     repos: Map<string, BackendRepo>;
-    /** Names declared twice (tool:<name>, agent:<name>): the framework refuses to start with one. */
+    /** The tokens of a repository put by name at run time, which no ai.repo of this process names. */
+    repoTokens?: RepoTokens;
+    /** Names declared twice (tool:<name>, agent:<name>, repoTokens): the framework refuses to start with one. */
     twice: Set<string>;
 }
 /**
@@ -181,17 +303,32 @@ export declare function backendRepo(options: {
     repository: string;
     defaultBranch?: string;
     machine?: string;
-    token: (ctx: {
-        repo: string;
-        repository: string;
-        signal: AbortSignal;
-    }) => string | Promise<string>;
+    token: (ctx: RepoTokenContext) => string | Promise<string>;
 }): BackendRepo;
+/**
+ * The tokens of the project's repositories put by name at run time
+ * (ai.repos.put(name, { repository, backend })) — one a product makes for
+ * itself — which no ai.repo of this backend names: each clone and each push
+ * of a chat's workspace asks this machine, and give answers with a token for
+ * that one operation, or null for a repository it gives none for (the
+ * workspace is refused it). An ai.repo of the name answers for its own
+ * repository first. Given once, at a module's top level.
+ */
+export declare function repoTokens(give: RepoTokens): void;
 export declare function backendAgent(name: string, define: (ctx: AgentContext) => TurnDefinition | Promise<TurnDefinition>, options?: {
     machine?: string;
 }): BackendAgent;
+/** A backend's agent (an ai.agent's value) — its name and machine — or undefined for anything else. */
+export declare function backendAgentOf(v: unknown): {
+    readonly name: string;
+    readonly machine?: string;
+} | undefined;
 /** A tool as the platform takes it (ToolRef). */
 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;
+/** A definition's bound on its tool calls, refused here as the module would refuse it. */
+export declare function maxToolCallsOf(n: unknown, what: string): number;
 /** A definition as the platform takes it (AgentDefinition). */
 export declare function definitionOf(d: AgentDefinitionInput, what: string): AgentDefinition;
 export {};

package/types/backend/src/bootstrap.d.ts

@@ -70,3 +70,11 @@ export declare class MigrationRunEnded extends Error {
     readonly code: number;
     constructor(code: number);
 }
+/**
+ * The app's CORS joined to the origins of its project's web apps, as the
+ * platform starts it with them (PALBASE_WEB_ORIGINS, comma-separated): a
+ * browser on one of them may call it without the app naming it. Any origin
+ * ("*") stays any. An origin CORS cannot hold (an address in brackets) is
+ * left out, and said.
+ */
+export declare function withWebOrigins(own: CorsOptions | undefined, given: string | undefined, warn?: (message: string) => void): CorsOptions | undefined;

package/types/backend/src/container.d.ts

@@ -14,6 +14,8 @@ export declare class Container {
     private readonly owner;
     private readonly defs;
     private readonly instances;
+    /** The classes the modules list as providers (not controllers): what ctx.inject may be given. */
+    private readonly providers;
     /** Construction order: dependencies before their dependents. */
     readonly order: object[];
     readonly controllers: {
@@ -41,6 +43,13 @@ export declare class Container {
      * a route's @Resolve, by its controller — under a constructor's rules.
      */
     dependencyOf<T extends object>(consumer: abstract new (...args: never[]) => object, dep: abstract new (...args: never[]) => T, at: string): T;
+    /**
+     * The built instance of a provider, asked for by code no module owns — a
+     * tool's run, an agent's function (ctx.inject) — so any module's provider,
+     * exported or not: the class itself, or the one provider that extends it,
+     * as a constructor's parameter of that type finds it. `at` says who asked.
+     */
+    provider<T extends object>(cls: abstract new (...args: never[]) => T, at: string): T;
     private reachable;
     private target;
     /** onStart() of every instance, in construction order; a throw stops the boot after the started ones are shut down. */

package/types/backend/src/database.d.ts

@@ -54,7 +54,7 @@ export interface DatabaseConfig {
  * nothing — `palbase db:plan` and `db:status` ask the app's own Palgres what a
  * start would do and what the database's ledger says.
  */
-export type MigrateMode = 'start' | 'complete' | 'rollback' | 'plan' | 'status';
+export type MigrateMode = 'start' | 'complete' | 'rollback' | 'plan' | 'status' | 'types';
 /** What the deploy asked of this run: a migration step, or nothing (serve). */
 export declare function migrateModeOf(env: Record<string, string | undefined>): MigrateMode | undefined;
 /**
@@ -106,9 +106,24 @@ export type MigrationExit = 0 | 1 | 75;
  * given to such a machine with its migrations on is refused as its release
  * starts, and the release's rollback then ends — the machine is not held by it.
  */
-export declare function migrateWithoutDatabase(mode: MigrateMode): MigrationExit;
+export declare function migrateWithoutDatabase(mode: MigrateMode): Promise<MigrationExit>;
+/**
+ * The app's tables as types (palbase db:types): each table's row, insert, unique keys and relations both ways —
+ * across its schema files, which a schema's own type cannot see (TablesOf) — as the block the CLI writes into
+ * palbase/palbase-env.d.ts. No database is asked: the schema files say it all.
+ */
+export declare function writeTypes(config: DatabaseConfig | undefined, out?: AnswerOut): Promise<MigrationExit>;
 /** The deploy's migration step. */
 export declare function runMigration(config: DatabaseConfig, env: Record<string, string | undefined>, mode: MigrateMode): Promise<MigrationExit>;
+/** Where the step's answer is written: the standard output's stream, done once what it was given is out. */
+export type AnswerOut = (text: string, done: () => void) => void;
+/**
+ * The step's answer, as one line on stdout the CLI reads: {"palbase_migrate": mode, "result": …} — out, and every
+ * log line before it, when this resolves: the run exits right after, and on a pipe what the stream still held went
+ * with the process (a large plan's line was cut at what the pipe took: the CLI read "Unterminated string in JSON at
+ * position 131072"). One stream, in order: a log line is never cut by it.
+ */
+export declare function said(mode: MigrateMode, result: unknown, out?: AnswerOut): Promise<void>;
 export interface OpenDatabase {
     model: Schema;
     binding: Binding;

package/types/backend/src/engine.d.ts

@@ -138,3 +138,5 @@ export interface App {
 }
 export declare const MAX_BODY_BYTES: number;
 export declare function createApp(opts: AppOptions): App;
+/** An origin CORS holds: https://host[:port], http only for localhost, no path. */
+export declare function corsOrigin(origin: string): boolean;

package/types/backend/src/gateways.d.ts

@@ -205,6 +205,21 @@ export declare function matchChannel(pattern: string, channel: string): Record<s
 export declare function channelOf(pattern: string, params: Readonly<Record<string, unknown>>): string | {
     problem: string;
 };
+/** Whose memberships of a gateway's channel are decided again, and whether the channel is over. */
+export interface RevalidateOptions {
+    /** Only this user's membership: the member taken out. */
+    user?: string;
+    /** The channel is over: every member dropped without being asked, its log forgotten — one channel's, every value given. */
+    end?: boolean;
+}
+/**
+ * What realtime is asked to decide again for a gateway's channels: the one channel when every capture of its pattern
+ * has a value, every channel of the pattern with the values given when some do not — or what is wrong with it, as
+ * realtime would refuse it.
+ */
+export declare function revalidationOf(pattern: string, params: Readonly<Record<string, unknown>>, options: RevalidateOptions): realtime.Revalidation | {
+    problem: string;
+};
 /** One event to a gateway's members, as realtime's broadcast takes it: its channel (topic), and conn_id for one membership alone. */
 type GatewayBroadcast = realtime.BroadcastMessage;
 export interface GatewayDeps {
@@ -216,6 +231,8 @@ export interface GatewayDeps {
     run<T>(user: SignedUser | undefined, where: string, signal: AbortSignal | undefined, work: () => Promise<T>): Promise<T>;
     /** realtime's POST /realtime/broadcast, as the app (its secret key). */
     broadcast(messages: GatewayBroadcast[]): Promise<unknown>;
+    /** realtime's POST /realtime/revalidate, as the app: the memberships it names decided again, on every replica. */
+    revalidate(body: realtime.Revalidation): Promise<unknown>;
     /** The platform's infrastructure, not the method, failed: the call is answered 503, and realtime asks again. */
     isOutage(e: unknown): boolean;
 }
@@ -239,6 +256,8 @@ export interface Gateways {
     emit(cls: Function, params: Readonly<Record<string, unknown>>, event: string, payload: unknown): void;
     /** A source piped into a gateway's channel from anywhere in the app (Palbase.gateways.to(…).pipe). */
     pipe(cls: Function, params: Readonly<Record<string, unknown>>, source: PipeSource): Promise<void>;
+    /** A gateway's channel — or its channels of the values given — decided again (Palbase.gateways.to(…).revalidate). */
+    revalidate(cls: Function, params: Readonly<Record<string, unknown>>, options?: RevalidateOptions): Promise<void>;
     /** Every channel let go: what was held is aborted (the app is stopping). */
     close(): void;
 }

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

@@ -4,6 +4,7 @@ export { Task, TaskFailure, Tasks, type EnqueueOptions, type PayloadOf, type Que
 export { Upload, UploadedObject, type UploadConfig } from './upload.js';
 export { Authorize, ChatPart, Gateway, GatewayRefusal, OnConnect, OnDisconnect, OnEmpty, OnFirst, Subscribe, type GatewayAuthorizeContext, type GatewayContext, type GatewayEvents, type GatewayGrant, type GatewayMessageContext, type GatewayOptions, type GatewayUser, type PipeSource, } from './gateways.js';
 export type { GatewaysApi, GatewayTarget } from './runtime.js';
+export type { AgentContext, ToolContext, TurnDefinition, TurnMessage } from '../../ai/src/index.js';
 export { getWebhookManifest, type WebhookEventHandler, type WebhookMeta } from './webhooks.js';
 export { DiError, type DiErrorKind } from './container.js';
 export { BadRequest, Conflict, DeadlockDetected, Forbidden, HttpError, NotFound, PalError, SerializationFailure, TooManyRequests, Unauthorized, UniqueViolation, defineError, type DefinedError, type DefinedErrorWithData, type Envelope, type FieldIssue, } from './errors.js';

package/types/backend/src/runtime.d.ts

@@ -52,9 +52,21 @@ export interface GatewayTarget<G> {
     pipe(source: {
         pipe(topic: string): Promise<void>;
     }): Promise<void>;
+    /**
+     * Who may be on the channel is decided again now, on every replica of realtime — a decision the gateway made may no
+     * longer hold: a member taken out of a chat, a team changed. A member it would no longer let in (its access, its
+     * @Authorize) is dropped, their client told the channel closed; their rejoin is decided on the merits. Params may
+     * leave captures out: every channel of the gateway with the values given. user: only that user's membership. end:
+     * the channel is over — every member dropped without being asked, its log forgotten (one channel, no user).
+     */
+    revalidate(options?: {
+        user?: string;
+        end?: boolean;
+    }): Promise<void>;
 }
 /** The app's gateways, from any service: Palbase.gateways.to(ChatGateway, { chatId }).emit('token', { text }). */
 export interface GatewaysApi {
+    /** A gateway's channel, by its pattern's values — some left out, for revalidate alone: the gateway's channels of the values given. */
     to<G extends Function>(gateway: G, params: Readonly<Record<string, string>>): GatewayTarget<G>;
 }
 /**

package/types/backend/src/testing/unit.d.ts

@@ -4,7 +4,7 @@ import { type FakeClient, type RecordedQuery } from 'palgres/testing';
 import type { CacheClient } from '../cache.js';
 import type { Schemas, Tables } from '../db-env.js';
 import type { Token } from '../decorators.js';
-import { type Logger } from '../runtime.js';
+import { type GatewaysApi, type Logger } from '../runtime.js';
 import type { Flags, Notifications, Realtime, Secrets, StorageService } from '../services.js';
 import { type StringsTable } from '../i18n.js';
 export type { RecordedQuery };
@@ -18,6 +18,8 @@ export interface RuntimeServices {
     Notifications: typeof Notifications;
     Flags: typeof Flags;
     Realtime: typeof Realtime;
+    /** Palbase.gateways: what a service sends a gateway's channel through (to(Gateway, params).emit, .pipe). */
+    Gateways: GatewaysApi;
 }
 /**
  * Runs `fn` with these stand-ins: Database is the client given (its typed

package/types/internal/src/chat.d.ts

@@ -1,7 +1,28 @@
-import type { ChatMessage } from './modules/ai.js';
+import type { ChatMessage, MessageAttachment } from './modules/ai.js';
 export type TurnStatus = 'running' | 'waiting' | 'completed' | 'failed' | 'canceled' | 'timed_out' | 'budget_exceeded';
 export type WaitingReason = 'approval' | 'tool_output' | 'subagents' | 'message';
 export type ToolStatus = 'running' | 'awaiting_output' | 'awaiting_approval' | 'approved' | 'denied' | 'expired' | 'completed' | 'failed' | 'canceled';
+/** How a turn ended, in the chat's words — as its event (ai.response.completed / failed) says it. */
+export type TurnEnd = 'completed' | 'failed' | 'stopped' | 'budget_exceeded';
+/**
+ * A push, a pull request or a merge the agent asked for (a tool part named push, pull_request or merge), and what a
+ * person decides it by: the repository, the branch it writes, the base it targets, the commit it carries.
+ */
+export interface Publication {
+    /** The engine's word: push_branch, open_pull_request, merge_pull_request. */
+    operation: string;
+    /** owner/name. */
+    repository: string;
+    /** The remote as the engine names it. */
+    remote: string;
+    branch: string;
+    /** The branch a pull request targets, or a merge goes into ('' for a push). */
+    base: string;
+    /** The commit it carries. */
+    commit: string;
+    /** The engine's own sentence of it. */
+    display: string;
+}
 /** A member's (or the server's) message, as the agent got it. */
 export interface MessageEvent {
     type: 'message';
@@ -19,7 +40,16 @@ export interface TurnEvent {
     /** On running and waiting: the chat has had one member all its life, as it is now (once a second has been added, never again). */
     solo?: boolean;
     status: TurnStatus;
-    /** Why it waits, and where in its answer — and, for a tool call, which: null unless status is waiting. */
+    /** A turn the chat's goal opened: the goal, the turn's role (work, or verify: the check of a claimed completion) and its number. */
+    goal?: {
+        goal_id: string;
+        role: 'work' | 'verify' | (string & {});
+        seq: number;
+    };
+    /**
+     * Why it waits, and where in its answer — and, for a tool call, which: null unless status is waiting. A publication
+     * waiting on a person's yes names its part (tool_call_id, tool_name push|pull_request|merge) and what it does.
+     */
     waiting: {
         reason: WaitingReason;
         text_offset: number;
@@ -27,8 +57,17 @@ export interface TurnEvent {
         tool_call_id?: string;
         tool_name?: string;
         input?: unknown;
+        expires_at?: string;
+        publication?: Publication;
     } | null;
+    /** How it ended, once it has: completed, failed, stopped (a member or the server, or the chat went), budget_exceeded. */
+    end?: TurnEnd | (string & {});
+    /** Why, when it did not complete and was not stopped — and whether asking again may go otherwise. */
     error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    } | {
         code?: string;
         message?: string;
     } | string | null;
@@ -47,6 +86,92 @@ export interface ResetEvent {
     response_id: string;
     offset: number;
 }
+/**
+ * The model's reasoning as it thinks, when the agent shows it (thinking: visible): a window of a step's at a time,
+ * each after the one before — the turn's own, never a subagent's.
+ */
+export interface ThinkingEvent {
+    type: 'thinking';
+    seq: number;
+    response_id: string;
+    run_id: string;
+    /** The model step it is of: its windows go together, its reasoning before what the step writes. */
+    step_id?: string;
+    text: string;
+    /**
+     * The model's provider would not give its reasoning (an OpenAI organization not verified for reasoning
+     * summaries): said once for the turn, with the model and the provider's reason — and no text.
+     */
+    unavailable?: true;
+    model?: string;
+    reason?: string;
+}
+export type GoalKind = 'set' | 'updated' | 'turn_started' | 'judged' | 'verified' | 'status_changed' | 'cleared';
+/** A word of the chat's goal: set, changed, a turn of it begun, a turn judged, a claimed completion checked, its status, cleared. */
+export interface GoalEvent {
+    type: 'goal';
+    /** The journal's sequence. */
+    seq: number;
+    goal_id: string;
+    kind: GoalKind | (string & {});
+    /** set and updated: the goal as it is now. */
+    goal?: {
+        objective: string;
+        rubric: string;
+        status: string;
+        stop_code: string;
+        stop_reason: string;
+        phase: string;
+        max_turns?: number | null;
+        max_cost_usd?: number | null;
+    };
+    /** updated: what changed. */
+    changed?: unknown;
+    /** turn_started: the turn's role (work, verify), its number among the goal's turns (the part's seq), its response. */
+    role?: string;
+    turn?: number;
+    response_id?: string;
+    run_id?: string;
+    /** judged and verified: the evaluator's word, and why; verified: what is missing. */
+    verdict?: string;
+    reason?: string;
+    missing?: unknown;
+    /** status_changed: from what to what, and the stop's code (cleared: reason too). */
+    from?: string;
+    to?: string;
+    code?: string;
+}
+/** One message or answer of what a fork began with. */
+export interface HistoryItem {
+    /** user: a member's message, or the server's; assistant: the agent's answer. */
+    role: 'user' | 'assistant';
+    message_id?: string;
+    client_id?: string;
+    author?: string | null;
+    author_name?: string;
+    text: string;
+    metadata?: Record<string, string>;
+    created_at?: string;
+    /** An answer's response, in the chat it was forked from. */
+    response_id?: string;
+    /** Its text here is the first of a longer one: the fork's model read it whole. */
+    text_truncated?: boolean;
+    /** A message's pictures and files ([] or absent for none), as the chat it was forked from had them. */
+    attachments?: MessageAttachment[];
+}
+/** What a fork began with: the chat's messages and its agent's answers before the message it was cut before, a few to a part — written first in the fork's channel. */
+export interface HistoryEvent {
+    type: 'history';
+    /** The chat it was forked from, and the message it was cut before. */
+    forked_from: {
+        chat_id: string;
+        before_message: string;
+    } | null;
+    /** This part's place among the history's parts, and how many there are. */
+    part: number;
+    parts: number;
+    items: HistoryItem[];
+}
 /** A tool call, each time its state changes. */
 export interface ToolEvent {
     type: 'tool';
@@ -68,6 +193,16 @@ export interface ToolEvent {
     is_error?: boolean;
     /** The subagent's response that made the call, when one did. */
     agent_response_id?: string | null;
+    /** A publication's part (named push, pull_request or merge, its call_id the publication's id): what it does and where. */
+    publication?: Publication;
+    /** When its approval lapses, while it waits for one. */
+    expires_at?: string;
+    /**
+     * Its answer is shown by its end (output: its last 16 KiB): how many bytes before it were left out, and that the
+     * part was cut to fit the channel — the whole answer is read by its call (chatToolCall).
+     */
+    omittedBytes: number;
+    outputTruncated: boolean;
     [field: string]: unknown;
 }
 /** A subagent at work — or one the agent asked for and was refused (status denied, with its reason). */
@@ -88,7 +223,37 @@ export interface AgentEvent {
     reason?: string;
     [field: string]: unknown;
 }
-export type ChatEvent = MessageEvent | TurnEvent | TextEvent | ResetEvent | ToolEvent | AgentEvent;
+/** The chat's live voice began, or ended: whose it is, what becomes of what is asked of it, how long it lasted, why it ended. */
+export interface VoiceEvent {
+    type: 'voice';
+    /** The journal's sequence of its start; 0 for its end, told from the module's record under the voice's id. */
+    seq: number;
+    voice_id: string;
+    /** Its member; null: the server's own. */
+    user_id: string | null;
+    /** chat: what the person asks for is a turn of the chat; events: the backend's to do (ai.voice.delegated). */
+    delegation: 'chat' | 'events' | (string & {});
+    status: 'started' | 'closed' | (string & {});
+    /** On closed: how long it lasted, and why it ended (close_requested, member_removed, chat_deleted, replaced, lost, …). */
+    seconds?: number;
+    close_reason?: string;
+}
+/** A line said in the chat's voice — the person's (user) or the voice's (assistant): a message of kind voice of its history. */
+export interface TranscriptEvent {
+    type: 'transcript';
+    seq: number;
+    /** The line's id: its message's in the chat's history. */
+    id: string;
+    voice_id: string;
+    role: 'user' | 'assistant' | (string & {});
+    /** The member who said it; null: the voice. */
+    user_id: string | null;
+    author_name: string;
+    text: string;
+    final: boolean;
+    created_at: string;
+}
+export type ChatEvent = MessageEvent | TurnEvent | TextEvent | ResetEvent | ThinkingEvent | ToolEvent | AgentEvent | GoalEvent | HistoryEvent | VoiceEvent | TranscriptEvent;
 /** A chat refusal of the module's, said in words its caller can act on; anything else (or one said already) as it was. */
 export declare function chatRefusal(e: unknown): unknown;
 /** The same promise, its chat refusals said as chatRefusal says them. */