@fungi.computer/oyster 0.26.0 → 0.27.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.
@@ -7,12 +7,37 @@ import { mediaSlot } from "../media.js";
7
7
  import { computer, routes as routeTable } from "../authorization.js";
8
8
  import * as Schema from "effect/Schema";
9
9
  import { pendingSchema } from "@fungi.computer/agar/backend-definition";
10
- import { mediaGenerationDescriptionSchema, mediaGenerationJsonRequestSchema, mediaGenerationReferenceSchema, } from "@fungi.computer/agar/media-json";
11
- import { createMediaService, estimateMediaModel, mediaPendingSchema, mediaResultSchema, mediaBindingCallSchema, mediaBindingRequest, parseMediaBindingCall, readMediaBindingReply, } from "@fungi.computer/darkroom/server";
10
+ import { mediaGenerationDescriptionSchema, mediaGenerationJsonRequestSchema, mediaGenerationQuoteRequestSchema, mediaGenerationReferenceSchema, } from "@fungi.computer/agar/media-json";
11
+ import { createDailyMediaMetering, createMediaService, estimateMediaModel, mediaPendingSchema, mediaResultSchema, mediaBindingCallSchema, mediaBindingRequest, parseMediaBindingCall, readMediaBindingReply, } from "@fungi.computer/darkroom/server";
12
12
  import { createWorkersAiMediaProvider, createImagesReferenceFitter, } from "@fungi.computer/darkroom/cloudflare";
13
13
  import { oysterPrincipalId, } from "../host.js";
14
14
  import { normalizeFilePath } from "../files.js";
15
15
  import { cloudflareAccountReady } from "./cloudflare-account.js";
16
+ /** One Durable Object holds the whole Oyster's UTC-day media total. */
17
+ const DAILY_METER_NAME = "oyster-daily-media-meter";
18
+ /** $1 is 100,000 milliunits (1 cent is 1,000). */
19
+ const MILLIUNITS_PER_USD = 100_000;
20
+ const dailyLimitUsdSchema = z
21
+ .string()
22
+ .trim()
23
+ .min(1)
24
+ .transform(Number)
25
+ .pipe(z.number().nonnegative());
26
+ /** Customer copy for the daily limit; the Oyster-wide limit is not holder-specific. */
27
+ const DAILY_LIMIT_COPY = "Today's spending limit for this Oyster is used up. It resets at 00:00 UTC.";
28
+ /** The daily limit in milliunits, or undefined when the var is unset. A set but invalid
29
+ * value fails closed with a zero limit, so a typo never silently removes the cap. */
30
+ function dailyLimitMilliunits(env) {
31
+ const raw = env.OYSTER_DAILY_MEDIA_LIMIT_USD;
32
+ if (raw === undefined)
33
+ return undefined;
34
+ const parsed = dailyLimitUsdSchema.safeParse(raw);
35
+ return parsed.success ? Math.floor(parsed.data * MILLIUNITS_PER_USD) : 0;
36
+ }
37
+ /** The service's provider-cost quote for one exact request. */
38
+ const mediaQuoteSchema = z.object({
39
+ providerCostMilliunits: z.number().int().nonnegative(),
40
+ });
16
41
  /** Media capability using Darkroom execution and the existing workspace FileSource. */
17
42
  export function workersMedia(env, workspace) {
18
43
  const { computerId } = workspace;
@@ -92,6 +117,31 @@ export function workersMedia(env, workspace) {
92
117
  },
93
118
  });
94
119
  });
120
+ routes.post("/quote", computer(), async (context, { principal }) => {
121
+ const input = Schema.decodeUnknownOption(Schema.fromJsonString(mediaGenerationQuoteRequestSchema), { onExcessProperty: "error" })(await context.req.text());
122
+ if (input._tag === "None")
123
+ return context.json(invalidRequest(), 400);
124
+ const references = input.value.settings.references?.map((reference) => ({
125
+ computerId,
126
+ ...reference,
127
+ path: normalizeFilePath(reference.path),
128
+ }));
129
+ if (references?.some((reference) => reference.path === null || reference.path === "/"))
130
+ return context.json(invalidRequest(), 400);
131
+ const response = await service(principal).request("http://media/quote", {
132
+ method: "POST",
133
+ signal: context.req.raw.signal,
134
+ headers: { "Content-Type": "application/json" },
135
+ body: JSON.stringify({
136
+ settings: { ...input.value.settings, references },
137
+ }),
138
+ });
139
+ if (!response.ok)
140
+ return context.json({ error: "These settings cannot be priced" }, 400);
141
+ // A self-hosted Oyster is unmetered: the price is the provider's cost.
142
+ const { providerCostMilliunits } = mediaQuoteSchema.parse(await response.json());
143
+ return context.json({ costMilliunits: providerCostMilliunits });
144
+ });
95
145
  routes.post("/cancel-attempt", computer(), async (context) => {
96
146
  const reference = Schema.decodeUnknownOption(Schema.fromJsonString(mediaGenerationReferenceSchema), { onExcessProperty: "error" })(await context.req.text());
97
147
  if (reference._tag === "None" || reference.value.computerId !== computerId)
@@ -169,14 +219,33 @@ function standaloneMediaService(env, actorId, workspace, owner = "owner", librar
169
219
  };
170
220
  },
171
221
  };
172
- return createMediaService({
222
+ const provider = createWorkersAiMediaProvider(env.AI, env.AI_GATEWAY_ID === undefined
223
+ ? undefined
224
+ : { gateway: { id: env.AI_GATEWAY_ID } });
225
+ const limit = dailyLimitMilliunits(env);
226
+ const host = {
173
227
  scope: { actorId, namespace: "oyster", owner, destinationId: computerId },
174
228
  operations: env.MEDIA_OPERATION,
175
- provider: createWorkersAiMediaProvider(env.AI, env.AI_GATEWAY_ID === undefined
176
- ? undefined
177
- : { gateway: { id: env.AI_GATEWAY_ID } }),
178
- metering: "unmetered",
229
+ provider,
179
230
  destination: admittedDestination,
231
+ };
232
+ if (limit === undefined)
233
+ return createMediaService({ ...host, metering: "unmetered" });
234
+ const meter = env.MEDIA_OPERATION.getByName(DAILY_METER_NAME);
235
+ const { dailyAdmit, dailySettle } = meter;
236
+ if (dailyAdmit === undefined || dailySettle === undefined)
237
+ throw new Error("OYSTER_DAILY_MEDIA_LIMIT_USD needs a MEDIA_OPERATION object that serves the daily meter.");
238
+ return createMediaService({
239
+ ...host,
240
+ metering: createDailyMediaMetering({
241
+ dailyAdmit: (input) => dailyAdmit.call(meter, input),
242
+ dailySettle: (input) => dailySettle.call(meter, input),
243
+ }, limit),
244
+ refusalMessages: {
245
+ insufficient_credits: DAILY_LIMIT_COPY,
246
+ denied: DAILY_LIMIT_COPY,
247
+ daily_limit_reached: DAILY_LIMIT_COPY,
248
+ },
180
249
  });
181
250
  }
182
251
  /** The Instance gate and native guest entrypoint share these argument codecs. */
@@ -114,9 +114,13 @@ export declare abstract class StandaloneRegistry extends OysterRegistry implemen
114
114
  state: "running" | "sleeping";
115
115
  position?: never | undefined;
116
116
  } & Disposable) | ({
117
- state: "running";
117
+ state: "sleeping";
118
+ } & Disposable) | ({
119
+ error: "busy";
118
120
  } & Disposable) | ({
119
121
  error: "no_runtime";
122
+ } & Disposable) | ({
123
+ state: "running";
120
124
  } & Disposable) | {
121
125
  error: string;
122
126
  computers?: undefined;
@@ -183,6 +183,15 @@ export class StandaloneRegistry extends OysterRegistry {
183
183
  expiresAt: Date.now() + 60_000,
184
184
  provenance: { actor: memberId },
185
185
  });
186
+ case "stop":
187
+ if (!this.ownsComputer(input.computerId))
188
+ return null;
189
+ return this.#env.COMPUTER.getByName(input.computerId).stopHostedComputer({
190
+ computerId: input.computerId,
191
+ actions: new Set(["stop"]),
192
+ expiresAt: Date.now() + 60_000,
193
+ provenance: { actor: memberId },
194
+ });
186
195
  case "start":
187
196
  if (!this.ownsComputer(input.computerId))
188
197
  return null;
@@ -10,6 +10,24 @@
10
10
 
11
11
  ## Type Aliases
12
12
 
13
+ ### OysterAgentInstructions
14
+
15
+ ```ts
16
+ type OysterAgentInstructions = Readonly<{
17
+ home: Readonly<{
18
+ name: string;
19
+ }> | null;
20
+ content: string | null;
21
+ bytes: number;
22
+ limit: number;
23
+ }>;
24
+ ```
25
+
26
+ An Agent's AGENTS.md on its Home Computer, with the byte limit the host
27
+ enforces.
28
+
29
+ ---
30
+
13
31
  ### OysterAgent
14
32
 
15
33
  ```ts
@@ -189,243 +207,215 @@ This Agent's App-tool policy, in the shape Apps read it.
189
207
 
190
208
  ```ts
191
209
  type OysterAgents = Readonly<{
192
- list: Promise<
193
- readonly Readonly<{
194
- agentId: string;
195
- name: string;
196
- avatar: Avatar;
197
- sessionOperations: readonly (
198
- "agent.read" | "agent.send" | "agent.manage"
199
- )[];
200
- }>[]
201
- >;
210
+ list: Promise<readonly Readonly<{
211
+ agentId: string;
212
+ name: string;
213
+ avatar: Avatar;
214
+ sessionOperations: readonly ("agent.read" | "agent.send" | "agent.manage")[];
215
+ }>[]>;
202
216
  ensureStarter: Promise<StarterOutcome>;
203
217
  setArchived: Promise<
204
- | Readonly<{
205
- archived: boolean;
206
- revision: number;
207
- }>
208
- | Readonly<{
209
- error:
210
- | "not_found"
211
- | "not_granted"
212
- | "self"
213
- | "not_creator"
214
- | "running"
215
- | "pending"
216
- | "unreadable"
217
- | "archived";
218
- message?: string;
219
- archived?: boolean;
220
- revision?: number;
221
- }>
222
- >;
223
- create: Promise<
224
- Readonly<{
225
- agentId: string;
226
- name: string;
227
- avatar: Avatar;
228
- sessionOperations: readonly (
229
- "agent.read" | "agent.send" | "agent.manage"
230
- )[];
231
- }>
232
- >;
218
+ | Readonly<{
219
+ archived: boolean;
220
+ revision: number;
221
+ }>
222
+ | Readonly<{
223
+ error: | "not_found"
224
+ | "not_granted"
225
+ | "self"
226
+ | "not_creator"
227
+ | "running"
228
+ | "pending"
229
+ | "unreadable"
230
+ | "archived";
231
+ message?: string;
232
+ archived?: boolean;
233
+ revision?: number;
234
+ }>>;
235
+ create: Promise<Readonly<{
236
+ agentId: string;
237
+ name: string;
238
+ avatar: Avatar;
239
+ sessionOperations: readonly ("agent.read" | "agent.send" | "agent.manage")[];
240
+ }>>;
233
241
  rename: Promise<
234
- | Readonly<{
235
- agentId: string;
236
- name: string;
237
- avatar: Avatar;
238
- sessionOperations: readonly (
239
- "agent.read" | "agent.send" | "agent.manage"
240
- )[];
241
- }>
242
- | Readonly<{
243
- error: "not_found" | "name_taken" | "not_granted";
244
- }>
245
- >;
242
+ | Readonly<{
243
+ agentId: string;
244
+ name: string;
245
+ avatar: Avatar;
246
+ sessionOperations: readonly ("agent.read" | "agent.send" | "agent.manage")[];
247
+ }>
248
+ | Readonly<{
249
+ error: "not_found" | "name_taken" | "not_granted";
250
+ }>>;
246
251
  setAvatar: Promise<
247
- | Readonly<{
248
- agentId: string;
249
- name: string;
250
- avatar: Avatar;
251
- sessionOperations: readonly (
252
- "agent.read" | "agent.send" | "agent.manage"
253
- )[];
254
- }>
255
- | Readonly<{
256
- error: "not_found" | "not_granted";
257
- }>
258
- >;
259
- readModelChoice: Promise<{
260
- keySource: "workers-ai" | "ai-gateway" | "byok";
261
- model: {
262
- providerId: Schema.String;
263
- modelId: Schema.String;
264
- reasoning?: Schema.optional<
265
- Schema.Literals<
266
- readonly ["minimal", "low", "medium", "high", "xhigh", "max"]
267
- >
268
- >;
269
- };
270
- keyId?: string;
271
- } | null>;
252
+ | Readonly<{
253
+ agentId: string;
254
+ name: string;
255
+ avatar: Avatar;
256
+ sessionOperations: readonly ("agent.read" | "agent.send" | "agent.manage")[];
257
+ }>
258
+ | Readonly<{
259
+ error: "not_found" | "not_granted";
260
+ }>>;
261
+ readModelChoice: Promise<
262
+ | {
263
+ keySource: "workers-ai" | "ai-gateway" | "byok";
264
+ model: {
265
+ providerId: Schema.String;
266
+ modelId: Schema.String;
267
+ reasoning?: Schema.optional<Schema.Literals<readonly ["minimal", "low", "medium", "high", "xhigh", "max"]>>;
268
+ };
269
+ keyId?: string;
270
+ }
271
+ | null>;
272
272
  readInstructions: Promise<
273
- | Readonly<{
274
- agentId: string;
275
- instructions: string;
276
- }>
277
- | Readonly<{
278
- error: "not_found" | "not_granted";
273
+ | Readonly<object & Readonly<{
274
+ home: | Readonly<{
275
+ name: ...;
279
276
  }>
280
- >;
277
+ | null;
278
+ content: string | null;
279
+ bytes: number;
280
+ limit: number;
281
+ }>>
282
+ | Readonly<{
283
+ error: "not_found" | "not_granted";
284
+ }>>;
281
285
  setInstructions: Promise<
282
- | Readonly<{
283
- agentId: string;
284
- instructions: string;
285
- }>
286
- | Readonly<{
287
- error: "not_found" | "not_granted";
286
+ | Readonly<object & Readonly<{
287
+ home: | Readonly<{
288
+ name: ...;
288
289
  }>
289
- >;
290
- decodeModelChoice: {
291
- keySource: "workers-ai" | "ai-gateway" | "byok";
292
- model: {
293
- providerId: Schema.String;
294
- modelId: Schema.String;
295
- reasoning?: Schema.optional<
296
- Schema.Literals<
297
- readonly ["minimal", "low", "medium", "high", "xhigh", "max"]
298
- >
299
- >;
300
- };
301
- keyId?: string;
302
- } | null;
290
+ | null;
291
+ content: string | null;
292
+ bytes: number;
293
+ limit: number;
294
+ }>>
295
+ | Readonly<{
296
+ error: "not_found" | "not_granted" | "conflict" | "too_large" | "no_home";
297
+ }>>;
298
+ decodeModelChoice: | {
299
+ keySource: "workers-ai" | "ai-gateway" | "byok";
300
+ model: {
301
+ providerId: Schema.String;
302
+ modelId: Schema.String;
303
+ reasoning?: Schema.optional<Schema.Literals<readonly ["minimal", "low", "medium", "high", "xhigh", "max"]>>;
304
+ };
305
+ keyId?: string;
306
+ }
307
+ | null;
303
308
  setModelChoice: Promise<
304
- | {
305
- keySource: "workers-ai" | "ai-gateway" | "byok";
306
- model: {
307
- providerId: Schema.String;
308
- modelId: Schema.String;
309
- reasoning?: Schema.optional<
310
- Schema.Literals<
311
- readonly ["minimal", "low", "medium", "high", "xhigh", "max"]
312
- >
313
- >;
314
- };
315
- keyId?: string;
316
- }
317
- | Readonly<{
318
- error: "not_found" | "not_granted" | AgentModelRefusal;
319
- }>
320
- >;
321
- policyStatus: Promise<Readonly<{
322
- status: "pending" | "approved";
323
- revision: string;
324
- }> | null>;
325
- appToolPolicy: Promise<{
326
- level: "read" | "write";
327
- revision: string;
328
- grantedBy: string;
329
- } | null>;
309
+ | {
310
+ keySource: "workers-ai" | "ai-gateway" | "byok";
311
+ model: {
312
+ providerId: Schema.String;
313
+ modelId: Schema.String;
314
+ reasoning?: Schema.optional<Schema.Literals<readonly ["minimal", "low", "medium", "high", "xhigh", "max"]>>;
315
+ };
316
+ keyId?: string;
317
+ }
318
+ | Readonly<{
319
+ error: "not_found" | "not_granted" | AgentModelRefusal;
320
+ }>>;
321
+ policyStatus: Promise<
322
+ | Readonly<{
323
+ status: "pending" | "approved";
324
+ revision: string;
325
+ }>
326
+ | null>;
327
+ appToolPolicy: Promise<
328
+ | {
329
+ level: "read" | "write";
330
+ revision: string;
331
+ grantedBy: string;
332
+ }
333
+ | null>;
330
334
  policyRevision: Promise<string | null>;
331
335
  approveAppToolPolicy: Promise<
332
- | {
333
- level: "read" | "write";
334
- revision: string;
335
- grantedBy: string;
336
- }
337
- | Readonly<{
338
- status: "pending";
339
- revision: string;
340
- }>
341
- | Readonly<{
342
- error: "not_found" | "revision_conflict" | "not_granted";
343
- }>
344
- >;
345
- setup: Promise<
346
- Readonly<{
347
- models: "ready" | "missing";
348
- media: "ready" | "missing";
349
- }>
350
- >;
351
- modelKeys: Promise<
352
- readonly Readonly<{
353
- keyId: string;
354
- provider: StandaloneModelKeyProvider;
355
- label: string;
356
- createdAt: number;
357
- validatedAt: number;
358
- }>[]
359
- >;
336
+ | {
337
+ level: "read" | "write";
338
+ revision: string;
339
+ grantedBy: string;
340
+ }
341
+ | Readonly<{
342
+ status: "pending";
343
+ revision: string;
344
+ }>
345
+ | Readonly<{
346
+ error: "not_found" | "revision_conflict" | "not_granted";
347
+ }>>;
348
+ setup: Promise<Readonly<{
349
+ models: "ready" | "missing";
350
+ media: "ready" | "missing";
351
+ }>>;
352
+ modelKeys: Promise<readonly Readonly<{
353
+ keyId: string;
354
+ provider: StandaloneModelKeyProvider;
355
+ label: string;
356
+ createdAt: number;
357
+ validatedAt: number;
358
+ }>[]>;
360
359
  sealModelKey: Promise<
361
- | Readonly<{
362
- keyId: string;
363
- provider: StandaloneModelKeyProvider;
364
- label: string;
365
- createdAt: number;
366
- validatedAt: number;
367
- }>
368
- | Readonly<{
369
- error: ModelKeyRefusal;
370
- }>
371
- >;
360
+ | Readonly<{
361
+ keyId: string;
362
+ provider: StandaloneModelKeyProvider;
363
+ label: string;
364
+ createdAt: number;
365
+ validatedAt: number;
366
+ }>
367
+ | Readonly<{
368
+ error: ModelKeyRefusal;
369
+ }>>;
372
370
  removeModelKey: Promise<"deleted" | "absent">;
373
- connections: Promise<
374
- readonly Readonly<{
375
- connectionId: string;
376
- name: string;
377
- label: string;
378
- kind: "mcp" | "openapi";
379
- url: string;
380
- auth: "none" | "token" | "oauth";
381
- state: "connected" | "pending" | "reconnect_required";
382
- grants: readonly Readonly<{
371
+ connections: Promise<readonly Readonly<{
372
+ connectionId: string;
373
+ name: string;
374
+ label: string;
375
+ kind: "mcp" | "openapi";
376
+ url: string;
377
+ auth: "none" | "token" | "oauth";
378
+ state: "connected" | "pending" | "reconnect_required";
379
+ grants: readonly Readonly<{
383
380
  agentId: string;
384
381
  access: ConnectionAccess;
385
- }>[];
386
- }>[]
387
- >;
382
+ }>[];
383
+ }>[]>;
388
384
  addConnection: Promise<
389
- | Readonly<{
390
- connectionId: string;
391
- authorizeUrl: string | null;
392
- }>
393
- | Readonly<{
394
- error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
395
- }>
396
- >;
385
+ | Readonly<{
386
+ connectionId: string;
387
+ authorizeUrl: string | null;
388
+ }>
389
+ | Readonly<{
390
+ error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
391
+ }>>;
397
392
  grantConnection: Promise<
398
- | Readonly<{
399
- error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
400
- }>
401
- | Readonly<{
402
- ok: true;
403
- }>
404
- >;
393
+ | Readonly<{
394
+ error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
395
+ }>
396
+ | Readonly<{
397
+ ok: true;
398
+ }>>;
405
399
  ungrantConnection: Promise<boolean>;
406
400
  removeConnection: Promise<boolean>;
407
401
  connectionTools: Promise<
408
- | readonly string[]
409
- | Readonly<{
410
- error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
411
- }>
412
- >;
402
+ | readonly string[]
403
+ | Readonly<{
404
+ error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
405
+ }>>;
413
406
  completeMcpConnection: Promise<
414
- | Readonly<{
415
- ok: true;
416
- }>
417
- | Readonly<{
418
- error: string;
419
- }>
420
- >;
407
+ | Readonly<{
408
+ ok: true;
409
+ }>
410
+ | Readonly<{
411
+ error: string;
412
+ }>>;
421
413
  mcpCallbackUrl: string;
422
414
  fetch: Promise<Response | null>;
423
- inbox: Promise<
424
- Readonly<{
425
- items: readonly OysterInboxItem[];
426
- revision: number;
427
- }>
428
- >;
415
+ inbox: Promise<Readonly<{
416
+ items: readonly OysterInboxItem[];
417
+ revision: number;
418
+ }>>;
429
419
  revision: Promise<number>;
430
420
  visit: Promise<boolean>;
431
421
  }>;