@fungi.computer/oyster 0.5.0 → 0.7.0

package/dist/release.d.ts

@@ -60,6 +60,19 @@ export type VerifiedRelease = Readonly<{
 export declare function sha256(bytes: Uint8Array): Promise<string>;
 /** Read one artifact and refuse it unless its bytes match `digest`. */
 export declare function readVerified(store: ArtifactStore, artifactRef: ArtifactRef, digest: Sha256Digest): Promise<Uint8Array>;
+/**
+ * Copies of verified artifacts near the reader, keyed by content digest. An
+ * entry holds only bytes that already matched its digest, so a hit is served
+ * without another store read or hash.
+ */
+export type VerifiedObjectCache = Readonly<{
+    /** The cached bytes for `digest`, or null on a miss. */
+    match: (digest: Sha256Digest) => Promise<ReadableStream<Uint8Array> | null>;
+    /** Keep verified bytes; an unstored write only costs the next reader a store read. */
+    put: (digest: Sha256Digest, bytes: Uint8Array) => Promise<"stored" | "unstored">;
+}>;
+/** {@link readVerified} through an optional digest-keyed cache it fills on a miss. */
+export declare function readCachedVerified(store: ArtifactStore, cache: VerifiedObjectCache | undefined, artifactRef: ArtifactRef, digest: Sha256Digest): Promise<ReadableStream<Uint8Array> | Uint8Array<ArrayBuffer>>;
 /** Decode an untrusted Release record, as an install request carries it. */
 export declare function parseRelease(value: unknown): Release;
 /**

package/dist/release.js

@@ -36,6 +36,16 @@ export async function readVerified(store, artifactRef, digest) {
         throw new ReleaseError("digest_mismatch", `Digest mismatch ${artifactRef}`);
     return bytes;
 }
+/** {@link readVerified} through an optional digest-keyed cache it fills on a miss. */
+export async function readCachedVerified(store, cache, artifactRef, digest) {
+    const hit = await cache?.match(digest);
+    if (hit !== undefined && hit !== null)
+        return hit;
+    const bytes = await readVerified(store, artifactRef, digest);
+    await cache?.put(digest, bytes);
+    // A response body owns a plain ArrayBuffer, whatever view the store returned.
+    return new Uint8Array(bytes);
+}
 const decodeText = (bytes) => new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes);
 /** Decode an untrusted Release record, as an install request carries it. */
 export function parseRelease(value) {

package/dist/request-origin.d.ts

@@ -0,0 +1,4 @@
+/** Require the request's own Origin and refuse cross-site provenance. */
+export declare function sameOriginRequest(request: Request): boolean;
+/** Channel reads allow absent Origin but never conflicting or cross-site provenance. */
+export declare function sameOriginReadRequest(request: Request): boolean;

package/dist/request-origin.js

@@ -0,0 +1,10 @@
+/** Require the request's own Origin and refuse cross-site provenance. */
+export function sameOriginRequest(request) {
+    return request.headers.has("origin") && sameOriginReadRequest(request);
+}
+/** Channel reads allow absent Origin but never conflicting or cross-site provenance. */
+export function sameOriginReadRequest(request) {
+    const origin = request.headers.get("origin");
+    return (request.headers.get("sec-fetch-site") !== "cross-site" &&
+        (origin === null || origin === new URL(request.url).origin));
+}

package/dist/standalone/agent-archive-owner.d.ts

@@ -0,0 +1,42 @@
+import type { CloudflareShiitake } from "@fungi.computer/shiitake/cloudflare";
+import { type ArchiveRefusalReason } from "@fungi.computer/shiitake/agent-control";
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+export { agentArchiveProjection } from "../agent-archive-projection.js";
+export type AgentArchiveTransitionResult = Readonly<{
+    archived: boolean;
+    revision: number;
+}> | Readonly<{
+    error: ArchiveRefusalReason;
+    message?: string;
+    archived?: boolean;
+    revision?: number;
+}>;
+/** The one owner-local archive transition, admission fence and repair cursor.
+ * The host lends only its existing transport and revisioned directory projection.
+ */
+export declare function agentArchiveOwner(deps: Readonly<{
+    storage: Pick<WatchdogSqliteOwner, "sql" | "transactionSync">;
+    agentId: () => string | undefined;
+    agent: () => Promise<CloudflareShiitake>;
+    /** Enable reconciliation where the host mounts Almanac and Loop with command grants. */
+    scheduledExtensions?: boolean;
+    refreshOutstanding: (agentId: string) => Promise<void>;
+    record: (agentId: string, archived: boolean, revision: number) => Promise<boolean>;
+    wake: () => Promise<void>;
+    waitUntil: (task: Promise<unknown>) => void;
+}>): {
+    read: () => {
+        archived: boolean;
+        revision: number;
+        pending: boolean;
+    };
+    assertOpen(): void;
+    work: {
+        pending: () => {
+            due: boolean;
+            nextWakeAt: number | null;
+        };
+        run: () => Promise<void>;
+    };
+    setArchived: (archived: boolean) => Promise<AgentArchiveTransitionResult>;
+};

package/dist/standalone/agent-archive-owner.js

@@ -0,0 +1,116 @@
+import { ShiitakeError } from "@fungi.computer/shiitake";
+import { AgentArchiveRefused, } from "@fungi.computer/shiitake/agent-control";
+import { agentArchive } from "./agent-archive.js";
+import { reconcileArchiveSchedules } from "./agent-archive-schedules.js";
+export { agentArchiveProjection } from "../agent-archive-projection.js";
+/** The one owner-local archive transition, admission fence and repair cursor.
+ * The host lends only its existing transport and revisioned directory projection.
+ */
+export function agentArchiveOwner(deps) {
+    const archive = agentArchive(deps.storage.sql);
+    let retryAfter = 0;
+    let tail = Promise.resolve();
+    const serialize = (action) => {
+        const run = tail.then(action);
+        tail = run.then(() => undefined, () => undefined);
+        return run;
+    };
+    const repairOnce = async () => {
+        const state = archive.read();
+        if (!state.pending)
+            return;
+        try {
+            const agentId = deps.agentId();
+            if (agentId === undefined)
+                throw new Error("Agent archive scope is unavailable");
+            if (deps.scheduledExtensions)
+                await reconcileArchiveSchedules(await deps.agent(), archive, state.archived);
+            if (!(await deps.record(agentId, state.archived, state.revision)))
+                throw new Error("Agent archive directory is unavailable");
+            deps.storage.transactionSync(() => {
+                archive.ack(state.revision);
+            });
+            retryAfter = 0;
+        }
+        catch (cause) {
+            retryAfter = Date.now() + 30_000;
+            throw cause;
+        }
+    };
+    return {
+        read: archive.read,
+        assertOpen() {
+            if (archive.read().archived)
+                throw new ShiitakeError("contract", "archived", "Agent is archived");
+        },
+        work: {
+            pending: () => {
+                const state = archive.read();
+                return {
+                    due: state.pending && Date.now() >= retryAfter,
+                    nextWakeAt: state.pending ? Math.max(Date.now(), retryAfter) : null,
+                };
+            },
+            run: () => serialize(repairOnce),
+        },
+        setArchived: (archived) => serialize(async () => {
+            const agent = await deps.agent();
+            const agentId = deps.agentId();
+            if (agentId === undefined)
+                return { error: "unreadable" };
+            if (archived) {
+                try {
+                    await deps.refreshOutstanding(agentId);
+                }
+                catch (cause) {
+                    console.error("agent archive settlement refresh failed", {
+                        kind: cause instanceof Error ? cause.name : "Unknown",
+                    });
+                    return { error: "unreadable" };
+                }
+            }
+            let changed;
+            try {
+                changed = deps.storage.transactionSync(() => {
+                    const before = archive.read();
+                    if (archived && !before.archived) {
+                        const busy = agent.busySync();
+                        if (busy !== undefined)
+                            throw new AgentArchiveRefused(busy.kind === "session" ? "running" : "pending", busy.kind === "session"
+                                ? `Command ${busy.commandId} is busy in Session ${busy.sessionId}`
+                                : `Delegated command ${busy.commandId} is unsettled for Agent ${busy.agentId}`);
+                    }
+                    return archive.transition(archived);
+                });
+            }
+            catch (error) {
+                if (error instanceof AgentArchiveRefused)
+                    return { error: error.reason, message: error.message };
+                console.error("agent archive busy read failed", {
+                    kind: error instanceof Error ? error.name : "Unknown",
+                });
+                return { error: "unreadable" };
+            }
+            if (changed.pending) {
+                try {
+                    await repairOnce();
+                }
+                catch (error) {
+                    deps.waitUntil(deps.wake().catch((cause) => {
+                        console.error("agent archive repair wake failed", cause);
+                    }));
+                    console.error("agent archive projection pending", {
+                        kind: error instanceof Error ? error.name : "Unknown",
+                    });
+                    return {
+                        error: "unreadable",
+                        message: "Archive state changed; directory or schedule repair is pending",
+                        archived: changed.archived,
+                        revision: changed.revision,
+                    };
+                }
+            }
+            return { archived: changed.archived, revision: changed.revision };
+        }),
+    };
+}

package/dist/standalone/agent-archive-schedules.d.ts

@@ -0,0 +1,6 @@
+import type { ShiitakeAgent } from "@fungi.computer/shiitake/client";
+import type { agentArchive } from "./agent-archive.js";
+/** Reconcile extension-owned timers via their ordinary commands, not private tables.
+ * Durable pause markers are written before the commands, so restart can retry.
+ */
+export declare function reconcileArchiveSchedules(owner: ShiitakeAgent, archive: ReturnType<typeof agentArchive>, archived: boolean): Promise<void>;

package/dist/standalone/agent-archive-schedules.js

@@ -0,0 +1,76 @@
+import { almanacContract, Schedule, } from "@fungi.computer/shiitake-extensions/almanac";
+import { loopContract, LoopProjection, } from "@fungi.computer/shiitake-extensions/loop";
+import * as Schema from "effect/Schema";
+const schedules = Schema.Array(Schedule);
+const schedule = Schema.NullOr(Schedule);
+const loop = Schema.NullOr(LoopProjection);
+/** Reconcile extension-owned timers via their ordinary commands, not private tables.
+ * Durable pause markers are written before the commands, so restart can retry.
+ */
+export async function reconcileArchiveSchedules(owner, archive, archived) {
+    if (archived) {
+        let after;
+        do {
+            const request = after === undefined ? { limit: 64 } : { after, limit: 64 };
+            const listed = Schema.decodeUnknownSync(schedules)(await owner.extensions.call(almanacContract.id, "list", request));
+            for (const item of listed) {
+                if (item.state !== "active")
+                    continue;
+                archive.suspend("almanac", item.id);
+                await owner.extensions.call(almanacContract.id, "pause", {
+                    scheduleId: item.id,
+                });
+            }
+            after = listed.length === 64 ? listed.at(-1)?.id : undefined;
+        } while (after !== undefined);
+        let next;
+        do {
+            const page = await owner.listSessions(next);
+            for (const row of page.sessions) {
+                const slot = (await owner.session(row.sessionId).read({ limit: 1 }))
+                    .extensions[loopContract.id];
+                if (slot?.status !== "running")
+                    continue;
+                const current = Schema.decodeUnknownSync(loop)(slot.value);
+                if (current?.loop.state !== "active")
+                    continue;
+                archive.suspend("loop", row.sessionId);
+                await owner
+                    .session(row.sessionId)
+                    .extension(loopContract.id)
+                    .call("pause", {});
+            }
+            next = page.next;
+        } while (next !== undefined);
+        return;
+    }
+    for (;;) {
+        const batch = archive.suspended();
+        if (batch.length === 0)
+            break;
+        for (const item of batch) {
+            if (item.kind === "almanac") {
+                const current = Schema.decodeUnknownSync(schedule)(await owner.extensions.call(almanacContract.id, "read", {
+                    scheduleId: item.id,
+                }));
+                if (current?.state === "paused")
+                    await owner.extensions.call(almanacContract.id, "resume", {
+                        scheduleId: item.id,
+                    });
+            }
+            else {
+                const slot = (await owner.session(item.id).read({ limit: 1 }))
+                    .extensions[loopContract.id];
+                if (slot?.status === "running") {
+                    const current = Schema.decodeUnknownSync(loop)(slot.value);
+                    if (current?.loop.state === "paused")
+                        await owner
+                            .session(item.id)
+                            .extension(loopContract.id)
+                            .call("resume", {});
+                }
+            }
+            archive.resumed(item.kind, item.id);
+        }
+    }
+}

package/dist/standalone/agent-archive.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+declare const suspendedRow: z.ZodObject<{
+    kind: z.ZodEnum<{
+        almanac: "almanac";
+        loop: "loop";
+    }>;
+    id: z.ZodString;
+}, z.core.$strict>;
+/** The Agent DO's one archive authority and durable repair cursor.
+ * Call transitions inside the same SQLite transaction as Shiitake.busySync.
+ */
+export declare function agentArchive(sql: WatchdogSqliteOwner["sql"]): {
+    read: () => {
+        archived: boolean;
+        revision: number;
+        pending: boolean;
+    };
+    /** Idempotent intent; a failed directory or schedule write retains pending. */
+    transition(archived: boolean): {
+        archived: boolean;
+        revision: number;
+        pending: boolean;
+    };
+    ack(revision: number): void;
+    /** Only schedules this archive paused are eligible for auto-resume. */
+    suspend(kind: "almanac" | "loop", id: string): void;
+    suspended(): readonly z.infer<typeof suspendedRow>[];
+    resumed(kind: "almanac" | "loop", id: string): void;
+};
+export {};

package/dist/standalone/agent-archive.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+const stateRow = z.strictObject({
+    archived: z.union([z.literal(0), z.literal(1)]),
+    revision: z.number().int().nonnegative(),
+    pending: z.union([z.literal(0), z.literal(1)]),
+});
+const suspendedRow = z.strictObject({
+    kind: z.enum(["almanac", "loop"]),
+    id: z.string(),
+});
+/** The Agent DO's one archive authority and durable repair cursor.
+ * Call transitions inside the same SQLite transaction as Shiitake.busySync.
+ */
+export function agentArchive(sql) {
+    sql.exec(`CREATE TABLE IF NOT EXISTS oyster_agent_archive (
+    singleton INTEGER PRIMARY KEY CHECK(singleton = 1),
+    archived INTEGER NOT NULL CHECK(archived IN (0, 1)),
+    revision INTEGER NOT NULL,
+    pending INTEGER NOT NULL CHECK(pending IN (0, 1))
+  ) STRICT`);
+    sql.exec("INSERT OR IGNORE INTO oyster_agent_archive(singleton,archived,revision,pending) VALUES(1,0,0,0)");
+    sql.exec(`CREATE TABLE IF NOT EXISTS oyster_agent_archive_suspended (
+    kind TEXT NOT NULL CHECK(kind IN ('almanac','loop')),
+    id TEXT NOT NULL,
+    PRIMARY KEY(kind,id)
+  ) STRICT`);
+    const read = () => {
+        const raw = sql
+            .exec("SELECT archived,revision,pending FROM oyster_agent_archive WHERE singleton=1")
+            .toArray()[0];
+        if (raw === undefined)
+            throw new Error("Agent archive authority is missing");
+        const row = stateRow.parse(raw);
+        return {
+            archived: row.archived === 1,
+            revision: row.revision,
+            pending: row.pending === 1,
+        };
+    };
+    return {
+        read,
+        /** Idempotent intent; a failed directory or schedule write retains pending. */
+        transition(archived) {
+            const before = read();
+            if (before.archived === archived)
+                return before;
+            sql.exec("UPDATE oyster_agent_archive SET archived=?, revision=revision+1, pending=1 WHERE singleton=1", archived ? 1 : 0);
+            return read();
+        },
+        ack(revision) {
+            sql.exec("UPDATE oyster_agent_archive SET pending=0 WHERE singleton=1 AND revision=?", revision);
+        },
+        /** Only schedules this archive paused are eligible for auto-resume. */
+        suspend(kind, id) {
+            sql.exec("INSERT OR IGNORE INTO oyster_agent_archive_suspended(kind,id) VALUES(?,?)", kind, id);
+        },
+        suspended() {
+            return sql
+                .exec("SELECT kind,id FROM oyster_agent_archive_suspended ORDER BY kind,id LIMIT 64")
+                .toArray()
+                .map((raw) => suspendedRow.parse(raw));
+        },
+        resumed(kind, id) {
+            sql.exec("DELETE FROM oyster_agent_archive_suspended WHERE kind=? AND id=?", kind, id);
+        },
+    };
+}

package/dist/standalone/agent-computers.d.ts

@@ -1,8 +1,9 @@
-import { Hono } from "hono";
+import type { TenantPrincipal } from "../tenant.js";
 import { type ComputerGrant } from "@fungi.computer/computer/fleet";
 import { type AgentComputerProjection, type ComputerAttachmentInput } from "../agent-computers.js";
 import type { AgentComputerConnection, AgentComputerPorts } from "../agent-computer-source.js";
-import { type OysterEnv, type OysterPrincipal } from "../host.js";
+import { type OysterEnv } from "../host.js";
+import { type Routes } from "../authorization.js";
 import type { StandaloneAgentComputerRpc } from "./computer.js";
 /** The directory supplies live authority; this adapter never invents a grant. */
 export type StandaloneAgentComputerAccess = Readonly<{
@@ -21,9 +22,9 @@ export type StandaloneAgentComputerReply = Readonly<{
 }>;
 /** Principal and persisted attachment transitions belong to the directory owner. */
 export type StandaloneAgentComputerControl = Readonly<{
-    attach: (principal: OysterPrincipal, command: ComputerAttachmentInput) => Promise<StandaloneAgentComputerReply>;
-    detach: (principal: OysterPrincipal, command: ComputerAttachmentInput) => Promise<StandaloneAgentComputerReply>;
-    read: (principal: OysterPrincipal, agentId: string) => Promise<StandaloneAgentComputerReply>;
+    attach: (principal: TenantPrincipal, command: ComputerAttachmentInput) => Promise<StandaloneAgentComputerReply>;
+    detach: (principal: TenantPrincipal, command: ComputerAttachmentInput) => Promise<StandaloneAgentComputerReply>;
+    read: (principal: TenantPrincipal, agentId: string) => Promise<StandaloneAgentComputerReply>;
 }>;
 /** Owner HTTP transport over the retained attachment command grammar. */
-export declare function standaloneAgentComputerRoutes(control: StandaloneAgentComputerControl): Hono<OysterEnv>;
+export declare function standaloneAgentComputerRoutes(control: StandaloneAgentComputerControl): Routes<OysterEnv>;

package/dist/standalone/agent-computers.js

@@ -1,9 +1,9 @@
-import { Hono } from "hono";
 import { createComputerFilesPort } from "@fungi.computer/computer";
 import { checkComputerGrant, FleetGrantRefused, } from "@fungi.computer/computer/fleet";
 import { computerCapabilities, computerValueSchema, } from "@fungi.computer/computer-contract";
 import { attachComputerInputSchema, detachComputerInputSchema, readAgentComputersInputSchema, } from "../agent-computers.js";
-import { oysterPrincipalIsOwner, } from "../host.js";
+import {} from "../host.js";
+import { owner, routes as routeTable } from "../authorization.js";
 /** Native operations use the captured Computer, never the mutable workspace selection. */
 export function standaloneAgentComputerPorts(access, connection) {
     const { computerId } = connection.attachment;
@@ -55,12 +55,9 @@ export function standaloneAgentComputerPorts(access, connection) {
 }
 /** Owner HTTP transport over the retained attachment command grammar. */
 export function standaloneAgentComputerRoutes(control) {
-    const routes = new Hono();
-    routes.post("/api/agents/:agentId/computers/:operation", async (context) => {
+    const routes = routeTable();
+    routes.post("/api/agents/:agentId/computers/:operation", owner("direct-or-app"), async (context, { principal }) => {
         context.header("Cache-Control", "no-store");
-        const principal = context.get("principal");
-        if (!oysterPrincipalIsOwner(principal))
-            return context.json({ error: "not_granted" }, 403);
         const operation = context.req.param("operation");
         if (!["attach", "detach", "read"].includes(operation))
             return context.json({ error: "not_found" }, 404);

package/dist/standalone/agent-mail.d.ts

@@ -21,11 +21,11 @@ export declare function agentMail(options: Omit<ConstructorParameters<typeof Age
                 tickConcurrent: () => Promise<WatchdogTickResult>;
             }>) => {
                 execute: (job: {
+                    readonly lane: string;
+                    readonly state: "running";
                     readonly queue: string;
                     readonly priority: number;
                     readonly payload: unknown;
-                    readonly state: "running";
-                    readonly lane: string;
                     readonly jobId: string;
                     readonly recovery?: {
                         readonly maxRecoveries: number;