@bendyline/gezel-sdk 1.0.10 → 1.1.1

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,742 @@
1
+ import { k as ScriptMeta, I as InferInput, a as InferOutput, h as ScriptInputs, p as ScriptOutputs } from './types-rOo0kM35.js';
2
+ export { G as GateScriptResult, S as ScriptArrayOutput, b as ScriptBooleanInput, c as ScriptBooleanOutput, d as ScriptCapability, e as ScriptChoiceInput, f as ScriptChoiceOption, g as ScriptInputField, i as ScriptJsonInput, j as ScriptJsonOutput, l as ScriptNumberInput, m as ScriptNumberOutput, n as ScriptObjectOutput, o as ScriptOutputField, q as ScriptRefInput, r as ScriptStringInput, s as ScriptStringOutput } from './types-rOo0kM35.js';
3
+
4
+ /**
5
+ * Script-SDK wire types for workspace-index status and readiness.
6
+ *
7
+ * These deliberately live in the self-contained SDK instead of importing
8
+ * the Zod-inferred core types. Script sandboxes and Monaco receive only the
9
+ * SDK declaration files, so an external type import would make that surface
10
+ * depend on another package. The parity test beside this file keeps these
11
+ * structural copies aligned with the canonical core schemas.
12
+ */
13
+ interface WorkspaceIndexStatus {
14
+ state: 'fresh' | 'stale' | 'indexing' | 'never' | 'disabled';
15
+ embeddings?: {
16
+ status: 'cold' | 'warming' | 'ready' | 'disabled' | 'unavailable';
17
+ reason?: string;
18
+ };
19
+ meta?: {
20
+ version: number;
21
+ scannedAt: string;
22
+ root: string;
23
+ durationMs: number;
24
+ fileCount: number;
25
+ commandCount: number;
26
+ shapeCount?: number;
27
+ };
28
+ aiScanPending?: boolean;
29
+ aiDrive?: 'background' | 'full';
30
+ enrichment?: {
31
+ eligible: number;
32
+ summarized: number;
33
+ embedded: number;
34
+ searchReady?: number;
35
+ pending: number;
36
+ skipped?: number;
37
+ skippedFiles?: Array<{
38
+ path: string;
39
+ attempts: number;
40
+ reason?: string;
41
+ }>;
42
+ shadowsPending?: number;
43
+ embedOnlyPending?: number;
44
+ embedModel?: string;
45
+ vectorsAvailable?: boolean;
46
+ reviews?: {
47
+ eligible: number;
48
+ reviewed: number;
49
+ stale: number;
50
+ pending: number;
51
+ };
52
+ };
53
+ }
54
+ interface IndexReadinessReport {
55
+ version: 1;
56
+ projectId: string;
57
+ generatedAt: string;
58
+ indexingEnabled: boolean;
59
+ staticState: 'fresh' | 'stale' | 'indexing' | 'never' | 'disabled';
60
+ fileCount?: number;
61
+ scannedAt?: string;
62
+ search: {
63
+ ready: boolean;
64
+ eligible?: number;
65
+ embedded?: number;
66
+ pendingEmbedOnly?: number;
67
+ embedModel?: string;
68
+ vectorsAvailable?: boolean;
69
+ };
70
+ aiTier: {
71
+ staffed: boolean;
72
+ paused: boolean;
73
+ achievable: boolean;
74
+ summariesEligible?: number;
75
+ summarized?: number;
76
+ summariesPending?: number;
77
+ shadowsPending?: number;
78
+ skipped?: number;
79
+ reviews?: {
80
+ eligible: number;
81
+ reviewed: number;
82
+ stale: number;
83
+ pending: number;
84
+ };
85
+ };
86
+ wait: {
87
+ budgetMs: number;
88
+ waitedMs: number;
89
+ drained: boolean;
90
+ driveStillRunning: boolean;
91
+ };
92
+ notes: string[];
93
+ }
94
+
95
+ /** Initialization supplied by the sandbox host before a script starts. */
96
+ interface ScriptInit {
97
+ input: unknown;
98
+ runId: string;
99
+ projectId: string;
100
+ engagementMode: 'proactive' | 'scheduled' | 'reactive' | 'off';
101
+ engagementFlags: {
102
+ llmAllowed: boolean;
103
+ };
104
+ }
105
+ /**
106
+ * Host boundary shared by the Node fd-3 and embedded interpreter runtimes.
107
+ * Implementations must dispatch through the host's capability checks, reject
108
+ * outstanding calls when a run is cancelled or disposed, and deliver a
109
+ * notification before returning (or throw if delivery fails). Script runtimes
110
+ * may terminate immediately after `gezel.output()` returns.
111
+ */
112
+ interface ScriptTransport {
113
+ readonly init: ScriptInit;
114
+ call<T = unknown>(method: string, params?: unknown): Promise<T>;
115
+ notify(method: string, params?: unknown): void;
116
+ }
117
+
118
+ /**
119
+ * Portable script SDK for runtimes without Node. A host supplies the
120
+ * initialization payload and a permission-checked RPC transport per run;
121
+ * importing this entry does not access stdin or any platform APIs.
122
+ */
123
+
124
+ /**
125
+ * Type-only helper that preserves the descriptor and lets downstream
126
+ * type inference (on `gezel.input` / the chained `gezel.output` payload)
127
+ * read it. Pass `as const` to get literal inference on choice options.
128
+ */
129
+ declare function defineScript<I extends ScriptInputs | undefined, O extends ScriptOutputs | undefined>(meta: ScriptMeta<I, O>): ScriptMeta<I, O>;
130
+ /** A single entry returned by {@link GezelSDK.fs | `gezel.fs.list`}. */
131
+ interface FsEntry {
132
+ /** Base name of the entry (not the full path), e.g. `index.html`. */
133
+ name: string;
134
+ /** `true` for directories, `false` for regular files. */
135
+ isDirectory: boolean;
136
+ /** Size in bytes. `0` for directories. */
137
+ size: number;
138
+ /** Last-modified time as an ISO-8601 timestamp. */
139
+ modified: string;
140
+ }
141
+ /** Metadata returned by {@link GezelSDK.fs | `gezel.fs.stat`}. */
142
+ interface FsStat {
143
+ /** Size in bytes. */
144
+ size: number;
145
+ /** Last-modified time as an ISO-8601 timestamp. */
146
+ modified: string;
147
+ /** `true` if the path is a directory. */
148
+ isDirectory: boolean;
149
+ /** `true` if the path is a regular file. */
150
+ isFile: boolean;
151
+ }
152
+ /** A single entry returned by {@link GezelSDK.artifacts | `gezel.artifacts.list`}. */
153
+ interface ArtifactEntry {
154
+ /** Artifact path relative to the project's artifact store. */
155
+ path: string;
156
+ /** Size in bytes. */
157
+ size: number;
158
+ /** Last-modified time as an ISO-8601 timestamp. */
159
+ modified: string;
160
+ }
161
+ /** A single entry returned by {@link GezelSDK.documents | `gezel.documents.list`}. */
162
+ interface DocumentEntry {
163
+ /** Document name (its key in the shared document store). */
164
+ name: string;
165
+ /** Size in bytes. */
166
+ size: number;
167
+ /** Last-modified time as an ISO-8601 timestamp. */
168
+ modified: string;
169
+ }
170
+ /** Options for {@link GezelSDK.llm | `gezel.llm.oneShot`}. */
171
+ interface OneShotOpts {
172
+ /**
173
+ * Hard timeout for the completion, in milliseconds. The call rejects
174
+ * if the model has not finished within this window. Defaults to
175
+ * `120000` (2 minutes).
176
+ */
177
+ timeoutMs?: number;
178
+ /**
179
+ * Override the model used for this single call (e.g. `'gemma-12b'`).
180
+ * When omitted, the project's configured default model is used.
181
+ */
182
+ model?: string;
183
+ }
184
+ /** Options for an unauthenticated {@link GezelSDK.http} request. */
185
+ interface HttpRequestOpts {
186
+ /** HTTP method. Defaults to `'GET'`. */
187
+ method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
188
+ /** Raw request body, already serialized. */
189
+ body?: string;
190
+ /** Extra headers. Anonymous requests reject `Authorization`. */
191
+ headers?: Record<string, string>;
192
+ }
193
+ /** Options for {@link GezelSDK.http | `gezel.http.authed`}. */
194
+ interface AuthedHttpOpts {
195
+ /**
196
+ * Short credential name. The script must declare `credential:<name>`
197
+ * in `meta.requires`, and the project must have granted access to it.
198
+ * The service resolves this to a raw secret at dispatch time and
199
+ * attaches the auth header — the script never sees the secret value.
200
+ */
201
+ credential: string;
202
+ /** HTTP method. Defaults to `'GET'`. */
203
+ method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
204
+ /** Raw request body (already serialized — e.g. a JSON string). */
205
+ body?: string;
206
+ /**
207
+ * Extra request headers. The `Authorization` header is added by the
208
+ * service from the resolved credential and will override any value
209
+ * you set here.
210
+ */
211
+ headers?: Record<string, string>;
212
+ /**
213
+ * How the credential is attached to the `Authorization` header:
214
+ * `'bearer'` → `Bearer <value>`, `'basic'` → `Basic <value>`.
215
+ * Defaults to `'bearer'`.
216
+ */
217
+ authScheme?: 'bearer' | 'basic';
218
+ }
219
+ /** The response returned by {@link GezelSDK.http | `gezel.http.authed`}. */
220
+ interface AuthedHttpResponse {
221
+ /** HTTP status code (e.g. `200`, `404`). */
222
+ status: number;
223
+ /** `true` when `status` is in the 2xx range. */
224
+ ok: boolean;
225
+ /** Response headers, lower-cased keys. */
226
+ headers: Record<string, string>;
227
+ /**
228
+ * Response body as text. Any occurrence of the resolved credential
229
+ * value is scrubbed before the body reaches the script. Parse with
230
+ * `JSON.parse(res.body)` when you expect JSON.
231
+ */
232
+ body: string;
233
+ }
234
+ /** Response returned by unauthenticated and credentialed HTTP requests. */
235
+ type HttpResponse = AuthedHttpResponse;
236
+ /**
237
+ * A single step of a task's craftbook, as returned by
238
+ * {@link GezelSDK.task | `gezel.task.steps`} and `gezel.task.currentStep`.
239
+ * This is a curated, read-only view — the internal routing machinery
240
+ * (gates, branches, hook script refs) is intentionally omitted.
241
+ */
242
+ interface TaskStep {
243
+ /** Stable step id — the value used as `phaseId` / routing `goto` elsewhere. */
244
+ id: string;
245
+ /** Human-readable step name. */
246
+ name: string;
247
+ /** Optional longer description of what the step is for. */
248
+ description?: string;
249
+ /**
250
+ * Lifecycle status derived from the task's state: the currently-active
251
+ * step is `'active'`, a step that has been completed is `'complete'`,
252
+ * and any step not yet reached is `'pending'`. (On a loop-back the
253
+ * re-activated step reports `'active'` again.)
254
+ */
255
+ status: 'pending' | 'active' | 'complete';
256
+ /** `true` if this is the task's currently-active step. */
257
+ isActive: boolean;
258
+ /** ISO-8601 timestamp of when the step completed, if it has. */
259
+ completedAt?: string;
260
+ /**
261
+ * How many times this step has been activated. A linear run touches a
262
+ * step once; a looping craftbook re-activates it each pass, so the
263
+ * count climbs. Absent until the step first activates.
264
+ */
265
+ attemptCount?: number;
266
+ /** `true` if this is a terminal step (no further routing after it). */
267
+ terminal?: boolean;
268
+ }
269
+ /** Who authored a {@link TaskNote}. */
270
+ type TaskNoteAuthor = {
271
+ kind: 'user';
272
+ } | {
273
+ kind: 'gezel';
274
+ gezelId: string;
275
+ name: string;
276
+ };
277
+ /** A single note on a task, as returned by `gezel.task.appendNote`. */
278
+ interface TaskNote {
279
+ /** Stable note id (pass to `gezel.task.deleteNote`). */
280
+ id: string;
281
+ /** ISO-8601 timestamp of when the note was written. */
282
+ at: string;
283
+ /** Who wrote the note. Notes written by scripts are authored as the user. */
284
+ author: TaskNoteAuthor;
285
+ /** The step this note is attached to, if any. */
286
+ stepId?: string;
287
+ /** The note text. */
288
+ text: string;
289
+ }
290
+ /** The result of a nested {@link GezelSDK.script | `gezel.script.run`} call. */
291
+ interface ScriptResult<TOutput = unknown> {
292
+ /** Unique id of the nested run, useful for correlating trace logs. */
293
+ runId: string;
294
+ /** `'ok'` if the nested script completed; `'error'` if it threw. */
295
+ status: 'ok' | 'error';
296
+ /**
297
+ * The value the nested script stamped via `gezel.output(...)`.
298
+ * Present only when `status === 'ok'`. Pass a type argument to
299
+ * `script.run<T>()` to type this field.
300
+ */
301
+ output?: TOutput;
302
+ /** Error message when `status === 'error'`; otherwise absent. */
303
+ error?: string;
304
+ }
305
+ /**
306
+ * The `gezel` object — the single entry point a script uses to reach the
307
+ * sandbox host. Every method is a typed proxy over the fd-3 RPC channel;
308
+ * each namespace (`fs`, `artifact`, `task`, …) maps to a capability that
309
+ * must be declared in the script's `meta.requires` (see
310
+ * {@link ScriptCapability}). Calling a method whose capability was not
311
+ * declared rejects with a `CAPABILITY_DENIED` error.
312
+ *
313
+ * @typeParam TInput - Shape of {@link GezelSDK.input | `gezel.input`}.
314
+ * Narrow it with {@link InferredInput} from your `defineScript` meta.
315
+ *
316
+ * @example Read a file, ask the model about it, and stamp the result:
317
+ * ```ts
318
+ * import { gezel, defineScript, type InferredInput } from '@bendyline/gezel-sdk';
319
+ *
320
+ * export const meta = defineScript({
321
+ * name: 'summarize-readme',
322
+ * description: 'Summarize the project README.',
323
+ * inputs: { path: { type: 'string', description: 'File to read', default: 'README.md' } },
324
+ * outputs: { summary: { type: 'string', description: 'One-paragraph summary' } },
325
+ * requires: ['workspace.read', 'llm'],
326
+ * } as const);
327
+ *
328
+ * const input = gezel.input as InferredInput<typeof meta>;
329
+ * const text = await gezel.fs.read(input.path ?? 'README.md');
330
+ * const summary = await gezel.llm.oneShot(`Summarize:\n\n${text}`);
331
+ * gezel.output({ summary });
332
+ * ```
333
+ */
334
+ interface GezelSDK<TInput = Record<string, unknown>> {
335
+ /**
336
+ * Parsed and validated input for this run, populated from the init
337
+ * payload before the first line of user code executes. Cast it to a
338
+ * precise type with {@link InferredInput} for full autocomplete:
339
+ *
340
+ * ```ts
341
+ * const input = gezel.input as InferredInput<typeof meta>;
342
+ * ```
343
+ */
344
+ readonly input: TInput;
345
+ /**
346
+ * Stamp the script's final output. **Call exactly once per run** —
347
+ * a second call throws. For a `gate` script, pass a
348
+ * {@link GateScriptResult}; for an `action` script, pass the object
349
+ * described by `meta.outputs`.
350
+ *
351
+ * @param value - The result payload to record for this run.
352
+ */
353
+ output(value: unknown): void;
354
+ /**
355
+ * Emit a structured log line, captured as part of the ScriptRun
356
+ * trace and also mirrored to stderr. Use it for progress and
357
+ * debugging; it does not affect the script's output.
358
+ *
359
+ * @param args - Values to log. Non-strings are JSON-stringified.
360
+ */
361
+ log(...args: unknown[]): void;
362
+ /**
363
+ * Project **workspace** files (the editable source tree). Paths are
364
+ * relative to the workspace root and sandboxed — they cannot escape
365
+ * it. Requires `workspace.read` for reads and `workspace.write` for
366
+ * writes.
367
+ *
368
+ * @example
369
+ * ```ts
370
+ * const files = await gezel.fs.listAll();
371
+ * const html = await gezel.fs.read('index.html');
372
+ * await gezel.fs.write('out/notes.md', '# Notes\n');
373
+ * ```
374
+ */
375
+ fs: {
376
+ /**
377
+ * Read a workspace file as UTF-8 text.
378
+ * @param path - Workspace-relative path.
379
+ * @returns The file contents.
380
+ * @throws If the file does not exist (`file not found: <path>`).
381
+ */
382
+ read(path: string): Promise<string>;
383
+ /**
384
+ * Write a workspace file, creating parent directories as needed
385
+ * and overwriting any existing file.
386
+ * @param path - Workspace-relative path.
387
+ * @param content - UTF-8 text to write.
388
+ */
389
+ write(path: string, content: string): Promise<void>;
390
+ /**
391
+ * List the immediate children of a directory (non-recursive).
392
+ * @param path - Workspace-relative directory; defaults to the root.
393
+ * @returns Entries for files and subdirectories.
394
+ */
395
+ list(path: string): Promise<FsEntry[]>;
396
+ /**
397
+ * Relative paths of ALL workspace files (recursive, one
398
+ * round-trip). Directories are omitted. Prefer this over walking
399
+ * {@link list} yourself.
400
+ */
401
+ listAll(): Promise<string[]>;
402
+ /**
403
+ * Stat a workspace path.
404
+ * @param path - Workspace-relative path.
405
+ * @returns Size, mtime, and file/directory flags.
406
+ */
407
+ stat(path: string): Promise<FsStat>;
408
+ /**
409
+ * Remove a workspace file.
410
+ * @param path - Workspace-relative path.
411
+ */
412
+ rm(path: string): Promise<void>;
413
+ /**
414
+ * Create a directory in the workspace.
415
+ * @param path - Workspace-relative path.
416
+ * @remarks {@link write} already creates parent directories, so this
417
+ * is only needed to materialize an empty directory.
418
+ */
419
+ mkdir(path: string): Promise<void>;
420
+ /**
421
+ * Rename / move a workspace file.
422
+ * @param from - Existing workspace-relative path.
423
+ * @param to - Destination workspace-relative path.
424
+ */
425
+ rename(from: string, to: string): Promise<void>;
426
+ };
427
+ /**
428
+ * Project **artifacts** — generated output files kept separately from
429
+ * the editable workspace (build products, reports, exports). Requires
430
+ * `artifacts.read` / `artifacts.write`.
431
+ */
432
+ artifacts: {
433
+ /**
434
+ * Read an artifact as UTF-8 text.
435
+ * @throws If the artifact does not exist (`artifact not found: <path>`).
436
+ */
437
+ read(path: string): Promise<string>;
438
+ /** Write (or overwrite) an artifact. */
439
+ write(path: string, content: string): Promise<void>;
440
+ /**
441
+ * List artifacts in one directory of the drawer, or a whole subtree.
442
+ * @param prefix - Directory to list (default: the drawer root).
443
+ * @param opts.recursive - Walk the subtree under `prefix` instead of one
444
+ * level. Returned paths stay relative to the drawer root, so they can
445
+ * be passed straight back to {@link read}. Large subtrees are capped by
446
+ * the walker's entry budget; scope `prefix` to stay inside it.
447
+ */
448
+ list(prefix?: string, opts?: {
449
+ recursive?: boolean;
450
+ }): Promise<ArtifactEntry[]>;
451
+ /** Delete an artifact. */
452
+ delete(path: string): Promise<void>;
453
+ };
454
+ /**
455
+ * Shared **documents** — a project-independent key/value store of
456
+ * named text documents. Requires `documents.read` / `documents.write`.
457
+ */
458
+ documents: {
459
+ /**
460
+ * Read a document by name.
461
+ * @throws If the document does not exist (`document not found: <name>`).
462
+ */
463
+ read(name: string): Promise<string>;
464
+ /** Write (or overwrite) a document by name. */
465
+ write(name: string, content: string): Promise<void>;
466
+ /** List all documents. */
467
+ list(): Promise<DocumentEntry[]>;
468
+ /** Delete a document by name. */
469
+ delete(name: string): Promise<void>;
470
+ };
471
+ /**
472
+ * **Tasks** — read, mutate, and annotate the project's task records.
473
+ * The `ref` is either `"<num>"` (a task number in the current project)
474
+ * or `"<projectId>/<num>"` to reach another project. Requires
475
+ * `tasks.read` for reads and `tasks.write` for mutations.
476
+ */
477
+ task: {
478
+ /**
479
+ * Fetch a task record.
480
+ * @param ref - `"<num>"` or `"<projectId>/<num>"`.
481
+ * @returns The full task object.
482
+ * @throws If the task does not exist (`task not found: <ref>`).
483
+ */
484
+ get(ref: string): Promise<unknown>;
485
+ /**
486
+ * List all steps of the task's craftbook, in order, each with its
487
+ * derived {@link TaskStep.status | status}.
488
+ * @param ref - `"<num>"` or `"<projectId>/<num>"`.
489
+ * @returns The task's steps as curated {@link TaskStep} views.
490
+ *
491
+ * @example
492
+ * ```ts
493
+ * const steps = await gezel.task.steps('7');
494
+ * const done = steps.filter((s) => s.status === 'complete').length;
495
+ * gezel.log(`progress: ${done}/${steps.length}`);
496
+ * ```
497
+ */
498
+ steps(ref: string): Promise<TaskStep[]>;
499
+ /**
500
+ * Get the task's currently-active step.
501
+ * @param ref - `"<num>"` or `"<projectId>/<num>"`.
502
+ * @returns The active {@link TaskStep}, or `null` if no step is active.
503
+ */
504
+ currentStep(ref: string): Promise<TaskStep | null>;
505
+ /**
506
+ * Patch fields on a task (e.g. `title`, `description`, `plan`,
507
+ * `assignee`).
508
+ * @param ref - `"<num>"` or `"<projectId>/<num>"`.
509
+ * @param patch - Partial set of task fields to update.
510
+ * @returns The updated task object.
511
+ */
512
+ update(ref: string, patch: Record<string, unknown>): Promise<unknown>;
513
+ /**
514
+ * Complete the task's currently-active step, advancing the craftbook.
515
+ * Completion gates run as usual; if a gate holds the step the call
516
+ * resolves with a `held` outcome rather than throwing.
517
+ * @param ref - `"<num>"` or `"<projectId>/<num>"`.
518
+ * @param nextPhaseName - Optional step to route to, overriding the
519
+ * craftbook's default next step.
520
+ * @returns The completion outcome (`{ status, task, gate? }`).
521
+ * @throws If the task has no active step to advance.
522
+ */
523
+ advance(ref: string, nextPhaseName?: string): Promise<unknown>;
524
+ /**
525
+ * Append a note to a task (fire-and-forget). Use {@link appendNote}
526
+ * instead when you need the created note back.
527
+ * @param ref - `"<num>"` or `"<projectId>/<num>"`.
528
+ * @param content - The note text.
529
+ * @param phaseId - Optional step id to attach the note to.
530
+ */
531
+ writeNotes(ref: string, content: string, phaseId?: string): Promise<void>;
532
+ /**
533
+ * Append a note to a task and return it — the convenient CRUD form of
534
+ * {@link writeNotes}, handy when you want the generated `id`/`at`.
535
+ * @param ref - `"<num>"` or `"<projectId>/<num>"`.
536
+ * @param text - The note text.
537
+ * @param stepId - Optional step id to attach the note to.
538
+ * @returns The created note.
539
+ */
540
+ appendNote(ref: string, text: string, stepId?: string): Promise<TaskNote>;
541
+ /**
542
+ * Read a task's notes as a single string (note bodies joined by
543
+ * blank lines).
544
+ * @param ref - `"<num>"` or `"<projectId>/<num>"`.
545
+ * @param phaseId - Optional step id to filter notes by.
546
+ * @returns The concatenated note text (empty string if none).
547
+ */
548
+ readNotes(ref: string, phaseId?: string): Promise<string>;
549
+ /**
550
+ * Delete a note from a task by id.
551
+ * @param ref - `"<num>"` or `"<projectId>/<num>"`.
552
+ * @param noteId - The id of the note to remove.
553
+ * @returns The removed note, or `null` if no note with that id existed.
554
+ */
555
+ deleteNote(ref: string, noteId: string): Promise<TaskNote | null>;
556
+ /**
557
+ * Create a new task in the current project.
558
+ * @param req - The create-task request (title, description, craftbook
559
+ * selection, assignee, …).
560
+ * @returns The newly created task object.
561
+ */
562
+ create(req: Record<string, unknown>): Promise<unknown>;
563
+ };
564
+ /**
565
+ * **Memory** — semantic store of prior learnings. Requires
566
+ * `memory.read` / `memory.write`.
567
+ *
568
+ * @example
569
+ * ```ts
570
+ * const hits = await gezel.memory.search('how we handle auth') as
571
+ * { text: string; score: number }[];
572
+ * await gezel.memory.save('Auth uses bearer tokens from the registry.');
573
+ * ```
574
+ */
575
+ memory: {
576
+ /**
577
+ * Semantic search over the project's saved memories.
578
+ * @param query - Natural-language query.
579
+ * @returns Ranked hits, each `{ text, score, day, scope, id, kind }`
580
+ * (highest score first).
581
+ */
582
+ search(query: string): Promise<unknown[]>;
583
+ /**
584
+ * Save a memory to the project's store. Near-duplicate text is
585
+ * skipped automatically.
586
+ * @param text - The fact to remember.
587
+ * @param meta - Optional metadata. A `kind` of `'fact'` |
588
+ * `'decision'` | `'pref'` | `'status'` categorizes the memory;
589
+ * other fields are ignored.
590
+ */
591
+ save(text: string, meta?: Record<string, unknown>): Promise<void>;
592
+ };
593
+ /**
594
+ * **LLM** — one-shot model completions. Requires the `llm` capability,
595
+ * and the project's AI engagement mode must not be `off` (otherwise
596
+ * the call rejects with an engagement error).
597
+ */
598
+ llm: {
599
+ /**
600
+ * Run a single prompt to completion and return the text.
601
+ * @param prompt - The full prompt to send.
602
+ * @param opts - Optional timeout / model override; see {@link OneShotOpts}.
603
+ * @returns The model's text response.
604
+ *
605
+ * @example
606
+ * ```ts
607
+ * const answer = await gezel.llm.oneShot('Name three primary colors.');
608
+ * ```
609
+ */
610
+ oneShot(prompt: string, opts?: OneShotOpts): Promise<string>;
611
+ };
612
+ /**
613
+ * **MCP** — escape hatch to invoke any tool on the shared MCP surface
614
+ * (e.g. GitHub, web fetch). Requires the `network` capability.
615
+ */
616
+ mcp: {
617
+ /**
618
+ * Invoke an MCP tool by name.
619
+ * @param tool - Tool name, e.g. `'github_pr_create'`.
620
+ * @param args - Tool arguments (tool-specific shape).
621
+ * @returns The tool's raw result.
622
+ *
623
+ * @example
624
+ * ```ts
625
+ * const res = await gezel.mcp.call('github_pr_create', {
626
+ * title: 'My change', body: '...', base: 'main',
627
+ * });
628
+ * ```
629
+ */
630
+ call(tool: string, args: unknown): Promise<unknown>;
631
+ };
632
+ /**
633
+ * Credentialed HTTP. The script names the credential it wants to
634
+ * use — the service resolves the value, attaches auth, and returns
635
+ * only the response body + headers. The raw credential value
636
+ * NEVER enters the script's address space.
637
+ *
638
+ * Scripts must declare `credential:<name>` in `meta.requires` for
639
+ * every credential they intend to use (in addition to `network`); the
640
+ * target project must have explicitly granted access to the
641
+ * credential. Missing grants, missing stored values, and missing
642
+ * capability declarations each produce distinct typed errors.
643
+ *
644
+ * @example
645
+ * ```ts
646
+ * const res = await gezel.http.authed('https://api.example.com/me', {
647
+ * credential: 'example-token',
648
+ * });
649
+ * if (res.ok) {
650
+ * const me = JSON.parse(res.body);
651
+ * }
652
+ * ```
653
+ */
654
+ http: {
655
+ /**
656
+ * Perform an unauthenticated HTTP request through the sandbox host.
657
+ * Redirects are returned without being followed.
658
+ */
659
+ request(url: string, opts?: HttpRequestOpts): Promise<HttpResponse>;
660
+ /**
661
+ * Perform an authenticated HTTP request.
662
+ * @param url - Absolute URL to request.
663
+ * @param opts - Method, body, headers, and the credential to use;
664
+ * see {@link AuthedHttpOpts}.
665
+ * @returns Status, headers, and the (secret-scrubbed) body.
666
+ */
667
+ authed(url: string, opts: AuthedHttpOpts): Promise<AuthedHttpResponse>;
668
+ };
669
+ /**
670
+ * The project's **workspace index** — status of the static scan and the
671
+ * AI tiers, plus a bounded "make it fresh" ensure. Requires `index.read`
672
+ * for {@link GezelSDK.index.status | status} and `index.refresh` for
673
+ * {@link GezelSDK.index.ensureFresh | ensureFresh}.
674
+ */
675
+ index: {
676
+ /** Current index status (static state + enrichment/review coverage). */
677
+ status(): Promise<WorkspaceIndexStatus>;
678
+ /**
679
+ * Make the index as fresh as it can get within an awake-time budget:
680
+ * awaited static re-scan, then an AI-tier catch-up drive raced against
681
+ * the budget. Always resolves with an honest readiness report — on a
682
+ * crew with no Boekwachter the AI tiers are reported unachievable
683
+ * rather than awaited, and an expired budget leaves the drive running
684
+ * in the background.
685
+ *
686
+ * @param opts.waitBudgetMs - Awake-time wait budget (default 180s,
687
+ * capped at 240s to stay inside the script run timeout).
688
+ * @param opts.reviews - Also wait for the per-file AI review tier
689
+ * (default true).
690
+ */
691
+ ensureFresh(opts?: {
692
+ waitBudgetMs?: number;
693
+ reviews?: boolean;
694
+ }): Promise<IndexReadinessReport>;
695
+ };
696
+ /**
697
+ * **Nested scripts** — run another script in the same project and get
698
+ * its stamped output back. No capability is required to call, but the
699
+ * nested script runs under its own `meta.requires`. Nesting is limited
700
+ * to 4 levels deep.
701
+ */
702
+ script: {
703
+ /**
704
+ * Run another script by name and await its result.
705
+ * @typeParam TOutput - Expected shape of the nested script's output.
706
+ * @param name - The script's name (not a path), e.g. `'diff-scan'`.
707
+ * @param input - Input object passed to the nested script.
708
+ * @returns A {@link ScriptResult} carrying status, output, or error.
709
+ *
710
+ * @example
711
+ * ```ts
712
+ * const res = await gezel.script.run<{ issues: string[] }>('diff-scan');
713
+ * if (res.status === 'ok') {
714
+ * for (const issue of res.output!.issues) gezel.log(issue);
715
+ * }
716
+ * ```
717
+ */
718
+ run<TOutput = unknown>(name: string, input?: Record<string, unknown>): Promise<ScriptResult<TOutput>>;
719
+ };
720
+ }
721
+ interface GezelSDKOptions {
722
+ /** Optional runtime log sink, in addition to the script.log notification. */
723
+ log?: (...args: unknown[]) => void;
724
+ }
725
+ /**
726
+ * Create a script context with its own input, transport, and output stamp.
727
+ * The transport is privileged host infrastructure: it must enforce the run's
728
+ * capability grants on every call, including notifications. This factory
729
+ * provides the script-facing API; it does not grant filesystem or network access.
730
+ */
731
+ declare function createGezelSDK(rpc: ScriptTransport, options?: GezelSDKOptions): GezelSDK;
732
+ /**
733
+ * Helper for narrowing `gezel.input` to the exact type derived from a
734
+ * `defineScript` meta. Pure type-level alias — nothing to call at
735
+ * runtime. Scripts that want full input typing can do:
736
+ *
737
+ * const input = gezel.input as InferredInput<typeof meta>;
738
+ */
739
+ type InferredInput<M> = M extends ScriptMeta<infer I, infer _O> ? InferInput<I> : never;
740
+ type InferredOutput<M> = M extends ScriptMeta<infer _I, infer O> ? InferOutput<O> : never;
741
+
742
+ export { type ArtifactEntry, type AuthedHttpOpts, type AuthedHttpResponse, type DocumentEntry, type FsEntry, type FsStat, type GezelSDK, type GezelSDKOptions, type HttpRequestOpts, type HttpResponse, type IndexReadinessReport, InferInput, InferOutput, type InferredInput, type InferredOutput, type OneShotOpts, type ScriptInit, ScriptInputs, ScriptMeta, ScriptOutputs, type ScriptResult, type ScriptTransport, type TaskNote, type TaskNoteAuthor, type TaskStep, type WorkspaceIndexStatus, createGezelSDK, defineScript };