@sorbetai/context 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,193 @@
1
- # Temporary Holding Version
1
+ # `@sorbetai/context`
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
+ `@sorbetai/context` owns Sorbet's Provider-neutral Context projection. It keeps
4
+ fixed prefix, append-only named state, Tool declarations, turn material, and
5
+ request material separate, then captures their per-request value in
6
+ `ContextSnapshot`. Prefix, Named State, and Tools form the model-visible current
7
+ state; Conversation and one-call material retain their temporal semantics.
8
+
9
+ | Area | Public entry point | Responsibility | Output |
10
+ | ---------------- | ------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------- |
11
+ | Fixed prefix | `ContextSource`, `PrefixContextContributor` | Compile current typed instructions, extensions, and Runtime authority. | `systemPrompt`, `prefixRevision` |
12
+ | Named state | `NamedStateOwner` | Read and validate one typed current value. | Per-name revision and XML frame |
13
+ | Tools | `PrepareContextInput.tools` | Compare selected declarations with the retained presentation. | Content revision and declaration delivery |
14
+ | Turn material | Turn-scoped document sources | Represent attachments and retrieved documents. | Ordinary user messages |
15
+ | Request material | `RequestContextSource`, `requestSources` | Propose per-call text with request-only or current-epoch retention. | Attributed user messages adopted with the request |
16
+ | Projection owner | `ContextManager` | Prepare, commit, restore, and start epochs. | Immutable `ContextSnapshot` and frame projection |
17
+ | Preparation | `ContextPreparationHook` | Compose mutable drafts with single-use `next` and explicit rejection. | Validated sources and state readings |
18
+ | Compiler | `ContextCompiler` | Render required changes after revisions are assigned. | Provider-neutral model input |
19
+
20
+ The package does not import Pi, discover resources, authorize Tool calls, or
21
+ lower Provider wire requests. Runtime supplies typed values and persists the
22
+ snapshot before calling `ContextManager.commit()`.
23
+
24
+ `inspectPrefixSourceLayout()` exposes non-overlapping source offsets and provenance
25
+ from an already-rendered immutable prefix. It never rerenders source text and returns
26
+ `unavailable` when that prefix does not match the owning renderer's layout. Offsets
27
+ measure UTF-16 characters, not Provider tokens. Runtime's read-only request inspection
28
+ uses them for source estimates; Context has no telemetry collector dependency.
29
+
30
+ Runtime's built-in `tool_sources` is an ordinary Named State containing capability
31
+ Namespace summaries. It uses the same comparison, absent-state transitions,
32
+ epoch restoration, and snapshot evidence as other Named States. Discovery selects
33
+ Tools; their declarations are reconciled independently of source descriptions.
34
+
35
+ `ContextManagerOptions.preparationHooks` captures an ordered chain for new logical
36
+ requests. Hooks edit resolved sources and declared state readings before revision
37
+ assignment, including after `await next(draft)`. They return an explicit
38
+ `continue` or `reject` decision; rejection throws `ContextPreparationRejectedError`
39
+ without changing committed Context. `next` performs preparation only, never model
40
+ dispatch or persistence. See the [preparation contract](./src/README.md#preparation)
41
+ and [ADR-0076](../../docs/adr/0076-native-context-preparation.md) for ownership.
42
+ Per-call `PrepareContextInput.preparationHooks` are captured before asynchronous
43
+ reads and nested inside that Host chain. Plugins uses the public
44
+ `runContextPreparation` dispatcher under a publication lease; Context has no Plugin
45
+ dependency. See [leased integration](../../docs/adr/0078-leased-context-preparation.md).
46
+
47
+ `PrepareContextInput.historySelection` supplies the initial `draft.modelView` before
48
+ the Hook chain. Hooks may compose with, replace or remove it. Runtime validates
49
+ the resulting references and complete Tool exchanges before request adoption;
50
+ selection and derived request material do not rewrite Journal conversation.
51
+
52
+ `draft.toolNames` starts with the captured declaration names. Hooks may narrow it
53
+ for the logical request; omission preserves the downstream selection. A Hook cannot
54
+ restore a name excluded by another Hook or invent an execution binding. Rebase
55
+ preserves the selected definitions without rerunning preparation. Runtime applies
56
+ this selection before permissions and effects when dispatching model Tool calls.
57
+
58
+ Hooks may edit `draft.requestSources` to propose material for
59
+ `scope.requestScopeId`, which Runtime supplies as the logical model-call identity.
60
+ `retention: 'request'` limits later model visibility to that call and its physical
61
+ retries; `retention: 'epoch'` retains the adopted occurrence for later calls until
62
+ compaction. Both kinds are recorded durably in the request snapshot. Neither
63
+ kind admits another user command or changes the immutable turn sources. See
64
+ [ADR-0077](../../docs/adr/0077-request-context-material.md) for adoption, placement
65
+ and recovery semantics.
66
+
67
+ The SDK may supply fixed definitions directly as typed sources or through a
68
+ `PrefixContextContributor`. Contributors are reread before each logical model
69
+ call and may return only instruction or extension sources. Context renders the
70
+ result through its fixed vocabulary:
71
+
72
+ ```xml
73
+ <sorbet-system-context>
74
+ <system-instructions>Follow repository instructions.</system-instructions>
75
+ <extension-section type="skill" name="repository-work">...</extension-section>
76
+ </sorbet-system-context>
77
+ ```
78
+
79
+ This root belongs only to the replaceable Provider prefix. Named state uses the
80
+ state name as its own XML root and is never nested beneath it.
81
+
82
+ A state owner returns both the current JSON value and the element that value
83
+ renders as. Context serializes that element: attributes for identity and status,
84
+ text for the state's own content, and children for entries.
85
+
86
+ ```xml
87
+ <objective status="paused">Ship the release</objective>
88
+ ```
89
+
90
+ ```xml
91
+ <codemode_tools>
92
+ <tool path="tools.read" args="{ path: string }">Read a text file.</tool>
93
+ <tool path="tools.search" args="{ query: string }">Search files.</tool>
94
+ </codemode_tools>
95
+ ```
96
+
97
+ There is no aggregate dynamic-state wrapper, no revision attribute and no delta
98
+ frame: every frame is complete, and the latest frame with a state's element name
99
+ supersedes earlier ones. A reader therefore never needs an earlier frame to
100
+ interpret a later one. Removal is an explicit same-name tombstone:
101
+
102
+ ```xml
103
+ <objective removed="true"/>
104
+ ```
105
+
106
+ An unchanged value emits no frame. `namedStates[].value` stores the complete
107
+ current value for runtime projections and recovery; committed model input retains
108
+ the exact frame sent for replay.
109
+
110
+ A changed fixed definition replaces the top-level `systemPrompt`; a changed state
111
+ appends only that name; a document enters the turn as a normal user message.
112
+ After compaction, the next request restores every currently present state at
113
+ conversation boundary `0`.
114
+
115
+ Safe retries reuse the captured snapshot and final Provider context. Reopen
116
+ rebuilds owner state from ordered durable snapshots. See the
117
+ [domain contract](./src/README.md) and
118
+ [ADR-0004](../../docs/adr/0004-single-context-injection-point.md).
119
+
120
+ ## Tool declarations
121
+
122
+ Supply the complete selected catalog to `prepare({ tools })`. Context captures
123
+ model-visible definitions before asynchronous reads, compares by name and
124
+ content, and ignores incidental catalog reordering. Discovery decides which
125
+ Tools belong in this catalog; Context decides what needs to be declared.
126
+ Declaration order keeps replay survivors, then new or redefined names.
127
+ Execution bindings and Permission remain Runtime responsibilities.
128
+
129
+ ```ts
130
+ import { ContextManager } from '@sorbetai/context';
131
+ import * as s from '@earendil-works/pi-schema';
132
+
133
+ const context = new ContextManager();
134
+ const readFile = {
135
+ name: 'read_file',
136
+ description: 'Read a file.',
137
+ parameters: s.obj({ path: s.str() }),
138
+ };
139
+
140
+ const first = await context.prepare({
141
+ stateOwners: [],
142
+ turnScopeId: 'turn-1',
143
+ tools: [readFile],
144
+ });
145
+ console.log(first.tools?.delivery.kind); // restoration
146
+
147
+ // Runtime persists model.requested before adopting this prepared snapshot.
148
+ context.commit(first);
149
+ const next = await context.prepare({
150
+ stateOwners: [],
151
+ turnScopeId: 'turn-2',
152
+ afterMessageCount: 2,
153
+ tools: [readFile],
154
+ });
155
+ console.log(next.tools?.delivery.kind); // unchanged
156
+ console.log(context.frames(next).filter((frame) => frame.kind === 'tools').length); // 1
157
+ ```
158
+
159
+ `ContextSnapshot.tools` contains complete `definitions`, content `revision`,
160
+ and `delivery`. Initial declarations and restoration use boundary `0`, including
161
+ an empty catalog. Transitions carry added definitions and removed names at the
162
+ current Conversation boundary; modifying a name removes and re-adds it.
163
+ `context.frames()` carries `kind: 'tools'` frames containing the neutral `tools`
164
+ snapshot. Runtime translates these decisions into Pi system messages near
165
+ `ModelRequestBoundary`; Context does not define a transport message format.
166
+
167
+ Restoring a newer epoch clears presentation while retaining definitions and
168
+ revision. The next request restores the full current catalog without incrementing
169
+ revision merely for restoration. Reopen uses retained declaration frames, rather than
170
+ the last catalog alone. Omitting `tools` leaves this optional projection out of
171
+ that preparation; pass `tools: []` to declare a known-empty catalog.
172
+
173
+ Pi owns conversion to each Provider protocol. A declaration transition can
174
+ require a full-catalog fallback, so this API does not promise universal cache
175
+ or wire-size savings. See
176
+ [ADR-0087](../../docs/adr/0087-context-world-state-and-incremental-tools.md).
177
+
178
+ The public surface is exported from [`src/index.ts`](./src/index.ts). Do not
179
+ deep-import internal modules.
180
+ XML rendering uses the package's internal string serializer and requires no DOM
181
+ or Node polyfills. Typed sources determine the tree without runtime AST schema
182
+ validation. Producers supply valid element and attribute names; the serializer
183
+ escapes text and attribute values, including literal entity references, and
184
+ preserves text whitespace. Attribute tabs and line endings use character
185
+ references so XML normalization preserves their values.
186
+
187
+ ## Development
188
+
189
+ ```sh
190
+ pnpm --filter @sorbetai/context typecheck
191
+ pnpm --filter @sorbetai/context test
192
+ pnpm --filter @sorbetai/context build
193
+ ```