@fungi.computer/oyster 0.1.0 → 0.3.0

package/dist/standalone/computer.js

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
+import { attachedBackendId, hostedBackingSchema, } from "@fungi.computer/computer/backing";
 import { appMethodRefusalStatus, appMethodRefusedReplySchema, } from "@fungi.computer/agar/backend";
-import { workflowGitPassResultSchema, } from "@fungi.computer/agar/computer-contracts";
 import * as Schema from "effect/Schema";
 import { computerPortsSchema, } from "@fungi.computer/agar/computer";
 import { verifyRelease } from "../host.js";
@@ -9,16 +9,19 @@ import { createStandalonePreview, previewOrigins, previewSelectorSchema, Preview
 import { standaloneTenancy } from "./tenancy.js";
 import { Base64 } from "effect/encoding";
 import * as z from "zod";
-import { ComputerPortConflictError, computerByteReadReplySchema, computerProcessSchema, installationProcessScope, processStartInputSchema, processStartToolInputSchema, computerCapabilities, computerToolResultSchema, readOutputSchema, } from "@fungi.computer/computer/operations";
-import { ComputerDO as NativeComputerDO, ComputerFileConflict, ComputerOperationConflictError, computerExecutionRequestSchema, computerValueSchema, computerPortInputSchema, listInputSchema, listOutputSchema, readBytesInputSchema, writeInputSchema, replaceInputSchema, writeOutputSchema, mkdirOutputSchema, computerPortsOutputSchema, computerPortOutputSchema, computerPortRemovalOutputSchema, processListOutputSchema, processKillOutputSchema, computerOperationResultSchema, mintComputerRequestId, processIdInputSchema, } from "@fungi.computer/computer";
-import { checkComputerGrant, computerActionSchema, computerGrantSchema, createFleetBacking, FleetGrantRefused, } from "@fungi.computer/computer/fleet";
+import { ComputerPortConflictError, computerByteReadReplySchema, computerProcessSchema, installationProcessScope, processStartInputSchema, processStartToolInputSchema, computerCapabilities, computerToolResultSchema, readOutputSchema, } from "@fungi.computer/computer-contract";
+import { ComputerDO as NativeComputerDO, ComputerOperationConflictError, } from "@fungi.computer/computer";
+import { ComputerFileConflict, computerExecutionRequestSchema, computerValueSchema, computerPortInputSchema, listInputSchema, listOutputSchema, readBytesInputSchema, writeInputSchema, replaceInputSchema, writeOutputSchema, mkdirOutputSchema, computerPortsOutputSchema, computerPortOutputSchema, computerPortRemovalOutputSchema, processListOutputSchema, processKillOutputSchema, computerOperationResultSchema, mintComputerRequestId, processIdInputSchema, } from "@fungi.computer/computer-contract";
+import { workflowGitExecutionEnvironment, workflowGitPassGrantSchema, } from "@fungi.computer/braid/runtime";
+import { checkComputerGrant, computerActionSchema, computerGrantSchema, createFleetBacking, FleetGrantRefused, FleetLifecycle, } from "@fungi.computer/computer/fleet";
 import { AppInstanceError, selectionOf } from "../index.js";
 import {} from "../cloudflare.js";
 import { computerSlots } from "../computer.js";
 import { oysterPrincipalId, oysterPrincipalIsOwner, } from "../host.js";
 import { keyAllowsComputerUse } from "../keys.js";
-import { oysterAppBuildTimeoutMs } from "../app-builds.js";
-const missingFile = z.object({ code: z.literal("ENOENT") });
+import { oysterAppBuildTimeoutMs, } from "../app-builds.js";
+import { workflowGitStepGrant, } from "./workflow-binding.js";
+const missingFile = z.lazy(() => z.object({ code: z.literal("ENOENT") }));
 const workspaceId = computerGrantSchema.shape.computerId;
 const command = computerExecutionRequestSchema({ maximumTimeMs: 45_000 }).omit({
     requestId: true,
@@ -39,10 +42,10 @@ const processStart = processStartInputSchema.omit({
 const processStartHttpBody = processStartInputSchema.omit({
     requestScope: true,
 });
-const processStartReply = z.union([
+const processStartReply = z.lazy(() => z.union([
     computerProcessSchema,
     z.strictObject({ error: z.literal("conflict") }),
-]);
+]));
 const bindingWrite = writeInputSchema.extend({
     expectedContent: replaceInputSchema.shape.expectedContent.optional(),
 });
@@ -109,11 +112,14 @@ const previewRefusal = appMethodRefusedReplySchema.parse({
     code: "forbidden",
     message: "Port previews belong to the current owner of an enabled installation.",
 });
+/** The non-secret context a native command carries for its admitted Git step. */
+const workflowGitExecutionContextSchema = z.lazy(() => z.strictObject({ workflowGit: workflowGitPassGrantSchema }));
 /** Durable workspace and existing backings, with fleet checks at native acceptance. */
 export class ComputerDO extends NativeComputerDO {
     previewBindings;
     #backends;
     #preview;
+    #lifecycle;
     constructor(state, previewBindings) {
         // The Computer's HTTP(S) egress goes only through the gateway the
         // standalone Worker exports beside this object.
@@ -123,6 +129,50 @@ export class ComputerDO extends NativeComputerDO {
         });
         this.previewBindings = previewBindings;
     }
+    #fleetLifecycle() {
+        if (this.#lifecycle !== undefined)
+            return this.#lifecycle;
+        this.#lifecycle = new FleetLifecycle({
+            storage: this.state.storage,
+            alarm: this.state,
+            computerId: this.#id(),
+            runtimeWatchMs: undefined,
+            backend: {
+                state: this.state,
+                onBoxVmHost: (hostId) => this.onBoxVmHost(hostId),
+                hostedContainerHost: (backing) => this.hostedContainerHost(backing),
+                readyWorkspace: () => this.readyWorkspace(),
+                workspace: () => this.workspace(),
+                syncRecycledWorkspace: async (backing) => {
+                    const workspace = await this.readyWorkspace();
+                    const id = attachedBackendId(backing);
+                    await workspace.push(id);
+                    await workspace.pull(id);
+                },
+                attachedBackends: () => this.attachedBackends(),
+                describeBackends: () => this.describeBackends(),
+                requireHostedRoute: () => this.requireHostedRoute(),
+                containerRunning: (backing) => this.containerRunning(backing),
+                // Standalone boots use the native host directly, not Hub's admission queue.
+                vmQueuePosition: () => Promise.resolve(null),
+            },
+        });
+        return this.#lifecycle;
+    }
+    /** Install the fleet's creation projection before exposing its new identity. */
+    initializeFleetBackings(backings) {
+        const owner = createFleetBacking(this.state.storage);
+        owner.ensure();
+        this.#backends = owner.computerCreated(this.#id(), z.array(hostedBackingSchema).parse(backings)).backends;
+    }
+    /** An admitted fleet control starts exactly this Computer's hosted backend. */
+    async startHostedComputer(authority) {
+        this.#accept(authority, "start");
+        return this.#fleetLifecycle().startHostedComputer(async (_backing, run) => {
+            this.#accept(authority, "start");
+            await run();
+        });
+    }
     #previewGrant(ownerId) {
         return {
             computerId: this.#id(),
@@ -173,6 +223,12 @@ export class ComputerDO extends NativeComputerDO {
         });
         return this.#preview;
     }
+    /** A read-only preflight over the maintained hosted-route selector. */
+    buildBackend() {
+        return this.hostedRoute() === undefined
+            ? { kind: "no_backend" }
+            : { kind: "hosted" };
+    }
     /**
      * Run one App build job's fixed command, under the build budget. The
      * registry that minted the job re-admits it for this Computer first.
@@ -186,7 +242,7 @@ export class ComputerDO extends NativeComputerDO {
             cwd: "/workspace",
             timeoutMs: input.timeoutMs,
             requestId: mintComputerRequestId(),
-        }, () => undefined, "bash", { maximumTimeMs: oysterAppBuildTimeoutMs });
+        }, () => undefined, "hosted", { maximumTimeMs: oysterAppBuildTimeoutMs });
         const output = z
             .object({ exitCode: z.number().nullable(), stderr: z.string() })
             .safeParse(result.output);
@@ -231,6 +287,36 @@ export class ComputerDO extends NativeComputerDO {
     #id() {
         return workspaceId.parse(this.state.id.name);
     }
+    /**
+     * The host side of native execution (Computer ABI 0edb0e4a): the grant's
+     * library run owner issues one credential for the invocation and the
+     * Computer hands it only to that command's Git environment.
+     */
+    executionHooks() {
+        const issuer = (context) => {
+            const grant = workflowGitExecutionContextSchema.parse(context).workflowGit;
+            return {
+                grant,
+                runs: this.previewBindings.WORKFLOW_RUNS.getByName(grant.teamId),
+            };
+        };
+        return {
+            async open(invocation, context) {
+                const { grant, runs } = issuer(context);
+                return {
+                    env: workflowGitExecutionEnvironment(await runs.issueWorkflowGit(invocation.id, grant)),
+                };
+            },
+            async renew(invocation, context) {
+                const { grant, runs } = issuer(context);
+                await runs.renewWorkflowGit(invocation.id, grant);
+            },
+            async close(invocation, context) {
+                const { grant, runs } = issuer(context);
+                await runs.closeWorkflowGit(invocation.id, grant);
+            },
+        };
+    }
     attachedBackends() {
         if (this.#backends !== undefined)
             return this.#backends;
@@ -268,7 +354,12 @@ export class ComputerDO extends NativeComputerDO {
         return output.parse(await this.callAfterAcceptance(tool, input, accept));
     }
     /** JSON operations keep the Computer's maintained parsers and execution engine. */
-    async value(authority, action, input) {
+    async value(authority, action, input, executionContext) {
+        // Only an exact public grant rides along, and only on a native command.
+        if (executionContext !== undefined &&
+            ((action !== "exec" && action !== "processStart") ||
+                !workflowGitExecutionContextSchema.safeParse(executionContext).success))
+            throw new AppInstanceError("binding_unavailable");
         const accept = () => {
             this.#accept(authority, action);
         };
@@ -283,7 +374,7 @@ export class ComputerDO extends NativeComputerDO {
                 return this.listProcessesAfterAcceptance(accept);
             case "processStart":
                 try {
-                    return await this.startProcessAfterAcceptance(input, accept);
+                    return await this.startProcessAfterAcceptance(input, accept, executionContext);
                 }
                 catch (cause) {
                     if (cause instanceof ComputerOperationConflictError ||
@@ -294,7 +385,7 @@ export class ComputerDO extends NativeComputerDO {
             case "processKill":
                 return this.killProcessAfterAcceptance(processIdInputSchema.parse(input), accept);
             case "exec":
-                return this.executeOperationAfterAcceptance({ ...command.parse(input), requestId: mintComputerRequestId() }, accept, "bash", { maximumTimeMs: 45_000 });
+                return this.executeOperationAfterAcceptance({ ...command.parse(input), requestId: mintComputerRequestId() }, accept, "bash", { maximumTimeMs: 45_000 }, undefined, executionContext);
             case "files.list":
                 return listOutputSchema.parse(await this.callAfterAcceptance("list", input, accept));
             case "files.readBytes": {
@@ -406,8 +497,8 @@ export class ComputerDO extends NativeComputerDO {
  * omit it, since a team-key principal then simply never reaches the
  * Computer, rather than reading `env.KEYS` directly and skipping the check.
  */
-export function standaloneWorkspace(env, keysLive) {
-    const computerId = workspaceId.parse(env.OYSTER_COMPUTER_ID);
+export function standaloneWorkspace(env, keysLive, selectedComputerId = env.OYSTER_COMPUTER_ID) {
+    const computerId = workspaceId.parse(selectedComputerId);
     const computer = () => env.COMPUTER.getByName(computerId);
     const authority = () => grant(computerId, "oyster-workspace");
     return {
@@ -524,11 +615,6 @@ export function standaloneComputerCapabilities(env, workspace, keysLive) {
 /** Closed COMPUTER binding codecs, joined into the standalone Instance. */
 export const computerFrameMethods = {
     COMPUTER: {
-        workflowGitPass: {
-            decodeArgs: (args) => z.tuple([empty]).parse(args),
-            decodeResult: (value) => workflowGitPassResultSchema.parse(value),
-            requiredOperations: () => ["workflowGitPass"],
-        },
         list: {
             decodeArgs: (args) => z.tuple([listInputSchema]).parse(args),
             decodeResult: (value) => listOutputSchema.parse(value),
@@ -592,13 +678,13 @@ export const computerFrameMethods = {
 /** Owner-only preview tickets carry the verified frame's Installation selection. */
 async function computerPreviewInvocation(env, frame, args) {
     const subject = frame.facts.subject;
-    const computerId = workspaceId.parse(env.OYSTER_COMPUTER_ID);
     const owner = frame.facts.selection.owner;
     if (subject.kind !== "call" ||
         subject.context.actor.kind !== "member" ||
         subject.context.role !== "owner" ||
         owner.kind !== "installation")
         throw new AppInstanceError("revoked");
+    const computerId = workspaceId.parse(subject.context.computerId);
     // The admitted owner's member ID; the Computer owner proves it is still
     // the live canonical owner before issuing any ticket.
     const ownerId = subject.context.actor.memberId;
@@ -623,12 +709,27 @@ async function computerPreviewInvocation(env, frame, args) {
         throw new AppInstanceError("revoked");
     return preview;
 }
-/** Dispatch one admitted COMPUTER operation under its captured frame. */
-export function computerInvocation(env, frame, method, args) {
+/** Re-admit the Computer captured by this invocation, never the current UI selection. */
+async function frameComputerId(env, scope, frame) {
+    frame.signal.throwIfAborted();
+    const subject = frame.facts.subject;
+    if (subject.kind !== "call" || subject.context.computerId === null)
+        throw new AppInstanceError("revoked");
+    const computerId = workspaceId.parse(subject.context.computerId);
+    if (!(await env.REGISTRY.getByName(scope.durableName("registry")).ownsComputer(computerId)))
+        throw new AppInstanceError("revoked");
     frame.signal.throwIfAborted();
+    return computerId;
+}
+/** Media and Computer bindings capture the same inventory-admitted workspace. */
+export async function standaloneFrameWorkspace(env, scope, frame) {
+    return standaloneWorkspace(env, undefined, await frameComputerId(env, scope, frame));
+}
+/** Dispatch one admitted COMPUTER operation under its captured frame. */
+export async function computerInvocation(env, scope, frame, method, args) {
+    const computerId = await frameComputerId(env, scope, frame);
     const subject = frame.facts.subject;
-    const computerId = workspaceId.parse(env.OYSTER_COMPUTER_ID);
-    if (subject.kind !== "call" || subject.context.computerId !== computerId)
+    if (subject.kind !== "call")
         throw new AppInstanceError("revoked");
     const actor = subject.context.actor;
     if (method === "preview")
@@ -703,6 +804,10 @@ export function computerInvocation(env, frame, method, args) {
         default:
             throw new AppInstanceError("revoked");
     }
+    // A Workflow Git step's native commands carry only its public grant.
+    const grant = action === "exec" || action === "processStart"
+        ? await workflowGitStepGrant(env, env.REGISTRY.getByName(scope.durableName("registry")), frame)
+        : null;
     const native = env.COMPUTER.getByName(computerId);
     frame.signal.throwIfAborted();
     return native.value({
@@ -710,5 +815,7 @@ export function computerInvocation(env, frame, method, args) {
         actions: new Set([action]),
         expiresAt: Math.min(frame.facts.deadlineAt, Date.now() + 60_000),
         provenance: { actor: `${actor.kind}:${actorId}` },
-    }, action, input);
+    }, action, input, grant === null
+        ? undefined
+        : computerValueSchema.parse(JSON.parse(JSON.stringify({ workflowGit: grant }))));
 }

package/dist/standalone/install-apps-cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // `oyster install-apps`: seed, build on the Oyster's own Computer, and install
-// the starter Apps (Tourtois, Bonsai, Shed, Inkcap, Trellis, Prints and
-// Grove). Each App comes from its own public repository by default, or from a
-// Botanical checkout with `--from <directory>`.
+// the seven starter Apps (Tourtois, Bonsai, Shed, Inkcap, Trellis, Prints,
+// and Grove). Each comes from its own public repository by default,
+// or from a Botanical checkout with `--from <directory>`.
 //
 //   OYSTER_URL=https://… OYSTER_OWNER_KEY=… oyster install-apps
 //     [--repositories <base URL>] [--ref <branch or tag>]
@@ -13,10 +13,39 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import process from "node:process";
 import { parseArgs } from "node:util";
+import { installReleaseCommand, installReleaseUsage, } from "../install-release-cli.js";
 import { defaultStarterBuildConcurrency, installStandaloneAppSet, } from "./app-set.js";
 /** The starter Apps' public source repositories. */
 const defaultRepositories = "https://github.com/fungi-computer";
 const usage = "Usage: oyster install-apps [--repositories <base URL>] [--ref <ref>] [--from <checkout>] [--concurrency 1-3] [--timings <file>]";
+const urlSource = "OYSTER_URL is the address of your deployed Oyster Worker, such as https://oyster.<your-subdomain>.workers.dev (http://127.0.0.1:8787 for a local one). You set it when you deploy.";
+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`.";
+const helpText = `${usage}
+
+Builds the seven starter Apps on your Oyster's own Computer and installs them.
+Starter builds need a deployed Oyster host; this command does not create one.
+Deploy first (see the Oyster README), then set:
+
+  ${urlSource}
+  ${keySource}
+
+Options:
+  --repositories <base URL>  fetch each App from <base URL> instead of the public repositories
+  --ref <ref>                branch or tag to build (default main)
+  --from <checkout>          install from a Botanical checkout directory
+  --concurrency 1-3          Apps to build at once
+  --timings <file>           write the build timings as JSON
+  -h, --help                 show this help
+`;
+function missingVariableMessage(url, key) {
+    const lines = [];
+    if (!url)
+        lines.push(`OYSTER_URL is not set. ${urlSource}`);
+    if (!key)
+        lines.push(`OYSTER_OWNER_KEY is not set. ${keySource}`);
+    lines.push("Run oyster install-apps --help for details.");
+    return lines.join("\n");
+}
 function seconds(milliseconds) {
     return `${(milliseconds / 1000).toFixed(1)}s`;
 }
@@ -56,13 +85,18 @@ async function installApps(args) {
             from: { type: "string" },
             concurrency: { type: "string" },
             timings: { type: "string" },
+            help: { type: "boolean", short: "h" },
         },
         strict: true,
     });
+    if (values.help === true) {
+        process.stdout.write(helpText);
+        return;
+    }
     const url = process.env.OYSTER_URL;
     const key = process.env.OYSTER_OWNER_KEY;
     if (!url || !key)
-        throw new Error("Set OYSTER_URL and OYSTER_OWNER_KEY");
+        throw new Error(missingVariableMessage(url, key));
     if (values.from !== undefined && values.repositories !== undefined)
         throw new Error("Choose either --from or --repositories");
     const concurrency = values.concurrency === undefined
@@ -115,12 +149,15 @@ async function installApps(args) {
     }
 }
 const [command, ...rest] = process.argv.slice(2);
-if (command !== "install-apps") {
+if (command === "--help" || command === "-h") {
+    process.stdout.write(usage + "\n" + installReleaseUsage + "\n");
+}
+else if (command !== "install-apps" && command !== "install") {
     process.stderr.write(`${usage}\n`);
     process.exitCode = 2;
 }
 else
-    await installApps(rest).catch((cause) => {
+    await (command === "install" ? installReleaseCommand(rest) : installApps(rest)).catch((cause) => {
         process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`);
         process.exitCode = 1;
     });

package/dist/standalone/instance.d.ts

@@ -4,8 +4,8 @@ import { type StandaloneAgentsEnv } from "./agents.js";
 import { type StandaloneComputerEnv } from "./computer.js";
 import { type OysterMediaEnv } from "./media.js";
 import { type AppSourceBindingEnv } from "./app-source.js";
-import { type WorkflowBindingEnv, type WorkflowEventEnv, type WorkflowGitPassEnv } from "./workflow-binding.js";
-export type StandaloneInstanceEnv = OysterGitWorkerEnv & WorkflowBindingEnv & WorkflowEventEnv & WorkflowGitPassEnv & StandaloneComputerEnv & StandaloneAgentsEnv & OysterMediaEnv & AppSourceBindingEnv;
+import { type WorkflowBindingEnv, type WorkflowEventEnv } from "./workflow-binding.js";
+export type StandaloneInstanceEnv = OysterGitWorkerEnv & WorkflowBindingEnv & WorkflowEventEnv & StandaloneComputerEnv & StandaloneAgentsEnv & OysterMediaEnv & AppSourceBindingEnv;
 /** Git and Events plus the declared Computer, Media, Workflow, Agent and App
  * source bindings. */
 export declare const standaloneBindings: OysterBindingTable<StandaloneInstanceEnv>;

package/dist/standalone/instance.js

@@ -2,10 +2,10 @@ import { AppInstanceError } from "../index.js";
 import { oysterBindingEntrypoint, } from "../workers.js";
 import { OysterGitInstance, OysterWebhooks, eventsBindingFor, gitBindings, } from "../workers-git.js";
 import { agentFrameMethods, dispatchAgentBinding, } from "./agents.js";
-import { computerFrameMethods, computerInvocation, standaloneWorkspace, } from "./computer.js";
+import { computerFrameMethods, computerInvocation, standaloneFrameWorkspace, } from "./computer.js";
 import { dispatchMediaBinding, mediaFrameMethods, } from "./media.js";
 import { appSourceFrameMethods, dispatchAppSourceBinding, } from "./app-source.js";
-import { workflowFrameMethods, dispatchWorkflowBinding, deliverWorkflowEvent, openWorkflowGitPass, workflowEventRecipients, } from "./workflow-binding.js";
+import { workflowFrameMethods, dispatchWorkflowBinding, deliverWorkflowEvent, workflowEventRecipients, } from "./workflow-binding.js";
 import { appsFrameMethods, dispatchAppsBuildsBinding, } from "./app-builds-binding.js";
 /** Git and Events plus the declared Computer, Media, Workflow, Agent and App
  * source bindings. */
@@ -21,19 +21,16 @@ export const standaloneBindings = {
     },
     COMPUTER: {
         methods: computerFrameMethods.COMPUTER,
-        async dispatch(context, frame, _props, method, args) {
-            if (method !== "workflowGitPass")
-                return computerInvocation(context.env, frame, method, args);
-            // A published Workflow Git step's pass, minted by the library that runs it.
-            const host = await context.backgroundHost();
-            if (host === null)
-                throw new AppInstanceError("revoked");
-            return openWorkflowGitPass(context.env, host.installations, frame, args);
+        dispatch(context, frame, _props, method, args) {
+            return computerInvocation(context.env, context.scope(), frame, method, args);
         },
     },
     MEDIA: {
         methods: mediaFrameMethods.MEDIA,
-        dispatch: (context, frame, props, method, args) => dispatchMediaBinding(context.env, frame, props, method, args, standaloneWorkspace(context.env)),
+        async dispatch(context, frame, props, method, args) {
+            const workspace = await standaloneFrameWorkspace(context.env, context.scope(), frame);
+            return dispatchMediaBinding(context.env, frame, props, method, args, workspace);
+        },
     },
     WORKFLOWS: {
         methods: workflowFrameMethods.WORKFLOWS,