@fungi.computer/oyster 0.19.27 → 0.19.29

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.
@@ -29,6 +29,8 @@ const defaultChoice = {
29
29
  };
30
30
  /** Pi's maintained catalog for a provider a key may be brought for. */
31
31
  async function byokCatalog(provider) {
32
+ if (provider === "cloudflare-workers-ai")
33
+ return cloudflareWorkersAIProvider().getModels();
32
34
  if (provider === "anthropic")
33
35
  return (await import("@earendil-works/pi-ai/providers/anthropic"))
34
36
  .anthropicProvider()
@@ -59,7 +61,8 @@ export async function resolveDefaultChoice(ready) {
59
61
  for (const { keyId, provider } of ready.keys) {
60
62
  if (provider !== "anthropic" &&
61
63
  provider !== "openai" &&
62
- provider !== "openrouter")
64
+ provider !== "openrouter" &&
65
+ provider !== "cloudflare-workers-ai")
63
66
  continue;
64
67
  const catalog = await byokCatalog(provider);
65
68
  const model = catalog.find((entry) => "default" in entry && entry.default === true) ??
@@ -78,7 +81,8 @@ export async function selectAgentModel(choice) {
78
81
  const { providerId, modelId, reasoning } = choice.model;
79
82
  if (choice.keySource === "byok") {
80
83
  // Only a catalogued provider's own models; an OpenAI-compatible base has none.
81
- if (!isModelKeyProvider(providerId) || providerId === "openai-compatible")
84
+ if (providerId !== "cloudflare-workers-ai" &&
85
+ (!isModelKeyProvider(providerId) || providerId === "openai-compatible"))
82
86
  throw new AgentModelRefused("unsupported_key_source");
83
87
  const found = (await byokCatalog(providerId)).find((item) => item.id === modelId);
84
88
  if (found === undefined || (reasoning !== undefined && !found.reasoning))
@@ -290,6 +290,11 @@ export declare class AgentDirectory extends DurableObject<StandaloneAgentEnv> {
290
290
  error: ModelKeyRefusal;
291
291
  }>>;
292
292
  listModelKeys(): Promise<readonly ModelKeyRecord[]>;
293
+ modelKeyBaseUrl(keyId: string): Promise<Readonly<{
294
+ baseUrl: string;
295
+ }> | Readonly<{
296
+ error: ModelKeyRefusal;
297
+ }>>;
293
298
  modelKey(keyId: string): Promise<ModelKeyRecord | null>;
294
299
  removeModelKey(keyId: string): Promise<"deleted" | "absent">;
295
300
  /** Host-only: the one place a stored key meets a provider request. */
@@ -953,7 +953,13 @@ export class StandaloneAgentBase extends ShiitakeDO {
953
953
  };
954
954
  if (choice.model.reasoning !== undefined)
955
955
  streamOptions.reasoning = choice.model.reasoning;
956
- return observedModels(normalizeModel(modelChoice), streamOptions);
956
+ const configuration = await directory.modelKeyBaseUrl(keyId);
957
+ if ("error" in configuration)
958
+ throw new AgentModelRefused(configuration.error === "key_removed"
959
+ ? "key_removed"
960
+ : "key_not_connected");
961
+ const { baseUrl } = configuration;
962
+ return observedModels(normalizeModel({ ...modelChoice, baseUrl }), streamOptions);
957
963
  }
958
964
  if (choice.keySource === "ai-gateway") {
959
965
  const egress = configuredProviderEgress(this.env);
@@ -1277,6 +1283,16 @@ export class AgentDirectory extends DurableObject {
1277
1283
  listModelKeys() {
1278
1284
  return this.modelKeys().list();
1279
1285
  }
1286
+ async modelKeyBaseUrl(keyId) {
1287
+ try {
1288
+ return { baseUrl: await this.modelKeys().baseUrl(keyId) };
1289
+ }
1290
+ catch (error) {
1291
+ if (error instanceof ModelKeyRefused)
1292
+ return { error: error.reason };
1293
+ throw error;
1294
+ }
1295
+ }
1280
1296
  modelKey(keyId) {
1281
1297
  return this.modelKeys().get(keyId);
1282
1298
  }
@@ -20,7 +20,7 @@ import { defaultStarterBuildConcurrency, installStandaloneAppSet, } from "./app-
20
20
  /** The starter Apps' public source repositories. */
21
21
  const defaultRepositories = "https://github.com/fungi-computer";
22
22
  const usage = "Usage: oyster install-apps [--repositories <base URL>] [--ref <ref>] [--from <checkout>] [--concurrency 1-3] [--timings <file>]";
23
- const urlSource = "OYSTER_URL is the address of your deployed Oyster Worker, such as https://oyster.<your-subdomain>.workers.dev. You set it when you deploy. A local `oyster try` Oyster has no Computer, so it cannot build the starter Apps.";
23
+ const urlSource = "OYSTER_URL is the address of your deployed Oyster Worker, such as https://oyster.<your-subdomain>.workers.dev. You set it when you deploy. For a local trial, run `oyster try`; it sets up its Computer and starter Apps.";
24
24
  const keySource = "OYSTER_OWNER_KEY is the owner key you chose for that Oyster: export OYSTER_OWNER_KEY=$(openssl rand -hex 24), then store it with `wrangler secret put OYSTER_OWNER_KEY`.";
25
25
  const helpText = `${usage}
26
26
 
@@ -1,5 +1,5 @@
1
1
  import { type CredentialRecord, type CredentialStorage } from "@fungi.computer/veil/credential-store";
2
- import { type ModelKeyRecord, type ModelKeyVault } from "@fungi.computer/veil/model-keys";
2
+ import { type ModelKeyRecord as HostedModelKeyRecord } from "@fungi.computer/veil/model-keys";
3
3
  /**
4
4
  * This instance's own model-key owner. Provider API keys are sealed (AES-GCM)
5
5
  * under a key derived from the instance master secret, a host secret that never
@@ -12,12 +12,16 @@ export declare class ModelKeyRefused extends Error {
12
12
  readonly reason: ModelKeyRefusal;
13
13
  constructor(reason: ModelKeyRefusal);
14
14
  }
15
- export type { ModelKeyRecord };
15
+ /** Standalone custody also accepts an owner’s Cloudflare account and token. */
16
+ export type ModelKeyRecord = Omit<HostedModelKeyRecord, "provider"> & {
17
+ readonly provider: HostedModelKeyRecord["provider"] | "cloudflare-workers-ai";
18
+ };
16
19
  /** What the owner submits to seal one provider key. */
17
20
  export type ModelKeySealInput = Readonly<{
18
21
  provider: string;
19
22
  label: string;
20
23
  apiKey: string;
24
+ accountId?: string;
21
25
  }>;
22
26
  export type ModelKeyStorage = CredentialStorage;
23
27
  /**
@@ -45,6 +49,14 @@ export declare function createModelKeyVault(options: {
45
49
  credentialKey: string | undefined;
46
50
  fetch?: typeof globalThis.fetch;
47
51
  now?: () => number;
48
- }): ModelKeyVault & Readonly<{
49
- get: (keyId: string) => Promise<ModelKeyRecord | null>;
50
- }>;
52
+ }): {
53
+ /** Validate with one cheap authenticated read, then store only the sealed key. */
54
+ seal(input: ModelKeySealInput): Promise<ModelKeyRecord>;
55
+ list(): Promise<readonly ModelKeyRecord[]>;
56
+ get(keyId: string): Promise<ModelKeyRecord | null>;
57
+ /** Host-only model configuration; the token never leaves its sealed callback. */
58
+ baseUrl(keyId: string): Promise<string>;
59
+ remove(keyId: string): Promise<"deleted" | "absent">;
60
+ /** Send one provider request with the key attached; the caller's auth is dropped. */
61
+ send(keyId: string, request: Request): Promise<Response>;
62
+ };
@@ -1,3 +1,4 @@
1
+ import * as Schema from "effect/Schema";
1
2
  import { createCredentialSealer, createCredentialStore, CredentialError, } from "@fungi.computer/veil/credential-store";
2
3
  import { isModelKeyProvider, modelKeyForwardedHeaders, modelKeyBaseUrl, modelKeyTarget, modelKeyValidationRequest, modelKeyValidationResult, } from "@fungi.computer/veil/model-keys";
3
4
  export class ModelKeyRefused extends Error {
@@ -8,10 +9,33 @@ export class ModelKeyRefused extends Error {
8
9
  this.name = "ModelKeyRefused";
9
10
  }
10
11
  }
12
+ const isProvider = (value) => value === "cloudflare-workers-ai" || isModelKeyProvider(value);
13
+ const cloudflareCredentialSchema = Schema.Struct({
14
+ apiKey: Schema.NonEmptyString,
15
+ accountId: Schema.String.check(Schema.isPattern(/^[a-f0-9]{32}$/u)),
16
+ });
17
+ const decodeCloudflareCredential = Schema.decodeUnknownOption(Schema.fromJsonString(cloudflareCredentialSchema));
18
+ function readCloudflareCredential(secret) {
19
+ const parsed = decodeCloudflareCredential(secret);
20
+ if (parsed._tag === "None")
21
+ throw new ModelKeyRefused("custody_unavailable");
22
+ return parsed.value;
23
+ }
24
+ const cloudflareBase = (accountId) => `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1`;
25
+ function providerConfiguration(provider, secret) {
26
+ if (provider === "cloudflare-workers-ai") {
27
+ const credential = readCloudflareCredential(secret);
28
+ return {
29
+ apiKey: credential.apiKey,
30
+ baseUrl: cloudflareBase(credential.accountId),
31
+ };
32
+ }
33
+ return { apiKey: secret, baseUrl: modelKeyBaseUrl(provider) };
34
+ }
11
35
  const kindOf = (provider) => `model-key/${provider}`;
12
36
  const providerOf = (kind) => {
13
37
  const provider = kind.slice("model-key/".length);
14
- if (!isModelKeyProvider(provider))
38
+ if (!isProvider(provider))
15
39
  throw new ModelKeyRefused("invalid_key");
16
40
  return provider;
17
41
  };
@@ -75,7 +99,7 @@ export function createModelKeyVault(options) {
75
99
  /** Validate with one cheap authenticated read, then store only the sealed key. */
76
100
  async seal(input) {
77
101
  const { provider, label, apiKey } = input;
78
- if (!isModelKeyProvider(provider) ||
102
+ if (!isProvider(provider) ||
79
103
  provider === "openai-compatible" ||
80
104
  label.length === 0 ||
81
105
  label.length > 64 ||
@@ -84,8 +108,27 @@ export function createModelKeyVault(options) {
84
108
  throw new ModelKeyRefused("invalid_key");
85
109
  if (credentialKey === undefined)
86
110
  throw new ModelKeyRefused("custody_unavailable");
87
- const baseUrl = modelKeyBaseUrl(provider);
88
- const probe = modelKeyValidationRequest({ provider, baseUrl }, AbortSignal.timeout(15_000));
111
+ let secret = apiKey;
112
+ let probe;
113
+ if (provider === "cloudflare-workers-ai") {
114
+ const credential = Schema.decodeUnknownOption(cloudflareCredentialSchema)({
115
+ apiKey,
116
+ accountId: input.accountId,
117
+ });
118
+ if (credential._tag === "None")
119
+ throw new ModelKeyRefused("invalid_key");
120
+ secret = JSON.stringify(credential.value);
121
+ // Cloudflare’s authenticated model search spends no inference tokens.
122
+ probe = new Request(`https://api.cloudflare.com/client/v4/accounts/${credential.value.accountId}/ai/models/search?per_page=1`, {
123
+ headers: { accept: "application/json" },
124
+ signal: AbortSignal.timeout(15_000),
125
+ });
126
+ }
127
+ else {
128
+ if (input.accountId !== undefined)
129
+ throw new ModelKeyRefused("invalid_key");
130
+ probe = modelKeyValidationRequest({ provider, baseUrl: modelKeyBaseUrl(provider) }, AbortSignal.timeout(15_000));
131
+ }
89
132
  let status;
90
133
  try {
91
134
  const response = await send(new Request(probe, {
@@ -103,7 +146,7 @@ export function createModelKeyVault(options) {
103
146
  throw new ModelKeyRefused("key_rejected");
104
147
  if (verdict === "unavailable")
105
148
  throw new ModelKeyRefused("provider_unavailable");
106
- return publicRecord(await custody(() => credentials.put({ kind: kindOf(provider), label, secret: apiKey })));
149
+ return publicRecord(await custody(() => credentials.put({ kind: kindOf(provider), label, secret })));
107
150
  },
108
151
  async list() {
109
152
  return (await custody(() => store().list()))
@@ -114,20 +157,24 @@ export function createModelKeyVault(options) {
114
157
  const record = await custody(() => store().get(keyId));
115
158
  return record === null ? null : publicRecord(record);
116
159
  },
160
+ /** Host-only model configuration; the token never leaves its sealed callback. */
161
+ baseUrl(keyId) {
162
+ return custody(() => store().withSecret(keyId, (secret, record) => {
163
+ const provider = providerOf(record.kind);
164
+ return Promise.resolve(providerConfiguration(provider, secret).baseUrl);
165
+ }));
166
+ },
117
167
  remove(keyId) {
118
168
  return custody(() => store().remove(keyId));
119
169
  },
120
170
  /** Send one provider request with the key attached; the caller's auth is dropped. */
121
171
  send(keyId, request) {
122
- return custody(() => store().withSecret(keyId, (apiKey, record) => {
172
+ return custody(() => store().withSecret(keyId, (secret, record) => {
123
173
  const provider = providerOf(record.kind);
174
+ const credential = providerConfiguration(provider, secret);
124
175
  let target;
125
176
  try {
126
- target = modelKeyTarget({
127
- locator: record.credentialId,
128
- provider,
129
- baseUrl: modelKeyBaseUrl(provider),
130
- }, request);
177
+ target = modelKeyTarget({ baseUrl: credential.baseUrl }, request);
131
178
  }
132
179
  catch {
133
180
  throw new ModelKeyRefused("target_denied");
@@ -135,7 +182,7 @@ export function createModelKeyVault(options) {
135
182
  // `duplex` is a Node/Workers extension lib.dom's RequestInit omits.
136
183
  const init = {
137
184
  method: request.method,
138
- headers: authenticated(provider, modelKeyForwardedHeaders(request), apiKey),
185
+ headers: authenticated(provider, modelKeyForwardedHeaders(request), credential.apiKey),
139
186
  body: request.method === "GET" ? null : request.body,
140
187
  signal: request.signal,
141
188
  duplex: "half",
@@ -138,17 +138,19 @@ Fungi release on the
138
138
  [package versions page](https://docs.fungi.computer/reference/packages/), and
139
139
  follow [Upgrade Oyster](https://docs.fungi.computer/guides/run-your-own-oyster/)
140
140
  with the package manager and store that installed the project. Redeploy with the
141
- same `npx wrangler deploy` command, then run `npx oyster install-apps`. If pnpm
142
- stops with `ERR_PNPM_UNEXPECTED_STORE`, rerun with `--store-dir` set to the
143
- store the error names.
141
+ same `npx wrangler deploy` command, then run
142
+ `npx @fungi.computer/oyster install-apps`. If pnpm stops with
143
+ `ERR_PNPM_UNEXPECTED_STORE`, rerun with `--store-dir` set to the store the error
144
+ names.
144
145
 
145
146
  Two older upgrades reset data rather than convert it. From before 0.7.0, the
146
147
  installed Apps are cleared once: Oyster Home asks you to reinstall them with
147
- `npx oyster install-apps`, which restores the Apps and their App settings, while
148
- each App's own backend database starts empty. Agents, Sessions, files and keys
149
- are kept. From 0.2 or earlier, Oyster answers every request with `409` and
150
- `store_from_older_oyster`; deploy under new resource names or tear the old one
151
- down first. The changelog entry for each release says when it resets data.
148
+ `npx @fungi.computer/oyster install-apps`, which restores the Apps and their App
149
+ settings, while each App's own backend database starts empty. Agents, Sessions,
150
+ files and keys are kept. From 0.2 or earlier, Oyster answers every request with
151
+ `409` and `store_from_older_oyster`; deploy under new resource names or tear the
152
+ old one down first. The changelog entry for each release says when it resets
153
+ data.
152
154
 
153
155
  ### Run on celld
154
156
 
@@ -330,23 +330,9 @@ type OysterAgents = Readonly<{
330
330
  media: "ready" | "missing";
331
331
  }>
332
332
  >;
333
- modelKeys: Promise<
334
- readonly Readonly<{
335
- keyId: string;
336
- provider: ModelKeyProvider;
337
- label: string;
338
- createdAt: number;
339
- validatedAt: number;
340
- }>[]
341
- >;
333
+ modelKeys: Promise<readonly ModelKeyRecord[]>;
342
334
  sealModelKey: Promise<
343
- | Readonly<{
344
- keyId: string;
345
- provider: ModelKeyProvider;
346
- label: string;
347
- createdAt: number;
348
- validatedAt: number;
349
- }>
335
+ | ModelKeyRecord
350
336
  | Readonly<{
351
337
  error: ModelKeyRefusal;
352
338
  }>
@@ -465,6 +451,22 @@ Why a key could not be stored or used; stable, secret-free.
465
451
 
466
452
  ---
467
453
 
454
+ ### ModelKeyRecord
455
+
456
+ ```ts
457
+ type ModelKeyRecord = Omit<HostedModelKeyRecord, "provider"> & object;
458
+ ```
459
+
460
+ Standalone custody also accepts an owner’s Cloudflare account and token.
461
+
462
+ #### Type Declaration
463
+
464
+ | Name | Type |
465
+ | ---------- | ------------------------------------------------------------------- |
466
+ | `provider` | `HostedModelKeyRecord`\[`"provider"`\] \| `"cloudflare-workers-ai"` |
467
+
468
+ ---
469
+
468
470
  ### ModelKeySealInput
469
471
 
470
472
  ```ts
@@ -472,6 +474,7 @@ type ModelKeySealInput = Readonly<{
472
474
  provider: string;
473
475
  label: string;
474
476
  apiKey: string;
477
+ accountId?: string;
475
478
  }>;
476
479
  ```
477
480
 
package/docs/api/apps.md CHANGED
@@ -26,6 +26,7 @@ readonly read(appKey): Promise<
26
26
  installationId: string;
27
27
  appId: string;
28
28
  appName: string;
29
+ appCalls: object[];
29
30
  artifactDigest: Sha256Digest;
30
31
  permissions: {
31
32
  authority: {
@@ -139,8 +140,8 @@ and the available resources.
139
140
  ###### Returns
140
141
 
141
142
  `Promise`\< \| `"unavailable"` \| \{ `storeGeneration`: `string`;
142
- `installationId`: `string`; `appId`: `string`; `appName`: `string`;
143
- `artifactDigest`: `Sha256Digest`; `permissions`: \{ `authority`: \{
143
+ `installationId`: `string`; `appId`: `string`; `appName`: `string`; `appCalls`:
144
+ `object`[]; `artifactDigest`: `Sha256Digest`; `permissions`: \{ `authority`: \{
144
145
  `authorityVersion`: `number`; `declaredOperationsDigest`: `Sha256Digest`;
145
146
  `approvedGrants`: readonly `Readonly`\<\{ `capability`: \| `"computer.list"` \|
146
147
  `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \|
@@ -1556,6 +1557,11 @@ const appPermissionPageSchema: ZodObject<{
1556
1557
  installationId: ZodString;
1557
1558
  appId: ZodString;
1558
1559
  appName: ZodString;
1560
+ appCalls: ZodArray<ZodObject<{
1561
+ operation: ZodString;
1562
+ method: ZodString;
1563
+ targetName: ZodString;
1564
+ }, $strict>>;
1559
1565
  artifactDigest: ZodPipe<ZodUnknown, ZodTransform<Sha256Digest, unknown>>;
1560
1566
  permissions: ZodObject<{
1561
1567
  authority: ZodObject<{
@@ -1732,13 +1732,13 @@ both compose it here.
1732
1732
 
1733
1733
  #### Parameters
1734
1734
 
1735
- | Parameter | Type |
1736
- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1737
- | `env` | [`OysterGitEnv`](#oystergitenv) |
1738
- | `scope` | [`TenantScope`](tenant.md#tenantscope) |
1739
- | `hostOwnerRoutes` | \| [`Routes`](authorization.md#routes)\<[`OysterEnv`](host.md#oysterenv)\> \| `undefined` |
1740
- | `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`: `"owners"` \| `"runner"`; `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` |
1741
- | `computerSetup?` | () => `Promise`\<`Pick`\<`Readonly`\<\{ `models`: `SetupState`; `media`: `SetupState`; `git`: `SetupState`; `terminal`: `"unknown"` \| `"ready"` \| `"missing"` \| `"exec-only"`; `terminalReason?`: `string`; \}\>, `"terminal"` \| `"terminalReason"`\>\> |
1735
+ | Parameter | Type |
1736
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1737
+ | `env` | [`OysterGitEnv`](#oystergitenv) |
1738
+ | `scope` | [`TenantScope`](tenant.md#tenantscope) |
1739
+ | `hostOwnerRoutes` | \| [`Routes`](authorization.md#routes)\<[`OysterEnv`](host.md#oysterenv)\> \| `undefined` |
1740
+ | `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 [`ModelKeyRecord`](agents.md#modelkeyrecord)[]\>; `sealModelKey`: `Promise`\< \| [`ModelKeyRecord`](agents.md#modelkeyrecord) \| `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`: `"owners"` \| `"runner"`; `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` |
1741
+ | `computerSetup?` | () => `Promise`\<`Pick`\<`Readonly`\<\{ `models`: `SetupState`; `media`: `SetupState`; `git`: `SetupState`; `terminal`: `"unknown"` \| `"ready"` \| `"missing"` \| `"exec-only"`; `terminalReason?`: `string`; \}\>, `"terminal"` \| `"terminalReason"`\>\> |
1742
1742
 
1743
1743
  #### Returns
1744
1744