@loopbacktools/server 0.0.0-stage → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bison Labs Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @loopbacktools/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Loopback server for Cloudflare Workers: the `Space` Durable Object that holds asks and their
+threads, the REST API and event socket an inbox uses, the MCP tools agents call, and the gates that
+decide who a request is from.
+
+Most people deploy [Loopback](https://github.com/LoopBackTools/loopback) as it is. Use this package to
+compose Loopback into a Worker of your own:
+
+```ts
+import { ConfiguredGate, createLoopback } from "@loopbacktools/server";
+
+export { Space } from "@loopbacktools/server";
+
+export default createLoopback({ gate: ConfiguredGate });
+```
+
+Declare the `Space` class as a Durable Object with SQLite storage, bind an R2 bucket as `FILES`, and
+set either `LOOPBACK_TOKEN` (one space behind one secret) or the JWT settings (a space per tenant
+behind your login). [`docs/hosting.md`](https://github.com/LoopBackTools/loopback/blob/main/docs/hosting.md)
+explains the JWT gate, OAuth for MCP clients, and wrapping the spaces to meter or decline what
+tenants open.
+
+The package is written in [Effect](https://effect.website) and compiled against
+`@cloudflare/workers-types`; its types refer to the Workers runtime's globals.
+
+MIT licensed.

package/dist/package.json

@@ -0,0 +1,57 @@
+{
+    "name": "@loopbacktools/server",
+    "version": "0.4.1",
+    "description": "The Loopback server: Durable Object, HTTP API, event socket and MCP tools for Cloudflare Workers.",
+    "homepage": "https://github.com/LoopBackTools/loopback/tree/main/packages/server#readme",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/LoopBackTools/loopback.git",
+        "directory": "packages/server"
+    },
+    "files": [
+        "dist"
+    ],
+    "type": "module",
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "publishConfig": {
+        "exports": {
+            ".": {
+                "types": "./dist/src/index.d.ts",
+                "default": "./dist/src/index.js"
+            }
+        },
+        "access": "public"
+    },
+    "scripts": {
+        "types": "cd test && cf workers types",
+        "typecheck": "pnpm types && tsc --noEmit && tsc --noEmit -p test/arch",
+        "test": "pnpm types && vitest run",
+        "build": "tsc -p tsconfig.build.json"
+    },
+    "dependencies": {
+        "@effect/sql-sqlite-do": "catalog:",
+        "@hono/zod-validator": "catalog:",
+        "@loopbacktools/protocol": "workspace:*",
+        "@modelcontextprotocol/server": "catalog:",
+        "effect": "catalog:",
+        "hono": "catalog:",
+        "jose": "catalog:",
+        "secure-json-parse": "catalog:",
+        "zod": "catalog:"
+    },
+    "devDependencies": {
+        "@cloudflare/vitest-plugin": "catalog:",
+        "@cloudflare/workers-types": "catalog:",
+        "@effect/vitest": "catalog:",
+        "@modelcontextprotocol/client": "catalog:",
+        "@types/node": "catalog:",
+        "archunit": "catalog:",
+        "cf": "catalog:",
+        "es-module-lexer": "catalog:",
+        "typescript": "catalog:",
+        "vitest": "catalog:"
+    }
+}

package/dist/src/domain/ask.d.ts

@@ -0,0 +1,78 @@
+import { type Actor, type Ask, type AskStatus, type Block, type BriefingInput, type BriefingPrompt, type Entry, type QuestionInput, type QuestionPrompt, type Reply, type ReviewInput, type ReviewPrompt } from "@loopbacktools/protocol";
+import { Effect } from "effect";
+import { AskClosed, ContentInvalid, NotYourTurn, ReplyInvalid } from "./errors.ts";
+/** An ask as the space stores it: everything but its thread and whether an agent is waiting. */
+export type AskRecord = AskHead & ({
+    readonly kind: "question";
+    readonly prompt: QuestionPrompt;
+} | {
+    readonly kind: "review";
+    readonly prompt: ReviewPrompt;
+    readonly revises: string | null;
+} | {
+    readonly kind: "briefing";
+    readonly prompt: BriefingPrompt;
+});
+interface AskHead {
+    readonly id: string;
+    /** What a retried call is recognised by. See `fingerprint`. */
+    readonly key: string;
+    readonly status: AskStatus;
+    readonly project: string | null;
+    readonly client: string | null;
+    /** Whose agent asked, when the deployment's gate knows. */
+    readonly raisedBy: Actor | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly closedAt: string | null;
+    /** The last time an agent call was blocked on this ask. */
+    readonly lastWaitedAt: string | null;
+}
+/** One turn of a thread as stored, with whether a human reply has been handed to an agent. */
+export interface EntryRecord {
+    readonly askId: string;
+    readonly seq: number;
+    readonly entry: Entry;
+    readonly deliveredAt: string | null;
+}
+/** How long a retried call may still join the ask it opened, measured from its last wait. */
+export declare const REATTACH_WINDOW_MS: number;
+/**
+ * The most an agent's opening or answer may hold, as JSON. Each is one SQLite row, which holds at
+ * most 2 MB, and the snapshot an inbox starts from carries every open ask in one WebSocket frame.
+ */
+export declare const MAX_ASK_BYTES: number;
+/**
+ * Refuses what an agent sends when it is too large to keep and show, with advice that fits what it
+ * was sending: an ask can be split into several, an answer can only show less.
+ */
+export declare const checkSize: (content: unknown, advice?: string) => Effect.Effect<void, ContentInvalid>;
+export declare const questionPrompt: (input: QuestionInput) => QuestionPrompt;
+export declare const reviewPrompt: (input: ReviewInput) => ReviewPrompt;
+/** A briefing as it opens, its points numbered; refused when it holds more than the inbox shows. */
+export declare const briefingPrompt: (input: BriefingInput) => Effect.Effect<BriefingPrompt, ContentInvalid>;
+/** The uploads a set of blocks shows. */
+export declare const imagesIn: (blocks: readonly Block[]) => string[];
+/** The ask in its wire shape. */
+export declare const toAsk: (record: AskRecord, thread: readonly EntryRecord[], waiting: boolean) => Ask;
+/**
+ * Where an ask stands once a reply lands: open for the agent after a follow-up, or after replies on a
+ * briefing that leave a point unresolved; closed otherwise.
+ */
+export declare const statusAfter: (record: AskRecord, thread: readonly Entry[], reply: Reply) => AskStatus;
+/**
+ * Whether a person may make this reply now. The rules the contract cannot state as a schema:
+ * whose turn it is, which outcomes fit which kind, that an answer's choices are among those
+ * offered, and that replies on a briefing fit its points. A briefing may be dismissed even while
+ * the agent owes an answer, so one whose agent has gone never stays open for good.
+ */
+export declare const checkReply: (record: AskRecord, thread: readonly Entry[], reply: Reply) => Effect.Effect<void, AskClosed | NotYourTurn | ReplyInvalid>;
+/**
+ * What identifies a call as a retry of one already made: the hex SHA-256 of what was asked, by
+ * which client, for which project. Equal inputs from another session share it too, which is why a
+ * match only counts inside `REATTACH_WINDOW_MS`.
+ */
+export declare const fingerprint: (subject: unknown) => Effect.Effect<string>;
+/** The hex SHA-256 of some text: how secrets are kept at rest, and how asks are fingerprinted. */
+export declare const sha256: (text: string) => Effect.Effect<string>;
+export {};

package/dist/src/domain/ask.js

@@ -0,0 +1,161 @@
+import { foldBriefing, MAX_TOP_POINTS, numberBriefing, respondedProblem, } from "@loopbacktools/protocol";
+import { Effect } from "effect";
+import { AskClosed, ContentInvalid, NotYourTurn, ReplyInvalid } from "./errors.js";
+/** How long a retried call may still join the ask it opened, measured from its last wait. */
+export const REATTACH_WINDOW_MS = 60 * 60 * 1000;
+/**
+ * The most an agent's opening or answer may hold, as JSON. Each is one SQLite row, which holds at
+ * most 2 MB, and the snapshot an inbox starts from carries every open ask in one WebSocket frame.
+ */
+export const MAX_ASK_BYTES = 256 * 1024;
+/**
+ * Refuses what an agent sends when it is too large to keep and show, with advice that fits what it
+ * was sending: an ask can be split into several, an answer can only show less.
+ */
+export const checkSize = (content, advice = "Show the part that matters.") => {
+    const bytes = new TextEncoder().encode(JSON.stringify(content)).byteLength;
+    return bytes <= MAX_ASK_BYTES
+        ? Effect.void
+        : Effect.fail(new ContentInvalid({
+            reason: `This is too large to show: ${Math.ceil(bytes / 1024)} KiB, where the most is ${MAX_ASK_BYTES / 1024} KiB. ${advice}`,
+        }));
+};
+export const questionPrompt = (input) => ({
+    question: input.question,
+    options: input.options ?? [],
+    multiple: input.multiple ?? false,
+    ...(input.context === undefined ? {} : { context: input.context }),
+});
+export const reviewPrompt = (input) => ({
+    title: input.title,
+    content: input.content,
+    ...(input.summary === undefined ? {} : { summary: input.summary }),
+});
+/** A briefing as it opens, its points numbered; refused when it holds more than the inbox shows. */
+export const briefingPrompt = (input) => {
+    const count = input.sections.reduce((sum, section) => sum + section.points.length, 0);
+    return count <= MAX_TOP_POINTS
+        ? Effect.succeed(numberBriefing(input))
+        : Effect.fail(new ContentInvalid({
+            reason: `This briefing has ${count} points, where the most is ${MAX_TOP_POINTS}. Split it into several briefings, or group points as sub-points once the person replies.`,
+        }));
+};
+/** The uploads a set of blocks shows. */
+export const imagesIn = (blocks) => blocks.flatMap((block) => (block.type === "image" ? [block.uploadId] : []));
+/** The ask in its wire shape. */
+export const toAsk = (record, thread, waiting) => {
+    const common = {
+        id: record.id,
+        status: record.status,
+        waiting,
+        thread: thread.map((row) => row.entry),
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        ...(record.project === null ? {} : { project: record.project }),
+        ...(record.client === null ? {} : { client: record.client }),
+        ...(record.raisedBy === null ? {} : { raisedBy: record.raisedBy }),
+        ...(record.closedAt === null ? {} : { closedAt: record.closedAt }),
+    };
+    switch (record.kind) {
+        case "question":
+            return { kind: "question", prompt: record.prompt, ...common };
+        case "review":
+            return {
+                kind: "review",
+                prompt: record.prompt,
+                ...(record.revises === null ? {} : { revises: record.revises }),
+                ...common,
+            };
+        case "briefing":
+            return { kind: "briefing", prompt: record.prompt, ...common };
+    }
+};
+/**
+ * Where an ask stands once a reply lands: open for the agent after a follow-up, or after replies on a
+ * briefing that leave a point unresolved; closed otherwise.
+ */
+export const statusAfter = (record, thread, reply) => {
+    if (reply.outcome === "follow_up")
+        return "awaiting_agent";
+    if (reply.outcome !== "responded" || record.kind !== "briefing")
+        return "closed";
+    const after = foldBriefing(record.prompt, [...thread, { author: "human", reply, at: "" }]);
+    return after.resolved ? "closed" : "awaiting_agent";
+};
+/**
+ * Whether a person may make this reply now. The rules the contract cannot state as a schema:
+ * whose turn it is, which outcomes fit which kind, that an answer's choices are among those
+ * offered, and that replies on a briefing fit its points. A briefing may be dismissed even while
+ * the agent owes an answer, so one whose agent has gone never stays open for good.
+ */
+export const checkReply = (record, thread, reply) => {
+    if (record.status === "closed")
+        return Effect.fail(new AskClosed({ askId: record.id }));
+    if (record.status === "awaiting_agent" &&
+        !(record.kind === "briefing" && reply.outcome === "dismissed")) {
+        return Effect.fail(new NotYourTurn({ askId: record.id, turn: "agent" }));
+    }
+    const invalid = (reason) => Effect.fail(new ReplyInvalid({ reason }));
+    switch (reply.outcome) {
+        case "dismissed":
+            return Effect.void;
+        case "follow_up":
+            return record.kind === "briefing"
+                ? invalid("A briefing takes replies on its points, not a question back: write on a point.")
+                : Effect.void;
+        case "responded": {
+            if (record.kind !== "briefing") {
+                return invalid(`"responded" is a reply to a briefing, and this ask is a ${record.kind}.`);
+            }
+            const problem = respondedProblem(record.prompt, thread, reply);
+            return problem === null ? Effect.void : invalid(problem);
+        }
+        case "approved":
+        case "changes_requested":
+            return record.kind === "review"
+                ? Effect.void
+                : invalid(`"${reply.outcome}" is a reply to a review, and this ask is a ${record.kind}.`);
+        case "answered": {
+            if (record.kind !== "question") {
+                return invalid(`"answered" is a reply to a question, and this ask is a ${record.kind}.`);
+            }
+            const offered = new Set(record.prompt.options.map((option) => option.label));
+            const unknown = reply.selected.filter((label) => !offered.has(label));
+            if (unknown.length > 0) {
+                return invalid(`Not among the choices offered: ${unknown.map((l) => `"${l}"`).join(", ")}.`);
+            }
+            if (new Set(reply.selected).size !== reply.selected.length) {
+                return invalid("A choice is selected more than once.");
+            }
+            if (!record.prompt.multiple && reply.selected.length > 1) {
+                return invalid("This question takes one choice.");
+            }
+            if (reply.selected.length === 0 && (reply.text ?? "").trim() === "") {
+                return invalid("An answer needs a choice or some text.");
+            }
+            return Effect.void;
+        }
+    }
+};
+/** Object keys sorted at every depth, so equal inputs serialise equally however they were built. */
+const canonical = (value) => {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (typeof value !== "object" || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, field]) => field !== undefined)
+        .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, field]) => [key, canonical(field)]));
+};
+/**
+ * What identifies a call as a retry of one already made: the hex SHA-256 of what was asked, by
+ * which client, for which project. Equal inputs from another session share it too, which is why a
+ * match only counts inside `REATTACH_WINDOW_MS`.
+ */
+export const fingerprint = (subject) => sha256(JSON.stringify(canonical(subject)));
+/** The hex SHA-256 of some text: how secrets are kept at rest, and how asks are fingerprinted. */
+export const sha256 = (text) => Effect.promise(async () => {
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+    return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+});

package/dist/src/domain/errors.d.ts

@@ -0,0 +1,70 @@
+import { Schema } from "effect";
+declare const AskNotFound_base: Schema.Class<AskNotFound, Schema.TaggedStruct<"AskNotFound", {
+    readonly askId: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** No ask with this id in the space. */
+export declare class AskNotFound extends AskNotFound_base {
+}
+declare const AskClosed_base: Schema.Class<AskClosed, Schema.TaggedStruct<"AskClosed", {
+    readonly askId: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The ask has already been closed by a reply. */
+export declare class AskClosed extends AskClosed_base {
+}
+declare const NotYourTurn_base: Schema.Class<NotYourTurn, Schema.TaggedStruct<"NotYourTurn", {
+    readonly askId: Schema.String;
+    readonly turn: Schema.Literals<readonly ["human", "agent"]>;
+}>, import("effect/Cause").YieldableError>;
+/** The move belongs to the other party: a reply while the agent owes an answer, or the reverse. */
+export declare class NotYourTurn extends NotYourTurn_base {
+}
+declare const ReplyInvalid_base: Schema.Class<ReplyInvalid, Schema.TaggedStruct<"ReplyInvalid", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A reply that does not fit the ask it answers. */
+export declare class ReplyInvalid extends ReplyInvalid_base {
+}
+declare const ContentInvalid_base: Schema.Class<ContentInvalid, Schema.TaggedStruct<"ContentInvalid", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Review content that refers to something the space does not hold. */
+export declare class ContentInvalid extends ContentInvalid_base {
+}
+declare const TicketInvalid_base: Schema.Class<TicketInvalid, Schema.TaggedStruct<"TicketInvalid", {}>, import("effect/Cause").YieldableError>;
+/** No event ticket matches: it was never issued, has been used, or has expired. */
+export declare class TicketInvalid extends TicketInvalid_base {
+}
+declare const UploadNotFound_base: Schema.Class<UploadNotFound, Schema.TaggedStruct<"UploadNotFound", {}>, import("effect/Cause").YieldableError>;
+/** No upload, or upload ticket, matches. */
+export declare class UploadNotFound extends UploadNotFound_base {
+}
+declare const UploadExpired_base: Schema.Class<UploadExpired, Schema.TaggedStruct<"UploadExpired", {}>, import("effect/Cause").YieldableError>;
+/** The upload ticket has expired or was already used. */
+export declare class UploadExpired extends UploadExpired_base {
+}
+declare const UploadIncomplete_base: Schema.Class<UploadIncomplete, Schema.TaggedStruct<"UploadIncomplete", {}>, import("effect/Cause").YieldableError>;
+/** The upload's body ended before, or ran past, the length it declared. */
+export declare class UploadIncomplete extends UploadIncomplete_base {
+}
+declare const UploadRejected_base: Schema.Class<UploadRejected, Schema.TaggedStruct<"UploadRejected", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The upload's content type is not the one its ticket was issued for. */
+export declare class UploadRejected extends UploadRejected_base {
+}
+declare const Declined_base: Schema.Class<Declined, Schema.TaggedStruct<"Declined", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The deployment declined to open an ask or an upload, as a host's limits can: the space itself never
+ * declines. The reason is written for the agent, and says what would let it through.
+ */
+export declare class Declined extends Declined_base {
+}
+declare const Unauthorized_base: Schema.Class<Unauthorized, Schema.TaggedStruct<"Unauthorized", {
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The request carries no credentials the gate accepts. */
+export declare class Unauthorized extends Unauthorized_base {
+}
+export {};

package/dist/src/domain/errors.js

@@ -0,0 +1,57 @@
+import { Schema } from "effect";
+/** No ask with this id in the space. */
+export class AskNotFound extends Schema.TaggedError()("AskNotFound", {
+    askId: Schema.String,
+}) {
+}
+/** The ask has already been closed by a reply. */
+export class AskClosed extends Schema.TaggedError()("AskClosed", {
+    askId: Schema.String,
+}) {
+}
+/** The move belongs to the other party: a reply while the agent owes an answer, or the reverse. */
+export class NotYourTurn extends Schema.TaggedError()("NotYourTurn", {
+    askId: Schema.String,
+    turn: Schema.Literals(["human", "agent"]),
+}) {
+}
+/** A reply that does not fit the ask it answers. */
+export class ReplyInvalid extends Schema.TaggedError()("ReplyInvalid", {
+    reason: Schema.String,
+}) {
+}
+/** Review content that refers to something the space does not hold. */
+export class ContentInvalid extends Schema.TaggedError()("ContentInvalid", {
+    reason: Schema.String,
+}) {
+}
+/** No event ticket matches: it was never issued, has been used, or has expired. */
+export class TicketInvalid extends Schema.TaggedError()("TicketInvalid", {}) {
+}
+/** No upload, or upload ticket, matches. */
+export class UploadNotFound extends Schema.TaggedError()("UploadNotFound", {}) {
+}
+/** The upload ticket has expired or was already used. */
+export class UploadExpired extends Schema.TaggedError()("UploadExpired", {}) {
+}
+/** The upload's body ended before, or ran past, the length it declared. */
+export class UploadIncomplete extends Schema.TaggedError()("UploadIncomplete", {}) {
+}
+/** The upload's content type is not the one its ticket was issued for. */
+export class UploadRejected extends Schema.TaggedError()("UploadRejected", {
+    reason: Schema.String,
+}) {
+}
+/**
+ * The deployment declined to open an ask or an upload, as a host's limits can: the space itself never
+ * declines. The reason is written for the agent, and says what would let it through.
+ */
+export class Declined extends Schema.TaggedError()("Declined", {
+    reason: Schema.String,
+}) {
+}
+/** The request carries no credentials the gate accepts. */
+export class Unauthorized extends Schema.TaggedError()("Unauthorized", {
+    reason: Schema.String,
+}) {
+}