@sorbetai/plugins 0.0.0-stage → 0.1.0-alpha.16
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/README.md +1179 -2
- package/dist/LICENSE.worker.acorn +21 -0
- package/dist/LICENSE.worker.acorn-walk +21 -0
- package/dist/LICENSE.worker.effect +21 -0
- package/dist/LICENSE.worker.ensure-error +9 -0
- package/dist/LICENSE.worker.es-toolkit +21 -0
- package/dist/LICENSE.worker.pi-schema.typebox +23 -0
- package/dist/authority-BWlX47zt.d.ts +547 -0
- package/dist/authority-Ci--C1Np.js +4667 -0
- package/dist/context-i4UGSmNB.d.ts +1326 -0
- package/dist/data-schema-CHZWAtoX.js +185 -0
- package/dist/facet-C9IwWGl5.d.ts +178 -0
- package/dist/index-NehD_iIX.d.ts +610 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +1400 -0
- package/dist/isolate-worker.d.mts +1 -0
- package/dist/isolate-worker.mjs +180791 -0
- package/dist/model.d.ts +27 -0
- package/dist/model.js +274 -0
- package/dist/node.d.ts +273 -0
- package/dist/node.js +2844 -0
- package/dist/object-borrow-C81Gj5tq.js +488 -0
- package/dist/object-invocation-DC6PCiFY.js +15 -0
- package/dist/object-invocation-DMnRagqW.d.ts +13 -0
- package/dist/object-method-Bs7hYSjS.js +69 -0
- package/dist/objects-DdioT9PR.js +113 -0
- package/dist/remote.d.ts +39 -0
- package/dist/remote.js +899 -0
- package/dist/run-yield-B1AE7-PN.js +16 -0
- package/dist/source-Ns6MY6kd.d.ts +214 -0
- package/dist/view-Cn9jz2Wx.js +73 -0
- package/package.json +53 -3
|
@@ -0,0 +1,1326 @@
|
|
|
1
|
+
import * as s from "@earendil-works/pi-schema";
|
|
2
|
+
import * as _sorbetai_schema76 from "@sorbetai/schema";
|
|
3
|
+
import * as _sorbetai_context0 from "@sorbetai/context";
|
|
4
|
+
import { ContextHistorySelector, ContextHistorySnapshot, ContextPreparationDraft, ContextPreparationHook, ContextPreparationResult, ContextPreparationScope, JsonValue, ModelContext, ReadonlyJsonValue, ToolDeclaration } from "@sorbetai/context";
|
|
5
|
+
import * as Context from "effect/Context";
|
|
6
|
+
import * as Effect from "effect/Effect";
|
|
7
|
+
import * as Scope from "effect/Scope";
|
|
8
|
+
import * as Stream from "effect/Stream";
|
|
9
|
+
|
|
10
|
+
//#region src/contributions/session-behavior.d.ts
|
|
11
|
+
declare const SessionBehaviorViewSchema: s.Schema<{
|
|
12
|
+
active: boolean;
|
|
13
|
+
contextState?: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null | undefined;
|
|
14
|
+
constraints?: {
|
|
15
|
+
toolNames: string[];
|
|
16
|
+
workspace?: "read-only" | undefined;
|
|
17
|
+
} | undefined;
|
|
18
|
+
instructions?: string | undefined;
|
|
19
|
+
checklist?: {
|
|
20
|
+
content: string;
|
|
21
|
+
status: "pending" | "in_progress" | "completed";
|
|
22
|
+
}[] | undefined;
|
|
23
|
+
decision?: {
|
|
24
|
+
id: string;
|
|
25
|
+
title: string;
|
|
26
|
+
markdown: string;
|
|
27
|
+
choices: {
|
|
28
|
+
id: string;
|
|
29
|
+
title: string;
|
|
30
|
+
}[];
|
|
31
|
+
} | undefined;
|
|
32
|
+
continuation?: {
|
|
33
|
+
id: string;
|
|
34
|
+
prompt: string;
|
|
35
|
+
} | undefined;
|
|
36
|
+
}>;
|
|
37
|
+
declare const SessionBehaviorMetadataSchema: s.Schema<{
|
|
38
|
+
contributionId: string;
|
|
39
|
+
name: string;
|
|
40
|
+
title: string;
|
|
41
|
+
stateSchema: Record<string, JsonValue>;
|
|
42
|
+
initialState?: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null | undefined;
|
|
43
|
+
initialView?: {
|
|
44
|
+
active: boolean;
|
|
45
|
+
contextState?: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null | undefined;
|
|
46
|
+
constraints?: {
|
|
47
|
+
toolNames: string[];
|
|
48
|
+
workspace?: "read-only" | undefined;
|
|
49
|
+
} | undefined;
|
|
50
|
+
instructions?: string | undefined;
|
|
51
|
+
checklist?: {
|
|
52
|
+
content: string;
|
|
53
|
+
status: "pending" | "in_progress" | "completed";
|
|
54
|
+
}[] | undefined;
|
|
55
|
+
decision?: {
|
|
56
|
+
id: string;
|
|
57
|
+
title: string;
|
|
58
|
+
markdown: string;
|
|
59
|
+
choices: {
|
|
60
|
+
id: string;
|
|
61
|
+
title: string;
|
|
62
|
+
}[];
|
|
63
|
+
} | undefined;
|
|
64
|
+
continuation?: {
|
|
65
|
+
id: string;
|
|
66
|
+
prompt: string;
|
|
67
|
+
} | undefined;
|
|
68
|
+
} | undefined;
|
|
69
|
+
}>;
|
|
70
|
+
type SessionBehaviorView = s.Static<typeof SessionBehaviorViewSchema>;
|
|
71
|
+
type SessionBehaviorMetadata = s.Static<typeof SessionBehaviorMetadataSchema>;
|
|
72
|
+
declare const SessionBehaviorCommandSchema: s.Schema<{
|
|
73
|
+
name: string;
|
|
74
|
+
input: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null;
|
|
75
|
+
}>;
|
|
76
|
+
type SessionBehaviorCommand = s.Static<typeof SessionBehaviorCommandSchema>;
|
|
77
|
+
interface SessionBehaviorScope {
|
|
78
|
+
readonly sessionId: string;
|
|
79
|
+
readonly runId?: string;
|
|
80
|
+
readonly operationId: string;
|
|
81
|
+
}
|
|
82
|
+
/** Pure synchronous transitions over detached JSON; only Runtime may commit the replacement. */
|
|
83
|
+
interface SessionBehaviorContribution extends Omit<SessionBehaviorMetadata, 'stateSchema' | 'initialView'> {
|
|
84
|
+
readonly stateSchema: s.Schema;
|
|
85
|
+
reduce(state: JsonValue, command: SessionBehaviorCommand, scope: SessionBehaviorScope): JsonValue;
|
|
86
|
+
project(state: JsonValue): SessionBehaviorView;
|
|
87
|
+
}
|
|
88
|
+
/** Invocation-scoped authority; it cannot address another Session. */
|
|
89
|
+
type SessionBehaviorDispatch = (name: string, command: SessionBehaviorCommand, signal?: AbortSignal) => Promise<SessionBehaviorView>;
|
|
90
|
+
//#endregion
|
|
91
|
+
//#region src/contributions/commands.d.ts
|
|
92
|
+
interface PluginCommandInput {
|
|
93
|
+
readonly arguments: string;
|
|
94
|
+
readonly source?: JsonValue;
|
|
95
|
+
}
|
|
96
|
+
interface PluginCommandContext {
|
|
97
|
+
readonly sessionId: string;
|
|
98
|
+
readonly signal: AbortSignal;
|
|
99
|
+
/** Bound to this registration's own Session; cannot change Run authority. */
|
|
100
|
+
readonly commandBehavior?: SessionBehaviorDispatch;
|
|
101
|
+
}
|
|
102
|
+
interface PluginCommandResult {
|
|
103
|
+
readonly text: string;
|
|
104
|
+
readonly details?: JsonValue;
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* A human-facing slash command. Registration is implemented as a hidden Tool
|
|
108
|
+
* carrying `sorbet.dev/slash-command`, so it uses the existing command directory,
|
|
109
|
+
* permissions, Effect boundary and selection/conflict handling.
|
|
110
|
+
*/
|
|
111
|
+
interface PluginCommandRegistration {
|
|
112
|
+
/** Stable within this Plugin instance. Defaults to the command name. */
|
|
113
|
+
readonly key?: string;
|
|
114
|
+
readonly name: string;
|
|
115
|
+
readonly description: string;
|
|
116
|
+
readonly argumentHint?: string;
|
|
117
|
+
execute(input: PluginCommandInput, context: PluginCommandContext): Promise<PluginCommandResult> | PluginCommandResult;
|
|
118
|
+
}
|
|
119
|
+
//#endregion
|
|
120
|
+
//#region src/contributions/observation.d.ts
|
|
121
|
+
type PluginExecutionProfile = 'isolate' | 'in_process' | 'native_pi' | 'native_cordis';
|
|
122
|
+
interface PluginNativeLifecycleObservation {
|
|
123
|
+
readonly activationId?: string;
|
|
124
|
+
readonly profile: 'native_pi' | 'native_cordis';
|
|
125
|
+
readonly phase: 'active' | 'stopping' | 'native-settled' | 'released' | 'uncertain';
|
|
126
|
+
readonly backend: 'unverified' | 'pending' | 'drained';
|
|
127
|
+
readonly durationMs?: number;
|
|
128
|
+
readonly startedAtUnixMs?: number;
|
|
129
|
+
readonly endedAtUnixMs?: number;
|
|
130
|
+
}
|
|
131
|
+
interface PluginNativeInvocationObservation {
|
|
132
|
+
readonly kind?: 'tool' | 'pipeline' | 'command';
|
|
133
|
+
readonly queueWaitMs?: number;
|
|
134
|
+
readonly activationId?: string;
|
|
135
|
+
readonly profile: 'native_pi' | 'native_cordis';
|
|
136
|
+
readonly sessionId: string;
|
|
137
|
+
readonly runId?: string;
|
|
138
|
+
readonly toolCallId?: string;
|
|
139
|
+
readonly outcome: 'succeeded' | 'failed' | 'cancelled';
|
|
140
|
+
readonly durationMs: number;
|
|
141
|
+
readonly startedAtUnixMs: number;
|
|
142
|
+
readonly endedAtUnixMs: number;
|
|
143
|
+
}
|
|
144
|
+
interface PluginNativeObservationPort {
|
|
145
|
+
readonly nativeInvocationStarted?: (data: Pick<PluginNativeInvocationObservation, 'activationId' | 'profile' | 'kind' | 'sessionId' | 'runId' | 'toolCallId'>) => void;
|
|
146
|
+
readonly nativeDependenciesChanged?: (data: {
|
|
147
|
+
readonly activationId?: string;
|
|
148
|
+
readonly profile: 'native_cordis';
|
|
149
|
+
readonly counts: Readonly<Record<'pending' | 'loading' | 'active' | 'failed' | 'disposed' | 'unloading', number>>;
|
|
150
|
+
}) => void;
|
|
151
|
+
readonly nativeLifecycle?: (data: PluginNativeLifecycleObservation) => void;
|
|
152
|
+
readonly nativeInvocationSettled?: (data: PluginNativeInvocationObservation) => void;
|
|
153
|
+
}
|
|
154
|
+
//#endregion
|
|
155
|
+
//#region src/contributions/mount-status.d.ts
|
|
156
|
+
interface PluginMountStatus {
|
|
157
|
+
readonly profile?: PluginExecutionProfile;
|
|
158
|
+
readonly path: readonly string[];
|
|
159
|
+
readonly phase: 'active' | 'failed' | 'pending' | 'removed';
|
|
160
|
+
readonly pendingReason?: 'retiring' | 'admission' | 'dependency-cycle';
|
|
161
|
+
/** Each path waits for a Service supplied by the next path, wrapping to the first. */
|
|
162
|
+
readonly dependencyCycle?: readonly {
|
|
163
|
+
readonly path: readonly string[];
|
|
164
|
+
readonly service: string;
|
|
165
|
+
}[];
|
|
166
|
+
readonly missingServices?: readonly string[];
|
|
167
|
+
readonly conflictingServices?: readonly string[];
|
|
168
|
+
readonly activationId?: string;
|
|
169
|
+
readonly error?: string;
|
|
170
|
+
}
|
|
171
|
+
//#endregion
|
|
172
|
+
//#region src/contributions/session-model.d.ts
|
|
173
|
+
interface PluginModelUsage {
|
|
174
|
+
readonly input: number;
|
|
175
|
+
readonly output: number;
|
|
176
|
+
readonly cacheRead: number;
|
|
177
|
+
readonly cacheWrite: number;
|
|
178
|
+
readonly totalTokens: number;
|
|
179
|
+
readonly reasoning?: number;
|
|
180
|
+
readonly cacheWrite1h?: number;
|
|
181
|
+
readonly cost: {
|
|
182
|
+
readonly input: number;
|
|
183
|
+
readonly output: number;
|
|
184
|
+
readonly cacheRead: number;
|
|
185
|
+
readonly cacheWrite: number;
|
|
186
|
+
readonly total: number;
|
|
187
|
+
};
|
|
188
|
+
}
|
|
189
|
+
interface PluginCompleteModelRequest {
|
|
190
|
+
readonly purpose: string;
|
|
191
|
+
/**
|
|
192
|
+
* Provider-ready input dispatched as-is, including its Tool declarations. A
|
|
193
|
+
* supplied Context takes precedence over `system` and `messages`; returned Tool
|
|
194
|
+
* calls stay response data and are never executed.
|
|
195
|
+
*/
|
|
196
|
+
readonly context?: ModelContext;
|
|
197
|
+
readonly system?: string;
|
|
198
|
+
readonly messages?: readonly {
|
|
199
|
+
readonly role: 'user' | 'assistant';
|
|
200
|
+
readonly content: string;
|
|
201
|
+
}[];
|
|
202
|
+
/** Resolved only within the Models collection authorized by the Host. */
|
|
203
|
+
readonly model?: {
|
|
204
|
+
readonly provider: string;
|
|
205
|
+
readonly id: string;
|
|
206
|
+
};
|
|
207
|
+
readonly maxOutputTokens?: number;
|
|
208
|
+
}
|
|
209
|
+
interface PluginModelForkRequest {
|
|
210
|
+
readonly purpose: string;
|
|
211
|
+
readonly responseMessageId: string;
|
|
212
|
+
readonly prompt: string;
|
|
213
|
+
readonly model?: PluginCompleteModelRequest['model'];
|
|
214
|
+
readonly maxOutputTokens?: number;
|
|
215
|
+
}
|
|
216
|
+
interface PluginModelInvocationReceipt {
|
|
217
|
+
readonly requestId: string;
|
|
218
|
+
readonly text: string;
|
|
219
|
+
readonly usage: PluginModelUsage;
|
|
220
|
+
readonly stopReason: string;
|
|
221
|
+
/** The Provider's or a hook's failure when `stopReason` is `error` or `aborted`. */
|
|
222
|
+
readonly errorMessage?: string;
|
|
223
|
+
readonly model: {
|
|
224
|
+
readonly provider: string;
|
|
225
|
+
readonly id: string;
|
|
226
|
+
};
|
|
227
|
+
}
|
|
228
|
+
/** The Provider model a hook runs for; `api` names its wire format, e.g. `anthropic-messages`. */
|
|
229
|
+
interface PluginProviderModel {
|
|
230
|
+
readonly provider: string;
|
|
231
|
+
readonly api: string;
|
|
232
|
+
readonly id: string;
|
|
233
|
+
/** The endpoint this request goes to, after any Host endpoint override. */
|
|
234
|
+
readonly baseUrl: string;
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* Provider-level hooks for one completion. They see the Provider's own wire shapes, so a
|
|
238
|
+
* Plugin can enable a Provider feature Sorbet does not model, such as hosted web search,
|
|
239
|
+
* and read what that feature streams back. Request evidence records Sorbet's input, not
|
|
240
|
+
* the rewritten payload.
|
|
241
|
+
*/
|
|
242
|
+
interface PluginProviderHooks {
|
|
243
|
+
/** Returns a replacement payload, or `undefined` to send it unchanged. */
|
|
244
|
+
readonly prepare?: (payload: unknown, model: PluginProviderModel) => unknown;
|
|
245
|
+
/** Reads each raw Provider stream event before normalization; events are read-only. */
|
|
246
|
+
readonly observe?: (event: unknown, model: PluginProviderModel) => void;
|
|
247
|
+
}
|
|
248
|
+
/** One completion with durable request evidence, without an implicit Agent/tool loop. */
|
|
249
|
+
interface PluginSessionModelPort {
|
|
250
|
+
complete(request: PluginCompleteModelRequest, options?: {
|
|
251
|
+
readonly signal?: AbortSignal;
|
|
252
|
+
readonly provider?: PluginProviderHooks;
|
|
253
|
+
}): Promise<PluginModelInvocationReceipt>;
|
|
254
|
+
/** Appends one prompt to the latest committed answer using its model and settings by default. */
|
|
255
|
+
fork?(request: PluginModelForkRequest, options?: {
|
|
256
|
+
readonly signal?: AbortSignal;
|
|
257
|
+
}): Promise<(PluginModelInvocationReceipt & {
|
|
258
|
+
readonly sourceModelRequestId: string;
|
|
259
|
+
}) | undefined>;
|
|
260
|
+
}
|
|
261
|
+
//#endregion
|
|
262
|
+
//#region src/contributions/session.d.ts
|
|
263
|
+
interface PluginSessionActor {
|
|
264
|
+
/** Stable Platform scope and Entry path, with each identity component URI-escaped. */
|
|
265
|
+
readonly entryId: string;
|
|
266
|
+
readonly activationId: string;
|
|
267
|
+
readonly signal: AbortSignal;
|
|
268
|
+
}
|
|
269
|
+
interface PluginSessionFact {
|
|
270
|
+
readonly id: string;
|
|
271
|
+
readonly sessionId: string;
|
|
272
|
+
readonly sequence: number;
|
|
273
|
+
readonly cursor: string;
|
|
274
|
+
readonly recordedAt: number;
|
|
275
|
+
readonly kind: string;
|
|
276
|
+
readonly runId?: string;
|
|
277
|
+
readonly operationId?: string;
|
|
278
|
+
readonly payload: JsonValue;
|
|
279
|
+
}
|
|
280
|
+
interface PluginSessionFactReadOptions {
|
|
281
|
+
readonly after?: string;
|
|
282
|
+
readonly kinds?: readonly string[];
|
|
283
|
+
readonly limit?: number;
|
|
284
|
+
}
|
|
285
|
+
interface PluginSessionFactsPort {
|
|
286
|
+
read(input?: PluginSessionFactReadOptions, options?: {
|
|
287
|
+
readonly signal?: AbortSignal;
|
|
288
|
+
}): Promise<{
|
|
289
|
+
readonly facts: readonly PluginSessionFact[];
|
|
290
|
+
readonly cursor?: string;
|
|
291
|
+
readonly hasMore: boolean;
|
|
292
|
+
}>;
|
|
293
|
+
/** Follow continues from a durable cursor; consumers may receive facts more than once. */
|
|
294
|
+
follow(input?: Omit<PluginSessionFactReadOptions, 'limit'>, options?: {
|
|
295
|
+
readonly signal?: AbortSignal;
|
|
296
|
+
}): AsyncIterable<PluginSessionFact>;
|
|
297
|
+
}
|
|
298
|
+
interface PluginSessionRecord {
|
|
299
|
+
readonly id: string;
|
|
300
|
+
readonly sessionId: string;
|
|
301
|
+
readonly sequence: number;
|
|
302
|
+
readonly cursor: string;
|
|
303
|
+
readonly recordedAt: number;
|
|
304
|
+
readonly owner: {
|
|
305
|
+
readonly entryId: string;
|
|
306
|
+
readonly activationId?: string;
|
|
307
|
+
};
|
|
308
|
+
readonly recordType: string;
|
|
309
|
+
readonly recordVersion: number;
|
|
310
|
+
readonly data: JsonValue;
|
|
311
|
+
/** Monotonic within one owner's record type, independently of the Session sequence. */
|
|
312
|
+
readonly revision: number;
|
|
313
|
+
readonly sourceSequence: number;
|
|
314
|
+
readonly idempotencyKey?: string;
|
|
315
|
+
}
|
|
316
|
+
interface PluginSessionRecordAppend {
|
|
317
|
+
readonly recordType: string;
|
|
318
|
+
readonly recordVersion: number;
|
|
319
|
+
readonly data: JsonValue;
|
|
320
|
+
readonly expectedRevision: number;
|
|
321
|
+
readonly sourceSequence: number;
|
|
322
|
+
readonly idempotencyKey?: string;
|
|
323
|
+
}
|
|
324
|
+
interface PluginSessionRecordsPort {
|
|
325
|
+
/** The Runtime supplies owner and commit identity; callers cannot choose either. */
|
|
326
|
+
append(input: PluginSessionRecordAppend, options?: {
|
|
327
|
+
readonly signal?: AbortSignal;
|
|
328
|
+
}): Promise<PluginSessionRecord>;
|
|
329
|
+
read(input?: {
|
|
330
|
+
readonly after?: string;
|
|
331
|
+
readonly recordType?: string;
|
|
332
|
+
readonly limit?: number;
|
|
333
|
+
}, options?: {
|
|
334
|
+
readonly signal?: AbortSignal;
|
|
335
|
+
}): Promise<{
|
|
336
|
+
readonly records: readonly PluginSessionRecord[];
|
|
337
|
+
readonly cursor?: string;
|
|
338
|
+
readonly hasMore: boolean;
|
|
339
|
+
}>;
|
|
340
|
+
}
|
|
341
|
+
type PluginSessionWorkOutcome<Result> = {
|
|
342
|
+
readonly status: 'succeeded';
|
|
343
|
+
readonly value: Result;
|
|
344
|
+
} | {
|
|
345
|
+
readonly status: 'failed';
|
|
346
|
+
readonly error: Error;
|
|
347
|
+
} | {
|
|
348
|
+
readonly status: 'cancelled';
|
|
349
|
+
readonly error: Error;
|
|
350
|
+
};
|
|
351
|
+
interface PluginSessionWorkHandle<Result> {
|
|
352
|
+
readonly settled: Promise<PluginSessionWorkOutcome<Result>>;
|
|
353
|
+
cancel(): void;
|
|
354
|
+
}
|
|
355
|
+
interface PluginSessionWorkPort {
|
|
356
|
+
/** Work is owned by the current Plugin generation and Session, without durable restart. */
|
|
357
|
+
spawn<Result>(task: (signal: AbortSignal) => Promise<Result>): PluginSessionWorkHandle<Result>;
|
|
358
|
+
}
|
|
359
|
+
interface PluginSessionControlPort {
|
|
360
|
+
/** Host adapters decode inputs and enter the resource's existing Runtime admission path. */
|
|
361
|
+
send(input: JsonValue, options?: {
|
|
362
|
+
readonly signal?: AbortSignal;
|
|
363
|
+
}): Promise<JsonValue>;
|
|
364
|
+
/** Appends a non-conversation display write when the Host supports it. */
|
|
365
|
+
write?(input: PluginSessionWriteInput, options?: {
|
|
366
|
+
readonly signal?: AbortSignal;
|
|
367
|
+
}): Promise<JsonValue>;
|
|
368
|
+
cancel?(options?: {
|
|
369
|
+
readonly signal?: AbortSignal;
|
|
370
|
+
}): Promise<void>;
|
|
371
|
+
}
|
|
372
|
+
/**
|
|
373
|
+
* A committed request prefix a Plugin may extend with its own instruction. It is a
|
|
374
|
+
* reconstruction of what Sorbet sent, not a capture of a Provider payload.
|
|
375
|
+
*/
|
|
376
|
+
interface PluginRequestContext {
|
|
377
|
+
/** Provider-ready input; `messages` already include every committed message. */
|
|
378
|
+
readonly context: ModelContext;
|
|
379
|
+
/** The request whose prefix this reuses. */
|
|
380
|
+
readonly sourceModelRequestId: string;
|
|
381
|
+
}
|
|
382
|
+
interface PluginSessionRequestPort {
|
|
383
|
+
/**
|
|
384
|
+
* `undefined` when the Session has no settled request prefix to reuse: no request
|
|
385
|
+
* yet, no committed response, or a later compaction, reset or input rewrite
|
|
386
|
+
* invalidated the prefix.
|
|
387
|
+
*/
|
|
388
|
+
current(options?: {
|
|
389
|
+
readonly signal?: AbortSignal;
|
|
390
|
+
}): Promise<PluginRequestContext | undefined>;
|
|
391
|
+
}
|
|
392
|
+
interface PluginSessionScope {
|
|
393
|
+
readonly sessionId: string;
|
|
394
|
+
readonly signal: AbortSignal;
|
|
395
|
+
readonly facts?: PluginSessionFactsPort;
|
|
396
|
+
readonly records?: PluginSessionRecordsPort;
|
|
397
|
+
readonly request?: PluginSessionRequestPort;
|
|
398
|
+
readonly model?: PluginSessionModelPort;
|
|
399
|
+
readonly work?: PluginSessionWorkPort;
|
|
400
|
+
readonly control?: PluginSessionControlPort;
|
|
401
|
+
}
|
|
402
|
+
interface PluginSessionDirectory {
|
|
403
|
+
/** Resolving an identity grants only the capabilities returned by the Host. */
|
|
404
|
+
bind(sessionId: string, options?: {
|
|
405
|
+
readonly signal?: AbortSignal;
|
|
406
|
+
}): Promise<PluginSessionScope>;
|
|
407
|
+
discover?(): Promise<readonly {
|
|
408
|
+
readonly sessionId: string;
|
|
409
|
+
}[]>;
|
|
410
|
+
create?(input: JsonValue): Promise<PluginSessionScope>;
|
|
411
|
+
}
|
|
412
|
+
/** Called once per activation; Hosts configure each entry's accessible resources and capabilities. */
|
|
413
|
+
type PluginSessionResolver = (actor: PluginSessionActor) => PluginSessionDirectory;
|
|
414
|
+
/** Host-decoded shape for Plugin `ctx.session.control.send`. */
|
|
415
|
+
declare const PluginSessionSendInputSchema: s.Schema<{
|
|
416
|
+
text: string;
|
|
417
|
+
images?: {
|
|
418
|
+
type: "image";
|
|
419
|
+
data: string;
|
|
420
|
+
mimeType: string;
|
|
421
|
+
}[] | undefined;
|
|
422
|
+
deliverAs?: "steer" | "followUp" | undefined;
|
|
423
|
+
}>;
|
|
424
|
+
type PluginSessionSendInput = s.Static<typeof PluginSessionSendInputSchema>;
|
|
425
|
+
declare const PluginSessionWriteInputSchema: s.Schema<{
|
|
426
|
+
text: string;
|
|
427
|
+
}>;
|
|
428
|
+
type PluginSessionWriteInput = s.Static<typeof PluginSessionWriteInputSchema>;
|
|
429
|
+
//#endregion
|
|
430
|
+
//#region src/contributions/tool-declaration.d.ts
|
|
431
|
+
declare const ModelToolMetadataSchema: s.Schema<{
|
|
432
|
+
contributionId: string;
|
|
433
|
+
name: string;
|
|
434
|
+
description: string;
|
|
435
|
+
parameters: Record<string, _sorbetai_schema76.JsonValue>;
|
|
436
|
+
label?: string | undefined;
|
|
437
|
+
outputSchema?: Record<string, _sorbetai_schema76.JsonValue> | undefined;
|
|
438
|
+
discovery?: {
|
|
439
|
+
exposure?: "direct" | "deferred" | "hidden" | undefined;
|
|
440
|
+
namespace?: {
|
|
441
|
+
name: string;
|
|
442
|
+
description?: string | undefined;
|
|
443
|
+
} | undefined;
|
|
444
|
+
} | undefined;
|
|
445
|
+
metadata?: Record<string, _sorbetai_schema76.JsonValue> | undefined;
|
|
446
|
+
}>;
|
|
447
|
+
//#endregion
|
|
448
|
+
//#region src/contributions/tool-result.d.ts
|
|
449
|
+
declare const ToolResultSchema: s.Schema<{
|
|
450
|
+
content: ({
|
|
451
|
+
type: "text";
|
|
452
|
+
text: string;
|
|
453
|
+
} | {
|
|
454
|
+
type: "image";
|
|
455
|
+
data: string;
|
|
456
|
+
mimeType: string;
|
|
457
|
+
})[];
|
|
458
|
+
details: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null;
|
|
459
|
+
structuredContent?: string | number | boolean | readonly ReadonlyJsonValue[] | {
|
|
460
|
+
readonly [key: string]: ReadonlyJsonValue;
|
|
461
|
+
} | null | undefined;
|
|
462
|
+
isError?: boolean | undefined;
|
|
463
|
+
}>;
|
|
464
|
+
type PluginToolResult = s.Static<typeof ToolResultSchema>;
|
|
465
|
+
//#endregion
|
|
466
|
+
//#region src/contributions/tool-hooks.d.ts
|
|
467
|
+
declare const ToolHookMetadataSchema: s.Schema<{
|
|
468
|
+
contributionId: string;
|
|
469
|
+
version?: number | undefined;
|
|
470
|
+
before?: string[] | undefined;
|
|
471
|
+
after?: string[] | undefined;
|
|
472
|
+
}>;
|
|
473
|
+
type ToolHookMetadata = s.Static<typeof ToolHookMetadataSchema>;
|
|
474
|
+
declare const ToolHookFeedbackSchema: s.Schema<{
|
|
475
|
+
isError: boolean;
|
|
476
|
+
content: ({
|
|
477
|
+
type: "text";
|
|
478
|
+
text: string;
|
|
479
|
+
} | {
|
|
480
|
+
type: "image";
|
|
481
|
+
data: string;
|
|
482
|
+
mimeType: string;
|
|
483
|
+
})[];
|
|
484
|
+
details: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null;
|
|
485
|
+
structuredContent?: string | number | boolean | readonly _sorbetai_context0.ReadonlyJsonValue[] | {
|
|
486
|
+
readonly [key: string]: _sorbetai_context0.ReadonlyJsonValue;
|
|
487
|
+
} | null | undefined;
|
|
488
|
+
}>;
|
|
489
|
+
type ToolHookFeedback = s.Static<typeof ToolHookFeedbackSchema>;
|
|
490
|
+
declare const ToolHookPreparationSchema: s.Schema<{
|
|
491
|
+
input: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null;
|
|
492
|
+
state?: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null | undefined;
|
|
493
|
+
} | {
|
|
494
|
+
block: true;
|
|
495
|
+
reason: string;
|
|
496
|
+
} | {
|
|
497
|
+
respond: {
|
|
498
|
+
isError: boolean;
|
|
499
|
+
content: ({
|
|
500
|
+
type: "text";
|
|
501
|
+
text: string;
|
|
502
|
+
} | {
|
|
503
|
+
type: "image";
|
|
504
|
+
data: string;
|
|
505
|
+
mimeType: string;
|
|
506
|
+
})[];
|
|
507
|
+
details: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null;
|
|
508
|
+
structuredContent?: string | number | boolean | readonly _sorbetai_context0.ReadonlyJsonValue[] | {
|
|
509
|
+
readonly [key: string]: _sorbetai_context0.ReadonlyJsonValue;
|
|
510
|
+
} | null | undefined;
|
|
511
|
+
};
|
|
512
|
+
input: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null;
|
|
513
|
+
}>;
|
|
514
|
+
type ToolHookPreparation = s.Static<typeof ToolHookPreparationSchema>;
|
|
515
|
+
declare const PreparedToolHooksSchema: s.Schema<{
|
|
516
|
+
input: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null;
|
|
517
|
+
steps: {
|
|
518
|
+
contributionId: string;
|
|
519
|
+
version: number;
|
|
520
|
+
state: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null;
|
|
521
|
+
}[];
|
|
522
|
+
outcome: {
|
|
523
|
+
kind: "execute";
|
|
524
|
+
} | {
|
|
525
|
+
kind: "block";
|
|
526
|
+
contributionId: string;
|
|
527
|
+
reason: string;
|
|
528
|
+
} | {
|
|
529
|
+
kind: "respond";
|
|
530
|
+
contributionId: string;
|
|
531
|
+
result: {
|
|
532
|
+
isError: boolean;
|
|
533
|
+
content: ({
|
|
534
|
+
type: "text";
|
|
535
|
+
text: string;
|
|
536
|
+
} | {
|
|
537
|
+
type: "image";
|
|
538
|
+
data: string;
|
|
539
|
+
mimeType: string;
|
|
540
|
+
})[];
|
|
541
|
+
details: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null;
|
|
542
|
+
structuredContent?: string | number | boolean | readonly _sorbetai_context0.ReadonlyJsonValue[] | {
|
|
543
|
+
readonly [key: string]: _sorbetai_context0.ReadonlyJsonValue;
|
|
544
|
+
} | null | undefined;
|
|
545
|
+
};
|
|
546
|
+
};
|
|
547
|
+
}>;
|
|
548
|
+
type PreparedToolHooks = s.Static<typeof PreparedToolHooksSchema>;
|
|
549
|
+
interface ToolHookContext {
|
|
550
|
+
/** Captured from lease acquisition, not supplied by the Tool caller; metadata, not authority. */
|
|
551
|
+
readonly sessionId: string;
|
|
552
|
+
readonly runId?: string;
|
|
553
|
+
readonly operationId?: string;
|
|
554
|
+
readonly source?: JsonValue;
|
|
555
|
+
readonly toolName: string;
|
|
556
|
+
readonly toolCallId: string;
|
|
557
|
+
readonly signal: AbortSignal;
|
|
558
|
+
}
|
|
559
|
+
interface ToolHookContribution extends ToolHookMetadata {
|
|
560
|
+
/** Runs before authorization. Return JSON state needed by feedback; never retain a continuation.
|
|
561
|
+
* Preparation may repeat only if its checkpoint was not committed. Both phases must be
|
|
562
|
+
* repeatable data transformations; external effects require a separate authorized operation.
|
|
563
|
+
*/
|
|
564
|
+
prepare?(input: JsonValue, context: ToolHookContext): Promise<ToolHookPreparation>;
|
|
565
|
+
/** Runs in reverse order against a committed result. A failure never re-executes the Tool.
|
|
566
|
+
* Bump metadata version when changing persisted state or feedback semantics incompatibly.
|
|
567
|
+
* Missing state is null. Blocked/denied/cancelled/unknown attempts do not enter feedback.
|
|
568
|
+
*/
|
|
569
|
+
feedback?(result: ToolHookFeedback, state: JsonValue, context: ToolHookContext): Promise<ToolHookFeedback>;
|
|
570
|
+
}
|
|
571
|
+
/** Trusted domain finalization ports, never exposed to Hook authors. */
|
|
572
|
+
interface ToolHookContinuation {
|
|
573
|
+
/** The Effect owner disables feedback processing for an uncertain outcome. */
|
|
574
|
+
canProcessFeedback?(): boolean;
|
|
575
|
+
execute(input: JsonValue): Promise<ToolHookFeedback>;
|
|
576
|
+
respond(input: JsonValue, result: ToolHookFeedback, contributionId: string): Promise<ToolHookFeedback>;
|
|
577
|
+
block(reason: string, contributionId: string): Promise<ToolHookFeedback>;
|
|
578
|
+
}
|
|
579
|
+
//#endregion
|
|
580
|
+
//#region src/contributions/tool-observation.d.ts
|
|
581
|
+
declare const ToolResultObservationSchema: s.Schema<{
|
|
582
|
+
factId: string;
|
|
583
|
+
sequence: number;
|
|
584
|
+
runId: string;
|
|
585
|
+
toolCallId: string;
|
|
586
|
+
toolName: string;
|
|
587
|
+
isError: boolean;
|
|
588
|
+
details: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null;
|
|
589
|
+
}>;
|
|
590
|
+
/** Committed feedback, not proof of external Effect success or live filesystem state. */
|
|
591
|
+
type PluginToolResultObservation = Readonly<s.Static<typeof ToolResultObservationSchema>>;
|
|
592
|
+
interface PluginToolResultSnapshot {
|
|
593
|
+
readonly sessionId: string;
|
|
594
|
+
readonly throughSequence: number;
|
|
595
|
+
readonly cursor?: string;
|
|
596
|
+
readonly results: readonly PluginToolResultObservation[];
|
|
597
|
+
}
|
|
598
|
+
//#endregion
|
|
599
|
+
//#region src/contributions/named-state.d.ts
|
|
600
|
+
declare const PluginStateReadResultSchema: s.Schema<{
|
|
601
|
+
present: true;
|
|
602
|
+
value: string | number | boolean | _sorbetai_schema76.JsonArray | _sorbetai_schema76.JsonObject | null;
|
|
603
|
+
element: {
|
|
604
|
+
kind: "text";
|
|
605
|
+
name: string;
|
|
606
|
+
attributes?: Record<string, string | number>;
|
|
607
|
+
text: string;
|
|
608
|
+
} | {
|
|
609
|
+
kind: "container";
|
|
610
|
+
name: string;
|
|
611
|
+
attributes?: Record<string, string | number>;
|
|
612
|
+
children: _sorbetai_context0.ContextXmlElement[];
|
|
613
|
+
};
|
|
614
|
+
} | {
|
|
615
|
+
present: false;
|
|
616
|
+
}>;
|
|
617
|
+
type PluginStateReadResult = s.Static<typeof PluginStateReadResultSchema>;
|
|
618
|
+
interface PluginStateReadContext {
|
|
619
|
+
/** Public request metadata only; grants no execution authority. */
|
|
620
|
+
readonly toolCatalog?: readonly ToolDeclaration[];
|
|
621
|
+
readonly sessionId: string;
|
|
622
|
+
readonly runId: string;
|
|
623
|
+
readonly signal: AbortSignal;
|
|
624
|
+
/** Fixed committed prefix for this request; absent when the execution consumer cannot supply it. */
|
|
625
|
+
readonly toolResults?: PluginToolResultSnapshot;
|
|
626
|
+
}
|
|
627
|
+
/** Current model-visible data, not a private-state persistence or Session mutation port. */
|
|
628
|
+
interface PluginNamedStateContribution {
|
|
629
|
+
readonly contributionId: string;
|
|
630
|
+
readonly stateName: string;
|
|
631
|
+
readonly schema: s.Schema;
|
|
632
|
+
/** Called for new logical requests only. Partition Session-specific data by sessionId. */
|
|
633
|
+
read(context: PluginStateReadContext): Promise<PluginStateReadResult>;
|
|
634
|
+
}
|
|
635
|
+
//#endregion
|
|
636
|
+
//#region src/contributions/prefix.d.ts
|
|
637
|
+
declare const PluginPrefixContributionSchema: s.Schema<{
|
|
638
|
+
contributionId: string;
|
|
639
|
+
content: string;
|
|
640
|
+
}>;
|
|
641
|
+
/** Fixed definitions copied into request views; replace the registration to change them. */
|
|
642
|
+
type PluginPrefixContribution = Readonly<s.Static<typeof PluginPrefixContributionSchema>>;
|
|
643
|
+
//#endregion
|
|
644
|
+
//#region src/contributions/input-transform.d.ts
|
|
645
|
+
declare const PluginInputSchema: s.Schema<string | ({
|
|
646
|
+
type: "text";
|
|
647
|
+
text: string;
|
|
648
|
+
textSignature?: string | undefined;
|
|
649
|
+
} | {
|
|
650
|
+
type: "image";
|
|
651
|
+
data: string;
|
|
652
|
+
mimeType: string;
|
|
653
|
+
})[]>;
|
|
654
|
+
type PluginInput = s.Static<typeof PluginInputSchema>;
|
|
655
|
+
interface PluginInputTransform {
|
|
656
|
+
readonly contributionId: string;
|
|
657
|
+
/** Return effective admitted input; never mutate admission authority. */
|
|
658
|
+
transform(input: PluginInput, context: {
|
|
659
|
+
readonly sessionId: string;
|
|
660
|
+
readonly runId: string;
|
|
661
|
+
readonly source: JsonValue;
|
|
662
|
+
readonly mode: 'initial' | 'steer' | 'followUp';
|
|
663
|
+
readonly signal: AbortSignal;
|
|
664
|
+
}): Promise<PluginInput>;
|
|
665
|
+
}
|
|
666
|
+
//#endregion
|
|
667
|
+
//#region src/contributions/compaction.d.ts
|
|
668
|
+
interface PluginCompactionModel {
|
|
669
|
+
readonly provider: string;
|
|
670
|
+
readonly id: string;
|
|
671
|
+
readonly api: string;
|
|
672
|
+
readonly contextWindow: number;
|
|
673
|
+
readonly maxTokens: number;
|
|
674
|
+
readonly cost: {
|
|
675
|
+
readonly input: number;
|
|
676
|
+
readonly cacheRead: number;
|
|
677
|
+
readonly tiers?: readonly {
|
|
678
|
+
readonly inputTokensAbove: number;
|
|
679
|
+
readonly input: number;
|
|
680
|
+
readonly cacheRead: number;
|
|
681
|
+
}[];
|
|
682
|
+
};
|
|
683
|
+
}
|
|
684
|
+
interface PluginCompactionSettings {
|
|
685
|
+
readonly enabled: boolean;
|
|
686
|
+
readonly reserveTokens: number;
|
|
687
|
+
readonly keepRecentTokens: number;
|
|
688
|
+
readonly summaryMaxOutputTokens?: number;
|
|
689
|
+
readonly instructions?: string;
|
|
690
|
+
}
|
|
691
|
+
interface PluginCompactionTrigger {
|
|
692
|
+
readonly sessionId: string;
|
|
693
|
+
readonly runId?: string;
|
|
694
|
+
readonly reason: 'threshold' | 'overflow' | 'manual';
|
|
695
|
+
readonly model: PluginCompactionModel;
|
|
696
|
+
readonly settings: PluginCompactionSettings;
|
|
697
|
+
readonly contextTokens: number;
|
|
698
|
+
readonly contextWindow: number;
|
|
699
|
+
readonly signal: AbortSignal;
|
|
700
|
+
}
|
|
701
|
+
interface PluginCompactionPolicyRegistration {
|
|
702
|
+
readonly key: string;
|
|
703
|
+
readonly version?: number;
|
|
704
|
+
shouldCompact(input: PluginCompactionTrigger): boolean | Promise<boolean>;
|
|
705
|
+
}
|
|
706
|
+
interface PluginCompactionPolicyContribution extends PluginCompactionPolicyRegistration {
|
|
707
|
+
readonly contributionId: string;
|
|
708
|
+
readonly version: number;
|
|
709
|
+
readonly entryId?: string;
|
|
710
|
+
readonly activationId?: string;
|
|
711
|
+
}
|
|
712
|
+
interface PluginCompactionCompileInput extends PluginCompactionTrigger {
|
|
713
|
+
readonly compactionId: string;
|
|
714
|
+
readonly sourceSequence: number;
|
|
715
|
+
readonly previousSummary?: string;
|
|
716
|
+
readonly messages: readonly JsonValue[];
|
|
717
|
+
readonly retainedTail: readonly JsonValue[];
|
|
718
|
+
readonly tokensBefore: number;
|
|
719
|
+
readonly records?: PluginSessionRecordsPort;
|
|
720
|
+
}
|
|
721
|
+
interface PluginCompactionCompilerRegistration {
|
|
722
|
+
readonly key: string;
|
|
723
|
+
readonly version?: number;
|
|
724
|
+
compile(input: PluginCompactionCompileInput): Promise<{
|
|
725
|
+
readonly text: string;
|
|
726
|
+
}> | {
|
|
727
|
+
readonly text: string;
|
|
728
|
+
};
|
|
729
|
+
}
|
|
730
|
+
interface PluginCompactionCompilerContribution extends PluginCompactionCompilerRegistration {
|
|
731
|
+
readonly contributionId: string;
|
|
732
|
+
readonly version: number;
|
|
733
|
+
readonly entryId?: string;
|
|
734
|
+
readonly activationId?: string;
|
|
735
|
+
}
|
|
736
|
+
/** Side-effect-only compaction observation; the Host still owns the checkpoint. */
|
|
737
|
+
interface PluginCompactionObservation {
|
|
738
|
+
readonly sessionId: string;
|
|
739
|
+
readonly runId?: string;
|
|
740
|
+
readonly compactionId: string;
|
|
741
|
+
readonly reason: 'threshold' | 'overflow' | 'manual';
|
|
742
|
+
readonly model: PluginCompactionModel;
|
|
743
|
+
readonly settings: PluginCompactionSettings;
|
|
744
|
+
readonly contextTokens: number;
|
|
745
|
+
readonly contextWindow: number;
|
|
746
|
+
readonly tokensBefore: number;
|
|
747
|
+
readonly messages: readonly JsonValue[];
|
|
748
|
+
readonly retainedTail: readonly JsonValue[];
|
|
749
|
+
/** Distinct committed overflow compaction requests for this Run, before this attempt. */
|
|
750
|
+
readonly priorOverflowRequests?: number;
|
|
751
|
+
readonly signal: AbortSignal;
|
|
752
|
+
}
|
|
753
|
+
interface PluginCompactionObservationDecision {
|
|
754
|
+
/** Cancels this compaction attempt; the Host records the failure, never a success. */
|
|
755
|
+
readonly cancel?: boolean;
|
|
756
|
+
/** Fixed, safe Host-visible reason if the attempt was cancelled. */
|
|
757
|
+
readonly reason?: string;
|
|
758
|
+
/** Replaces the model summary for this attempt; the Host still owns coverage and retention. */
|
|
759
|
+
readonly summary?: string;
|
|
760
|
+
}
|
|
761
|
+
interface PluginCompactionObserverRegistration {
|
|
762
|
+
readonly key: string;
|
|
763
|
+
readonly version?: number;
|
|
764
|
+
before?(input: PluginCompactionObservation): void | PluginCompactionObservationDecision | Promise<void | PluginCompactionObservationDecision>;
|
|
765
|
+
}
|
|
766
|
+
interface PluginCompactionObserverContribution extends PluginCompactionObserverRegistration {
|
|
767
|
+
readonly contributionId: string;
|
|
768
|
+
readonly version: number;
|
|
769
|
+
readonly entryId?: string;
|
|
770
|
+
readonly activationId?: string;
|
|
771
|
+
}
|
|
772
|
+
//#endregion
|
|
773
|
+
//#region src/contributions/history-selector.d.ts
|
|
774
|
+
declare const HistorySelectorMetadataSchema: s.Schema<{
|
|
775
|
+
selectorId: string;
|
|
776
|
+
}>;
|
|
777
|
+
type HistorySelectorMetadata = s.Static<typeof HistorySelectorMetadataSchema>;
|
|
778
|
+
interface PluginHistorySelector extends HistorySelectorMetadata {
|
|
779
|
+
readonly select: ContextHistorySelector;
|
|
780
|
+
}
|
|
781
|
+
//#endregion
|
|
782
|
+
//#region src/contributions/object-resource.d.ts
|
|
783
|
+
interface ObjectResourceAccess {
|
|
784
|
+
/** The key is a typed value token, not a Service lookup. Incompatible resources require
|
|
785
|
+
* explicit replacement. Staged replacement retains old values until their generations drain.
|
|
786
|
+
* Exclusive replacement drains calls, revokes old capabilities and closes old owners first;
|
|
787
|
+
* failures after teardown starts cannot restore them. Acquisition must own its dependencies
|
|
788
|
+
* for the full resource lifetime and must not capture generation-scoped handles. */
|
|
789
|
+
resource<Identifier, Resource>(name: string, key: Context.Key<Identifier, Resource>, definition: {
|
|
790
|
+
readonly version: number;
|
|
791
|
+
readonly identity: ReadonlyJsonValue;
|
|
792
|
+
readonly acquire: Effect.Effect<Resource, Error, Scope.Scope>;
|
|
793
|
+
readonly replacement?: 'staged' | 'exclusive';
|
|
794
|
+
}): Effect.Effect<Resource, Error>;
|
|
795
|
+
}
|
|
796
|
+
interface ObjectResourceDeclaration {
|
|
797
|
+
readonly name: string;
|
|
798
|
+
readonly key: string;
|
|
799
|
+
readonly version: number;
|
|
800
|
+
readonly identity: ReadonlyJsonValue;
|
|
801
|
+
readonly acquire: Effect.Effect<Context.Context<unknown>, Error, Scope.Scope>;
|
|
802
|
+
readonly replacement?: 'staged' | 'exclusive';
|
|
803
|
+
}
|
|
804
|
+
interface ObjectResourceHost {
|
|
805
|
+
resource(declaration: ObjectResourceDeclaration): Effect.Effect<Context.Context<unknown>, Error>;
|
|
806
|
+
}
|
|
807
|
+
//#endregion
|
|
808
|
+
//#region src/contributions/object-state.d.ts
|
|
809
|
+
interface ObjectStateFrame<Schema extends s.Schema> {
|
|
810
|
+
readonly name: string;
|
|
811
|
+
readonly version: number;
|
|
812
|
+
readonly revision: number;
|
|
813
|
+
readonly value: s.Static<Schema>;
|
|
814
|
+
}
|
|
815
|
+
interface ObjectStateSnapshot {
|
|
816
|
+
readonly name: string;
|
|
817
|
+
readonly schema: ReadonlyJsonValue;
|
|
818
|
+
readonly version: number;
|
|
819
|
+
readonly revision: number;
|
|
820
|
+
readonly value: ReadonlyJsonValue;
|
|
821
|
+
}
|
|
822
|
+
interface ObjectStateObservationPort {
|
|
823
|
+
/** Lists committed states by name; staged declarations remain private to their candidate. */
|
|
824
|
+
states(): Effect.Effect<readonly ObjectStateSnapshot[], Error>;
|
|
825
|
+
/** Starts with the latest committed frame and may skip revisions. Unknown state or a closed
|
|
826
|
+
* Ref fails at subscription; an active stream ends when its Ref or root admission closes. */
|
|
827
|
+
watchState(name: string): Stream.Stream<ObjectStateSnapshot, Error>;
|
|
828
|
+
}
|
|
829
|
+
/** Read values are readonly borrows; SDK writes are captured once. The stream starts after adoption, replays the latest frame,
|
|
830
|
+
* may skip revisions, and ends when this generation closes or is superseded by a migration. */
|
|
831
|
+
interface ObjectState<Schema extends s.Schema> {
|
|
832
|
+
readonly get: Effect.Effect<s.Static<Schema>, Error>;
|
|
833
|
+
set(value: s.Static<Schema>): Effect.Effect<void, Error>;
|
|
834
|
+
/** Runs change synchronously once; unchanged values emit no additional revision. */
|
|
835
|
+
update(change: (current: s.Static<Schema>) => s.Static<Schema>): Effect.Effect<void, Error>;
|
|
836
|
+
readonly changes: Stream.Stream<ObjectStateFrame<Schema>, Error>;
|
|
837
|
+
}
|
|
838
|
+
interface ObjectStateAccess {
|
|
839
|
+
/** Compatible declarations retain the current value. An explicit migration drains admitted
|
|
840
|
+
* calls and fences old writers before transforming a private candidate. Its pure synchronous
|
|
841
|
+
* transform runs once, requires the exact previous schema/version, and must increase the version.
|
|
842
|
+
* Failure restores old admission; adoption supersedes older methods and typed state handles. */
|
|
843
|
+
state<Schema extends s.Schema, Previous extends s.Schema = s.Schema>(name: string, definition: {
|
|
844
|
+
readonly schema: Schema;
|
|
845
|
+
readonly version: number;
|
|
846
|
+
readonly initial: s.Static<Schema>;
|
|
847
|
+
readonly migrate?: {
|
|
848
|
+
readonly from: {
|
|
849
|
+
readonly schema: Previous;
|
|
850
|
+
readonly version: number;
|
|
851
|
+
};
|
|
852
|
+
readonly transform: (previous: s.Static<Previous>) => s.Static<Schema>;
|
|
853
|
+
};
|
|
854
|
+
}): Effect.Effect<ObjectState<Schema>, Error>;
|
|
855
|
+
}
|
|
856
|
+
interface ObjectStateDeclaration {
|
|
857
|
+
readonly name: string;
|
|
858
|
+
readonly version: number;
|
|
859
|
+
readonly schema: JsonValue;
|
|
860
|
+
readonly initial: JsonValue;
|
|
861
|
+
readonly migrate?: {
|
|
862
|
+
readonly schema: JsonValue;
|
|
863
|
+
readonly version: number;
|
|
864
|
+
readonly transform: (previous: JsonValue) => Effect.Effect<JsonValue, Error>;
|
|
865
|
+
};
|
|
866
|
+
}
|
|
867
|
+
interface ObjectStateFrameData {
|
|
868
|
+
readonly name: string;
|
|
869
|
+
readonly version: number;
|
|
870
|
+
readonly revision: number;
|
|
871
|
+
readonly value: JsonValue;
|
|
872
|
+
}
|
|
873
|
+
interface ObjectStatePort {
|
|
874
|
+
readonly read: Effect.Effect<ObjectStateFrameData, Error>;
|
|
875
|
+
/** The owner gates admission, invokes change once, and commits only if it returns successfully. */
|
|
876
|
+
modify(change: (current: JsonValue) => Effect.Effect<JsonValue, Error>): Effect.Effect<void, Error>;
|
|
877
|
+
readonly changes: Stream.Stream<ObjectStateFrameData, Error>;
|
|
878
|
+
}
|
|
879
|
+
interface ObjectStateHost {
|
|
880
|
+
state(declaration: ObjectStateDeclaration): Effect.Effect<ObjectStatePort, Error>;
|
|
881
|
+
}
|
|
882
|
+
//#endregion
|
|
883
|
+
//#region src/contributions/object-self.d.ts
|
|
884
|
+
type ObjectSelf = ObjectStateAccess & ObjectResourceAccess;
|
|
885
|
+
//#endregion
|
|
886
|
+
//#region src/contributions/objects.d.ts
|
|
887
|
+
interface ObjectMethodSchema {
|
|
888
|
+
readonly input: s.Schema;
|
|
889
|
+
readonly output: s.Schema;
|
|
890
|
+
}
|
|
891
|
+
type ObjectMethodSchemas = Readonly<Record<string, ObjectMethodSchema>>;
|
|
892
|
+
interface ObjectType<Key extends s.Schema, Methods extends ObjectMethodSchemas> {
|
|
893
|
+
readonly id: string;
|
|
894
|
+
readonly version: number;
|
|
895
|
+
readonly key: Key;
|
|
896
|
+
readonly methods: Methods;
|
|
897
|
+
}
|
|
898
|
+
interface ObjectAddress {
|
|
899
|
+
readonly namespace: string;
|
|
900
|
+
readonly typeId: string;
|
|
901
|
+
readonly version: number;
|
|
902
|
+
readonly key: JsonValue;
|
|
903
|
+
}
|
|
904
|
+
type ObjectMethods<Methods extends ObjectMethodSchemas> = { readonly [Name in keyof Methods]: (input: s.Static<Methods[Name]['input']>) => Effect.Effect<s.Static<Methods[Name]['output']>, Error> };
|
|
905
|
+
interface ObjectFactory<Key extends s.Schema, Methods extends ObjectMethodSchemas> {
|
|
906
|
+
create(key: s.Static<Key>, self: ObjectSelf): Effect.Effect<ObjectMethods<Methods>, Error, Scope.Scope>;
|
|
907
|
+
}
|
|
908
|
+
/** The acquiring Scope owns this Ref; calls fail once that borrow has closed. */
|
|
909
|
+
interface ObjectRef<Key extends s.Schema, Methods extends ObjectMethodSchemas> extends ObjectStateObservationPort {
|
|
910
|
+
readonly address: ObjectAddress & {
|
|
911
|
+
readonly key: s.Static<Key>;
|
|
912
|
+
};
|
|
913
|
+
call<Name$1 extends keyof Methods & string>(name: Name$1, input: s.Static<Methods[Name$1]['input']>): Effect.Effect<s.Static<Methods[Name$1]['output']>, Error>;
|
|
914
|
+
}
|
|
915
|
+
interface PluginObjects {
|
|
916
|
+
/** Reads current root-visible contracts and resident addresses without constructing instances. */
|
|
917
|
+
catalog(): Effect.Effect<ObjectCatalog, Error>;
|
|
918
|
+
acquire<Key extends s.Schema, Methods extends ObjectMethodSchemas>(type: ObjectType<Key, Methods>, key: s.Static<Key>): Effect.Effect<ObjectRef<Key, Methods>, Error, Scope.Scope>;
|
|
919
|
+
}
|
|
920
|
+
/** Resolution of a declared contract to its resident instance in one namespace. */
|
|
921
|
+
type ObjectAcquisition = Pick<PluginObjects, 'acquire'>;
|
|
922
|
+
interface ObjectCatalog {
|
|
923
|
+
readonly namespace: string;
|
|
924
|
+
readonly types: readonly {
|
|
925
|
+
readonly contract: ObjectContractDescriptor;
|
|
926
|
+
readonly availability: 'available' | 'ambiguous';
|
|
927
|
+
}[];
|
|
928
|
+
readonly instances: readonly ObjectAddress[];
|
|
929
|
+
}
|
|
930
|
+
interface ObjectContractDescriptor {
|
|
931
|
+
readonly id: string;
|
|
932
|
+
readonly version: number;
|
|
933
|
+
readonly key: s.Schema;
|
|
934
|
+
readonly methods: ObjectMethodSchemas;
|
|
935
|
+
}
|
|
936
|
+
interface ObjectBinding {
|
|
937
|
+
call(name: string, input: JsonValue): Effect.Effect<JsonValue, Error>;
|
|
938
|
+
}
|
|
939
|
+
interface CapturedObjectFactory {
|
|
940
|
+
readonly typeId: string;
|
|
941
|
+
readonly version: number;
|
|
942
|
+
readonly descriptor: ObjectContractDescriptor;
|
|
943
|
+
readonly assertAvailable?: () => void;
|
|
944
|
+
create(key: JsonValue, self: ObjectSelf): Effect.Effect<ObjectBinding, Error, Scope.Scope>;
|
|
945
|
+
}
|
|
946
|
+
/** Captures mutable SDK schemas once. Internal consumers borrow the resulting readonly contract. */
|
|
947
|
+
declare function defineObject<Key extends s.Schema, const Methods extends ObjectMethodSchemas>(id: string, definition: {
|
|
948
|
+
readonly version?: number;
|
|
949
|
+
readonly key: Key;
|
|
950
|
+
readonly methods: Methods;
|
|
951
|
+
}): ObjectType<Key, Methods>;
|
|
952
|
+
//#endregion
|
|
953
|
+
//#region src/contributions/context-preparation.d.ts
|
|
954
|
+
interface PluginContextPreparationScope extends ContextPreparationScope {
|
|
955
|
+
/** Model consumer's captured borrow identity, shared with its Tool invocations. */
|
|
956
|
+
readonly leaseId?: string;
|
|
957
|
+
/** Detached request Tool names, not execution authority. Absent means unknown; [] means none. */
|
|
958
|
+
readonly visibleToolNames?: readonly string[];
|
|
959
|
+
}
|
|
960
|
+
/** Composition order is nesting order; Session/Run identity comes from the lease. */
|
|
961
|
+
interface PluginContextPreparationHook {
|
|
962
|
+
readonly hookId: string;
|
|
963
|
+
around(draft: ContextPreparationDraft, scope: PluginContextPreparationScope & {
|
|
964
|
+
readonly sessionId: string;
|
|
965
|
+
readonly runId: string;
|
|
966
|
+
}, next: Parameters<ContextPreparationHook['around']>[2]): Promise<ContextPreparationResult>;
|
|
967
|
+
}
|
|
968
|
+
//#endregion
|
|
969
|
+
//#region src/contributions/run-yield.d.ts
|
|
970
|
+
declare const YieldDecisionSchema: s.Schema<{
|
|
971
|
+
continue: false;
|
|
972
|
+
} | {
|
|
973
|
+
continue: true;
|
|
974
|
+
message: string | ({
|
|
975
|
+
type: "text";
|
|
976
|
+
text: string;
|
|
977
|
+
textSignature?: string | undefined;
|
|
978
|
+
} | {
|
|
979
|
+
type: "image";
|
|
980
|
+
data: string;
|
|
981
|
+
mimeType: string;
|
|
982
|
+
})[];
|
|
983
|
+
}>;
|
|
984
|
+
type YieldDecision = s.Static<typeof YieldDecisionSchema>;
|
|
985
|
+
interface CommittedAnswer {
|
|
986
|
+
readonly responseMessageId: string;
|
|
987
|
+
readonly message: JsonValue;
|
|
988
|
+
}
|
|
989
|
+
/** Known committed spend; missing response counters remain explicit, never estimated. */
|
|
990
|
+
interface UsageTotals {
|
|
991
|
+
readonly totalTokens: number;
|
|
992
|
+
readonly openModelRequests: number;
|
|
993
|
+
readonly unknownModelRequests: number;
|
|
994
|
+
readonly incompleteModelUsageRequests: number;
|
|
995
|
+
}
|
|
996
|
+
interface YieldContext {
|
|
997
|
+
readonly sessionId: string;
|
|
998
|
+
readonly runId: string;
|
|
999
|
+
/** Observation only; core continuation budgets measure tokens, not rounds. */
|
|
1000
|
+
readonly continuations: number;
|
|
1001
|
+
readonly usage: {
|
|
1002
|
+
readonly run: UsageTotals;
|
|
1003
|
+
readonly session: UsageTotals;
|
|
1004
|
+
};
|
|
1005
|
+
readonly behaviorState: JsonValue | undefined;
|
|
1006
|
+
/** Bound to this registration's own behavior. Cannot change Run authority. */
|
|
1007
|
+
readonly commandBehavior?: (command: SessionBehaviorCommand) => Promise<SessionBehaviorView>;
|
|
1008
|
+
/** Own-session records for this Plugin Entry; absent when the Host cannot scope it. */
|
|
1009
|
+
readonly records?: PluginSessionRecordsPort;
|
|
1010
|
+
readonly signal: AbortSignal;
|
|
1011
|
+
}
|
|
1012
|
+
/** Called after Pi settles and before the Run terminal, under the request lease. */
|
|
1013
|
+
interface RunYieldHook {
|
|
1014
|
+
/** Optional behavior owned by the same plugin registration path. */
|
|
1015
|
+
readonly behavior?: string;
|
|
1016
|
+
onYield(answer: CommittedAnswer, context: YieldContext): YieldDecision | Promise<YieldDecision>;
|
|
1017
|
+
}
|
|
1018
|
+
interface RunYieldContribution extends RunYieldHook {
|
|
1019
|
+
readonly contributionId: string;
|
|
1020
|
+
/** Host projection: owning Entry and Activation, used for Records scoping. */
|
|
1021
|
+
readonly entryId?: string;
|
|
1022
|
+
readonly activationId?: string;
|
|
1023
|
+
}
|
|
1024
|
+
//#endregion
|
|
1025
|
+
//#region src/contributions/component.d.ts
|
|
1026
|
+
type PluginToolExecutor = (name: string, input: JsonValue, options?: {
|
|
1027
|
+
readonly signal?: AbortSignal;
|
|
1028
|
+
}) => Promise<PluginToolResult>;
|
|
1029
|
+
/** Trusted-code Tool contribution; its captured Host resources are not sandboxed by Runtime. */
|
|
1030
|
+
interface ModelToolContribution {
|
|
1031
|
+
/** Omission is unsafe; recovery never automatically invokes this Tool. */
|
|
1032
|
+
readonly recovery?: 'unsafe' | 'safe';
|
|
1033
|
+
readonly contributionId: string;
|
|
1034
|
+
readonly name: string;
|
|
1035
|
+
/** Human-readable display name; the protocol Tool name remains its identity. */
|
|
1036
|
+
readonly label?: string;
|
|
1037
|
+
readonly description: string;
|
|
1038
|
+
readonly parameters: object;
|
|
1039
|
+
readonly outputSchema?: object;
|
|
1040
|
+
/** Namespaced protocol/Host metadata; retained in request evidence, never permission authority. */
|
|
1041
|
+
readonly metadata?: s.Static<typeof ModelToolMetadataSchema>['metadata'];
|
|
1042
|
+
/** Hidden Tools are available to admitted Host operation borrows, never model requests. */
|
|
1043
|
+
readonly discovery?: s.Static<typeof ModelToolMetadataSchema>['discovery'];
|
|
1044
|
+
/** Trusted synchronous code executed before schema validation and permission evaluation.
|
|
1045
|
+
* It must not perform protected effects; purity is not enforced by the runtime. */
|
|
1046
|
+
readonly prepareArguments?: (input: JsonValue) => JsonValue;
|
|
1047
|
+
execute(input: JsonValue, context: {
|
|
1048
|
+
/** Lease-owned identity, not authority to access or mutate a Session. */
|
|
1049
|
+
readonly approval: 'approved' | 'not-required';
|
|
1050
|
+
readonly steeringSignal?: AbortSignal;
|
|
1051
|
+
/** Public request metadata only; grants no execution authority. */
|
|
1052
|
+
readonly toolCatalog?: readonly ToolDeclaration[];
|
|
1053
|
+
readonly sessionId: string;
|
|
1054
|
+
/** Optional W3C carrier for downstream instrumentation; confers no authority. */
|
|
1055
|
+
readonly traceContext?: {
|
|
1056
|
+
readonly traceparent: string;
|
|
1057
|
+
readonly tracestate?: string;
|
|
1058
|
+
};
|
|
1059
|
+
readonly runId?: string;
|
|
1060
|
+
readonly operationId?: string;
|
|
1061
|
+
readonly source?: JsonValue;
|
|
1062
|
+
/** Captured model borrow; optional for direct Host invocation outside a model consumer. */
|
|
1063
|
+
readonly leaseId?: string;
|
|
1064
|
+
readonly signal: AbortSignal;
|
|
1065
|
+
/** Rechecks the captured owner and Package before deferred effect dispatch. */
|
|
1066
|
+
readonly assertAvailable?: () => void;
|
|
1067
|
+
/** Transfers this invocation's captured resources to work owned by its caller.
|
|
1068
|
+
* Call before this callback settles; resources remain held until work settles. */
|
|
1069
|
+
readonly ownTask?: (execute: () => Promise<void>) => Promise<void>;
|
|
1070
|
+
/** Executes another Tool in the same Run at a nested permission and Effect boundary. */
|
|
1071
|
+
readonly executeTool?: PluginToolExecutor;
|
|
1072
|
+
/** Model-protocol identity; only meaningful together with its Session/Run. */
|
|
1073
|
+
readonly toolCallId?: string;
|
|
1074
|
+
/**
|
|
1075
|
+
* Lazily captures committed feedback once per invocation; absence is not empty history.
|
|
1076
|
+
* The handle expires with this callback. Started reads are joined, and a read failure
|
|
1077
|
+
* fails an otherwise successful invocation. Snapshots are detached and immutable.
|
|
1078
|
+
*/
|
|
1079
|
+
readonly readToolResults?: (signal?: AbortSignal) => Promise<PluginToolResultSnapshot>;
|
|
1080
|
+
readonly commandBehavior?: SessionBehaviorDispatch;
|
|
1081
|
+
/** Transient feedback only; valid until this invocation settles. */
|
|
1082
|
+
readonly onUpdate?: (result: PluginToolResult) => void;
|
|
1083
|
+
}): Promise<PluginToolResult>;
|
|
1084
|
+
}
|
|
1085
|
+
interface ToolPluginContributions {
|
|
1086
|
+
readonly runYield?: readonly RunYieldContribution[];
|
|
1087
|
+
readonly compactionPolicies?: readonly PluginCompactionPolicyContribution[];
|
|
1088
|
+
readonly compactionCompilers?: readonly PluginCompactionCompilerContribution[];
|
|
1089
|
+
readonly compactionObservers?: readonly PluginCompactionObserverContribution[];
|
|
1090
|
+
readonly objectFactories?: readonly CapturedObjectFactory[];
|
|
1091
|
+
readonly sessionBehaviors?: readonly SessionBehaviorContribution[];
|
|
1092
|
+
readonly tools: readonly ModelToolContribution[];
|
|
1093
|
+
readonly hooks?: readonly ToolHookContribution[];
|
|
1094
|
+
readonly namedStates?: readonly PluginNamedStateContribution[];
|
|
1095
|
+
readonly prefixes?: readonly PluginPrefixContribution[];
|
|
1096
|
+
readonly inputTransforms?: readonly PluginInputTransform[];
|
|
1097
|
+
readonly preparationHooks?: readonly PluginContextPreparationHook[];
|
|
1098
|
+
readonly historySelectors?: readonly PluginHistorySelector[];
|
|
1099
|
+
/** Rechecks external admission after outstanding acquisitions finish. */
|
|
1100
|
+
readonly assertReady?: () => void | Promise<void>;
|
|
1101
|
+
/** Process-local registrations sampled at a consumer boundary, never archived as callbacks. */
|
|
1102
|
+
readonly live?: PluginContributionSource;
|
|
1103
|
+
readonly children?: PluginChildSource;
|
|
1104
|
+
readonly services?: PluginServiceSource;
|
|
1105
|
+
}
|
|
1106
|
+
interface PluginServiceRegistration {
|
|
1107
|
+
readonly key: string;
|
|
1108
|
+
readonly context: Context.Context<unknown>;
|
|
1109
|
+
}
|
|
1110
|
+
interface PluginServiceSource {
|
|
1111
|
+
readonly version: number;
|
|
1112
|
+
snapshot(): readonly PluginServiceRegistration[];
|
|
1113
|
+
subscribe(changed: () => void): () => void;
|
|
1114
|
+
}
|
|
1115
|
+
/** String identifiers require a Provider; Context References retain their Effect defaults. */
|
|
1116
|
+
type PluginServiceRequirement = string | Context.Key<unknown, unknown>;
|
|
1117
|
+
interface PluginChildComponent {
|
|
1118
|
+
readonly report?: (status: PluginMountStatus) => void;
|
|
1119
|
+
readonly key: string;
|
|
1120
|
+
readonly requires: readonly PluginServiceRequirement[];
|
|
1121
|
+
readonly provides?: readonly PluginServiceRequirement[];
|
|
1122
|
+
readonly realm?: 'inherit' | 'isolate';
|
|
1123
|
+
readonly replacement?: 'staged' | 'exclusive';
|
|
1124
|
+
readonly component: ToolPluginComponent;
|
|
1125
|
+
}
|
|
1126
|
+
interface PluginChildSource {
|
|
1127
|
+
readonly version: number;
|
|
1128
|
+
snapshot(): readonly PluginChildComponent[];
|
|
1129
|
+
subscribe(changed: () => void): () => void;
|
|
1130
|
+
}
|
|
1131
|
+
interface PluginContributionSource {
|
|
1132
|
+
readonly version: number;
|
|
1133
|
+
snapshot(): ToolPluginContributions;
|
|
1134
|
+
subscribe(changed: () => void): () => void;
|
|
1135
|
+
}
|
|
1136
|
+
interface PluginLifetime {
|
|
1137
|
+
readonly signal: AbortSignal;
|
|
1138
|
+
/** Checks retained ownership without starting a task; retirement alone does not revoke a borrow. */
|
|
1139
|
+
assertAvailable(): void;
|
|
1140
|
+
/** Runs in the owner's Scope; cancellation joins finalizers before releasing the owner. */
|
|
1141
|
+
run<A>(effect: Effect.Effect<A, Error, Scope.Scope>): Promise<A>;
|
|
1142
|
+
/** Critical acquisitions remain owned even when the caller does not await them. */
|
|
1143
|
+
acquire<A>(acquire: (signal: AbortSignal) => Promise<A>, release: (resource: A) => Promise<void>): Promise<A>;
|
|
1144
|
+
/** Adopts cleanup until Scope closure starts; later calls throw without running the callback. */
|
|
1145
|
+
addFinalizer(finalizer: () => Promise<void>): void;
|
|
1146
|
+
/** Local work only; this does not admit a durable operation or an external effect. */
|
|
1147
|
+
supervise(task: (signal: AbortSignal) => Promise<void>): {
|
|
1148
|
+
readonly settled: Promise<void>;
|
|
1149
|
+
};
|
|
1150
|
+
}
|
|
1151
|
+
interface ToolPluginComponent {
|
|
1152
|
+
readonly componentId: string;
|
|
1153
|
+
readonly executionProfile?: PluginExecutionProfile;
|
|
1154
|
+
/** A loader's temporary capacity gate; availability wakes reconciliation without changing Desired. */
|
|
1155
|
+
readonly admission?: {
|
|
1156
|
+
available(): boolean;
|
|
1157
|
+
subscribe(changed: () => void): () => void;
|
|
1158
|
+
};
|
|
1159
|
+
/** Loads runtime-readable declarations before Service resolution, in the instance's Scope.
|
|
1160
|
+
* The returned contract must remain stable for this component identity. */
|
|
1161
|
+
readonly load?: (context: {
|
|
1162
|
+
readonly activationId: string;
|
|
1163
|
+
readonly lifetime: PluginLifetime;
|
|
1164
|
+
}) => Promise<LoadedPluginComponent>;
|
|
1165
|
+
activate(context: {
|
|
1166
|
+
readonly activationId: string;
|
|
1167
|
+
readonly lifetime: PluginLifetime;
|
|
1168
|
+
readonly sessions?: PluginSessionDirectory;
|
|
1169
|
+
/** Host-owned Object resolution for a Plugin that must hold a published instance. */
|
|
1170
|
+
readonly objects?: ObjectAcquisition;
|
|
1171
|
+
readonly services?: Context.Context<unknown>;
|
|
1172
|
+
readonly observation?: PluginNativeObservationPort;
|
|
1173
|
+
}): Promise<ToolPluginContributions>;
|
|
1174
|
+
}
|
|
1175
|
+
interface LoadedPluginComponent {
|
|
1176
|
+
/** Rechecks loader-owned authority before newly admitted resource calls. */
|
|
1177
|
+
readonly assertAvailable?: () => void;
|
|
1178
|
+
readonly requires?: readonly PluginServiceRequirement[];
|
|
1179
|
+
readonly provides?: readonly PluginServiceRequirement[];
|
|
1180
|
+
readonly realm?: 'inherit' | 'isolate';
|
|
1181
|
+
readonly replacement?: 'staged' | 'exclusive';
|
|
1182
|
+
readonly activate: ToolPluginComponent['activate'];
|
|
1183
|
+
}
|
|
1184
|
+
/** Default ESM export for sorbet.tool-component/v1; config is materialized before evaluation. */
|
|
1185
|
+
interface PluginPackageComponent {
|
|
1186
|
+
readonly componentId: string;
|
|
1187
|
+
activate(context: {
|
|
1188
|
+
readonly activationId: string;
|
|
1189
|
+
readonly lifetime: PluginLifetime;
|
|
1190
|
+
readonly config: JsonValue;
|
|
1191
|
+
}): Promise<Omit<ToolPluginContributions, 'tools'> & {
|
|
1192
|
+
readonly tools: readonly (ModelToolContribution | {
|
|
1193
|
+
readonly hostBinding: string;
|
|
1194
|
+
})[];
|
|
1195
|
+
}>;
|
|
1196
|
+
}
|
|
1197
|
+
//#endregion
|
|
1198
|
+
//#region src/contributions/context.d.ts
|
|
1199
|
+
type PluginApplyResult<Requirements = never> = void | PluginRegistration | Promise<void | PluginRegistration> | Effect.Effect<void, Error, Scope.Scope | Requirements>;
|
|
1200
|
+
type PluginApply<Config, Requirements = never> = ((context: PluginContext, config: Readonly<Config>) => PluginApplyResult<Requirements>) & {
|
|
1201
|
+
readonly executionProfile?: PluginExecutionProfile;
|
|
1202
|
+
};
|
|
1203
|
+
interface PluginDefinition<Config, Services extends readonly Context.Key<unknown, unknown>[]> {
|
|
1204
|
+
readonly requires: Services;
|
|
1205
|
+
/** Expected outputs for cold dependency diagnostics; only provide() makes a Service available. */
|
|
1206
|
+
readonly provides?: readonly Context.Key<unknown, unknown>[];
|
|
1207
|
+
/**
|
|
1208
|
+
* Opens a realm for this mount and its children. Inherit searches the nearest
|
|
1209
|
+
* provider through parent realms; isolate stops parent lookup. Omission shares
|
|
1210
|
+
* the current realm. A local conflict blocks inherited fallback.
|
|
1211
|
+
*/
|
|
1212
|
+
readonly realm?: 'inherit' | 'isolate';
|
|
1213
|
+
/** Exclusive replacement waits for all older generations at this path to drain and close. */
|
|
1214
|
+
readonly replacement?: 'staged' | 'exclusive';
|
|
1215
|
+
readonly apply: PluginApply<Config, Services[number]['Identifier']>;
|
|
1216
|
+
}
|
|
1217
|
+
/** Withdrawal affects future requests; captured callbacks remain valid until their borrowers drain. */
|
|
1218
|
+
interface PluginRegistration {
|
|
1219
|
+
dispose(): void;
|
|
1220
|
+
}
|
|
1221
|
+
/** Reports desired updates/removal immediately and the latest reconciliation for this handle. */
|
|
1222
|
+
interface PluginMount<Config> extends PluginRegistration {
|
|
1223
|
+
status(): PluginMountStatus;
|
|
1224
|
+
update(config: Readonly<Config>): void;
|
|
1225
|
+
}
|
|
1226
|
+
interface PluginToolRegistration extends Omit<ModelToolContribution, 'contributionId'> {
|
|
1227
|
+
/** Stable within this Plugin instance. Defaults to the model-visible Tool name. */
|
|
1228
|
+
readonly key?: string;
|
|
1229
|
+
}
|
|
1230
|
+
interface PluginHostToolRegistration {
|
|
1231
|
+
/** Stable within this Plugin instance. Defaults to the Host binding name. */
|
|
1232
|
+
readonly key?: string;
|
|
1233
|
+
readonly hostBinding: string;
|
|
1234
|
+
}
|
|
1235
|
+
interface PluginToolHookRegistration extends Omit<ToolHookContribution, 'contributionId' | 'before' | 'after'> {
|
|
1236
|
+
readonly key: string;
|
|
1237
|
+
readonly before?: readonly PluginRegistrationReference[];
|
|
1238
|
+
readonly after?: readonly PluginRegistrationReference[];
|
|
1239
|
+
}
|
|
1240
|
+
type PluginRegistrationReference = string | Readonly<{
|
|
1241
|
+
entry: string;
|
|
1242
|
+
key: string;
|
|
1243
|
+
}>;
|
|
1244
|
+
interface PluginNamedStateRegistration extends Omit<PluginNamedStateContribution, 'contributionId'> {
|
|
1245
|
+
/** Stable within this Plugin instance. Defaults to the model-visible state name. */
|
|
1246
|
+
readonly key?: string;
|
|
1247
|
+
}
|
|
1248
|
+
interface PluginContext {
|
|
1249
|
+
readonly objects: {
|
|
1250
|
+
/**
|
|
1251
|
+
* Builds an Object contract inside the Host's own module graph.
|
|
1252
|
+
*
|
|
1253
|
+
* An execution profile that resolves only `effect` cannot import the SDK,
|
|
1254
|
+
* so a Plugin that must publish an Object takes its contract from the
|
|
1255
|
+
* context rather than from a module import.
|
|
1256
|
+
*/
|
|
1257
|
+
define<Key extends s.Schema, Methods extends ObjectMethodSchemas>(id: string, definition: {
|
|
1258
|
+
readonly version?: number;
|
|
1259
|
+
readonly key: Key;
|
|
1260
|
+
readonly methods: Methods;
|
|
1261
|
+
}): ObjectType<Key, Methods>;
|
|
1262
|
+
/** Publishes a factory in this Mount's Realm; instances acquire resources only on demand. */
|
|
1263
|
+
serve<Key extends s.Schema, Methods extends ObjectMethodSchemas>(type: ObjectType<Key, Methods>, factory: ObjectFactory<Key, Methods>): PluginRegistration;
|
|
1264
|
+
/**
|
|
1265
|
+
* Resolves a declared contract to its resident instance in this Platform's
|
|
1266
|
+
* namespace, so a Plugin that publishes state can also hold and update it.
|
|
1267
|
+
* The acquiring Scope owns the reference; closing it releases this holder only.
|
|
1268
|
+
* Acquire from supervised work: taking a reference during `apply` deadlocks the
|
|
1269
|
+
* Activation's own retirement.
|
|
1270
|
+
*/
|
|
1271
|
+
acquire: ObjectAcquisition['acquire'];
|
|
1272
|
+
};
|
|
1273
|
+
readonly entryId?: string;
|
|
1274
|
+
readonly activationId?: string;
|
|
1275
|
+
readonly observation?: PluginNativeObservationPort;
|
|
1276
|
+
/** Publishes into the current realm; withdrawal re-resolves affected consumers during reconciliation. */
|
|
1277
|
+
provide<I, S>(service: Context.Key<I, S>, value: NoInfer<S>): PluginRegistration;
|
|
1278
|
+
mount<Config>(key: string, apply: PluginApply<Config>, config: NoInfer<Config>): PluginMount<Config>;
|
|
1279
|
+
mount<Config, const Services extends readonly Context.Key<unknown, unknown>[]>(key: string, definition: PluginDefinition<Config, Services>, config: NoInfer<Config>): PluginMount<Config>;
|
|
1280
|
+
readonly session: {
|
|
1281
|
+
behavior(behavior: Omit<SessionBehaviorContribution, 'contributionId'>): PluginRegistration;
|
|
1282
|
+
bind: PluginSessionDirectory['bind'];
|
|
1283
|
+
discover(): Promise<readonly {
|
|
1284
|
+
readonly sessionId: string;
|
|
1285
|
+
}[]>;
|
|
1286
|
+
create(input: JsonValue): ReturnType<PluginSessionDirectory['bind']>;
|
|
1287
|
+
};
|
|
1288
|
+
readonly signal: AbortSignal;
|
|
1289
|
+
/** Rechecks this captured owner's availability and authority without admitting new work.
|
|
1290
|
+
* Retained requests may use retiring owners until their resources actually close. */
|
|
1291
|
+
assertAvailable(): void;
|
|
1292
|
+
acquire<Resource>(acquire: (signal: AbortSignal) => Promise<Resource>, release: (resource: Resource) => Promise<void>): Promise<Resource>;
|
|
1293
|
+
supervise(task: (signal: AbortSignal) => Promise<void>): {
|
|
1294
|
+
readonly settled: Promise<void>;
|
|
1295
|
+
};
|
|
1296
|
+
readonly tools: {
|
|
1297
|
+
register(tool: PluginToolRegistration | PluginHostToolRegistration): PluginRegistration;
|
|
1298
|
+
hook(hook: PluginToolHookRegistration): PluginRegistration;
|
|
1299
|
+
};
|
|
1300
|
+
/** Human-facing slash command; registered as a hidden slash-command Tool. */
|
|
1301
|
+
readonly commands: {
|
|
1302
|
+
register(command: PluginCommandRegistration): PluginRegistration;
|
|
1303
|
+
};
|
|
1304
|
+
readonly runYield: {
|
|
1305
|
+
register(key: string, hook: RunYieldHook): PluginRegistration;
|
|
1306
|
+
};
|
|
1307
|
+
/** Compaction threshold policy; Host selects at most one. */
|
|
1308
|
+
readonly compaction: {
|
|
1309
|
+
policy(registration: PluginCompactionPolicyRegistration): PluginRegistration;
|
|
1310
|
+
/** Deterministic compiler; Host selects at most one. */
|
|
1311
|
+
compiler(registration: PluginCompactionCompilerRegistration): PluginRegistration;
|
|
1312
|
+
/** Side-effect observer; cannot own or replace the checkpoint. */
|
|
1313
|
+
observe(registration: PluginCompactionObserverRegistration): PluginRegistration;
|
|
1314
|
+
};
|
|
1315
|
+
readonly input: {
|
|
1316
|
+
transform(key: string, transform: PluginInputTransform['transform']): PluginRegistration;
|
|
1317
|
+
};
|
|
1318
|
+
readonly context: {
|
|
1319
|
+
prefix(key: string, content: string): PluginRegistration;
|
|
1320
|
+
state(state: PluginNamedStateRegistration): PluginRegistration;
|
|
1321
|
+
around(key: string, around: PluginContextPreparationHook['around']): PluginRegistration;
|
|
1322
|
+
selectHistory(key: string, selector: ContextHistorySelector): PluginRegistration;
|
|
1323
|
+
};
|
|
1324
|
+
}
|
|
1325
|
+
//#endregion
|
|
1326
|
+
export { PluginCompactionObservationDecision as $, PluginExecutionProfile as $t, ObjectAcquisition as A, PluginSessionFactReadOptions as At, PluginObjects as B, PluginSessionWorkHandle as Bt, RunYieldHook as C, PluginToolResult as Ct, PluginContextPreparationHook as D, PluginSessionControlPort as Dt, YieldDecision as E, PluginSessionActor as Et, ObjectFactory as F, PluginSessionRequestPort as Ft, ObjectStateHost as G, PluginCompleteModelRequest as Gt, ObjectSelf as H, PluginSessionWorkPort as Ht, ObjectMethodSchemas as I, PluginSessionResolver as It, PluginCompactionCompileInput as J, PluginModelUsage as Jt, ObjectStateSnapshot as K, PluginModelForkRequest as Kt, ObjectMethods as L, PluginSessionScope as Lt, ObjectBinding as M, PluginSessionRecord as Mt, ObjectCatalog as N, PluginSessionRecordAppend as Nt, PluginContextPreparationScope as O, PluginSessionDirectory as Ot, ObjectContractDescriptor as P, PluginSessionRecordsPort as Pt, PluginCompactionObservation as Q, PluginMountStatus as Qt, ObjectRef as R, PluginSessionSendInput as Rt, CommittedAnswer as S, ToolHookPreparation as St, YieldContext as T, PluginRequestContext as Tt, ObjectState as U, PluginSessionWriteInput as Ut, defineObject as V, PluginSessionWorkOutcome as Vt, ObjectStateFrame as W, PluginSessionWriteInputSchema as Wt, PluginCompactionCompilerRegistration as X, PluginProviderModel as Xt, PluginCompactionCompilerContribution as Y, PluginProviderHooks as Yt, PluginCompactionModel as Z, PluginSessionModelPort as Zt, PluginServiceRequirement as _, ReadonlyJsonValue as _n, ToolHookContext as _t, PluginMount as a, PluginCommandRegistration as an, PluginCompactionTrigger as at, ToolPluginComponent as b, ToolHookFeedback as bt, PluginToolHookRegistration as c, SessionBehaviorCommandSchema as cn, PluginInputTransform as ct, ModelToolContribution as d, SessionBehaviorMetadata as dn, PluginStateReadContext as dt, PluginNativeInvocationObservation as en, PluginCompactionObserverContribution as et, PluginChildSource as f, SessionBehaviorMetadataSchema as fn, PluginStateReadResult as ft, PluginServiceRegistration as g, JsonValue as gn, PreparedToolHooksSchema as gt, PluginPackageComponent as h, SessionBehaviorViewSchema as hn, PreparedToolHooks as ht, PluginDefinition as i, PluginCommandInput as in, PluginCompactionSettings as it, ObjectAddress as j, PluginSessionFactsPort as jt, CapturedObjectFactory as k, PluginSessionFact as kt, PluginToolRegistration as l, SessionBehaviorContribution as ln, PluginPrefixContribution as lt, PluginLifetime as m, SessionBehaviorView as mn, PluginToolResultSnapshot as mt, PluginApplyResult as n, PluginNativeObservationPort as nn, PluginCompactionPolicyContribution as nt, PluginNamedStateRegistration as o, PluginCommandResult as on, PluginInput as ot, PluginContributionSource as p, SessionBehaviorScope as pn, PluginToolResultObservation as pt, ObjectResourceHost as q, PluginModelInvocationReceipt as qt, PluginContext as r, PluginCommandContext as rn, PluginCompactionPolicyRegistration as rt, PluginRegistration as s, SessionBehaviorCommand as sn, PluginInputSchema as st, PluginApply as t, PluginNativeLifecycleObservation as tn, PluginCompactionObserverRegistration as tt, LoadedPluginComponent as u, SessionBehaviorDispatch as un, PluginNamedStateContribution as ut, PluginServiceSource as v, ToolHookContinuation as vt, UsageTotals as w, ModelToolMetadataSchema as wt, ToolPluginContributions as x, ToolHookFeedbackSchema as xt, PluginToolExecutor as y, ToolHookContribution as yt, ObjectType as z, PluginSessionSendInputSchema as zt };
|