@ykurilov/agent-chat-background 0.0.0-stage → 0.56.0

package/dist/types/store/sqlite-schema.d.ts

@@ -0,0 +1,431 @@
+import type { HelperProgress, TaskStatus } from "@ykurilov/agent-chat-core";
+import type { ModelMessage } from "ai";
+export declare const backgroundTasks: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "background_tasks";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        ownerId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "owner_id";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        chatId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "chat_id";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        messageId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "message_id";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        toolCallId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "tool_call_id";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        channel: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "channel";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: "max" | "telegram" | "vk" | "web";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["web", "telegram", "vk", "max"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        kind: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "kind";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: "helper" | "tool";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["tool", "helper"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        name: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "name";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        input: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "input";
+            tableName: "background_tasks";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: unknown;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        title: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "title";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "status";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: TaskStatus;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+            $type: TaskStatus;
+        }>;
+        helperMessages: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "helper_messages";
+            tableName: "background_tasks";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: ModelMessage[];
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: ModelMessage[];
+        }>;
+        progress: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "progress";
+            tableName: "background_tasks";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: HelperProgress;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: HelperProgress;
+        }>;
+        result: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "result";
+            tableName: "background_tasks";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: unknown;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        error: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "error";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        leaseOwner: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "lease_owner";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        leaseUntil: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "lease_until";
+            tableName: "background_tasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        attempt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "attempt";
+            tableName: "background_tasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "created_at";
+            tableName: "background_tasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        startedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "started_at";
+            tableName: "background_tasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        finishedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "finished_at";
+            tableName: "background_tasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        deliveredAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "delivered_at";
+            tableName: "background_tasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        deliveryKey: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "delivery_key";
+            tableName: "background_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+    };
+    dialect: 'sqlite';
+}>;

package/dist/types/store/sqlite.d.ts

@@ -0,0 +1,6 @@
+import type { TaskStore } from "../types.js";
+/**
+ * Хранилище задач в файле SQLite. Схема приводится к последней миграции при открытии; файл может быть общим
+ * с хранилищем чатов. Две копии сервера на одном файле делят задачи через аренду.
+ */
+export declare function createSqliteTaskStore(filePath: string, migrationsFolder: string): TaskStore;

package/dist/types/store/task-store.d.ts

@@ -0,0 +1,23 @@
+import type { TaskStatus } from "@ykurilov/agent-chat-core";
+import type { TaskCondition, TaskPatch, TaskRecord } from "../types.js";
+/**
+ * Жизнь задачи в хранилище.
+ * - `queued`/`running` — идёт; аренда у копии сервера, которая её ведёт.
+ * - `awaiting_approval` и законченные — ждут доставки служебного сообщения; аренда у копии, которая доставляет.
+ * - `delivered_at` стоит — чату всё сообщено, аренды нет, задача никому не нужна до следующего события.
+ * Поэтому «задаче нужна копия сервера» — ровно `delivered_at IS NULL`.
+ */
+export declare const RUNNING_STATUSES: readonly ["queued", "running"];
+export declare const FINISHED_STATUSES: readonly ["done", "failed", "canceled", "interrupted", "timed_out"];
+/** О чём чат получает служебное сообщение. */
+export declare const NOTICE_STATUSES: readonly ["done", "failed", "canceled", "interrupted", "timed_out", "awaiting_approval"];
+export declare const isRunningStatus: (status: TaskStatus) => boolean;
+export declare const isFinishedStatus: (status: TaskStatus) => boolean;
+/** Выполнено ли условие записи для задачи. */
+export declare function meetsCondition(task: TaskRecord, when: TaskCondition | undefined): boolean;
+/** Убирает пустые необязательные поля: запись из любого хранилища выглядит одинаково. */
+export declare function withoutEmptyFields(record: TaskRecord): TaskRecord;
+/** Правка (или вся запись) как пары «поле — значение»: переданный `undefined` стирает поле (`null` в базе). */
+export declare function patchEntries(patch: TaskPatch | TaskRecord): Array<[string, unknown]>;
+/** PostgreSQL не хранит символ NUL ни в тексте, ни в jsonb: убираем его до записи. */
+export declare function withoutNul<T>(value: T): T;

package/dist/types/task-delivery.d.ts

@@ -0,0 +1,24 @@
+import type { AgentNotice, BackgroundPort } from "@ykurilov/agent-chat-core";
+import type { TaskRecord, TaskStore } from "./types.js";
+export interface TaskDelivery {
+    /** В чате есть недоставленные итоги, которые держит эта копия: доставить сейчас или, если чат занят, позже. */
+    request(ownerId: string, chatId: string): Promise<void>;
+    /** Ход чата закончился: если чат ждал доставки — пора. */
+    chatFree(ownerId: string, chatId: string): void;
+    /** Повтор для всех чатов, где доставка не удалась (обход по таймеру). */
+    retryPending(): Promise<void>;
+    forget(ownerId: string, chatId: string): void;
+    /** Дождаться доставок, которые уже идут. */
+    idle(): Promise<void>;
+}
+/**
+ * Доставка итогов задач в чат служебными сообщениями. Копия доставляет только задачи со своей арендой. Готовые задачи
+ * чата уходят пачками с ключом из ключей задач: повтор после сбоя ядро не повторит.
+ */
+export declare function createTaskDelivery(deps: {
+    store: TaskStore;
+    leaseOwner: string;
+    port(): BackgroundPort;
+}): TaskDelivery;
+/** Служебное сообщение о задаче, как его видят модель и экран. */
+export declare function noticeOf(task: TaskRecord): AgentNotice;

package/dist/types/task-runner.d.ts

@@ -0,0 +1,51 @@
+import type { BackgroundPort, TaskStatus } from "@ykurilov/agent-chat-core";
+import type { TaskDelivery } from "./task-delivery.js";
+import type { TaskPatch, TaskRecord, TaskStore } from "./types.js";
+/** Чем закончился запуск: статус и поля итога. */
+export type TaskOutcome = TaskPatch & {
+    status: TaskStatus;
+};
+/** Что запуск задачи получает от бегунка. */
+export interface RunControl {
+    signal: AbortSignal;
+    /** Короткий текст хода в карточке; частые вызовы не копят записи. */
+    reportProgress(text: string): void;
+    /** Сохранить шаг (помощник); аренду проверяет перед записью, потерянная аренда обрывает запуск. */
+    saveStep(patch: TaskPatch): Promise<void>;
+}
+/** Как вести задачу; строка — почему её вести нельзя (описания больше нет в настройках). */
+export type TaskPlan = {
+    work(record: TaskRecord, control: RunControl): Promise<TaskOutcome>;
+    rerunAfterRestart: boolean;
+    timeoutMs: number;
+} | string;
+/** Новая задача из вызова инструмента. */
+export type NewTask = Pick<TaskRecord, "ownerId" | "chatId" | "messageId" | "toolCallId" | "channel" | "kind" | "name" | "input" | "title">;
+export interface TaskRunner {
+    start(task: NewTask, maxRunningPerUser: number): Promise<{
+        status: "started";
+        taskId: string;
+    } | {
+        status: "too_many_tasks";
+    }>;
+    cancel(ownerId: string, chatId: string, taskId: string, by: "human" | "agent"): Promise<"canceled" | "not_found" | "already_finished">;
+    answerApproval(ownerId: string, chatId: string, taskId: string, approvalId: string, decision: "allow" | "deny"): Promise<"resumed" | "not_found" | "stale">;
+    chatDeleted(ownerId: string, chatId: string): Promise<void>;
+    /** Подобрать задачи, чья аренда истекла: хозяин пропал. */
+    recoverExpired(): Promise<void>;
+    renewLeases(): Promise<void>;
+    /** Остановить запуски без записи итога и отпустить аренды: следующий старт подберёт задачи сразу. */
+    stop(): Promise<void>;
+}
+/**
+ * Бегунок задач. Задача идёт у той копии сервера, что держит аренду; аренда продлевается по таймеру службы. Итог
+ * пишется, только если аренда ещё наша. Переходы одной задачи (итог, отмена, ответ на подтверждение) идут по одному.
+ */
+export declare function createTaskRunner(deps: {
+    store: TaskStore;
+    leaseOwner: string;
+    leaseMs: number;
+    port(): BackgroundPort;
+    delivery: TaskDelivery;
+    plan(record: TaskRecord): TaskPlan;
+}): TaskRunner;

package/dist/types/task-tools.d.ts

@@ -0,0 +1,13 @@
+import type { AgentToolsModel } from "@ykurilov/agent-chat-core";
+import type { Tool } from "ai";
+import type { TaskRunner } from "./task-runner.js";
+import type { TaskStore } from "./types.js";
+export declare const CHECK_TASKS = "check_tasks";
+export declare const CANCEL_TASK = "cancel_task";
+/** Постоянный блок системной инструкции: один на все ходы, кэш модели не ломает. */
+export declare function backgroundInstructions(maxRunningPerUser: number): string;
+/** `check_tasks` и `cancel_task` для хода: только задачи этого чата. */
+export declare function taskToolsForTurn(model: AgentToolsModel, service: {
+    store: TaskStore;
+    runner(): TaskRunner;
+}): Record<string, Tool>;

package/dist/types/types.d.ts

@@ -0,0 +1,97 @@
+import type { AgentChannel, HelperProgress, TaskStatus } from "@ykurilov/agent-chat-core";
+import type { FlexibleSchema, ModelMessage } from "ai";
+/** Задача, как она лежит в хранилище. Времена — ISO 8601. */
+export interface TaskRecord {
+    id: string;
+    ownerId: string;
+    chatId: string;
+    messageId: string;
+    toolCallId: string;
+    channel: AgentChannel;
+    kind: "tool" | "helper";
+    /** Имя фонового инструмента или помощника. */
+    name: string;
+    input?: unknown;
+    /** Для карточки и служебного сообщения. */
+    title: string;
+    status: TaskStatus;
+    /** Шаги помощника: с них задача продолжается после перезапуска. */
+    helperMessages?: ModelMessage[];
+    progress?: HelperProgress;
+    result?: unknown;
+    error?: string;
+    leaseOwner?: string;
+    leaseUntil?: string;
+    attempt: number;
+    createdAt: string;
+    startedAt?: string;
+    finishedAt?: string;
+    /** Когда служебное сообщение о конце задачи попало в чат. */
+    deliveredAt?: string;
+    /** Ключ служебного сообщения, с которым задачу начали доставлять: повтор после сбоя идёт той же пачкой и с тем же ключом. */
+    deliveryKey?: string;
+}
+/** Поля, которые меняются у уже созданной задачи. */
+export type TaskPatch = Partial<Omit<TaskRecord, "id" | "ownerId" | "chatId" | "createdAt">>;
+/** Условие записи: аренда у этой копии, статус из списка, задача ждёт ответа именно на этот вопрос. */
+export interface TaskCondition {
+    leaseOwner?: string;
+    statuses?: readonly TaskStatus[];
+    pendingApprovalId?: string;
+}
+/** Хранилище задач: память, SQLite, Postgres (контракт один). Каждая операция владельца проверяет сама. */
+export interface TaskStore {
+    create(task: TaskRecord): Promise<void>;
+    get(ownerId: string, taskId: string): Promise<TaskRecord | null>;
+    /** `when` — запись одним условным обновлением: условие не выполнено (задачу забрали, статус сменился) — `null`, запись прежняя. */
+    update(ownerId: string, taskId: string, patch: TaskPatch, when?: TaskCondition): Promise<TaskRecord | null>;
+    listForChat(ownerId: string, chatId: string): Promise<TaskRecord[]>;
+    /** Сколько задач человека занимают место: `queued` и `running`. Задача на паузе (`awaiting_approval`) место не занимает (T055). */
+    countActive(ownerId: string): Promise<number>;
+    /**
+     * Берёт задачу в работу, если она свободна: ждёт запуска или аренда истекла. Два сервера не возьмут одну задачу.
+     * `null` — не взяли.
+     */
+    claim(taskId: string, leaseOwner: string, leaseUntil: string, now: string): Promise<TaskRecord | null>;
+    /** Продлевает аренду; `false` — задачу уже забрал другой или она закончена. */
+    renewLease(taskId: string, leaseOwner: string, leaseUntil: string): Promise<boolean>;
+    /** Задачи в работе, чья аренда истекла: хозяин пропал (перезапуск, падение). */
+    listExpired(now: string): Promise<TaskRecord[]>;
+    /** Законченные задачи чата, о которых чат ещё не знает. */
+    listUndelivered(ownerId: string, chatId: string): Promise<TaskRecord[]>;
+    /**
+     * Отмечает доставленной пачку с ключом `deliveryKey`. Задачу, которую тем временем продолжили или отменили (ключ
+     * сброшен, статус сменился), не трогает: её ведёт и доставит та копия, что её продолжила или отменила.
+     */
+    markDelivered(taskIds: readonly string[], deliveryKey: string, at: string): Promise<void>;
+    deleteForChat(ownerId: string, chatId: string): Promise<void>;
+    close?(): Promise<void>;
+}
+/** Контекст запуска фонового инструмента. */
+export interface BackgroundRunContext {
+    ownerId: string;
+    chatId: string;
+    /** Сигнал отмены: срабатывает по «Отменить», таймауту и закрытию службы. */
+    signal: AbortSignal;
+    /** Коротко, что делается сейчас; видно в карточке задачи. */
+    reportProgress(text: string): void;
+}
+/** Фоновый инструмент: агент запускает его, ход идёт дальше, итог придёт служебным сообщением. */
+export interface BackgroundToolDefinition<Input = unknown, Output = unknown> {
+    description: string;
+    inputSchema: FlexibleSchema<Input>;
+    /** Название задачи для карточки и служебного сообщения. */
+    title(input: Input): string;
+    run(input: Input, context: BackgroundRunContext): Promise<Output>;
+    /** Спрашивается до запуска, как у обычного инструмента. */
+    needsApproval?: boolean;
+    /** `true` — после перезапуска сервера запустить заново; по умолчанию задача получает «прервана». */
+    rerunAfterRestart?: boolean;
+    /** Предел времени; по умолчанию общий `timeoutMs` службы. */
+    timeoutMs?: number;
+    /**
+     * Пометки инструмента, как у `tool({ metadata })`. `{ externalContent: true }` — задача приносит чужой текст (веб,
+     * письма, файлы): вызов в чате помечен, и живые демонстрации в этом чате не запускаются.
+     */
+    metadata?: Record<string, unknown>;
+}