@fungi.computer/oyster 0.4.1 → 0.6.0

package/dist/machine-link/host.js

@@ -5,10 +5,12 @@ import { correlationKey } from "@fungi.computer/cairn";
 import { createMachineLinkPostChannel, MachineLinkPostUnavailable, machineLinkAudience, machineLinkProtocolVersion, } from "@fungi.computer/seam/machine-link-protocol";
 import { importSeamVerifiers, seamHeader, verifySeamRequest, } from "@fungi.computer/seam";
 import { createPost, definePostRoute, PostDeliveryResultSchema, } from "@fungi.computer/carrier/post";
+import { undeliverableReply } from "@fungi.computer/bird-dog";
 import { BirdDogMailSchema } from "@fungi.computer/bird-dog/effect";
 import { machineAgentOperationSchema } from "@fungi.computer/seam/machine-link-protocol";
 import { Watchdog, } from "@fungi.computer/watchdog";
 import { createMachineLinkSockets } from "./presence.js";
+import { machineLinkDisposition } from "./disposition.js";
 const attachmentSchema = z.strictObject({
     deviceId: z.string().min(1).max(256),
     fenceEpoch: z.int().nonnegative(),
@@ -48,6 +50,15 @@ const machineMailEnvelope = Schema.Struct({
     address: custodyAddress,
     event: BirdDogMailSchema,
 });
+const machineDispositionEnvelope = Schema.Struct({
+    key: Schema.String,
+    kind: Schema.Literal("machineLinkDisposition"),
+    address: custodyAddress,
+    event: Schema.Struct({
+        original: machineMailEnvelope,
+        reply: BirdDogMailSchema,
+    }),
+});
 const machineAgentEnvelope = Schema.Struct({
     key: Schema.String,
     kind: Schema.Literal("machineAgent"),
@@ -87,6 +98,25 @@ export class MachineLinkHost {
                     }),
                 },
             }),
+            machineLinkDisposition: definePostRoute({
+                addressKind: "machineLinkAgent",
+                address: custodyAddress,
+                event: machineDispositionEnvelope.fields.event,
+                name: ({ agentId }) => agentId,
+                namespace: {
+                    getByName: () => ({
+                        deliver: async (envelope) => {
+                            const typed = Schema.decodeUnknownSync(machineDispositionEnvelope, { onExcessProperty: "error" })(envelope);
+                            return await this.options.disposition(typed.event.original, {
+                                key: typed.key,
+                                kind: "agentMail",
+                                address: typed.address,
+                                event: typed.event.reply,
+                            });
+                        },
+                    }),
+                },
+            }),
         };
         context.setWebSocketAutoResponse(new WebSocketRequestResponsePair("ping", "pong"));
         this.router = new Hono().get("/api/teams/:teamId/local/mesh/:deviceId/connect", async (context) => {
@@ -141,6 +171,8 @@ export class MachineLinkHost {
         await this.publishDirectory(socket, deviceId);
         await this.releaseCustody();
         await this.drainCustody();
+        await this.stageUndeliverableReplies();
+        await this.drainCustody();
     }
     async publishDirectory(socket, deviceId) {
         this.deviceId = deviceId;
@@ -195,7 +227,7 @@ export class MachineLinkHost {
         }
         return channel;
     }
-    async deliver(deviceId, envelope) {
+    async deliver(deviceId, envelope, options = {}) {
         this.deviceId = deviceId;
         await this.options.authorize(deviceId);
         const links = createMachineLinkSockets(this.context, deviceId);
@@ -205,7 +237,7 @@ export class MachineLinkHost {
         const typedEnvelope = Schema.decodeUnknownSync(Schema.Union([machineMailEnvelope, machineAgentEnvelope]))(envelope);
         if (typedEnvelope.kind === "machineAgent")
             return await this.deliverLiveOperation(deviceId, socket, typedEnvelope);
-        return await this.deliverCustodyMail(deviceId, socket, typedEnvelope);
+        return await this.deliverCustodyMail(deviceId, socket, typedEnvelope, options.refuseDuplicate === true);
     }
     async deliverLiveOperation(deviceId, socket, envelope) {
         if (socket === undefined)
@@ -213,18 +245,31 @@ export class MachineLinkHost {
         await this.publishDirectory(socket, deviceId);
         return await this.channel(socket, deviceId).deliver(envelope);
     }
-    async deliverCustodyMail(deviceId, socket, envelope) {
+    async deliverCustodyMail(deviceId, socket, envelope, refuseDuplicate = false) {
         const { post } = await this.custody();
         const existing = post.read(envelope.key);
         if (existing !== undefined) {
+            if (refuseDuplicate)
+                return "refused";
             this.owner.transactionSync(() => {
                 post.send(envelope);
             });
             return previousCustodyReceipt(existing);
         }
-        this.owner.transactionSync(() => {
+        const duplicate = this.owner.transactionSync(() => {
+            if (post.read(envelope.key) !== undefined)
+                return true;
             post.send(envelope);
+            return false;
         });
+        if (duplicate) {
+            if (refuseDuplicate)
+                return "refused";
+            const raced = post.read(envelope.key);
+            return raced === undefined
+                ? recipientOffline
+                : previousCustodyReceipt(raced);
+        }
         await this.options.scheduleWake(post.nextWake() ?? Date.now());
         if (socket === undefined)
             return recipientOffline;
@@ -237,12 +282,87 @@ export class MachineLinkHost {
     /** Run due Carrier work; expired rows remain visible as Carrier dead letters. */
     async alarm() {
         await this.drainCustody();
+        await this.stageUndeliverableReplies();
+        await this.drainCustody();
+    }
+    /** Turn each terminal incoming-mail row into a durable reply outbox row. */
+    async stageUndeliverableReplies() {
+        const { post } = await this.custody();
+        let cursor;
+        do {
+            const page = post.deadLetters(64, cursor);
+            for (const letter of page.letters)
+                this.stageUndeliverableReply(post, letter);
+            cursor = page.nextCursor;
+        } while (cursor !== undefined);
+    }
+    stageUndeliverableReply(post, letter) {
+        if ((letter.reason !== "exhausted" && letter.reason !== "expired") ||
+            letter.envelope.kind !== "agentMail")
+            return;
+        const original = Schema.decodeUnknownSync(machineMailEnvelope, {
+            onExcessProperty: "error",
+        })(letter.envelope);
+        if (original.event.reply !== undefined ||
+            original.event.from.kind !== "agent")
+            return;
+        const replyKey = `${original.key}:reply:0`;
+        if (post.read(replyKey) !== undefined)
+            return;
+        const reply = {
+            key: replyKey,
+            kind: "agentMail",
+            address: {
+                scopeId: original.address.scopeId,
+                agentId: original.event.from.agentId,
+            },
+            event: undeliverableReply(original.event, Date.now()),
+        };
+        const disposition = {
+            key: replyKey,
+            kind: "machineLinkDisposition",
+            address: reply.address,
+            event: { original, reply: reply.event },
+        };
+        this.owner.transactionSync(() => {
+            if (post.read(replyKey) === undefined)
+                post.send(disposition);
+        });
     }
-    /** Expose terminal custody rows so S9 can stage its own disposition reply. */
+    /** Expose terminal custody rows for the device-owned diagnostic surface. */
     async deadLetters(afterKey) {
         const { post } = await this.custody();
         return post.deadLetters(64, afterKey);
     }
+    /** Prove a disposition is still present in this link's durable Post outbox. */
+    async hasStagedDisposition(deviceId, original, reply) {
+        this.deviceId = deviceId;
+        await this.options.authorize(deviceId);
+        const identity = { teamId: this.options.teamId, deviceId };
+        const requested = machineLinkDisposition(identity, original, reply);
+        if (requested === undefined)
+            return false;
+        const { post } = await this.custody();
+        const row = post.read(requested.reply.key);
+        if (row?.state !== "pending")
+            return false;
+        try {
+            const staged = Schema.decodeUnknownSync(machineDispositionEnvelope, {
+                onExcessProperty: "error",
+            })(row.envelope);
+            const stagedDisposition = machineLinkDisposition(identity, staged.event.original, {
+                key: staged.key,
+                kind: "agentMail",
+                address: staged.address,
+                event: staged.event.reply,
+            });
+            return (stagedDisposition !== undefined &&
+                JSON.stringify(stagedDisposition) === JSON.stringify(requested));
+        }
+        catch {
+            return false;
+        }
+    }
     async deliverToSocket(envelope) {
         const deviceId = this.deviceId;
         if (deviceId === undefined)

package/dist/machine-link/link.d.ts

@@ -29,6 +29,10 @@ export declare function createMachineLink<Readback>(state: MachineLinkState, opt
     fetch: (request: Request) => Promise<Response>;
     /** Mail addressed to this device's Agent, rechecked against its home. */
     deliver(input: MachineLinkIdentity, caller: MachineLinkCaller, agentId: string, envelope: PostEnvelope): Promise<PostDeliveryResult>;
+    /** A relay's typed terminal reply to an Agent homed on this device. */
+    deliverRelayDisposition(input: MachineLinkIdentity, relayInput: MachineLinkIdentity, original: PostEnvelope, reply: PostEnvelope): Promise<PostDeliveryResult>;
+    /** Attest a still-pending disposition in this device's own Post outbox. */
+    hasStagedDisposition(input: MachineLinkIdentity, original: PostEnvelope, reply: PostEnvelope): Promise<boolean>;
     /** One finite Agent operation on this device, returning its receipt. */
     operation(input: MachineLinkIdentity, caller: MachineLinkCaller, agentId: string, raw: MachineAgentOperation): Promise<Schema.Json>;
     /**

package/dist/machine-link/link.js

@@ -4,8 +4,16 @@ import * as Schema from "effect/Schema";
 import { BirdDogMailSchema } from "@fungi.computer/bird-dog/effect";
 import { agentMailAddressSchema, machineAgentOperationSchema, MachineLinkPostUnavailable, } from "@fungi.computer/seam/machine-link-protocol";
 import { machineLinkFenceFactSchema, machineLinkIdentitySchema, machineLinkName, MachineLinkRefused, } from "./authority.js";
+import { machineLinkDisposition } from "./disposition.js";
 import { MachineLinkHost } from "./host.js";
 const pinKey = "machine-link:identity";
+function isRetainedRelayFence(target, relay, fence) {
+    return (relay.teamId === target.teamId &&
+        relay.deviceId !== target.deviceId &&
+        fence !== null &&
+        fence.teamId === relay.teamId &&
+        fence.deviceId === relay.deviceId);
+}
 /**
  * One device's link inside its own Durable Object. The host's DO class
  * delegates every entry point here. Identity is pinned on the first live
@@ -60,6 +68,12 @@ export function createMachineLink(state, options) {
         })(envelope.event);
         return { address, mail: body };
     };
+    const deliverUndeliverable = async (identity, rawOriginal, rawReply) => {
+        const checked = machineLinkDisposition(identity, rawOriginal, rawReply);
+        if (checked === undefined)
+            return "refused";
+        return await authority.deliverUndeliverable(identity, checked.original, checked.reply);
+    };
     /**
      * The link's own sender check, whatever the host answered: the facts must
      * name the caller and actor it saw, a hosted caller must be hosted, and a
@@ -94,6 +108,8 @@ export function createMachineLink(state, options) {
         if (envelope.kind !== "agentMail")
             return "refused";
         const { address, mail: body } = mail(envelope);
+        if (body.from.kind !== "agent")
+            return "refused";
         const caller = {
             kind: "device",
             deviceId: identity.deviceId,
@@ -118,6 +134,7 @@ export function createMachineLink(state, options) {
             replay: openReplayStore,
             directory: () => authority.directory(identity),
             receive: (_device, envelope) => receive(identity, envelope),
+            disposition: (original, reply) => deliverUndeliverable(identity, original, reply),
             scheduleWake: (at) => state.storage.setAlarm(at),
             report: options.report,
         }));
@@ -149,16 +166,45 @@ export function createMachineLink(state, options) {
                 return "refused";
             const { address, mail: body } = mail(envelope);
             const facts = await checkedTarget(device, caller, agentId, null);
+            const senderMatches = body.from.kind === "agent" && body.from.agentId === facts.callerAgentId;
+            const systemOfflineDisposition = body.from.kind === "system" &&
+                body.reply?.outcome === "undeliverable" &&
+                body.reply.reason === "recipient_offline" &&
+                body.to.agentId === facts.targetAgentId;
             if (facts.targetHome.kind !== "machine" ||
                 facts.targetHome.deviceId !== device.deviceId ||
                 envelope.key !== body.key ||
                 address.scopeId !== facts.teamId ||
                 address.agentId !== facts.targetAgentId ||
                 body.to.agentId !== facts.targetAgentId ||
-                body.from.agentId !== facts.callerAgentId)
+                (!senderMatches && !systemOfflineDisposition))
                 return "refused";
             return await hostFor(device).deliver(device.deviceId, envelope);
         },
+        /** A relay's typed terminal reply to an Agent homed on this device. */
+        async deliverRelayDisposition(input, relayInput, original, reply) {
+            const device = await current(input);
+            const relay = machineLinkIdentitySchema.parse(relayInput);
+            const retainedRelay = await authority.currentFence(relay);
+            if (!isRetainedRelayFence(device, relay, retainedRelay))
+                return "refused";
+            const checked = machineLinkDisposition(device, original, reply);
+            if (checked === undefined)
+                return "refused";
+            if (!(await authority.verifyRelayDisposition(relay, checked.original, checked.reply)))
+                return "refused";
+            const home = await authority.agentHome(device, checked.reply.address.agentId);
+            if (home?.kind !== "machine" || home.deviceId !== device.deviceId)
+                return "refused";
+            return await hostFor(device).deliver(device.deviceId, checked.reply, {
+                refuseDuplicate: true,
+            });
+        },
+        /** Attest a still-pending disposition in this device's own Post outbox. */
+        async hasStagedDisposition(input, original, reply) {
+            const device = await current(input);
+            return await hostFor(device).hasStagedDisposition(device.deviceId, original, reply);
+        },
         /** One finite Agent operation on this device, returning its receipt. */
         async operation(input, caller, agentId, raw) {
             const device = await current(input);

package/dist/page/capabilities.js

@@ -3,7 +3,7 @@ import { compile, parse, pathToRegexp } from "path-to-regexp";
 import * as Schema from "effect/Schema";
 import { AppError } from "@fungi.computer/agar";
 import { parseJsonValue } from "@fungi.computer/whistle/wire";
-import { computerTargetUrl } from "./computer-target.js";
+import { computerTargetUrl } from "../computer-target.js";
 const queryInput = Schema.Record(Schema.String, Schema.Union([Schema.String, Schema.Number, Schema.Boolean]));
 const capabilityInputSchema = Schema.Union([Schema.Json, Schema.Undefined]);
 function resolveRoute(path, input) {

package/dist/page/child-selection.d.ts

@@ -0,0 +1,27 @@
+/** The launch fields a window names; none of them is authority. */
+export type ChildLaunch = Readonly<{
+    appId: string;
+    releaseId: string;
+    surfaceId: string;
+    href: string;
+}>;
+/** The identity the App's own configuration route answers with. */
+export type ChildIdentity = Readonly<{
+    installationId: string;
+    appId: string;
+    releaseId: string;
+    computerId: string | null;
+}>;
+/**
+ * The installation page a launch names, or null when the address is not one.
+ * Only an `/apps/<installationId>/` page is ever asked for its configuration.
+ */
+export declare function childInstallationAddress(href: string, origin: string): URL | null;
+/**
+ * The launch still names what the host serves at its address: the same
+ * installation, App and Release, under the admitted Computer. The host's
+ * configuration read is the one fresh answer; no directory read precedes it.
+ */
+export declare function childMatchesLaunch(launch: ChildLaunch, pathname: string, config: ChildIdentity, computerTarget: string | undefined): boolean;
+/** Concurrent callers share the one read in flight; a settled read is never reused. */
+export declare function sharedRead<A>(read: () => Promise<A>): () => Promise<A>;

package/dist/page/child-selection.js

@@ -0,0 +1,38 @@
+import { addressKey } from "@fungi.computer/nacre/app-directory";
+const installationPath = /^\/apps\/[^/]+\/$/u;
+/**
+ * The installation page a launch names, or null when the address is not one.
+ * Only an `/apps/<installationId>/` page is ever asked for its configuration.
+ */
+export function childInstallationAddress(href, origin) {
+    const address = new URL(href, origin);
+    return address.origin === origin && installationPath.test(address.pathname)
+        ? address
+        : null;
+}
+/**
+ * The launch still names what the host serves at its address: the same
+ * installation, App and Release, under the admitted Computer. The host's
+ * configuration read is the one fresh answer; no directory read precedes it.
+ */
+export function childMatchesLaunch(launch, pathname, config, computerTarget) {
+    return (pathname === `/apps/${encodeURIComponent(config.installationId)}/` &&
+        launch.surfaceId ===
+            addressKey({
+                kind: "installation",
+                installationId: config.installationId,
+            }) &&
+        config.appId === launch.appId &&
+        config.releaseId === launch.releaseId &&
+        (computerTarget === undefined || config.computerId === computerTarget));
+}
+/** Concurrent callers share the one read in flight; a settled read is never reused. */
+export function sharedRead(read) {
+    let inFlight;
+    return () => {
+        inFlight ??= read().finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    };
+}

package/dist/page/mount.js

@@ -9,7 +9,7 @@ import { RpcTarget, RpcStub } from "@fungi.computer/capnweb";
 import { EventSource } from "eventsource";
 import { connectBrowser, UiBrowserError, } from "@fungi.computer/knapsack/ui/browser";
 import { createPageLifetime } from "./lifetime.js";
-import { computerTargetUrl } from "./computer-target.js";
+import { computerTargetUrl } from "../computer-target.js";
 import * as Schema from "effect/Schema";
 import { AppError, createCapabilityRegistry, } from "@fungi.computer/agar";
 import { appStorage } from "@fungi.computer/agar/storage";