@kana-ai/edgar-contracts 0.0.0-stage → 0.1.0

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.
@@ -0,0 +1,435 @@
1
+ /** Generated by json-schema-to-typescript from the schema of the same name. */
2
+
3
+ /**
4
+ * One line of the newline-delimited JSON-RPC 2.0 stream between the engine and a provider runtime. A line is at most `rpc.schema.json#/$defs/MaxMessageBytes` bytes of UTF-8.
5
+ *
6
+ * This interface was referenced by `Provider`'s JSON-Schema
7
+ * via the `definition` "Message".
8
+ */
9
+ export type ProviderMessage = ProviderRequest | ProviderNotification | Success | Failure;
10
+ export type Id = number | string;
11
+ /**
12
+ * `hello`, `session.*` and `shutdown` go from the engine to the runtime; `tool.request` goes from the runtime to the engine.
13
+ *
14
+ * This interface was referenced by `Provider`'s JSON-Schema
15
+ * via the `definition` "Method".
16
+ */
17
+ export type ProviderMethod =
18
+ "hello" | "session.start" | "session.send" | "session.cancel" | "shutdown" | "tool.request";
19
+ /**
20
+ * A provider session id, a lowercase UUID; the engine stores it to resume or fork the session.
21
+ *
22
+ * This interface was referenced by `Provider`'s JSON-Schema
23
+ * via the `definition` "Handle".
24
+ */
25
+ export type Handle = string;
26
+ /**
27
+ * This interface was referenced by `Provider`'s JSON-Schema
28
+ * via the `definition` "SessionEvent".
29
+ */
30
+ export type SessionEvent = MessageEvent | UsageEvent | LimitEvent | ResultEvent | ErrorEvent;
31
+ /**
32
+ * The one result of a stage or a tool call.
33
+ */
34
+ export type Outcome = Done | Skipped | TemporaryFailure | PermanentFailure | Waiting;
35
+ /**
36
+ * A kind that may lead to another attempt.
37
+ */
38
+ export type TemporaryKind =
39
+ | "provider_unavailable"
40
+ | "rate_limited"
41
+ | "network"
42
+ | "timeout"
43
+ | "silence"
44
+ | "lost_lease"
45
+ | "runtime_crashed"
46
+ | "disk_full"
47
+ | "interrupted"
48
+ | "not_performed";
49
+ /**
50
+ * A kind that trying again cannot help.
51
+ */
52
+ export type PermanentKind =
53
+ | "invalid_input"
54
+ | "invalid"
55
+ | "tool_error"
56
+ | "refused"
57
+ | "attempts_exhausted"
58
+ | "denied_by_hook"
59
+ | "denied_by_person"
60
+ | "exposed"
61
+ | "stale_base"
62
+ | "manifest_drift"
63
+ | "context_exhausted"
64
+ | "token_budget"
65
+ | "unauthenticated"
66
+ | "forbidden"
67
+ | "not_found"
68
+ | "cancelled"
69
+ | "runtime_payload_too_large";
70
+ /**
71
+ * Either kind, for records that hold both.
72
+ */
73
+ export type FailureKind = TemporaryKind | PermanentKind;
74
+ /**
75
+ * -32700 parse_error, -32600 invalid_request, -32601 method_not_found, -32602 invalid_params, -32603 internal_error, -32001 runtime_payload_too_large, -32002 unknown_id, -32003 busy, -32004 contract_mismatch, -32010 capability_refused, -32011 sandbox_refused.
76
+ */
77
+ export type ErrorCode =
78
+ -32700 | -32600 | -32601 | -32602 | -32603 | -32001 | -32002 | -32003 | -32004 | -32010 | -32011;
79
+ /**
80
+ * The RPC contract version.
81
+ */
82
+ export type Contract = 1;
83
+ /**
84
+ * The one credential of the session; its value reaches only the vendor process, never a sandbox. A `cli` credential has no value: the vendor's program uses the sign-in of its own CLI.
85
+ *
86
+ * This interface was referenced by `Provider`'s JSON-Schema
87
+ * via the `definition` "Credential".
88
+ */
89
+ export type Credential =
90
+ | {
91
+ kind: "oauth" | "api_key";
92
+ value: string;
93
+ }
94
+ | {
95
+ kind: "cli";
96
+ };
97
+
98
+ /**
99
+ * The JSON-RPC 2.0 messages between the engine and a provider runtime such as `edgar-provider-claude`; this document only holds definitions.
100
+ */
101
+ export interface Provider {
102
+ [k: string]: unknown;
103
+ }
104
+ /**
105
+ * This interface was referenced by `Provider`'s JSON-Schema
106
+ * via the `definition` "Request".
107
+ */
108
+ export interface ProviderRequest {
109
+ jsonrpc: "2.0";
110
+ id: Id;
111
+ method: ProviderMethod;
112
+ params: {
113
+ [k: string]: unknown;
114
+ };
115
+ }
116
+ /**
117
+ * This interface was referenced by `Provider`'s JSON-Schema
118
+ * via the `definition` "Notification".
119
+ */
120
+ export interface ProviderNotification {
121
+ jsonrpc: "2.0";
122
+ method: "session.event";
123
+ params: SessionEventParams;
124
+ }
125
+ /**
126
+ * This interface was referenced by `Provider`'s JSON-Schema
127
+ * via the `definition` "SessionEventParams".
128
+ */
129
+ export interface SessionEventParams {
130
+ handle: Handle;
131
+ event: SessionEvent;
132
+ }
133
+ /**
134
+ * The text of one model message.
135
+ *
136
+ * This interface was referenced by `Provider`'s JSON-Schema
137
+ * via the `definition` "MessageEvent".
138
+ */
139
+ export interface MessageEvent {
140
+ type: "message";
141
+ role: "assistant";
142
+ text: string;
143
+ }
144
+ /**
145
+ * The session's running totals, sent before each `result`.
146
+ *
147
+ * This interface was referenced by `Provider`'s JSON-Schema
148
+ * via the `definition` "UsageEvent".
149
+ */
150
+ export interface UsageEvent {
151
+ type: "usage";
152
+ input_tokens: number;
153
+ output_tokens: number;
154
+ cache_read_tokens?: number;
155
+ cache_write_tokens?: number;
156
+ /**
157
+ * The vendor's estimate, not a bill.
158
+ */
159
+ cost_usd?: number;
160
+ }
161
+ /**
162
+ * A rate or usage limit of the provider's account, sent when the vendor reports it; the session goes on.
163
+ *
164
+ * This interface was referenced by `Provider`'s JSON-Schema
165
+ * via the `definition` "LimitEvent".
166
+ */
167
+ export interface LimitEvent {
168
+ type: "limit";
169
+ limit: Limit;
170
+ }
171
+ /**
172
+ * What a vendor or a provider said about one rate or usage limit: how much is left of `limit`, and when it resets. The engine keeps the newest one per `source` and does not start a stage on a used-up source before `resets_at`.
173
+ */
174
+ export interface Limit {
175
+ /**
176
+ * The host of the API, such as `api.github.com`, or the provider name, such as `claude`.
177
+ */
178
+ source: string;
179
+ /**
180
+ * The requests, tokens or credits left in the window.
181
+ */
182
+ remaining?: number;
183
+ /**
184
+ * The size of the window.
185
+ */
186
+ limit?: number;
187
+ /**
188
+ * When the window resets, in Unix milliseconds.
189
+ */
190
+ resets_at?: number;
191
+ /**
192
+ * The vendor's name of the limit, such as `core`, `requests`, `tokens` or `five_hour`.
193
+ */
194
+ window?: string;
195
+ }
196
+ /**
197
+ * The end of a turn: `done` with what the model returned through `edgar__result` (or its last text when the role has no `edgar__result`), or a failure.
198
+ *
199
+ * This interface was referenced by `Provider`'s JSON-Schema
200
+ * via the `definition` "ResultEvent".
201
+ */
202
+ export interface ResultEvent {
203
+ type: "result";
204
+ outcome: Outcome;
205
+ }
206
+ export interface Done {
207
+ outcome: "done";
208
+ output: unknown;
209
+ limit?: Limit;
210
+ }
211
+ export interface Skipped {
212
+ outcome: "skipped";
213
+ }
214
+ export interface TemporaryFailure {
215
+ outcome: "temporary_failure";
216
+ kind: TemporaryKind;
217
+ message: string;
218
+ /**
219
+ * Whole seconds to wait before the next attempt.
220
+ */
221
+ retry_after?: number;
222
+ /**
223
+ * The raw vendor or provider code.
224
+ */
225
+ cause?: string;
226
+ limit?: Limit;
227
+ }
228
+ export interface PermanentFailure {
229
+ outcome: "permanent_failure";
230
+ kind: PermanentKind;
231
+ message: string;
232
+ /**
233
+ * The raw vendor or provider code.
234
+ */
235
+ cause?: string;
236
+ limit?: Limit;
237
+ }
238
+ export interface Waiting {
239
+ outcome: "waiting";
240
+ key: string;
241
+ /**
242
+ * Unix time in milliseconds.
243
+ */
244
+ timeout_at: number;
245
+ }
246
+ /**
247
+ * The session stopped while no turn was running; `session_gone` means it cannot be resumed.
248
+ *
249
+ * This interface was referenced by `Provider`'s JSON-Schema
250
+ * via the `definition` "ErrorEvent".
251
+ */
252
+ export interface ErrorEvent {
253
+ type: "error";
254
+ kind: FailureKind | "session_gone";
255
+ message: string;
256
+ /**
257
+ * The raw vendor code.
258
+ */
259
+ cause?: string;
260
+ }
261
+ export interface Success {
262
+ jsonrpc: "2.0";
263
+ id: Id;
264
+ result: unknown;
265
+ }
266
+ export interface Failure {
267
+ jsonrpc: "2.0";
268
+ id: Id | null;
269
+ error: RpcError;
270
+ }
271
+ export interface RpcError {
272
+ code: ErrorCode;
273
+ message: string;
274
+ }
275
+ /**
276
+ * This interface was referenced by `Provider`'s JSON-Schema
277
+ * via the `definition` "HelloParams".
278
+ */
279
+ export interface ProviderHelloParams {
280
+ contract: Contract;
281
+ }
282
+ /**
283
+ * This interface was referenced by `Provider`'s JSON-Schema
284
+ * via the `definition` "HelloResult".
285
+ */
286
+ export interface ProviderHelloResult {
287
+ contract: Contract;
288
+ provider: "claude" | "codex" | "acp";
289
+ /**
290
+ * The version of the vendor SDK the runtime runs, for example the Claude Agent SDK's.
291
+ */
292
+ sdk_version: string;
293
+ }
294
+ /**
295
+ * One line of the role's list of skills. The session gets no text of a skill: the model loads it with the tool `edgar__skill`.
296
+ *
297
+ * This interface was referenced by `Provider`'s JSON-Schema
298
+ * via the `definition` "Skill".
299
+ */
300
+ export interface Skill {
301
+ name: string;
302
+ /**
303
+ * One line that says what the skill covers and when to load it.
304
+ */
305
+ description: string;
306
+ }
307
+ /**
308
+ * One tool the role may call; a tool not listed is not sent to the model.
309
+ *
310
+ * This interface was referenced by `Provider`'s JSON-Schema
311
+ * via the `definition` "ToolSpec".
312
+ */
313
+ export interface ProviderTool {
314
+ /**
315
+ * `edgar__<tool>` for a built-in tool, `<extension>__<tool>` for an extension's.
316
+ */
317
+ name: string;
318
+ description: string;
319
+ /**
320
+ * A JSON Schema 2020-12 of type `object`.
321
+ */
322
+ input_schema: {
323
+ type: "object";
324
+ [k: string]: unknown;
325
+ };
326
+ }
327
+ /**
328
+ * This interface was referenced by `Provider`'s JSON-Schema
329
+ * via the `definition` "Limits".
330
+ */
331
+ export interface Limits {
332
+ /**
333
+ * How full the context gets before the provider compacts it.
334
+ */
335
+ context_tokens?: number;
336
+ /**
337
+ * The most input and output tokens the session may spend; past it the turn ends `token_budget`.
338
+ */
339
+ max_tokens?: number;
340
+ /**
341
+ * The most model turns one `session.send` may take.
342
+ */
343
+ max_turns?: number;
344
+ }
345
+ /**
346
+ * Start from an earlier session; with `fork` the new session gets a new handle and the earlier one is left as it was.
347
+ *
348
+ * This interface was referenced by `Provider`'s JSON-Schema
349
+ * via the `definition` "Resume".
350
+ */
351
+ export interface Resume {
352
+ handle: Handle;
353
+ fork: boolean;
354
+ }
355
+ /**
356
+ * This interface was referenced by `Provider`'s JSON-Schema
357
+ * via the `definition` "SessionStartParams".
358
+ */
359
+ export interface SessionStartParams {
360
+ /**
361
+ * The engine's id of this session, for logs.
362
+ */
363
+ session_id: string;
364
+ model: string;
365
+ instructions: string;
366
+ skills: Skill[];
367
+ tools: ProviderTool[];
368
+ limits: Limits;
369
+ /**
370
+ * The role's `effort`: how hard the model thinks. Absent leaves the vendor's default.
371
+ */
372
+ effort?: "low" | "medium" | "high" | "max";
373
+ cwd: string;
374
+ credential: Credential;
375
+ resume?: Resume;
376
+ }
377
+ /**
378
+ * This interface was referenced by `Provider`'s JSON-Schema
379
+ * via the `definition` "SessionStartResult".
380
+ */
381
+ export interface SessionStartResult {
382
+ handle: Handle;
383
+ }
384
+ /**
385
+ * Starts one turn; the turn ends with a `result` event. A second send before that is refused with `busy`.
386
+ *
387
+ * This interface was referenced by `Provider`'s JSON-Schema
388
+ * via the `definition` "SessionSendParams".
389
+ */
390
+ export interface SessionSendParams {
391
+ handle: Handle;
392
+ message: string;
393
+ }
394
+ /**
395
+ * This interface was referenced by `Provider`'s JSON-Schema
396
+ * via the `definition` "SessionSendResult".
397
+ */
398
+ export interface SessionSendResult {}
399
+ /**
400
+ * This interface was referenced by `Provider`'s JSON-Schema
401
+ * via the `definition` "SessionCancelParams".
402
+ */
403
+ export interface SessionCancelParams {
404
+ handle: Handle;
405
+ }
406
+ /**
407
+ * Sent once the session has stopped; `cancelled` is false when no such session was open. The handle can still be resumed.
408
+ *
409
+ * This interface was referenced by `Provider`'s JSON-Schema
410
+ * via the `definition` "SessionCancelResult".
411
+ */
412
+ export interface SessionCancelResult {
413
+ cancelled: boolean;
414
+ }
415
+ /**
416
+ * The model asks for a tool; the engine checks its policies, runs it and answers a `ToolRequestResult`, or refuses with an `ErrorCode`.
417
+ *
418
+ * This interface was referenced by `Provider`'s JSON-Schema
419
+ * via the `definition` "ToolRequestParams".
420
+ */
421
+ export interface ToolRequestParams {
422
+ handle: Handle;
423
+ call_id: string;
424
+ tool: string;
425
+ input: unknown;
426
+ }
427
+ /**
428
+ * `done.output` is what the model reads; a failure reaches the model as an error with its kind and message.
429
+ *
430
+ * This interface was referenced by `Provider`'s JSON-Schema
431
+ * via the `definition` "ToolRequestResult".
432
+ */
433
+ export interface ToolRequestResult {
434
+ outcome: Outcome;
435
+ }