minicode-ai 0.11.0 → 0.13.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.
Files changed (221) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/LICENSE +21 -21
  3. package/README.md +4 -4
  4. package/cli/args.ts +46 -0
  5. package/cli/commands/acp.ts +163 -10
  6. package/cli/commands/config.ts +33 -18
  7. package/cli/commands/daemon.ts +515 -0
  8. package/cli/commands/exec.ts +145 -53
  9. package/cli/commands/openwork.ts +986 -0
  10. package/cli/commands/sessions.ts +4 -1
  11. package/cli/commands/stats.ts +34 -4
  12. package/cli/commands.ts +217 -2
  13. package/cli/index.ts +146 -14
  14. package/cli/recovery-warning.ts +115 -0
  15. package/cli/router.ts +32 -1
  16. package/cli/setup.ts +2332 -171
  17. package/cli/tui.ts +113 -7
  18. package/docs/OUTPUT_ARCHITECTURE_AUDIT.md +489 -0
  19. package/docs/OUTPUT_EVENT_MODEL.md +289 -0
  20. package/docs/OUTPUT_IMPLEMENTATION_PLAN.md +391 -0
  21. package/docs/OUTPUT_PROTOCOL_SPEC.md +285 -0
  22. package/docs/OUTPUT_RENDERING_SPEC.md +248 -0
  23. package/docs/OUTPUT_UX_RULES.md +449 -0
  24. package/docs/PLAN_UIUX_V6.md +2 -2
  25. package/docs/README.md +4 -3
  26. package/docs/TERMINAL_CONTRACT.md +278 -66
  27. package/docs/architecture.md +89 -7
  28. package/docs/changelog.md +1 -1
  29. package/docs/choosing-mode.md +2 -2
  30. package/docs/cli.md +9 -5
  31. package/docs/concepts.md +1 -1
  32. package/docs/contributing.md +9 -2
  33. package/docs/environment.md +6 -2
  34. package/docs/exec.md +46 -5
  35. package/docs/memory-sessions.md +2 -0
  36. package/docs/policy-sandbox.md +1 -1
  37. package/docs/pricing-budget.md +1 -1
  38. package/docs/quickstart.md +2 -2
  39. package/docs/repl.md +6 -2
  40. package/docs/security-model.md +1 -1
  41. package/docs/security.md +1 -1
  42. package/docs/skills.md +2 -2
  43. package/docs/terminal.md +9 -5
  44. package/docs/tools.md +1 -1
  45. package/package.json +35 -5
  46. package/src/app/session.ts +261 -15
  47. package/src/app/tool-layer.ts +94 -7
  48. package/src/daemon/approvals.ts +361 -0
  49. package/src/daemon/capability.ts +145 -0
  50. package/src/daemon/children.ts +142 -0
  51. package/src/daemon/client.ts +267 -0
  52. package/src/daemon/control.ts +350 -0
  53. package/src/daemon/discovery.ts +234 -0
  54. package/src/daemon/feed.ts +155 -0
  55. package/src/daemon/framing.ts +94 -0
  56. package/src/daemon/host.ts +316 -0
  57. package/src/daemon/protocol.ts +217 -0
  58. package/src/daemon/resource.ts +170 -0
  59. package/src/daemon/sanitize.ts +57 -0
  60. package/src/daemon/server.ts +627 -0
  61. package/src/daemon/store.ts +317 -0
  62. package/src/daemon/subscription.ts +270 -0
  63. package/src/daemon/telemetry.ts +81 -0
  64. package/src/hooks/run.ts +12 -1
  65. package/src/lib/atomic-write.ts +29 -3
  66. package/src/lib/db-path.ts +26 -0
  67. package/src/lib/keystore.ts +544 -42
  68. package/src/lib/net.ts +43 -1
  69. package/src/lib/safe-open.ts +116 -1
  70. package/src/lib/session-id.ts +15 -0
  71. package/src/lsp/client.ts +123 -5
  72. package/src/mcp/client.ts +139 -17
  73. package/src/mcp/server.ts +177 -50
  74. package/src/mcp/transport.ts +16 -19
  75. package/src/memory/vector.ts +770 -55
  76. package/src/policy/allowlist.ts +14 -2
  77. package/src/policy/bash-guard.ts +105 -10
  78. package/src/policy/compaction.ts +82 -5
  79. package/src/policy/consequence-engine.ts +220 -0
  80. package/src/policy/context.ts +132 -0
  81. package/src/policy/executor.ts +187 -121
  82. package/src/policy/no-progress.ts +559 -0
  83. package/src/policy/permission.ts +4 -8
  84. package/src/policy/pricing.ts +17 -3
  85. package/src/policy/scrub.ts +69 -2
  86. package/src/policy/tool-contract.ts +515 -0
  87. package/src/policy/usage.ts +310 -24
  88. package/src/policy/verifier.ts +6 -3
  89. package/src/policy/work-mode.ts +182 -0
  90. package/src/presentation/adapter.ts +533 -26
  91. package/src/presentation/events.ts +151 -0
  92. package/src/presentation/model.ts +180 -27
  93. package/src/presentation/projection.ts +858 -0
  94. package/src/presentation/reducer.ts +645 -310
  95. package/src/presentation/store.ts +12 -7
  96. package/src/providers/anthropic.ts +18 -10
  97. package/src/providers/responses.ts +17 -7
  98. package/src/runtime/capability.ts +409 -0
  99. package/src/runtime/child-execution.ts +274 -0
  100. package/src/runtime/composition.ts +958 -0
  101. package/src/runtime/dispatch.ts +591 -0
  102. package/src/runtime/execution-backend.ts +632 -0
  103. package/src/runtime/execution-events.ts +272 -0
  104. package/src/runtime/execution-id.ts +230 -0
  105. package/src/runtime/execution-journal.ts +926 -0
  106. package/src/runtime/execution-kernel.ts +456 -0
  107. package/src/runtime/execution-registry.ts +379 -0
  108. package/src/runtime/process-supervision.ts +276 -0
  109. package/src/runtime/production-execution.ts +551 -0
  110. package/src/runtime/production-runtime.ts +217 -0
  111. package/src/runtime/recovery-safety.ts +70 -0
  112. package/src/runtime/recovery.ts +477 -0
  113. package/src/runtime/runtime-capabilities.ts +179 -0
  114. package/src/runtime/runtime-diagnostics.ts +141 -0
  115. package/src/runtime/runtime-host.ts +365 -0
  116. package/src/runtime/runtime-status-facts.ts +222 -0
  117. package/src/runtime/runtime-status-provider.ts +74 -0
  118. package/src/runtime/runtime-status.ts +459 -0
  119. package/src/runtime/runtime-task-admission.ts +101 -0
  120. package/src/runtime/supervisor.ts +444 -0
  121. package/src/session/authority.ts +168 -0
  122. package/src/session/checkpoint.ts +88 -1
  123. package/src/session/context-adapter.ts +251 -0
  124. package/src/session/context-assembly.ts +242 -0
  125. package/src/session/context-identity.ts +389 -0
  126. package/src/session/context-projection.ts +248 -0
  127. package/src/session/context-selector.ts +500 -0
  128. package/src/session/cross-session-adoption.ts +249 -0
  129. package/src/session/full-history-fold.ts +171 -0
  130. package/src/session/identity.ts +192 -0
  131. package/src/session/journal.ts +805 -102
  132. package/src/session/open-work-intent.ts +732 -0
  133. package/src/session/open-work.ts +767 -0
  134. package/src/session/pending-tools.ts +94 -0
  135. package/src/session/persistence.ts +3569 -127
  136. package/src/session/runtime-header.ts +208 -0
  137. package/src/session/shadow-git.ts +13 -5
  138. package/src/session/verification.ts +1623 -0
  139. package/src/task/assignment.ts +136 -0
  140. package/src/task/autonomous-adapter.ts +168 -0
  141. package/src/task/autonomous-context.ts +630 -0
  142. package/src/task/autonomous-policy.ts +490 -0
  143. package/src/task/continuity.ts +179 -0
  144. package/src/task/execution-cancellation.ts +165 -0
  145. package/src/task/graph-validate.ts +379 -0
  146. package/src/task/graph.ts +305 -0
  147. package/src/task/identity.ts +230 -0
  148. package/src/task/model.ts +417 -0
  149. package/src/task/production-scheduler.ts +293 -0
  150. package/src/task/readiness.ts +229 -0
  151. package/src/task/scheduler-observability.ts +387 -0
  152. package/src/task/scheduler.ts +1197 -0
  153. package/src/task/scheduling-policy.ts +165 -0
  154. package/src/task/session-authority.ts +148 -0
  155. package/src/task/session-ownership.ts +211 -0
  156. package/src/task/store.ts +2887 -0
  157. package/src/task/sync.ts +343 -0
  158. package/src/task/trigger.ts +260 -0
  159. package/src/tools/bash.ts +377 -211
  160. package/src/tools/code_run.ts +1 -1
  161. package/src/tools/delete_file.ts +1 -1
  162. package/src/tools/edit.ts +33 -6
  163. package/src/tools/evidence.ts +30 -0
  164. package/src/tools/git.ts +4 -4
  165. package/src/tools/glob.ts +12 -3
  166. package/src/tools/grep.ts +1 -1
  167. package/src/tools/lsp.ts +4 -4
  168. package/src/tools/mcp_call.ts +11 -4
  169. package/src/tools/memory.ts +153 -18
  170. package/src/tools/move_file.ts +1 -1
  171. package/src/tools/patch.ts +1 -1
  172. package/src/tools/read_file.ts +1 -1
  173. package/src/tools/read_image.ts +1 -1
  174. package/src/tools/submit_result.ts +1 -1
  175. package/src/tools/task.ts +437 -41
  176. package/src/tools/todo.ts +662 -35
  177. package/src/tools/web_fetch.ts +4 -2
  178. package/src/tools/web_search.ts +9 -3
  179. package/src/tools/write_file.ts +1 -1
  180. package/src/ui/assistant/simple.ts +123 -50
  181. package/src/ui/assistant/turn-status.ts +17 -3
  182. package/src/ui/contract.ts +184 -0
  183. package/src/ui/footer.ts +54 -18
  184. package/src/ui/i18n/en.ts +62 -6
  185. package/src/ui/i18n/id.ts +62 -6
  186. package/src/ui/input/prompt-engine.ts +120 -25
  187. package/src/ui/render/errors.ts +39 -1
  188. package/src/ui/render/markdown-table.ts +455 -0
  189. package/src/ui/render/markdown.ts +22 -1
  190. package/src/ui/render/table-grid.ts +184 -0
  191. package/src/ui/render/table.ts +15 -76
  192. package/src/ui/runtime/screen.ts +7 -2
  193. package/src/ui/runtime/statusline.ts +25 -6
  194. package/src/ui/tui/app.ts +598 -133
  195. package/src/ui/tui/transcript.ts +531 -89
  196. package/vendor/minicore/VENDOR.md +1 -1
  197. package/vendor/minicore/src/core/budget.ts +25 -25
  198. package/vendor/minicore/src/core/compact.ts +75 -75
  199. package/vendor/minicore/src/core/errors.ts +59 -59
  200. package/vendor/minicore/src/core/events.ts +73 -73
  201. package/vendor/minicore/src/core/executor.ts +139 -139
  202. package/vendor/minicore/src/core/history.ts +31 -31
  203. package/vendor/minicore/src/core/index.ts +41 -41
  204. package/vendor/minicore/src/core/loop.ts +355 -355
  205. package/vendor/minicore/src/core/permission.ts +22 -22
  206. package/vendor/minicore/src/core/provider.ts +39 -39
  207. package/vendor/minicore/src/core/recovery.ts +35 -35
  208. package/vendor/minicore/src/core/session.ts +327 -327
  209. package/vendor/minicore/src/core/snapshot.ts +146 -146
  210. package/vendor/minicore/src/core/tokens.ts +107 -107
  211. package/vendor/minicore/src/core/tool.ts +115 -115
  212. package/vendor/minicore/src/core/types.ts +50 -50
  213. package/vendor/minicore/src/providers/openai-compat.ts +417 -417
  214. package/AGENTS.md +0 -45
  215. package/PLAN.md +0 -491
  216. package/docs/ARCHITECTURE.html +0 -1248
  217. package/docs/CONTROL-PLANE-MAP.md +0 -139
  218. package/docs/HARNESS.md +0 -150
  219. package/docs/SUMMARY.md +0 -52
  220. package/docs/UI_RENDER_PIPELINE.md +0 -165
  221. package/docs/USAGE.md +0 -11
@@ -1,146 +1,146 @@
1
- // Defensive snapshots for crossing host/provider/observer boundaries. The
2
- // kernel keeps mutable buffers internally, but external adapters, tools,
3
- // executors, and event listeners must not receive references that can corrupt
4
- // runtime state or alter in-flight actions.
5
-
6
- import type { Execution, SessionState, Step, TurnResult } from "./session.ts";
7
- import type { ToolSchema } from "./tool.ts";
8
- import type { AssistantMessage, Content, ContentPart, Message, ToolCall, ToolResult } from "./types.ts";
9
-
10
- export function snapshotMessages(messages: readonly Message[]): Message[] {
11
- return messages.map(snapshotMessage);
12
- }
13
-
14
- function snapshotMessage(message: Message): Message {
15
- switch (message.role) {
16
- case "user":
17
- return { role: "user", content: snapshotContent(message.content) };
18
- case "assistant":
19
- return snapshotAssistant(message);
20
- case "tool":
21
- return snapshotToolResult(message);
22
- }
23
- }
24
-
25
- export function snapshotToolCall(call: ToolCall): ToolCall {
26
- return {
27
- id: call.id,
28
- name: call.name,
29
- args: snapshotValue(call.args),
30
- };
31
- }
32
-
33
- export function snapshotToolResult(result: ToolResult): ToolResult {
34
- const out: ToolResult = {
35
- role: "tool",
36
- toolCallId: result.toolCallId,
37
- name: result.name,
38
- content: snapshotValue(result.content),
39
- };
40
- return result.isError === undefined ? out : { ...out, isError: result.isError };
41
- }
42
-
43
- export function snapshotToolSchemas(tools: readonly ToolSchema[]): ToolSchema[] {
44
- return tools.map((toolSchema) => ({
45
- name: toolSchema.name,
46
- description: toolSchema.description,
47
- parameters: snapshotValue(toolSchema.parameters),
48
- }));
49
- }
50
-
51
- export function snapshotState(state: Readonly<SessionState>): SessionState {
52
- return {
53
- history: snapshotMessages(state.history),
54
- turnCount: state.turnCount,
55
- stepCount: state.stepCount,
56
- model: state.model,
57
- };
58
- }
59
-
60
- export function snapshotExecution(execution: Execution): Execution {
61
- return {
62
- call: snapshotToolCall(execution.call),
63
- result: snapshotToolResult(execution.result),
64
- };
65
- }
66
-
67
- export function snapshotStep(step: Step): Step {
68
- return {
69
- index: step.index,
70
- toolCalls: step.toolCalls.map(snapshotToolCall),
71
- results: step.results.map(snapshotToolResult),
72
- };
73
- }
74
-
75
- export function snapshotTurnResult(result: TurnResult): TurnResult {
76
- return {
77
- finalText: result.finalText,
78
- steps: result.steps.map(snapshotStep),
79
- usage: { turns: result.usage.turns, steps: result.usage.steps },
80
- };
81
- }
82
-
83
- function snapshotAssistant(message: AssistantMessage): AssistantMessage {
84
- const base: AssistantMessage = {
85
- role: "assistant",
86
- content: snapshotContent(message.content),
87
- };
88
- const withReasoning = message.reasoning === undefined ? base : { ...base, reasoning: message.reasoning };
89
- return message.toolCalls === undefined
90
- ? withReasoning
91
- : { ...withReasoning, toolCalls: message.toolCalls.map(snapshotToolCall) };
92
- }
93
-
94
- function snapshotContent(content: Content): Content {
95
- if (typeof content === "string") return content;
96
- return content.map(snapshotContentPart);
97
- }
98
-
99
- function snapshotContentPart(part: ContentPart): ContentPart {
100
- switch (part.type) {
101
- case "text":
102
- return { type: "text", text: part.text };
103
- case "image":
104
- return { type: "image", mime: part.mime, data: part.data.slice() };
105
- }
106
- }
107
-
108
- function snapshotValue<T>(value: T): T {
109
- if (value instanceof Uint8Array) return value.slice() as T;
110
- try {
111
- return structuredClone(value);
112
- } catch {
113
- return clonePlainValue(value) as T;
114
- }
115
- }
116
-
117
- function clonePlainValue(value: unknown, seen = new WeakMap<object, unknown>()): unknown {
118
- if (value === null || (typeof value !== "object" && typeof value !== "function")) return value;
119
- if (value instanceof Uint8Array) return value.slice();
120
- if (typeof value === "function") return value;
121
- const existing = seen.get(value);
122
- if (existing) return existing;
123
- if (Array.isArray(value)) {
124
- const out: unknown[] = [];
125
- seen.set(value, out);
126
- for (const item of value) out.push(clonePlainValue(item, seen));
127
- return out;
128
- }
129
- const proto = Object.getPrototypeOf(value);
130
- // Known limitation (documented): non-plain objects (Date, RegExp, class
131
- // instances, …) are returned AS-IS — the same reference crosses the
132
- // boundary. Plain objects/arrays/binary are deep-copied; exotic types are
133
- // kept so cloning never corrupts them, at the cost of shared identity.
134
- if (proto !== Object.prototype && proto !== null) return value;
135
- const out = Object.create(proto) as Record<string, unknown>;
136
- seen.set(value, out);
137
- for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
138
- Object.defineProperty(out, key, {
139
- value: clonePlainValue(child, seen),
140
- enumerable: true,
141
- writable: true,
142
- configurable: true,
143
- });
144
- }
145
- return out;
146
- }
1
+ // Defensive snapshots for crossing host/provider/observer boundaries. The
2
+ // kernel keeps mutable buffers internally, but external adapters, tools,
3
+ // executors, and event listeners must not receive references that can corrupt
4
+ // runtime state or alter in-flight actions.
5
+
6
+ import type { Execution, SessionState, Step, TurnResult } from "./session.ts";
7
+ import type { ToolSchema } from "./tool.ts";
8
+ import type { AssistantMessage, Content, ContentPart, Message, ToolCall, ToolResult } from "./types.ts";
9
+
10
+ export function snapshotMessages(messages: readonly Message[]): Message[] {
11
+ return messages.map(snapshotMessage);
12
+ }
13
+
14
+ function snapshotMessage(message: Message): Message {
15
+ switch (message.role) {
16
+ case "user":
17
+ return { role: "user", content: snapshotContent(message.content) };
18
+ case "assistant":
19
+ return snapshotAssistant(message);
20
+ case "tool":
21
+ return snapshotToolResult(message);
22
+ }
23
+ }
24
+
25
+ export function snapshotToolCall(call: ToolCall): ToolCall {
26
+ return {
27
+ id: call.id,
28
+ name: call.name,
29
+ args: snapshotValue(call.args),
30
+ };
31
+ }
32
+
33
+ export function snapshotToolResult(result: ToolResult): ToolResult {
34
+ const out: ToolResult = {
35
+ role: "tool",
36
+ toolCallId: result.toolCallId,
37
+ name: result.name,
38
+ content: snapshotValue(result.content),
39
+ };
40
+ return result.isError === undefined ? out : { ...out, isError: result.isError };
41
+ }
42
+
43
+ export function snapshotToolSchemas(tools: readonly ToolSchema[]): ToolSchema[] {
44
+ return tools.map((toolSchema) => ({
45
+ name: toolSchema.name,
46
+ description: toolSchema.description,
47
+ parameters: snapshotValue(toolSchema.parameters),
48
+ }));
49
+ }
50
+
51
+ export function snapshotState(state: Readonly<SessionState>): SessionState {
52
+ return {
53
+ history: snapshotMessages(state.history),
54
+ turnCount: state.turnCount,
55
+ stepCount: state.stepCount,
56
+ model: state.model,
57
+ };
58
+ }
59
+
60
+ export function snapshotExecution(execution: Execution): Execution {
61
+ return {
62
+ call: snapshotToolCall(execution.call),
63
+ result: snapshotToolResult(execution.result),
64
+ };
65
+ }
66
+
67
+ export function snapshotStep(step: Step): Step {
68
+ return {
69
+ index: step.index,
70
+ toolCalls: step.toolCalls.map(snapshotToolCall),
71
+ results: step.results.map(snapshotToolResult),
72
+ };
73
+ }
74
+
75
+ export function snapshotTurnResult(result: TurnResult): TurnResult {
76
+ return {
77
+ finalText: result.finalText,
78
+ steps: result.steps.map(snapshotStep),
79
+ usage: { turns: result.usage.turns, steps: result.usage.steps },
80
+ };
81
+ }
82
+
83
+ function snapshotAssistant(message: AssistantMessage): AssistantMessage {
84
+ const base: AssistantMessage = {
85
+ role: "assistant",
86
+ content: snapshotContent(message.content),
87
+ };
88
+ const withReasoning = message.reasoning === undefined ? base : { ...base, reasoning: message.reasoning };
89
+ return message.toolCalls === undefined
90
+ ? withReasoning
91
+ : { ...withReasoning, toolCalls: message.toolCalls.map(snapshotToolCall) };
92
+ }
93
+
94
+ function snapshotContent(content: Content): Content {
95
+ if (typeof content === "string") return content;
96
+ return content.map(snapshotContentPart);
97
+ }
98
+
99
+ function snapshotContentPart(part: ContentPart): ContentPart {
100
+ switch (part.type) {
101
+ case "text":
102
+ return { type: "text", text: part.text };
103
+ case "image":
104
+ return { type: "image", mime: part.mime, data: part.data.slice() };
105
+ }
106
+ }
107
+
108
+ function snapshotValue<T>(value: T): T {
109
+ if (value instanceof Uint8Array) return value.slice() as T;
110
+ try {
111
+ return structuredClone(value);
112
+ } catch {
113
+ return clonePlainValue(value) as T;
114
+ }
115
+ }
116
+
117
+ function clonePlainValue(value: unknown, seen = new WeakMap<object, unknown>()): unknown {
118
+ if (value === null || (typeof value !== "object" && typeof value !== "function")) return value;
119
+ if (value instanceof Uint8Array) return value.slice();
120
+ if (typeof value === "function") return value;
121
+ const existing = seen.get(value);
122
+ if (existing) return existing;
123
+ if (Array.isArray(value)) {
124
+ const out: unknown[] = [];
125
+ seen.set(value, out);
126
+ for (const item of value) out.push(clonePlainValue(item, seen));
127
+ return out;
128
+ }
129
+ const proto = Object.getPrototypeOf(value);
130
+ // Known limitation (documented): non-plain objects (Date, RegExp, class
131
+ // instances, …) are returned AS-IS — the same reference crosses the
132
+ // boundary. Plain objects/arrays/binary are deep-copied; exotic types are
133
+ // kept so cloning never corrupts them, at the cost of shared identity.
134
+ if (proto !== Object.prototype && proto !== null) return value;
135
+ const out = Object.create(proto) as Record<string, unknown>;
136
+ seen.set(value, out);
137
+ for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
138
+ Object.defineProperty(out, key, {
139
+ value: clonePlainValue(child, seen),
140
+ enumerable: true,
141
+ writable: true,
142
+ configurable: true,
143
+ });
144
+ }
145
+ return out;
146
+ }
@@ -1,108 +1,108 @@
1
- // Token estimation: an injectable policy. The kernel's default is a plain
2
- // chars/4 heuristic — swap it per model without touching the kernel.
3
- // Truncation in executor.ts must stay in the same unit as this heuristic, so
4
- // the chars-per-token factor lives here as the single source of truth.
5
-
6
- import type { ToolSchema } from "./tool.ts";
7
- import type { Content, Message } from "./types.ts";
8
-
9
- export const DEFAULT_CHARS_PER_TOKEN = 4;
10
-
11
- export type TokenEstimator = (text: string) => number;
12
-
13
- export const defaultTokenEstimator: TokenEstimator = (text) => Math.ceil(text.length / DEFAULT_CHARS_PER_TOKEN);
14
-
15
- export function contentToText(content: Content): string {
16
- if (typeof content === "string") return content;
17
- return content.map((part) => (part.type === "text" ? part.text : `[image:${part.mime}]`)).join("\n");
18
- }
19
-
20
- /**
21
- * Token estimate for inline image bytes. The text placeholder above would
22
- * price a 100KB image at ~15 tokens, hiding it from budget pressure until
23
- * the context genuinely overflows — so image parts are priced from their
24
- * base64 wire size instead.
25
- */
26
- export function estimateImageTokens(byteLength: number): number {
27
- return Math.ceil(Math.ceil((byteLength * 4) / 3) / DEFAULT_CHARS_PER_TOKEN);
28
- }
29
-
30
- function estimateContent(content: Content, est: TokenEstimator): number {
31
- if (typeof content === "string") return est(content);
32
- let total = 0;
33
- for (const part of content) {
34
- if (part.type === "text") total += est(part.text);
35
- else total += estimateImageTokens(part.data.byteLength);
36
- }
37
- return total;
38
- }
39
-
40
- /**
41
- * JSON.stringify that never throws: cyclic values (possible only from hostile
42
- * or buggy input) fall back to a plain string instead of leaking a raw
43
- * TypeError through the kernel's deterministic error taxonomy.
44
- */
45
- export function safeStringify(value: unknown): string {
46
- try {
47
- return JSON.stringify(value) ?? String(value);
48
- } catch {
49
- return String(value);
50
- }
51
- }
52
-
53
- export function estimateMessage(message: Message, est: TokenEstimator): number {
54
- switch (message.role) {
55
- case "user":
56
- return estimateContent(message.content, est);
57
- case "assistant":
58
- return estimateContent(message.content, est) + est(safeStringify(message.toolCalls ?? [])) + est(message.reasoning ?? "");
59
- case "tool": {
60
- const c = message.content;
61
- // Binary tool results (e.g. images): JSON.stringify of a Uint8Array
62
- // explodes into a {"0":..} map, faking pressure and triggering
63
- // premature compaction. Price it as image bytes instead.
64
- if (c instanceof Uint8Array) return estimateImageTokens(c.byteLength);
65
- return est(typeof c === "string" ? c : safeStringify(c ?? null));
66
- }
67
- default:
68
- return 0;
69
- }
70
- }
71
-
72
- export function estimateMessages(messages: readonly Message[], est: TokenEstimator): number {
73
- let total = 0;
74
- for (const message of messages) total += estimateMessage(message, est);
75
- return total;
76
- }
77
-
78
- /** The fixed per-request cost of the tool schemas sent with every call. */
79
- export function estimateTools(tools: readonly ToolSchema[], est: TokenEstimator): number {
80
- let total = 0;
81
- for (const tool of tools) total += est(tool.name) + est(tool.description) + est(safeStringify(tool.parameters));
82
- return total;
83
- }
84
-
85
- /** The fixed per-request cost of the system prompt. */
86
- export function estimateSystem(system: string | undefined, est: TokenEstimator): number {
87
- return system ? est(system) : 0;
88
- }
89
-
90
- /**
91
- * Single source for the current context size: messages + system + tools —
92
- * everything sent per request. Shared by the loop (pressure evaluation)
93
- * and the Session getter (observability) so no duplicate estimator can
94
- * drift. Pure over its arguments; takes the store shape instead of
95
- * SessionInternal to avoid a session<->loop circular import.
96
- */
97
- export function estimateSessionContext(
98
- store: { messages: readonly Message[] },
99
- system: string | undefined,
100
- tools: readonly ToolSchema[],
101
- est: TokenEstimator,
102
- ): number {
103
- return (
104
- estimateMessages(store.messages, est) +
105
- estimateSystem(system, est) +
106
- estimateTools(tools, est)
107
- );
1
+ // Token estimation: an injectable policy. The kernel's default is a plain
2
+ // chars/4 heuristic — swap it per model without touching the kernel.
3
+ // Truncation in executor.ts must stay in the same unit as this heuristic, so
4
+ // the chars-per-token factor lives here as the single source of truth.
5
+
6
+ import type { ToolSchema } from "./tool.ts";
7
+ import type { Content, Message } from "./types.ts";
8
+
9
+ export const DEFAULT_CHARS_PER_TOKEN = 4;
10
+
11
+ export type TokenEstimator = (text: string) => number;
12
+
13
+ export const defaultTokenEstimator: TokenEstimator = (text) => Math.ceil(text.length / DEFAULT_CHARS_PER_TOKEN);
14
+
15
+ export function contentToText(content: Content): string {
16
+ if (typeof content === "string") return content;
17
+ return content.map((part) => (part.type === "text" ? part.text : `[image:${part.mime}]`)).join("\n");
18
+ }
19
+
20
+ /**
21
+ * Token estimate for inline image bytes. The text placeholder above would
22
+ * price a 100KB image at ~15 tokens, hiding it from budget pressure until
23
+ * the context genuinely overflows — so image parts are priced from their
24
+ * base64 wire size instead.
25
+ */
26
+ export function estimateImageTokens(byteLength: number): number {
27
+ return Math.ceil(Math.ceil((byteLength * 4) / 3) / DEFAULT_CHARS_PER_TOKEN);
28
+ }
29
+
30
+ function estimateContent(content: Content, est: TokenEstimator): number {
31
+ if (typeof content === "string") return est(content);
32
+ let total = 0;
33
+ for (const part of content) {
34
+ if (part.type === "text") total += est(part.text);
35
+ else total += estimateImageTokens(part.data.byteLength);
36
+ }
37
+ return total;
38
+ }
39
+
40
+ /**
41
+ * JSON.stringify that never throws: cyclic values (possible only from hostile
42
+ * or buggy input) fall back to a plain string instead of leaking a raw
43
+ * TypeError through the kernel's deterministic error taxonomy.
44
+ */
45
+ export function safeStringify(value: unknown): string {
46
+ try {
47
+ return JSON.stringify(value) ?? String(value);
48
+ } catch {
49
+ return String(value);
50
+ }
51
+ }
52
+
53
+ export function estimateMessage(message: Message, est: TokenEstimator): number {
54
+ switch (message.role) {
55
+ case "user":
56
+ return estimateContent(message.content, est);
57
+ case "assistant":
58
+ return estimateContent(message.content, est) + est(safeStringify(message.toolCalls ?? [])) + est(message.reasoning ?? "");
59
+ case "tool": {
60
+ const c = message.content;
61
+ // Binary tool results (e.g. images): JSON.stringify of a Uint8Array
62
+ // explodes into a {"0":..} map, faking pressure and triggering
63
+ // premature compaction. Price it as image bytes instead.
64
+ if (c instanceof Uint8Array) return estimateImageTokens(c.byteLength);
65
+ return est(typeof c === "string" ? c : safeStringify(c ?? null));
66
+ }
67
+ default:
68
+ return 0;
69
+ }
70
+ }
71
+
72
+ export function estimateMessages(messages: readonly Message[], est: TokenEstimator): number {
73
+ let total = 0;
74
+ for (const message of messages) total += estimateMessage(message, est);
75
+ return total;
76
+ }
77
+
78
+ /** The fixed per-request cost of the tool schemas sent with every call. */
79
+ export function estimateTools(tools: readonly ToolSchema[], est: TokenEstimator): number {
80
+ let total = 0;
81
+ for (const tool of tools) total += est(tool.name) + est(tool.description) + est(safeStringify(tool.parameters));
82
+ return total;
83
+ }
84
+
85
+ /** The fixed per-request cost of the system prompt. */
86
+ export function estimateSystem(system: string | undefined, est: TokenEstimator): number {
87
+ return system ? est(system) : 0;
88
+ }
89
+
90
+ /**
91
+ * Single source for the current context size: messages + system + tools —
92
+ * everything sent per request. Shared by the loop (pressure evaluation)
93
+ * and the Session getter (observability) so no duplicate estimator can
94
+ * drift. Pure over its arguments; takes the store shape instead of
95
+ * SessionInternal to avoid a session<->loop circular import.
96
+ */
97
+ export function estimateSessionContext(
98
+ store: { messages: readonly Message[] },
99
+ system: string | undefined,
100
+ tools: readonly ToolSchema[],
101
+ est: TokenEstimator,
102
+ ): number {
103
+ return (
104
+ estimateMessages(store.messages, est) +
105
+ estimateSystem(system, est) +
106
+ estimateTools(tools, est)
107
+ );
108
108
  }