@loopbacktools/sdk 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,138 @@
-# Temporary Holding Version
+# @loopbacktools/sdk
 
-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.
+Everything a frontend needs to read and answer what agents ask through Loopback: the REST calls,
+the live event socket with reconnects, and the inbox state kept current from it.
+
+It comes in two forms over one implementation: a promise client for any framework, and an Effect
+service.
+
+```sh
+pnpm add @loopbacktools/sdk
+```
+
+The inbox, [`@loopbacktools/inbox`](https://www.npmjs.com/package/@loopbacktools/inbox), is built only on
+this SDK, so it is a full example to work from, or a set of components to use as they are.
+
+## Promise client
+
+```ts
+import { ApiError, createLoopbackClient } from "@loopbacktools/sdk";
+
+const loopback = createLoopbackClient({
+	baseUrl: "https://loopback.example.workers.dev",
+	token: "…", // or a function returning a fresh one
+});
+
+const { open } = await loopback.snapshot();
+
+try {
+	await loopback.reply(open[0].id, { outcome: "approved", note: "Ship it" });
+} catch (error) {
+	if (error instanceof ApiError) console.log(error.status, error.code, error.message);
+}
+```
+
+Replies are one of:
+
+| `outcome`           | Fields                                  | For                           |
+| ------------------- | --------------------------------------- | ----------------------------- |
+| `answered`          | `selected: string[]`, `text?`           | questions                     |
+| `approved`          | `note?`                                 | reviews                       |
+| `changes_requested` | `feedback`                              | reviews                       |
+| `follow_up`         | `question` — keeps the ask open         | questions, reviews            |
+| `responded`         | `points: { point, text?, resolved? }[]` | briefings                     |
+| `dismissed`         |                                         | questions, reviews, briefings |
+
+A briefing's points, and where each stands, are folded from its prompt and thread by
+`foldBriefing(ask.prompt, ask.thread)`: the tree an inbox renders, the points that need the person,
+and those the agent owes an answer on. `respondedProblem` says why a `responded` reply would be
+refused before it is sent.
+
+`agentSignIn()` says how an agent signs in to the deployment's MCP endpoint, `"oauth"` or `"token"`,
+as the server tells it, for a page that explains connecting one.
+
+`loopback.file(uploadId)` fetches an image a review shows, as a `Blob`.
+
+### The live inbox
+
+`loopback.inbox` is an external store. It connects when its first listener subscribes and
+disconnects after its last one leaves.
+
+```tsx
+import type { Ask } from "@loopbacktools/sdk";
+import { useSyncExternalStore } from "react";
+
+const titleOf = (ask: Ask) => {
+	switch (ask.kind) {
+		case "question":
+			return ask.prompt.question;
+		case "review":
+		case "briefing":
+			return ask.prompt.title;
+		case "unknown":
+			return "Reload to see this ask";
+	}
+};
+
+function Inbox() {
+	const inbox = useSyncExternalStore(loopback.inbox.subscribe, loopback.inbox.getSnapshot);
+	return (
+		<ul>
+			{inbox.open.map((ask) => (
+				<li key={ask.id}>{titleOf(ask)}</li>
+			))}
+		</ul>
+	);
+}
+```
+
+`InboxState` holds `status` (`connecting`, `live` or `reconnecting`), `open` (newest first) and
+`recent` (most recently closed first). `awaitingHuman(state)` picks the asks waiting on the person.
+
+### Updates
+
+`loopback.update` is an external store too, saying whether Loopback has been updated under the page,
+as every response tells the client, the one each socket connection begins with included:
+
+- `none`: the page's code is level with the server's.
+- `available`: a later deploy of the same revision of the contract answers. Offer a reload.
+- `required`: the server writes a later revision of the contract than this client reads, or refused
+  the client as newer than itself, as it does after a rollback. Reload: asks may arrive that this
+  page can't draw, and what it sends may be refused.
+
+It never goes back. Reload when it's safe for the person, such as when the page is hidden, rather
+than under someone typing.
+
+## Effect
+
+```ts
+import { LoopbackClient } from "@loopbacktools/sdk";
+import { Effect, Stream } from "effect";
+
+const program = Effect.gen(function* () {
+	const loopback = yield* LoopbackClient;
+	yield* loopback.inbox.pipe(Stream.runForEach((state) => Effect.log(`${state.open.length} open`)));
+});
+
+program.pipe(
+	Effect.provide(LoopbackClient.layer({ baseUrl: "https://…", token: "…" })),
+	Effect.runFork,
+);
+```
+
+`events` is the raw stream of socket frames, and `applyEvent` is the reducer `inbox` is built on,
+for anyone keeping their own state. `update` is the stream of `Update`s, starting with the current
+one.
+
+## Types
+
+Every type the API speaks (`Ask`, `Reply`, `Block`, `Snapshot`, …) is re-exported, generated from
+the API's TypeSpec definition. The client decodes everything it receives against them rather than
+trusting it, and refuses a body that isn't the contract as an `ApiError` with the code
+`invalid_body`.
+
+A deployment can run a newer revision of the contract than the code that reads it, so each union a
+release can grow ends in an `unknown` member: an `Ask` of kind `unknown`, a `Block` of type
+`unknown`, a `Reply` with the outcome `unknown`. Each keeps what can still be shown and what it was
+(`was`). An exhaustive `switch` has to handle it, and the compiler says so. Socket frames of a type
+the client doesn't know are skipped. What a reply sends is `ReplyBody`.

package/dist/src/client.d.ts

@@ -0,0 +1,77 @@
+import { type Reply as ReplyBody } from "@loopbacktools/protocol";
+import { Ask, AskPage, Snapshot, Whoami } from "@loopbacktools/protocol/schema";
+import { Context, Effect, Layer, Schema, Stream } from "effect";
+import { type InboxEvent, type InboxState } from "./inbox.ts";
+declare const ApiError_base: Schema.Class<ApiError, Schema.TaggedStruct<"ApiError", {
+    readonly status: Schema.Number;
+    readonly code: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A request Loopback refused, or one that never reached it (`status` 0). */
+export declare class ApiError extends ApiError_base {
+}
+export interface LoopbackConfig {
+    /** Where Loopback is served, such as `https://loopback.example.workers.dev`. */
+    readonly baseUrl: string;
+    /**
+     * The credential the deployment's gate accepts, or a function that fetches a fresh one. Leave it
+     * out where something in front of Loopback already signs requests in, as a Worker that vouches
+     * for its callers does: requests then carry no credential of their own.
+     */
+    readonly token?: string | (() => string | Promise<string>);
+    /** A `fetch` to use instead of the global one. */
+    readonly fetch?: typeof globalThis.fetch;
+    /** A `WebSocket` constructor to use instead of the global one. */
+    readonly WebSocket?: typeof globalThis.WebSocket;
+}
+/** The subprotocol the event socket speaks. */
+export declare const EVENTS_PROTOCOL = "loopback.v1";
+/**
+ * The prefix under which the socket offers its one-time ticket, since a browser cannot set headers
+ * there. The token itself only ever travels in `Authorization`, which Cloudflare keeps out of logs.
+ */
+export declare const TICKET_PROTOCOL_PREFIX = "loopback.ticket.";
+/**
+ * Whether Loopback has been updated under this client, so that reloading the page would bring its
+ * code level with the server's. `available` once a later build of the same revision of the contract
+ * answers: a reload is worth offering. `required` once the server writes a later revision than this
+ * client reads, or refuses this client as from a newer one, as it does after a rollback: what it
+ * sends may no longer be read, nor what it hears drawn. It never goes back.
+ */
+export type Update = "none" | "available" | "required";
+export interface LoopbackApi {
+    readonly whoami: Effect.Effect<Whoami, ApiError>;
+    /** Every open ask and the most recently closed. */
+    readonly snapshot: Effect.Effect<Snapshot, ApiError>;
+    readonly ask: (id: string) => Effect.Effect<Ask, ApiError>;
+    /** Closed asks, newest first, before `before` when given. */
+    readonly history: (page?: {
+        readonly before?: string;
+        readonly limit?: number;
+    }) => Effect.Effect<AskPage, ApiError>;
+    readonly reply: (id: string, reply: ReplyBody) => Effect.Effect<Ask, ApiError>;
+    /** An uploaded image, for showing in a review. */
+    readonly file: (uploadId: string) => Effect.Effect<Blob, ApiError>;
+    /**
+     * How an agent signs in to this deployment's MCP endpoint, `/mcp`: with OAuth, as behind a login,
+     * or with the deployment's token. The server says which by serving the endpoint's protected
+     * resource metadata only when it is OAuth.
+     */
+    readonly agentSignIn: Effect.Effect<"oauth" | "token", ApiError>;
+    /** The event socket's frames, reconnecting for as long as the stream runs. */
+    readonly events: Stream.Stream<InboxEvent>;
+    /** The inbox, kept current from `events`: one state per change. */
+    readonly inbox: Stream.Stream<InboxState>;
+    /**
+     * Whether Loopback has been updated under this client, as every response says, the one each
+     * connection of `events` begins with included: the current value, then each change.
+     */
+    readonly update: Stream.Stream<Update>;
+}
+export declare const make: (config: LoopbackConfig) => LoopbackApi;
+declare const LoopbackClient_base: Context.ServiceClass<LoopbackClient, "@loopbacktools/sdk/LoopbackClient", LoopbackApi>;
+/** The Loopback client as an Effect service. */
+export declare class LoopbackClient extends LoopbackClient_base {
+    static readonly layer: (config: LoopbackConfig) => Layer.Layer<LoopbackClient, never, never>;
+}
+export {};

package/dist/src/client.js

@@ -0,0 +1,189 @@
+import { BUILD_HEADER, RELOAD_CODE, REVISION_HEADER, } from "@loopbacktools/protocol";
+import { Ask, AskPage, EventTicket, REVISION, ServerEvent, Snapshot, Whoami, } from "@loopbacktools/protocol/schema";
+import { Context, Deferred, Effect, Exit, Layer, Option, Queue, Schedule, Schema, Stream, SubscriptionRef, } from "effect";
+import { applyEvent, initialInbox } from "./inbox.js";
+/** A request Loopback refused, or one that never reached it (`status` 0). */
+export class ApiError extends Schema.TaggedError()("ApiError", {
+    status: Schema.Number,
+    code: Schema.String,
+    message: Schema.String,
+}) {
+}
+/** The subprotocol the event socket speaks. */
+export const EVENTS_PROTOCOL = "loopback.v1";
+/**
+ * The prefix under which the socket offers its one-time ticket, since a browser cannot set headers
+ * there. The token itself only ever travels in `Authorization`, which Cloudflare keeps out of logs.
+ */
+export const TICKET_PROTOCOL_PREFIX = "loopback.ticket.";
+/** How often the socket sends a keep-alive ping. */
+const PING_MS = 25_000;
+/** Reconnects back off from half a second to ten, with jitter. */
+const RECONNECT = Schedule.min([
+    Schedule.exponential("500 millis"),
+    Schedule.spaced("10 seconds"),
+]).pipe(Schedule.jittered);
+const urgency = { none: 0, available: 1, required: 2 };
+class SocketClosed extends Schema.TaggedError()("SocketClosed", {}) {
+}
+/** A frame as the contract says it is, or none for one that isn't a frame at all. */
+const decodeFrame = Schema.decodeUnknownOption(ServerEvent);
+export const make = (config) => {
+    const base = config.baseUrl.replace(/\/+$/, "");
+    // The globals are looked up per call, so a polyfill or stub installed after this runs is used.
+    const fetcher = config.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    const socketClass = () => config.WebSocket ?? globalThis.WebSocket;
+    const { token: source } = config;
+    const token = Effect.tryPromise({
+        try: async () => (source === undefined || typeof source === "string" ? source : source()),
+        catch: (error) => new ApiError({
+            status: 0,
+            code: "token",
+            message: error instanceof Error ? error.message : String(error),
+        }),
+    });
+    const updates = Effect.runSync(SubscriptionRef.make("none"));
+    const raise = (to) => SubscriptionRef.update(updates, (now) => (urgency[to] > urgency[now] ? to : now));
+    /** The build that answered first, which the page is taken to be from. */
+    let firstBuild;
+    /** What a response says of the code that sent it, measured against this client's. */
+    const heard = (response) => {
+        if (Number(response.headers.get(REVISION_HEADER)) > REVISION)
+            return "required";
+        const build = response.headers.get(BUILD_HEADER);
+        if (build === null)
+            return "none";
+        firstBuild ??= build;
+        return Date.parse(build) > Date.parse(firstBuild) ? "available" : "none";
+    };
+    /** A response body that is not what the contract says it is. */
+    const unreadable = (response) => () => new ApiError({
+        status: response.status,
+        code: "invalid_body",
+        message: `Loopback answered ${response.status} with a body that could not be read.`,
+    });
+    const request = (path, init = {}) => Effect.gen(function* () {
+        const headers = new Headers(init.headers);
+        headers.set(REVISION_HEADER, String(REVISION));
+        const credential = yield* token;
+        if (credential !== undefined)
+            headers.set("Authorization", `Bearer ${credential}`);
+        const response = yield* Effect.tryPromise({
+            try: (signal) => fetcher(`${base}/api/v1${path}`, { ...init, headers, signal }),
+            catch: (error) => new ApiError({
+                status: 0,
+                code: "network",
+                message: error instanceof Error ? error.message : String(error),
+            }),
+        });
+        yield* raise(heard(response));
+        if (response.ok)
+            return response;
+        const problem = yield* Effect.promise(() => response.json().catch(() => ({})));
+        if (response.status === 409 && problem.code === RELOAD_CODE)
+            yield* raise("required");
+        return yield* new ApiError({
+            status: response.status,
+            code: problem.code ?? "unknown",
+            message: problem.message ?? response.statusText,
+        });
+    });
+    /**
+     * A response body, decoded as the contract says it is rather than cast to it. A message from a
+     * newer revision decodes to the `unknown` member of its union; a body that isn't the contract at
+     * all is refused as `invalid_body`.
+     */
+    const read = (schema) => (path, init) => Effect.flatMap(request(path, init), (response) => Effect.tryPromise({
+        try: () => response.json(),
+        catch: unreadable(response),
+    }).pipe(Effect.flatMap((body) => Effect.mapError(Schema.decodeUnknownEffect(schema)(body), unreadable(response)))));
+    /**
+     * One connection: its frames, then a failure when it closes. Only a connection that was live
+     * reports the drop: the retry's backoff starts over whenever the stream emits, so one that never
+     * connected must emit nothing for the next attempt to wait longer.
+     */
+    const connection = Stream.callback((queue) => Effect.gen(function* () {
+        const Socket = socketClass();
+        const { ticket } = yield* Effect.mapError(read(EventTicket)("/events/tickets", { method: "POST" }), () => new SocketClosed());
+        const url = `${base.replace(/^http/, "ws")}/api/v1/events`;
+        const closed = yield* Deferred.make();
+        const socket = yield* Effect.acquireRelease(Effect.try({
+            try: () => new Socket(url, [EVENTS_PROTOCOL, `${TICKET_PROTOCOL_PREFIX}${ticket}`]),
+            catch: () => new SocketClosed(),
+        }), (open) => Effect.sync(() => open.close()));
+        let live = false;
+        socket.addEventListener("message", (message) => {
+            if (typeof message.data !== "string" || message.data === "pong")
+                return;
+            let frame;
+            try {
+                frame = JSON.parse(message.data);
+            }
+            catch {
+                return;
+            }
+            // A frame of a type this client doesn't know, from a newer revision, is skipped.
+            const event = decodeFrame(frame);
+            if (Option.isNone(event) || event.value.type === "unknown")
+                return;
+            live = true;
+            Queue.offerUnsafe(queue, event.value);
+        });
+        const close = () => Deferred.doneUnsafe(closed, Exit.void);
+        socket.addEventListener("close", close);
+        socket.addEventListener("error", close);
+        const ping = setInterval(() => {
+            if (socket.readyState === Socket.OPEN)
+                socket.send("ping");
+        }, PING_MS);
+        yield* Effect.addFinalizer(() => Effect.sync(() => clearInterval(ping)));
+        yield* Deferred.await(closed);
+        if (live)
+            Queue.offerUnsafe(queue, { type: "disconnected" });
+        return yield* new SocketClosed();
+    }));
+    const events = connection.pipe(Stream.retry(RECONNECT), Stream.catch(() => Stream.empty));
+    return {
+        whoami: read(Whoami)("/whoami"),
+        snapshot: read(Snapshot)("/snapshot"),
+        ask: (id) => read(Ask)(`/asks/${encodeURIComponent(id)}`),
+        history: (page = {}) => {
+            const query = new URLSearchParams();
+            if (page.before !== undefined)
+                query.set("before", page.before);
+            if (page.limit !== undefined)
+                query.set("limit", String(page.limit));
+            const search = query.size === 0 ? "" : `?${query}`;
+            return read(AskPage)(`/asks${search}`);
+        },
+        reply: (id, reply) => read(Ask)(`/asks/${encodeURIComponent(id)}/reply`, {
+            method: "POST",
+            body: JSON.stringify(reply),
+            headers: { "Content-Type": "application/json" },
+        }),
+        file: (uploadId) => Effect.flatMap(request(`/files/${encodeURIComponent(uploadId)}`), (response) => Effect.tryPromise({ try: () => response.blob(), catch: unreadable(response) })),
+        agentSignIn: Effect.tryPromise({
+            try: (signal) => fetcher(`${base}/.well-known/oauth-protected-resource/mcp`, { signal }),
+            catch: (error) => new ApiError({
+                status: 0,
+                code: "network",
+                message: error instanceof Error ? error.message : String(error),
+            }),
+        }).pipe(Effect.flatMap((response) => response.ok
+            ? Effect.succeed("oauth")
+            : response.status === 404
+                ? Effect.succeed("token")
+                : Effect.fail(new ApiError({
+                    status: response.status,
+                    code: "unknown",
+                    message: `Loopback answered ${response.status} asked how agents sign in.`,
+                })))),
+        events,
+        inbox: events.pipe(Stream.scan(() => initialInbox, applyEvent)),
+        update: SubscriptionRef.changes(updates).pipe(Stream.changes),
+    };
+};
+/** The Loopback client as an Effect service. */
+export class LoopbackClient extends Context.Service()("@loopbacktools/sdk/LoopbackClient") {
+    static layer = (config) => Layer.succeed(LoopbackClient, make(config));
+}

package/dist/src/inbox.d.ts

@@ -0,0 +1,27 @@
+import type { Ask, ServerEvent, UnknownEvent } from "@loopbacktools/protocol/schema";
+/** How many closed asks the inbox keeps, matching what a snapshot carries. */
+export declare const RECENT_LIMIT = 50;
+/** The inbox as a frontend renders it, kept current from the event socket. */
+export interface InboxState {
+    /**
+     * `connecting` until the first snapshot arrives, `live` while the socket is up, and
+     * `reconnecting` after it drops, until the next snapshot replaces everything.
+     */
+    readonly status: "connecting" | "live" | "reconnecting";
+    /** Open asks, newest first. */
+    readonly open: readonly Ask[];
+    /** Closed asks, most recently closed first. */
+    readonly recent: readonly Ask[];
+}
+/**
+ * What the event stream yields: the server's frames it can read, and the socket dropping. A frame of
+ * a type this client doesn't know is skipped before it gets here.
+ */
+export type InboxEvent = Exclude<ServerEvent, UnknownEvent> | {
+    readonly type: "disconnected";
+};
+export declare const initialInbox: InboxState;
+/** The inbox after one event. Pure, so any frontend can keep its own copy with it. */
+export declare const applyEvent: (state: InboxState, event: InboxEvent) => InboxState;
+/** Open asks waiting on the person rather than on an agent. */
+export declare const awaitingHuman: (state: InboxState) => readonly Ask[];

package/dist/src/inbox.js

@@ -0,0 +1,24 @@
+/** How many closed asks the inbox keeps, matching what a snapshot carries. */
+export const RECENT_LIMIT = 50;
+export const initialInbox = { status: "connecting", open: [], recent: [] };
+const newestFirst = (a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0;
+/** The inbox after one event. Pure, so any frontend can keep its own copy with it. */
+export const applyEvent = (state, event) => {
+    switch (event.type) {
+        case "snapshot":
+            return { status: "live", open: event.snapshot.open, recent: event.snapshot.recent };
+        case "disconnected":
+            return state.status === "connecting" ? state : { ...state, status: "reconnecting" };
+        case "ask.opened":
+        case "ask.updated": {
+            const { ask } = event;
+            const open = state.open.filter((item) => item.id !== ask.id);
+            const recent = state.recent.filter((item) => item.id !== ask.id);
+            return ask.status === "closed"
+                ? { ...state, open, recent: [ask, ...recent].slice(0, RECENT_LIMIT) }
+                : { ...state, open: [...open, ask].toSorted(newestFirst), recent };
+        }
+    }
+};
+/** Open asks waiting on the person rather than on an agent. */
+export const awaitingHuman = (state) => state.open.filter((ask) => ask.status === "awaiting_human");

package/dist/src/index.d.ts

@@ -0,0 +1,7 @@
+export type * from "@loopbacktools/protocol/schema";
+export type { Reply as ReplyBody } from "@loopbacktools/protocol";
+export type { BriefingTree, PointNode, PointState, PointTurn } from "@loopbacktools/protocol";
+export { answerEntries, answersProblem, findPoint, foldBriefing, hasWords, MAX_POINT_DEPTH, MAX_TOP_POINTS, numberBriefing, respondedProblem, } from "@loopbacktools/protocol";
+export { ApiError, EVENTS_PROTOCOL, LoopbackClient, type LoopbackApi, type LoopbackConfig, make, TICKET_PROTOCOL_PREFIX, type Update, } from "./client.ts";
+export { applyEvent, awaitingHuman, type InboxEvent, type InboxState, initialInbox, RECENT_LIMIT, } from "./inbox.ts";
+export { createLoopbackClient, type InboxStore, type LoopbackPromiseClient, type Store, } from "./promise.ts";

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { answerEntries, answersProblem, findPoint, foldBriefing, hasWords, MAX_POINT_DEPTH, MAX_TOP_POINTS, numberBriefing, respondedProblem, } from "@loopbacktools/protocol";
+export { ApiError, EVENTS_PROTOCOL, LoopbackClient, make, TICKET_PROTOCOL_PREFIX, } from "./client.js";
+export { applyEvent, awaitingHuman, initialInbox, RECENT_LIMIT, } from "./inbox.js";
+export { createLoopbackClient, } from "./promise.js";

package/dist/src/promise.d.ts

@@ -0,0 +1,31 @@
+import type { Reply as ReplyBody } from "@loopbacktools/protocol";
+import type { Ask, AskPage, Snapshot, Whoami } from "@loopbacktools/protocol/schema";
+import { type LoopbackConfig, type Update } from "./client.ts";
+import { type InboxState } from "./inbox.ts";
+/** A value kept live as an external store: the shape React's `useSyncExternalStore` takes, and any other framework can. */
+export interface Store<A> {
+    /** Starts following the value with the first listener and stops after the last leaves. */
+    readonly subscribe: (listener: () => void) => () => void;
+    /** The current value. The same object until something changes. */
+    readonly getSnapshot: () => A;
+}
+/** The inbox as an external store. */
+export type InboxStore = Store<InboxState>;
+/** The Loopback client for code that does not use Effect: every call is a promise. */
+export interface LoopbackPromiseClient {
+    readonly whoami: () => Promise<Whoami>;
+    readonly snapshot: () => Promise<Snapshot>;
+    readonly ask: (id: string) => Promise<Ask>;
+    readonly history: (page?: {
+        readonly before?: string;
+        readonly limit?: number;
+    }) => Promise<AskPage>;
+    readonly reply: (id: string, reply: ReplyBody) => Promise<Ask>;
+    readonly file: (uploadId: string) => Promise<Blob>;
+    /** How an agent signs in to this deployment's MCP endpoint: see `LoopbackApi`. */
+    readonly agentSignIn: () => Promise<"oauth" | "token">;
+    readonly inbox: InboxStore;
+    /** Whether Loopback has been updated under this client: see `Update`. */
+    readonly update: Store<Update>;
+}
+export declare const createLoopbackClient: (config: LoopbackConfig) => LoopbackPromiseClient;

package/dist/src/promise.js

@@ -0,0 +1,51 @@
+import { Cause, Effect, Exit, Fiber, Stream } from "effect";
+import { make } from "./client.js";
+import { initialInbox } from "./inbox.js";
+/** Runs a call, rejecting with the `ApiError` itself so callers can match on it. */
+const settle = async (effect) => {
+    const exit = await Effect.runPromiseExit(effect);
+    if (Exit.isSuccess(exit))
+        return exit.value;
+    throw Cause.squash(exit.cause);
+};
+/** A stream followed while anything listens, starting over from `initial` each time it is followed anew. */
+const storeOf = (stream, initial) => {
+    const listeners = new Set();
+    let state = initial;
+    let following;
+    return {
+        subscribe: (listener) => {
+            listeners.add(listener);
+            following ??= Effect.runFork(stream.pipe(Stream.runForEach((next) => Effect.sync(() => {
+                state = next;
+                for (const notify of listeners)
+                    notify();
+            }))));
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0 && following !== undefined) {
+                    Effect.runFork(Fiber.interrupt(following));
+                    following = undefined;
+                    state = initial;
+                }
+            };
+        },
+        getSnapshot: () => state,
+    };
+};
+export const createLoopbackClient = (config) => {
+    const api = make(config);
+    const inbox = storeOf(api.inbox, initialInbox);
+    const update = storeOf(api.update, "none");
+    return {
+        whoami: () => settle(api.whoami),
+        snapshot: () => settle(api.snapshot),
+        ask: (id) => settle(api.ask(id)),
+        history: (page) => settle(api.history(page)),
+        reply: (id, reply) => settle(api.reply(id, reply)),
+        file: (uploadId) => settle(api.file(uploadId)),
+        agentSignIn: () => settle(api.agentSignIn),
+        inbox,
+        update,
+    };
+};

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@loopbacktools/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.1",
+  "description": "A client for Loopback: read and answer what agents ask, and follow the inbox live, from any frontend.",
+  "homepage": "https://github.com/LoopBackTools/loopback/tree/main/packages/sdk#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LoopBackTools/loopback.git",
+    "directory": "packages/sdk"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "effect": "4.0.6",
+    "@loopbacktools/protocol": "0.4.1"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.6",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json"
+  }
 }