@sorbetai/runtime 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,88 @@
1
- # Temporary Holding Version
1
+ # @sorbetai/runtime
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
+ Sorbet's shared durable domains: the Unit writer and commit line, Task kernel,
4
+ Run and Effect facts, permissions, and Session read models. Agent execution lives
5
+ in [`@sorbetai/durable`](../durable/README.md). Runtime does not import that executor
6
+ or instantiate a Pi Agent.
7
+
8
+ | Domain | Owner | Contract |
9
+ | ----------- | ------------------------------------------ | ------------------------------------------------------------------------------------ |
10
+ | Unit | [units](./src/units/README.md) | One Session tree, writer, atomic groups, reliable messages and recovery coordination |
11
+ | Tasks | [tasks](./src/tasks/README.md) | Durable phases, waits, checkpoints, cancellation and restart policy |
12
+ | Journal | [journal](./src/journal) | Append-only facts, storage, cursors and subscriptions |
13
+ | Run | [run](./src/run) | Admission, lifecycle validation, outcome and input projections |
14
+ | Session | [session](./src/session/README.md) | Conversation, request evidence, usage, plugins and shared services |
15
+ | Tools | [tools](./src/tools/README.md) | Neutral definitions, discovery and bounded output |
16
+ | Permissions | [permissions](./src/permissions/README.md) | Policy evaluation and exact-action grants |
17
+ | Events | [events](./src/events) | Transient execution and lifecycle notifications |
18
+ | Observation | [observation](./src/observation/README.md) | Passive measurements of existing domain boundaries |
19
+
20
+ ## Execution and ownership
21
+
22
+ Use `DurableSession.open` for a Session that owns its Unit, `DurableUnit` for a tree,
23
+ or `SorbetSession.open({ unit, ... })` to attach to a host-owned `UnitRuntime`.
24
+ [Durable's examples and ownership rules](../durable/README.md#use) describe these
25
+ entry points. The old `SorbetSession` executor and its construction options have
26
+ been removed. Compatible Journal facts can be read and interrupted Runs adopted
27
+ by the durable executor without replaying old Effect attempts. This does not imply
28
+ compatibility with every published Journal format; see the
29
+ [Journal compatibility boundary](./src/journal/README.md).
30
+
31
+ A Durable Unit has one store, commit line and writer. Sessions borrow it; they do
32
+ not own separate writers. Atomic groups can cover a parent, its children and their
33
+ Tasks. Different Units run independently. Hosts own resources, transport and
34
+ rebuildable wake indexes. See [ADR-0106](../../docs/adr/0106-workspace-store-and-commit-line.md)
35
+ and [ADR-0113](../../docs/adr/0113-independent-durable-executor.md).
36
+
37
+ `JsonlUnitStore` persists atomic groups and excludes a second writer. Journal
38
+ readers and subscriptions never authorize execution. `JsonlJournalStore` remains
39
+ available for reading and validating historical single-Session data; it is not an
40
+ alternative Agent executor. Injected artifact and Tool output stores are borrowed;
41
+ the host owns their access and retention policy.
42
+
43
+ ## Public contracts
44
+
45
+ The root entry is the portable SDK in every environment. Import
46
+ `@sorbetai/runtime/node` for `JsonlUnitStore`, JSONL readers, filesystem writer
47
+ leases and Unit sealing. These adapters are no longer exported from the package
48
+ root; Node consumers must update their imports. Other hosts inject a `UnitStore`.
49
+
50
+ `ToolDefinition`, `ToolResult` and `ExecutionEvent` are Sorbet contracts. Message
51
+ and model-context types belong to `@sorbetai/context`. Provider and authentication
52
+ objects enter through the explicit `@sorbetai/durable/pi` adapter; Runtime's public
53
+ execution contracts do not expose Pi Agent state or Tool types.
54
+
55
+ `ToolInvocationContext.forkSeed` is now an optional asynchronous callback. Tools
56
+ that fork model context must check for it and call `await context.forkSeed()`;
57
+ nested invocations omit this capability. The previous eager seed value is removed.
58
+
59
+ Tools return execution results; Journal owns committed Effect outcomes and their
60
+ recovery feedback. Events describe transient observations of execution, while
61
+ Context owns the Tool messages presented to models. A committed Tool result can
62
+ be published immediately even when conversation projection awaits the rest of
63
+ the batch to preserve model call order.
64
+
65
+ `submission.accepted` owns input content and `submission.placed` owns its Run,
66
+ message identity and boundary. Additional input is not also written as
67
+ `run.input.accepted`. `RunInputProjection` joins those facts for conversation,
68
+ inspection and request reconstruction, and deduplicates historical journals that
69
+ wrote both forms. `run.accepted` still records the initial Run admission and its
70
+ authority. Display write/reset controls end with `submission.applied`.
71
+
72
+ Run outcomes, resources and live events have distinct lifetimes: the terminal
73
+ Journal fact settles `result()`; `drained()` joins execution and cleanup. A cleanup
74
+ failure cannot rewrite a terminal. Live stream deltas are transient; replayable
75
+ history comes from Journal facts and durable cursors.
76
+
77
+ ## Verification
78
+
79
+ ```sh
80
+ pnpm --filter @sorbetai/runtime test
81
+ pnpm --filter @sorbetai/runtime typecheck
82
+ pnpm --filter @sorbetai/durable test
83
+ ```
84
+
85
+ Runtime tests cover storage, Task and Run invariants. Executor integration,
86
+ permissions, plugins and process-loss scenarios live in Durable and the consuming
87
+ host packages. [The Stage C plan](../../docs/exec-plans/20261028-00-durable-stage-c-package.md)
88
+ records migration status and measured validation.