@loopbacktools/server 0.0.0-stage → 0.4.0

package/dist/src/space/object.d.ts

@@ -0,0 +1,30 @@
+import { DurableObject } from "cloudflare:workers";
+import { type Caller, type ExitJson, type OperationName } from "./rpc.ts";
+/** The subprotocol an inbox speaks on the event socket. */
+export declare const EVENTS_PROTOCOL = "loopback.v1";
+/**
+ * One space: its asks, their threads, upload tickets, and the inboxes watching it. Everything it
+ * does is a space operation, served through `call`; `fetch` only accepts an inbox's WebSocket.
+ */
+export declare class Space extends DurableObject {
+    #private;
+    constructor(ctx: DurableObjectState, env: unknown);
+    /**
+     * Deletes everything the space holds and closes the inboxes watching it. It carries on as an
+     * empty space: its schema is applied afresh before it takes another request. An agent waiting
+     * on an ask it held finds the ask gone at the end of its current lap.
+     */
+    erase(): Promise<void>;
+    /**
+     * Runs one space operation on the arguments it decodes them to, and answers with its Exit, encoded
+     * for the trip back.
+     */
+    call(method: OperationName, args: readonly unknown[], caller?: Caller): Promise<ExitJson>;
+    /** Accepts an inbox's event socket and sends it the space as it stands. */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Inboxes only send keep-alive pings, which the auto-response answers without waking us. Closing
+     * needs no handler: the runtime completes the close handshake itself.
+     */
+    webSocketMessage(): Promise<void>;
+}

package/dist/src/space/object.js

@@ -0,0 +1,169 @@
+import { SqliteClient } from "@effect/sql-sqlite-do";
+import { BUILD_HEADER, REVISION_HEADER } from "@loopbacktools/protocol";
+import { REVISION } from "@loopbacktools/protocol/schema";
+import { DurableObject } from "cloudflare:workers";
+import { Effect, Exit, Layer, Logger, ManagedRuntime } from "effect";
+import { readArguments } from "./arguments.js";
+import { migrations } from "./migrations.js";
+import { operations, snapshot } from "./operations.js";
+import { buildOf, encodeExit, isLater, Outdated, } from "./rpc.js";
+import { Host, Presence, Replies } from "./services.js";
+import { AskStore, TicketStore, UploadStore } from "./store.js";
+/** The subprotocol an inbox speaks on the event socket. */
+export const EVENTS_PROTOCOL = "loopback.v1";
+/** How long a space that has refused newer code waits before restarting: long enough to answer. */
+const RESTART_DELAY_MS = 100;
+/** The close code an inbox reconnects after when the space is now on other code: Service Restart. */
+const RECONNECT_ONTO_NEW_CODE = 1012;
+/**
+ * One space: its asks, their threads, upload tickets, and the inboxes watching it. Everything it
+ * does is a space operation, served through `call`; `fetch` only accepts an inbox's WebSocket.
+ */
+export class Space extends DurableObject {
+    #runtime;
+    /** The deploy this object's code is from. */
+    #ownBuild;
+    /** Set once newer code has called: from then on everything is refused until the restart. */
+    #restarting = false;
+    constructor(ctx, env) {
+        super(ctx, env);
+        this.#ownBuild = buildOf(env);
+        ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair("ping", "pong"));
+        this.#runtime = this.#build();
+        // Build the runtime, migrations included, before the object takes any request.
+        void ctx.blockConcurrencyWhile(() => this.#runtime.runPromise(Effect.void));
+    }
+    #build() {
+        const sql = SqliteClient.layer({ storage: this.ctx.storage });
+        const host = Layer.succeed(Host, Host.of({
+            broadcast: (event) => this.#broadcast(event),
+            spaceId: this.ctx.id.toString(),
+        }));
+        return ManagedRuntime.make(Layer.mergeAll(AskStore.layer, UploadStore.layer, TicketStore.layer, migrations).pipe(Layer.provide(sql), Layer.merge(Layer.mergeAll(host, Replies.layer, Presence.layer)), Layer.merge(Logger.layer([Logger.consoleJson])), Layer.orDie));
+    }
+    /**
+     * Deletes everything the space holds and closes the inboxes watching it. It carries on as an
+     * empty space: its schema is applied afresh before it takes another request. An agent waiting
+     * on an ask it held finds the ask gone at the end of its current lap.
+     */
+    async erase() {
+        await this.ctx.blockConcurrencyWhile(async () => {
+            for (const socket of this.ctx.getWebSockets()) {
+                try {
+                    socket.close(1000, "The space was erased.");
+                }
+                catch {
+                    // Already closing.
+                }
+            }
+            const erased = this.#runtime;
+            await this.ctx.storage.deleteAll();
+            this.#runtime = this.#build();
+            await this.#runtime.runPromise(Effect.void);
+            await erased.dispose();
+        });
+    }
+    /**
+     * For a while after a deploy, an active space can go on running the code it started with while a
+     * newer Worker calls it. Called by newer code, from a later build or writing a later revision of
+     * the contract, it refuses, running nothing, and restarts onto that code a moment later, once the
+     * refusal is on its way; whatever reaches it until then is refused the same way. A caller retries
+     * what was refused. Older code calling a newer space carries on, as does code from before callers
+     * named their version, which passes nothing.
+     */
+    #outdatedFor(caller) {
+        const newer = (caller?.revision ?? REVISION) > REVISION || isLater(caller?.build, this.#ownBuild);
+        if (!this.#restarting && !newer)
+            return false;
+        if (!this.#restarting) {
+            this.#restarting = true;
+            setTimeout(() => this.ctx.abort("Newer code called this space: restarting onto it."), RESTART_DELAY_MS);
+        }
+        return true;
+    }
+    /**
+     * Runs one space operation on the arguments it decodes them to, and answers with its Exit, encoded
+     * for the trip back.
+     */
+    async call(method, args, caller) {
+        if (this.#outdatedFor(caller))
+            return encodeExit(Exit.fail(new Outdated()));
+        if (!Object.hasOwn(operations, method)) {
+            return encodeExit(await Effect.runPromiseExit(Effect.die(new Error(`No operation ${method}`))));
+        }
+        const operation = operations[method];
+        return encodeExit(await this.#runtime.runPromiseExit(Effect.flatMap(readArguments(method, args), (read) => operation(...read))));
+    }
+    /** Accepts an inbox's event socket and sends it the space as it stands. */
+    async fetch(request) {
+        if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") {
+            return new Response("Expected a WebSocket upgrade.", { status: 426 });
+        }
+        // The inbox reconnects, by then to the space on the new code.
+        const revision = request.headers.get(REVISION_HEADER);
+        const handedBy = {
+            revision: revision === null ? undefined : Number(revision),
+            build: request.headers.get(BUILD_HEADER) ?? undefined,
+        };
+        if (this.#outdatedFor(handedBy)) {
+            return new Response("This space is restarting onto newer code.", {
+                status: 503,
+                headers: { "Retry-After": "1" },
+            });
+        }
+        // Read the space first: a socket is only accepted once there is something to send it.
+        const current = await this.#runtime.runPromise(snapshot);
+        const { 0: client, 1: server } = new WebSocketPair();
+        this.ctx.acceptWebSocket(server);
+        const acceptedBy = { revision: REVISION, build: this.#ownBuild ?? null };
+        server.serializeAttachment(acceptedBy);
+        const first = { type: "snapshot", snapshot: current };
+        server.send(JSON.stringify(first));
+        const offered = (request.headers.get("Sec-WebSocket-Protocol") ?? "")
+            .split(",")
+            .map((protocol) => protocol.trim());
+        return new Response(null, {
+            status: 101,
+            webSocket: client,
+            ...(offered.includes(EVENTS_PROTOCOL)
+                ? { headers: { "Sec-WebSocket-Protocol": EVENTS_PROTOCOL } }
+                : {}),
+        });
+    }
+    /**
+     * Inboxes only send keep-alive pings, which the auto-response answers without waking us. Closing
+     * needs no handler: the runtime completes the close handshake itself.
+     */
+    async webSocketMessage() { }
+    /**
+     * Whether a socket was accepted by other code than this. A hibernated socket stays open while its
+     * space moves onto new code, so an inbox could go on hearing frames its page can't read, and never
+     * learn that Loopback was updated.
+     */
+    #acceptedByOther(socket) {
+        const by = socket.deserializeAttachment();
+        return by?.revision !== REVISION || by.build !== (this.#ownBuild ?? null);
+    }
+    /**
+     * Sends every inbox the event. One whose socket other code accepted is closed instead: it
+     * reconnects onto this code, and hears from the server that it is newer.
+     */
+    #broadcast(event) {
+        return Effect.sync(() => {
+            const frame = JSON.stringify(event);
+            for (const socket of this.ctx.getWebSockets()) {
+                try {
+                    if (this.#acceptedByOther(socket)) {
+                        socket.close(RECONNECT_ONTO_NEW_CODE, "Loopback was updated.");
+                    }
+                    else {
+                        socket.send(frame);
+                    }
+                }
+                catch {
+                    // A socket that is closing misses the frame; it gets a fresh snapshot on reconnect.
+                }
+            }
+        });
+    }
+}

package/dist/src/space/operations.d.ts

@@ -0,0 +1,149 @@
+import { type Actor, type Ask, type AskPage, type BriefingAnswerInput, type BriefingInput, type FollowUpInput, type ImageType, type QuestionInput, type Reply, type ReviewInput, type Snapshot, type ToolReply, type UploadReceipt } from "@loopbacktools/protocol";
+import { Effect } from "effect";
+import { AskClosed, AskNotFound, ContentInvalid, NotYourTurn, TicketInvalid, UploadExpired, UploadNotFound, UploadRejected } from "../domain/errors.ts";
+import { Host, Presence, Replies } from "./services.ts";
+import { AskStore, TicketStore, UploadStore } from "./store.ts";
+/** How many closed asks a snapshot carries. */
+export declare const RECENT_LIMIT = 50;
+/** How long an upload ticket stays usable. */
+export declare const UPLOAD_TTL_MS: number;
+/** How long an event ticket stays usable: long enough to open a socket, too short to be worth stealing. */
+export declare const TICKET_TTL_MS: number;
+/** The largest image an upload ticket accepts. */
+export declare const UPLOAD_MAX_BYTES: number;
+/** A question, review or briefing an agent is opening, with the MCP client that sent it when known. */
+export type OpenRequest = ({
+    readonly kind: "question";
+    readonly input: QuestionInput;
+} | {
+    readonly kind: "review";
+    readonly input: ReviewInput;
+} | {
+    readonly kind: "briefing";
+    readonly input: BriefingInput;
+}) & {
+    readonly client?: string;
+    /** Whose agent is asking. A retried call is only recognised as the same person's. */
+    readonly actor: Actor;
+};
+/** An upload ticket as the space issues it. The worker turns `token` into a URL. */
+export interface IssuedUpload {
+    readonly uploadId: string;
+    readonly spaceId: string;
+    readonly token: string;
+    readonly contentType: ImageType;
+    readonly expiresAt: string;
+    readonly maxBytes: number;
+}
+/** A reply the space holds for an agent, with the thread entry it is, so the agent can take it. */
+export interface Delivery extends ToolReply {
+    readonly seq: number;
+}
+/** An upload ticket that has been claimed for one upload. */
+export interface ClaimedUpload {
+    readonly uploadId: string;
+    readonly contentType: ImageType;
+    readonly maxBytes: number;
+}
+/**
+ * Opens an ask, or rejoins the one a retried call opened. A retry is the same question or review,
+ * from the same client and project, while the ask is still open or holds a reply that never
+ * reached the agent, and only if an agent waited on it within the reattach window.
+ */
+export declare const open: (request: OpenRequest) => Effect.Effect<Ask, ContentInvalid, AskStore | Host | Presence | UploadStore>;
+/**
+ * Records the agent's answer to a question the person asked back, and hands the move back to them.
+ * Sending the same answer again while it is already their move is a retry, and changes nothing.
+ */
+export declare const answerFollowUp: (input: FollowUpInput) => Effect.Effect<Ask, AskClosed | AskNotFound | ContentInvalid | NotYourTurn, AskStore | Host | Presence | UploadStore>;
+/** The agent's move on a briefing as recorded, and its turn: the thread entry the move ended with. */
+export interface BriefingMove {
+    readonly ask: Ask;
+    readonly turn: number;
+}
+/**
+ * Records the agent's answers on a briefing, one thread entry per point, numbering any sub-points,
+ * and hands the move back to the person. A move sent again before its reply reached the agent is a
+ * retry: it rejoins the move it repeats, and changes nothing.
+ */
+export declare const answerBriefing: (input: BriefingAnswerInput) => Effect.Effect<BriefingMove, AskClosed | AskNotFound | ContentInvalid | NotYourTurn, AskStore | Host | Presence | UploadStore>;
+/**
+ * Waits up to `waitMs` for a reply the agent has not yet taken, and shows it. `null` means none
+ * came: the caller waits again. The reply stays the agent's to take until `markDelivered` says it
+ * reached them, so a wait whose caller has gone loses nothing. While a wait is held the ask shows
+ * as waiting.
+ */
+export declare const awaitReply: (askId: string, waitMs: number) => Effect.Effect<Delivery | null, AskNotFound, AskStore | Host | Presence | Replies>;
+/** Records that the agent was handed the reply at `seq`: a retry no longer collects it. */
+export declare const markDelivered: (askId: string, seq: number) => Effect.Effect<null, never, AskStore>;
+/**
+ * Where an agent's background task stands. A task follows one of the agent's turns, numbered by
+ * the thread entry it ended with (0 for opening the ask), and completes with the first reply the
+ * person gives after it.
+ */
+export interface TaskState {
+    readonly status: "working" | "completed" | "cancelled";
+    readonly createdAt: string;
+    readonly lastUpdatedAt: string;
+    readonly reply: Delivery | null;
+}
+/**
+ * One poll of an agent's background task. While it is working, each poll keeps the ask showing an
+ * agent following it; once the person replies, it completes with that reply, every time it is asked.
+ */
+export declare const followTask: (askId: string, afterSeq: number) => Effect.Effect<TaskState, AskNotFound, AskStore | Host | Presence>;
+/**
+ * The agent stops following a background task. The ask stays open, and the person can still
+ * answer it; the inbox stops showing anyone waiting. A task that already completed stays completed.
+ */
+export declare const cancelTask: (askId: string, afterSeq: number) => Effect.Effect<TaskState, AskNotFound, AskStore | Host | Presence>;
+/** Records a person's reply, wakes the agent waiting for it, and tells every inbox. */
+export declare const reply: (askId: string, answer: Reply, by: Actor) => Effect.Effect<Ask, AskClosed | AskNotFound | NotYourTurn | import("../domain/errors.ts").ReplyInvalid, AskStore | Host | Presence | Replies>;
+export declare const get: (askId: string) => Effect.Effect<Ask, AskNotFound, AskStore | Presence>;
+/** Every open ask and the most recently closed. */
+export declare const snapshot: Effect.Effect<Snapshot, never, AskStore | Presence>;
+/** A page of closed asks, newest first. */
+export declare const history: (before: string | undefined, limit: number) => Effect.Effect<AskPage, never, AskStore | Presence>;
+/** Issues a single-use ticket to upload one image. */
+export declare const createUpload: (contentType: ImageType) => Effect.Effect<IssuedUpload, never, Host | UploadStore>;
+/** Uses up an upload ticket. Once claimed it is spent, whether or not the upload then succeeds. */
+export declare const claimUpload: (token: string, contentType: string) => Effect.Effect<ClaimedUpload, UploadExpired | UploadNotFound | UploadRejected, UploadStore>;
+/** Records that a claimed upload's bytes are stored. */
+export declare const completeUpload: (uploadId: string, size: number) => Effect.Effect<UploadReceipt, UploadNotFound, UploadStore>;
+/** A stored upload's type and size. */
+export declare const findUpload: (uploadId: string) => Effect.Effect<UploadReceipt, UploadNotFound, UploadStore>;
+/** A one-time pass onto the space's event socket, for the actor named. */
+export interface IssuedTicket {
+    readonly spaceId: string;
+    readonly secret: string;
+    readonly expiresAt: string;
+}
+/** Issues a one-time pass onto the event socket, held only as its hash. */
+export declare const issueTicket: (actorId: string) => Effect.Effect<IssuedTicket, never, Host | TicketStore>;
+/** Spends an event ticket: who it was issued to, or `TicketInvalid` when it is unknown, used or expired. */
+export declare const redeemTicket: (ticketSecret: string) => Effect.Effect<{
+    actorId: string;
+}, TicketInvalid, TicketStore>;
+/** Everything a space does, by name: what its object serves over RPC. */
+export declare const operations: {
+    open: (request: OpenRequest) => Effect.Effect<Ask, ContentInvalid, AskStore | Host | Presence | UploadStore>;
+    answerFollowUp: (input: FollowUpInput) => Effect.Effect<Ask, AskClosed | AskNotFound | ContentInvalid | NotYourTurn, AskStore | Host | Presence | UploadStore>;
+    answerBriefing: (input: BriefingAnswerInput) => Effect.Effect<BriefingMove, AskClosed | AskNotFound | ContentInvalid | NotYourTurn, AskStore | Host | Presence | UploadStore>;
+    awaitReply: (askId: string, waitMs: number) => Effect.Effect<Delivery | null, AskNotFound, AskStore | Host | Presence | Replies>;
+    markDelivered: (askId: string, seq: number) => Effect.Effect<null, never, AskStore>;
+    followTask: (askId: string, afterSeq: number) => Effect.Effect<TaskState, AskNotFound, AskStore | Host | Presence>;
+    cancelTask: (askId: string, afterSeq: number) => Effect.Effect<TaskState, AskNotFound, AskStore | Host | Presence>;
+    reply: (askId: string, answer: Reply, by: Actor) => Effect.Effect<Ask, AskClosed | AskNotFound | NotYourTurn | import("../domain/errors.ts").ReplyInvalid, AskStore | Host | Presence | Replies>;
+    get: typeof get;
+    snapshot: () => Effect.Effect<Snapshot, never, AskStore | Presence>;
+    history: (before: string | undefined, limit: number) => Effect.Effect<AskPage, never, AskStore | Presence>;
+    createUpload: (contentType: ImageType) => Effect.Effect<IssuedUpload, never, Host | UploadStore>;
+    claimUpload: (token: string, contentType: string) => Effect.Effect<ClaimedUpload, UploadExpired | UploadNotFound | UploadRejected, UploadStore>;
+    completeUpload: (uploadId: string, size: number) => Effect.Effect<UploadReceipt, UploadNotFound, UploadStore>;
+    findUpload: (uploadId: string) => Effect.Effect<UploadReceipt, UploadNotFound, UploadStore>;
+    issueTicket: (actorId: string) => Effect.Effect<IssuedTicket, never, Host | TicketStore>;
+    redeemTicket: (ticketSecret: string) => Effect.Effect<{
+        actorId: string;
+    }, TicketInvalid, TicketStore>;
+};
+export type Operations = typeof operations;