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

package/dist/types/runtime/migrate-chats.d.ts

@@ -0,0 +1,20 @@
+import type { AgentFlow } from "../format/flow-format.js";
+import type { StateMap } from "../engine/migrate-run.js";
+import type { FlowChatRecord, FlowStore, SaveFlowVersionResult } from "../store/flow-store.js";
+import type { ChatMigrator, LoadedFlow } from "./flow-types.js";
+export interface ChatMigratorDeps {
+    store: FlowStore;
+    now: () => Date;
+    /** Разобрать и проверить сценарий приложения; с ошибками — `null`. */
+    checkedFlow(loaded: LoadedFlow): AgentFlow | null;
+    /** Сохранить уже проверенный сценарий версии. */
+    saveVersion(loaded: LoadedFlow, flow: AgentFlow): Promise<SaveFlowVersionResult>;
+    /** Пересчитать таймер переведённого чата по новой версии. Запись чата к этому времени уже на новой версии. */
+    rescheduleMigrated(input: {
+        record: FlowChatRecord;
+        flow: AgentFlow;
+        map: StateMap;
+    }): Promise<void>;
+}
+/** Перевод чатов на новую версию пачками: версия меняется сразу, состояние — в начале следующего хода чата. */
+export declare function createChatMigrator(deps: ChatMigratorDeps): ChatMigrator;

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

@@ -0,0 +1,15 @@
+import { type ToolSet } from "ai";
+import type { FlowStore } from "../store/flow-store.js";
+import type { CardToolsTurn, ClientFactStore } from "./flow-types.js";
+export declare const FLOW_NOTE_TOOL = "flow_note";
+export declare const CLIENT_CARD_TOOL = "client_card";
+/**
+ * `flow_note` (записать узнанное: поле карточки или заметку чата; отметить вопрос между делом) и `client_card` (показать
+ * или стереть то, что агент знает о человеке). Собираются на ход чата: им нужны человек, состояние чата и сценарий.
+ */
+export declare function noteTools(input: {
+    store: FlowStore;
+    now: () => Date;
+    turn: CardToolsTurn;
+    facts?: ClientFactStore;
+}): ToolSet;

package/dist/types/runtime/pause.d.ts

@@ -0,0 +1,21 @@
+import type { FlowPauseInput, FlowPauseSettings, FlowPort, FlowStaffReply } from "./flow-types.js";
+import type { FlowRuntime } from "./flow-events.js";
+/** Пауза длится столько часов после последнего ответа сотрудника; каждый его ответ продлевает (→ В4). */
+export declare const DEFAULT_PAUSE_STAFF_SILENCE_HOURS = 2;
+export interface FlowPauseControl {
+    pause(input: FlowPauseInput): Promise<void>;
+    resume(input: {
+        ownerId: string;
+        chatId: string;
+    }): Promise<void>;
+    /** Ответ сотрудника продлевает паузу на `staffSilenceHours` и попадает в контекст агента. */
+    noteStaffReply(input: FlowStaffReply): Promise<void>;
+}
+export declare function createFlowPause({ runtime, settings, port, }: {
+    runtime: FlowRuntime;
+    settings: FlowPauseSettings;
+    port: (chat: {
+        ownerId: string;
+        chatId: string;
+    }) => Promise<FlowPort>;
+}): FlowPauseControl;

package/dist/types/runtime/prepare-turn.d.ts

@@ -0,0 +1,12 @@
+import type { PrepareTurn } from "@ykurilov/agent-chat-core";
+import { type FlowRuntime } from "./flow-events.js";
+import { type FlowFinisher } from "./flow-finish.js";
+/** Имена служебных сообщений `app`, которые сценарий применяет в начале хода. */
+export declare const FLOW_TIMER_NOTICE = "flow_timer";
+export declare const FLOW_EVENT_NOTICE = "flow_event";
+/**
+ * `agent.prepareTurn` сценария: в начале хода, до застывших блоков, применяет всё, что случилось вне хода — ожидающие
+ * переходы судьи (только на своей ветке), события приложения, перевод версии, наступившие таймеры, — и сообщение
+ * человека («назад» после касаний). Модель получает служебное сообщение «Сработало: …» и уже новую карточку.
+ */
+export declare function flowPrepareTurn(runtime: FlowRuntime, appTimeZone: () => string | undefined, finisher?: () => FlowFinisher): PrepareTurn;

package/dist/types/runtime/side-task-tool.d.ts

@@ -0,0 +1,5 @@
+import type { FlowExtraTool } from "./extra-tool.js";
+export declare const FLOW_SIDE_TASK_TOOL = "flow_side_task";
+/** «осталась 1 попытка», «осталось 2 попытки»: для строки хвоста и ответов инструмента. */
+export declare const sideTaskAttemptsText: (left: number) => string;
+export declare const sideTaskTool: FlowExtraTool;

package/dist/types/runtime/step-tail.d.ts

@@ -0,0 +1,11 @@
+import type { StepContext } from "@ykurilov/agent-chat-core";
+import { type FlowRuntime } from "./flow-events.js";
+import type { FlowTailPart } from "./tail/tail-part.js";
+/** Строки хвоста по порядку: день, рамка дня, попутные задачи. Каждую делает свой модуль. */
+export declare const FLOW_TAIL_PARTS: readonly FlowTailPart[];
+/**
+ * `agent.stepContext` со строками сценария. Номер дня, рамки и попутные задачи — только здесь: хвост не пишется в историю
+ * и стоит после всех кэшируемых частей, постоянная инструкция от дня не зависит. Сначала хвост приложения, затем строки
+ * сценария. Сценарий без «Дней и времени» и попутных задач — хвост приложения как есть.
+ */
+export declare function withStepTail(own: StepContext | undefined, runtime: FlowRuntime, parts?: readonly FlowTailPart[]): StepContext;

package/dist/types/runtime/tail/day-line.d.ts

@@ -0,0 +1,2 @@
+import type { FlowTailPart } from "./tail-part.js";
+export declare const dayLine: FlowTailPart;

package/dist/types/runtime/tail/frame-line.d.ts

@@ -0,0 +1,2 @@
+import type { FlowTailPart } from "./tail-part.js";
+export declare const frameLine: FlowTailPart;

package/dist/types/runtime/tail/side-tasks-line.d.ts

@@ -0,0 +1,2 @@
+import type { FlowTailPart } from "./tail-part.js";
+export declare const sideTasksLine: FlowTailPart;

package/dist/types/runtime/tail/tail-part.d.ts

@@ -0,0 +1,21 @@
+import type { AgentFlow } from "../../format/flow-format.js";
+import type { FlowRun } from "../../engine/flow-run.js";
+import type { FlowRuntime } from "../flow-events.js";
+/** Что видит строка хвоста шага: сценарий чата и место. Моменты — по часам чата. */
+export interface FlowTailInput {
+    ownerId: string;
+    chatId: string;
+    flow: AgentFlow;
+    run: FlowRun;
+    now: number;
+    /** Пояс человека: известный, иначе приложения или сервера. Нет — UTC (строки без «Дней и времени» его не читают). */
+    timeZone?: string;
+    /** Хранилище и карточка клиента: строке, которой нужны данные человека (попутные задачи). Нет — такая строка молчит. */
+    runtime?: FlowRuntime;
+    /** Ход ведёт сотрудник, а не человек: личное ему не предлагаем. */
+    staff?: boolean;
+    /** Пояс человека неизвестен, а сегодня его первый день до первой ночи (В1): тогда агент узнаёт город. Считает этап 4. */
+    askTimeZone?: boolean;
+}
+/** Одна строка хвоста шага; нечего сказать — `null`. */
+export type FlowTailPart = (input: FlowTailInput) => string | null | Promise<string | null>;

package/dist/types/runtime/test-clock.d.ts

@@ -0,0 +1,26 @@
+import { type FlowRun } from "../engine/flow-run.js";
+import { type FlowRuntime } from "./flow-events.js";
+import type { FlowPort, FlowTestClockInput, FlowTimers } from "./flow-types.js";
+/** Ключ данных чата (`Chat.data`) с пометкой тестового чата и сдвигом его часов. */
+export declare const FLOW_TEST_CHAT_KEY = "flowTestChat";
+/** Данные нового тестового чата: `service.createChat(userId, { data: flowTestChatData() })`. */
+export declare function flowTestChatData(): Record<string, unknown>;
+/** Сдвиг часов из данных чата, мс; `null` — чат не тестовый. */
+export declare function testChatOffset(data: Record<string, unknown> | undefined): number | null;
+/** Часы чата, мс: часы сервера плюс сдвиг тестового чата. */
+export declare const chatTime: (run: Pick<FlowRun, "timeOffset"> | null | undefined, serverNow: number) => number;
+/**
+ * Промотать часы тестового чата вперёд: на `ms` или до начала следующего дня сценария (`to: "next_day_start"`). Сдвиг
+ * в данные чата, ближайший таймер пересчитан по новым часам и, если наступил, срабатывает сразу (агент пишет первым по
+ * обычным правилам); возврат — после конца этого хода. Чат не тестовый — ошибка.
+ */
+export declare function advanceTestClock(input: {
+    runtime: FlowRuntime;
+    port: FlowPort;
+    timers: FlowTimers | null;
+    ownerId: string;
+    chatId: string;
+    clock: FlowTestClockInput;
+}): Promise<{
+    timeOffset: number;
+}>;

package/dist/types/runtime/time-zone-tool.d.ts

@@ -0,0 +1,3 @@
+import type { FlowExtraTool } from "./extra-tool.js";
+export declare const FLOW_TIME_ZONE_TOOL = "flow_time_zone";
+export declare const timeZoneTool: FlowExtraTool;

package/dist/types/runtime/turn-gate.d.ts

@@ -0,0 +1,8 @@
+import type { BeforeTurnHandler } from "@ykurilov/agent-chat-core";
+import type { FlowAdmit } from "./admit.js";
+/**
+ * Ворота хода сценария: сообщение человека (`send`) проходит через `admit`. Готовая фраза — `{ reply }`, промолчать —
+ * `{ hold }`. Закончен разговор — по режиму сценария (→ В6): `reply` — ход идёт, агент ответит по общей части;
+ * `silent` — сообщение записано, агент молчит.
+ */
+export declare function flowTurnGate(admit: FlowAdmit): BeforeTurnHandler;

package/dist/types/sqlite.d.ts

@@ -0,0 +1,9 @@
+import { type SqliteFlowStore } from "./store/sqlite.js";
+export type { SqliteFlowStore } from "./store/sqlite.js";
+export { FLOWS_MIGRATIONS_TABLE } from "./store/migration-settings.js";
+export { flowChats, flowClientCards, flowFirstMessages, flowVersions } from "./store/sqlite-schema.js";
+/**
+ * Сценарии в файле SQLite; файл может быть общим с хранилищем чатов (`createSqliteChatStorage`).
+ * Таблицы приводятся к последней миграции при открытии.
+ */
+export declare function sqliteFlowStore(filePath: string): SqliteFlowStore;

package/dist/types/store/flow-store-shared.d.ts

@@ -0,0 +1,20 @@
+import type { StateMap } from "../engine/migrate-run.js";
+import type { ChatsInState, MigrateBatchInput, PendingFlowChange } from "./flow-store.js";
+/** Ожидающий перевод версии. Ключ с временем: перевод v1 → v2 → v1 → v2 не схлопывается в один. */
+export declare function migratePending(input: MigrateBatchInput): PendingFlowChange;
+/** Переход, применённый в срок без хода: «забрать» его не снимает — «Переделать» на той же ветке применит его снова. */
+export declare const appliedInTime: (change: PendingFlowChange) => boolean;
+/**
+ * Ожидающее после `addPending`: новый ключ — в конец; тот же ключ — прежний остаётся, но `appliedAt` нового дописывается,
+ * если его не было (переход отложили ночью, а утром применили в срок). Ничего не изменилось — `null`.
+ */
+export declare function pendingAdded(pending: readonly PendingFlowChange[], change: PendingFlowChange): PendingFlowChange[] | null;
+/** Состояние после перевода: удалённое — по карте, остальное как было. Зеркало для подсчёта до следующего хода. */
+export declare const mappedState: (stateId: string, map: StateMap) => string;
+export declare const byVersionAndState: (left: ChatsInState, right: ChatsInState) => -1 | 0 | 1;
+/** Порядок строк как у базы (`COLLATE "C"` и `BINARY`): по кодам символов, без учёта языка. */
+export declare const compareText: (left: string, right: string) => -1 | 0 | 1;
+/** Время к одному виду: `toISOString` с миллисекундами, как его вернёт база. */
+export declare const normalizeTime: (iso: string) => string;
+/** PostgreSQL не хранит символ NUL ни в тексте, ни в JSON: вырезаем его до записи. */
+export declare function withoutNul<T>(value: T): T;

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

@@ -0,0 +1,240 @@
+import type { AgentFlow } from "../format/flow-format.js";
+import type { FlowEndReason, Transition } from "../engine/flow-run.js";
+import type { StateMap } from "../engine/migrate-run.js";
+/** Что случилось с чатом вне хода; применит `prepareTurn` следующего хода. Повтор с тем же `key` ничего не добавляет. */
+export type PendingFlowChange = {
+    kind: "transition";
+    key: string;
+    transition: Transition;
+    /** Последнее сообщение ветки, на которой решён переход; `null` — пустой чат. Ветку сменили — ожидание снимается. */
+    branchHead: string | null;
+    /**
+     * Переход по таймеру уже применён в срок без хода (писать первым нельзя): запись чата и `onTransition` сделаны,
+     * таймеры идут от новой ноды. Ход только переносит его в состояние чата, не сообщая заново.
+     */
+    appliedAt?: string;
+} | {
+    kind: "event";
+    key: string;
+    name: string;
+    data?: unknown;
+    at: string;
+} | {
+    kind: "migrate";
+    key: string;
+    versionId: string;
+    map: StateMap;
+    at: string;
+};
+/** Чат, который идёт по сценарию: версия закреплена, состояние и ближайший таймер — для выборок и тика. */
+export interface FlowChatRecord {
+    chatId: string;
+    ownerId: string;
+    flowId: string;
+    versionId: string;
+    /** Копия состояния из `FlowRun` для счёта чатов по состояниям. Правда — в состоянии чата. */
+    stateId: string;
+    pending: PendingFlowChange[];
+    /** Ближайший таймер: когда, какое условие и на какой ветке он посчитан. */
+    dueAt: string | null;
+    dueExitId: string | null;
+    dueBranchHead: string | null;
+    /** Пояс человека (IANA): от него «время суток» и тихие часы. Запасной: сначала — пояс человека (`readTimeZone`). */
+    timeZone: string;
+    updatedAt: string;
+    /** Разговор закончился: таймеров и касаний больше нет. */
+    endedAt: string | null;
+    endReason: FlowEndReason | null;
+    /** Пауза «отвечает живой сотрудник» до этого момента; таймеры не берутся. */
+    pausedUntil: string | null;
+    /** Канал приложения закрыл окно: первым не писать до сообщения человека. */
+    windowClosed: boolean;
+    /** День сценария («ГГГГ-ММ-ДД»), который агент закрыл (`flow_close_day`): сегодня первым не пишет. */
+    dayClosedOn: string | null;
+    /** Недоставленный ответ, который ждёт повтора. */
+    delivery: FlowPendingDelivery | null;
+    /** Куда приложение перенесло чат при закреплении; первый ход кладёт это место в состояние чата и снимает запись. */
+    placement: FlowChatPlacement | null;
+}
+/** Моменты, от которых считаются дни и сроки перенесённого чата (ISO). */
+export interface FlowChatPlacement {
+    startedAt: string;
+    enteredAt: string;
+    /** Последнее сообщение человека. */
+    lastHumanAt?: string;
+    /** Последнее сообщение агента: ответ или касание. */
+    lastAgentAt?: string;
+    /** Следующий шаг ряда касаний. */
+    nudgeStep?: number;
+    /** Сколько сообщений человек написал за день сценария к моменту `at`: день считается по поясу человека, когда он известен. */
+    humanToday?: {
+        at: string;
+        count: number;
+    };
+}
+/** Повтор доставки того же текста по ключу `messageId`, без нового хода модели. */
+export interface FlowPendingDelivery {
+    messageId: string;
+    /** Номер следующей попытки, с 1. */
+    attempt: number;
+    retryAt: string;
+    /** Причины хода «пишет первым» — для `FlowOutgoing.reasons`. */
+    reasons: string[];
+}
+export interface PinFlowChatInput {
+    chatId: string;
+    ownerId: string;
+    flowId: string;
+    versionId: string;
+    stateId: string;
+    timeZone: string;
+    /** Чат перенесён в заданное место: до первого хода хранится здесь, переживая перезапуск сервера. */
+    placement?: FlowChatPlacement;
+    at: string;
+}
+export type FlowChatPatch = Partial<Pick<FlowChatRecord, "versionId" | "stateId" | "timeZone" | "placement">>;
+export interface FlowDueInput {
+    at: string;
+    exitId: string;
+    branchHead: string | null;
+}
+export interface RenewLeaseInput {
+    chatId: string;
+    owner: string;
+    now: string;
+    leaseMs: number;
+}
+export interface SetDueOptions {
+    /** Не писать, если чат ждёт повтора доставки: у повтора свой срок, его не затереть. */
+    unlessDelivery?: boolean;
+}
+export interface LeaseDueInput {
+    now: string;
+    /** Копия сервера, которая берёт таймеры. */
+    owner: string;
+    leaseMs: number;
+    limit: number;
+}
+export interface SavedFlowVersion {
+    flowId: string;
+    versionId: string;
+    /** Отпечаток сценария: одна версия — один отпечаток. */
+    hash: string;
+    flow: AgentFlow;
+    createdAt: string;
+}
+/** `same` — эта версия уже сохранена с тем же отпечатком; `conflict` — под тем же номером другой сценарий. */
+export type SaveFlowVersionResult = "new" | "same" | "conflict";
+export interface ChatsInState {
+    versionId: string;
+    stateId: string;
+    chats: number;
+}
+export interface MigrateBatchInput {
+    flowId: string;
+    toVersionId: string;
+    /** Куда перевести чаты из удалённых состояний. */
+    map: StateMap;
+    limit: number;
+    at: string;
+}
+/** Поле карточки клиента: долгая память о человеке по всем его чатам. */
+export interface ClientCardEntry {
+    fieldId: string;
+    value: unknown;
+    updatedAt: string;
+    /** Где узнали. */
+    chatId: string;
+    flowId: string;
+}
+/** Свободный факт о человеке («ведёт блог»): не поле сценария, а короткая фраза, которую агент записал сам. */
+export interface ClientFact {
+    /** Стабильный по тексту (`factId`): тот же факт — тот же id. */
+    id: string;
+    text: string;
+    updatedAt: string;
+    /** Где узнали. */
+    chatId: string;
+    flowId: string;
+}
+export interface WriteCardFieldInput {
+    ownerId: string;
+    fieldId: string;
+    value: unknown;
+    chatId: string;
+    flowId: string;
+    at: string;
+}
+/** Попытки попутной задачи: на человека (`chatId: null`) или на разговор. */
+export interface SideTaskRecord {
+    taskId: string;
+    chatId: string | null;
+    /** Сколько раз агент предложил. */
+    asks: number;
+    doneAt: string | null;
+}
+export interface NoteSideTaskInput {
+    ownerId: string;
+    taskId: string;
+    /** `null` — попытки на человека; id чата — у задач «заново в каждом разговоре». */
+    chatId: string | null;
+    status: "asked" | "done";
+    at: string;
+}
+export interface FlowStore {
+    /** Закрепить версию за чатом. Чат уже закреплён — вернуть как есть, ничего не менять. */
+    pinChat(input: PinFlowChatInput): Promise<FlowChatRecord>;
+    getChat(chatId: string): Promise<FlowChatRecord | null>;
+    updateChat(chatId: string, patch: FlowChatPatch, at: string): Promise<FlowChatRecord | null>;
+    deleteChat(chatId: string): Promise<void>;
+    /** Новый ключ — в конец; тот же ключ — не дублируется, но `appliedAt` дописывается к ожидающему без него. */
+    addPending(chatId: string, change: PendingFlowChange): Promise<void>;
+    /** Забрать всё ожидающее, в порядке добавления, и очистить; переходы, применённые в срок (`appliedAt`), остаются. */
+    takePending(chatId: string): Promise<PendingFlowChange[]>;
+    /** `null` — таймеров нет. Снимает аренду. */
+    setDue(chatId: string, due: FlowDueInput | null, options?: SetDueOptions): Promise<void>;
+    /** Взять в аренду наступившие таймеры, которые никто не держит; ранние — первыми. Законченные и стоящие на паузе — пропустить. */
+    leaseDue(input: LeaseDueInput): Promise<FlowChatRecord[]>;
+    releaseLease(chatId: string, owner: string): Promise<void>;
+    /** Продлить свою аренду до `now + leaseMs`. `false` — строка уже не наша: взяла другая копия или срок переписан. */
+    renewLease(input: RenewLeaseInput): Promise<boolean>;
+    saveVersion(input: Omit<SavedFlowVersion, "createdAt"> & {
+        at: string;
+    }): Promise<SaveFlowVersionResult>;
+    getVersion(flowId: string, versionId: string): Promise<SavedFlowVersion | null>;
+    countChatsByState(input: {
+        flowId: string;
+    }): Promise<ChatsInState[]>;
+    /** Перевести до `limit` чатов на версию `toVersionId`: версия меняется сразу, перевод состояния — ожидающим `migrate`. */
+    migrateBatch(input: MigrateBatchInput): Promise<{
+        moved: string[];
+    }>;
+    readCard(ownerId: string): Promise<ClientCardEntry[]>;
+    writeCardField(input: WriteCardFieldInput): Promise<void>;
+    forgetCard(ownerId: string, fieldId: string | "all"): Promise<void>;
+    /** Сколько сообщений агент написал первым за сутки человека (`day` — «ГГГГ-ММ-ДД» в его поясе). */
+    countFirstMessages(ownerId: string, day: string): Promise<number>;
+    /** Записать ещё одно; вернуть новый счёт. */
+    addFirstMessage(ownerId: string, day: string): Promise<number>;
+    /** Разговор закончен: ставит время и причину, снимает таймер. Уже закончен — ничего не меняет. */
+    endChat(chatId: string, input: {
+        reason: FlowEndReason;
+        at: string;
+    }): Promise<FlowChatRecord | null>;
+    /** `null` — снять паузу. */
+    setPause(chatId: string, until: string | null): Promise<FlowChatRecord | null>;
+    setWindowClosed(chatId: string, closed: boolean): Promise<void>;
+    setDayClosed(chatId: string, day: string | null): Promise<void>;
+    setDelivery(chatId: string, delivery: FlowPendingDelivery | null): Promise<void>;
+    /** Пояс человека (IANA); `null` — неизвестен. Общий для всех его чатов. */
+    readTimeZone(ownerId: string): Promise<string | null>;
+    writeTimeZone(ownerId: string, timeZone: string, at: string): Promise<void>;
+    /** Попытки попутных задач человека: на человека и в этом разговоре. По `taskId`. */
+    readSideTasks(ownerId: string, chatId: string): Promise<SideTaskRecord[]>;
+    /** `asked` — ещё одна попытка, `done` — задача решена. Вернуть запись после изменения. */
+    noteSideTask(input: NoteSideTaskInput): Promise<SideTaskRecord>;
+    /** «Забудь обо мне»: стереть все попытки попутных задач человека — и на него, и на его разговоры. */
+    forgetSideTasks(ownerId: string): Promise<void>;
+    /** Остановка сервера: SQLite закрывает файл, PostgreSQL дожидается миграции (пул приложения не закрывает). */
+    close?(): Promise<void>;
+}

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

@@ -0,0 +1,3 @@
+import type { FlowStore } from "./flow-store.js";
+/** Сценарии в памяти процесса: для разработки и тестов. Перезапуск их теряет, две копии сервера их не делят. */
+export declare function memoryFlowStore(): FlowStore;

package/dist/types/store/migration-settings.d.ts

@@ -0,0 +1,7 @@
+/** Своя таблица учёта: хранилище чатов, песочница, фон и мессенджеры живут в той же базе и ведут свои. */
+export declare const FLOWS_MIGRATIONS_TABLE = "__flows_migrations";
+/**
+ * Постоянное число для блокировки базы миграциями сценариев. Не совпадает с ключами ядра (…442), песочницы (…443),
+ * фона (…444), мессенджеров (…445) и картинок (…446).
+ */
+export declare const FLOWS_MIGRATION_LOCK_KEY = 7311900447;