@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 +21 -0
- package/README.md +192 -2
- package/dist/index.d.ts +3129 -0
- package/dist/index.js +1277 -0
- package/dist/index.js.map +1 -0
- package/package.json +34 -3
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
|
-
#
|
|
1
|
+
# `@sorbetai/context`
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
```
|