@fungi.computer/oyster 0.47.3 → 0.47.5

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.
@@ -702,7 +702,7 @@ export declare const agentFrameMethods: {
702
702
  readonly kind: "workflow-review";
703
703
  readonly installationId: string;
704
704
  readonly workflowId: string | null;
705
- readonly state: "pending" | "closed" | "delivered" | "answered" | "timed_out";
705
+ readonly state: "pending" | "timed_out" | "closed" | "delivered" | "answered";
706
706
  readonly workflowTitle: string;
707
707
  readonly reviewTitle: string;
708
708
  readonly reviewers: "owners" | "runner";
package/dist/workers.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import type { ApprovalListInput, ApprovalAnswerInput, AutoApproveInput } from "@fungi.computer/approvals";
2
2
  import type { HostActor, AppMethodCallContext } from "@fungi.computer/puffball/app";
3
3
  import { type OysterApprovalCall } from "./approval-home.js";
4
+ import { type FrameFailureSlot } from "./frame-failure.js";
4
5
  import { type BootCapabilityGrant, type BootCapabilityLease } from "./boot-capability.js";
5
6
  import { type Installation } from "./apps/installation.js";
6
7
  import { type UiBootCheckOutcome } from "./boot-gate.js";
@@ -33,6 +34,7 @@ import type { AppApi } from "@fungi.computer/puffball";
33
34
  import type { AppDeclaration } from "@fungi.computer/puffball/app";
34
35
  import { createOysterAppSourceReceipts, createOysterAppRegistrations, createOysterArtifactsRepositoryMetadataStore } from "./app-sources.js";
35
36
  export { r2ArtifactStore, r2FileSource, ownerKeyAuth };
37
+ export type { FrameFailure, FrameFailureSlot } from "./frame-failure.js";
36
38
  /** Native values returned by the standalone Git, event and JSON binding owners. */
37
39
  export type OysterBindingResult = Awaited<ReturnType<GitBinding[keyof GitBinding]>> | Schema.Json | undefined;
38
40
  /** Verified backend custody is captured in the frame, never in a current-context field. */
@@ -42,6 +44,8 @@ export type OysterInvocationHost = BackgroundFrameState & Readonly<{
42
44
  count: number;
43
45
  ms: number;
44
46
  };
47
+ /** The reason this frame's own owner failed it, read when its guest call rejects. */
48
+ failure: FrameFailureSlot;
45
49
  artifact: Backend;
46
50
  declaration: AppDeclaration | null;
47
51
  /** The verified declared method; opaque backend and lifecycle frames have none. */
package/dist/workers.js CHANGED
@@ -3,6 +3,7 @@ import { createInstallationStoreGeneration } from "./installation-store-generati
3
3
  import { OysterApprovalHome, } from "./approval-home.js";
4
4
  import { timingSafeEqual } from "node:crypto";
5
5
  import { z } from "zod";
6
+ import { FrameFailureError, createFrameFailureSlot, decodeBindingReply, } from "./frame-failure.js";
6
7
  import { bootCapabilityGrantSchema, bootCapabilityLeaseSchema, reportBootPage, validateCapabilityAssetSet, } from "./boot-capability.js";
7
8
  import { serveBootCapability } from "./boot-capability-route.js";
8
9
  import { installationSchema, isCommittedInstallation, } from "./apps/installation.js";
@@ -528,6 +529,21 @@ function result(run) {
528
529
  causeClass: causeClass(error),
529
530
  code: error.code,
530
531
  };
532
+ if (error instanceof FrameFailureError) {
533
+ console.error("AppInstance failure", {
534
+ stage: "instance_operation",
535
+ code: "failed",
536
+ reason: error.failure.reason,
537
+ ref: error.ref,
538
+ });
539
+ return {
540
+ ok: false,
541
+ causeClass: causeClass(error),
542
+ code: "failed",
543
+ reason: error.failure.reason,
544
+ ref: error.ref,
545
+ };
546
+ }
531
547
  const diagnostic = failureDiagnostic(error);
532
548
  console.error("AppInstance failure", {
533
549
  stage: "instance_operation",
@@ -939,7 +955,7 @@ export class OysterInstance extends DurableObject {
939
955
  if (this.frames.active(props.frameId) !== frame)
940
956
  throw new AppInstanceError("revoked");
941
957
  assertBackgroundBinding(frame, props.binding);
942
- return descriptor.decodeResult(result);
958
+ return decodeBindingReply(descriptor, { binding: props.binding, method }, result, frame.host.failure, { frameId: frame.frameId });
943
959
  }
944
960
  /** Last provider-accepted ref recorded by this installation's journal. */
945
961
  async gitTip(installationId, repository, ref, tenantId = defaultTenant) {
@@ -1063,6 +1079,7 @@ export class OysterInstance extends DurableObject {
1063
1079
  }
1064
1080
  let host = {
1065
1081
  bindingWaits: { count: 0, ms: 0 },
1082
+ failure: createFrameFailureSlot(),
1066
1083
  artifact: { release, ...resolved },
1067
1084
  declaration: resolved.declaration,
1068
1085
  origin: "unchecked",
@@ -1073,12 +1090,22 @@ export class OysterInstance extends DurableObject {
1073
1090
  // checks them against the owner state the host applied to it, never by
1074
1091
  // calling back up to the registry.
1075
1092
  let admitted = verified;
1093
+ let frameRef = "";
1076
1094
  try {
1077
1095
  return await this.frames.run(scoped, host, (frame) => {
1078
1096
  admitted = Date.now();
1097
+ frameRef = frame.frameId;
1079
1098
  return work(this.runtimeFor(limits), frame);
1080
1099
  });
1081
1100
  }
1101
+ catch (cause) {
1102
+ const failure = host.failure.read();
1103
+ // A typed refusal already says why; only a generic rejection takes the
1104
+ // host's own recorded reason.
1105
+ if (failure === undefined || cause instanceof AppInstanceError)
1106
+ throw cause;
1107
+ throw new FrameFailureError(failure, frameRef, { cause });
1108
+ }
1082
1109
  finally {
1083
1110
  reportSlowInvocation(methodName ?? facts.subject.kind, host, {
1084
1111
  entered,
@@ -161,6 +161,39 @@ Method descriptors for the closed App binding vocabulary.
161
161
 
162
162
  ---
163
163
 
164
+ ### FrameBindingEntrypointMethod
165
+
166
+ ```ts
167
+ type FrameBindingEntrypointMethod = Omit<
168
+ FrameBindingMethod<unknown>,
169
+ "decodeResult"
170
+ >;
171
+ ```
172
+
173
+ What the binding entrypoint needs of a method: its argument grammar and
174
+ operation policy. It never decodes a reply; the frame owner does, with the full
175
+ [FrameBindingMethod](#framebindingmethod).
176
+
177
+ ---
178
+
179
+ ### FrameBindingEntrypointMethods
180
+
181
+ ```ts
182
+ type FrameBindingEntrypointMethods = Readonly<
183
+ Partial<
184
+ Record<
185
+ AppBackendBindingName,
186
+ Readonly<Record<string, FrameBindingEntrypointMethod>>
187
+ >
188
+ >
189
+ >;
190
+ ```
191
+
192
+ The entrypoint's view of [FrameBindingMethods](#framebindingmethods): no reply
193
+ decoders.
194
+
195
+ ---
196
+
164
197
  ### AppFacetStub
165
198
 
166
199
  ```ts
@@ -303,6 +336,44 @@ wrap.
303
336
 
304
337
  ---
305
338
 
339
+ ### FrameFailure
340
+
341
+ ```ts
342
+ type FrameFailure = Readonly<{
343
+ reason: Extract<AppFailureReason, "binding_reply_invalid">;
344
+ binding: string;
345
+ method: string;
346
+ path: string;
347
+ }>;
348
+ ```
349
+
350
+ Why one invocation failed on the host's side, written by the frame owner and
351
+ read by the same invocation when its guest call rejects. Only host-known names
352
+ and a field path: a failure that crossed the guest facet is never trusted for
353
+ text.
354
+
355
+ ---
356
+
357
+ ### FrameFailureSlot
358
+
359
+ ```ts
360
+ type FrameFailureSlot = Readonly<{
361
+ record: void;
362
+ read:
363
+ | Readonly<{
364
+ reason: Extract<AppFailureReason, "binding_reply_invalid">;
365
+ binding: string;
366
+ method: string;
367
+ path: string;
368
+ }>
369
+ | undefined;
370
+ }>;
371
+ ```
372
+
373
+ One slot per invocation; the first host failure wins.
374
+
375
+ ---
376
+
306
377
  ### GuestLimits
307
378
 
308
379
  ```ts
@@ -627,10 +698,10 @@ One native binding factory for both Hub and standalone, preserving RPC values.
627
698
 
628
699
  #### Parameters
629
700
 
630
- | Parameter | Type |
631
- | ---------- | --------------------------------------------------------------------------------------------------------- |
632
- | `methods` | [`FrameBindingMethods`](#framebindingmethods)\<`Result`\> |
633
- | `dispatch` | (`env`, `props`, `method`, `args`) => `Promise`\<[`FrameBindingReply`](#framebindingreply)\<`unknown`\>\> |
701
+ | Parameter | Type |
702
+ | ---------- | -------------------------------------------------------------------------------------------------------- |
703
+ | `methods` | [`FrameBindingEntrypointMethods`](#framebindingentrypointmethods) |
704
+ | `dispatch` | (`env`, `props`, `method`, `args`) => `Promise`\<[`FrameBindingReply`](#framebindingreply)\<`Result`\>\> |
634
705
 
635
706
  #### Returns
636
707
 
@@ -756,6 +827,82 @@ Guest code gets only host gatekeeper bindings and no ambient outbound access.
756
827
 
757
828
  [`AppInstance`](index.md#appinstance)\<`Host`\>
758
829
 
830
+ ---
831
+
832
+ ### createFrameFailureSlot()
833
+
834
+ ```ts
835
+ function createFrameFailureSlot(): FrameFailureSlot;
836
+ ```
837
+
838
+ A fresh, empty failure slot for one invocation.
839
+
840
+ #### Returns
841
+
842
+ [`FrameFailureSlot`](#framefailureslot)
843
+
844
+ ---
845
+
846
+ ### rejectedFieldPath()
847
+
848
+ ```ts
849
+ function rejectedFieldPath(cause): string;
850
+ ```
851
+
852
+ The field a reply decoder rejected: the deepest path among its (nested union)
853
+ issues.
854
+
855
+ #### Parameters
856
+
857
+ | Parameter | Type |
858
+ | --------- | ------- |
859
+ | `cause` | `Error` |
860
+
861
+ #### Returns
862
+
863
+ `string`
864
+
865
+ ---
866
+
867
+ ### decodeBindingReply()
868
+
869
+ ```ts
870
+ function decodeBindingReply<Result>(
871
+ descriptor,
872
+ call,
873
+ reply,
874
+ failure,
875
+ logged,
876
+ ): Result;
877
+ ```
878
+
879
+ Decode one connection reply with its method's descriptor: the only place a reply
880
+ is decoded, where it first arrives and the frame that asked is in hand. A reply
881
+ the descriptor rejects is our bug, not the App's: it is recorded on the frame
882
+ (and named in the log, never its values) before the exception reaches the guest,
883
+ which cannot be trusted to say why. `logged` names the frame and invocation in
884
+ that log line.
885
+
886
+ #### Type Parameters
887
+
888
+ | Type Parameter |
889
+ | -------------- |
890
+ | `Result` |
891
+
892
+ #### Parameters
893
+
894
+ | Parameter | Type |
895
+ | ------------ | ----------------------------------------------------------------------------------- |
896
+ | `descriptor` | `Pick`\<[`FrameBindingMethod`](#framebindingmethod)\<`Result`\>, `"decodeResult"`\> |
897
+ | `call` | `Readonly`\<\{ `binding`: `string`; `method`: `string`; \}\> |
898
+ | `reply` | `unknown` |
899
+ | `failure` | [`FrameFailureSlot`](#framefailureslot) |
900
+ | `logged` | `Readonly`\<`Record`\<`string`, `string` \| `null`\>\> |
901
+
902
+ #### Returns
903
+
904
+ `Result`
905
+
759
906
  ## References
760
907
 
761
908
  ### BackgroundFrameState
package/docs/api/host.md CHANGED
@@ -256,6 +256,8 @@ type InstanceResult<T> =
256
256
  | "AbortError"
257
257
  | "TimeoutError"
258
258
  | "Other";
259
+ reason?: AppFailureReason;
260
+ ref?: string;
259
261
  }>;
260
262
  ```
261
263
 
package/docs/api/mcp.md CHANGED
@@ -96,9 +96,15 @@ type ComputerControlPort = Readonly<{
96
96
  running: "running";
97
97
  sleeping: "sleeping";
98
98
  starting: "starting";
99
- start_failed: "start_failed";
100
99
  }>;
101
100
  }
101
+ | {
102
+ state: z.ZodLiteral<"start_failed">;
103
+ }
104
+ | {
105
+ state: z.ZodLiteral<"start_failed">;
106
+ reason: z.ZodString;
107
+ }
102
108
  | {
103
109
  state: z.ZodLiteral<"queued">;
104
110
  position: z.ZodNumber;
@@ -110,9 +116,15 @@ type ComputerControlPort = Readonly<{
110
116
  running: "running";
111
117
  sleeping: "sleeping";
112
118
  starting: "starting";
113
- start_failed: "start_failed";
114
119
  }>;
115
120
  }
121
+ | {
122
+ state: z.ZodLiteral<"start_failed">;
123
+ }
124
+ | {
125
+ state: z.ZodLiteral<"start_failed">;
126
+ reason: z.ZodString;
127
+ }
116
128
  | {
117
129
  state: z.ZodLiteral<"queued">;
118
130
  position: z.ZodNumber;
@@ -274,16 +286,16 @@ One set of schemas and operations for MCP and direct broker invocation.
274
286
  | `state` | `object` | - | - |
275
287
  | `state.replay` | `"safe"` | - | - |
276
288
  | `state.access` | `"read"` | - | - |
277
- | `state.description` | `string` | `"Read runtime state without waking a Computer, including its live admission queue position."` | - |
278
- | `state.input` | `ZodObject`\<\{ `computerId`: `ZodString`; \}, `$strict`\> | `fleetComputerId` | - |
279
- | `state.output` | `ZodDiscriminatedUnion`\<\[`ZodObject`\<\{ `state`: `ZodEnum`\<\{ `running`: `"running"`; `sleeping`: `"sleeping"`; `starting`: `"starting"`; `start_failed`: `"start_failed"`; \}\>; \}, `$strict`\>, `ZodObject`\<\{ `state`: `ZodLiteral`\<`"queued"`\>; `position`: `ZodNumber`; \}, `$strict`\>\], `"state"`\> | `computerStateSchema` | - |
280
- | `state.execute()` | (`input`, `context`) => `Promise`\< \| \{ `state`: `"running"` \| `"sleeping"` \| `"starting"` \| `"start_failed"`; \} \| \{ `state`: `"queued"`; `position`: `number`; \}\> | - | Return liveness without waking the runtime. |
289
+ | `state.description` | `string` | `"Read runtime state without waking a Computer, including its live admission queue position. Pass reason: true to get why a failed start failed."` | - |
290
+ | `state.input` | `ZodObject`\<\{ `computerId`: `ZodString`; `reason`: `ZodExactOptional`\<`ZodLiteral`\<`true`\>\>; \}, `$strict`\> | `fleetStateRead` | - |
291
+ | `state.output` | `ZodUnion`\<readonly \[`ZodObject`\<\{ `state`: `ZodEnum`\<\{ `running`: `"running"`; `sleeping`: `"sleeping"`; `starting`: `"starting"`; \}\>; \}, `$strict`\>, `ZodObject`\<\{ `state`: `ZodLiteral`\<`"start_failed"`\>; \}, `$strict`\>, `ZodObject`\<\{ `state`: `ZodLiteral`\<`"start_failed"`\>; `reason`: `ZodString`; \}, `$strict`\>, `ZodObject`\<\{ `state`: `ZodLiteral`\<`"queued"`\>; `position`: `ZodNumber`; \}, `$strict`\>\]\> | `computerStateSchema` | - |
292
+ | `state.execute()` | (`input`, `context`) => `Promise`\< \| \{ `state`: `"running"` \| `"sleeping"` \| `"starting"`; \} \| \{ `state`: `"start_failed"`; \} \| \{ `state`: `"start_failed"`; `reason`: `string`; \} \| \{ `state`: `"queued"`; `position`: `number`; \}\> | - | Return liveness without waking the runtime. |
281
293
  | `start` | `object` | - | - |
282
294
  | `start.replay` | `"unsafe"` | - | - |
283
295
  | `start.description` | `string` | `"Start a hosted Computer through ordinary admission. Waits until connected; poll computers.state while queued. Safe to retry."` | - |
284
296
  | `start.input` | `ZodObject`\<\{ `computerId`: `ZodString`; \}, `$strict`\> | `fleetComputerId` | - |
285
- | `start.output` | `ZodDiscriminatedUnion`\<\[`ZodObject`\<\{ `state`: `ZodEnum`\<\{ `running`: `"running"`; `sleeping`: `"sleeping"`; `starting`: `"starting"`; `start_failed`: `"start_failed"`; \}\>; \}, `$strict`\>, `ZodObject`\<\{ `state`: `ZodLiteral`\<`"queued"`\>; `position`: `ZodNumber`; \}, `$strict`\>\], `"state"`\> | `computerStateSchema` | - |
286
- | `start.execute()` | (`input`, `context`) => `Promise`\< \| \{ `state`: `"running"` \| `"sleeping"` \| `"starting"` \| `"start_failed"`; \} \| \{ `state`: `"queued"`; `position`: `number`; \}\> | - | Admit and start this Computer. |
297
+ | `start.output` | `ZodUnion`\<readonly \[`ZodObject`\<\{ `state`: `ZodEnum`\<\{ `running`: `"running"`; `sleeping`: `"sleeping"`; `starting`: `"starting"`; \}\>; \}, `$strict`\>, `ZodObject`\<\{ `state`: `ZodLiteral`\<`"start_failed"`\>; \}, `$strict`\>, `ZodObject`\<\{ `state`: `ZodLiteral`\<`"start_failed"`\>; `reason`: `ZodString`; \}, `$strict`\>, `ZodObject`\<\{ `state`: `ZodLiteral`\<`"queued"`\>; `position`: `ZodNumber`; \}, `$strict`\>\]\> | `computerStateSchema` | - |
298
+ | `start.execute()` | (`input`, `context`) => `Promise`\< \| \{ `state`: `"running"` \| `"sleeping"` \| `"starting"`; \} \| \{ `state`: `"start_failed"`; \} \| \{ `state`: `"start_failed"`; `reason`: `string`; \} \| \{ `state`: `"queued"`; `position`: `number`; \}\> | - | Admit and start this Computer. |
287
299
  | `create` | `object` | - | - |
288
300
  | `create.replay` | `"unsafe"` | - | - |
289
301
  | `create.description` | `string` | `"Create a Computer with an optional friendly name and size (small, default or large; default when omitted). Request identity is generated automatically. If the outcome is uncertain, retry with its returned requestId and the original name and size input; do not start a second creation."` | - |
@@ -2117,7 +2117,7 @@ both compose it here.
2117
2117
  | `env` | [`OysterGitEnv`](#oystergitenv) |
2118
2118
  | `scope` | [`TenantScope`](tenant.md#tenantscope) |
2119
2119
  | `hostOwnerRoutes` | \| [`Routes`](authorization.md#routes)\<[`OysterEnv`](host.md#oysterenv)\> \| `undefined` |
2120
- | `agents` | \| `Readonly`\<\{ `list`: `Promise`\<readonly `Readonly`\<\{ `agentId`: `string`; `name`: `string`; `avatar`: \{ `v`: `1`; `character`: `"mushroom"` \| `"cat"` \| `"burger"`; `appearance`: `z.ZodRecord`\<`z.ZodString`, `z.ZodUnion`\<readonly ...\>\>; `expression`: `string`; `renderStyle`: \| `"plain"` \| `"pencil"` \| `"manga"` \| `"riso"` \| `"halftone"` \| `"blueprint"` \| `"crt"` \| `"watercolor"`; \}; `sessionOperations`: readonly (`"agent.manage"` \| `"agent.read"` \| `"agent.send"`)[]; \}\>[]\>; `ensureStarter`: `Promise`\<[`StarterOutcome`](agents.md#starteroutcome)\>; `setArchived`: `Promise`\< \| `Readonly`\<\{ `archived`: `boolean`; `revision`: `number`; \}\> \| `Readonly`\<\{ `error`: \| `"archived"` \| `"pending"` \| `"not_found"` \| `"running"` \| `"not_granted"` \| `"self"` \| `"not_creator"` \| `"unreadable"`; `message?`: `string`; `archived?`: `boolean`; `revision?`: `number`; \}\>\>; `create`: `Promise`\<`Readonly`\<\{ `agentId`: `string`; `name`: `string`; `avatar`: \{ `v`: `1`; `character`: `"mushroom"` \| `"cat"` \| `"burger"`; `appearance`: `z.ZodRecord`\<`z.ZodString`, `z.ZodUnion`\<readonly \[..., ..., ...\]\>\>; `expression`: `string`; `renderStyle`: \| `"plain"` \| `"pencil"` \| `"manga"` \| `"riso"` \| `"halftone"` \| `"blueprint"` \| `"crt"` \| `"watercolor"`; \}; `sessionOperations`: readonly (`"agent.manage"` \| `"agent.read"` \| `"agent.send"`)[]; \}\>\>; `rename`: `Promise`\< \| `Readonly`\<\{ `agentId`: `string`; `name`: `string`; `avatar`: \{ `v`: `1`; `character`: `"mushroom"` \| `"cat"` \| `"burger"`; `appearance`: `z.ZodRecord`\<`z.ZodString`, `z.ZodUnion`\<readonly ...\>\>; `expression`: `string`; `renderStyle`: \| `"plain"` \| `"pencil"` \| `"manga"` \| `"riso"` \| `"halftone"` \| `"blueprint"` \| `"crt"` \| `"watercolor"`; \}; `sessionOperations`: readonly (`"agent.manage"` \| `"agent.read"` \| `"agent.send"`)[]; \}\> \| `Readonly`\<\{ `error`: `"not_found"` \| `"not_granted"` \| `"name_taken"`; \}\>\>; `setAvatar`: `Promise`\< \| `Readonly`\<\{ `agentId`: `string`; `name`: `string`; `avatar`: \{ `v`: `1`; `character`: `"mushroom"` \| `"cat"` \| `"burger"`; `appearance`: `z.ZodRecord`\<`z.ZodString`, `z.ZodUnion`\<readonly ...\>\>; `expression`: `string`; `renderStyle`: \| `"plain"` \| `"pencil"` \| `"manga"` \| `"riso"` \| `"halftone"` \| `"blueprint"` \| `"crt"` \| `"watercolor"`; \}; `sessionOperations`: readonly (`"agent.manage"` \| `"agent.read"` \| `"agent.send"`)[]; \}\> \| `Readonly`\<\{ `error`: `"not_found"` \| `"not_granted"`; \}\>\>; `readModelChoice`: `Promise`\< \| \{ `keySource`: `"workers-ai"` \| `"ai-gateway"` \| `"byok"`; `model`: \{ `providerId`: `string`; `modelId`: `string`; `reasoning?`: `"max"` \| `"low"` \| `"medium"` \| `"high"` \| `"minimal"` \| `"xhigh"`; \}; `keyId?`: `string`; \} \| `null`\>; `readInstructions`: `Promise`\< \| `Readonly`\<`object` & `Readonly`\<\{ `home`: `Readonly`\<...\> \| `null`; `content`: `string` \| `null`; `bytes`: `number`; `limit`: `number`; \}\>\> \| `Readonly`\<\{ `error`: `"not_found"` \| `"not_granted"`; \}\>\>; `setInstructions`: `Promise`\< \| `Readonly`\<`object` & `Readonly`\<\{ `home`: `Readonly`\<...\> \| `null`; `content`: `string` \| `null`; `bytes`: `number`; `limit`: `number`; \}\>\> \| `Readonly`\<\{ `error`: `"conflict"` \| `"not_found"` \| `"not_granted"` \| `"too_large"` \| `"no_home"`; \}\>\>; `decodeModelChoice`: \| \{ `keySource`: `"workers-ai"` \| `"ai-gateway"` \| `"byok"`; `model`: \{ `providerId`: `string`; `modelId`: `string`; `reasoning?`: `"max"` \| `"low"` \| `"medium"` \| `"high"` \| `"minimal"` \| `"xhigh"`; \}; `keyId?`: `string`; \} \| `null`; `setModelChoice`: `Promise`\< \| \{ `keySource`: `"workers-ai"` \| `"ai-gateway"` \| `"byok"`; `model`: \{ `providerId`: `string`; `modelId`: `string`; `reasoning?`: `"max"` \| `"low"` \| `"medium"` \| `"high"` \| `"minimal"` \| `"xhigh"`; \}; `keyId?`: `string`; \} \| `Readonly`\<\{ `error`: \| `"not_found"` \| `"not_granted"` \| [`AgentModelRefusal`](agents.md#agentmodelrefusal); \}\>\>; `policyStatus`: `Promise`\< \| `Readonly`\<\{ `status`: `"pending"` \| `"approved"`; `revision`: `string`; \}\> \| `null`\>; `appToolPolicy`: `Promise`\< \| \{ `level`: `"read"` \| `"write"`; `revision`: `string`; `grantedBy`: `string`; \} \| `null`\>; `policyRevision`: `Promise`\<`string` \| `null`\>; `approveAppToolPolicy`: `Promise`\< \| \{ `level`: `"read"` \| `"write"`; `revision`: `string`; `grantedBy`: `string`; \} \| `Readonly`\<\{ `status`: `"pending"`; `revision`: `string`; \}\> \| `Readonly`\<\{ `error`: `"not_found"` \| `"not_granted"` \| `"revision_conflict"`; \}\>\>; `setup`: `Promise`\<`Readonly`\<\{ `models`: `"ready"` \| `"missing"`; `media`: `"ready"` \| `"missing"`; \}\>\>; `modelKeys`: `Promise`\<readonly `Readonly`\<\{ `keyId`: `string`; `provider`: [`StandaloneModelKeyProvider`](agents.md#standalonemodelkeyprovider); `label`: `string`; `createdAt`: `number`; `validatedAt`: `number`; \}\>[]\>; `sealModelKey`: `Promise`\< \| `Readonly`\<\{ `keyId`: `string`; `provider`: [`StandaloneModelKeyProvider`](agents.md#standalonemodelkeyprovider); `label`: `string`; `createdAt`: `number`; `validatedAt`: `number`; \}\> \| `Readonly`\<\{ `error`: [`ModelKeyRefusal`](agents.md#modelkeyrefusal); \}\>\>; `removeModelKey`: `Promise`\<`"deleted"` \| `"absent"`\>; `vault`: `Promise`\<[`VaultResult`](agents.md#vaultresult)\>; `connections`: `Promise`\<readonly `Readonly`\<\{ `connectionId`: `string`; `name`: `string`; `label`: `string`; `kind`: `"mcp"` \| `"openapi"`; `url`: `string`; `auth`: `"none"` \| `"oauth"` \| `"token"`; `state`: `"pending"` \| `"connected"` \| `"reconnect_required"`; `grants`: readonly `Readonly`\<\{ `agentId`: `string`; `access`: [`ConnectionAccess`](agents.md#connectionaccess); \}\>[]; \}\>[]\>; `addConnection`: `Promise`\< \| `Readonly`\<\{ `error`: `"limit"` \| `"not_found"` \| `"duplicate_name"` \| `"invalid_endpoint"`; \}\> \| `Readonly`\<\{ `connectionId`: `string`; `authorizeUrl`: `string` \| `null`; \}\>\>; `grantConnection`: `Promise`\< \| `Readonly`\<\{ `error`: `"limit"` \| `"not_found"` \| `"duplicate_name"` \| `"invalid_endpoint"`; \}\> \| `Readonly`\<\{ `ok`: `true`; \}\>\>; `ungrantConnection`: `Promise`\<`boolean`\>; `removeConnection`: `Promise`\<`boolean`\>; `connectionTools`: `Promise`\< \| readonly `string`[] \| `Readonly`\<\{ `error`: `"limit"` \| `"not_found"` \| `"duplicate_name"` \| `"invalid_endpoint"`; \}\>\>; `completeMcpConnection`: `Promise`\< \| `Readonly`\<\{ `ok`: `true`; \}\> \| `Readonly`\<\{ `error`: `string`; \}\>\>; `mcpCallbackUrl`: `string`; `fetch`: `Promise`\<`Response` \| `null`\>; `inbox`: `Promise`\<`Readonly`\<\{ `items`: readonly ( \| \{ `agentId`: `string`; `sessionId`: `string`; `title`: `string`; `triggerId?`: `string`; `createdAt`: `number`; `lastActivityAt`: `number`; `settledAt?`: `number`; `visitedAt?`: `number`; `state`: `"running"` \| `"done"` \| `"errored"` \| `"needs_you"`; \} \| \{ `agentId`: `string`; `sessionId`: `string`; `state`: `"unavailable"`; \} \| \{ `kind`: `"workflow-review"`; `key`: \{ `runId`: `string`; `nodeId`: `string`; `iteration`: `string`; \}; `installationId`: `string`; `workflowId`: `string` \| `null`; `workflowTitle`: `string`; `reviewTitle`: `string`; `reviewers`: `"owners"` \| `"runner"`; `show`: readonly `Json`[]; `choices?`: readonly ...[]; `openedAt`: `number`; `expiresAt`: `number`; `state`: `"pending"` \| `"closed"` \| `"delivered"` \| `"answered"` \| `"timed_out"`; \})[]; `revision`: `number`; \}\>\>; `revision`: `Promise`\<`number`\>; `visit`: `Promise`\<`boolean`\>; \}\> \| `undefined` |
2120
+ | `agents` | \| `Readonly`\<\{ `list`: `Promise`\<readonly `Readonly`\<\{ `agentId`: `string`; `name`: `string`; `avatar`: \{ `v`: `1`; `character`: `"mushroom"` \| `"cat"` \| `"burger"`; `appearance`: `z.ZodRecord`\<`z.ZodString`, `z.ZodUnion`\<readonly ...\>\>; `expression`: `string`; `renderStyle`: \| `"plain"` \| `"pencil"` \| `"manga"` \| `"riso"` \| `"halftone"` \| `"blueprint"` \| `"crt"` \| `"watercolor"`; \}; `sessionOperations`: readonly (`"agent.manage"` \| `"agent.read"` \| `"agent.send"`)[]; \}\>[]\>; `ensureStarter`: `Promise`\<[`StarterOutcome`](agents.md#starteroutcome)\>; `setArchived`: `Promise`\< \| `Readonly`\<\{ `archived`: `boolean`; `revision`: `number`; \}\> \| `Readonly`\<\{ `error`: \| `"archived"` \| `"pending"` \| `"not_found"` \| `"running"` \| `"not_granted"` \| `"self"` \| `"not_creator"` \| `"unreadable"`; `message?`: `string`; `archived?`: `boolean`; `revision?`: `number`; \}\>\>; `create`: `Promise`\<`Readonly`\<\{ `agentId`: `string`; `name`: `string`; `avatar`: \{ `v`: `1`; `character`: `"mushroom"` \| `"cat"` \| `"burger"`; `appearance`: `z.ZodRecord`\<`z.ZodString`, `z.ZodUnion`\<readonly \[..., ..., ...\]\>\>; `expression`: `string`; `renderStyle`: \| `"plain"` \| `"pencil"` \| `"manga"` \| `"riso"` \| `"halftone"` \| `"blueprint"` \| `"crt"` \| `"watercolor"`; \}; `sessionOperations`: readonly (`"agent.manage"` \| `"agent.read"` \| `"agent.send"`)[]; \}\>\>; `rename`: `Promise`\< \| `Readonly`\<\{ `agentId`: `string`; `name`: `string`; `avatar`: \{ `v`: `1`; `character`: `"mushroom"` \| `"cat"` \| `"burger"`; `appearance`: `z.ZodRecord`\<`z.ZodString`, `z.ZodUnion`\<readonly ...\>\>; `expression`: `string`; `renderStyle`: \| `"plain"` \| `"pencil"` \| `"manga"` \| `"riso"` \| `"halftone"` \| `"blueprint"` \| `"crt"` \| `"watercolor"`; \}; `sessionOperations`: readonly (`"agent.manage"` \| `"agent.read"` \| `"agent.send"`)[]; \}\> \| `Readonly`\<\{ `error`: `"not_found"` \| `"not_granted"` \| `"name_taken"`; \}\>\>; `setAvatar`: `Promise`\< \| `Readonly`\<\{ `agentId`: `string`; `name`: `string`; `avatar`: \{ `v`: `1`; `character`: `"mushroom"` \| `"cat"` \| `"burger"`; `appearance`: `z.ZodRecord`\<`z.ZodString`, `z.ZodUnion`\<readonly ...\>\>; `expression`: `string`; `renderStyle`: \| `"plain"` \| `"pencil"` \| `"manga"` \| `"riso"` \| `"halftone"` \| `"blueprint"` \| `"crt"` \| `"watercolor"`; \}; `sessionOperations`: readonly (`"agent.manage"` \| `"agent.read"` \| `"agent.send"`)[]; \}\> \| `Readonly`\<\{ `error`: `"not_found"` \| `"not_granted"`; \}\>\>; `readModelChoice`: `Promise`\< \| \{ `keySource`: `"workers-ai"` \| `"ai-gateway"` \| `"byok"`; `model`: \{ `providerId`: `string`; `modelId`: `string`; `reasoning?`: `"max"` \| `"low"` \| `"medium"` \| `"high"` \| `"minimal"` \| `"xhigh"`; \}; `keyId?`: `string`; \} \| `null`\>; `readInstructions`: `Promise`\< \| `Readonly`\<`object` & `Readonly`\<\{ `home`: `Readonly`\<...\> \| `null`; `content`: `string` \| `null`; `bytes`: `number`; `limit`: `number`; \}\>\> \| `Readonly`\<\{ `error`: `"not_found"` \| `"not_granted"`; \}\>\>; `setInstructions`: `Promise`\< \| `Readonly`\<`object` & `Readonly`\<\{ `home`: `Readonly`\<...\> \| `null`; `content`: `string` \| `null`; `bytes`: `number`; `limit`: `number`; \}\>\> \| `Readonly`\<\{ `error`: `"conflict"` \| `"not_found"` \| `"not_granted"` \| `"too_large"` \| `"no_home"`; \}\>\>; `decodeModelChoice`: \| \{ `keySource`: `"workers-ai"` \| `"ai-gateway"` \| `"byok"`; `model`: \{ `providerId`: `string`; `modelId`: `string`; `reasoning?`: `"max"` \| `"low"` \| `"medium"` \| `"high"` \| `"minimal"` \| `"xhigh"`; \}; `keyId?`: `string`; \} \| `null`; `setModelChoice`: `Promise`\< \| \{ `keySource`: `"workers-ai"` \| `"ai-gateway"` \| `"byok"`; `model`: \{ `providerId`: `string`; `modelId`: `string`; `reasoning?`: `"max"` \| `"low"` \| `"medium"` \| `"high"` \| `"minimal"` \| `"xhigh"`; \}; `keyId?`: `string`; \} \| `Readonly`\<\{ `error`: \| `"not_found"` \| `"not_granted"` \| [`AgentModelRefusal`](agents.md#agentmodelrefusal); \}\>\>; `policyStatus`: `Promise`\< \| `Readonly`\<\{ `status`: `"pending"` \| `"approved"`; `revision`: `string`; \}\> \| `null`\>; `appToolPolicy`: `Promise`\< \| \{ `level`: `"read"` \| `"write"`; `revision`: `string`; `grantedBy`: `string`; \} \| `null`\>; `policyRevision`: `Promise`\<`string` \| `null`\>; `approveAppToolPolicy`: `Promise`\< \| \{ `level`: `"read"` \| `"write"`; `revision`: `string`; `grantedBy`: `string`; \} \| `Readonly`\<\{ `status`: `"pending"`; `revision`: `string`; \}\> \| `Readonly`\<\{ `error`: `"not_found"` \| `"not_granted"` \| `"revision_conflict"`; \}\>\>; `setup`: `Promise`\<`Readonly`\<\{ `models`: `"ready"` \| `"missing"`; `media`: `"ready"` \| `"missing"`; \}\>\>; `modelKeys`: `Promise`\<readonly `Readonly`\<\{ `keyId`: `string`; `provider`: [`StandaloneModelKeyProvider`](agents.md#standalonemodelkeyprovider); `label`: `string`; `createdAt`: `number`; `validatedAt`: `number`; \}\>[]\>; `sealModelKey`: `Promise`\< \| `Readonly`\<\{ `keyId`: `string`; `provider`: [`StandaloneModelKeyProvider`](agents.md#standalonemodelkeyprovider); `label`: `string`; `createdAt`: `number`; `validatedAt`: `number`; \}\> \| `Readonly`\<\{ `error`: [`ModelKeyRefusal`](agents.md#modelkeyrefusal); \}\>\>; `removeModelKey`: `Promise`\<`"deleted"` \| `"absent"`\>; `vault`: `Promise`\<[`VaultResult`](agents.md#vaultresult)\>; `connections`: `Promise`\<readonly `Readonly`\<\{ `connectionId`: `string`; `name`: `string`; `label`: `string`; `kind`: `"mcp"` \| `"openapi"`; `url`: `string`; `auth`: `"none"` \| `"oauth"` \| `"token"`; `state`: `"pending"` \| `"connected"` \| `"reconnect_required"`; `grants`: readonly `Readonly`\<\{ `agentId`: `string`; `access`: [`ConnectionAccess`](agents.md#connectionaccess); \}\>[]; \}\>[]\>; `addConnection`: `Promise`\< \| `Readonly`\<\{ `error`: `"limit"` \| `"not_found"` \| `"duplicate_name"` \| `"invalid_endpoint"`; \}\> \| `Readonly`\<\{ `connectionId`: `string`; `authorizeUrl`: `string` \| `null`; \}\>\>; `grantConnection`: `Promise`\< \| `Readonly`\<\{ `error`: `"limit"` \| `"not_found"` \| `"duplicate_name"` \| `"invalid_endpoint"`; \}\> \| `Readonly`\<\{ `ok`: `true`; \}\>\>; `ungrantConnection`: `Promise`\<`boolean`\>; `removeConnection`: `Promise`\<`boolean`\>; `connectionTools`: `Promise`\< \| readonly `string`[] \| `Readonly`\<\{ `error`: `"limit"` \| `"not_found"` \| `"duplicate_name"` \| `"invalid_endpoint"`; \}\>\>; `completeMcpConnection`: `Promise`\< \| `Readonly`\<\{ `ok`: `true`; \}\> \| `Readonly`\<\{ `error`: `string`; \}\>\>; `mcpCallbackUrl`: `string`; `fetch`: `Promise`\<`Response` \| `null`\>; `inbox`: `Promise`\<`Readonly`\<\{ `items`: readonly ( \| \{ `agentId`: `string`; `sessionId`: `string`; `title`: `string`; `triggerId?`: `string`; `createdAt`: `number`; `lastActivityAt`: `number`; `settledAt?`: `number`; `visitedAt?`: `number`; `state`: `"running"` \| `"done"` \| `"errored"` \| `"needs_you"`; \} \| \{ `agentId`: `string`; `sessionId`: `string`; `state`: `"unavailable"`; \} \| \{ `kind`: `"workflow-review"`; `key`: \{ `runId`: `string`; `nodeId`: `string`; `iteration`: `string`; \}; `installationId`: `string`; `workflowId`: `string` \| `null`; `workflowTitle`: `string`; `reviewTitle`: `string`; `reviewers`: `"owners"` \| `"runner"`; `show`: readonly `Json`[]; `choices?`: readonly ...[]; `openedAt`: `number`; `expiresAt`: `number`; `state`: `"pending"` \| `"timed_out"` \| `"closed"` \| `"delivered"` \| `"answered"`; \})[]; `revision`: `number`; \}\>\>; `revision`: `Promise`\<`number`\>; `visit`: `Promise`\<`boolean`\>; \}\> \| `undefined` |
2121
2121
  | `computerSetup?` | () => `Promise`\<`Pick`\<`Readonly`\<\{ `models`: `SetupState`; `media`: `SetupState`; `git`: `SetupState`; `terminal`: `"unknown"` \| `"ready"` \| `"missing"` \| `"exec-only"`; `terminalReason?`: `string`; \}\>, `"terminal"` \| `"terminalReason"`\>\> |
2122
2122
 
2123
2123
  #### Returns