@sorbetai/durable 0.0.0-stage → 0.1.0-alpha.17

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Loro LLC.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,305 @@
1
- # Temporary Holding Version
1
+ # @sorbetai/durable
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The Task executor used by Node Agent and its Server, ACP and TUI hosts. It keeps Run identity, queued input,
4
+ approvals, model retry deadlines and compaction progress across process loss.
5
+ [ADR-0113](../../docs/adr/0113-independent-durable-executor.md) owns the package
6
+ boundary. The root SDK is host-neutral; `/pi` supplies Pi model transport and the
7
+ `SorbetSession` facade used by first-party hosts; `/children` supplies child agents
8
+ (the `agent` and Team Tools) for any host that composes a Unit. Runtime does not depend on this package.
9
+
10
+ | Behavior | Owner | Contract |
11
+ | --------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
12
+ | Unit lifetime | [`unit.ts`](./src/unit.ts) | Shared writer, Session attachment, wake timer and resource cleanup |
13
+ | Host commands | [`session.ts`](./src/session.ts), [`input.ts`](./src/input.ts) | Durable admission, input placement, approval replies and cancellation |
14
+ | Execution | [`run.ts`](./src/run.ts), [`generation.ts`](./src/generation.ts), [`tool.ts`](./src/tool.ts) | Task phases and atomic lifecycle boundaries |
15
+ | Compaction | [`compaction.ts`](./src/compaction.ts) | Durable workflow progress; borrows Runtime's summary planner and algorithm |
16
+ | Plugins and resources | [`bindings.ts`](./src/bindings.ts), [`resources.ts`](./src/resources.ts), [`yield.ts`](./src/yield.ts) | Request borrows, behavior constraints, Run resource drain and Goal continuation |
17
+ | Evidence | [`history.ts`](./src/history.ts) | Incremental execution indexes and Runtime's shared conversation projection |
18
+ | Model transport | [`contracts.ts`](./src/contracts.ts), [`transport.ts`](./src/pi/transport.ts) | Neutral model requests; Pi authentication, Provider calls and stream parsing |
19
+ | Host facade | [`pi/session.ts`](./src/pi/session.ts) | Host Session controls, shared Runtime services and Sorbet live-event translation |
20
+ | Child agents | [`children/`](./src/children/README.md) | Child Task admission, completion delivery, agent and Team Tools behind a host port |
21
+ | Persistence | [`@sorbetai/runtime`](../runtime/src/units/README.md) | UnitStore, commit line, Task kernel, Signals and fact validation |
22
+
23
+ The dependency direction is `durable → runtime/context/plugins/model`. Runtime
24
+ never imports Durable. The executor uses the existing Task scheduler and Journal.
25
+ Its root entry does not import Pi; `/pi` borrows configured Pi Models and never
26
+ owns credentials or a second Provider catalog.
27
+
28
+ ## Use
29
+
30
+ ```ts
31
+ import { JsonlUnitStore } from '@sorbetai/runtime/node';
32
+ import { DurableSession } from '@sorbetai/durable';
33
+ import { createPiTransport } from '@sorbetai/durable/pi';
34
+
35
+ const session = await DurableSession.open({
36
+ store: new JsonlUnitStore({ unitId: 'assistant', filePath: '/data/assistant.jsonl' }),
37
+ model: { provider: selected.provider, id: selected.id, api: selected.api },
38
+ transport: createPiTransport(models),
39
+ toolPermissionPolicy: {
40
+ fallback: { access: 'allow', approval: 'required' },
41
+ tools: {},
42
+ rules: [],
43
+ },
44
+ tools,
45
+ plugins: platform,
46
+ resourceProvider,
47
+ });
48
+ try {
49
+ const run = await session.start({ prompt: 'Inspect the project.', idempotencyKey: 'request-1' });
50
+ // The host handles pendingApprovals() while result() waits.
51
+ const answer = await run.result();
52
+ await run.drained();
53
+ } finally {
54
+ await session.close();
55
+ }
56
+ ```
57
+
58
+ Use a dedicated C UnitStore. The executor rejects units owned by another executor.
59
+ Browser bundles can use the root SDK and `createPiTransport` without Node
60
+ polyfills or builtin-module externals. Inject the host's `UnitStore` and Tool
61
+ resources; browser packaging does not provide a Durable Object storage adapter
62
+ or alarm integration.
63
+ Hosts own Tool resources and sandbox policy. `resourceProvider.acquire` runs before
64
+ external work on each live Run attachment, including recovery. Release runs once
65
+ after Task settlement; a following Run waits for release. A release failure leaves
66
+ the committed Run outcome intact, rejects subsequent work, and is reported by close.
67
+ A behavior requiring a read-only workspace requires a resource that explicitly
68
+ attests to that constraint.
69
+
70
+ ## CodeMode
71
+
72
+ CodeMode is supplied by the [`@sorbetai/codemode` Plugin](../../plugins/codemode/README.md).
73
+ Mount it on a Plugin Platform and pass that Platform to the Session. Node Agent
74
+ mounts it by default. Durable owns its nested tool permission, Effect and recovery
75
+ boundaries; the Plugin owns the interpreter, instructions and tool catalog state.
76
+
77
+ ## Shared Session tree
78
+
79
+ `DurableSession.open` owns a root Session and closes its Unit. For a tree, use
80
+ `DurableUnit` and attach each Session with its own model, permissions, plugins
81
+ and resource provider:
82
+
83
+ ```ts
84
+ import { DurableUnit } from '@sorbetai/durable';
85
+
86
+ const unit = await DurableUnit.open({ store });
87
+ try {
88
+ const root = await unit.attach(unit.unitId, rootEnvironment);
89
+ await unit.createSession({
90
+ sessionId: 'researcher',
91
+ parentSessionId: unit.unitId,
92
+ creationKey: 'researcher',
93
+ });
94
+ const child = await unit.attach('researcher', childEnvironment);
95
+ const runs = await Promise.all([
96
+ root.start({ prompt: 'Review the implementation.', idempotencyKey: 'review' }),
97
+ child.start({ prompt: 'Check the references.', idempotencyKey: 'review' }),
98
+ ]);
99
+ await Promise.all(runs.map((run) => run.result()));
100
+ } finally {
101
+ await unit.close();
102
+ }
103
+ ```
104
+
105
+ `createSession` persists a child identity; it does not start work or inherit the
106
+ parent's authority. On reopen, use `sessions()` to discover existing identities
107
+ and `attach` the environments that are available. An unbound Session's unfinished Tasks
108
+ stay visible through `unit.tasks()` with `definition_missing`; attaching enables them
109
+ after its Journal projections are restored. Other attached Sessions can run.
110
+ Attach each identity once at a time. `unit.detach(sessionId)` drains that Session
111
+ and suspends its live Task reservations without ending its Run. Reattachment
112
+ restores the same Tasks and reacquires resources; sibling Sessions keep running.
113
+
114
+ Task kinds and stored ownership remain unchanged. Runtime selects process-local
115
+ Task handlers by the owning Session, following nested Task ownership. Each
116
+ Session owns its history, approvals, grants, inputs and Run resources. Run
117
+ idempotency keys are Session-local; Submission delivery IDs remain Unit-wide.
118
+ Session `tasks`, `retryTask` and Submission lookup stay within that Session.
119
+ `waitForIdle` joins runnable work across the Unit, including sibling Sessions;
120
+ approval and timer waits remain pending. `unit.close` drains every attached
121
+ Session before releasing resources; borrowed Session handles are released through `unit.detach`.
122
+
123
+ Node Agent composes its existing Agent/Team Tools and Reporter Tasks with these
124
+ Session bindings. Spawn, initial input, replies and completion delivery keep their
125
+ Unit transaction boundaries. Child Run permits and sandbox resources belong to
126
+ the host; the executor acquires them before any external work.
127
+
128
+ To attach to an existing host-owned Unit, use
129
+ `DurableSession.attach(unitRuntime, sessionId, environment)`. Closing that binding
130
+ does not close the Unit writer. The host retains wake and shutdown ownership.
131
+
132
+ ## Input, permissions and recovery
133
+
134
+ `start` atomically records admission and creates its RunTask. Repeating the same
135
+ idempotency key returns that Run; conflicting content or a competing Run rejects.
136
+ `submit({ prompt, deliveryId, whenBusy })` persists queued input. Steering enters
137
+ at the next Tool boundary; follow-up and remaining steering start a successor Run
138
+ at the final boundary. `whenBusy: 'reject'` refuses new input while a Run is active,
139
+ without accepting a Submission.
140
+ `steeringMode: 'all'` places all queued steering at a Tool boundary; the default
141
+ places one. `followUpMode: 'all'` places all pending steering and follow-up inputs
142
+ into one successor Run at the final boundary; the default selects one. Acceptance
143
+ order determines batch order. The prior terminal, successor Task and every batch
144
+ placement share one commit. The returned Submission supports durable status,
145
+ placement, settlement and withdrawal before placement.
146
+
147
+ Input content lives in `submission.accepted`; `submission.placed` records its
148
+ Run, message identity and boundary. Additional inputs and yield continuations do
149
+ not also write `run.input.accepted`. Runtime's shared projection joins these facts
150
+ and reads old dual-write journals without duplicating messages. Initial
151
+ `run.accepted` remains the Run's admission and authority record.
152
+
153
+ `submitInput(input, { whenBusy })` accepts a user message, a `context-event`
154
+ with turn Context sources, or a `write`/`reset` control. Context events enter model
155
+ input without becoming user conversation messages. Each delivery has its own
156
+ compiled source namespace, so independent reports may reuse source names; the
157
+ accepted sources remain unchanged. Request evidence identifies which inputs kept
158
+ material after preparation. Recovery resends the committed request with the same
159
+ Context rather than preparing the event again.
160
+
161
+ `pendingApprovals()` includes unresolved requests restored from disk.
162
+ `resolveApproval(id, { outcome: 'allowed-once' })` authorizes one attempt;
163
+ `{ outcome: 'rejected', reason }` denies it. Equivalent replies are idempotent;
164
+ conflicting replies reject. Adding `remember: 'session'` grants future calls with
165
+ that exact Tool name and complete prepared parameters. `listPermissionGrants()`
166
+ returns active grants; `revokePermissionGrant(id)` durably revokes future reuse.
167
+ Reopening restores grants and revocations. A base deny remains binding; existing
168
+ approval waits and already admitted Effects keep their decisions. Safe retries
169
+ recheck current grants and otherwise require a fresh approval. See
170
+ [Session grant semantics](../runtime/src/permissions/README.md).
171
+ Both admitted and current policies, binding identities and parameter schemas must
172
+ permit a Tool. Prepared approval parameters remain fixed across reopen. Plugin
173
+ contribution identity survives restart; execution borrows the current implementation
174
+ and records its actual lease/binding on the Effect. Historical process-local bindings
175
+ are never restored or treated as authority.
176
+
177
+ A lost model request is recorded as unknown, then sent under a new physical ID
178
+ with its original logical ID, context and dispatch settings. Transient failures
179
+ sleep durably before retrying; defaults are three retries, a two-second initial
180
+ delay and a sixty-second delay cap. `modelRetry.maxRetries: Infinity` removes the
181
+ attempt limit. The Pi adapter disables hidden Provider retries.
182
+
183
+ A lost Tool attempt becomes `effect.unknown`. An unsafe Tool returns uncertainty
184
+ to the model. If both its recorded and current declarations are safe,
185
+ `safeToolRetries` permits new attempts (default one). Every new attempt has a new
186
+ identity, reruns authorization and obtains a fresh one-time approval when required.
187
+ It never reuses or overwrites the abandoned attempt.
188
+
189
+ `abort` records cancellation, drains the Task subtree and external operations,
190
+ then commits the cancelled Run outcome. `close` drains I/O and releases the writer
191
+ while retaining unfinished work. A Tool that ignores cancellation can delay close.
192
+ Cancelling `run.result(signal)` only detaches that observer.
193
+
194
+ `waitForIdle()` joins currently runnable work; durable approvals and retry sleeps
195
+ may remain. `tasks()` lists those unfinished states and parked work; ended Tasks are
196
+ history in the Journal. `taskRestartLimit`
197
+ uses the existing consecutive unclean-recovery policy (default five, `Infinity`
198
+ disables parking). `retryTask(id, commandId)` explicitly resets parked work.
199
+
200
+ ## Context, plugins and Goal
201
+
202
+ Each Generation borrows the current Plugin model port. Input transforms and their
203
+ request evidence commit together. Preparation hooks, history selection, prefixes,
204
+ Named State owners and declaration narrowing feed the shared ContextManager.
205
+ Physical retries reuse committed input without rerunning those callbacks. Tool
206
+ invocation and Named State reads can observe committed Tool results.
207
+
208
+ Tool Hooks use the shared `prepare`/`feedback` contract. Prepared arguments and
209
+ JSON state commit as a Journal fact before approval; Task checkpoints retain only
210
+ its identity, so large file arguments do not exhaust the checkpoint budget. The actual Effect commits before feedback;
211
+ reopening that phase reprocesses its result without dispatching the Tool again.
212
+ Preparation and feedback may repeat if their own result did not commit. See the
213
+ [Hook contract](../plugins/README.md#tool-hooks) for ordering and versioning.
214
+
215
+ `write({ deliveryId, text, source })` adds display-only text. It normally applies
216
+ in its acceptance commit, but stays behind an earlier pending reset.
217
+ `reset({ deliveryId, source })` waits until the current Run settles, then starts a
218
+ new effective-conversation epoch before later input. It preserves fixed prefix,
219
+ Named State revisions, history and usage. Neither control calls a model or starts
220
+ a Run. `submission.applied` is its terminal; await `settled()`, not `placed()`.
221
+ `displayEntries()` interleaves conversation and controls by their applied order;
222
+ `SorbetSession.conversation()` retains its historical conversation contract;
223
+ model requests use the reset-aware effective projection.
224
+
225
+ `requestContext()` returns the latest settled request prefix plus the messages
226
+ committed after it, or `undefined` when a later compaction, reset or input rewrite
227
+ invalidated that prefix. Host features extend it with one instruction instead of
228
+ rebuilding the system prompt, Tool declarations and conversation themselves.
229
+
230
+ `listBehaviors`, `commandBehavior` and `getUsage` support the existing optional
231
+ [Goal plugin](../../plugins/goal/README.md). Yield decisions commit with either
232
+ continuation input or the Run terminal. Continuation retains the same Run and
233
+ resource attachment. Host state changes during an asynchronous hook invalidate
234
+ its pending decision. `yieldUsageLimit` limits committed Run token usage at yield
235
+ boundaries; omission and `Infinity` impose no limit. Goal owns its own cross-Run
236
+ budget and state.
237
+
238
+ Configure `compaction` with model capacity/pricing and optional settings to enable
239
+ threshold compaction. An overflow triggers a blocking CompactionTask, followed by
240
+ one retry after successful compaction. Summary calls use write-ahead facts and
241
+ checkpoints. Reopening reuses committed summary responses and resends only an
242
+ interrupted call under a new identity. Committing the summary starts a new Context
243
+ epoch while preserving Named State revisions. Compaction changes the effective
244
+ conversation, never the historical Journal.
245
+
246
+ ## Host facade and migration
247
+
248
+ `SorbetSession` reuses Runtime's public Journal handles, external model/Tool
249
+ operations, automatic reviewer, artifact archive and Object capabilities. It
250
+ provides live Tool/Plan/usage events, manual compaction and the Session controls
251
+ used by first-party hosts. Node Agent remains responsible for sandbox policy,
252
+ Plugin composition, credentials, attaching child Sessions and environment cleanup.
253
+
254
+ An interrupted A/B Run is adopted under its existing `runId`. Adoption settles
255
+ old model requests, Effects and approvals before creating its RunTask; external
256
+ work reacquires the host environment. The old Run's resume limit and explicit
257
+ `resetAttempts` still apply during adoption. Already-created C Tasks use Task
258
+ recovery instead. Cancellation receipts acknowledge committed intent; `result()`
259
+ and `drained()` wait for terminal outcome and resource cleanup respectively.
260
+ A RunTask that ends without writing its Run terminal (a faulted phase, an orphaned
261
+ abort) does not leave the Session busy: the attached Session, `resume()` and
262
+ `abort()` settle its open model requests, Effects and approvals as facts and commit
263
+ one `run.failed` (`runtime_error`) or, after a cancel request, `run.cancelled`.
264
+ A parked descendant Task makes the host Run view `parked`; it is not reported as
265
+ active execution. `resumeInterruptedRun(runId, { resetAttempts: true })` resets its parked
266
+ Tasks under the same Run identity. The Unit recovery decision uses that same Task
267
+ graph, so it does not repeatedly reacquire an environment for parked work.
268
+ The facade also exposes `tasks()` and `retryTask()` for Session-owned work such as
269
+ manual compaction.
270
+
271
+ Public Pi type cleanup and removal of the legacy executor remain separate work.
272
+ The [execution plan](../../docs/exec-plans/20261028-00-durable-stage-c-package.md)
273
+ tracks complete Stage C acceptance.
274
+
275
+ Streaming deltas are delivered and discarded. Checkpoints contain IDs and phases,
276
+ not transcripts. Preparing model input still copies selected conversation; reopening
277
+ still scans history. No constant-memory or constant-time-reopen claim is made.
278
+
279
+ ## Verify
280
+
281
+ ```sh
282
+ pnpm --filter @sorbetai/durable... build
283
+ pnpm --filter @sorbetai/durable test
284
+ pnpm --filter @sorbetai/durable typecheck
285
+ pnpm --filter @sorbetai/durable benchmark
286
+ ```
287
+
288
+ Tests use real JSONL process termination and HTTP/SSE through Pi, plus deterministic
289
+ transports for fault placement. They validate execution semantics, not live-model
290
+ quality. The benchmark isolates Harness overhead from model latency.
291
+
292
+ ## Migrating from the old executor
293
+
294
+ `@sorbetai/runtime` no longer exports `SorbetSession` or its construction options.
295
+ Use the owned Unit API above, or `SorbetSession.open({ unit, sessionId, models,
296
+ model, toolPermissionPolicy })` for an existing host-owned Unit. Pi-facing model
297
+ objects are confined to `/pi`; general Tools use Runtime's `ToolDefinition` and
298
+ `ToolResult`, messages use Context's neutral types. An injected ContextManager is
299
+ exclusive to that Session attachment.
300
+
301
+ [Shared Session services](../runtime/src/session/README.md) own inspection,
302
+ independent Tool/model operations, Plugin records and behaviors.
303
+ [Object capabilities](../runtime/src/session/objects.md) document granted method
304
+ selection and cleanup. Old Journal data remains readable and interrupted A/B Runs
305
+ use the existing adoption path; removing the executor does not rewrite history.