@fungi.computer/oyster 0.25.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.
Files changed (49) hide show
  1. package/dist/agents.d.ts +24 -8
  2. package/dist/agents.js +12 -5
  3. package/dist/app-builds.d.ts +4 -2
  4. package/dist/app-builds.js +14 -0
  5. package/dist/apps/catalog.js +1 -1
  6. package/dist/boot-host-script.js +1 -1
  7. package/dist/build/build-memory.d.ts +13 -0
  8. package/dist/build/build-memory.js +29 -0
  9. package/dist/build/candidate-cli.mjs +25 -2
  10. package/dist/build/local-build.js +4 -5
  11. package/dist/cloudflare.d.ts +2 -2
  12. package/dist/cloudflare.js +3 -0
  13. package/dist/computer-control-port.d.ts +2 -0
  14. package/dist/embed-metafiles.js +2 -2
  15. package/dist/embed-scripts.js +1 -1
  16. package/dist/hello-app-script.js +1 -1
  17. package/dist/mcp.d.ts +26 -0
  18. package/dist/mcp.js +12 -2
  19. package/dist/media.d.ts +5 -0
  20. package/dist/media.js +1 -0
  21. package/dist/page-script.js +2 -2
  22. package/dist/release.d.ts +5 -0
  23. package/dist/standalone/agent-computers.js +17 -1
  24. package/dist/standalone/agents.d.ts +16 -8
  25. package/dist/standalone/agents.js +88 -25
  26. package/dist/standalone/app-set.d.ts +11 -3
  27. package/dist/standalone/app-set.js +26 -8
  28. package/dist/standalone/computer-control.js +7 -1
  29. package/dist/standalone/computer-fleet.d.ts +6 -0
  30. package/dist/standalone/computer-fleet.js +9 -1
  31. package/dist/standalone/computer-skill-source.d.ts +20 -0
  32. package/dist/standalone/computer-skill-source.js +165 -0
  33. package/dist/standalone/computer.d.ts +30 -4
  34. package/dist/standalone/computer.js +60 -3
  35. package/dist/standalone/install-apps-cli.js +9 -3
  36. package/dist/standalone/media.d.ts +9 -4
  37. package/dist/standalone/media.js +76 -7
  38. package/dist/standalone/registry.d.ts +8 -1
  39. package/dist/standalone/registry.js +10 -1
  40. package/docs/api/agents.md +204 -214
  41. package/docs/api/apps.md +33 -33
  42. package/docs/api/cloudflare.md +4 -1
  43. package/docs/api/mcp.md +52 -46
  44. package/docs/api/media.md +4 -0
  45. package/docs/api/workers-git.md +7 -7
  46. package/examples/standalone/wrangler.jsonc +3 -0
  47. package/package.json +19 -23
  48. package/dist/agent-instructions.d.ts +0 -35
  49. package/dist/agent-instructions.js +0 -42
@@ -0,0 +1,165 @@
1
+ import { admitSkill, maximumDirectoryEntries, maximumFileBytes, newSkillAdmission, parseSkill, skillCatalogOf, skillDiagnostic, skillExplanation, skillFileSchema, SkillSourceError, } from "@fungi.computer/shiitake-extensions/skills/discovery";
2
+ import { defineIdFamily } from "@fungi.computer/cairn/id";
3
+ import { z } from "zod";
4
+ /** Each Files call this source makes is its own invocation. */
5
+ const skillIds = defineIdFamily({
6
+ family: "computer-skills",
7
+ version: 1,
8
+ kinds: { execution: { prefix: "skill_exec" } },
9
+ });
10
+ /** Where the Computer keeps skills, searched in this order; the first name wins. */
11
+ const skillRoots = [".fungi/skills", ".agents/skills"];
12
+ /** What a person is told when no skill is installed on the Computer. */
13
+ export const computerSkillsEmpty = "No skills are installed; put one at .agents/skills/<name>/SKILL.md on the Computer.";
14
+ const nameLength = z.string().min(1);
15
+ const segments = (path) => path.split("/").filter(Boolean);
16
+ const fileName = (path) => segments(path).at(-1) ?? "";
17
+ const directoryOf = (path) => `/${segments(path).slice(0, -1).join("/")}`;
18
+ /** The model's view of a skill file: bare when one Computer, else a computer:// locator. */
19
+ function located(computer, path, several) {
20
+ return several
21
+ ? `computer://${encodeURIComponent(computer)}${path.startsWith("/") ? path : `/${path}`}`
22
+ : path;
23
+ }
24
+ /** Read one whole file or refuse it plainly: oversized, not text, or unreadable. */
25
+ async function readWhole(port, path, signal) {
26
+ signal.throwIfAborted();
27
+ let page;
28
+ try {
29
+ page = await port.read({ path, offset: 0, limit: maximumFileBytes }, invocation(signal));
30
+ }
31
+ catch (cause) {
32
+ signal.throwIfAborted();
33
+ throw new SkillSourceError("Skill file cannot be read", { cause });
34
+ }
35
+ if (!("content" in page))
36
+ throw new SkillSourceError("Skill file is not text");
37
+ if (page.truncated)
38
+ throw new SkillSourceError("Skill file exceeds the 128 KiB bound");
39
+ return page.content;
40
+ }
41
+ function invocation(signal) {
42
+ return {
43
+ executionId: skillIds.execution.generate(),
44
+ deadlineAt: null,
45
+ signal,
46
+ };
47
+ }
48
+ /** Skill folders under one root of one Computer, found by their SKILL.md. */
49
+ async function findSkillFiles(port, root, signal, diagnostics) {
50
+ let found;
51
+ try {
52
+ found = await port.glob({ path: root, pattern: "**/SKILL.md", limit: 256 }, invocation(signal));
53
+ }
54
+ catch {
55
+ // A Computer without the folder, or one the Agent may not search, has no skills here.
56
+ signal.throwIfAborted();
57
+ return [];
58
+ }
59
+ if (found.truncated !== null)
60
+ diagnostics.push(skillDiagnostic(root, "bound", "Skill discovery exceeds its 256-skill search bound"));
61
+ const files = [];
62
+ for (const row of found.results) {
63
+ if (row.type === "directory")
64
+ continue;
65
+ const inside = row.path.startsWith("/") ? row.path : `/${row.path}`;
66
+ const relative = segments(inside).slice(segments(root).length);
67
+ // Like Local: dot folders and node_modules are not searched.
68
+ if (relative
69
+ .slice(0, -1)
70
+ .some((part) => part.startsWith(".") || part === "node_modules")) {
71
+ diagnostics.push(skillDiagnostic(inside, "skipped", "Dot directories and node_modules are not searched"));
72
+ continue;
73
+ }
74
+ files.push(inside);
75
+ }
76
+ return files.sort();
77
+ }
78
+ /** Discover and load the skills on the Agent's attached Computers. */
79
+ export function createComputerSkillSource(options) {
80
+ const scan = async (signal) => {
81
+ const computers = await options.computers();
82
+ const several = computers.length > 1;
83
+ const state = newSkillAdmission();
84
+ const homes = new Map();
85
+ for (const computer of computers) {
86
+ for (const root of skillRoots) {
87
+ signal.throwIfAborted();
88
+ const files = await findSkillFiles(computer.port, root, signal, state.diagnostics);
89
+ for (const path of files) {
90
+ const directoryName = fileName(directoryOf(path));
91
+ const skillPath = located(computer.name, path, several);
92
+ try {
93
+ const { metadata } = parseSkill(await readWhole(computer.port, path, signal), directoryName);
94
+ const before = state.skills.length;
95
+ admitSkill(state, {
96
+ metadata,
97
+ directoryName,
98
+ skillPath,
99
+ location: skillPath,
100
+ displayLocation: skillPath,
101
+ origin: { kind: "project" },
102
+ });
103
+ if (state.skills.length > before)
104
+ homes.set(metadata.name, { computer, location: path });
105
+ }
106
+ catch (cause) {
107
+ signal.throwIfAborted();
108
+ state.diagnostics.push({
109
+ path: skillPath,
110
+ reason: "invalid",
111
+ message: skillExplanation(cause, "Skill metadata or file is invalid"),
112
+ cause,
113
+ });
114
+ }
115
+ }
116
+ }
117
+ }
118
+ if (state.skills.length === 0 && state.diagnostics.length === 0)
119
+ state.diagnostics.push(skillDiagnostic(".agents/skills", "empty", "No skill folders on the Computer"));
120
+ return { catalog: skillCatalogOf(state), homes };
121
+ };
122
+ return {
123
+ catalog: async (signal) => (await scan(signal)).catalog,
124
+ read: async (name, file, signal) => {
125
+ nameLength.parse(name);
126
+ const { catalog, homes } = await scan(signal);
127
+ const home = homes.get(name);
128
+ const found = catalog.skills.find((skill) => skill.name === name);
129
+ if (home === undefined || found === undefined)
130
+ throw new Error(`Unknown or hidden skill: ${name}`);
131
+ const baseDirectory = directoryOf(home.location);
132
+ const selected = file === undefined ? "SKILL.md" : skillFileSchema.parse(file);
133
+ const content = await readWhole(home.computer.port, `${baseDirectory}/${selected}`, signal);
134
+ if (selected !== "SKILL.md")
135
+ return {
136
+ name,
137
+ file: selected,
138
+ content,
139
+ baseDirectory,
140
+ supportingFiles: [],
141
+ };
142
+ const parsed = parseSkill(content, fileName(baseDirectory));
143
+ if (parsed.metadata["disable-model-invocation"])
144
+ throw new Error(`Hidden skill: ${name}`);
145
+ const listed = await home.computer.port.glob({ path: baseDirectory, pattern: "**/*", limit: 256 }, invocation(signal));
146
+ if (listed.truncated !== null ||
147
+ listed.results.length > maximumDirectoryEntries)
148
+ throw new SkillSourceError("Skill supporting files exceed the entry bound");
149
+ const prefix = `${baseDirectory}/`;
150
+ const supportingFiles = listed.results
151
+ .filter((row) => row.type !== "directory")
152
+ .map((row) => (row.path.startsWith("/") ? row.path : `/${row.path}`))
153
+ .filter((path) => path.startsWith(prefix) && path !== home.location)
154
+ .map((path) => path.slice(prefix.length))
155
+ .sort();
156
+ return {
157
+ name,
158
+ file: selected,
159
+ content: parsed.body,
160
+ baseDirectory,
161
+ supportingFiles,
162
+ };
163
+ },
164
+ };
165
+ }
@@ -1,3 +1,4 @@
1
+ import { type ComputerSize } from "@fungi.computer/computer/backing";
1
2
  import { type AppMethodRefusedReply } from "@fungi.computer/agar/backend";
2
3
  import { type ComputerPorts } from "@fungi.computer/agar/computer";
3
4
  import { type PreviewSelector } from "./preview.js";
@@ -6,7 +7,7 @@ import * as z from "zod";
6
7
  import { computerProcessSchema, computerToolResultSchema, readOutputSchema } from "@fungi.computer/computer-contract";
7
8
  import { ComputerDO as NativeComputerDO, type AttachedBackend, type ComputerEnv, type ComputerFilesRpc } from "@fungi.computer/computer";
8
9
  import { patchInputSchema, patchOutputSchema } from "@fungi.computer/knapsack/files-patch";
9
- import { listOutputSchema, writeOutputSchema, mkdirOutputSchema, moveOutputSchema, computerPortsOutputSchema, computerPortOutputSchema, computerPortRemovalOutputSchema, processListOutputSchema, processKillOutputSchema, processLogsOutputSchema, computerOperationResultSchema, type ComputerExecutionHostHooks, type ComputerValue } from "@fungi.computer/computer-contract";
10
+ import { listOutputSchema, writeOutputSchema, mkdirOutputSchema, moveOutputSchema, computerPortsOutputSchema, computerPortOutputSchema, computerPortRemovalOutputSchema, processListOutputSchema, processKillOutputSchema, processLogsOutputSchema, processWaitOutputSchema, computerOperationResultSchema, type ComputerExecutionHostHooks, type ComputerValue } from "@fungi.computer/computer-contract";
10
11
  import { type WorkflowGitCredential, type WorkflowGitPassGrant } from "@fungi.computer/braid/runtime";
11
12
  import { type ComputerAction, type ComputerBackendView, type ComputerGrant, type LocalBackendAttachInput, type LocalBackendDetachInput } from "@fungi.computer/computer/fleet";
12
13
  import type { InvocationFrame } from "../invocation.js";
@@ -40,7 +41,7 @@ export type StandaloneComputerResult = z.output<typeof listOutputSchema> | Reado
40
41
  truncated: boolean;
41
42
  }> | Readonly<{
42
43
  error: "conflict" | "no_runtime" | "not_found" | "invalid";
43
- }> | z.output<typeof writeOutputSchema> | z.output<typeof moveOutputSchema> | z.output<typeof mkdirOutputSchema> | z.output<typeof computerPortsOutputSchema> | z.output<typeof computerPortOutputSchema> | z.output<typeof computerPortRemovalOutputSchema> | z.output<typeof processListOutputSchema> | z.output<typeof processKillOutputSchema> | z.output<typeof processLogsOutputSchema> | z.output<typeof computerProcessSchema> | ComputerPorts["ports"][number] | z.output<typeof computerOperationResultSchema> | z.output<typeof readOutputSchema> | z.output<typeof computerToolResultSchema>;
44
+ }> | z.output<typeof writeOutputSchema> | z.output<typeof moveOutputSchema> | z.output<typeof mkdirOutputSchema> | z.output<typeof computerPortsOutputSchema> | z.output<typeof computerPortOutputSchema> | z.output<typeof computerPortRemovalOutputSchema> | z.output<typeof processListOutputSchema> | z.output<typeof processKillOutputSchema> | z.output<typeof processLogsOutputSchema> | z.output<typeof processWaitOutputSchema> | z.output<typeof computerProcessSchema> | ComputerPorts["ports"][number] | z.output<typeof computerOperationResultSchema> | z.output<typeof readOutputSchema> | z.output<typeof computerToolResultSchema>;
44
45
  /**
45
46
  * A port-preview listing, or the typed refusal the owner route presents with
46
47
  * {@link appMethodRefusalStatus}. A refusal never escapes as a 500.
@@ -86,8 +87,10 @@ export declare class ComputerDO extends NativeComputerDO implements ComputerFetc
86
87
  * name from the configured id once the namespace verifies it.
87
88
  */
88
89
  protected nameCandidates(): readonly string[];
90
+ /** The size fixed at creation; a Computer never created by the fleet has none. */
91
+ protected computerSize(): ComputerSize;
89
92
  /** Install the fleet's creation projection before exposing its new identity. */
90
- initializeFleetBackings(backings: readonly AttachedBackend[]): void;
93
+ initializeFleetBackings(backings: readonly AttachedBackend[], size: ComputerSize): void;
91
94
  /** The owner's attached backends with live status. Reads wake nothing. */
92
95
  readBackends(authority: ComputerGrant, actor: string): ComputerBackendView[];
93
96
  /** Attach the owner's machine; a replay of the same request returns it. */
@@ -118,6 +121,14 @@ export declare class ComputerDO extends NativeComputerDO implements ComputerFetc
118
121
  } | {
119
122
  error: "no_runtime";
120
123
  }>;
124
+ /** An admitted fleet control stops exactly this Computer's hosted backend. */
125
+ stopHostedComputer(authority: ComputerGrant): Promise<{
126
+ state: "sleeping";
127
+ } | {
128
+ error: "busy";
129
+ } | {
130
+ error: "no_runtime";
131
+ }>;
121
132
  /** Runtime facts for the host's owner-admitted setup read. */
122
133
  runtimeSetup(): {
123
134
  terminal: "exec-only";
@@ -191,7 +202,7 @@ export declare class ComputerDO extends NativeComputerDO implements ComputerFetc
191
202
  fileWrite(authority: ComputerGrant, path: string, bytes: Uint8Array): Promise<void>;
192
203
  /** Patch is handled by the Computer's pinned native engine, not by the Agent. */
193
204
  filePatch(authority: ComputerGrant, input: z.output<typeof patchInputSchema>): Promise<z.output<typeof patchOutputSchema>>;
194
- fileReplace(authority: ComputerGrant, path: string, expectedContent: string, content: string): Promise<{
205
+ fileReplace(authority: ComputerGrant, path: string, expectedContent: string | null, content: string): Promise<{
195
206
  path: string;
196
207
  bytes: number;
197
208
  kind: "replaced";
@@ -210,6 +221,21 @@ export declare class ComputerDO extends NativeComputerDO implements ComputerFetc
210
221
  * Computer, rather than reading `env.KEYS` directly and skipping the check.
211
222
  */
212
223
  export declare function standaloneWorkspace(env: StandaloneComputerEnv, keysLive?: OysterKeysLivePort, selectedComputerId?: string): OysterWorkspace;
224
+ /**
225
+ * One Computer's AGENTS.md as the principal behind `actor`: the Computer's
226
+ * grant names that person or key. A missing file reads as null.
227
+ */
228
+ export declare function standaloneHomeInstructionsFile(computer: Pick<ComputerDO, "fileRead" | "fileReplace">, computerId: string, actor: string): {
229
+ read: () => Promise<string | null>;
230
+ /** Replace what the owner last read, or with null create it only while absent. */
231
+ replace: (expectedContent: string | null, content: string) => Promise<{
232
+ path: string;
233
+ bytes: number;
234
+ kind: "replaced";
235
+ } | {
236
+ kind: "conflict";
237
+ }>;
238
+ };
213
239
  /**
214
240
  * Owner/key capability routes over the selected Computer's native
215
241
  * namespace. Each route declares the Computer requirement, so a key reaches
@@ -1,4 +1,4 @@
1
- import { attachedBackendId, hostedBackingSchema, } from "@fungi.computer/computer/backing";
1
+ import { attachedBackendId, computerSizeSchema, hostedBackingSchema, } from "@fungi.computer/computer/backing";
2
2
  import { appMethodRefusalStatus, appMethodRefusedReplySchema, } from "@fungi.computer/agar/backend";
3
3
  import * as Schema from "effect/Schema";
4
4
  import { computerPortsSchema, } from "@fungi.computer/agar/computer";
@@ -12,7 +12,7 @@ import * as z from "zod";
12
12
  import { ComputerPortConflictError, computerByteReadReplySchema, computerProcessSchema, installationProcessScope, processStartInputSchema, processStartToolInputSchema, computerCapabilities, computerToolResultSchema, readOutputSchema, } from "@fungi.computer/computer-contract";
13
13
  import { ComputerDO as NativeComputerDO, ComputerOperationConflictError, ComputerBackendUnavailableError, } from "@fungi.computer/computer";
14
14
  import { patchInputSchema, patchOutputSchema, } from "@fungi.computer/knapsack/files-patch";
15
- import { ComputerFileConflict, ComputerFileMoveError, computerExecutionRequestSchema, computerValueSchema, computerPortInputSchema, listInputSchema, listOutputSchema, readBytesInputSchema, writeInputSchema, replaceInputSchema, writeOutputSchema, mkdirOutputSchema, moveInputSchema, moveOutputSchema, computerPortsOutputSchema, computerPortOutputSchema, computerPortRemovalOutputSchema, processListOutputSchema, processKillOutputSchema, processLogsInputSchema, processLogsOutputSchema, computerOperationResultSchema, mintComputerRequestId, processIdInputSchema, } from "@fungi.computer/computer-contract";
15
+ import { ComputerFileConflict, ComputerFileMoveError, computerExecutionRequestSchema, computerValueSchema, computerPortInputSchema, listInputSchema, listOutputSchema, readBytesInputSchema, writeInputSchema, replaceInputSchema, writeOutputSchema, mkdirOutputSchema, moveInputSchema, moveOutputSchema, computerPortsOutputSchema, computerPortOutputSchema, computerPortRemovalOutputSchema, processListOutputSchema, processKillOutputSchema, processLogsInputSchema, processWaitInputSchema, processLogsOutputSchema, processWaitOutputSchema, computerOperationResultSchema, mintComputerRequestId, processIdInputSchema, } from "@fungi.computer/computer-contract";
16
16
  import { workflowGitExecutionEnvironment, workflowGitPassGrantSchema, } from "@fungi.computer/braid/runtime";
17
17
  import { checkComputerGrant, computerActionSchema, computerGrantSchema, ComputerBackingError, createFleetBacking, FleetGrantRefused, FleetLifecycle, } from "@fungi.computer/computer/fleet";
18
18
  import { AppInstanceError, selectionOf } from "../index.js";
@@ -50,6 +50,7 @@ const processStartReply = z.lazy(() => z.union([
50
50
  const bindingWrite = writeInputSchema.extend({
51
51
  expectedContent: replaceInputSchema.shape.expectedContent.optional(),
52
52
  });
53
+ const bindingMkdir = z.strictObject({ path: writeInputSchema.shape.path });
53
54
  const allActions = new Set(computerActionSchema.options);
54
55
  const terminalGrantHeader = "X-Oyster-Computer-Grant";
55
56
  const terminalGrant = computerGrantSchema.extend({
@@ -91,6 +92,8 @@ const computerTools = {
91
92
  start_process: { action: "processStart", output: computerProcessSchema },
92
93
  list_processes: { action: "processList", output: processListOutputSchema },
93
94
  kill_process: { action: "processKill", output: processKillOutputSchema },
95
+ process_logs: { action: "processLogs", output: processLogsOutputSchema },
96
+ wait_process: { action: "processWait", output: processWaitOutputSchema },
94
97
  };
95
98
  const computerTool = z.enum([
96
99
  "read",
@@ -103,6 +106,8 @@ const computerTool = z.enum([
103
106
  "start_process",
104
107
  "list_processes",
105
108
  "kill_process",
109
+ "process_logs",
110
+ "wait_process",
106
111
  ]);
107
112
  const previewRefusal = appMethodRefusedReplySchema.parse({
108
113
  kind: "refused",
@@ -111,6 +116,7 @@ const previewRefusal = appMethodRefusedReplySchema.parse({
111
116
  });
112
117
  /** The non-secret context a native command carries for its admitted Git step. */
113
118
  const workflowGitExecutionContextSchema = z.lazy(() => z.strictObject({ workflowGit: workflowGitPassGrantSchema }));
119
+ const sizeTable = "CREATE TABLE IF NOT EXISTS oyster_computer_size (singleton INTEGER PRIMARY KEY CHECK (singleton = 1), size TEXT NOT NULL CHECK (size IN ('small','default','large'))) STRICT";
114
120
  /** Durable workspace and existing backings, with fleet checks at native acceptance. */
115
121
  export class ComputerDO extends NativeComputerDO {
116
122
  previewBindings;
@@ -167,8 +173,21 @@ export class ComputerDO extends NativeComputerDO {
167
173
  });
168
174
  return this.#lifecycle;
169
175
  }
176
+ /** The size fixed at creation; a Computer never created by the fleet has none. */
177
+ computerSize() {
178
+ const sql = this.state.storage.sql;
179
+ sql.exec(sizeTable);
180
+ const row = sql
181
+ .exec("SELECT size FROM oyster_computer_size WHERE singleton=1")
182
+ .toArray()[0];
183
+ if (row === undefined)
184
+ throw new Error("Computer was created without a size");
185
+ return computerSizeSchema.parse(row.size);
186
+ }
170
187
  /** Install the fleet's creation projection before exposing its new identity. */
171
- initializeFleetBackings(backings) {
188
+ initializeFleetBackings(backings, size) {
189
+ this.state.storage.sql.exec(sizeTable);
190
+ this.state.storage.sql.exec("INSERT OR IGNORE INTO oyster_computer_size (singleton, size) VALUES (1, ?)", size);
172
191
  const owner = createFleetBacking(this.state.storage);
173
192
  owner.ensure();
174
193
  this.#backends = owner.computerCreated(this.#id(), z.array(hostedBackingSchema).parse(backings)).backends;
@@ -249,6 +268,13 @@ export class ComputerDO extends NativeComputerDO {
249
268
  await run();
250
269
  });
251
270
  }
271
+ /** An admitted fleet control stops exactly this Computer's hosted backend. */
272
+ async stopHostedComputer(authority) {
273
+ this.#accept(authority, "stop");
274
+ if (this.previewBindings.OYSTER_COMPUTER_BACKEND === "local")
275
+ return { error: "no_runtime" };
276
+ return this.#fleetLifecycle().stopHostedComputer();
277
+ }
252
278
  /** Runtime facts for the host's owner-admitted setup read. */
253
279
  runtimeSetup() {
254
280
  const backends = this.describeBackends();
@@ -505,6 +531,8 @@ export class ComputerDO extends NativeComputerDO {
505
531
  }
506
532
  case "processLogs":
507
533
  return this.processLogsAfterAcceptance(processLogsInputSchema.parse(input), accept);
534
+ case "processWait":
535
+ return this.waitProcessAfterAcceptance(processWaitInputSchema.parse(input), accept);
508
536
  case "processKill":
509
537
  return this.killProcessAfterAcceptance(processIdInputSchema.parse(input), accept);
510
538
  case "exec":
@@ -668,6 +696,24 @@ export function standaloneWorkspace(env, keysLive, selectedComputerId = env.OYST
668
696
  },
669
697
  };
670
698
  }
699
+ /**
700
+ * One Computer's AGENTS.md as the principal behind `actor`: the Computer's
701
+ * grant names that person or key. A missing file reads as null.
702
+ */
703
+ export function standaloneHomeInstructionsFile(computer, computerId, actor) {
704
+ const authority = grant(computerId, actor);
705
+ const path = "/AGENTS.md";
706
+ return {
707
+ read: async () => {
708
+ const bytes = await computer.fileRead(authority, path);
709
+ return bytes === null
710
+ ? null
711
+ : new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
712
+ },
713
+ /** Replace what the owner last read, or with null create it only while absent. */
714
+ replace: (expectedContent, content) => computer.fileReplace(authority, path, expectedContent, content),
715
+ };
716
+ }
671
717
  /**
672
718
  * Owner/key capability routes over the selected Computer's native
673
719
  * namespace. Each route declares the Computer requirement, so a key reaches
@@ -795,6 +841,11 @@ export const computerFrameMethods = {
795
841
  .parse(value),
796
842
  requiredOperations: () => ["write"],
797
843
  },
844
+ mkdir: {
845
+ decodeArgs: (args) => z.tuple([bindingMkdir]).parse(args),
846
+ decodeResult: (value) => mkdirOutputSchema.parse(value),
847
+ requiredOperations: () => ["mkdir"],
848
+ },
798
849
  move: {
799
850
  decodeArgs: (args) => z.tuple([moveInputSchema]).parse(args),
800
851
  decodeResult: (value) => z
@@ -936,6 +987,12 @@ export async function computerInvocation(env, scope, frame, method, args) {
936
987
  };
937
988
  break;
938
989
  }
990
+ case "mkdir": {
991
+ const [parsed] = z.tuple([bindingMkdir]).parse(args);
992
+ action = "mkdir";
993
+ input = { path: parsed.path, recursive: true };
994
+ break;
995
+ }
939
996
  case "move":
940
997
  action = "files.move";
941
998
  [input] = z.tuple([moveInputSchema]).parse(args);
@@ -6,7 +6,7 @@
6
6
  //
7
7
  // OYSTER_URL=https://… OYSTER_OWNER_KEY=… oyster install-apps
8
8
  // [--repositories <base URL>] [--ref <branch or tag>]
9
- // [--from <checkout directory>] [--concurrency 1-3] [--timings <file>]
9
+ // [--from <checkout directory>] [--concurrency 1-3] [--timings <file>] [--only <app>[,<app>]]
10
10
  import { execFileSync } from "node:child_process";
11
11
  import { mkdtemp, rm, writeFile } from "node:fs/promises";
12
12
  import { tmpdir } from "node:os";
@@ -19,7 +19,7 @@ import { installReleaseCommand, installReleaseUsage, } from "../install-release-
19
19
  import { defaultStarterBuildConcurrency, installStandaloneAppSet, } from "./app-set.js";
20
20
  /** The starter Apps' public source repositories. */
21
21
  const defaultRepositories = "https://github.com/fungi-computer";
22
- const usage = "Usage: oyster install-apps [--repositories <base URL>] [--ref <ref>] [--from <checkout>] [--concurrency 1-3] [--timings <file>]";
22
+ const usage = "Usage: oyster install-apps [--repositories <base URL>] [--ref <ref>] [--from <checkout>] [--concurrency 1-3] [--timings <file>] [--only <app>[,<app>]]";
23
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}
@@ -36,6 +36,7 @@ Options:
36
36
  --ref <ref> branch or tag to build (default main)
37
37
  --from <checkout> install from a Botanical checkout directory
38
38
  --concurrency 1-3 Apps to build at once
39
+ --only <app>[,<app>] install only these Apps, such as --only prints
39
40
  --timings <file> write the build timings as JSON
40
41
  -h, --help show this help
41
42
  `;
@@ -92,6 +93,7 @@ export async function installApps(args, install = installStandaloneAppSet, ui =
92
93
  from: { type: "string" },
93
94
  concurrency: { type: "string" },
94
95
  timings: { type: "string" },
96
+ only: { type: "string" },
95
97
  help: { type: "boolean", short: "h" },
96
98
  },
97
99
  strict: true,
@@ -108,8 +110,11 @@ export async function installApps(args, install = installStandaloneAppSet, ui =
108
110
  if (values.from !== undefined && values.repositories !== undefined)
109
111
  throw new Error("Choose either --from or --repositories");
110
112
  const concurrency = values.concurrency === undefined
111
- ? defaultStarterBuildConcurrency
113
+ ? defaultStarterBuildConcurrency()
112
114
  : Number(values.concurrency);
115
+ const only = values.only === undefined
116
+ ? undefined
117
+ : values.only.split(",").map((name) => name.trim());
113
118
  const scratch = await mkdtemp(join(tmpdir(), "oyster-install-apps-"));
114
119
  try {
115
120
  let source;
@@ -134,6 +139,7 @@ export async function installApps(args, install = installStandaloneAppSet, ui =
134
139
  url,
135
140
  key,
136
141
  concurrency,
142
+ only,
137
143
  // Builds run side by side, so each report is its own line, not a spinner.
138
144
  report: (message) => {
139
145
  ui.step(message);
@@ -2,7 +2,7 @@ import type { FrameBindingProps } from "../cloudflare.js";
2
2
  import type { InvocationFrame } from "../invocation.js";
3
3
  import type { OysterBindingResult } from "../workers.js";
4
4
  import * as Schema from "effect/Schema";
5
- import { type MediaServiceHost } from "@fungi.computer/darkroom/server";
5
+ import { type DailyMediaMeterPort, type MediaServiceHost } from "@fungi.computer/darkroom/server";
6
6
  import { type MediaAiPort, type MediaImagePort } from "@fungi.computer/darkroom/cloudflare";
7
7
  import { type OysterCapability } from "../host.js";
8
8
  import type { FileSource } from "../files.js";
@@ -12,8 +12,13 @@ export type OysterMediaEnv = Readonly<{
12
12
  AI: MediaAiPort;
13
13
  /** This Worker's own origin; a loopback origin has no Cloudflare account. */
14
14
  OYSTER_ORIGIN?: string | undefined;
15
- /** Darkroom's durable operation namespace. */
16
- MEDIA_OPERATION: MediaServiceHost["operations"];
15
+ /** Darkroom's durable operation namespace; the named daily-meter object lives here too. */
16
+ MEDIA_OPERATION: Readonly<{
17
+ getByName(name: string): ReturnType<MediaServiceHost["operations"]["getByName"]> & Partial<DailyMediaMeterPort>;
18
+ }>;
19
+ /** Hard stop on one UTC day's media spend, in US dollars (for example `100`).
20
+ * Unset leaves media unmetered. A set but invalid value refuses all media. */
21
+ OYSTER_DAILY_MEDIA_LIMIT_USD?: string | undefined;
17
22
  /** Native image decoding and bounded reference fitting. */
18
23
  IMAGES?: MediaImagePort;
19
24
  /** The AI Gateway third-party models (GPT Image 2, Seedance, Veo) route
@@ -55,7 +60,7 @@ export declare const mediaFrameMethods: {
55
60
  requestId: string;
56
61
  libraryPath: string;
57
62
  settings: {
58
- model: "bytedance/seedance-2.0" | "google/veo-3.1" | "bytedance/seedance-2.0-fast" | "bytedance/seedance-2.0-mini" | "google/veo-3.1-fast" | "minimax/h3-max";
63
+ model: "bytedance/seedance-2.0" | "google/veo-3.1" | "bytedance/seedance-2.5" | "bytedance/seedance-2.0-fast" | "bytedance/seedance-2.0-mini" | "google/veo-3.1-fast" | "minimax/h3-max";
59
64
  prompt: string;
60
65
  resolution?: "480p" | "720p" | "768p" | "1080p" | "4k" | undefined;
61
66
  aspectRatio?: "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "9:21" | undefined;
@@ -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. */
@@ -69,12 +69,14 @@ export declare abstract class StandaloneRegistry extends OysterRegistry implemen
69
69
  computerFleet(memberId: string, request: StandaloneFleetRequest): Promise<Readonly<{
70
70
  computerId: string;
71
71
  name: string;
72
+ size: import("@fungi.computer/computer").ComputerSize;
72
73
  createdAt: number;
73
74
  updatedAt: number;
74
75
  }> | {
75
76
  readonly computers: Readonly<{
76
77
  computerId: string;
77
78
  name: string;
79
+ size: import("@fungi.computer/computer").ComputerSize;
78
80
  createdAt: number;
79
81
  updatedAt: number;
80
82
  }>[];
@@ -112,9 +114,13 @@ export declare abstract class StandaloneRegistry extends OysterRegistry implemen
112
114
  state: "running" | "sleeping";
113
115
  position?: never | undefined;
114
116
  } & Disposable) | ({
115
- state: "running";
117
+ state: "sleeping";
118
+ } & Disposable) | ({
119
+ error: "busy";
116
120
  } & Disposable) | ({
117
121
  error: "no_runtime";
122
+ } & Disposable) | ({
123
+ state: "running";
118
124
  } & Disposable) | {
119
125
  error: string;
120
126
  computers?: undefined;
@@ -128,6 +134,7 @@ export declare abstract class StandaloneRegistry extends OysterRegistry implemen
128
134
  } | Readonly<{
129
135
  computerId: string;
130
136
  name: string;
137
+ size: import("@fungi.computer/computer").ComputerSize;
131
138
  createdAt: number;
132
139
  updatedAt: number;
133
140
  }>)[];
@@ -107,7 +107,7 @@ export class StandaloneRegistry extends OysterRegistry {
107
107
  const backings = this.#computers.readBacking(created.computerId);
108
108
  if (backings === null)
109
109
  throw new Error("Computer backing is missing");
110
- await this.#env.COMPUTER.getByName(created.computerId).initializeFleetBackings(backings);
110
+ await this.#env.COMPUTER.getByName(created.computerId).initializeFleetBackings(backings, created.size);
111
111
  return created;
112
112
  }
113
113
  case "list":
@@ -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;