@fungi.computer/oyster 0.8.2 → 0.10.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.
Files changed (72) hide show
  1. package/README.md +34 -17
  2. package/dist/agents.d.ts +16 -1
  3. package/dist/agents.js +63 -3
  4. package/dist/apps/catalog.d.ts +11 -0
  5. package/dist/apps/catalog.js +1 -0
  6. package/dist/apps/gate.d.ts +2 -2
  7. package/dist/apps/installation.d.ts +7 -7
  8. package/dist/apps/permissions.d.ts +5 -5
  9. package/dist/boot-host-script.js +1 -1
  10. package/dist/build/candidate-cli.mjs +1 -0
  11. package/dist/computer-control-port.d.ts +20 -1
  12. package/dist/host.js +11 -4
  13. package/dist/installation-client.d.ts +6 -5
  14. package/dist/installation-client.js +21 -17
  15. package/dist/installation-execution.js +41 -8
  16. package/dist/installation-operations.d.ts +30 -8
  17. package/dist/installation-operations.js +122 -24
  18. package/dist/instance-refusal.d.ts +4 -2
  19. package/dist/instance-refusal.js +5 -1
  20. package/dist/mcp.d.ts +132 -2
  21. package/dist/mcp.js +63 -1
  22. package/dist/page/mount.d.ts +8 -1
  23. package/dist/page/mount.js +72 -6
  24. package/dist/page-script.js +3 -3
  25. package/dist/standalone/agent-computers.d.ts +12 -1
  26. package/dist/standalone/agent-computers.js +35 -0
  27. package/dist/standalone/agent-connections.d.ts +47 -0
  28. package/dist/standalone/agent-connections.js +170 -0
  29. package/dist/standalone/agent-model-choice.d.ts +7 -3
  30. package/dist/standalone/agent-model-choice.js +33 -4
  31. package/dist/standalone/agents.d.ts +70 -9
  32. package/dist/standalone/agents.js +187 -110
  33. package/dist/standalone/app-set.js +6 -7
  34. package/dist/standalone/browser.d.ts +4 -3
  35. package/dist/standalone/browser.js +4 -3
  36. package/dist/standalone/computer-control.js +55 -1
  37. package/dist/standalone/computer-fleet.d.ts +29 -2
  38. package/dist/standalone/computer-fleet.js +51 -23
  39. package/dist/standalone/computer.d.ts +20 -1
  40. package/dist/standalone/computer.js +63 -1
  41. package/dist/standalone/model-key-vault.d.ts +50 -0
  42. package/dist/standalone/model-key-vault.js +147 -0
  43. package/dist/standalone/registry.d.ts +23 -0
  44. package/dist/standalone/registry.js +39 -0
  45. package/dist/standalone/web.d.ts +10 -0
  46. package/dist/standalone/web.js +34 -0
  47. package/dist/standalone/worker-routes.d.ts +3 -1
  48. package/dist/standalone/worker-routes.js +1 -0
  49. package/dist/standalone/worker.js +9 -1
  50. package/dist/standalone/workflow-host.d.ts +5 -5
  51. package/dist/standalone/workflow-trigger-host.d.ts +1 -1
  52. package/dist/web/index.d.ts +3 -0
  53. package/dist/web/index.js +3 -0
  54. package/dist/web/search-contract.d.ts +19 -0
  55. package/dist/web/search-contract.js +14 -0
  56. package/dist/web/search.d.ts +25 -0
  57. package/dist/web/search.js +123 -0
  58. package/dist/web/source.d.ts +46 -0
  59. package/dist/web/source.js +335 -0
  60. package/dist/workers-git.js +2 -1
  61. package/docs/api/agents.md +81 -3
  62. package/docs/api/apps.md +160 -142
  63. package/docs/api/build-contract.md +27 -21
  64. package/docs/api/build.md +55 -54
  65. package/docs/api/git.md +3 -3
  66. package/docs/api/host.md +226 -60
  67. package/docs/api/mcp.md +83 -44
  68. package/docs/api/page/mount.md +6 -1
  69. package/docs/api/workers-git.md +6 -6
  70. package/docs/api/workers.md +53 -47
  71. package/docs/site/agent-quickstart.mdx +4 -2
  72. package/package.json +27 -22
package/docs/api/mcp.md CHANGED
@@ -91,6 +91,7 @@ type ComputerControlPort = Readonly<{
91
91
  running: "running";
92
92
  sleeping: "sleeping";
93
93
  starting: "starting";
94
+ start_failed: "start_failed";
94
95
  }>;
95
96
  }
96
97
  | {
@@ -104,6 +105,7 @@ type ComputerControlPort = Readonly<{
104
105
  running: "running";
105
106
  sleeping: "sleeping";
106
107
  starting: "starting";
108
+ start_failed: "start_failed";
107
109
  }>;
108
110
  }
109
111
  | {
@@ -123,6 +125,25 @@ type ComputerControlPort = Readonly<{
123
125
  kind: "uncertain" | "denied" | "conflict" | "invalid";
124
126
  }
125
127
  >;
128
+ backends: Promise<object[]>;
129
+ attachLocal: Promise<
130
+ | {
131
+ kind: "attached";
132
+ backendId: string;
133
+ }
134
+ | {
135
+ kind: "uncertain" | "denied" | "conflict" | "invalid";
136
+ }
137
+ >;
138
+ detachLocal: Promise<
139
+ | {
140
+ kind: "detached";
141
+ detached: boolean;
142
+ }
143
+ | {
144
+ kind: "denied" | "uncertain" | "invalid";
145
+ }
146
+ >;
126
147
  }>;
127
148
  ```
128
149
 
@@ -235,34 +256,52 @@ One set of schemas and operations for MCP and direct broker invocation.
235
256
 
236
257
  `object`
237
258
 
238
- | Name | Type | Default value | Description |
239
- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
240
- | `list` | `object` | - | - |
241
- | `list.replay` | `"safe"` | - | - |
242
- | `list.access` | `"read"` | - | - |
243
- | `list.description` | `string` | `"List a page of permitted Computers. Follow nextOffset for another page."` | - |
244
- | `list.input` | `ZodObject`\<\{ `limit`: `ZodDefault`\<`ZodNumber`\>; `offset`: `ZodDefault`\<`ZodNumber`\>; \}, `$strict`\> | `computerPageSchema` | - |
245
- | `list.output` | `ZodObject`\<\{ `computers`: `ZodArray`\<`ZodObject`\<\{ `computerId`: `ZodString`; `name`: `ZodString`; `createdAt`: `ZodNumber`; `updatedAt`: `ZodNumber`; \}, `$strict`\>\>; `nextOffset`: `ZodNullable`\<`ZodNumber`\>; \}, `$strict`\> | `teamComputerDirectorySchema` | - |
246
- | `list.execute()` | (`input`, `context`) => `Promise`\<\{ `computers`: `object`[]; `nextOffset`: `number` \| `null`; \}\> | - | Return an admitted inventory page to MCP or the retained broker. |
247
- | `state` | `object` | - | - |
248
- | `state.replay` | `"safe"` | - | - |
249
- | `state.access` | `"read"` | - | - |
250
- | `state.description` | `string` | `"Read runtime state without waking a Computer, including its live admission queue position."` | - |
251
- | `state.input` | `ZodObject`\<\{ `computerId`: `ZodString`; \}, `$strict`\> | `fleetComputerId` | - |
252
- | `state.output` | `ZodDiscriminatedUnion`\<\[`ZodObject`\<\{ `state`: `ZodEnum`\<\{ `running`: `"running"`; `sleeping`: `"sleeping"`; `starting`: `"starting"`; \}\>; \}, `$strict`\>, `ZodObject`\<\{ `state`: `ZodLiteral`\<`"queued"`\>; `position`: `ZodNumber`; \}, `$strict`\>\], `"state"`\> | `computerStateSchema` | - |
253
- | `state.execute()` | (`input`, `context`) => `Promise`\< \| \{ `state`: `"running"` \| `"sleeping"` \| `"starting"`; \} \| \{ `state`: `"queued"`; `position`: `number`; \}\> | - | Return liveness without waking the runtime. |
254
- | `start` | `object` | - | - |
255
- | `start.replay` | `"unsafe"` | - | - |
256
- | `start.description` | `string` | `"Start a hosted Computer through ordinary admission. Waits until connected; poll computers.state while queued. Safe to retry."` | - |
257
- | `start.input` | `ZodObject`\<\{ `computerId`: `ZodString`; \}, `$strict`\> | `fleetComputerId` | - |
258
- | `start.output` | `ZodDiscriminatedUnion`\<\[`ZodObject`\<\{ `state`: `ZodEnum`\<\{ `running`: `"running"`; `sleeping`: `"sleeping"`; `starting`: `"starting"`; \}\>; \}, `$strict`\>, `ZodObject`\<\{ `state`: `ZodLiteral`\<`"queued"`\>; `position`: `ZodNumber`; \}, `$strict`\>\], `"state"`\> | `computerStateSchema` | - |
259
- | `start.execute()` | (`input`, `context`) => `Promise`\< \| \{ `state`: `"running"` \| `"sleeping"` \| `"starting"`; \} \| \{ `state`: `"queued"`; `position`: `number`; \}\> | - | Admit and start this Computer. |
260
- | `create` | `object` | - | - |
261
- | `create.replay` | `"unsafe"` | - | - |
262
- | `create.description` | `string` | `"Create a Computer with an optional friendly name. Request identity is generated automatically. If the outcome is uncertain, retry with its returned requestId and the original name input; do not start a second creation."` | - |
263
- | `create.input` | `ZodObject`\<\{ `name`: `ZodDefault`\<`ZodNullable`\<`ZodString`\>\>; `requestId`: `ZodDefault`\<`ZodNullable`\<`ZodString`\>\>; \}, `$strict`\> | `fleetCreate` | - |
264
- | `create.output` | `ZodDiscriminatedUnion`\<\[`ZodObject`\<\{ `kind`: `ZodLiteral`\<`"created"`\>; `requestId`: `ZodString`; `computer`: `ZodObject`\<\{ `computerId`: `ZodString`; `name`: `ZodString`; \}, `$strict`\>; \}, `$strict`\>, `ZodObject`\<\{ `kind`: `ZodEnum`\<\{ `invalid`: `"invalid"`; `conflict`: `"conflict"`; `denied`: `"denied"`; `uncertain`: `"uncertain"`; \}\>; `requestId`: `ZodString`; \}, `$strict`\>\], `"kind"`\> | `fleetCreation` | - |
265
- | `create.execute()` | (`input`, `context`) => `Promise`\< \| \{ `kind`: `"created"`; `requestId`: `string`; `computer`: \{ `computerId`: `string`; `name`: `string`; \}; \} \| \{ `kind`: `"invalid"` \| `"conflict"` \| `"denied"` \| `"uncertain"`; `requestId`: `string`; \}\> | - | Mint one identity or preserve the requestId for an uncertain retry. |
259
+ | Name | Type | Default value | Description |
260
+ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
261
+ | `list` | `object` | - | - |
262
+ | `list.replay` | `"safe"` | - | - |
263
+ | `list.access` | `"read"` | - | - |
264
+ | `list.description` | `string` | `"List a page of permitted Computers. Follow nextOffset for another page."` | - |
265
+ | `list.input` | `ZodObject`\<\{ `limit`: `ZodDefault`\<`ZodNumber`\>; `offset`: `ZodDefault`\<`ZodNumber`\>; \}, `$strict`\> | `computerPageSchema` | - |
266
+ | `list.output` | `ZodObject`\<\{ `computers`: `ZodArray`\<`ZodObject`\<\{ `computerId`: `ZodString`; `name`: `ZodString`; `createdAt`: `ZodNumber`; `updatedAt`: `ZodNumber`; \}, `$strict`\>\>; `nextOffset`: `ZodNullable`\<`ZodNumber`\>; \}, `$strict`\> | `teamComputerDirectorySchema` | - |
267
+ | `list.execute()` | (`input`, `context`) => `Promise`\<\{ `computers`: `object`[]; `nextOffset`: `number` \| `null`; \}\> | - | Return an admitted inventory page to MCP or the retained broker. |
268
+ | `state` | `object` | - | - |
269
+ | `state.replay` | `"safe"` | - | - |
270
+ | `state.access` | `"read"` | - | - |
271
+ | `state.description` | `string` | `"Read runtime state without waking a Computer, including its live admission queue position."` | - |
272
+ | `state.input` | `ZodObject`\<\{ `computerId`: `ZodString`; \}, `$strict`\> | `fleetComputerId` | - |
273
+ | `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` | - |
274
+ | `state.execute()` | (`input`, `context`) => `Promise`\< \| \{ `state`: `"running"` \| `"sleeping"` \| `"starting"` \| `"start_failed"`; \} \| \{ `state`: `"queued"`; `position`: `number`; \}\> | - | Return liveness without waking the runtime. |
275
+ | `start` | `object` | - | - |
276
+ | `start.replay` | `"unsafe"` | - | - |
277
+ | `start.description` | `string` | `"Start a hosted Computer through ordinary admission. Waits until connected; poll computers.state while queued. Safe to retry."` | - |
278
+ | `start.input` | `ZodObject`\<\{ `computerId`: `ZodString`; \}, `$strict`\> | `fleetComputerId` | - |
279
+ | `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` | - |
280
+ | `start.execute()` | (`input`, `context`) => `Promise`\< \| \{ `state`: `"running"` \| `"sleeping"` \| `"starting"` \| `"start_failed"`; \} \| \{ `state`: `"queued"`; `position`: `number`; \}\> | - | Admit and start this Computer. |
281
+ | `create` | `object` | - | - |
282
+ | `create.replay` | `"unsafe"` | - | - |
283
+ | `create.description` | `string` | `"Create a Computer with an optional friendly name. Request identity is generated automatically. If the outcome is uncertain, retry with its returned requestId and the original name input; do not start a second creation."` | - |
284
+ | `create.input` | `ZodObject`\<\{ `name`: `ZodDefault`\<`ZodNullable`\<`ZodString`\>\>; `requestId`: `ZodDefault`\<`ZodNullable`\<`ZodString`\>\>; \}, `$strict`\> | `fleetCreate` | - |
285
+ | `create.output` | `ZodDiscriminatedUnion`\<\[`ZodObject`\<\{ `kind`: `ZodLiteral`\<`"created"`\>; `requestId`: `ZodString`; `computer`: `ZodObject`\<\{ `computerId`: `ZodString`; `name`: `ZodString`; \}, `$strict`\>; \}, `$strict`\>, `ZodObject`\<\{ `kind`: `ZodEnum`\<\{ `invalid`: `"invalid"`; `conflict`: `"conflict"`; `denied`: `"denied"`; `uncertain`: `"uncertain"`; \}\>; `requestId`: `ZodString`; \}, `$strict`\>\], `"kind"`\> | `fleetCreation` | - |
286
+ | `create.execute()` | (`input`, `context`) => `Promise`\< \| \{ `kind`: `"created"`; `requestId`: `string`; `computer`: \{ `computerId`: `string`; `name`: `string`; \}; \} \| \{ `kind`: `"invalid"` \| `"conflict"` \| `"denied"` \| `"uncertain"`; `requestId`: `string`; \}\> | - | Mint one identity or preserve the requestId for an uncertain retry. |
287
+ | `backends` | `object` | - | - |
288
+ | `backends.replay` | `"safe"` | - | - |
289
+ | `backends.description` | `string` | `"List one Computer's attached execution backends (platform container, on-box VM, members' machines) with live status."` | - |
290
+ | `backends.input` | `ZodObject`\<\{ `computerId`: `ZodString`; \}, `$strict`\> | `fleetComputerId` | - |
291
+ | `backends.output` | `ZodObject`\<\{ `backends`: `ZodArray`\<`ZodObject`\<\{ `id`: `ZodString`; `kind`: `ZodEnum`\<\{ `platform-container`: `"platform-container"`; `on-box-vm`: `"on-box-vm"`; `local`: `"local"`; \}\>; `status`: `ZodEnum`\<\{ `ready`: `"ready"`; `online`: `"online"`; `offline`: `"offline"`; `queued`: `"queued"`; \}\>; `queuePosition`: `ZodNullable`\<`ZodNumber`\>; `hostId`: `ZodNullable`\<`ZodString`\>; `hostLabel`: `ZodNullable`\<`ZodString`\>; `folderLabel`: `ZodNullable`\<`ZodString`\>; `detachable`: `ZodBoolean`; \}, `$strict`\>\>; \}, `$strict`\> | `fleetBackends` | - |
292
+ | `backends.execute()` | (`input`, `context`) => `Promise`\<\{ `backends`: `object`[]; \}\> | - | Return the attached list without waking any backend. |
293
+ | `attachLocal` | `object` | - | - |
294
+ | `attachLocal.replay` | `"unsafe"` | - | - |
295
+ | `attachLocal.description` | `string` | `"Attach this authenticated member's machine to a Computer as an execution backend. Send only the device public key and labels; the folder path and private key stay on the machine. Retry an uncertain outcome with its returned requestId."` | - |
296
+ | `attachLocal.input` | `ZodObject`\<\{ `computerId`: `ZodString`; `publicKey`: `ZodBase64`; `hostLabel`: `ZodLazy`\<`ZodString`\>; `folderLabel`: `ZodLazy`\<`ZodString`\>; `requestId`: `ZodDefault`\<`ZodNullable`\<`ZodString`\>\>; \}, `$strict`\> | `fleetAttachInput` | - |
297
+ | `attachLocal.output` | `ZodDiscriminatedUnion`\<\[`ZodObject`\<\{ `kind`: `ZodLiteral`\<`"attached"`\>; `requestId`: `ZodString`; `backendId`: `ZodString`; \}, `$strict`\>, `ZodObject`\<\{ `kind`: `ZodEnum`\<\{ `invalid`: `"invalid"`; `conflict`: `"conflict"`; `denied`: `"denied"`; `uncertain`: `"uncertain"`; \}\>; `requestId`: `ZodString`; \}, `$strict`\>\], `"kind"`\> | `fleetAttachment` | - |
298
+ | `attachLocal.execute()` | (`input`, `context`) => `Promise`\< \| \{ `kind`: `"attached"`; `requestId`: `string`; `backendId`: `string`; \} \| \{ `kind`: `"invalid"` \| `"conflict"` \| `"denied"` \| `"uncertain"`; `requestId`: `string`; \}\> | - | Mint one identity or preserve the requestId for an uncertain retry. |
299
+ | `detachLocal` | `object` | - | - |
300
+ | `detachLocal.replay` | `"unsafe"` | - | - |
301
+ | `detachLocal.description` | `string` | `"Detach a machine this member attached from a Computer. Its live connection closes and the Computer keeps its files. Safe to retry."` | - |
302
+ | `detachLocal.input` | `ZodLazy`\<`ZodObject`\<\{ `computerId`: `ZodString`; `backendId`: `ZodString`; \}, `$strict`\>\> | `localBackendDetachSchema` | - |
303
+ | `detachLocal.output` | `ZodDiscriminatedUnion`\<\[`ZodObject`\<\{ `kind`: `ZodLiteral`\<`"detached"`\>; `detached`: `ZodBoolean`; \}, `$strict`\>, `ZodObject`\<\{ `kind`: `ZodEnum`\<\{ `invalid`: `"invalid"`; `denied`: `"denied"`; `uncertain`: `"uncertain"`; \}\>; \}, `$strict`\>\], `"kind"`\> | `fleetDetachment` | - |
304
+ | `detachLocal.execute()` | (`input`, `context`) => `Promise`\< \| \{ `kind`: `"detached"`; `detached`: `boolean`; \} \| \{ `kind`: `"invalid"` \| `"denied"` \| `"uncertain"`; \}\> | - | Close the attachment and its live connection; a gone one settles. |
266
305
 
267
306
  ---
268
307
 
@@ -334,15 +373,15 @@ Derive the current principal's admitted App modules and grants.
334
373
 
335
374
  #### Parameters
336
375
 
337
- | Parameter | Type |
338
- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
339
- | `host` | `Pick`\<[`OysterHost`](host.md#oysterhost), \| `"installations"` \| `"instances"` \| `"artifacts"` \| `"guestLimits"` \| `"backgroundOriginKey"` \| `"computerId"` \| `"capabilities"` \| `"appToolPolicy"` \| `"keys"` \| `"approvals"`\> |
340
- | `surfaces` | [`AppSurfaceCache`](#appsurfacecache) |
341
- | `principal` | [`TenantPrincipal`](tenant.md#tenantprincipal) |
342
- | `installations` | readonly `Readonly`\<\{ `installationId`: `string`; `instanceId`: [`InstanceId`](index.md#instanceid) \| `null`; `appId`: `AppId`; `release`: \{ `releaseId`: `ReleaseId`; `appId`: `AppId`; `artifact`: \{ `artifactRef`: `ArtifactRef`; `artifactDigest`: `Sha256Digest`; `provenance`: \{ `sourceRevision`: `SourceRevision`; `sourceTreeDigest`: `Sha256Digest`; `buildRecipeDigest`: `Sha256Digest`; \}; \}; \}; `releasePin`: `"pinned"` \| `"floating"`; `authority`: \{ `authorityVersion`: `number`; `declaredOperationsDigest`: `Sha256Digest`; `approvedGrants`: readonly `Readonly`\<\{ `capability`: \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"approvals"` \| `"agent.list"` \| `"agent.manage"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"agent.read"` \| `"agent.send"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`; `capabilityApproved`: `true`; `operations`: readonly `string`[]; `resources`: \| `"tenant-scope"` \| readonly `Readonly`\<\{ `kind`: ...; `id`: ...; \}\>[]; \}\>[]; `approval`: \| `Readonly`\<\{ `by`: \| \{ `kind`: `"member"`; `memberId`: `string`; \} \| \{ `kind`: `"agent"`; `agentId`: `string`; \} \| \{ `kind`: `"team-key"`; `keyId`: `string`; \}; `at`: `number`; `authorityVersion`: `number`; \}\> \| `null`; \}; `status`: `"enabled"` \| `"disabled"` \| `"deleted"`; \}\>[] |
343
- | `access` | [`OysterCallerAccess`](#oystercalleraccess) |
344
- | `sessionId` | `string` \| `null` |
345
- | `mode` | `"approval"` \| `"direct"` |
376
+ | Parameter | Type |
377
+ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
378
+ | `host` | `Pick`\<[`OysterHost`](host.md#oysterhost), \| `"installations"` \| `"instances"` \| `"artifacts"` \| `"guestLimits"` \| `"backgroundOriginKey"` \| `"computerId"` \| `"capabilities"` \| `"appToolPolicy"` \| `"keys"` \| `"approvals"`\> |
379
+ | `surfaces` | [`AppSurfaceCache`](#appsurfacecache) |
380
+ | `principal` | [`TenantPrincipal`](tenant.md#tenantprincipal) |
381
+ | `installations` | readonly `Readonly`\<\{ `installationId`: `string`; `instanceId`: [`InstanceId`](index.md#instanceid) \| `null`; `appId`: `AppId`; `release`: \{ `releaseId`: `ReleaseId`; `appId`: `AppId`; `artifact`: \{ `artifactRef`: `ArtifactRef`; `artifactDigest`: `Sha256Digest`; `provenance`: \{ `sourceRevision`: `SourceRevision`; `sourceTreeDigest`: `Sha256Digest`; `buildRecipeDigest`: `Sha256Digest`; \}; \}; \}; `releasePin`: `"pinned"` \| `"floating"`; `authority`: \{ `authorityVersion`: `number`; `declaredOperationsDigest`: `Sha256Digest`; `approvedGrants`: readonly `Readonly`\<\{ `capability`: \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"approvals"` \| `"agent.list"` \| `"agent.manage"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"agent.read"` \| `"agent.send"` \| `"llm.generation"` \| `"media.generation"` \| `"media.share"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`; `capabilityApproved`: `true`; `operations`: readonly `string`[]; `resources`: \| `"tenant-scope"` \| readonly `Readonly`\<\{ `kind`: ...; `id`: ...; \}\>[]; \}\>[]; `approval`: \| `Readonly`\<\{ `by`: \| \{ `kind`: `"member"`; `memberId`: `string`; \} \| \{ `kind`: `"agent"`; `agentId`: `string`; \} \| \{ `kind`: `"team-key"`; `keyId`: `string`; \}; `at`: `number`; `authorityVersion`: `number`; \}\> \| `null`; \}; `status`: `"enabled"` \| `"disabled"` \| `"deleted"`; \}\>[] |
382
+ | `access` | [`OysterCallerAccess`](#oystercalleraccess) |
383
+ | `sessionId` | `string` \| `null` |
384
+ | `mode` | `"approval"` \| `"direct"` |
346
385
 
347
386
  #### Returns
348
387
 
@@ -389,13 +428,13 @@ installation authority or the caller's own grants.
389
428
 
390
429
  #### Parameters
391
430
 
392
- | Parameter | Type |
393
- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
394
- | `host` | `Pick`\<[`OysterHost`](host.md#oysterhost), \| `"installations"` \| `"instances"` \| `"artifacts"` \| `"guestLimits"` \| `"backgroundOriginKey"` \| `"computerId"` \| `"capabilities"` \| `"appToolPolicy"` \| `"keys"` \| `"approvals"`\> |
395
- | `principal` | [`TenantPrincipal`](tenant.md#tenantprincipal) |
396
- | `access` | [`OysterCallerAccess`](#oystercalleraccess) |
397
- | `surfaces` | [`AppSurfaceCache`](#appsurfacecache) |
398
- | `preloadedInstallations?` | readonly `Readonly`\<\{ `installationId`: `string`; `instanceId`: [`InstanceId`](index.md#instanceid) \| `null`; `appId`: `AppId`; `release`: \{ `releaseId`: `ReleaseId`; `appId`: `AppId`; `artifact`: \{ `artifactRef`: `ArtifactRef`; `artifactDigest`: `Sha256Digest`; `provenance`: \{ `sourceRevision`: `SourceRevision`; `sourceTreeDigest`: `Sha256Digest`; `buildRecipeDigest`: `Sha256Digest`; \}; \}; \}; `releasePin`: `"pinned"` \| `"floating"`; `authority`: \{ `authorityVersion`: `number`; `declaredOperationsDigest`: `Sha256Digest`; `approvedGrants`: readonly `Readonly`\<\{ `capability`: \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"approvals"` \| `"agent.list"` \| `"agent.manage"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"agent.read"` \| `"agent.send"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`; `capabilityApproved`: `true`; `operations`: readonly `string`[]; `resources`: `"tenant-scope"` \| readonly `Readonly`\<...\>[]; \}\>[]; `approval`: \| `Readonly`\<\{ `by`: \| \{ `kind`: `"member"`; `memberId`: `string`; \} \| \{ `kind`: `"agent"`; `agentId`: `string`; \} \| \{ `kind`: `"team-key"`; `keyId`: `string`; \}; `at`: `number`; `authorityVersion`: `number`; \}\> \| `null`; \}; `status`: `"enabled"` \| `"disabled"` \| `"deleted"`; \}\>[] |
431
+ | Parameter | Type |
432
+ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
433
+ | `host` | `Pick`\<[`OysterHost`](host.md#oysterhost), \| `"installations"` \| `"instances"` \| `"artifacts"` \| `"guestLimits"` \| `"backgroundOriginKey"` \| `"computerId"` \| `"capabilities"` \| `"appToolPolicy"` \| `"keys"` \| `"approvals"`\> |
434
+ | `principal` | [`TenantPrincipal`](tenant.md#tenantprincipal) |
435
+ | `access` | [`OysterCallerAccess`](#oystercalleraccess) |
436
+ | `surfaces` | [`AppSurfaceCache`](#appsurfacecache) |
437
+ | `preloadedInstallations?` | readonly `Readonly`\<\{ `installationId`: `string`; `instanceId`: [`InstanceId`](index.md#instanceid) \| `null`; `appId`: `AppId`; `release`: \{ `releaseId`: `ReleaseId`; `appId`: `AppId`; `artifact`: \{ `artifactRef`: `ArtifactRef`; `artifactDigest`: `Sha256Digest`; `provenance`: \{ `sourceRevision`: `SourceRevision`; `sourceTreeDigest`: `Sha256Digest`; `buildRecipeDigest`: `Sha256Digest`; \}; \}; \}; `releasePin`: `"pinned"` \| `"floating"`; `authority`: \{ `authorityVersion`: `number`; `declaredOperationsDigest`: `Sha256Digest`; `approvedGrants`: readonly `Readonly`\<\{ `capability`: \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"approvals"` \| `"agent.list"` \| `"agent.manage"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"agent.read"` \| `"agent.send"` \| `"llm.generation"` \| `"media.generation"` \| `"media.share"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`; `capabilityApproved`: `true`; `operations`: readonly `string`[]; `resources`: `"tenant-scope"` \| readonly `Readonly`\<...\>[]; \}\>[]; `approval`: \| `Readonly`\<\{ `by`: \| \{ `kind`: `"member"`; `memberId`: `string`; \} \| \{ `kind`: `"agent"`; `agentId`: `string`; \} \| \{ `kind`: `"team-key"`; `keyId`: `string`; \}; `at`: `number`; `authorityVersion`: `number`; \}\> \| `null`; \}; `status`: `"enabled"` \| `"disabled"` \| `"deleted"`; \}\>[] |
399
438
 
400
439
  #### Returns
401
440
 
@@ -330,7 +330,12 @@ Desktop chrome (menus, palette, status) belongs to the trusted shell.
330
330
  function connectOysterApp(options): Promise<AppHost>;
331
331
  ```
332
332
 
333
- Connect a child or home App using the same admitted Oyster slot handles.
333
+ Connect a child or home App using the same admitted Oyster slot handles. The
334
+ host navigates the App's frame (`config.uiUrl`) only once it listens for the
335
+ App's ready signal, so slow capability resolution on a cold Oyster can never
336
+ outlast that signal. Opening is bounded: the capabilities and the document get
337
+ the shared cold-document budget, and the handshake after the document loads gets
338
+ the App's own ready window.
334
339
 
335
340
  #### Parameters
336
341