@fungi.computer/oyster 0.15.0 → 0.17.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 (51) hide show
  1. package/dist/agents.d.ts +15 -0
  2. package/dist/agents.js +10 -1
  3. package/dist/apps/permissions.js +8 -1
  4. package/dist/auth.d.ts +2 -0
  5. package/dist/auth.js +9 -8
  6. package/dist/boot-host-script.js +1 -1
  7. package/dist/build/candidate-cli.mjs +4 -0
  8. package/dist/computer.d.ts +5 -0
  9. package/dist/computer.js +1 -0
  10. package/dist/embed-metafiles.js +2 -2
  11. package/dist/embed-scripts.js +2 -2
  12. package/dist/hello-app-script.js +1 -1
  13. package/dist/host-page-assets.js +1 -1
  14. package/dist/host-page.d.ts +5 -1
  15. package/dist/host-page.js +23 -23
  16. package/dist/host.js +6 -1
  17. package/dist/page/app-access.js +23 -1
  18. package/dist/page/app-rights.d.ts +8 -0
  19. package/dist/page/app-rights.js +13 -0
  20. package/dist/page/computer-handles.d.ts +15 -0
  21. package/dist/page/computer-handles.js +4 -1
  22. package/dist/page/mount.d.ts +5 -0
  23. package/dist/page/mount.js +4 -0
  24. package/dist/page-script.js +3 -3
  25. package/dist/root-data.d.ts +3 -0
  26. package/dist/standalone/agents.d.ts +8 -0
  27. package/dist/standalone/agents.js +61 -12
  28. package/dist/standalone/cloudflare-account.d.ts +10 -0
  29. package/dist/standalone/cloudflare-account.js +17 -0
  30. package/dist/standalone/computer.d.ts +2 -2
  31. package/dist/standalone/computer.js +16 -1
  32. package/dist/standalone/media.d.ts +2 -0
  33. package/dist/standalone/media.js +17 -1
  34. package/dist/standalone/owner-routes.js +2 -0
  35. package/dist/standalone/registry.d.ts +16 -0
  36. package/dist/standalone/registry.js +30 -0
  37. package/dist/standalone/sign-in-link.d.ts +1 -1
  38. package/dist/standalone/sign-in-link.js +9 -18
  39. package/dist/standalone/trial-starters.d.ts +52 -0
  40. package/dist/standalone/trial-starters.js +67 -0
  41. package/dist/starter-agent.d.ts +65 -0
  42. package/dist/starter-agent.js +85 -0
  43. package/docs/api/agents.md +23 -0
  44. package/docs/api/auth.md +10 -0
  45. package/docs/api/computer.md +4 -0
  46. package/docs/api/host.md +1 -0
  47. package/docs/api/page/mount.md +2 -0
  48. package/docs/api/root-data.md +10 -9
  49. package/docs/api/workers-git.md +14 -9
  50. package/docs/api/workers.md +28 -20
  51. package/package.json +25 -21
@@ -0,0 +1,65 @@
1
+ /**
2
+ * The starter Agent policy: an owner with an empty Team gets one Agent named
3
+ * "Shiitake", once, ever. This module owns only that rule and its one-row
4
+ * ledger. It never creates anything itself: the host supplies its ordinary,
5
+ * idempotent Agent create, so the starter has exactly the identity, Computer,
6
+ * App tools and funding checks of any other Agent. It stores no model, prompt,
7
+ * session or tool grant.
8
+ */
9
+ import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
10
+ /** The declaration. Changing it affects only Teams with no ledger row. */
11
+ export declare const starterAgent: {
12
+ readonly version: 1;
13
+ readonly name: "Shiitake";
14
+ readonly requestId: "starter-agent:v1";
15
+ };
16
+ /** What the ledger remembers: that the starter was settled, never to be offered again. */
17
+ export type StarterLedgerRow = Readonly<{
18
+ version: number;
19
+ outcome: "created" | "team-not-empty";
20
+ agentId: string | null;
21
+ at: number;
22
+ }>;
23
+ /** One row per Team in the host's own SQLite. */
24
+ export type StarterLedgerStore = Readonly<{
25
+ read(): StarterLedgerRow | undefined;
26
+ /** First write wins; a later one is ignored. */
27
+ record(row: StarterLedgerRow): void;
28
+ }>;
29
+ /** The ledger as the policy reads it; a host across an RPC awaits its store. */
30
+ export type StarterLedger = Readonly<{
31
+ read(): StarterLedgerRow | undefined | Promise<StarterLedgerRow | undefined>;
32
+ record(row: StarterLedgerRow): void | Promise<void>;
33
+ }>;
34
+ /** The host's ordinary create, as the starter sees it. */
35
+ export type StarterCreateResult = Readonly<{
36
+ status: "created";
37
+ agentId: string;
38
+ }> | Readonly<{
39
+ status: "unfunded";
40
+ }>;
41
+ export type StarterAgentHost = Readonly<{
42
+ ledger: StarterLedger;
43
+ /** Only the Team owner's read may trigger the starter. */
44
+ isOwner(): boolean;
45
+ /** Agents in the Team, archived ones included. */
46
+ agentCount(): number | Promise<number>;
47
+ /** The host's normal create, replayed by `requestId`; funding refusal is `unfunded`. */
48
+ create(request: {
49
+ name: string;
50
+ requestId: string;
51
+ }): Promise<StarterCreateResult>;
52
+ /** Where a failed attempt is reported; the caller's read never fails. */
53
+ report?(cause: unknown): void;
54
+ now?(): number;
55
+ }>;
56
+ /** How one offer of the starter Agent settled; only `created` made an Agent. */
57
+ export type StarterOutcome = "created" | "already-offered" | "team-not-empty" | "unfunded" | "not-owner" | "failed";
58
+ /** Open the one-row ledger in the host's own SQLite. */
59
+ export declare function createStarterLedger(sql: WatchdogSqliteOwner["sql"]): StarterLedgerStore;
60
+ /**
61
+ * Offer the starter Agent if this Team never had its chance. Safe to call on
62
+ * every owner directory read: concurrent calls share one attempt, and the
63
+ * host's `requestId` replay makes a second attempt return the same Agent.
64
+ */
65
+ export declare function ensureStarterAgent(host: StarterAgentHost): Promise<StarterOutcome>;
@@ -0,0 +1,85 @@
1
+ import { z } from "zod";
2
+ /** The declaration. Changing it affects only Teams with no ledger row. */
3
+ export const starterAgent = {
4
+ version: 1,
5
+ name: "Shiitake",
6
+ requestId: "starter-agent:v1",
7
+ };
8
+ const ledgerRowSchema = z.strictObject({
9
+ version: z.number().int(),
10
+ outcome: z.enum(["created", "team-not-empty"]),
11
+ agent_id: z.string().nullable(),
12
+ at: z.number(),
13
+ });
14
+ /** Open the one-row ledger in the host's own SQLite. */
15
+ export function createStarterLedger(sql) {
16
+ sql.exec("CREATE TABLE IF NOT EXISTS starter_agent (id INTEGER PRIMARY KEY CHECK (id = 1), version INTEGER NOT NULL, outcome TEXT NOT NULL, agent_id TEXT, at INTEGER NOT NULL) STRICT");
17
+ return {
18
+ read() {
19
+ const row = sql
20
+ .exec("SELECT version, outcome, agent_id, at FROM starter_agent WHERE id = 1")
21
+ .toArray()[0];
22
+ if (row === undefined)
23
+ return undefined;
24
+ const stored = ledgerRowSchema.parse(row);
25
+ return {
26
+ version: stored.version,
27
+ outcome: stored.outcome,
28
+ agentId: stored.agent_id,
29
+ at: stored.at,
30
+ };
31
+ },
32
+ record(row) {
33
+ sql.exec("INSERT INTO starter_agent(id, version, outcome, agent_id, at) VALUES(1, ?, ?, ?, ?) ON CONFLICT(id) DO NOTHING", row.version, row.outcome, row.agentId, row.at);
34
+ },
35
+ };
36
+ }
37
+ const inFlight = new WeakMap();
38
+ /**
39
+ * Offer the starter Agent if this Team never had its chance. Safe to call on
40
+ * every owner directory read: concurrent calls share one attempt, and the
41
+ * host's `requestId` replay makes a second attempt return the same Agent.
42
+ */
43
+ export function ensureStarterAgent(host) {
44
+ const running = inFlight.get(host.ledger);
45
+ if (running !== undefined)
46
+ return running;
47
+ const attempt = settle(host).finally(() => inFlight.delete(host.ledger));
48
+ inFlight.set(host.ledger, attempt);
49
+ return attempt;
50
+ }
51
+ async function settle(host) {
52
+ try {
53
+ if (!host.isOwner())
54
+ return "not-owner";
55
+ if ((await host.ledger.read()) !== undefined)
56
+ return "already-offered";
57
+ const at = (host.now ?? Date.now)();
58
+ if ((await host.agentCount()) > 0) {
59
+ await host.ledger.record({
60
+ version: starterAgent.version,
61
+ outcome: "team-not-empty",
62
+ agentId: null,
63
+ at,
64
+ });
65
+ return "team-not-empty";
66
+ }
67
+ const result = await host.create({
68
+ name: starterAgent.name,
69
+ requestId: starterAgent.requestId,
70
+ });
71
+ if (result.status === "unfunded")
72
+ return "unfunded";
73
+ await host.ledger.record({
74
+ version: starterAgent.version,
75
+ outcome: "created",
76
+ agentId: result.agentId,
77
+ at,
78
+ });
79
+ return "created";
80
+ }
81
+ catch (cause) {
82
+ host.report?.(cause);
83
+ return "failed";
84
+ }
85
+ }
@@ -199,6 +199,7 @@ type OysterAgents = Readonly<{
199
199
  )[];
200
200
  }>[]
201
201
  >;
202
+ ensureStarter: Promise<StarterOutcome>;
202
203
  setArchived: Promise<
203
204
  | Readonly<{
204
205
  archived: boolean;
@@ -323,6 +324,12 @@ type OysterAgents = Readonly<{
323
324
  error: "not_found" | "revision_conflict" | "not_granted";
324
325
  }>
325
326
  >;
327
+ setup: Promise<
328
+ Readonly<{
329
+ models: "ready" | "missing";
330
+ media: "ready" | "missing";
331
+ }>
332
+ >;
326
333
  modelKeys: Promise<
327
334
  readonly Readonly<{
328
335
  keyId: string;
@@ -470,6 +477,22 @@ type ModelKeySealInput = Readonly<{
470
477
 
471
478
  What the owner submits to seal one provider key.
472
479
 
480
+ ---
481
+
482
+ ### StarterOutcome
483
+
484
+ ```ts
485
+ type StarterOutcome =
486
+ | "created"
487
+ | "already-offered"
488
+ | "team-not-empty"
489
+ | "unfunded"
490
+ | "not-owner"
491
+ | "failed";
492
+ ```
493
+
494
+ How one offer of the starter Agent settled; only `created` made an Agent.
495
+
473
496
  ## Variables
474
497
 
475
498
  ### maxAgentConnections
package/docs/api/auth.md CHANGED
@@ -18,6 +18,16 @@ const ownerKeyCookieName: "oyster_session" = "oyster_session";
18
18
 
19
19
  Cookie emitted by ownerKeyAuth, for composing credential-specific adapters.
20
20
 
21
+ ---
22
+
23
+ ### returningCookieName
24
+
25
+ ```ts
26
+ const returningCookieName: "oyster_returning" = "oyster_returning";
27
+ ```
28
+
29
+ Marks a browser that has signed in here before; it carries no authority.
30
+
21
31
  ## Functions
22
32
 
23
33
  ### ownerKeyAuth()
@@ -192,6 +192,10 @@ Computer routes supplied by the host; execution stays in the Computer runtime.
192
192
  | `processes.methods.kill.kind` | `"json"` | `"json"` |
193
193
  | `processes.methods.kill.method` | `"POST"` | `"POST"` |
194
194
  | `processes.methods.kill.path` | `"processes/kill"` | `"processes/kill"` |
195
+ | `processes.methods.logs` | `object` | - |
196
+ | `processes.methods.logs.kind` | `"json"` | `"json"` |
197
+ | `processes.methods.logs.method` | `"GET"` | `"GET"` |
198
+ | `processes.methods.logs.path` | `"processes/logs"` | `"processes/logs"` |
195
199
  | <a id="property-terminal"></a> `terminal` | `object` | - |
196
200
  | `terminal.id` | `string` | `computerTerminal.id` |
197
201
  | `terminal.version` | `number` | `computerTerminal.version` |
package/docs/api/host.md CHANGED
@@ -460,6 +460,7 @@ type OysterHost = Readonly<{
460
460
  computerId: string;
461
461
  name: string;
462
462
  }>;
463
+ installing?: readonly InstallingApp[];
463
464
  }>>;
464
465
  storage: Pick<AppStorageWire, "read" | "write" | "reset"> & Readonly<{
465
466
  events: Promise<Response>;
@@ -132,6 +132,8 @@ type OysterAppConnectionOptions = Readonly<{
132
132
  appOpen?: OysterAppOpenRouting;
133
133
  openRequest?: AppHostLaunch["context"]["value"]["openRequest"];
134
134
  surfaceId?: string;
135
+ setup?: AppSetup;
136
+ permissions?: AppPermissions;
135
137
  reservedChords: readonly AppHostReservedChord[];
136
138
  theme: string;
137
139
  }>;
@@ -38,6 +38,7 @@ type OysterRootDirectory = Readonly<{
38
38
  computerId: string;
39
39
  name: string;
40
40
  }>;
41
+ installing?: readonly InstallingApp[];
41
42
  }>;
42
43
  ```
43
44
 
@@ -100,12 +101,12 @@ Data adapters for a standalone workbench over the root's existing owners.
100
101
 
101
102
  #### Returns
102
103
 
103
- | Name | Type | Description |
104
- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
105
- | `storage` | `object` | Each open(authorize) receives fresh host admission and Release-declared keys. |
106
- | `storage.purgeInstallation()` | (`address`) => `void` | Remove an installation's values and write counters inside its delete transaction. |
107
- | `storage.purgeMember()` | (`memberId`, `throughVersion`) => `void` | Remove a member's private values and counters through the revoked membership version. |
108
- | `openInstallation()` | (`authorize`) => `object` | Bind a lifecycle view to fresh installation admission; only declared team layers are accessible. |
109
- | `open()` | (`authorize`) => `object` | Bind a member view to live admission, declared keys and the current membership version. |
110
- | `directory()` | () => `Promise`\<`Readonly`\<\{ `apps`: readonly `object`[]; `roles`: [`OysterRootRoles`](#oysterrootroles); `computer?`: `Readonly`\<\{ `computerId`: `string`; `name`: `string`; \}\>; \}\>\> | Project the current installations without minting permissions or role choices. |
111
- | `platformDestinations()` | () => readonly `Readonly`\<\{ `id`: `string`; `label`: `string`; \}\>[] | No standalone platform navigation destination is implemented yet. |
104
+ | Name | Type | Description |
105
+ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
106
+ | `storage` | `object` | Each open(authorize) receives fresh host admission and Release-declared keys. |
107
+ | `storage.purgeInstallation()` | (`address`) => `void` | Remove an installation's values and write counters inside its delete transaction. |
108
+ | `storage.purgeMember()` | (`memberId`, `throughVersion`) => `void` | Remove a member's private values and counters through the revoked membership version. |
109
+ | `openInstallation()` | (`authorize`) => `object` | Bind a lifecycle view to fresh installation admission; only declared team layers are accessible. |
110
+ | `open()` | (`authorize`) => `object` | Bind a member view to live admission, declared keys and the current membership version. |
111
+ | `directory()` | () => `Promise`\<`Readonly`\<\{ `apps`: readonly `object`[]; `roles`: [`OysterRootRoles`](#oysterrootroles); `computer?`: `Readonly`\<\{ `computerId`: `string`; `name`: `string`; \}\>; `installing?`: readonly `object`[]; \}\>\> | Project the current installations without minting permissions or role choices. |
112
+ | `platformDestinations()` | () => readonly `Readonly`\<\{ `id`: `string`; `label`: `string`; \}\>[] | No standalone platform navigation destination is implemented yet. |
@@ -1012,6 +1012,10 @@ gill(
1012
1012
  title: string;
1013
1013
  state: "empty";
1014
1014
  rows: readonly [];
1015
+ emptyText?: string;
1016
+ action?: {
1017
+ kind: "open";
1018
+ };
1015
1019
  next?: string;
1016
1020
  }
1017
1021
  | {
@@ -1076,9 +1080,10 @@ Invoke a Release-declared Gill in a fresh immutable frame.
1076
1080
  ###### Returns
1077
1081
 
1078
1082
  `Promise`\<[`InstanceResult`](host.md#instanceresult)\< \| \{ `viewId`:
1079
- `string`; `title`: `string`; `state`: `"empty"`; `rows`: readonly \[\]; `next?`:
1080
- `string`; \} \| \{ `viewId`: `string`; `title`: `string`; `state`: `"error"`;
1081
- `rows`: readonly \[\]; `reason?`: `"disabled"` \| `"exec_isolation_required"` \|
1083
+ `string`; `title`: `string`; `state`: `"empty"`; `rows`: readonly \[\];
1084
+ `emptyText?`: `string`; `action?`: \{ `kind`: `"open"`; \}; `next?`: `string`;
1085
+ \} \| \{ `viewId`: `string`; `title`: `string`; `state`: `"error"`; `rows`:
1086
+ readonly \[\]; `reason?`: `"disabled"` \| `"exec_isolation_required"` \|
1082
1087
  `"params_required"`; `error`: `string`; `recovery?`: \| \{ `kind`:
1083
1088
  `"configure"`; `param`: `string`; \} \| \{ `kind`: `"open"`; \}; \} \| \{
1084
1089
  `viewId`: `string`; `title`: `string`; `state`: `"full"`; `rows`: readonly
@@ -1722,12 +1727,12 @@ both compose it here.
1722
1727
 
1723
1728
  #### Parameters
1724
1729
 
1725
- | Parameter | Type |
1726
- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1727
- | `env` | [`OysterGitEnv`](#oystergitenv) |
1728
- | `scope` | [`TenantScope`](tenant.md#tenantscope) |
1729
- | `hostOwnerRoutes` | \| [`Routes`](authorization.md#routes)\<[`OysterEnv`](host.md#oysterenv)\> \| `undefined` |
1730
- | `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"`)[]; \}\>[]\>; `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`\>; `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"`; \}\>\>; `modelKeys`: `Promise`\<readonly `Readonly`\<\{ `keyId`: `string`; `provider`: `"anthropic"` \| `"openai"` \| `"openrouter"` \| `"openai-compatible"`; `label`: `string`; `createdAt`: `number`; `validatedAt`: `number`; \}\>[]\>; `sealModelKey`: `Promise`\< \| `Readonly`\<\{ `keyId`: `string`; `provider`: `"anthropic"` \| `"openai"` \| `"openrouter"` \| `"openai-compatible"`; `label`: `string`; `createdAt`: `number`; `validatedAt`: `number`; \}\> \| `Readonly`\<\{ `error`: [`ModelKeyRefusal`](agents.md#modelkeyrefusal); \}\>\>; `removeModelKey`: `Promise`\<`"deleted"` \| `"absent"`\>; `connections`: `Promise`\<readonly `Readonly`\<\{ `connectionId`: `string`; `name`: `string`; `label`: `string`; `kind`: `"mcp"` \| `"openapi"`; `url`: `string`; `auth`: `"none"` \| `"token"` \| `"oauth"`; `state`: `"pending"` \| `"connected"` \| `"reconnect_required"`; `grants`: readonly `Readonly`\<\{ `agentId`: `string`; `access`: [`ConnectionAccess`](agents.md#connectionaccess); \}\>[]; \}\>[]\>; `addConnection`: `Promise`\< \| `Readonly`\<\{ `connectionId`: `string`; `authorizeUrl`: `string` \| `null`; \}\> \| `Readonly`\<\{ `error`: `"limit"` \| `"not_found"` \| `"duplicate_name"` \| `"invalid_endpoint"`; \}\>\>; `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`: `"runner"` \| `"owners"`; `show`: readonly `Json`[]; `choices?`: readonly ...[]; `openedAt`: `number`; `expiresAt`: `number`; `state`: `"pending"` \| `"delivered"` \| `"answered"` \| `"timed_out"` \| `"closed"`; \})[]; `revision`: `number`; \}\>\>; `revision`: `Promise`\<`number`\>; `visit`: `Promise`\<`boolean`\>; \}\> \| `undefined` |
1730
+ | Parameter | Type |
1731
+ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1732
+ | `env` | [`OysterGitEnv`](#oystergitenv) |
1733
+ | `scope` | [`TenantScope`](tenant.md#tenantscope) |
1734
+ | `hostOwnerRoutes` | \| [`Routes`](authorization.md#routes)\<[`OysterEnv`](host.md#oysterenv)\> \| `undefined` |
1735
+ | `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`\>; `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`: `"anthropic"` \| `"openai"` \| `"openrouter"` \| `"openai-compatible"`; `label`: `string`; `createdAt`: `number`; `validatedAt`: `number`; \}\>[]\>; `sealModelKey`: `Promise`\< \| `Readonly`\<\{ `keyId`: `string`; `provider`: `"anthropic"` \| `"openai"` \| `"openrouter"` \| `"openai-compatible"`; `label`: `string`; `createdAt`: `number`; `validatedAt`: `number`; \}\> \| `Readonly`\<\{ `error`: [`ModelKeyRefusal`](agents.md#modelkeyrefusal); \}\>\>; `removeModelKey`: `Promise`\<`"deleted"` \| `"absent"`\>; `connections`: `Promise`\<readonly `Readonly`\<\{ `connectionId`: `string`; `name`: `string`; `label`: `string`; `kind`: `"mcp"` \| `"openapi"`; `url`: `string`; `auth`: `"none"` \| `"token"` \| `"oauth"`; `state`: `"pending"` \| `"connected"` \| `"reconnect_required"`; `grants`: readonly `Readonly`\<\{ `agentId`: `string`; `access`: [`ConnectionAccess`](agents.md#connectionaccess); \}\>[]; \}\>[]\>; `addConnection`: `Promise`\< \| `Readonly`\<\{ `connectionId`: `string`; `authorizeUrl`: `string` \| `null`; \}\> \| `Readonly`\<\{ `error`: `"limit"` \| `"not_found"` \| `"duplicate_name"` \| `"invalid_endpoint"`; \}\>\>; `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`: `"runner"` \| `"owners"`; `show`: readonly `Json`[]; `choices?`: readonly ...[]; `openedAt`: `number`; `expiresAt`: `number`; `state`: `"pending"` \| `"delivered"` \| `"answered"` \| `"timed_out"` \| `"closed"`; \})[]; `revision`: `number`; \}\>\>; `revision`: `Promise`\<`number`\>; `visit`: `Promise`\<`boolean`\>; \}\> \| `undefined` |
1731
1736
 
1732
1737
  #### Returns
1733
1738