@itphx/synth-shared 0.9.0 → 0.10.1

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.
Files changed (72) hide show
  1. package/dist/config/defaults.js +51 -1
  2. package/dist/config/env-overrides.d.ts +68 -0
  3. package/dist/config/env-overrides.js +165 -0
  4. package/dist/config/index.d.ts +1 -0
  5. package/dist/config/index.js +1 -0
  6. package/dist/config/loader.d.ts +3 -1
  7. package/dist/config/loader.js +12 -4
  8. package/dist/config/resolve.d.ts +23 -6
  9. package/dist/config/resolve.js +33 -12
  10. package/dist/config/types.d.ts +699 -146
  11. package/dist/config/types.js +195 -28
  12. package/dist/i18n/index.d.ts +1 -1
  13. package/dist/i18n/index.js +50 -8
  14. package/dist/index.d.ts +4 -2
  15. package/dist/index.js +3 -2
  16. package/dist/interfaces/index.d.ts +8 -1
  17. package/dist/schemas/index.d.ts +1723 -45
  18. package/dist/schemas/index.js +403 -29
  19. package/dist/skills/frontmatter.js +1 -1
  20. package/dist/types/agent.d.ts +30 -0
  21. package/dist/types/agent.js +1 -0
  22. package/dist/types/bus-events.d.ts +7 -0
  23. package/dist/types/bus-events.js +1 -0
  24. package/dist/types/commands.d.ts +10 -10
  25. package/dist/types/commands.js +2 -2
  26. package/dist/types/decision.d.ts +502 -0
  27. package/dist/types/decision.js +98 -0
  28. package/dist/types/events.d.ts +219 -0
  29. package/dist/types/events.js +1 -0
  30. package/dist/types/fs.d.ts +44 -0
  31. package/dist/types/fs.js +16 -0
  32. package/dist/types/git.d.ts +63 -0
  33. package/dist/types/git.js +1 -0
  34. package/dist/types/hooks.d.ts +96 -0
  35. package/dist/types/hooks.js +1 -0
  36. package/dist/types/index.d.ts +18 -1097
  37. package/dist/types/index.js +44 -215
  38. package/dist/types/llm.d.ts +32 -0
  39. package/dist/types/llm.js +8 -0
  40. package/dist/types/mcp.d.ts +104 -0
  41. package/dist/types/mcp.js +40 -0
  42. package/dist/types/message.d.ts +63 -0
  43. package/dist/types/message.js +12 -0
  44. package/dist/types/permission.d.ts +2 -2
  45. package/dist/types/permission.js +1 -1
  46. package/dist/types/project.d.ts +134 -0
  47. package/dist/types/project.js +67 -0
  48. package/dist/types/prompt.d.ts +236 -0
  49. package/dist/types/prompt.js +15 -0
  50. package/dist/types/provider.d.ts +84 -0
  51. package/dist/types/provider.js +35 -0
  52. package/dist/types/schedules.d.ts +109 -0
  53. package/dist/types/schedules.js +9 -0
  54. package/dist/types/service-keys.d.ts +106 -0
  55. package/dist/types/service-keys.js +72 -0
  56. package/dist/types/session.d.ts +269 -0
  57. package/dist/types/session.js +13 -0
  58. package/dist/types/skills.d.ts +11 -11
  59. package/dist/types/skills.js +6 -6
  60. package/dist/types/tools.d.ts +4 -3
  61. package/dist/types/tools.js +2 -0
  62. package/dist/types/user.d.ts +113 -0
  63. package/dist/types/user.js +31 -0
  64. package/dist/types/webhooks.d.ts +97 -0
  65. package/dist/types/webhooks.js +53 -0
  66. package/dist/utils/glob.d.ts +1 -1
  67. package/dist/utils/glob.js +1 -1
  68. package/dist/utils/index.js +2 -2
  69. package/dist/utils/workspace.js +1 -1
  70. package/dist/version.d.ts +1 -1
  71. package/dist/version.js +1 -1
  72. package/package.json +1 -1
@@ -0,0 +1,219 @@
1
+ /**
2
+ * ADR-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
+ /** ADR-089: идентичность отправителя события (маппинг на RBAC — ADR-029/ADR-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
+ /** ADR-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
+ /** Нормализованное тело: текст, ссылки на вложения (PROP-085), метаданные. */
35
+ payload: unknown;
36
+ identity: EventIdentity;
37
+ /** Стабильный ключ идемпотентности. */
38
+ dedupKey: string;
39
+ /** Время события, ISO-8601. */
40
+ ts: string;
41
+ }
42
+ /** ADR-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
+ /** Шаблон агента/скилла для создания/настройки сессии (ADR-046). */
54
+ agentTemplate?: string;
55
+ /** `projectId` — контейнер сессии (ADR-014). */
56
+ project?: string;
57
+ }
58
+ /** ADR-089/ADR-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
+ * Опциональный лимит запросов в минуту для этого ключа (ADR-089/ADR-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
+ * ADR-052 (задел): ISO-8601 срок действия ключа. Заполнен и уже прошёл —
82
+ * ключ недействителен (`resolveBySecret` → `null`). Не задан — бессрочно.
83
+ */
84
+ expiresAt?: string;
85
+ /**
86
+ * ADR-052 (задел): ISO-8601 отзыв ключа (мягкое удаление). Заполнен —
87
+ * ключ недействителен независимо от срока (`EventApiKeyStore.revoke`).
88
+ */
89
+ revokedAt?: string;
90
+ }
91
+ /** ADR-089: ответ создания ключа — метаданные + однократно показываемый секрет. */
92
+ export interface EventBindingApiKeyCreated extends EventBindingApiKey {
93
+ /** Plaintext-секрет; возвращается единственный раз при создании. */
94
+ key: string;
95
+ }
96
+ /**
97
+ * ADR-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
+ * ADR-089 (auto-bind): правило закрепляет внешний адрес события
114
+ * (`chatKey`/`threadKey`) за сессией — Router создаёт `EventBinding`
115
+ * (`mode='bound'`) при первой доставке.
116
+ */
117
+ | {
118
+ mode: 'bind';
119
+ agentTemplate?: string;
120
+ project?: string;
121
+ };
122
+ /** ADR-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
+ /** ADR-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
+ * ADR-089/ADR-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
+ /** ADR-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
+ * ADR-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
+ /** ADR-089: решение Router — куда направить событие (или отложить/отбросить). */
190
+ export type RouteDecision = RouteDecisionKind & RouteDecisionMeta;
191
+ /** ADR-089: инициатор запроса на сессию. */
192
+ export type EventInitiator = 'user' | 'agent' | 'external' | 'system';
193
+ /**
194
+ * ADR-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,44 @@
1
+ export declare enum FsErrorCode {
2
+ PATH_TRAVERSAL = "PATH_TRAVERSAL",
3
+ NOT_FOUND = "NOT_FOUND",
4
+ NOT_A_DIRECTORY = "NOT_A_DIRECTORY",
5
+ IS_DIRECTORY = "IS_DIRECTORY",
6
+ BINARY_FILE = "BINARY_FILE",
7
+ WORKSPACE_NOT_SET = "WORKSPACE_NOT_SET",
8
+ WORKSPACE_NOT_FOUND = "WORKSPACE_NOT_FOUND",
9
+ PERMISSION_DENIED = "PERMISSION_DENIED",
10
+ ALREADY_EXISTS = "ALREADY_EXISTS",
11
+ DIR_NOT_EMPTY = "DIR_NOT_EMPTY",
12
+ /** ADR-075: путь вне `workspacesRoot` запрещён политикой (managed). */
13
+ WORKSPACE_OUTSIDE_ROOT_DENIED = "WORKSPACE_OUTSIDE_ROOT_DENIED"
14
+ }
15
+ export interface FileEntry {
16
+ name: string;
17
+ path: string;
18
+ isDirectory: boolean;
19
+ size: number;
20
+ modifiedAt: number;
21
+ }
22
+ export interface DirectoryListResult {
23
+ path: string;
24
+ entries: FileEntry[];
25
+ }
26
+ export interface FileReadResult {
27
+ path: string;
28
+ content: string;
29
+ size: number;
30
+ encoding: 'utf-8' | 'binary';
31
+ }
32
+ export interface FileWriteBody {
33
+ projectId: string;
34
+ path: string;
35
+ content: string;
36
+ }
37
+ export interface FileMkdirBody {
38
+ projectId: string;
39
+ path: string;
40
+ }
41
+ export interface FsError {
42
+ error: string;
43
+ code: FsErrorCode;
44
+ }
@@ -0,0 +1,16 @@
1
+ // --- File System ---
2
+ export var FsErrorCode;
3
+ (function (FsErrorCode) {
4
+ FsErrorCode["PATH_TRAVERSAL"] = "PATH_TRAVERSAL";
5
+ FsErrorCode["NOT_FOUND"] = "NOT_FOUND";
6
+ FsErrorCode["NOT_A_DIRECTORY"] = "NOT_A_DIRECTORY";
7
+ FsErrorCode["IS_DIRECTORY"] = "IS_DIRECTORY";
8
+ FsErrorCode["BINARY_FILE"] = "BINARY_FILE";
9
+ FsErrorCode["WORKSPACE_NOT_SET"] = "WORKSPACE_NOT_SET";
10
+ FsErrorCode["WORKSPACE_NOT_FOUND"] = "WORKSPACE_NOT_FOUND";
11
+ FsErrorCode["PERMISSION_DENIED"] = "PERMISSION_DENIED";
12
+ FsErrorCode["ALREADY_EXISTS"] = "ALREADY_EXISTS";
13
+ FsErrorCode["DIR_NOT_EMPTY"] = "DIR_NOT_EMPTY";
14
+ /** ADR-075: путь вне `workspacesRoot` запрещён политикой (managed). */
15
+ FsErrorCode["WORKSPACE_OUTSIDE_ROOT_DENIED"] = "WORKSPACE_OUTSIDE_ROOT_DENIED";
16
+ })(FsErrorCode || (FsErrorCode = {}));
@@ -0,0 +1,63 @@
1
+ /**
2
+ * ADR-076: запись реестра git-репозиториев проекта. Старые данные (`repos` как
3
+ * `string[]` либо `{ path }`) нормализуются через `normalizeGitRepoConfig`.
4
+ */
5
+ export interface GitRepoConfig {
6
+ /** Стабильный id записи реестра (uuid); отсутствует у обнаруженных scan-ом. */
7
+ id?: string;
8
+ name?: string;
9
+ url?: string;
10
+ type?: 'https' | 'ssh';
11
+ /** Относительный путь ВНУТРИ project.workspace (допускает вложенность). */
12
+ path: string;
13
+ defaultBranch?: string;
14
+ sshKeyId?: string;
15
+ lastFetch?: string;
16
+ }
17
+ /**
18
+ * ADR-076: SSH-ключ агента — отдельная сущность реестра (не в
19
+ * `AgentDefinition`). Секреты `privateKey`/`passphrase` шифруются at-rest
20
+ * (AES-256-GCM; реализация — в core) и НИКОГДА не отдаются через API.
21
+ */
22
+ export interface SSHKey {
23
+ id: string;
24
+ name: string;
25
+ /** Метка типа ключа, дефолт `'user'`. */
26
+ type?: string;
27
+ privateKey: string;
28
+ passphrase?: string;
29
+ /** Привязка к агентам: один ключ может обслуживать несколько агентов. */
30
+ agentIds: string[];
31
+ createdAt: string;
32
+ updatedAt?: string;
33
+ }
34
+ /** Публичное представление ключа (без `privateKey`/`passphrase`). */
35
+ export type SSHKeyMeta = Omit<SSHKey, 'privateKey' | 'passphrase'>;
36
+ export interface RepoStatus {
37
+ path: string;
38
+ isRepo: boolean;
39
+ currentBranch?: string;
40
+ lastCommitAt?: string;
41
+ lastCommitSubject?: string;
42
+ }
43
+ export interface CommitInfo {
44
+ hash: string;
45
+ shortHash: string;
46
+ subject: string;
47
+ message: string;
48
+ author: string;
49
+ authorEmail: string;
50
+ date: string;
51
+ relativeDate: string;
52
+ branch: string;
53
+ }
54
+ export interface CommitFileInfo {
55
+ path: string;
56
+ status: 'added' | 'modified' | 'deleted' | 'renamed';
57
+ additions: number;
58
+ deletions: number;
59
+ }
60
+ export interface CommitDetail extends CommitInfo {
61
+ files: CommitFileInfo[];
62
+ diff: string;
63
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,96 @@
1
+ /**
2
+ * ADR-030: контракты hook-шины событий агента и интеграций. Система хуков не
3
+ * реализована в рантайме (Plugin SDK — отдельный этап), здесь только типы:
4
+ * имена хуков, режим выполнения, результат и карта контекстов.
5
+ */
6
+ import type { SynthEvent, EventInitiator } from './events.js';
7
+ /** ADR-030: имена хуков жизненного цикла агента и интеграций (ADR-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
+ /** ADR-030: результат хука. `block`/`reason` — только для `sync`. */
15
+ export interface HookResult {
16
+ block?: boolean;
17
+ reason?: string;
18
+ patch?: Record<string, unknown>;
19
+ }
20
+ /** ADR-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 {};