@itphx/synth-shared 0.12.4 → 0.13.4

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 (41) hide show
  1. package/dist/config/defaults.js +97 -4
  2. package/dist/config/env-overrides.js +29 -0
  3. package/dist/config/resolve.d.ts +17 -0
  4. package/dist/config/resolve.js +40 -1
  5. package/dist/config/types.d.ts +394 -7
  6. package/dist/config/types.js +275 -6
  7. package/dist/i18n/index.d.ts +1 -1
  8. package/dist/i18n/index.js +188 -3
  9. package/dist/index.d.ts +2 -2
  10. package/dist/index.js +2 -2
  11. package/dist/schemas/index.d.ts +90 -10
  12. package/dist/schemas/index.js +55 -4
  13. package/dist/types/agent.d.ts +8 -1
  14. package/dist/types/bus-events.d.ts +59 -1
  15. package/dist/types/egress.d.ts +1 -1
  16. package/dist/types/egress.js +1 -1
  17. package/dist/types/file-kind.d.ts +40 -0
  18. package/dist/types/file-kind.js +157 -0
  19. package/dist/types/fs.d.ts +54 -1
  20. package/dist/types/fs.js +43 -0
  21. package/dist/types/git.d.ts +5 -0
  22. package/dist/types/index.d.ts +2 -0
  23. package/dist/types/index.js +6 -0
  24. package/dist/types/llm.d.ts +95 -0
  25. package/dist/types/llm.js +58 -0
  26. package/dist/types/message-stream.d.ts +348 -0
  27. package/dist/types/message-stream.js +41 -0
  28. package/dist/types/message.d.ts +49 -0
  29. package/dist/types/pack.d.ts +6 -6
  30. package/dist/types/permission.d.ts +26 -0
  31. package/dist/types/pipeline-engine.d.ts +2 -2
  32. package/dist/types/provider.d.ts +280 -0
  33. package/dist/types/provider.js +289 -0
  34. package/dist/types/session.d.ts +170 -3
  35. package/dist/types/tools.d.ts +21 -0
  36. package/dist/types/tools.js +1 -1
  37. package/dist/utils/reasoning.d.ts +18 -2
  38. package/dist/utils/reasoning.js +16 -7
  39. package/dist/version.d.ts +1 -1
  40. package/dist/version.js +1 -1
  41. package/package.json +2 -2
@@ -10,7 +10,13 @@ export declare enum FsErrorCode {
10
10
  ALREADY_EXISTS = "ALREADY_EXISTS",
11
11
  DIR_NOT_EMPTY = "DIR_NOT_EMPTY",
12
12
  /** ADR-075: путь вне `workspacesRoot` запрещён политикой (managed). */
13
- WORKSPACE_OUTSIDE_ROOT_DENIED = "WORKSPACE_OUTSIDE_ROOT_DENIED"
13
+ WORKSPACE_OUTSIDE_ROOT_DENIED = "WORKSPACE_OUTSIDE_ROOT_DENIED",
14
+ /**
15
+ * Чтение файла отказано: размер больше лимита чтения либо файл бинарный
16
+ * (HTTP 413). Машинный код ответа — `FILE_TOO_LARGE`, подробности —
17
+ * в `details` (`maxReadBytes`/`size`/`reason`).
18
+ */
19
+ FILE_TOO_LARGE = "FILE_TOO_LARGE"
14
20
  }
15
21
  export interface FileEntry {
16
22
  name: string;
@@ -22,6 +28,11 @@ export interface FileEntry {
22
28
  export interface DirectoryListResult {
23
29
  path: string;
24
30
  entries: FileEntry[];
31
+ /**
32
+ * Обход прерван по лимиту записей (`maxDepth > 0`): ответ — неполный.
33
+ * `maxDepth = 0` (по умолчанию) лимит не применяется → `false`.
34
+ */
35
+ truncated?: boolean;
25
36
  }
26
37
  export interface FileReadResult {
27
38
  path: string;
@@ -41,6 +52,11 @@ export interface FileMkdirBody {
41
52
  export interface FsError {
42
53
  error: string;
43
54
  code: FsErrorCode;
55
+ /**
56
+ * Подробности отказа (аддитивно): например, `maxReadBytes`/`size`/`reason`
57
+ * для `FILE_TOO_LARGE`. Клиент читает их машинно, не разбирая текст.
58
+ */
59
+ details?: Record<string, unknown>;
44
60
  }
45
61
  /**
46
62
  * Лимит загрузки файла (`POST /api/v2/fs/upload`) по умолчанию, байт: 100 МиБ.
@@ -53,3 +69,40 @@ export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
53
69
  export declare const MIN_UPLOAD_BYTES = 1024;
54
70
  /** Верхняя граница настраиваемого лимита загрузки (байт): 2 ГиБ (тело буферизуется в память). */
55
71
  export declare const MAX_UPLOAD_BYTES_LIMIT: number;
72
+ /**
73
+ * Лимит чтения файла (`GET /api/v2/fs/read`) по умолчанию, байт: 5 МиБ.
74
+ * Файл больше лимита (или бинарный) → `413` с машинным кодом `FILE_TOO_LARGE`
75
+ * и `details.maxReadBytes`; содержимое в память не читается (размер известен
76
+ * из `stat`). Переопределяется конфигом (`storage.maxReadBytes` / env
77
+ * `SYNTH_MAX_READ_BYTES`) или опцией фабрики `createFsRoutes`
78
+ * (`FsRoutesOptions.maxReadBytes`, для тестов).
79
+ */
80
+ export declare const DEFAULT_MAX_READ_BYTES: number;
81
+ /** Нижняя граница настраиваемого лимита чтения (байт). */
82
+ export declare const MIN_READ_BYTES = 1024;
83
+ /** Верхняя граница настраиваемого лимита чтения (байт): 512 МиБ (файл читается в память). */
84
+ export declare const MAX_READ_BYTES_LIMIT: number;
85
+ /**
86
+ * Лимит предпросмотра файла (`GET /api/v2/fs/raw`) по умолчанию, байт: 100 МиБ.
87
+ * Медиа-файлы (видео/аудио/изображения) заметно крупнее текстовых, поэтому
88
+ * лимит предпросмотра отдельный от `DEFAULT_MAX_READ_BYTES` (5 МиБ — чтение
89
+ * текста). Файл больше лимита → `413` с машинным кодом `FILE_TOO_LARGE` и
90
+ * `details.maxPreviewBytes`. Переопределяется конфигом
91
+ * (`storage.maxPreviewBytes` / env `SYNTH_MAX_PREVIEW_BYTES`) или опцией
92
+ * фабрики `createFsRoutes` (`FsRoutesOptions.maxPreviewBytes`, для тестов).
93
+ */
94
+ export declare const DEFAULT_MAX_PREVIEW_BYTES: number;
95
+ /** Нижняя граница настраиваемого лимита предпросмотра (байт). */
96
+ export declare const MIN_PREVIEW_BYTES = 1024;
97
+ /** Верхняя граница настраиваемого лимита предпросмотра (байт): 512 МиБ. */
98
+ export declare const MAX_PREVIEW_BYTES_LIMIT: number;
99
+ /**
100
+ * Жёсткий предел глубины рекурсивного листинга (`GET /api/v2/fs?maxDepth=`):
101
+ * значение из запроса ограничивается этим числом (было 10).
102
+ */
103
+ export declare const MAX_FS_LIST_DEPTH = 3;
104
+ /**
105
+ * Общий предел числа записей в рекурсивном листинге (`GET /api/v2/fs?maxDepth>0`):
106
+ * при достижении обход прекращается, в ответе `truncated: true`.
107
+ */
108
+ export declare const MAX_FS_LIST_ENTRIES = 10000;
package/dist/types/fs.js CHANGED
@@ -13,6 +13,12 @@ export var FsErrorCode;
13
13
  FsErrorCode["DIR_NOT_EMPTY"] = "DIR_NOT_EMPTY";
14
14
  /** ADR-075: путь вне `workspacesRoot` запрещён политикой (managed). */
15
15
  FsErrorCode["WORKSPACE_OUTSIDE_ROOT_DENIED"] = "WORKSPACE_OUTSIDE_ROOT_DENIED";
16
+ /**
17
+ * Чтение файла отказано: размер больше лимита чтения либо файл бинарный
18
+ * (HTTP 413). Машинный код ответа — `FILE_TOO_LARGE`, подробности —
19
+ * в `details` (`maxReadBytes`/`size`/`reason`).
20
+ */
21
+ FsErrorCode["FILE_TOO_LARGE"] = "FILE_TOO_LARGE";
16
22
  })(FsErrorCode || (FsErrorCode = {}));
17
23
  /**
18
24
  * Лимит загрузки файла (`POST /api/v2/fs/upload`) по умолчанию, байт: 100 МиБ.
@@ -25,3 +31,40 @@ export const DEFAULT_MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
25
31
  export const MIN_UPLOAD_BYTES = 1024;
26
32
  /** Верхняя граница настраиваемого лимита загрузки (байт): 2 ГиБ (тело буферизуется в память). */
27
33
  export const MAX_UPLOAD_BYTES_LIMIT = 2 * 1024 * 1024 * 1024;
34
+ /**
35
+ * Лимит чтения файла (`GET /api/v2/fs/read`) по умолчанию, байт: 5 МиБ.
36
+ * Файл больше лимита (или бинарный) → `413` с машинным кодом `FILE_TOO_LARGE`
37
+ * и `details.maxReadBytes`; содержимое в память не читается (размер известен
38
+ * из `stat`). Переопределяется конфигом (`storage.maxReadBytes` / env
39
+ * `SYNTH_MAX_READ_BYTES`) или опцией фабрики `createFsRoutes`
40
+ * (`FsRoutesOptions.maxReadBytes`, для тестов).
41
+ */
42
+ export const DEFAULT_MAX_READ_BYTES = 5 * 1024 * 1024;
43
+ /** Нижняя граница настраиваемого лимита чтения (байт). */
44
+ export const MIN_READ_BYTES = 1024;
45
+ /** Верхняя граница настраиваемого лимита чтения (байт): 512 МиБ (файл читается в память). */
46
+ export const MAX_READ_BYTES_LIMIT = 512 * 1024 * 1024;
47
+ /**
48
+ * Лимит предпросмотра файла (`GET /api/v2/fs/raw`) по умолчанию, байт: 100 МиБ.
49
+ * Медиа-файлы (видео/аудио/изображения) заметно крупнее текстовых, поэтому
50
+ * лимит предпросмотра отдельный от `DEFAULT_MAX_READ_BYTES` (5 МиБ — чтение
51
+ * текста). Файл больше лимита → `413` с машинным кодом `FILE_TOO_LARGE` и
52
+ * `details.maxPreviewBytes`. Переопределяется конфигом
53
+ * (`storage.maxPreviewBytes` / env `SYNTH_MAX_PREVIEW_BYTES`) или опцией
54
+ * фабрики `createFsRoutes` (`FsRoutesOptions.maxPreviewBytes`, для тестов).
55
+ */
56
+ export const DEFAULT_MAX_PREVIEW_BYTES = 100 * 1024 * 1024;
57
+ /** Нижняя граница настраиваемого лимита предпросмотра (байт). */
58
+ export const MIN_PREVIEW_BYTES = 1024;
59
+ /** Верхняя граница настраиваемого лимита предпросмотра (байт): 512 МиБ. */
60
+ export const MAX_PREVIEW_BYTES_LIMIT = 512 * 1024 * 1024;
61
+ /**
62
+ * Жёсткий предел глубины рекурсивного листинга (`GET /api/v2/fs?maxDepth=`):
63
+ * значение из запроса ограничивается этим числом (было 10).
64
+ */
65
+ export const MAX_FS_LIST_DEPTH = 3;
66
+ /**
67
+ * Общий предел числа записей в рекурсивном листинге (`GET /api/v2/fs?maxDepth>0`):
68
+ * при достижении обход прекращается, в ответе `truncated: true`.
69
+ */
70
+ export const MAX_FS_LIST_ENTRIES = 10_000;
@@ -60,4 +60,9 @@ export interface CommitFileInfo {
60
60
  export interface CommitDetail extends CommitInfo {
61
61
  files: CommitFileInfo[];
62
62
  diff: string;
63
+ /**
64
+ * Diff обрезан по лимиту размера (`MAX_COMMIT_DIFF_BYTES`): поле присутствует
65
+ * и равно `true`, когда diff неполон. Отсутствует — diff отдан целиком.
66
+ */
67
+ diff_truncated?: boolean;
63
68
  }
@@ -13,8 +13,10 @@ export * from './agent.js';
13
13
  export * from './provider.js';
14
14
  export * from './llm.js';
15
15
  export * from './bus-events.js';
16
+ export * from './message-stream.js';
16
17
  export * from './steering.js';
17
18
  export * from './fs.js';
19
+ export * from './file-kind.js';
18
20
  export * from './tools.js';
19
21
  export * from './permission.js';
20
22
  export * from './skills.js';
@@ -32,10 +32,16 @@ export * from './provider.js';
32
32
  export * from './llm.js';
33
33
  // EventType/BusEvent — шина событий сессии (ADR-009/024)
34
34
  export * from './bus-events.js';
35
+ // ADR-118: контракт «Поток сообщений v2» — модель хода (Turn/Step/Part),
36
+ // контракт приёма `202 {messageId, mode, position}` и payload'ы новых событий.
37
+ export * from './message-stream.js';
35
38
  // ADR-104: режимы отправки сообщения во время хода (steering)
36
39
  export * from './steering.js';
37
40
  // Файловая система (FS API v2)
38
41
  export * from './fs.js';
42
+ // Классификация файла по расширению (kind/MIME, allow-list inline-предпросмотра)
43
+ // — browser-safe контракт для UI и ядра.
44
+ export * from './file-kind.js';
39
45
  // --- Реэкспорт существующих доменных модулей ---
40
46
  // Tool types — re-exported from tools.ts
41
47
  export * from './tools.js';
@@ -1,3 +1,5 @@
1
+ import type { ReasoningLevel } from './session.js';
2
+ import type { Currency } from './provider.js';
1
3
  /**
2
4
  * ADR-036/ADR-072: дефолт rate limit LLM Gateway. Единый источник для Zod-схемы
3
5
  * конфига и runtime-дефолтов (settings-роуты, fallback'и backend/core).
@@ -6,6 +8,25 @@ export declare const DEFAULT_LLM_GATEWAY_RATE_LIMIT: {
6
8
  readonly userPerMinute: 60;
7
9
  readonly providerPerMinute: 120;
8
10
  };
11
+ /**
12
+ * ADR-117: тир усилия модели (effort) — масштаб opencode
13
+ * (`packages/ai/src/schema/options.ts`). Anthropic 5.x принимает его в
14
+ * `output_config.effort`; передаётся из `ChatOptions.effort` (явно) либо
15
+ * выводится из `reasoningLevel` (`effortForReasoningLevel`).
16
+ */
17
+ export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
18
+ export type EffortLevel = (typeof EFFORT_LEVELS)[number];
19
+ /** Проверка, что значение — допустимый тир effort. */
20
+ export declare function isEffortLevel(value: unknown): value is EffortLevel;
21
+ /**
22
+ * Маппинг `reasoningLevel` → `effort`.
23
+ *
24
+ * Только прямые соответствия `low|medium|high`; `default`/`none` — `undefined`
25
+ * (параметр не отправляется), потому что «выключить размышления» через
26
+ * effort-тир не выразить: у effort-моделей это другой режим, и выдумывать
27
+ * значение нельзя. `xhigh`/`max` существуют только как явный `ChatOptions.effort`.
28
+ */
29
+ export declare function effortForReasoningLevel(level?: ReasoningLevel): EffortLevel | undefined;
9
30
  export interface TokenUsage {
10
31
  inputTokens: number;
11
32
  outputTokens: number;
@@ -13,6 +34,46 @@ export interface TokenUsage {
13
34
  cacheReadTokens?: number;
14
35
  cacheWriteTokens?: number;
15
36
  reasoningTokens?: number;
37
+ /**
38
+ * ADR-102/ADR-118 (паритет с opencode `Usage.cost`): стоимость вызова,
39
+ * если провайдер вернул её сам. Приоритетнее каталожной цены модели.
40
+ * `amount` в `currency`; `0` — достоверная нулевая стоимость.
41
+ */
42
+ cost?: {
43
+ amount: number;
44
+ currency: Currency;
45
+ };
46
+ }
47
+ /**
48
+ * Нормализованная причина завершения ответа модели (единый словарь для всех
49
+ * протоколов).
50
+ *
51
+ * Зачем: провайдеры сообщают причину по-разному (`stop_reason` у Anthropic,
52
+ * `finish_reason` у OpenAI-совместимых, `done_reason` у Ollama), а потребителю
53
+ * (оркестратору) нужно отличать «модель ничего не сказала» от «ответ срезан
54
+ * лимитом вывода»: при `max_tokens` пустой `content` — это не пустой ответ, а
55
+ * исчерпанный бюджет (например, adaptive thinking съел весь `max_tokens`).
56
+ *
57
+ * - `end_turn` — естественное завершение;
58
+ * - `tool_use` — модель просит вызвать инструмент;
59
+ * - `max_tokens` — ответ срезан лимитом вывода (в т.ч. весь ушёл в reasoning);
60
+ * - `stop_sequence` — сработала стоп-последовательность;
61
+ * - `length` — то же, что `max_tokens` (сырое значение Ollama/части API);
62
+ * - `content_filter` — завершение фильтром провайдера;
63
+ * - `error` — завершение по ошибке провайдера;
64
+ * - `unknown` — причина есть, но не распознана.
65
+ */
66
+ export declare const LLM_FINISH_REASONS: readonly ["end_turn", "tool_use", "max_tokens", "stop_sequence", "length", "content_filter", "error", "unknown"];
67
+ export type LlmFinishReason = (typeof LLM_FINISH_REASONS)[number];
68
+ /**
69
+ * Anthropic-протокол: один блок размышлений ответа. `signature` — подпись
70
+ * thinking-блока, `redactedData` — opaque-данные `redacted_thinking`
71
+ * (блок без видимого текста). Порядок элементов — порядок блоков в ответе.
72
+ */
73
+ export interface LLMReasoningBlock {
74
+ text: string;
75
+ signature?: string;
76
+ redactedData?: string;
16
77
  }
17
78
  export interface LLMChunk {
18
79
  content: string;
@@ -20,7 +81,33 @@ export interface LLMChunk {
20
81
  usage?: TokenUsage;
21
82
  toolCalls?: Record<string, unknown>[];
22
83
  reasoning?: string;
84
+ /**
85
+ * Anthropic: все блоки размышлений ответа (по блокам, с подписями).
86
+ * `reasoning` — накопленный текст для UI/учёта токенов; подпись валидна
87
+ * только для своего блока, поэтому при нескольких блоках реплей идёт отсюда.
88
+ */
89
+ reasoningBlocks?: LLMReasoningBlock[];
90
+ /**
91
+ * Anthropic-протокол: подпись thinking-блока (`signature`). Без возврата этой
92
+ * подписи в историю Anthropic отвергает следующий запрос tool-loop
93
+ * («Expected `thinking`…»). Пустая строка — валидная подпись (RouterAI/qwen
94
+ * отдают `"signature": ""`). Аддитивное поле: остальные провайдеры его не
95
+ * заполняют.
96
+ */
97
+ reasoningSignature?: string;
98
+ /**
99
+ * Anthropic-протокол: opaque-данные блоков `redacted_thinking` (verbatim
100
+ * `data`) — реплеятся в историю без изменений.
101
+ */
102
+ reasoningRedacted?: string[];
23
103
  model?: string;
104
+ /**
105
+ * Причина завершения ответа (нормализованный словарь `LlmFinishReason`).
106
+ * Аддитивное поле: заполняется адаптерами протоколов (Anthropic —
107
+ * `stop_reason`, OpenAI — `finish_reason`, Ollama — `done_reason`), иначе
108
+ * `undefined`. Значимо в финальном чанке (`isFinal: true`).
109
+ */
110
+ finishReason?: LlmFinishReason;
24
111
  }
25
112
  export interface LLMResponse {
26
113
  content: string;
@@ -28,5 +115,13 @@ export interface LLMResponse {
28
115
  usage: TokenUsage;
29
116
  toolCalls?: Record<string, unknown>[];
30
117
  reasoning?: string;
118
+ /** Anthropic: блоки размышлений ответа (см. `LLMChunk.reasoningBlocks`). */
119
+ reasoningBlocks?: LLMReasoningBlock[];
120
+ /** Anthropic: подпись thinking-блока (см. `LLMChunk.reasoningSignature`). */
121
+ reasoningSignature?: string;
122
+ /** Anthropic: opaque-данные `redacted_thinking` (см. `LLMChunk.reasoningRedacted`). */
123
+ reasoningRedacted?: string[];
124
+ /** Причина завершения ответа (см. `LLMChunk.finishReason`). */
125
+ finishReason?: LlmFinishReason;
31
126
  debugInfo?: Record<string, unknown>;
32
127
  }
package/dist/types/llm.js CHANGED
@@ -6,3 +6,61 @@ export const DEFAULT_LLM_GATEWAY_RATE_LIMIT = {
6
6
  userPerMinute: 60,
7
7
  providerPerMinute: 120,
8
8
  };
9
+ // --- LLM ---
10
+ /**
11
+ * ADR-117: тир усилия модели (effort) — масштаб opencode
12
+ * (`packages/ai/src/schema/options.ts`). Anthropic 5.x принимает его в
13
+ * `output_config.effort`; передаётся из `ChatOptions.effort` (явно) либо
14
+ * выводится из `reasoningLevel` (`effortForReasoningLevel`).
15
+ */
16
+ export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
17
+ /** Проверка, что значение — допустимый тир effort. */
18
+ export function isEffortLevel(value) {
19
+ return typeof value === 'string' && EFFORT_LEVELS.includes(value);
20
+ }
21
+ /**
22
+ * Маппинг `reasoningLevel` → `effort`.
23
+ *
24
+ * Только прямые соответствия `low|medium|high`; `default`/`none` — `undefined`
25
+ * (параметр не отправляется), потому что «выключить размышления» через
26
+ * effort-тир не выразить: у effort-моделей это другой режим, и выдумывать
27
+ * значение нельзя. `xhigh`/`max` существуют только как явный `ChatOptions.effort`.
28
+ */
29
+ export function effortForReasoningLevel(level) {
30
+ if (level === 'low')
31
+ return 'low';
32
+ if (level === 'medium')
33
+ return 'medium';
34
+ if (level === 'high')
35
+ return 'high';
36
+ return undefined;
37
+ }
38
+ /**
39
+ * Нормализованная причина завершения ответа модели (единый словарь для всех
40
+ * протоколов).
41
+ *
42
+ * Зачем: провайдеры сообщают причину по-разному (`stop_reason` у Anthropic,
43
+ * `finish_reason` у OpenAI-совместимых, `done_reason` у Ollama), а потребителю
44
+ * (оркестратору) нужно отличать «модель ничего не сказала» от «ответ срезан
45
+ * лимитом вывода»: при `max_tokens` пустой `content` — это не пустой ответ, а
46
+ * исчерпанный бюджет (например, adaptive thinking съел весь `max_tokens`).
47
+ *
48
+ * - `end_turn` — естественное завершение;
49
+ * - `tool_use` — модель просит вызвать инструмент;
50
+ * - `max_tokens` — ответ срезан лимитом вывода (в т.ч. весь ушёл в reasoning);
51
+ * - `stop_sequence` — сработала стоп-последовательность;
52
+ * - `length` — то же, что `max_tokens` (сырое значение Ollama/части API);
53
+ * - `content_filter` — завершение фильтром провайдера;
54
+ * - `error` — завершение по ошибке провайдера;
55
+ * - `unknown` — причина есть, но не распознана.
56
+ */
57
+ export const LLM_FINISH_REASONS = [
58
+ 'end_turn',
59
+ 'tool_use',
60
+ 'max_tokens',
61
+ 'stop_sequence',
62
+ 'length',
63
+ 'content_filter',
64
+ 'error',
65
+ 'unknown',
66
+ ];