minicode-ai 0.13.0 → 0.14.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 (83) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +21 -21
  3. package/README.md +4 -0
  4. package/cli/args.ts +50 -2
  5. package/cli/commands/acp.ts +18 -3
  6. package/cli/commands/daemon.ts +114 -19
  7. package/cli/commands/exec.ts +95 -7
  8. package/cli/commands/mcp.ts +66 -5
  9. package/cli/commands/memory.ts +46 -14
  10. package/cli/commands.ts +5 -0
  11. package/cli/index.ts +30 -5
  12. package/cli/minicode.js +6 -0
  13. package/cli/setup.ts +365 -24
  14. package/cli/tui.ts +72 -27
  15. package/docs/TERMINAL_CONTRACT.md +91 -24
  16. package/docs/agents.md +2 -2
  17. package/docs/cli.md +1 -0
  18. package/docs/environment.md +1 -0
  19. package/docs/memory-sessions.md +5 -0
  20. package/package.json +3 -2
  21. package/src/app/session.ts +153 -35
  22. package/src/app/tool-layer.ts +67 -61
  23. package/src/daemon/approvals.ts +25 -1
  24. package/src/daemon/client.ts +51 -1
  25. package/src/daemon/control.ts +8 -0
  26. package/src/daemon/protocol.ts +47 -1
  27. package/src/daemon/server.ts +45 -9
  28. package/src/daemon/subscription.ts +25 -1
  29. package/src/daemon/telemetry.ts +4 -0
  30. package/src/hooks/run.ts +5 -1
  31. package/src/mcp/client.ts +349 -90
  32. package/src/mcp/http-transport.ts +7 -0
  33. package/src/mcp/transport.ts +5 -0
  34. package/src/memory/files.ts +69 -3
  35. package/src/memory/vector.ts +556 -160
  36. package/src/policy/approval-binding.ts +199 -0
  37. package/src/policy/context.ts +20 -1
  38. package/src/policy/executor.ts +44 -5
  39. package/src/policy/permission.ts +243 -26
  40. package/src/policy/tool-contract.ts +77 -0
  41. package/src/policy/usage.ts +3 -1
  42. package/src/policy/work-mode.ts +49 -1
  43. package/src/presentation/adapter.ts +157 -7
  44. package/src/presentation/events.ts +173 -1
  45. package/src/presentation/model.ts +37 -0
  46. package/src/presentation/projection.ts +107 -18
  47. package/src/presentation/reducer.ts +134 -10
  48. package/src/sandbox/os.ts +18 -1
  49. package/src/session/persistence.ts +153 -11
  50. package/src/task/store.ts +43 -3
  51. package/src/tools/memory.ts +70 -10
  52. package/src/tools/task.ts +7 -1
  53. package/src/tools/todo.ts +14 -4
  54. package/src/ui/approval/prompt.ts +52 -7
  55. package/src/ui/assistant/simple.ts +160 -57
  56. package/src/ui/contract.ts +46 -0
  57. package/src/ui/footer.ts +14 -5
  58. package/src/ui/i18n/en.ts +9 -0
  59. package/src/ui/i18n/id.ts +9 -0
  60. package/src/ui/render/collapse.ts +24 -52
  61. package/src/ui/render/detail.ts +14 -9
  62. package/src/ui/render/errors.ts +8 -0
  63. package/src/ui/render/reasoning.ts +13 -8
  64. package/src/ui/session-state.ts +243 -0
  65. package/src/ui/tui/app.ts +7 -3
  66. package/src/ui/tui/transcript.ts +271 -30
  67. package/vendor/minicore/src/core/budget.ts +25 -25
  68. package/vendor/minicore/src/core/compact.ts +75 -75
  69. package/vendor/minicore/src/core/errors.ts +59 -59
  70. package/vendor/minicore/src/core/events.ts +73 -73
  71. package/vendor/minicore/src/core/executor.ts +139 -139
  72. package/vendor/minicore/src/core/history.ts +31 -31
  73. package/vendor/minicore/src/core/index.ts +41 -41
  74. package/vendor/minicore/src/core/loop.ts +355 -355
  75. package/vendor/minicore/src/core/permission.ts +22 -22
  76. package/vendor/minicore/src/core/provider.ts +39 -39
  77. package/vendor/minicore/src/core/recovery.ts +35 -35
  78. package/vendor/minicore/src/core/session.ts +327 -327
  79. package/vendor/minicore/src/core/snapshot.ts +146 -146
  80. package/vendor/minicore/src/core/tokens.ts +107 -107
  81. package/vendor/minicore/src/core/tool.ts +115 -115
  82. package/vendor/minicore/src/core/types.ts +50 -50
  83. package/vendor/minicore/src/providers/openai-compat.ts +417 -417
@@ -1,327 +1,327 @@
1
- // Session: configuration binding + lifecycle records. The loop lives in
2
- // loop.ts; this module only composes the parts and exposes a minimal API.
3
-
4
- import type { BudgetPolicy } from "./budget.ts";
5
- import { defaultBudgetPolicy } from "./budget.ts";
6
- import type { CompactionStrategy } from "./compact.ts";
7
- import { mechanicalCompaction } from "./compact.ts";
8
- import { AgentError, abortError } from "./errors.ts";
9
- import type { AgentEvent, EventBus } from "./events.ts";
10
- import { createEventBus } from "./events.ts";
11
- import type { ToolExecutor } from "./executor.ts";
12
- import { sequentialExecutor } from "./executor.ts";
13
- import { ContextStore } from "./history.ts";
14
- import type { PermissionHandler } from "./permission.ts";
15
- import type { ModelProvider } from "./provider.ts";
16
- import type { RecoveryPolicy } from "./recovery.ts";
17
- import { defaultRecoveryPolicy } from "./recovery.ts";
18
- import { executeTurn } from "./loop.ts";
19
- import { snapshotState, snapshotTurnResult } from "./snapshot.ts";
20
- import type { Tool, ToolRegistry } from "./tool.ts";
21
- import { createToolRegistry } from "./tool.ts";
22
- import type { TokenEstimator } from "./tokens.ts";
23
- import { defaultTokenEstimator, estimateSessionContext } from "./tokens.ts";
24
- import type { Message, ToolCall, ToolResult } from "./types.ts";
25
-
26
- export const DEFAULT_MAX_STEPS = 50;
27
- export const DEFAULT_CONTEXT_WINDOW_TOKENS = 128_000;
28
- export const DEFAULT_TOOL_RESULT_MAX_TOKENS = 4_096;
29
- export const DEFAULT_KEEP_RECENT_TURNS = 3;
30
-
31
- export const DEFAULT_TIMEOUT_MS = 600_000;
32
-
33
- export interface SessionConfig {
34
- provider: ModelProvider;
35
- permissions: PermissionHandler;
36
- tools?: readonly Tool[];
37
- system?: string;
38
- model?: string;
39
- cwd?: string;
40
- /**
41
- * Session permission mode, forwarded to each turn's ToolContext so tools
42
- * can adapt their behavior. Plain string or live getter — prefer the
43
- * getter when the mode can change at runtime. Optional; absent preserves
44
- * the legacy behavior (ctx.permissionMode undefined).
45
- */
46
- permissionMode?: string | (() => string);
47
- /**
48
- * Seed history untuk sesi baru (mis. resume dari storage). Messages akan
49
- * di-append ke ContextStore saat createSession, jadi `session.state.history`
50
- * langsung memuatnya dan turn berikutnya meneruskan konteks penuh.
51
- */
52
- initialMessages?: readonly Message[];
53
- turnCount?: number;
54
- stepCount?: number;
55
- executor?: ToolExecutor;
56
- budget?: BudgetPolicy;
57
- estimator?: TokenEstimator;
58
- compaction?: CompactionStrategy;
59
- recovery?: RecoveryPolicy;
60
- maxSteps?: number;
61
- contextWindowTokens?: number;
62
- toolResultMaxTokens?: number;
63
- keepRecentTurns?: number;
64
- /**
65
- * Hard deadline for a single run() call, in milliseconds. When exceeded, the
66
- * turn is aborted and run() rejects with AgentError("timeout") — even if the
67
- * in-flight provider/tool ignores the abort signal. Defaults to
68
- * DEFAULT_TIMEOUT_MS (10 minutes); set to Infinity to disable.
69
- */
70
- timeoutMs?: number;
71
- /**
72
- * Reports errors thrown by event listeners. Observer code must never be able
73
- * to break a turn (lifecycle/executor events) nor trigger a spurious retry
74
- * (provider streaming events): emit catches every handler error, reports it
75
- * here, and continues. Defaults to console.error.
76
- */
77
- onHandlerError?: (error: unknown, event: AgentEvent) => void;
78
- }
79
-
80
- export interface SessionState {
81
- readonly history: readonly Message[];
82
- turnCount: number;
83
- stepCount: number;
84
- readonly model?: string;
85
- }
86
-
87
- export interface Execution {
88
- readonly call: ToolCall;
89
- readonly result: ToolResult;
90
- }
91
-
92
- export interface Step {
93
- readonly index: number;
94
- readonly toolCalls: readonly ToolCall[];
95
- readonly results: readonly ToolResult[];
96
- }
97
-
98
- export interface TurnResult {
99
- readonly steps: readonly Step[];
100
- readonly finalText?: string;
101
- readonly usage: { readonly turns: number; readonly steps: number };
102
- }
103
-
104
- export interface Session {
105
- /**
106
- * Point-in-time defensive snapshot of the committed session state.
107
- *
108
- * Each access deep-copies the committed history and counters, so a
109
- * same-process caller that casts away the read-only types and mutates the
110
- * result can never corrupt the kernel's state (the committed history that
111
- * feeds the next turn) — the mutation touches only the caller's copy.
112
- *
113
- * Semantics: the returned value is a snapshot, not a live view. A reference
114
- * held across a run stays frozen at the moment it was read; re-access
115
- * `session.state` for fresh data. Committed state changes only when a turn
116
- * completes successfully, and for change notification prefer the event bus
117
- * (`turn:completed`, `step:completed`). Cost is O(history) per access, so
118
- * read once per turn rather than polling.
119
- */
120
- readonly state: Readonly<SessionState>;
121
- readonly events: EventBus;
122
- /**
123
- * Current context size from the same source of truth as the loop's
124
- * pressure evaluation (messages + system + tools under the session
125
- * estimator). One number for drivers and UI — no duplicate estimator.
126
- * O(history) per access (snapshot pattern); recomputed over the
127
- * committed store on every access.
128
- */
129
- readonly contextTokens: number;
130
- run(input: string, opts?: { signal?: AbortSignal; model?: string }): Promise<TurnResult>;
131
- abort(): void;
132
- }
133
-
134
- /** Internal handle consumed by loop.ts. Not part of the public surface. */
135
- export interface SessionInternal {
136
- readonly provider: ModelProvider;
137
- readonly permissions: PermissionHandler;
138
- readonly registry: ToolRegistry;
139
- readonly executor: ToolExecutor;
140
- readonly system?: string;
141
- readonly model?: string;
142
- readonly cwd?: string;
143
- readonly permissionMode?: string | (() => string);
144
- readonly budget: BudgetPolicy;
145
- readonly estimator: TokenEstimator;
146
- readonly compaction: CompactionStrategy;
147
- readonly recovery: RecoveryPolicy;
148
- readonly maxSteps: number;
149
- readonly contextWindowTokens: number;
150
- readonly toolResultMaxTokens: number;
151
- readonly keepRecentTurns: number;
152
- readonly timeoutMs: number;
153
- readonly store: ContextStore;
154
- readonly events: EventBus;
155
- readonly state: SessionState;
156
- }
157
-
158
- interface SessionImpl extends SessionInternal {
159
- sessionAbort: AbortController;
160
- running: boolean;
161
- }
162
-
163
- export function createSession(config: SessionConfig): Session {
164
- const store = new ContextStore();
165
- if (config.initialMessages?.length) store.appendAll(config.initialMessages);
166
- const events = createEventBus({ onHandlerError: config.onHandlerError });
167
- const sessionAbort = new AbortController();
168
- const state: SessionState = {
169
- history: store.messages,
170
- turnCount: config.turnCount ?? 0,
171
- stepCount: config.stepCount ?? 0,
172
- model: config.model,
173
- };
174
-
175
- const impl: SessionImpl = {
176
- provider: config.provider,
177
- permissions: config.permissions,
178
- registry: createToolRegistry(config.tools ?? []),
179
- executor: config.executor ?? sequentialExecutor(),
180
- system: config.system,
181
- model: config.model,
182
- cwd: config.cwd,
183
- permissionMode: config.permissionMode,
184
- budget: config.budget ?? defaultBudgetPolicy,
185
- estimator: config.estimator ?? defaultTokenEstimator,
186
- compaction: config.compaction ?? mechanicalCompaction,
187
- recovery: config.recovery ?? defaultRecoveryPolicy,
188
- maxSteps: config.maxSteps ?? DEFAULT_MAX_STEPS,
189
- contextWindowTokens: config.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS,
190
- toolResultMaxTokens: config.toolResultMaxTokens ?? DEFAULT_TOOL_RESULT_MAX_TOKENS,
191
- keepRecentTurns: config.keepRecentTurns ?? DEFAULT_KEEP_RECENT_TURNS,
192
- timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
193
- store,
194
- events,
195
- state,
196
- sessionAbort,
197
- running: false,
198
- };
199
-
200
- return {
201
- // Public state crosses a host boundary, so it is a defensive snapshot per
202
- // access (same policy as provider requests, tool ctx.state, and event
203
- // payloads). The kernel keeps the raw object internally via `impl.state`.
204
- get state() {
205
- return snapshotState(state);
206
- },
207
- get events() {
208
- return events;
209
- },
210
- // Same source of truth as the loop — estimateSessionContext in
211
- // tokens.ts — never a duplicate estimator.
212
- get contextTokens() {
213
- return estimateSessionContext(store, config.system, impl.registry.list(), impl.estimator);
214
- },
215
- async run(input, opts) {
216
- if (impl.running) throw new AgentError("busy", "session is already running");
217
- impl.running = true;
218
- const timeout = createTimeout(impl.timeoutMs);
219
- const joined = joinSignals(impl.sessionAbort.signal, opts?.signal, timeout.signal);
220
- const turnStore = new ContextStore();
221
- turnStore.appendAll(store.messages);
222
- const turnState: SessionState = {
223
- history: turnStore.messages,
224
- turnCount: state.turnCount,
225
- stepCount: state.stepCount,
226
- model: opts?.model ?? config.model,
227
- };
228
- const turnImpl: SessionInternal = {
229
- ...impl,
230
- store: turnStore,
231
- state: turnState,
232
- };
233
- try {
234
- const turn = executeTurn(turnImpl, input, joined.signal, opts?.model);
235
- // The race guarantees run() rejects as soon as the joined signal
236
- // aborts (user abort, session.abort, or timeout), even if the
237
- // in-flight provider/tool ignores the signal. Any late work mutates
238
- // only turnStore and is discarded.
239
- const result = await withAbort(turn, joined.signal);
240
- // A run is transactional with respect to model context: failed,
241
- // aborted, or timed-out turns are discarded instead of leaving orphaned
242
- // user messages or assistant tool_calls without matching tool results.
243
- // Non-cooperative providers/tools may still settle after withTimeout
244
- // rejects, but they mutate only this private turnStore.
245
- store.replace(0, store.messages.length, turnStore.messages);
246
- state.turnCount = turnState.turnCount;
247
- state.stepCount = turnState.stepCount;
248
- events.emit({ type: "turn:completed", result: snapshotTurnResult(result) });
249
- return result;
250
- } finally {
251
- timeout.cancel();
252
- joined.cleanup();
253
- impl.running = false;
254
- if (impl.sessionAbort.signal.aborted) impl.sessionAbort = new AbortController();
255
- }
256
- },
257
- abort() {
258
- if (impl.running) impl.sessionAbort.abort(new AgentError("aborted", "turn aborted"));
259
- },
260
- };
261
- }
262
-
263
- function joinSignals(...signals: Array<AbortSignal | undefined>): { signal: AbortSignal; cleanup(): void } {
264
- const active = signals.filter((s): s is AbortSignal => s !== undefined);
265
- if (active.length <= 1) {
266
- return active[0] ? { signal: active[0], cleanup: noop } : { signal: new AbortController().signal, cleanup: noop };
267
- }
268
- const alreadyAborted = active.find((s) => s.aborted);
269
- if (alreadyAborted) return { signal: alreadyAborted, cleanup: noop };
270
- const controller = new AbortController();
271
- const handlers: Array<[AbortSignal, () => void]> = active.map((s) => {
272
- const onAbort = () => controller.abort(s.reason);
273
- s.addEventListener("abort", onAbort, { once: true });
274
- return [s, onAbort];
275
- });
276
- return {
277
- signal: controller.signal,
278
- cleanup() {
279
- for (const [signal, onAbort] of handlers) signal.removeEventListener("abort", onAbort);
280
- },
281
- };
282
- }
283
-
284
- function noop(): void {}
285
-
286
- interface Timeout {
287
- readonly signal: AbortSignal;
288
- cancel(): void;
289
- }
290
-
291
- function createTimeout(ms: number): Timeout {
292
- const controller = new AbortController();
293
- const error = new AgentError("timeout", `turn exceeded ${ms}ms`);
294
- // setTimeout clamps a non-finite delay to 1ms in Node/Bun, so Infinity would
295
- // abort the turn almost immediately instead of disabling the deadline.
296
- const timer = Number.isFinite(ms) ? setTimeout(() => controller.abort(error), ms) : undefined;
297
- return {
298
- signal: controller.signal,
299
- cancel: () => {
300
- if (timer !== undefined) clearTimeout(timer);
301
- },
302
- };
303
- }
304
-
305
- function withAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
306
- if (signal.aborted) return Promise.reject(abortError(signal));
307
- return new Promise((resolve, reject) => {
308
- const onAbort = () => {
309
- cleanup();
310
- reject(abortError(signal));
311
- };
312
- signal.addEventListener("abort", onAbort, { once: true });
313
- promise.then(
314
- (value) => {
315
- cleanup();
316
- resolve(value);
317
- },
318
- (cause) => {
319
- cleanup();
320
- reject(cause);
321
- },
322
- );
323
- function cleanup() {
324
- signal.removeEventListener("abort", onAbort);
325
- }
326
- });
327
- }
1
+ // Session: configuration binding + lifecycle records. The loop lives in
2
+ // loop.ts; this module only composes the parts and exposes a minimal API.
3
+
4
+ import type { BudgetPolicy } from "./budget.ts";
5
+ import { defaultBudgetPolicy } from "./budget.ts";
6
+ import type { CompactionStrategy } from "./compact.ts";
7
+ import { mechanicalCompaction } from "./compact.ts";
8
+ import { AgentError, abortError } from "./errors.ts";
9
+ import type { AgentEvent, EventBus } from "./events.ts";
10
+ import { createEventBus } from "./events.ts";
11
+ import type { ToolExecutor } from "./executor.ts";
12
+ import { sequentialExecutor } from "./executor.ts";
13
+ import { ContextStore } from "./history.ts";
14
+ import type { PermissionHandler } from "./permission.ts";
15
+ import type { ModelProvider } from "./provider.ts";
16
+ import type { RecoveryPolicy } from "./recovery.ts";
17
+ import { defaultRecoveryPolicy } from "./recovery.ts";
18
+ import { executeTurn } from "./loop.ts";
19
+ import { snapshotState, snapshotTurnResult } from "./snapshot.ts";
20
+ import type { Tool, ToolRegistry } from "./tool.ts";
21
+ import { createToolRegistry } from "./tool.ts";
22
+ import type { TokenEstimator } from "./tokens.ts";
23
+ import { defaultTokenEstimator, estimateSessionContext } from "./tokens.ts";
24
+ import type { Message, ToolCall, ToolResult } from "./types.ts";
25
+
26
+ export const DEFAULT_MAX_STEPS = 50;
27
+ export const DEFAULT_CONTEXT_WINDOW_TOKENS = 128_000;
28
+ export const DEFAULT_TOOL_RESULT_MAX_TOKENS = 4_096;
29
+ export const DEFAULT_KEEP_RECENT_TURNS = 3;
30
+
31
+ export const DEFAULT_TIMEOUT_MS = 600_000;
32
+
33
+ export interface SessionConfig {
34
+ provider: ModelProvider;
35
+ permissions: PermissionHandler;
36
+ tools?: readonly Tool[];
37
+ system?: string;
38
+ model?: string;
39
+ cwd?: string;
40
+ /**
41
+ * Session permission mode, forwarded to each turn's ToolContext so tools
42
+ * can adapt their behavior. Plain string or live getter — prefer the
43
+ * getter when the mode can change at runtime. Optional; absent preserves
44
+ * the legacy behavior (ctx.permissionMode undefined).
45
+ */
46
+ permissionMode?: string | (() => string);
47
+ /**
48
+ * Seed history untuk sesi baru (mis. resume dari storage). Messages akan
49
+ * di-append ke ContextStore saat createSession, jadi `session.state.history`
50
+ * langsung memuatnya dan turn berikutnya meneruskan konteks penuh.
51
+ */
52
+ initialMessages?: readonly Message[];
53
+ turnCount?: number;
54
+ stepCount?: number;
55
+ executor?: ToolExecutor;
56
+ budget?: BudgetPolicy;
57
+ estimator?: TokenEstimator;
58
+ compaction?: CompactionStrategy;
59
+ recovery?: RecoveryPolicy;
60
+ maxSteps?: number;
61
+ contextWindowTokens?: number;
62
+ toolResultMaxTokens?: number;
63
+ keepRecentTurns?: number;
64
+ /**
65
+ * Hard deadline for a single run() call, in milliseconds. When exceeded, the
66
+ * turn is aborted and run() rejects with AgentError("timeout") — even if the
67
+ * in-flight provider/tool ignores the abort signal. Defaults to
68
+ * DEFAULT_TIMEOUT_MS (10 minutes); set to Infinity to disable.
69
+ */
70
+ timeoutMs?: number;
71
+ /**
72
+ * Reports errors thrown by event listeners. Observer code must never be able
73
+ * to break a turn (lifecycle/executor events) nor trigger a spurious retry
74
+ * (provider streaming events): emit catches every handler error, reports it
75
+ * here, and continues. Defaults to console.error.
76
+ */
77
+ onHandlerError?: (error: unknown, event: AgentEvent) => void;
78
+ }
79
+
80
+ export interface SessionState {
81
+ readonly history: readonly Message[];
82
+ turnCount: number;
83
+ stepCount: number;
84
+ readonly model?: string;
85
+ }
86
+
87
+ export interface Execution {
88
+ readonly call: ToolCall;
89
+ readonly result: ToolResult;
90
+ }
91
+
92
+ export interface Step {
93
+ readonly index: number;
94
+ readonly toolCalls: readonly ToolCall[];
95
+ readonly results: readonly ToolResult[];
96
+ }
97
+
98
+ export interface TurnResult {
99
+ readonly steps: readonly Step[];
100
+ readonly finalText?: string;
101
+ readonly usage: { readonly turns: number; readonly steps: number };
102
+ }
103
+
104
+ export interface Session {
105
+ /**
106
+ * Point-in-time defensive snapshot of the committed session state.
107
+ *
108
+ * Each access deep-copies the committed history and counters, so a
109
+ * same-process caller that casts away the read-only types and mutates the
110
+ * result can never corrupt the kernel's state (the committed history that
111
+ * feeds the next turn) — the mutation touches only the caller's copy.
112
+ *
113
+ * Semantics: the returned value is a snapshot, not a live view. A reference
114
+ * held across a run stays frozen at the moment it was read; re-access
115
+ * `session.state` for fresh data. Committed state changes only when a turn
116
+ * completes successfully, and for change notification prefer the event bus
117
+ * (`turn:completed`, `step:completed`). Cost is O(history) per access, so
118
+ * read once per turn rather than polling.
119
+ */
120
+ readonly state: Readonly<SessionState>;
121
+ readonly events: EventBus;
122
+ /**
123
+ * Current context size from the same source of truth as the loop's
124
+ * pressure evaluation (messages + system + tools under the session
125
+ * estimator). One number for drivers and UI — no duplicate estimator.
126
+ * O(history) per access (snapshot pattern); recomputed over the
127
+ * committed store on every access.
128
+ */
129
+ readonly contextTokens: number;
130
+ run(input: string, opts?: { signal?: AbortSignal; model?: string }): Promise<TurnResult>;
131
+ abort(): void;
132
+ }
133
+
134
+ /** Internal handle consumed by loop.ts. Not part of the public surface. */
135
+ export interface SessionInternal {
136
+ readonly provider: ModelProvider;
137
+ readonly permissions: PermissionHandler;
138
+ readonly registry: ToolRegistry;
139
+ readonly executor: ToolExecutor;
140
+ readonly system?: string;
141
+ readonly model?: string;
142
+ readonly cwd?: string;
143
+ readonly permissionMode?: string | (() => string);
144
+ readonly budget: BudgetPolicy;
145
+ readonly estimator: TokenEstimator;
146
+ readonly compaction: CompactionStrategy;
147
+ readonly recovery: RecoveryPolicy;
148
+ readonly maxSteps: number;
149
+ readonly contextWindowTokens: number;
150
+ readonly toolResultMaxTokens: number;
151
+ readonly keepRecentTurns: number;
152
+ readonly timeoutMs: number;
153
+ readonly store: ContextStore;
154
+ readonly events: EventBus;
155
+ readonly state: SessionState;
156
+ }
157
+
158
+ interface SessionImpl extends SessionInternal {
159
+ sessionAbort: AbortController;
160
+ running: boolean;
161
+ }
162
+
163
+ export function createSession(config: SessionConfig): Session {
164
+ const store = new ContextStore();
165
+ if (config.initialMessages?.length) store.appendAll(config.initialMessages);
166
+ const events = createEventBus({ onHandlerError: config.onHandlerError });
167
+ const sessionAbort = new AbortController();
168
+ const state: SessionState = {
169
+ history: store.messages,
170
+ turnCount: config.turnCount ?? 0,
171
+ stepCount: config.stepCount ?? 0,
172
+ model: config.model,
173
+ };
174
+
175
+ const impl: SessionImpl = {
176
+ provider: config.provider,
177
+ permissions: config.permissions,
178
+ registry: createToolRegistry(config.tools ?? []),
179
+ executor: config.executor ?? sequentialExecutor(),
180
+ system: config.system,
181
+ model: config.model,
182
+ cwd: config.cwd,
183
+ permissionMode: config.permissionMode,
184
+ budget: config.budget ?? defaultBudgetPolicy,
185
+ estimator: config.estimator ?? defaultTokenEstimator,
186
+ compaction: config.compaction ?? mechanicalCompaction,
187
+ recovery: config.recovery ?? defaultRecoveryPolicy,
188
+ maxSteps: config.maxSteps ?? DEFAULT_MAX_STEPS,
189
+ contextWindowTokens: config.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS,
190
+ toolResultMaxTokens: config.toolResultMaxTokens ?? DEFAULT_TOOL_RESULT_MAX_TOKENS,
191
+ keepRecentTurns: config.keepRecentTurns ?? DEFAULT_KEEP_RECENT_TURNS,
192
+ timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
193
+ store,
194
+ events,
195
+ state,
196
+ sessionAbort,
197
+ running: false,
198
+ };
199
+
200
+ return {
201
+ // Public state crosses a host boundary, so it is a defensive snapshot per
202
+ // access (same policy as provider requests, tool ctx.state, and event
203
+ // payloads). The kernel keeps the raw object internally via `impl.state`.
204
+ get state() {
205
+ return snapshotState(state);
206
+ },
207
+ get events() {
208
+ return events;
209
+ },
210
+ // Same source of truth as the loop — estimateSessionContext in
211
+ // tokens.ts — never a duplicate estimator.
212
+ get contextTokens() {
213
+ return estimateSessionContext(store, config.system, impl.registry.list(), impl.estimator);
214
+ },
215
+ async run(input, opts) {
216
+ if (impl.running) throw new AgentError("busy", "session is already running");
217
+ impl.running = true;
218
+ const timeout = createTimeout(impl.timeoutMs);
219
+ const joined = joinSignals(impl.sessionAbort.signal, opts?.signal, timeout.signal);
220
+ const turnStore = new ContextStore();
221
+ turnStore.appendAll(store.messages);
222
+ const turnState: SessionState = {
223
+ history: turnStore.messages,
224
+ turnCount: state.turnCount,
225
+ stepCount: state.stepCount,
226
+ model: opts?.model ?? config.model,
227
+ };
228
+ const turnImpl: SessionInternal = {
229
+ ...impl,
230
+ store: turnStore,
231
+ state: turnState,
232
+ };
233
+ try {
234
+ const turn = executeTurn(turnImpl, input, joined.signal, opts?.model);
235
+ // The race guarantees run() rejects as soon as the joined signal
236
+ // aborts (user abort, session.abort, or timeout), even if the
237
+ // in-flight provider/tool ignores the signal. Any late work mutates
238
+ // only turnStore and is discarded.
239
+ const result = await withAbort(turn, joined.signal);
240
+ // A run is transactional with respect to model context: failed,
241
+ // aborted, or timed-out turns are discarded instead of leaving orphaned
242
+ // user messages or assistant tool_calls without matching tool results.
243
+ // Non-cooperative providers/tools may still settle after withTimeout
244
+ // rejects, but they mutate only this private turnStore.
245
+ store.replace(0, store.messages.length, turnStore.messages);
246
+ state.turnCount = turnState.turnCount;
247
+ state.stepCount = turnState.stepCount;
248
+ events.emit({ type: "turn:completed", result: snapshotTurnResult(result) });
249
+ return result;
250
+ } finally {
251
+ timeout.cancel();
252
+ joined.cleanup();
253
+ impl.running = false;
254
+ if (impl.sessionAbort.signal.aborted) impl.sessionAbort = new AbortController();
255
+ }
256
+ },
257
+ abort() {
258
+ if (impl.running) impl.sessionAbort.abort(new AgentError("aborted", "turn aborted"));
259
+ },
260
+ };
261
+ }
262
+
263
+ function joinSignals(...signals: Array<AbortSignal | undefined>): { signal: AbortSignal; cleanup(): void } {
264
+ const active = signals.filter((s): s is AbortSignal => s !== undefined);
265
+ if (active.length <= 1) {
266
+ return active[0] ? { signal: active[0], cleanup: noop } : { signal: new AbortController().signal, cleanup: noop };
267
+ }
268
+ const alreadyAborted = active.find((s) => s.aborted);
269
+ if (alreadyAborted) return { signal: alreadyAborted, cleanup: noop };
270
+ const controller = new AbortController();
271
+ const handlers: Array<[AbortSignal, () => void]> = active.map((s) => {
272
+ const onAbort = () => controller.abort(s.reason);
273
+ s.addEventListener("abort", onAbort, { once: true });
274
+ return [s, onAbort];
275
+ });
276
+ return {
277
+ signal: controller.signal,
278
+ cleanup() {
279
+ for (const [signal, onAbort] of handlers) signal.removeEventListener("abort", onAbort);
280
+ },
281
+ };
282
+ }
283
+
284
+ function noop(): void {}
285
+
286
+ interface Timeout {
287
+ readonly signal: AbortSignal;
288
+ cancel(): void;
289
+ }
290
+
291
+ function createTimeout(ms: number): Timeout {
292
+ const controller = new AbortController();
293
+ const error = new AgentError("timeout", `turn exceeded ${ms}ms`);
294
+ // setTimeout clamps a non-finite delay to 1ms in Node/Bun, so Infinity would
295
+ // abort the turn almost immediately instead of disabling the deadline.
296
+ const timer = Number.isFinite(ms) ? setTimeout(() => controller.abort(error), ms) : undefined;
297
+ return {
298
+ signal: controller.signal,
299
+ cancel: () => {
300
+ if (timer !== undefined) clearTimeout(timer);
301
+ },
302
+ };
303
+ }
304
+
305
+ function withAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
306
+ if (signal.aborted) return Promise.reject(abortError(signal));
307
+ return new Promise((resolve, reject) => {
308
+ const onAbort = () => {
309
+ cleanup();
310
+ reject(abortError(signal));
311
+ };
312
+ signal.addEventListener("abort", onAbort, { once: true });
313
+ promise.then(
314
+ (value) => {
315
+ cleanup();
316
+ resolve(value);
317
+ },
318
+ (cause) => {
319
+ cleanup();
320
+ reject(cause);
321
+ },
322
+ );
323
+ function cleanup() {
324
+ signal.removeEventListener("abort", onAbort);
325
+ }
326
+ });
327
+ }