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

package/dist/types/runtime/extra-tool.d.ts

@@ -0,0 +1,16 @@
+import type { AgentToolsModel } from "@ykurilov/agent-chat-core";
+import type { Tool } from "ai";
+import type { AgentFlow } from "../format/flow-format.js";
+import type { FlowRuntime } from "./flow-events.js";
+/**
+ * Служебный инструмент сценария из своего файла. Набор зависит только от версии сценария, а не от состояния: кэш цел.
+ * Сценарий без нужных полей — инструмента нет, набор как в 0.48.
+ */
+export interface FlowExtraTool {
+    name: string;
+    wanted(flow: AgentFlow): boolean;
+    make(input: {
+        runtime: FlowRuntime;
+        model: AgentToolsModel;
+    }): Tool;
+}

package/dist/types/runtime/first-message-retry.d.ts

@@ -0,0 +1,4 @@
+/** Ход «пишет первым» не начался или приложение сказало «не сейчас» (`canWriteNow` → `false`): касание — через час. */
+export declare const FIRST_MESSAGE_RETRY_MS = 3600000;
+/** `canWriteNow` → `{ retryAt }` в прошлом: повтор не чаще, чем раз в минуту. */
+export declare const FIRST_MESSAGE_MIN_RETRY_MS = 60000;

package/dist/types/runtime/first-message-rules.d.ts

@@ -0,0 +1,55 @@
+import type { FlowSchedule } from "../format/flow-format.js";
+import type { FirstMessagesSetting } from "../engine/flow-run.js";
+import type { FlowChatRecord, FlowStore } from "../store/flow-store.js";
+import type { FirstMessageRules, FlowPeople } from "./flow-types.js";
+/** Что в записи чата запрещает писать первым. */
+export type FlowChatWriteState = Pick<FlowChatRecord, "dayClosedOn" | "pausedUntil" | "windowClosed">;
+/**
+ * Запрет из записи чата, до правил приложения: окно канала закрыто — молчать до сообщения человека (`retryAt: null`);
+ * пауза сотрудника — до её конца; агент закрыл день — до начала следующего. Нет запрета — `null`.
+ */
+export declare function chatWriteBlock(chat: FlowChatWriteState, at: number, timeZone: string, schedule: FlowSchedule | undefined): {
+    retryAt: number | null;
+} | null;
+/** Правила «писать первым» на хранилище счётчиков; `false` в настройках — `null`, агент пишет первым без ограничений. */
+export declare function createFirstMessageRules(setting: FirstMessagesSetting | undefined, store: FlowStore): FirstMessageRules | null;
+/** Пояс чата ещё не известен: страница его не присылала. */
+export declare const UNKNOWN_TIME_ZONE = "";
+export declare const serverTimeZone: () => string;
+/**
+ * Пояс страницы из пояса хода. Ядро с 0.53 говорит его прямо (`pageTimeZone`). Без этого поля: ядро без пояса страницы
+ * подставляет запасной (приложения или сервера), поэтому совпадение с запасным — «страница пояс не прислала»: такой пояс
+ * не затирает известный пояс чата.
+ */
+export declare function pageTimeZone(turnZone: string, appZone: string | undefined, sent?: string | null): string | null;
+/**
+ * Пояс чата для таймеров: известный (человека или со страницы), иначе `defaultTimeZone`, иначе приложения, иначе
+ * сервера — с предупреждением один раз на чат.
+ */
+export declare function createChatTimeZones(input: {
+    appTimeZone: () => string | undefined;
+    defaultTimeZone?: string;
+    warn: (message: string) => void;
+}): {
+    of(chatId: string, stored: string): string;
+};
+/** Пояс IANA в каноническом виде («asia/novosibirsk» → «Asia/Novosibirsk»); не пояс — `null`. */
+export declare function ianaTimeZone(value: string): string | null;
+/** Пояс человека: один на все его разговоры. Копия в записи чата — для таймеров, которые читают её без ожидания. */
+export interface FlowTimeZones {
+    /** Известный пояс: записанный человеку, иначе узнанный в этом чате. Не знаем — `null`. */
+    known(ownerId: string, chatId: string): Promise<string | null>;
+    /** Пояс для счёта: известный, иначе приложения или сервера. */
+    of(ownerId: string, chatId: string): Promise<string>;
+    /** Запасной пояс чата, пока пояс человека неизвестен: приложения или сервера. */
+    fallback(chatId: string): string;
+    /** Пояс узнан (страница, слова человека): человеку и копия в запись чата. */
+    write(ownerId: string, chatId: string, timeZone: string): Promise<void>;
+}
+/** Пояса людей: адаптер приложения `people` или таблица модуля; запасной — `fallback` (приложения или сервера). */
+export declare function createFlowTimeZones(input: {
+    store: FlowStore;
+    people?: FlowPeople;
+    fallback: (chatId: string) => string;
+    now: () => number;
+}): FlowTimeZones;

package/dist/types/runtime/first-reasons-notice.d.ts

@@ -0,0 +1,9 @@
+import type { AgentFlow } from "../format/flow-format.js";
+import type { FlowFirstReason } from "../engine/nudges.js";
+import type { FlowNotice } from "./flow-types.js";
+/**
+ * Служебное сообщение хода «пишет первым». Только переход ноды — прежнее «Сработало: …» (как в 0.48); есть другие
+ * причины — их список и задача «новое и полезное». `data.exitId` — переход, который применит ход; `data.nudgeStep` —
+ * шаг ряда касаний после хода (после перехода и утреннего — 0, ряд заново); `data.nudgeStepOwn` — его насчитал свой ряд ноды на N дней (`ownNudge`).
+ */
+export declare function firstReasonsNotice(flow: AgentFlow, reasons: readonly FlowFirstReason[], exitId: string | null, ownNudge?: boolean): FlowNotice;

package/dist/types/runtime/flow-delivery.d.ts

@@ -0,0 +1,53 @@
+import { type StoredMessage } from "@ykurilov/agent-chat-core";
+import type { FlowFirstReason } from "../engine/nudges.js";
+import type { FlowChatRecord } from "../store/flow-store.js";
+import type { FirstMessageRules, FlowAttachment, FlowDeliveryOutcome, FlowDeliveryReport, FlowOutgoing, FlowPort } from "./flow-types.js";
+import { type FlowRuntime } from "./flow-events.js";
+import type { FlowFinisher } from "./flow-finish.js";
+/** Срок записи о повторе доставки в таблице сроков. */
+export declare const FLOW_DELIVERY_EXIT = "@delivery";
+/** Ход «пишет первым» закончен: что ушло и когда. */
+export interface FirstTurnAnswer {
+    ownerId: string;
+    chatId: string;
+    /** Готовый ответ хода (`awaitAnswer`); нет — каналы SDK. */
+    answer: {
+        messageId: string;
+        text: string;
+        status: string;
+        parts: StoredMessage["parts"];
+    } | undefined;
+    reasons: FlowFirstReason[];
+    /** Момент хода по часам чата и пояс человека: счётчик дня. */
+    at: number;
+    timeZone: string;
+}
+export interface FlowDelivery {
+    /** У приложения своя доставка (`attach({ deliver })`). Нет — доставляют каналы SDK, как в 0.48. */
+    own(): boolean;
+    /** Отдать ответ в `deliver` и разобрать исход. */
+    send(message: FlowOutgoing): Promise<FlowDeliveryOutcome>;
+    /** Исход из каналов SDK (`reportDelivery`). */
+    report(input: FlowDeliveryReport): Promise<void>;
+    /** Ход «пишет первым» закончен: своя доставка — первая попытка; каналы SDK — в счётчик дня сразу (как в 0.48). Итог попытки; нечего отдавать — `null`. */
+    afterFirstTurn(turn: FirstTurnAnswer): Promise<FlowDeliveryOutcome["status"] | null>;
+    /** Наступил срок повтора (`record.delivery`): тот же текст, тот же `messageId`, без нового хода. Итог попытки; повторять нечего — `null`. */
+    retry(record: FlowChatRecord, serverAt: number): Promise<FlowDeliveryOutcome["status"] | null>;
+}
+export declare function createFlowDelivery(input: {
+    runtime: FlowRuntime;
+    deliver: () => FlowAttachment["deliver"];
+    port?: (chat: {
+        ownerId: string;
+        chatId: string;
+    }) => Promise<FlowPort>;
+    finish?: () => FlowFinisher;
+    firstMessages?: () => FirstMessageRules | null;
+    timeZoneOf?: (ownerId: string, chatId: string) => Promise<string>;
+    /** Канал SDK сообщил «не доставлено» (`failed`, `window_closed`): касание не засчитано — сроки чата пересчитать. */
+    onUndelivered?: (chat: {
+        ownerId: string;
+        chatId: string;
+        at: number;
+    }) => Promise<void>;
+}): FlowDelivery;

package/dist/types/runtime/flow-events.d.ts

@@ -0,0 +1,126 @@
+import type { Chat } from "@ykurilov/agent-chat-core";
+import type { AgentFlow, FlowExit } from "../format/flow-format.js";
+import { type FlowRun, type Transition } from "../engine/flow-run.js";
+import { describeCondition, type FlowEvent } from "../engine/next-transition.js";
+import type { FlowChatRecord, FlowStore, PendingFlowChange } from "../store/flow-store.js";
+import type { FlowNotice, FlowTransitionEvent } from "./flow-types.js";
+import type { FlowFirstReason } from "../engine/nudges.js";
+import type { FlowTimeZones } from "./first-message-rules.js";
+/**
+ * `FlowRun` в состоянии чата: плюс ответ агента, в начале которого он записан. По нему ожидающий переход судьи узнаёт
+ * свою ветку: правка или «Переделать» начинают ветку с другим ответом — переход снимается.
+ */
+export type ChatFlowRun = FlowRun & {
+    answerId?: string;
+    /** Почему агент пишет первым в ответе `answerId`; ход на сообщение человека — нет. Для хвоста приложения. */
+    firstReasons?: FlowFirstReason[];
+};
+/** Чат закреплён за версией сценария. */
+export interface PinnedFlow {
+    flowId: string;
+    versionId: string;
+    flow: AgentFlow;
+    /** Разговор закончен (`endChat`): инструкция «после конца» вместо правил сценария. */
+    ended?: boolean;
+}
+/** Что общего у частей сценария в службе чата: хранилище, часы, сценарий чата и отчёт о переходах. */
+export interface FlowRuntime {
+    store: FlowStore;
+    now(): number;
+    logError(message: string): void;
+    /** Сценарий чата; с `chat` закрепляет незакреплённый чат за версией (`loadFlow`). `null` — чат без сценария. */
+    chatFlow(ownerId: string, chatId: string, chat?: Chat): Promise<PinnedFlow | null>;
+    /** Фоновая работа, которую ждёт `settled`; нет — не отслеживается (подделки в тестах). */
+    track?(work: Promise<unknown>): void;
+    /** Значения карточки клиента по `id` полей: для условий по данным. */
+    cardValues(ownerId: string): Promise<Record<string, unknown>>;
+    /** Пояс человека; нет — пояс хода (подделки в тестах). */
+    timeZones?: FlowTimeZones;
+    /** `AgentFlowOptions.defaultTimeZone`: пояс хода без страницы и без известного пояса человека — он, а не пояс службы. */
+    defaultTimeZone?: string;
+    /** Переходы случились: копия состояния в хранилище, `onTransition`. Не бросает. */
+    afterTransitions(input: {
+        ownerId: string;
+        chatId: string;
+        pinned: PinnedFlow;
+        run: FlowRun;
+        transitions: Transition[];
+    }): Promise<void>;
+}
+/** Сообщить приложению о переходе (`onTransition`); ошибка приложения не ломает ход. */
+export declare function reportTransition(handler: ((event: FlowTransitionEvent) => void | Promise<void>) | undefined, event: FlowTransitionEvent, logError: (message: string) => void): Promise<void>;
+/** `FlowRun` из состояния чата; нет или не то — `null`. */
+export declare function storedRun(value: unknown): ChatFlowRun | null;
+/** Где чат сейчас: из состояния ветки, а на пустой ветке — старт сценария. */
+export declare function currentRun(flow: AgentFlow, values: Record<string, unknown> | undefined, now: number): ChatFlowRun;
+/**
+ * Куда перенесли чат при закреплении (`loadFlow`, `adopt`): состояние и моменты, от которых считаются сроки, а у идущего
+ * чата — последние слова обеих сторон, шаг касаний и счёт сообщений человека за день. Нет поля — как у нового чата.
+ */
+export interface ChatPlacement {
+    stateId?: string;
+    startedAt?: number;
+    enteredAt?: number;
+    lastHumanAt?: number;
+    lastAgentAt?: number;
+    nudgeStep?: number;
+    /** Сообщения человека за день сценария к моменту `at`. */
+    humanToday?: {
+        at: number;
+        count: number;
+    };
+}
+/**
+ * Место чата, перенесённого в заданное состояние: путь начинается с него, сроки таймеров — от `enteredAt` (нет — от
+ * `startedAt`). Счёт дня ложится в день сценария по поясу `timeZone`; пояса нет — счёт не переносится.
+ */
+export declare function placedRun(flow: AgentFlow, placement: ChatPlacement, now: number, timeZone?: string): ChatFlowRun;
+/** Перенос из записи чата; первый ход его уже записал в состояние (или переноса не было) — `null`. */
+export declare function recordPlacement(record: Pick<FlowChatRecord, "stateId" | "placement">): ChatPlacement | null;
+/**
+ * Где чат сейчас вне хода: из состояния ветки; до первого хода перенесённого чата — из записи переноса; иначе старт.
+ * Так таймеры, `admit` и `readRun` видят перенесённое место, не дожидаясь хода человека.
+ */
+export declare function chatRun(flow: AgentFlow, values: Record<string, unknown> | undefined, record: Pick<FlowChatRecord, "stateId" | "placement"> | null | undefined, now: number, timeZone?: string): ChatFlowRun;
+/**
+ * Пояс человека для шага движка вне подготовки хода, как в `runOutsideTurn`: пояса модуля, без них — из записи чата;
+ * неизвестен — `defaultTimeZone`, иначе сервера.
+ */
+export declare function personTimeZone(runtime: Pick<FlowRuntime, "store" | "timeZones" | "defaultTimeZone">, chat: {
+    ownerId: string;
+    chatId: string;
+}): Promise<string>;
+/** `chatRun` для частей сценария вне хода: запись чата (если не передана) и пояс человека читаются тут. */
+export declare function runOutsideTurn(runtime: Pick<FlowRuntime, "store" | "timeZones">, chat: {
+    ownerId: string;
+    chatId: string;
+}, flow: AgentFlow, values: Record<string, unknown> | undefined, now: number, record?: FlowChatRecord | null): Promise<ChatFlowRun>;
+/**
+ * Шаг движка с проверкой нового состояния: условия по данным и наступившие таймеры, чей срок не зависит от входа
+ * (`overdueOnEntry`). Переходы складываются в `out`. `timeZone` — пояс человека: по нему считаются дни программы.
+ */
+export declare function advance(flow: AgentFlow, run: ChatFlowRun, event: FlowEvent, input: {
+    now: number;
+    card: Record<string, unknown>;
+    out: Transition[];
+    onChainLimit: (run: FlowRun) => void;
+    timeZone: string;
+}): ChatFlowRun;
+/** Событие движка для ожидающего перехода: таймер проверяется заново по своему сроку, судья — как вердикт. */
+export declare function pendingEvent(transition: Transition, timeZone: string): FlowEvent;
+/**
+ * Ожидающее вне хода поверх места ветки — каким место станет к ходу: переходы своей ветки из того же состояния и
+ * события приложения. Само ожидание не трогается.
+ */
+export declare function withPending(flow: AgentFlow, run: ChatFlowRun, pending: readonly PendingFlowChange[], input: Parameters<typeof advance>[3]): ChatFlowRun;
+/** Строка журнала про зацикливание. */
+export declare const chainLimitMessage: (chatId: string, run: FlowRun) => string;
+/** Условие выхода по `id`: своё у состояния или общее. */
+export declare function exitById(flow: AgentFlow, exitId: string): FlowExit | undefined;
+export { describeCondition };
+/** Точный первый текст состояния: агент пишет его слово в слово, без модели, когда это возможно. */
+export declare function exactFirstText(flow: AgentFlow, stateId: string): string | null;
+/** Служебное сообщение модели о переходах вне её ответа: «Сработало: тишина 3 ч → «Напоминание»». */
+export declare function transitionNotice(flow: AgentFlow, transitions: Transition[]): FlowNotice;
+/** Результат инструмента, после которого сменилось состояние: карточка нового состояния и точный первый текст. */
+export declare function transitionReport(flow: AgentFlow, run: FlowRun, transitions: Transition[]): string;

package/dist/types/runtime/flow-finish.d.ts

@@ -0,0 +1,68 @@
+import type { AgentFlow, FlowAfterEnd } from "../format/flow-format.js";
+import type { FlowEndReason, FlowRun, Transition } from "../engine/flow-run.js";
+import type { FirstMessageRules, FlowFinish, FlowPort } from "./flow-types.js";
+import type { ChatFlowRun, FlowRuntime, PinnedFlow } from "./flow-events.js";
+import type { FlowDelivery } from "./flow-delivery.js";
+/** Имя служебного сообщения `app` прощального хода при «срок вышел». */
+export declare const FLOW_DEADLINE_NOTICE = "flow_deadline";
+/**
+ * Что делать с сообщением человека после конца (→ В6). Единственная точка решения: позже здесь встанет передача
+ * следующему сценарию и признак «кто ведёт сейчас» (сценарий, рассылка, сотрудник).
+ */
+export declare function afterEndOf(flow: AgentFlow): FlowAfterEnd;
+/**
+ * Закрывает ли конечная нода разговор. Сценарий с «Днями и временем» или с заданным `afterEnd` — да; иначе, как в 0.48,
+ * агент и дальше отвечает по карточке конечной ноды, а приложение узнаёт о ней только событием.
+ */
+export declare const finalEndsChat: (flow: AgentFlow) => boolean;
+/** Место чата, закрытого вне хода (таймер, перенос): переход в `deadlineState` и отметка конца. О переходе уже сообщено. */
+export declare function endedRun<T extends FlowRun>(flow: AgentFlow, run: T, ended: {
+    endedAt: number;
+    endReason: FlowEndReason;
+}): T;
+export interface FlowDeadlineInput {
+    ownerId: string;
+    chatId: string;
+    pinned: PinnedFlow;
+    run: ChatFlowRun;
+    /** Когда срок вышел, по часам чата. */
+    at: number;
+    timeZone: string;
+}
+export interface FlowFinisher {
+    /** Переходы хода: вход в конечную ноду — конец `final` (или только событие у сценария 0.48). */
+    afterTransitions(input: {
+        ownerId: string;
+        chatId: string;
+        pinned: PinnedFlow;
+        run: FlowRun;
+        transitions: readonly Transition[];
+    }): Promise<void>;
+    /** «Срок вышел»: конец `deadline`, переход в `deadlineState`, событие. Возвращает место после конца. */
+    deadline(input: FlowDeadlineInput): Promise<{
+        run: ChatFlowRun;
+        ended: boolean;
+    }>;
+    /** Прощальный ход при «срок вышел» (→ В5): по правилам «писать первым»; готовый текст — без модели. */
+    farewell(input: FlowDeadlineInput & {
+        port: FlowPort;
+        firstMessages: FirstMessageRules | null;
+        delivery?: FlowDelivery;
+    }): Promise<void>;
+    /** Конец вне хода: «не завершил» (3 дня тишины), «заблокировал» (исход доставки), причина приложения (`flow.end`). Один раз. */
+    end(input: {
+        ownerId: string;
+        chatId: string;
+        pinned: PinnedFlow;
+        run: FlowRun;
+        reason: FlowEndReason;
+        outcome?: string;
+        at: number;
+    }): Promise<{
+        ended: boolean;
+    }>;
+}
+export declare function createFlowFinish(input: {
+    runtime: FlowRuntime;
+    onFinish?: (event: FlowFinish) => void | Promise<void>;
+}): FlowFinisher;

package/dist/types/runtime/flow-known-texts.d.ts

@@ -0,0 +1,11 @@
+import type { ReplyChecksSetting } from "@ykurilov/agent-chat-core";
+import type { AgentFlow } from "../format/flow-format.js";
+/** Тексты сценария: общая часть, ноды, первые сообщения, прощание, рамки дня, попутные задачи. */
+export declare function flowKnownTexts(flow: AgentFlow): string[];
+/**
+ * `replyChecks` службы с текстами сценария чата в `knownTexts` (после своих текстов приложения). Чат без сценария и сбой
+ * чтения сценария — только свои тексты; сбой — строка в журнал.
+ */
+export declare function withFlowKnownTexts(setting: ReplyChecksSetting, flowOf: (ownerId: string, chatId: string) => Promise<{
+    flow: AgentFlow;
+} | null>, logError: (message: string) => void): ReplyChecksSetting;

package/dist/types/runtime/flow-signals.d.ts

@@ -0,0 +1,12 @@
+import type { FlowPort, FlowSignalInput } from "./flow-types.js";
+import { type FlowRuntime } from "./flow-events.js";
+/**
+ * Событие приложения с «будить»: служебное сообщение `app` (`flow_event`), агент отвечает сразу. Переход применит
+ * `prepareTurn` этого хода; у нового состояния точный первый текст — готовый ответ без модели. Срочный сигнал проходит
+ * мимо правил «писать первым» и в счётчик не идёт. Чат занят — событие ждёт начала следующего хода.
+ */
+export declare function sendFlowSignal(input: {
+    runtime: FlowRuntime;
+    port: FlowPort;
+    signal: FlowSignalInput;
+}): Promise<void>;

package/dist/types/runtime/flow-timers.d.ts

@@ -0,0 +1,55 @@
+import type { AgentFlow } from "../format/flow-format.js";
+import type { Transition } from "../engine/flow-run.js";
+import type { FlowChatRecord, FlowStore } from "../store/flow-store.js";
+import type { FirstMessageRules, FlowPort, FlowTimers, FlowTimerSettings } from "./flow-types.js";
+import { type ChatFlowRun } from "./flow-events.js";
+import { type FlowDelivery } from "./flow-delivery.js";
+export declare const DEFAULT_TIMER_TICK_MS = 15000;
+export declare const DEFAULT_TIMER_LEASE_MS = 60000;
+/** Мягкий потолок ходов сервера подряд без сообщения человека у сценария (страховка от петли переходов по таймерам). */
+export declare const DEFAULT_FLOW_SERVER_TURNS_IN_ROW = 50;
+/**
+ * Тик по наступившим срокам: аренда, затем один ход «пишет первым» на все причины срока (переход ноды по таймеру,
+ * утреннее, накопленное, касание) через `deliverNotices` (вид `app`) или готовый текст. По plan.md, «Пишет первым».
+ */
+export declare function createFlowTimers(input: {
+    store: FlowStore;
+    settings: FlowTimerSettings;
+    firstMessages: FirstMessageRules | null;
+    /** Служба чата этого разговора. */
+    port: (chat: {
+        ownerId: string;
+        chatId: string;
+    }) => FlowPort | Promise<FlowPort>;
+    logError: (message: string) => void;
+    now: () => Date;
+    /** Сценарий версии, за которой закреплён чат. */
+    flowOf: (record: FlowChatRecord) => Promise<AgentFlow | null>;
+    /** Пояс человека: известный пояс чата, иначе приложения, иначе сервера (→ В10). */
+    timeZoneOf: (chatId: string, stored: string) => string;
+    cardValues: (ownerId: string) => Promise<Record<string, unknown>>;
+    /** Наступил «срок вышел» (этап 4): конец разговора и прощание. Нет — срок снимается. */
+    onDeadline?: (input: {
+        record: FlowChatRecord;
+        flow: AgentFlow;
+        run: ChatFlowRun;
+        at: number;
+        timeZone: string;
+    }) => Promise<void>;
+    /** «Не завершил»: тишина человека дольше `giveUpAfter` — конец без сообщения. */
+    onGiveUp?: (input: {
+        record: FlowChatRecord;
+        flow: AgentFlow;
+        run: ChatFlowRun;
+        at: number;
+    }) => Promise<void>;
+    /** Переход по таймеру применён в срок без хода: запись чата, `onTransition`, конечная нода. */
+    onAppliedTransitions?: (input: {
+        record: FlowChatRecord;
+        flow: AgentFlow;
+        run: ChatFlowRun;
+        transitions: Transition[];
+    }) => Promise<void>;
+    /** Доставка ответа в каналы приложения и счётчик дня. Нет — каналы SDK, счётчик сразу. */
+    delivery?: () => FlowDelivery;
+}): FlowTimers;

package/dist/types/runtime/flow-tools.d.ts

@@ -0,0 +1,23 @@
+import type { AgentToolsSource } from "@ykurilov/agent-chat-core";
+import { type FlowRuntime, type PinnedFlow } from "./flow-events.js";
+import type { ClientCardTools, FlowJudge, JudgeMessage } from "./flow-types.js";
+import type { FlowExtraTool } from "./extra-tool.js";
+export declare const FLOW_EXIT_TOOL = "flow_exit";
+/** Служебные инструменты возможностей сценария, каждый из своего файла. */
+export declare const FLOW_EXTRA_TOOLS: readonly FlowExtraTool[];
+export interface FlowToolsInput {
+    runtime: FlowRuntime;
+    judge: () => FlowJudge;
+    /** Последние реплики чата для судьи. */
+    history: (ownerId: string, chatId: string) => Promise<JudgeMessage[]>;
+    /** `flow_note` и `client_card`; модуля ещё нет — пусто. */
+    cardTools: () => ClientCardTools["tools"];
+    /**
+     * Сценарий чата, уже прочитанный в этом ходе (`prepareTurn`, инструкция); набор инструментов собирается без ожидания.
+     * Нет — только инструменты 0.48.
+     */
+    knownFlow: (chatId: string) => PinnedFlow | undefined;
+    extraTools?: readonly FlowExtraTool[];
+}
+/** Служебный `flow_exit` и обёртки инструментов приложения: охрана по состоянию, события «вызван инструмент». */
+export declare function withFlowTools(tools: AgentToolsSource | undefined, input: FlowToolsInput): AgentToolsSource;