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

package/dist/types/engine/flow-run.d.ts

@@ -0,0 +1,130 @@
+/** Ключ в состоянии чата (`ChatState`), под которым лежит `FlowRun`. */
+export declare const FLOW_STATE_KEY = "flow";
+/** Сколько последних шагов пути хранить в чате. */
+export declare const FLOW_PATH_LIMIT = 50;
+/** Больше стольких переходов подряд без ответа агента — сценарий зациклился, движок останавливается. */
+export declare const FLOW_CHAIN_LIMIT = 5;
+/** Кто решил переход: агент заявил и судья подтвердил, судья сам, данные, событие или таймер. */
+export type TransitionDecider = "claim" | "judge" | "data" | "event" | "timer";
+/** Почему случился переход — словами для людей: «тишина 3 ч», «нода длится 1 день», «поле „Оплатил“ = да». */
+export interface TransitionReason {
+    kind: TransitionDecider;
+    text: string;
+}
+/** Почему разговор закончился: конечная нода, срок вышел, человек пропал, канал заблокирован, своя причина приложения (`flow.end`). */
+export type FlowEndReason = "final" | "deadline" | "abandoned" | "blocked" | (string & {});
+/** Как чат попал в состояние: старт сценария, переход или перевод на новую версию. */
+export type FlowPathCause = TransitionDecider | "start" | "migrate";
+export interface FlowPathEntry {
+    state: string;
+    /** Время входа, мс с 1970 года. */
+    at: number;
+    /** Метки состояния на момент входа. */
+    tags: string[];
+    from: string | null;
+    exitId: string | null;
+    decidedBy: FlowPathCause;
+    /** Уверенность судьи, 0…1. */
+    probability?: number;
+    /** Причина перехода словами. В записях до 0.49 нет. */
+    reason?: TransitionReason;
+}
+/** Где чат в сценарии. Хранится в состоянии чата под `FLOW_STATE_KEY`; все времена — мс с 1970 года. */
+export interface FlowRun {
+    state: string;
+    /** Когда вошли в текущее состояние. */
+    enteredAt: number;
+    /** Когда чат начал сценарий. */
+    startedAt: number;
+    /** Последние `FLOW_PATH_LIMIT` шагов, первый — самый старый. */
+    path: FlowPathEntry[];
+    /** Остановленные часы «время в состоянии» основных состояний, пока чат в напоминаниях: id состояния → накоплено мс. */
+    pausedClocks: Record<string, number>;
+    /** Заметки этого чата по `id` поля `chatNotes`. */
+    notes: Record<string, unknown>;
+    humanMessages: number;
+    agentAnswers: number;
+    /** На каком сообщении человека (`humanMessages`) был последний вопрос между делом. */
+    sideQuestionAt: number | null;
+    /** Последний переход, который судья не подтвердил: заявлять его снова можно после нового сообщения человека. */
+    lastRejected: {
+        exitId: string;
+        atHumanMessages: number;
+    } | null;
+    lastAgentAt: number | null;
+    lastHumanAt: number | null;
+    /** Переходов подряд без ответа агента; предел — `FLOW_CHAIN_LIMIT`. */
+    chain: number;
+    /** Сдвиг часов для тестового чата, мс. В рабочих чатах нет. */
+    timeOffset?: number;
+    /** Начало первого дня сценария (с учётом позднего старта и пояса человека). */
+    dayAnchorAt?: number;
+    /** Сообщения человека за текущий день сценария: местная дата «ГГГГ-ММ-ДД» → сколько. Хранится только текущий день. */
+    dayCounts?: Record<string, number>;
+    /** Какой шаг ряда касаний следующий; сообщение человека возвращает к 0. */
+    nudgeStep?: number;
+    /** `nudgeStep` насчитан своим рядом ноды на N дней (`nudges.days`): после них общий ряд начинается сначала. С 0.55. */
+    nudgeStepOwn?: boolean;
+    /** Ходов сервера подряд (по служебным сообщениям) после последнего сообщения человека, с 0.53; нет — 0. */
+    serverTurns?: number;
+    /** Последний ход «пишет первым», после которого человек не писал, и счёт до него: не доставлен — не засчитан (FR-309). */
+    touch?: FlowTouch;
+    /** Когда разговор закончился. После конца таймеров и касаний нет. */
+    endedAt?: number;
+    endReason?: FlowEndReason;
+}
+/** Ход «пишет первым» и что было до него. Ответ хода помечен «не доставлено» — счёт возвращается к этому. */
+export interface FlowTouch {
+    /** Ответ агента этого хода. */
+    answerId: string;
+    /** Когда ход был, по часам чата: от него считается следующий срок, если касание не дошло. */
+    at: number;
+    lastAgentAt: number | null;
+    nudgeStep: number;
+    nudgeStepOwn?: boolean;
+    agentAnswers: number;
+}
+/** Переход, который движок решил сделать. */
+export interface Transition {
+    from: string;
+    /** Новое состояние; при «назад» — уже найденное основное состояние. */
+    to: string;
+    exitId: string;
+    decidedBy: TransitionDecider;
+    probability?: number;
+    /** Метки состояния `to`. */
+    tags: string[];
+    at: number;
+    /** Переход «назад» (`@return`). */
+    returned?: boolean;
+    /** Причина словами: уходит в `onTransition` и в путь. */
+    reason?: TransitionReason;
+}
+/** Тихие часы и потолок сообщений, которые агент пишет первым (по таймерам). */
+export interface FirstMessagesRules {
+    /** Ночью не писать: «ЧЧ:ММ» в поясе человека. Срок переносится на конец тихих часов. */
+    quietHours: {
+        from: string;
+        to: string;
+    };
+    /** Не больше стольких сообщений первым за сутки человека. */
+    maxPerDay: number;
+    /**
+     * Своя проверка приложения: например, человек отписался или остановлены расходы. `true` — писать. `false` — не сейчас:
+     * касание повторится через час. `"never"` — молчать до сообщения человека. `{ retryAt }` — повторить в этот момент
+     * (негодная дата — как `false`, прошедшая — через минуту). Конец разговора («срок вышел», «не завершил») и переходы нод
+     * по таймерам от ответа не зависят: наступают в свой срок.
+     */
+    canWriteNow?: (input: {
+        ownerId: string;
+        chatId: string;
+        at: Date;
+    }) => CanWriteNow | Promise<CanWriteNow>;
+}
+/** Ответ `canWriteNow`: писать, не сейчас (повтор через час), молчать до сообщения человека или повторить в названный момент (с 0.53). */
+export type CanWriteNow = boolean | "never" | {
+    retryAt: Date;
+};
+/** `false` — правила выключены: агент пишет первым без тихих часов и потолка. Не писать первым — `canWriteNow: () => "never"`. */
+export type FirstMessagesSetting = Partial<FirstMessagesRules> | false;
+export declare const DEFAULT_FIRST_MESSAGES: Readonly<Omit<FirstMessagesRules, "canWriteNow">>;

package/dist/types/engine/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./flow-run.js";
+export { nextTransition, type FlowEvent } from "./next-transition.js";
+export { startRun, applyTransition, noteHumanMessage, noteAgentAnswer, noteRejectedClaim, claimAllowed, noteSideQuestion, } from "./run-updates.js";
+export { dataConditionHolds, fieldValueFits } from "./data-conditions.js";
+export { nextDue, nextWake, dueReasons, timerDueAt, FLOW_DEADLINE_EXIT, FLOW_FIRST_EXIT, FLOW_GIVE_UP_EXIT, type DueReasons, type FlowDue } from "./timers.js";
+export { returnTarget } from "./targets.js";
+export { isFinal, isTouch, commonApplies, activeExits, fieldById, type ActiveExit, type FieldPlace } from "./flow-graph.js";
+export { firstMessageSlot, resolveFirstMessages, localDay, type FirstMessageInput } from "./first-messages.js";
+export { sideQuestion, isFieldStale, type SideQuestion, type SideQuestionInput } from "./side-questions.js";
+export { migrateRun, type StateMap } from "./migrate-run.js";
+export { dayOf, dayInProgress, dayStartAt, dayAnchor, stateDaysDue, flowDay, deadlineAt, withDayAnchor, beforeFirstNight, type FlowDayInfo } from "./flow-days.js";
+export { stateNudges, nextNudge, type FlowFirstReason, type NudgeDue } from "./nudges.js";
+export { frameState, type FrameState } from "./day-frame.js";
+export { openSideTasks, type OpenSideTasksInput, type SideTaskAttempts } from "./side-tasks.js";

package/dist/types/engine/migrate-run.d.ts

@@ -0,0 +1,11 @@
+import type { AgentFlow } from "../format/flow-format.js";
+import type { FlowRun } from "./flow-run.js";
+/** Куда перевести чаты из состояний, которых нет в новой версии: id старого → id нового. */
+export type StateMap = Record<string, string>;
+/**
+ * Переводит чат на новую версию сценария (→ В11). Состояние есть в новой версии — часы и путь целы. Удалено — вход в
+ * состояние из `map`; без цели — ошибка (её ловит перевод чатов раньше). Заметки чата — по совпадающим `id`.
+ * Удалённые состояния в пути и в остановленных часах переименовываются по `map`: так «назад» ведёт туда, куда автор
+ * отправил удалённое состояние.
+ */
+export declare function migrateRun(run: FlowRun, next: AgentFlow, map: StateMap, now: number): FlowRun;

package/dist/types/engine/next-transition.d.ts

@@ -0,0 +1,40 @@
+import type { AgentFlow, FlowCatalog, FlowCondition, FlowEventType } from "../format/flow-format.js";
+import { type FlowRun, type Transition } from "./flow-run.js";
+/** Что случилось в чате: на это движок ищет переход. */
+export type FlowEvent = 
+/** Сообщение человека, нажатая кнопка, вызванный инструмент, событие приложения. */
+{
+    type: "event";
+    event: FlowEventType;
+    name?: string;
+}
+/**
+ * Изменились данные: проверить условия по ним. `field` — какое поле изменилось (нет — все условия по данным).
+ * Заметки чата движок берёт из `run.notes`, карточку клиента приносит событие.
+ */
+ | {
+    type: "data";
+    field?: string;
+    card?: Record<string, unknown>;
+}
+/** Судья подтвердил условие словами: по заявке агента (`claim`) или сам после ответа (`judge`). `why` — слова агента из заявки. */
+ | {
+    type: "verdict";
+    exitId: string;
+    probability: number;
+    decidedBy: "claim" | "judge";
+    why?: string;
+}
+/** Наступил таймер из `nextDue`. Пояс человека нужен, чтобы перепроверить срок: человек мог успеть ответить. */
+ | {
+    type: "timer";
+    exitId: string;
+    timeZone: string;
+};
+/** Условие человеческими словами: для служебного сообщения модели и для причины перехода. С каталогом — подписи событий. */
+export declare function describeCondition(flow: AgentFlow, when: FlowCondition, catalog?: Pick<FlowCatalog, "events">): string;
+/**
+ * Следующий переход или `null` — агент остаётся (→ В2). Порядок: свои условия, потом общие (→ В3); «назад» — в последнее
+ * основное состояние (→ В1). После `FLOW_CHAIN_LIMIT` переходов подряд без ответа агента и сообщения человека — `null`.
+ */
+export declare function nextTransition(flow: AgentFlow, run: FlowRun, event: FlowEvent, now: number): Transition | null;

package/dist/types/engine/nudges.d.ts

@@ -0,0 +1,78 @@
+import type { AgentFlow, FlowNudges } from "../format/flow-format.js";
+import type { FlowRun } from "./flow-run.js";
+/** Почему агент пишет первым. Причины одного срока собираются в один ход. */
+export type FlowFirstReason = 
+/** Переход по таймеру в новую ноду. */
+{
+    kind: "transition";
+    stateId: string;
+}
+/** Утреннее сообщение (`schedule.firstMessages.morning`). */
+ | {
+    kind: "morning";
+}
+/** Касание по тишине: номер шага ряда `afterSilence`, с 1. */
+ | {
+    kind: "silence";
+    step: number;
+}
+/** Касание по часам (`dailyAt`). */
+ | {
+    kind: "daily";
+    at: string;
+}
+/** Сообщения человека остались без ответа (после жёсткой рамки дня, при лимите расходов) — ответить на накопленное. */
+ | {
+    kind: "night_messages";
+    count: number;
+}
+/** Прощание при «срок вышел» (`schedule.farewellOnDeadline`, → В5). */
+ | {
+    kind: "farewell";
+};
+/** Ближайшее касание; `give_up` — конец разговора «не завершил» без сообщения. */
+export interface NudgeDue {
+    at: number;
+    reason: FlowFirstReason | {
+        kind: "give_up";
+    };
+    /** Касание своего ряда ноды на N дней (`nudges.days`): его шаг не идёт в счёт общего ряда. */
+    own?: boolean;
+}
+/** Касания ноды: свои, «off», общие из «Дней и времени», общие сценария. Нет ни тех, ни других — `null`. */
+export declare function stateNudges(flow: AgentFlow, stateId: string): FlowNudges | null;
+/** Порог утреннего по умолчанию: человек писал за 3 ч до него — утреннее завтра. */
+export declare const DEFAULT_SKIP_MORNING_MIN = 180;
+/** То, чего нет в месте чата: пауза сотрудника из записи и сообщения человека без ответа из истории. */
+export interface FirstWakeContext {
+    /** Пауза сотрудника до этого момента (мс): тишина считается от её конца, утро на паузе пропускается. */
+    pausedUntil?: number | null;
+    /** Сообщения человека после последнего ответа агента, записанные без хода (ночь, рамка дня, пауза). */
+    unanswered?: number;
+    /** Последнее касание не доставлено (мс): оно не засчитано, а следующий срок — не раньше этого момента. */
+    undeliveredAt?: number | null;
+}
+/**
+ * Ближайшее касание чата: ряд `afterSilence` от последнего ответа агента, после ряда — часы `dailyAt`. `give_up`
+ * («не завершил») — `giveUpAfter` тишины человека; побеждает, если наступает не позже касания. Касаний в ноде нет,
+ * человек ответил или писал без ответа, агент ещё не писал, разговор закончен — `null`.
+ */
+export declare function nextNudge(flow: AgentFlow, run: FlowRun, now: number, timeZone: string, context?: FirstWakeContext): NudgeDue | null;
+/**
+ * Когда наступит «не завершил» (`giveUpAfter` тишины человека), независимо от касаний: отложенное или не начатое
+ * касание конец разговора не двигает. Нет `giveUpAfter` или тишина не идёт — `null`.
+ */
+export declare function giveUpAt(flow: AgentFlow, run: FlowRun, timeZone: string, context?: FirstWakeContext): number | null;
+/**
+ * Утреннее сообщение: начало следующего дня после последних слов агента. Человек писал меньше чем за
+ * `skipMorningIfHumanWithinMin` до него или на нём стояла пауза сотрудника — утреннее следующего дня.
+ */
+export declare function nextMorning(flow: AgentFlow, run: FlowRun, timeZone: string, context?: FirstWakeContext): number | null;
+/**
+ * До какого момента молчат касания в начале дня: человек писал до начала дня и меньше `skipMorningIfHumanWithinMin`
+ * назад — как утреннее, ждут и касание тишины, перенесённое ночью на утро, и касание по часам. Переход ноды по сроку и
+ * ответ на ночные сообщения — по делу, они не ждут. Ждать не нужно — `null`.
+ */
+export declare function dayStartHoldUntil(flow: AgentFlow, run: FlowRun, now: number, timeZone: string, reasons: readonly FlowFirstReason[]): number | null;
+/** Ответить на накопленное: в начале дня после последних записанных в место слов. Сообщений без ответа нет — `null`. */
+export declare function nextNightReply(flow: AgentFlow, run: FlowRun, timeZone: string, context?: FirstWakeContext): number | null;

package/dist/types/engine/run-updates.d.ts

@@ -0,0 +1,37 @@
+import type { AgentFlow } from "../format/flow-format.js";
+import { type FlowPathEntry, type FlowRun, type Transition } from "./flow-run.js";
+/** Чат начинает сценарий в стартовом состоянии. */
+export declare function startRun(flow: AgentFlow, now: number): FlowRun;
+/** Добавляет шаг в путь, храня последние `FLOW_PATH_LIMIT`. */
+export declare function appendPath(path: FlowPathEntry[], entry: FlowPathEntry): FlowPathEntry[];
+/**
+ * Применяет переход из `nextTransition`. Часы «времени в состоянии» (→ В5): уходя из основного состояния в касание, движок
+ * запоминает, сколько там пробыли; «назад» продолжает отсчёт с этого места, обычный вход — с нуля.
+ */
+export declare function applyTransition(flow: AgentFlow, run: FlowRun, transition: Transition): FlowRun;
+/**
+ * Пришло сообщение человека: тишина прервана, счёт переходов подряд — заново, ряд касаний — с первого шага.
+ * `dayKey` — местная дата дня сценария («ГГГГ-ММ-ДД»), только у сценариев с днями: по нему считаются рамки дня.
+ */
+export declare function noteHumanMessage(run: FlowRun, now: number, dayKey?: string, count?: number): FlowRun;
+/** Агент ответил (или написал первым): от этого момента считается тишина, счёт переходов подряд — заново. */
+export declare function noteAgentAnswer(run: FlowRun, now: number): FlowRun;
+/**
+ * Ответ касания не доставлен (FR-309): касание не засчитано — шаг ряда, последние слова агента и счёт ответов как до
+ * него. `undeliveredAt` — когда касание было: раньше него следующий срок не наступает. Пометка не меняется — откат тот же
+ * сколько ни считай.
+ */
+export declare function withoutUndeliveredTouch(run: FlowRun, undelivered: ReadonlySet<string>): {
+    run: FlowRun;
+    undeliveredAt: number | null;
+};
+/** Судья не подтвердил заявку агента: тот же выход можно заявить снова после нового сообщения человека. */
+export declare function noteRejectedClaim(run: FlowRun, exitId: string): FlowRun;
+/** Можно ли заявить выход: его не отклоняли с последнего сообщения человека. */
+export declare function claimAllowed(run: FlowRun, exitId: string): boolean;
+/** Агент спросил о человеке между делом: следующий такой вопрос — по темпу сценария. */
+export declare function noteSideQuestion(run: FlowRun): FlowRun;
+/** Место без пометки «шаг насчитан своим рядом ноды». */
+export declare function withoutOwnStep<R extends FlowRun>(run: R): R;
+/** Шаг ряда касаний после хода «пишет первым»: `own` — его насчитал свой ряд ноды на N дней. */
+export declare function withNudgeStep<R extends FlowRun>(run: R, step: number, own: boolean): R;

package/dist/types/engine/side-questions.d.ts

@@ -0,0 +1,26 @@
+import type { AgentFlow, ClientCardField } from "../format/flow-format.js";
+import type { FlowRun } from "./flow-run.js";
+export interface SideQuestionInput {
+    /** Карточка клиента: id поля → значение и когда записано (мс). */
+    card: Record<string, {
+        value: unknown;
+        updatedAt: number;
+    }>;
+    now: number;
+}
+/**
+ * О чём спросить человека: `learn` — «узнать здесь», спросить прямо; `stale` — известно давно, мягко уточнить;
+ * `unknown` — следующее неизвестное поле карточки, спросить между делом.
+ */
+export interface SideQuestion {
+    fieldId: string;
+    reason: "learn" | "stale" | "unknown";
+}
+/** Пора ли уточнить поле: прошло больше `refreshAfterMonths` месяцев с записи. Без срока поле не устаревает. */
+export declare function isFieldStale(field: Pick<ClientCardField, "refreshAfterMonths">, updatedAt: number, now: number): boolean;
+/**
+ * Что спросить сейчас или `null`. «Узнать здесь» — прямо и вне темпа. Дальше — только если состояние не «без вопросов» и
+ * с прошлого вопроса между делом прошло `pace.sideQuestionEveryMessages` сообщений человека: сначала устаревшее, потом
+ * первое неизвестное поле карточки по порядку. В конце сценария не спрашиваем.
+ */
+export declare function sideQuestion(flow: AgentFlow, run: FlowRun, input: SideQuestionInput): SideQuestion | null;

package/dist/types/engine/side-tasks.d.ts

@@ -0,0 +1,44 @@
+import { type AgentFlow, type FlowSideTask } from "../format/flow-format.js";
+import type { FlowRun } from "./flow-run.js";
+/** Попытки задачи, как их отдаёт хранилище: на человека (`chatId: null`) или на разговор. */
+export interface SideTaskAttempts {
+    taskId: string;
+    chatId: string | null;
+    asks: number;
+    doneAt: string | null;
+}
+/** Встроенная задача: пока пояс человека неизвестен, в первый день до ночи узнать город (В1). Первая по важности. */
+export declare const TIME_ZONE_TASK_ID = "ask_time_zone";
+export declare const TIME_ZONE_TASK: FlowSideTask;
+/** Задача по id: встроенная «узнать город» — только у сценария с «Днями и временем», иначе задача сценария. */
+export declare function sideTaskById(flow: AgentFlow, id: string): FlowSideTask | undefined;
+/** Есть ли у сценария попутные задачи: свои или встроенная. Нет — ни инструмента, ни правила, ни строки (как в 0.48). */
+export declare const hasSideTasks: (flow: AgentFlow) => boolean;
+export interface SideTaskContext {
+    flow: AgentFlow;
+    run: FlowRun;
+    /** Разговор, в котором идёт ход: по нему считаются попытки задач «заново в каждом разговоре». */
+    chatId: string;
+    attempts: readonly SideTaskAttempts[];
+    /** Значения карточки клиента по `id` поля. Заметки чата берутся из `run.notes`. */
+    card: Readonly<Record<string, unknown>>;
+    /** Пояс человека неизвестен, а сегодня его первый день до первой ночи: тогда открыта встроенная задача «узнать город». Отдаёт этап 4. */
+    askTimeZone?: boolean;
+}
+export type OpenSideTasksInput = SideTaskContext;
+/** Решена ли задача: отмечена или её поле уже известно. Потрачена ли: попытки кончились. Иначе — открыта. */
+export type SideTaskStanding = "open" | "done" | "spent";
+/** Попытки задачи: на человека — запись без разговора, у «заново в каждом разговоре» — запись этого разговора. */
+export declare function sideTaskRecord(task: FlowSideTask, chatId: string, attempts: readonly SideTaskAttempts[]): SideTaskAttempts | undefined;
+/** Известно ли поле задачи: значение подходит типу поля. Поля нет в сценарии — не известно. */
+export declare function sideTaskFieldKnown(task: FlowSideTask, context: Pick<SideTaskContext, "flow" | "run" | "card">): boolean;
+/** Где задача сейчас — без учёта темпа и места в сценарии. */
+export declare function sideTaskStanding(task: FlowSideTask, context: SideTaskContext): SideTaskStanding;
+/** Прошло ли с прошлого вопроса или задачи между делом столько сообщений человека, сколько велит `pace`. */
+export declare function sideTaskPaceReached(flow: AgentFlow, run: FlowRun): boolean;
+/**
+ * Задачи, которые агент может предложить сейчас: открытые, и только если темп позволяет, состояние не «без вопросов» и
+ * сценарий не кончился. Порядок — как в сценарии. Встроенная «узнать город» — первой и вне общего темпа: у неё только
+ * первый день до ночи. Задач нет — пусто, как в 0.48.
+ */
+export declare function openSideTasks(input: OpenSideTasksInput): FlowSideTask[];

package/dist/types/engine/targets.d.ts

@@ -0,0 +1,9 @@
+import { type AgentFlow, type FlowState } from "../format/flow-format.js";
+import type { FlowRun } from "./flow-run.js";
+/** Куда ведёт «назад»: последнее в пути основное состояние, касания пропускаются. Такого нет — старт (→ В1). */
+export declare function returnTarget(flow: AgentFlow, run: FlowRun): FlowState | undefined;
+/** Состояние, в которое ведёт условие, или `undefined`: цели нет, она удалена или «назад» ведёт туда же, где чат. */
+export declare function exitTarget(flow: AgentFlow, run: FlowRun, to: string | null): {
+    state: FlowState;
+    returned: boolean;
+} | undefined;

package/dist/types/engine/timers.d.ts

@@ -0,0 +1,61 @@
+import type { AgentFlow, FlowSchedule, TimerCondition } from "../format/flow-format.js";
+import type { FlowRun } from "./flow-run.js";
+import { type FirstWakeContext, type FlowFirstReason } from "./nudges.js";
+/** `exitId` срока «срок вышел» в `FlowDue`: это не выход ноды, а конец разговора (`schedule.lengthDays`). */
+export declare const FLOW_DEADLINE_EXIT = "@deadline";
+export interface FlowDue {
+    /** Когда сработает, мс с 1970 года. */
+    at: number;
+    exitId: string;
+}
+/**
+ * Срок одного таймера в текущем состоянии чата; `null` — сейчас не идёт (тишины нет: человек ответил или агент ещё не писал).
+ * «Нода длится N дней» и «наступил день N» считаются по «Дням и времени»: без `schedule` не идут.
+ */
+export declare function timerDueAt(condition: TimerCondition, run: FlowRun, timeZone: string, schedule?: FlowSchedule): number | null;
+/**
+ * Выход по таймеру, который уже наступил к входу в состояние и срок которого от входа не зависит: срабатывает сразу, в том
+ * же шаге, а не отдельным ходом. Тишина, время в состоянии, «длится N дней», время суток — нет: их срок от входа. Нет — `null`.
+ */
+export declare function overdueOnEntry(flow: AgentFlow, run: FlowRun, now: number, timeZone: string): string | null;
+/**
+ * Ближайший таймер чата: побеждает наступивший раньше, при равенстве — таймер состояния. «Срок вышел» побеждает и при
+ * равенстве: разговор кончается, а не переходит. Законченный разговор сроков не имеет. `timeZone` — пояс человека.
+ */
+export declare function nextDue(flow: AgentFlow, run: FlowRun, _now: number, timeZone: string): FlowDue | null;
+/** `exitId` срока «пишет первым» в `FlowDue`: касание, утреннее или ответ на накопленное, без перехода. */
+export declare const FLOW_FIRST_EXIT = "@first";
+/** `exitId` срока «не завершил»: конец разговора без сообщения. */
+export declare const FLOW_GIVE_UP_EXIT = "@give_up";
+/**
+ * Ближайший срок чата: переход ноды, «срок вышел», «не завершил» или «пишет первым». При равенстве побеждает «срок
+ * вышел», затем «не завершил» (разговор кончается), затем таймер ноды: причины «пишет первым» того же момента он заберёт с собой.
+ */
+export declare function nextWake(flow: AgentFlow, run: FlowRun, now: number, timeZone: string, context?: FirstWakeContext): FlowDue | null;
+/** Что наступило к `now`: конец разговора, переход ноды и все причины написать первым — на один ход. */
+export interface DueReasons {
+    /** «Срок вышел»: остальное не считается. */
+    deadline: boolean;
+    /** «Не завершил»: конец без сообщения. */
+    giveUp: boolean;
+    /** Наступивший выход ноды по таймеру. */
+    exitId: string | null;
+    /** Утро, накопленное, касание — по порядку. Переход ноды в них не входит: его причину даёт сам переход. */
+    reasons: FlowFirstReason[];
+    /** Касание в причинах — своего ряда ноды на N дней: шаг помечается, общий ряд потом начнётся сначала. */
+    ownNudge?: boolean;
+}
+export declare function dueReasons(flow: AgentFlow, run: FlowRun, now: number, timeZone: string, context?: FirstWakeContext): DueReasons;
+/** Ближайший срок «пишет первым» строго после `now`: касание, утреннее, накопленное. Нет — `null`. */
+export declare function nextFirstMessageAfter(flow: AgentFlow, run: FlowRun, now: number, timeZone: string, context?: FirstWakeContext): number | null;
+/** Ближайший конец разговора после `now`: «срок вышел» или «не завершил». Нет — `null`. */
+export declare function endingWake(flow: AgentFlow, run: FlowRun, now: number, timeZone: string, context: FirstWakeContext): FlowDue | null;
+/**
+ * Касание отложено (нельзя писать сейчас, ход не начался): срок — повтор `retry`, но не позже ближайшего срока, который не
+ * касание: выход ноды, «срок вышел», «не завершил». Конец разговора не зависит от того, дошло ли касание. Сроки не позже
+ * `now` (наступивший выход, который ждёт хода) не в счёт. `retry.at: null` — повтора нет. Ничего нет — `null`.
+ */
+export declare function deferredWake(flow: AgentFlow, run: FlowRun, now: number, timeZone: string, context: FirstWakeContext, retry: {
+    at: number | null;
+    exitId: string;
+}): FlowDue | null;

package/dist/types/engine/zoned-time.d.ts

@@ -0,0 +1,27 @@
+export interface ZonedDate {
+    year: number;
+    /** 1…12 */
+    month: number;
+    day: number;
+}
+export interface ZonedParts extends ZonedDate {
+    hour: number;
+    minute: number;
+    second: number;
+}
+/** Дата и часы на часах человека в момент `at`. */
+export declare function zonedParts(at: number, timeZone: string): ZonedParts;
+/** Момент, когда на часах человека будет `date` и `minutes` минут от полуночи. */
+export declare function zonedTime(date: ZonedDate, minutes: number, timeZone: string): number;
+/** Следующий календарный день. */
+export declare function nextDate(date: ZonedDate, days?: number): ZonedDate;
+/** «ЧЧ:ММ» → минуты от полуночи; не то — `null`. */
+export declare function parseClock(clock: string): number | null;
+/** Минуты от полуночи на часах человека. */
+export declare function clockMinutes(at: number, timeZone: string): number;
+/** Первый момент строго после `after`, когда на часах человека `minutes` минут от полуночи. */
+export declare function nextClockTime(after: number, minutes: number, timeZone: string): number;
+/** Начало следующих суток на часах человека. */
+export declare function startOfNextDay(at: number, timeZone: string): number;
+/** Сутки человека: «ГГГГ-ММ-ДД» в его поясе. */
+export declare function localDay(at: number, timeZone: string): string;

package/dist/types/format/catalog-events.d.ts

@@ -0,0 +1,5 @@
+import type { FlowCatalog } from "./flow-format.js";
+/** Имена кнопок и событий приложения — каталог даёт их строками или объектами `{ name, label }`. */
+export declare function catalogEventNames(catalog: Pick<FlowCatalog, "events">): string[];
+/** Подпись события из каталога; нет каталога, события или подписи — `undefined`, и показывают имя. */
+export declare function catalogEventLabel(catalog: Pick<FlowCatalog, "events"> | undefined, name: string): string | undefined;

package/dist/types/format/compact-flow.d.ts

@@ -0,0 +1,8 @@
+import { type AgentFlow } from "./flow-format.js";
+type Json = Record<string, unknown>;
+/**
+ * JSON сценария без значений по умолчанию — так его хранят и показывают в окне JSON.
+ * `parseFlow(compactFlow(flow))` возвращает тот же сценарий.
+ */
+export declare function compactFlow(flow: AgentFlow): Json;
+export {};