@sorbetai/control 0.0.0-stage → 0.1.0-alpha.18

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,79 @@
1
- # Temporary Holding Version
1
+ # `@sorbetai/control`
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/control` is Sorbet's headless local control plane. It manages authentication,
4
+ stored credentials, custom Providers, and the model catalog for one `dataDirectory`.
5
+ The same Provider runtime is used by `@sorbetai/node-agent`.
6
+
7
+ It does **not** create Sessions, execute Runs, load tools or plugins, connect MCP servers,
8
+ or start the durable executor.
9
+
10
+ ## Quick start
11
+
12
+ ```ts
13
+ import { openSorbetControl } from '@sorbetai/control';
14
+
15
+ const control = await openSorbetControl({ dataDirectory: '/path/to/.sorbet' });
16
+ try {
17
+ console.log(await control.authentication.methods());
18
+ console.log(await control.credentials.list()); // descriptors only; never secrets
19
+
20
+ const provider = await control.providers.createCustom({
21
+ name: 'Local gateway',
22
+ protocol: 'openai-responses',
23
+ baseUrl: 'http://127.0.0.1:8080/v1',
24
+ models: [{ id: 'local-model' }],
25
+ });
26
+ console.log(provider.id);
27
+ } finally {
28
+ await control.close();
29
+ }
30
+ ```
31
+
32
+ ## API surface
33
+
34
+ | API | Purpose |
35
+ | -------------------------- | ------------------------------------------------------------------------------------------------------ |
36
+ | `authentication.methods()` | List interactive API-key and OAuth login methods. |
37
+ | `authentication.login()` | Drive login through an injected `AuthInteraction`. |
38
+ | `credentials.list()` | List non-secret credential descriptors. |
39
+ | `credentials.logout()` | Remove one Provider's stored credential. |
40
+ | `providers.listCustom()` | Read custom Provider definitions. |
41
+ | `providers.createCustom()` | Persist and register a custom Provider. |
42
+ | `providers.updateCustom()` | Replace its definition while preserving identity and credentials. |
43
+ | `providers.deleteCustom()` | Remove an unreferenced custom Provider and related local state. |
44
+ | `providers.refresh()` | Rediscover models for dynamic Providers (custom + `radius`); pass `providers` in options to refresh one. |
45
+ | `providers.availableModels()` | Models a Host agent may select; pass `providerId` in options to list one Provider's models. |
46
+ | `providers.listConfigurable()` | Providers whose endpoint may be overridden. |
47
+ | `providers.setEndpoint()` | Override one Provider endpoint; only the non-secret `apiType`/`baseUrl` is persisted. |
48
+ | `providers.disableEndpoint()` | Clear one Provider's endpoint override and its persisted entry. |
49
+ | `compatibility` | Report the API name/version and package name/version; the package version is read from `package.json`. |
50
+ | `installationId()` | Read or create the stable local installation identity. |
51
+ | `close()` | Stop admission and drain admitted operations. |
52
+
53
+ ## Lifecycle and cancellation
54
+
55
+ Each call is admitted before it starts. Calling `close()` rejects later calls with
56
+ `control_closed` and waits for already-admitted work to settle. Per-operation failures remain
57
+ on their own promises; `close()` does not rethrow them.
58
+
59
+ `openSorbetControl({ signal })` may cancel initialization. Login and credential operations also
60
+ accept the cancellation signals supported by Pi. Provider mutations accept an `AbortSignal`. Aborting while waiting for the JSON mutation lease prevents the primary mutation. Once the `providers.json` replacement begins, later aborts are ignored while credential, endpoint, and model-catalog cleanup settles to its actual result.
61
+
62
+ ## Processes and live state
63
+
64
+ JSON-backed stores coordinate writers across processes with a JSON mutation lease and atomic
65
+ replacement. Multiple control or Node Agent processes can safely share one `dataDirectory`.
66
+
67
+ A running Node Agent keeps its Provider catalog in memory. Custom Provider changes made by a
68
+ separate control process are persisted safely, but that already-running Agent will not observe
69
+ them until it restarts or performs a host-provided refresh/recomposition.
70
+
71
+ Provider deletion reads every persisted Unit through Runtime's canonical recovery decoder and
72
+ fails closed on unsupported or corrupt committed state, corrupt reviewer settings, and legacy
73
+ Session data that still requires migration. A live Node Agent unions that strict disk view with
74
+ its projected catalog and reviewer selection so pending in-process references are also protected.
75
+
76
+ Provider registries are process-local. A control process can persist a change while another live
77
+ process retains its older registry until restart or host recomposition. Reference checking and the
78
+ `providers.json` mutation also remain separate cross-process steps, so a Session created between
79
+ them is a residual TOCTOU; the current architecture has no shared Unit/Provider transaction lock.
@@ -0,0 +1,306 @@
1
+ import * as s from "@earendil-works/pi-schema";
2
+ import { Api, AuthInteraction, AuthType, Credential, CredentialStore, Model, Models, ModelsRefreshOptions, ModelsRefreshResult, MutableModels } from "@earendil-works/pi-ai";
3
+
4
+ //#region src/agent-models.d.ts
5
+ /** A model one Host agent can select, with Sorbet's canonical `providerId/modelId` selector. */
6
+ interface AvailableAgentModel {
7
+ readonly selector: string;
8
+ readonly providerId: string;
9
+ readonly modelId: string;
10
+ readonly displayName: string;
11
+ }
12
+ declare function encodeModelSelector(providerId: string, modelId: string): string;
13
+ //#endregion
14
+ //#region src/compatibility.d.ts
15
+ /**
16
+ * Package/API identity reported by the control facade. `api` is the stable surface name a
17
+ * Host negotiates against; `packageVersion` is read from package.json so it cannot drift from the
18
+ * published artifact.
19
+ */
20
+ declare const SORBET_CONTROL_COMPATIBILITY: Readonly<{
21
+ api: "sorbet.control";
22
+ apiVersion: 1;
23
+ packageName: string;
24
+ packageVersion: string;
25
+ }>;
26
+ type SorbetControlCompatibility = typeof SORBET_CONTROL_COMPATIBILITY;
27
+ //#endregion
28
+ //#region src/providers/contracts.d.ts
29
+ declare const CustomProviderProtocolSchema: s.Schema<"anthropic-messages" | "openai-responses" | "openai-completions">;
30
+ declare const CustomProviderModelProperties: {
31
+ id: s.Schema<string>;
32
+ name: s.Optional<s.Schema<string>>;
33
+ reasoning: s.Optional<s.Schema<boolean>>;
34
+ thinkingLevelMap: s.Optional<s.Schema<{
35
+ off?: string | null | undefined;
36
+ minimal?: string | null | undefined;
37
+ low?: string | null | undefined;
38
+ medium?: string | null | undefined;
39
+ high?: string | null | undefined;
40
+ xhigh?: string | null | undefined;
41
+ max?: string | null | undefined;
42
+ }>>;
43
+ input: s.Optional<s.Schema<("text" | "image")[]>>;
44
+ contextWindow: s.Optional<s.Schema<number>>;
45
+ maxTokens: s.Optional<s.Schema<number>>;
46
+ };
47
+ declare const CustomProviderModelSchema: s.Schema<{
48
+ id: string;
49
+ name?: string | undefined;
50
+ reasoning?: boolean | undefined;
51
+ thinkingLevelMap?: {
52
+ off?: string | null | undefined;
53
+ minimal?: string | null | undefined;
54
+ low?: string | null | undefined;
55
+ medium?: string | null | undefined;
56
+ high?: string | null | undefined;
57
+ xhigh?: string | null | undefined;
58
+ max?: string | null | undefined;
59
+ } | undefined;
60
+ input?: ("text" | "image")[] | undefined;
61
+ contextWindow?: number | undefined;
62
+ maxTokens?: number | undefined;
63
+ }>;
64
+ declare const CreateCustomProviderInputSchema: s.Schema<{
65
+ name: string;
66
+ protocol: "anthropic-messages" | "openai-responses" | "openai-completions";
67
+ baseUrl: string;
68
+ models: {
69
+ id: string;
70
+ name?: string | undefined;
71
+ reasoning?: boolean | undefined;
72
+ thinkingLevelMap?: {
73
+ off?: string | null | undefined;
74
+ minimal?: string | null | undefined;
75
+ low?: string | null | undefined;
76
+ medium?: string | null | undefined;
77
+ high?: string | null | undefined;
78
+ xhigh?: string | null | undefined;
79
+ max?: string | null | undefined;
80
+ } | undefined;
81
+ input?: ("text" | "image")[] | undefined;
82
+ contextWindow?: number | undefined;
83
+ maxTokens?: number | undefined;
84
+ }[];
85
+ catalogRefs?: string[] | undefined;
86
+ }>;
87
+ declare const UpdateCustomProviderInputSchema: s.Schema<{
88
+ name: string;
89
+ protocol: "anthropic-messages" | "openai-responses" | "openai-completions";
90
+ baseUrl: string;
91
+ models: {
92
+ id: string;
93
+ name?: string | undefined;
94
+ reasoning?: boolean | undefined;
95
+ thinkingLevelMap?: {
96
+ off?: string | null | undefined;
97
+ minimal?: string | null | undefined;
98
+ low?: string | null | undefined;
99
+ medium?: string | null | undefined;
100
+ high?: string | null | undefined;
101
+ xhigh?: string | null | undefined;
102
+ max?: string | null | undefined;
103
+ } | undefined;
104
+ input?: ("text" | "image")[] | undefined;
105
+ contextWindow?: number | undefined;
106
+ maxTokens?: number | undefined;
107
+ }[];
108
+ catalogRefs?: string[] | undefined;
109
+ }>;
110
+ declare const CustomProviderDefinitionSchema: s.Schema<{
111
+ id: string;
112
+ name: string;
113
+ protocol: "anthropic-messages" | "openai-responses" | "openai-completions";
114
+ baseUrl: string;
115
+ models: {
116
+ id: string;
117
+ name?: string | undefined;
118
+ reasoning?: boolean | undefined;
119
+ thinkingLevelMap?: {
120
+ off?: string | null | undefined;
121
+ minimal?: string | null | undefined;
122
+ low?: string | null | undefined;
123
+ medium?: string | null | undefined;
124
+ high?: string | null | undefined;
125
+ xhigh?: string | null | undefined;
126
+ max?: string | null | undefined;
127
+ } | undefined;
128
+ input?: ("text" | "image")[] | undefined;
129
+ contextWindow?: number | undefined;
130
+ maxTokens?: number | undefined;
131
+ }[];
132
+ catalogRefs?: string[] | undefined;
133
+ }>;
134
+ type CustomProviderProtocol = s.Static<typeof CustomProviderProtocolSchema>;
135
+ type CustomProviderModel = Readonly<s.Static<typeof CustomProviderModelSchema>>;
136
+ type CreateCustomProviderInput = Readonly<s.Static<typeof CreateCustomProviderInputSchema>>;
137
+ type UpdateCustomProviderInput = Readonly<s.Static<typeof UpdateCustomProviderInputSchema>>;
138
+ type CustomProviderDefinition = Readonly<s.Static<typeof CustomProviderDefinitionSchema>>;
139
+ declare const ProviderProtocolSchema: s.Schema<string>;
140
+ declare const ProviderEndpointConfigurationProperties: {
141
+ apiType: s.Schema<string>;
142
+ baseUrl: s.Schema<string>;
143
+ };
144
+ declare const ProviderEndpointConfigurationSchema: s.Schema<{
145
+ apiType: string;
146
+ baseUrl: string;
147
+ }>;
148
+ declare const ProviderEndpointOverrideSchema: s.Schema<{
149
+ apiType: string;
150
+ baseUrl: string;
151
+ headers?: Record<string, string> | undefined;
152
+ }>;
153
+ declare const ConfigurableProviderSchema: s.Schema<{
154
+ providerId: string;
155
+ supported: string[];
156
+ required: boolean;
157
+ current: {
158
+ apiType: string;
159
+ baseUrl: string;
160
+ } | null;
161
+ }>;
162
+ type ProviderProtocol = s.Static<typeof ProviderProtocolSchema>;
163
+ type ProviderEndpointConfiguration = Readonly<s.Static<typeof ProviderEndpointConfigurationSchema>>;
164
+ type ProviderEndpointOverride = Readonly<s.Static<typeof ProviderEndpointOverrideSchema>>;
165
+ type ConfigurableProvider = Readonly<s.Static<typeof ConfigurableProviderSchema>>;
166
+ interface CustomProviderStore {
167
+ list(options?: {
168
+ readonly signal?: AbortSignal;
169
+ }): Promise<readonly CustomProviderDefinition[]>;
170
+ create(provider: CustomProviderDefinition, options?: {
171
+ readonly signal?: AbortSignal;
172
+ }): Promise<void>;
173
+ replace(provider: CustomProviderDefinition, options?: {
174
+ readonly signal?: AbortSignal;
175
+ }): Promise<void>;
176
+ delete(providerId: string, options?: {
177
+ readonly signal?: AbortSignal;
178
+ }): Promise<void>;
179
+ }
180
+ interface PersistedProviderEndpoint {
181
+ readonly providerId: string;
182
+ readonly configuration: ProviderEndpointConfiguration;
183
+ }
184
+ interface ProviderEndpointStore {
185
+ list(): Promise<readonly PersistedProviderEndpoint[]>;
186
+ set(providerId: string, configuration: ProviderEndpointConfiguration): Promise<void>;
187
+ delete(providerId: string): Promise<void>;
188
+ }
189
+ //#endregion
190
+ //#region src/contracts.d.ts
191
+ interface ControlOperationOptions {
192
+ readonly signal?: AbortSignal;
193
+ }
194
+ /** Read-only answer to which Providers committed host state still names. */
195
+ interface ProviderReferenceAuthority {
196
+ listReferencedProviderIds(options?: ControlOperationOptions): Promise<readonly string[]>;
197
+ }
198
+ interface SorbetProviderCatalog {
199
+ listCustom(options?: ControlOperationOptions): Promise<readonly CustomProviderDefinition[]>;
200
+ createCustom(input: CreateCustomProviderInput, options?: ControlOperationOptions): Promise<CustomProviderDefinition>;
201
+ updateCustom(providerId: string, input: UpdateCustomProviderInput, options?: ControlOperationOptions): Promise<CustomProviderDefinition>;
202
+ deleteCustom(providerId: string, options?: ControlOperationOptions): Promise<void>;
203
+ applyPersistedEndpoints(): Promise<void>;
204
+ listConfigurable(): readonly ConfigurableProvider[];
205
+ setEndpoint(providerId: string, override: ProviderEndpointOverride): Promise<void>;
206
+ disableEndpoint(providerId: string): Promise<void>;
207
+ refresh(options?: ModelsRefreshOptions): Promise<ModelsRefreshResult>;
208
+ availableModels(providerId?: string): Promise<readonly AvailableAgentModel[]>;
209
+ model(providerId: string, modelId: string): Model<Api>;
210
+ }
211
+ interface SorbetProviderRuntime {
212
+ readonly credentials: CredentialStore;
213
+ readonly models: Models;
214
+ readonly catalog: SorbetProviderCatalog;
215
+ login(providerId: string, type: AuthType, interaction: AuthInteraction, options?: ControlOperationOptions): Promise<Credential>;
216
+ refresh(options?: ModelsRefreshOptions): Promise<ModelsRefreshResult>;
217
+ }
218
+ interface CreateSorbetProviderRuntimeOptions {
219
+ readonly dataDirectory: string;
220
+ readonly credentialStore?: CredentialStore;
221
+ readonly customProviderStore?: CustomProviderStore;
222
+ readonly providerEndpointStore?: ProviderEndpointStore;
223
+ readonly createModels?: (context: {
224
+ readonly credentials: CredentialStore;
225
+ }) => MutableModels | Promise<MutableModels>;
226
+ readonly createId?: () => string;
227
+ readonly references?: ProviderReferenceAuthority;
228
+ }
229
+ interface SorbetControl {
230
+ readonly dataDirectory: string;
231
+ readonly authentication: {
232
+ methods(options?: ControlOperationOptions): Promise<readonly {
233
+ readonly providerId: string;
234
+ readonly providerName: string;
235
+ readonly type: AuthType;
236
+ readonly name: string;
237
+ }[]>;
238
+ login(input: {
239
+ readonly providerId: string;
240
+ readonly type: AuthType;
241
+ readonly interaction: AuthInteraction;
242
+ readonly signal?: AbortSignal;
243
+ }): Promise<void>;
244
+ };
245
+ readonly credentials: {
246
+ list(options?: ControlOperationOptions): Promise<readonly {
247
+ readonly providerId: string;
248
+ readonly type: 'api_key' | 'oauth';
249
+ }[]>;
250
+ logout(providerId: string, options?: ControlOperationOptions): Promise<void>;
251
+ };
252
+ readonly providers: {
253
+ listCustom(options?: ControlOperationOptions): Promise<readonly CustomProviderDefinition[]>;
254
+ createCustom(input: CreateCustomProviderInput, options?: ControlOperationOptions): Promise<CustomProviderDefinition>;
255
+ updateCustom(providerId: string, input: UpdateCustomProviderInput, options?: ControlOperationOptions): Promise<CustomProviderDefinition>;
256
+ deleteCustom(providerId: string, options?: ControlOperationOptions): Promise<void>;
257
+ /**
258
+ * Rediscovers models for dynamic Providers (custom + `radius`). Pass
259
+ * `providers: ['id']` in options to refresh one; static built-ins are skipped.
260
+ */
261
+ refresh(options?: ModelsRefreshOptions): Promise<ModelsRefreshResult>;
262
+ /**
263
+ * Models a Host agent may select, across built-in and discovered catalogs.
264
+ * Pass `providerId` to list one Provider's models.
265
+ */
266
+ availableModels(options?: ControlOperationOptions & {
267
+ readonly providerId?: string;
268
+ }): Promise<readonly AvailableAgentModel[]>;
269
+ /** Built-in and custom Providers whose endpoint may be overridden. */
270
+ listConfigurable(options?: ControlOperationOptions): Promise<readonly ConfigurableProvider[]>;
271
+ /** Overrides one Provider endpoint; only the non-secret address is persisted. */
272
+ setEndpoint(providerId: string, override: ProviderEndpointOverride, options?: ControlOperationOptions): Promise<void>;
273
+ /** Clears one Provider's endpoint override and its persisted entry. */
274
+ disableEndpoint(providerId: string, options?: ControlOperationOptions): Promise<void>;
275
+ };
276
+ readonly compatibility: SorbetControlCompatibility;
277
+ installationId(): Promise<string>;
278
+ close(): Promise<void>;
279
+ }
280
+ //#endregion
281
+ //#region src/control.d.ts
282
+ interface OpenSorbetControlOptions {
283
+ /** Defaults to `SORBET_DATA_DIR`, then `~/.sorbet`. */
284
+ readonly dataDirectory?: string;
285
+ /** Aborts initialization. Admitted control operations run to their real outcome. */
286
+ readonly signal?: AbortSignal;
287
+ }
288
+ interface OpenComposedSorbetControlOptions extends OpenSorbetControlOptions, Omit<CreateSorbetProviderRuntimeOptions, 'dataDirectory'> {}
289
+ /**
290
+ * Opens the local control plane for one Sorbet data directory.
291
+ *
292
+ * Only control-plane resources are initialized: Provider stores, the models.dev
293
+ * catalog, the mutable Provider registry, and the installation identity. No
294
+ * Sessions, tools, plugins, MCP connections, sandboxing, or the durable
295
+ * executor are started.
296
+ *
297
+ * The opening signal only cancels initialization. Once a control operation is
298
+ * admitted, it settles to its real outcome rather than reporting an abort that
299
+ * could imply an atomic write did not occur.
300
+ */
301
+ declare function openSorbetControl(options?: OpenSorbetControlOptions): Promise<SorbetControl>;
302
+ /** Composition entry for Sorbet hosts that supply Provider stores or a Pi registry. */
303
+ declare function openComposedSorbetControl(options: OpenComposedSorbetControlOptions): Promise<SorbetControl>;
304
+ //#endregion
305
+ export { ProviderProtocol as A, PersistedProviderEndpoint as C, ProviderEndpointOverride as D, ProviderEndpointConfigurationSchema as E, SorbetControlCompatibility as F, AvailableAgentModel as I, encodeModelSelector as L, UpdateCustomProviderInput as M, UpdateCustomProviderInputSchema as N, ProviderEndpointOverrideSchema as O, SORBET_CONTROL_COMPATIBILITY as P, CustomProviderStore as S, ProviderEndpointConfigurationProperties as T, CustomProviderModel as _, ControlOperationOptions as a, CustomProviderProtocol as b, SorbetControl as c, ConfigurableProvider as d, ConfigurableProviderSchema as f, CustomProviderDefinitionSchema as g, CustomProviderDefinition as h, openSorbetControl as i, ProviderProtocolSchema as j, ProviderEndpointStore as k, SorbetProviderCatalog as l, CreateCustomProviderInputSchema as m, OpenSorbetControlOptions as n, CreateSorbetProviderRuntimeOptions as o, CreateCustomProviderInput as p, openComposedSorbetControl as r, ProviderReferenceAuthority as s, OpenComposedSorbetControlOptions as t, SorbetProviderRuntime as u, CustomProviderModelProperties as v, ProviderEndpointConfiguration as w, CustomProviderProtocolSchema as x, CustomProviderModelSchema as y };
306
+ //# sourceMappingURL=control-NCdUIEUB.d.ts.map