@itphx/synth-shared 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,219 @@
1
+ /**
2
+ * AD-089: домен внешних событий — нормализованное `Event`, устойчивая `Binding`
3
+ * и решение Router. Контракты без бизнес-логики: сам Router/приём событий живут
4
+ * в core, здесь только типы.
5
+ */
6
+ import type { SessionOrigin, SessionSettings } from './index.js';
7
+ /**
8
+ * Источник события. Свободная строка, известные значения: `'telegram'`,
9
+ * `'synth-media'`, `'webhook'`, `'cron'`, `'ci'`, `'ui'`.
10
+ */
11
+ export type EventSource = string;
12
+ /** Режим обработки события: `drop` — осознанный отказ с аудитом. */
13
+ export type EventMode = 'bound' | 'ephemeral' | 'queue' | 'drop';
14
+ /** Режим доставки события в `EventBinding` (без `drop`). */
15
+ export type EventDeliveryMode = Exclude<EventMode, 'drop'>;
16
+ /** AD-089: идентичность отправителя события (маппинг на RBAC — AD-029/AD-043). */
17
+ export interface EventIdentity {
18
+ /** Внешний идентификатор пользователя. */
19
+ principalId?: string;
20
+ /** Ключ чата: `'chat:<source>:<chatId>'`. */
21
+ chatKey?: string;
22
+ /** Ключ треда/топика: `'thread:<source>:<chatId>:<threadId>'`. */
23
+ threadKey?: string;
24
+ /** Роли для маппинга на RBAC. */
25
+ roles?: string[];
26
+ }
27
+ /** AD-089: нормализованное внешнее событие (источник-специфика — в `payload`). */
28
+ export interface SynthEvent {
29
+ /** `'evt_<uuid>'`, уникален в пределах инстанса. */
30
+ id: string;
31
+ source: string;
32
+ /** `'message' | 'callback' | 'webhook' | 'schedule' | 'ci_event' | 'session.requested'`. */
33
+ type: string;
34
+ /** Нормализованное тело: текст, ссылки на вложения (AD-085), метаданные. */
35
+ payload: unknown;
36
+ identity: EventIdentity;
37
+ /** Стабильный ключ идемпотентности. */
38
+ dedupKey: string;
39
+ /** Время события, ISO-8601. */
40
+ ts: string;
41
+ }
42
+ /** AD-089: устойчивая привязка внешнего адреса к сессии/шаблону. */
43
+ export interface EventBinding {
44
+ id: string;
45
+ source: string;
46
+ /** Привязка на чат. */
47
+ chatKey?: string;
48
+ /** Привязка на тред/топик (приоритетнее чата). */
49
+ threadKey?: string;
50
+ /** Конкретная постоянная сессия (mode=`bound`). */
51
+ sessionId?: string;
52
+ mode: EventDeliveryMode;
53
+ /** Шаблон агента/скилла для создания/настройки сессии (AD-046). */
54
+ agentTemplate?: string;
55
+ /** `projectId` — контейнер сессии (AD-014). */
56
+ project?: string;
57
+ }
58
+ /** AD-089/AD-052: API-ключ привязки для аутентификации приёма событий. */
59
+ export interface EventBindingApiKey {
60
+ /** `eak_<uuid>`. */
61
+ id: string;
62
+ bindingId: string;
63
+ /** Обязательная уникальная (глобально по инстансу) метка ключа. */
64
+ label: string;
65
+ /** Опциональное описание назначения ключа. */
66
+ description?: string;
67
+ /**
68
+ * Опциональный лимит запросов в минуту для этого ключа (AD-089/AD-052).
69
+ * Не задан — глобальный дефолт `events.keyRateLimitPerMinute`; `0` — без лимита.
70
+ */
71
+ rateLimitPerMinute?: number;
72
+ /** id создателя (пользователя). */
73
+ createdBy: string;
74
+ /** ISO-8601. */
75
+ createdAt: string;
76
+ /** ISO-8601; best-effort, обновляется при использовании. */
77
+ lastUsedAt?: string;
78
+ /** Префикс ключа для идентификации в UI (секрет наружу не отдаётся). */
79
+ prefix: string;
80
+ /**
81
+ * AD-052 (задел): ISO-8601 срок действия ключа. Заполнен и уже прошёл —
82
+ * ключ недействителен (`resolveBySecret` → `null`). Не задан — бессрочно.
83
+ */
84
+ expiresAt?: string;
85
+ /**
86
+ * AD-052 (задел): ISO-8601 отзыв ключа (мягкое удаление). Заполнен —
87
+ * ключ недействителен независимо от срока (`EventApiKeyStore.revoke`).
88
+ */
89
+ revokedAt?: string;
90
+ }
91
+ /** AD-089: ответ создания ключа — метаданные + однократно показываемый секрет. */
92
+ export interface EventBindingApiKeyCreated extends EventBindingApiKey {
93
+ /** Plaintext-секрет; возвращается единственный раз при создании. */
94
+ key: string;
95
+ }
96
+ /**
97
+ * AD-089: цель правила маршрутизации (та же семантика, что у
98
+ * `EventBinding`/`ScheduleTarget`).
99
+ */
100
+ export type EventRouteTarget = {
101
+ mode: 'bound';
102
+ sessionId: string;
103
+ } | {
104
+ mode: 'ephemeral';
105
+ agentTemplate?: string;
106
+ project?: string;
107
+ ttl?: string;
108
+ } | {
109
+ mode: 'queue';
110
+ sessionId: string;
111
+ }
112
+ /**
113
+ * AD-089 (auto-bind): правило закрепляет внешний адрес события
114
+ * (`chatKey`/`threadKey`) за сессией — Router создаёт `EventBinding`
115
+ * (`mode='bound'`) при первой доставке.
116
+ */
117
+ | {
118
+ mode: 'bind';
119
+ agentTemplate?: string;
120
+ project?: string;
121
+ };
122
+ /** AD-089: условие срабатывания правила (AND по заполненным полям). */
123
+ export interface EventRouteMatch {
124
+ source?: string;
125
+ type?: string;
126
+ chatKey?: string;
127
+ threadKey?: string;
128
+ principalId?: string;
129
+ /** Метка в `payload.label`. */
130
+ label?: string;
131
+ /** Подстроки в тексте события (регистронезависимо; достаточно одного). */
132
+ keywords?: string[];
133
+ }
134
+ /** AD-089: правило маршрутизации событий «событие → сессия» (проектные/инстанс-правила). */
135
+ export interface EventRouteRule {
136
+ /** `rule_<uuid>`, уникален в пределах инстанса. */
137
+ id: string;
138
+ name?: string;
139
+ /** Больше = раньше; при равенстве — порядок в файле. */
140
+ priority: number;
141
+ enabled: boolean;
142
+ match: EventRouteMatch;
143
+ target: EventRouteTarget;
144
+ }
145
+ /**
146
+ * AD-089/AD-084: диагностическая мета решения Router. Необязательные поля,
147
+ * не ломают дискриминант `kind`; заполняются decision-слоем (`confidence`)
148
+ * и маршрутизацией (`signals`) — попадают в ответ `POST /events` и в журнал.
149
+ */
150
+ export interface RouteDecisionMeta {
151
+ /** Уверенность decision-модели (0..1), если решение принято decision-слоем. */
152
+ confidence?: number;
153
+ /**
154
+ * Диагностические сигналы решения (напр. `decision-rules`, `agent:<id>`,
155
+ * `model:<p/m>`, `latency:<ms>ms`).
156
+ */
157
+ signals?: string[];
158
+ }
159
+ /** AD-089: вариант решения Router без меты (дискриминант `kind`). */
160
+ type RouteDecisionKind = {
161
+ kind: 'bound';
162
+ sessionId: string;
163
+ } | {
164
+ kind: 'ephemeral';
165
+ agentTemplate: string;
166
+ ttl: string;
167
+ project?: string;
168
+ } | {
169
+ kind: 'queue';
170
+ owner: string;
171
+ reason: string;
172
+ } | {
173
+ kind: 'drop';
174
+ reason: string;
175
+ audited: true;
176
+ }
177
+ /**
178
+ * AD-089 (auto-bind): Router решает закрепить событие за новой сессией —
179
+ * `RequestSessionService` создаёт сессию без `expiresAt` и `EventBinding`
180
+ * (`mode='bound'`), после чего доставляет событие. Источник решения — фоллбек
181
+ * при `events.autoBind` и наличии `identity.chatKey|threadKey`, либо правило
182
+ * с целью `mode: 'bind'`.
183
+ */
184
+ | {
185
+ kind: 'bind';
186
+ agentTemplate: string;
187
+ project?: string;
188
+ };
189
+ /** AD-089: решение Router — куда направить событие (или отложить/отбросить). */
190
+ export type RouteDecision = RouteDecisionKind & RouteDecisionMeta;
191
+ /** AD-089: инициатор запроса на сессию. */
192
+ export type EventInitiator = 'user' | 'agent' | 'external' | 'system';
193
+ /**
194
+ * AD-089: намерение создать/привязать сессию — единый funnel. Создание сессии
195
+ * обрабатывается тем же Router'ом, независимо от инициатора.
196
+ */
197
+ export interface SessionRequest {
198
+ initiator: EventInitiator;
199
+ intent: 'explicit' | 'event';
200
+ projectId?: string;
201
+ parentId?: string;
202
+ agentTemplate?: string;
203
+ mode?: EventDeliveryMode;
204
+ /** TTL для режима `ephemeral` (напр. `'24h'`). */
205
+ ttl?: string;
206
+ title?: string;
207
+ /** Канонический ключ иконки (PROJECT_ICON_KEYS). */
208
+ icon?: string;
209
+ /** Канонический ключ цвета (PROJECT_COLOR_KEYS). */
210
+ color?: string;
211
+ engine?: string;
212
+ /** Происхождение сессии (`user`/`fork`/`subagent`) — паритет с createSession. */
213
+ sessionOrigin?: SessionOrigin;
214
+ settings?: Partial<SessionSettings>;
215
+ /** id исходного события, инициировавшего запрос. */
216
+ sourceEventId?: string;
217
+ dedupKey?: string;
218
+ }
219
+ export {};
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,96 @@
1
+ /**
2
+ * AD-030: контракты hook-шины событий агента и интеграций. Система хуков не
3
+ * реализована в рантайме (Plugin SDK — отдельный этап), здесь только типы:
4
+ * имена хуков, режим выполнения, результат и карта контекстов.
5
+ */
6
+ import type { SynthEvent, EventInitiator } from './events.js';
7
+ /** AD-030: имена хуков жизненного цикла агента и интеграций (AD-089). */
8
+ export type HookName = 'pre_tool_use' | 'post_tool_use' | 'session_start' | 'session_end' | 'plan_approved' | 'plan_rejected' | 'agent_spawned' | 'agent_completed' | 'agent_failed' | 'permission_denied' | 'external_event' | 'message_received' | 'callback' | 'session_requested' | 'schedule_fired';
9
+ /**
10
+ * Режим выполнения хука: `sync` — блокирующий (можно `block`/`patch`),
11
+ * `async` — fire-and-forget (тяжёлые операции: CI, нотификации).
12
+ */
13
+ export type HookMode = 'sync' | 'async';
14
+ /** AD-030: результат хука. `block`/`reason` — только для `sync`. */
15
+ export interface HookResult {
16
+ block?: boolean;
17
+ reason?: string;
18
+ patch?: Record<string, unknown>;
19
+ }
20
+ /** AD-030: карта контекста по имени хука (минимально необходимые поля). */
21
+ export interface HookContextMap {
22
+ pre_tool_use: {
23
+ tool: string;
24
+ input: unknown;
25
+ agent?: string;
26
+ };
27
+ post_tool_use: {
28
+ tool: string;
29
+ input: unknown;
30
+ output?: unknown;
31
+ duration: number;
32
+ };
33
+ session_start: {
34
+ sessionId: string;
35
+ projectId?: string;
36
+ agent?: string;
37
+ };
38
+ session_end: {
39
+ sessionId: string;
40
+ summary?: string;
41
+ };
42
+ plan_approved: {
43
+ sessionId: string;
44
+ planContent?: string;
45
+ };
46
+ plan_rejected: {
47
+ sessionId: string;
48
+ reason?: string;
49
+ };
50
+ agent_spawned: {
51
+ agentId: string;
52
+ agentType?: string;
53
+ parentId?: string;
54
+ };
55
+ agent_completed: {
56
+ agentId: string;
57
+ result?: unknown;
58
+ };
59
+ agent_failed: {
60
+ agentId: string;
61
+ error?: string;
62
+ retries?: number;
63
+ };
64
+ permission_denied: {
65
+ tool: string;
66
+ input?: unknown;
67
+ reason?: string;
68
+ };
69
+ external_event: {
70
+ event: SynthEvent;
71
+ };
72
+ message_received: {
73
+ source: string;
74
+ chatKey?: string;
75
+ threadKey?: string;
76
+ from?: string;
77
+ text?: string;
78
+ };
79
+ callback: {
80
+ source: string;
81
+ callbackId: string;
82
+ data?: unknown;
83
+ from?: string;
84
+ };
85
+ session_requested: {
86
+ reason?: string;
87
+ agentTemplate?: string;
88
+ project?: string;
89
+ initiator: EventInitiator;
90
+ };
91
+ schedule_fired: {
92
+ scheduleId: string;
93
+ cron?: string;
94
+ payload?: unknown;
95
+ };
96
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -318,6 +318,15 @@ export interface Message {
318
318
  export interface SessionStatus {
319
319
  blocked?: string;
320
320
  blockedAt?: string;
321
+ /**
322
+ * Персистентный флаг запроса отмены генерации (кнопка «Стоп», `/stop`).
323
+ * Живёт в JSON-хранилище (AD-005): позволяет остановить сессию, когда
324
+ * `currentStream`/cancel-token ещё не установлены (очередь, backoff).
325
+ * Сбрасывается процессором очереди после обработки.
326
+ */
327
+ cancelRequested?: boolean;
328
+ /** Время запроса отмены (ISO) — для диагностики/аудита. */
329
+ cancelRequestedAt?: string;
321
330
  }
322
331
  export declare const PLAN_MODES: readonly ["auto", "strict", "off"];
323
332
  export type PlanMode = (typeof PLAN_MODES)[number];
@@ -531,6 +540,12 @@ export interface SessionSettings {
531
540
  embedProvider?: string;
532
541
  /** Модель для embedding. */
533
542
  embedModel?: string;
543
+ /**
544
+ * AD-084: включить decision-уровень в микро-каскаде (перед локальной LLM).
545
+ * Не задано — берётся `config.decision.enabled`; `false` — принудительное
546
+ * отключение уровня в сессии.
547
+ */
548
+ decisionFirst?: boolean;
534
549
  /** Гранулярные permissions сессии. Приоритетнее глобальной секции permission в config.yaml. */
535
550
  permission?: PermissionConfig;
536
551
  /** Доступность MCP-инструментов по режимам plan/act (serverName → настройки). */
@@ -639,6 +654,13 @@ export interface Session {
639
654
  canSummarize: boolean;
640
655
  createdAt: string;
641
656
  updatedAt: string;
657
+ /**
658
+ * AD-089: ISO-8601 — время авто-архивации ephemeral-сессии (server-managed,
659
+ * клиент задать не может). Задан — сессия скрывается из списков по умолчанию.
660
+ */
661
+ expiresAt?: string;
662
+ /** AD-089: ISO-8601 — время архивации сессии (server-managed). */
663
+ archivedAt?: string;
642
664
  inputTokens: number;
643
665
  outputTokens: number;
644
666
  totalTokens: number;
@@ -969,6 +991,38 @@ export interface ContextFileContent {
969
991
  isOverridden: boolean;
970
992
  category: ContextCategory;
971
993
  }
994
+ /**
995
+ * AD-089: внешняя идентичность, привязанная к профилю пользователя.
996
+ * Ключ — `provider` + `externalId` (числовой id источника). `username`/
997
+ * `displayName` — display-кэш (может устареть), НЕ ключ.
998
+ */
999
+ export interface ExternalIdentity {
1000
+ /** Префикс principalId (AD-089), напр. 'tg' (Telegram). */
1001
+ provider: string;
1002
+ /** Числовой id в источнике, строкой (напр. '450316139'). */
1003
+ externalId: string;
1004
+ /** Display-кэш: username источника (может устареть). */
1005
+ username?: string;
1006
+ /** Display-кэш: отображаемое имя источника. */
1007
+ displayName?: string;
1008
+ /** ISO: когда привязано. */
1009
+ linkedAt: string;
1010
+ /** Кто подтвердил (id пользователя инстанса). */
1011
+ linkedBy?: string;
1012
+ }
1013
+ /**
1014
+ * AD-089: principalId внешнего отправителя из пары провайдер+id.
1015
+ * Формат — `<provider>:<externalId>` (напр. `tg:450316139`).
1016
+ */
1017
+ export declare function buildPrincipalId(provider: string, externalId: string): string;
1018
+ /**
1019
+ * AD-089: разбор principalId на `provider`/`externalId` — деление по **первому**
1020
+ * `:`. Невалидное (нет `:`, пустые части) → `null`.
1021
+ */
1022
+ export declare function parsePrincipalId(principalId: string): {
1023
+ provider: string;
1024
+ externalId: string;
1025
+ } | null;
972
1026
  export interface ProfileData {
973
1027
  id: string;
974
1028
  username: string;
@@ -979,7 +1033,21 @@ export interface ProfileData {
979
1033
  isActive: boolean;
980
1034
  preferences: Record<string, unknown>;
981
1035
  notes: string;
1036
+ /**
1037
+ * Онбординг-интервью пройдено. Отдельное поле вместо legacy-метки
1038
+ * `[ИНТЕРВЬЮ]` в свободном `notes`. Не задано (legacy-профиль) — бэкфилл при
1039
+ * чтении по наличию метки (`FileProfileStore._deserialize`).
1040
+ */
1041
+ interviewCompleted: boolean;
1042
+ /** ISO-время завершения интервью (для аудита/аналитики). */
1043
+ interviewCompletedAt?: string;
982
1044
  displayName?: string;
1045
+ /**
1046
+ * AD-089: внешние идентичности (Telegram и др.), привязанные к профилю.
1047
+ * Опционально — legacy-профили без поля трактуются как `[]`. Ключ — пара
1048
+ * `provider`+`externalId`; `username`/`displayName` — display-кэш.
1049
+ */
1050
+ identities?: ExternalIdentity[];
983
1051
  createdAt: string;
984
1052
  updatedAt: string;
985
1053
  lastLogin?: string;
@@ -1044,7 +1112,7 @@ export interface QueueItem {
1044
1112
  streamId: string;
1045
1113
  enqueuedAt: string;
1046
1114
  }
1047
- export type EventType = 'session.created' | 'session.updated' | 'session.deleted' | 'session.renamed' | 'session.forked' | 'session.fork.created' | 'session.reference.added' | 'session.reference.removed' | 'session.messages.merged' | 'session.moved' | 'project.updated' | 'fs.changed' | 'message.added' | 'message.updated' | 'child.message.added' | 'child.session.updated' | 'stream.start' | 'stream.chunk' | 'stream.usage' | 'stream.done' | 'stream.ended' | 'stream.cancelled' | 'stream.error' | 'stream.retry' | 'queue.stalled' | 'message.queued' | 'permission.asked' | 'permission.replied' | 'permission.hold' | 'question.asked' | 'question.replied' | 'context.summarization_pending' | 'context.summarized' | 'context.sliding_window_applied' | 'context.limit_warning' | 'context.sticky_note_added' | 'context.sticky_note_updated' | 'context.sticky_note_deleted' | 'context.instructions_loaded' | 'tool_call.started' | 'tool_call.result' | 'tool_call.loop' | 'subagent.progress' | 'subagent.retry' | 'subagent.resume.started' | 'subagent.resume.finished' | 'permission.asked' | 'permission.replied' | 'permission.denied' | 'message.quality_check' | 'session.routing_category' | 'plan.approved' | 'todos.updated' | 'skill.invoked' | 'command.invoked' | 'command.inline_shell' | 'error';
1115
+ export type EventType = 'session.created' | 'session.updated' | 'session.deleted' | 'session.renamed' | 'session.forked' | 'session.fork.created' | 'session.reference.added' | 'session.reference.removed' | 'session.messages.merged' | 'session.moved' | 'project.updated' | 'fs.changed' | 'message.added' | 'message.updated' | 'child.message.added' | 'child.session.updated' | 'stream.start' | 'stream.chunk' | 'stream.usage' | 'stream.done' | 'stream.ended' | 'stream.cancelled' | 'stream.error' | 'stream.retry' | 'queue.stalled' | 'message.queued' | 'permission.asked' | 'permission.replied' | 'permission.hold' | 'question.asked' | 'question.replied' | 'context.summarization_pending' | 'context.summarized' | 'context.sliding_window_applied' | 'context.limit_warning' | 'context.sticky_note_added' | 'context.sticky_note_updated' | 'context.sticky_note_deleted' | 'context.instructions_loaded' | 'tool_call.started' | 'tool_call.result' | 'tool_call.loop' | 'subagent.progress' | 'subagent.retry' | 'subagent.resume.started' | 'subagent.resume.finished' | 'permission.asked' | 'permission.replied' | 'permission.denied' | 'message.quality_check' | 'session.routing_category' | 'plan.approved' | 'todos.updated' | 'skill.invoked' | 'command.invoked' | 'command.inline_shell' | 'event.received' | 'event.routed' | 'binding.changed' | 'error';
1048
1116
  export interface BusEvent {
1049
1117
  type: EventType;
1050
1118
  sessionId: string;
@@ -1099,3 +1167,9 @@ export * from './tools.js';
1099
1167
  export * from './permission.js';
1100
1168
  export * from './skills.js';
1101
1169
  export * from './commands.js';
1170
+ export * from './events.js';
1171
+ export * from './hooks.js';
1172
+ export * from './schedules.js';
1173
+ export * from './decision.js';
1174
+ export * from './service-keys.js';
1175
+ export * from './webhooks.js';
@@ -194,6 +194,29 @@ export const DEFAULT_LLM_GATEWAY_RATE_LIMIT = {
194
194
  userPerMinute: 60,
195
195
  providerPerMinute: 120,
196
196
  };
197
+ /**
198
+ * AD-089: principalId внешнего отправителя из пары провайдер+id.
199
+ * Формат — `<provider>:<externalId>` (напр. `tg:450316139`).
200
+ */
201
+ export function buildPrincipalId(provider, externalId) {
202
+ return `${provider}:${externalId}`;
203
+ }
204
+ /**
205
+ * AD-089: разбор principalId на `provider`/`externalId` — деление по **первому**
206
+ * `:`. Невалидное (нет `:`, пустые части) → `null`.
207
+ */
208
+ export function parsePrincipalId(principalId) {
209
+ if (typeof principalId !== 'string')
210
+ return null;
211
+ const idx = principalId.indexOf(':');
212
+ if (idx <= 0 || idx === principalId.length - 1)
213
+ return null;
214
+ const provider = principalId.slice(0, idx);
215
+ const externalId = principalId.slice(idx + 1);
216
+ if (!provider || !externalId)
217
+ return null;
218
+ return { provider, externalId };
219
+ }
197
220
  // --- File System ---
198
221
  export var FsErrorCode;
199
222
  (function (FsErrorCode) {
@@ -218,3 +241,15 @@ export * from './permission.js';
218
241
  export * from './skills.js';
219
242
  // Slash-команды и bundles (AD-046 §7) — re-exported from commands.ts
220
243
  export * from './commands.js';
244
+ // Внешние события (AD-089) — re-exported from events.ts
245
+ export * from './events.js';
246
+ // Hooks агента и интеграций (AD-030) — re-exported from hooks.ts
247
+ export * from './hooks.js';
248
+ // Планировщик расписаний (AD-051 срез / AD-089) — re-exported from schedules.ts
249
+ export * from './schedules.js';
250
+ // Decision-модели (AD-084): контракт state+questions → answers — re-exported from decision.ts
251
+ export * from './decision.js';
252
+ // AD-052 (этап I): service-key — scopes + проектная проекция — re-exported from service-keys.ts
253
+ export * from './service-keys.js';
254
+ // AD-052 (этап II): исходящие webhooks — типы и матчер событий — re-exported from webhooks.ts
255
+ export * from './webhooks.js';
@@ -0,0 +1,109 @@
1
+ /**
2
+ * AD-051 (минимальный срез) / AD-089: контракты планировщика расписаний.
3
+ *
4
+ * Шедулер не создаёт сессии сам: срабатывание публикует нормализованное событие
5
+ * (`source: 'cron'`, `type: 'schedule_fired'`) через `EventIngress`, а
6
+ * маршрутизацию в сессию выполняет `EventRouter` (seam — `RouteRuleProvider`).
7
+ * Здесь только типы без бизнес-логики; cron/interval-парсеры живут в core.
8
+ */
9
+ /**
10
+ * AD-051/AD-089: цель срабатывания расписания.
11
+ * - `bound` — постоянная сессия (событие уходит в неё);
12
+ * - `ephemeral` — разовая сессия с TTL и авто-архивом;
13
+ * - `queue` — не запускать сразу, отложить владельцу.
14
+ */
15
+ export type ScheduleTarget = {
16
+ mode: 'bound';
17
+ sessionId: string;
18
+ } | {
19
+ mode: 'ephemeral';
20
+ agentTemplate?: string;
21
+ project?: string;
22
+ ttl?: string;
23
+ } | {
24
+ mode: 'queue';
25
+ sessionId: string;
26
+ };
27
+ /** AD-051/AD-089: статус последнего запуска расписания. */
28
+ export type ScheduleRunStatus = 'ok' | 'error' | 'skipped';
29
+ /**
30
+ * AD-051: триггер срабатывания расписания.
31
+ * - `cron` — обычный тик планировщика (или интервальное срабатывание);
32
+ * - `manual` — принудительный запуск (`POST /:id/run`, force);
33
+ * - `catchup` — догоняющее срабатывание после простоя.
34
+ */
35
+ export type ScheduleJobTrigger = 'cron' | 'manual' | 'catchup';
36
+ /**
37
+ * AD-051: запись Job-истории — результат одного срабатывания расписания.
38
+ *
39
+ * Append-only JSONL `{dataDir}/scheduler/jobs.jsonl`. `decision` — итог
40
+ * маршрутизации события (`RouteDecision['kind']`), `reason` — причина
41
+ * `drop`/`skip`, `sessionId` — материализованная Router'ом сессия (если была).
42
+ */
43
+ export interface ScheduleJob {
44
+ /** `job_<uuid>`, уникален в пределах инстанса. */
45
+ id: string;
46
+ scheduleId: string;
47
+ scheduleName: string;
48
+ trigger: ScheduleJobTrigger;
49
+ status: ScheduleRunStatus;
50
+ /** Начало срабатывания, ISO-8601. */
51
+ startedAt: string;
52
+ /** Окончание срабатывания, ISO-8601. */
53
+ finishedAt: string;
54
+ durationMs: number;
55
+ target: ScheduleTarget;
56
+ /** Ключ идемпотентности события (`cron:<id>:<...>`). */
57
+ dedupKey?: string;
58
+ /** Решение Router: `'bound' | 'queue' | 'ephemeral' | 'bind' | 'drop'`. */
59
+ decision?: 'bound' | 'queue' | 'ephemeral' | 'bind' | 'drop';
60
+ /** Причина `drop`/`skip` (напр. `no_route`, `busy`, `missed`). */
61
+ reason?: string;
62
+ /** Идентификатор сессии, в которую доставлено событие. */
63
+ sessionId?: string;
64
+ /** Текст ошибки при `status === 'error'`. */
65
+ error?: string;
66
+ }
67
+ /**
68
+ * AD-051/AD-089: расписание запуска промпта/события.
69
+ *
70
+ * Ровно одно из `cron` (5 полей) / `every` (интервал) задано; время cron
71
+ * считается в UTC. `payload` домешивается в тело события, `prompt` — текст
72
+ * сообщения (`payload.text`).
73
+ */
74
+ export interface Schedule {
75
+ /** `sch_<uuid>`, уникален в пределах инстанса. */
76
+ id: string;
77
+ name: string;
78
+ enabled: boolean;
79
+ /** Cron-выражение из 5 полей (`minute hour day-of-month month day-of-week`), UTC. */
80
+ cron?: string;
81
+ /** Интервал `30s | 15m | 1h | 24h`. */
82
+ every?: string;
83
+ target: ScheduleTarget;
84
+ /** Текст промпта (попадает в событие как `payload.text`). */
85
+ prompt?: string;
86
+ /** Дополнительные поля тела события. */
87
+ payload?: Record<string, unknown>;
88
+ /** Владелец расписания (попадает в `identity.principalId`). */
89
+ ownerId?: string;
90
+ /**
91
+ * AD-051: поведение при пропущенном срабатывании на старте процесса
92
+ * (`skip` — пропустить, `once` — одно догоняющее). Не задано — дефолт из
93
+ * конфига `scheduler.catchUp`.
94
+ */
95
+ catchUp?: 'skip' | 'once';
96
+ createdAt: string;
97
+ updatedAt: string;
98
+ /** Время последнего запуска, ISO-8601. */
99
+ lastRunAt?: string;
100
+ /** Время следующего запуска, ISO-8601. */
101
+ nextRunAt?: string;
102
+ lastStatus?: ScheduleRunStatus;
103
+ lastError?: string;
104
+ }
105
+ /**
106
+ * AD-051/AD-089: вход создания/обновления расписания — без служебных полей,
107
+ * которыми управляет хранилище/сервис (`id`, таймстемпы, статус последнего запуска).
108
+ */
109
+ export type ScheduleInput = Omit<Schedule, 'id' | 'createdAt' | 'updatedAt' | 'lastRunAt' | 'nextRunAt' | 'lastStatus' | 'lastError'>;
@@ -0,0 +1,9 @@
1
+ /**
2
+ * AD-051 (минимальный срез) / AD-089: контракты планировщика расписаний.
3
+ *
4
+ * Шедулер не создаёт сессии сам: срабатывание публикует нормализованное событие
5
+ * (`source: 'cron'`, `type: 'schedule_fired'`) через `EventIngress`, а
6
+ * маршрутизацию в сессию выполняет `EventRouter` (seam — `RouteRuleProvider`).
7
+ * Здесь только типы без бизнес-логики; cron/interval-парсеры живут в core.
8
+ */
9
+ export {};