@rikalabs/akter 0.1.0-alpha.0

package/dist/serve/mcp/endpoint.d.ts

@@ -0,0 +1,39 @@
+import { Effect, Schema } from "effect";
+import { Headers, HttpServerResponse } from "effect/http";
+import type { McpTool } from "./tools.ts";
+/** The MCP revision this endpoint speaks. */
+export declare const MCP_VERSION = "2026-07-28";
+/** What a tool call runs with, after its arguments passed the tool's own parameters. */
+export interface ToolCall {
+    readonly tool: McpTool;
+    readonly id: string | undefined;
+    readonly commandId: string | undefined;
+    readonly input: Schema.Json | undefined;
+}
+/** A tool call's outcome as the same JSON its HTTP route answers: the value on success, an error body otherwise. */
+export type ToolResult = {
+    readonly ok: true;
+    readonly value: Schema.Json | undefined;
+} | {
+    readonly ok: false;
+    readonly body: Schema.Json;
+};
+interface McpEndpoint {
+    readonly tools: ReadonlyArray<McpTool>;
+    readonly info: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly call: (call: ToolCall) => Effect.Effect<ToolResult>;
+}
+/**
+ * Answers one MCP request over Streamable HTTP for the caller the endpoint's
+ * route already authenticated. The revision is stateless: every request names
+ * its protocol version, so there is no handshake, session, or stream, and a
+ * tool call is one HTTP response. A notification is accepted and ignored.
+ */
+export declare const handleMcp: (endpoint: McpEndpoint, request: {
+    readonly headers: Headers.Headers;
+    readonly body: Uint8Array;
+}) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>;
+export {};

package/dist/serve/mcp/endpoint.js

@@ -0,0 +1,187 @@
+import { Effect, Option, Result, Schema } from "effect";
+import { Base64 } from "effect/encoding";
+import { Headers, HttpServerResponse } from "effect/http";
+import { ActorError, InvalidInput } from "../../errors/actor.js";
+import { actorErrorBody } from "../../protocol/wire.js";
+import { invalidInput, undecodable } from "../wire.js";
+/** The MCP revision this endpoint speaks. */
+export const MCP_VERSION = "2026-07-28";
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const HEADER_MISMATCH = -32020;
+const UNSUPPORTED_VERSION = -32022;
+const VERSION_META = "io.modelcontextprotocol/protocolVersion";
+const CAPABILITIES_META = "io.modelcontextprotocol/clientCapabilities";
+const SERVER_INFO_META = "io.modelcontextprotocol/serverInfo";
+const BASE64_SENTINEL = /^=\?base64\?(.*)\?=$/;
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true });
+const Message = Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    id: Schema.optionalKey(Schema.Union([Schema.String, Schema.Finite])),
+    method: Schema.String,
+    params: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
+});
+const Params = Schema.Struct({
+    _meta: Schema.Struct({
+        [VERSION_META]: Schema.String,
+        [CAPABILITIES_META]: Schema.Record(Schema.String, Schema.Json),
+    }),
+});
+const ListParams = Schema.Struct({ cursor: Schema.optionalKey(Schema.String) });
+const CallParams = Schema.Struct({
+    name: Schema.String,
+    arguments: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
+});
+const Arguments = Schema.Struct({
+    id: Schema.optionalKey(Schema.String),
+    commandId: Schema.optionalKey(Schema.String),
+    input: Schema.optionalKey(Schema.Json),
+});
+const decodeText = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Json));
+const decodeMessage = Schema.decodeUnknownEffect(Message);
+const decodeParams = Schema.decodeUnknownEffect(Params);
+const decodeListParams = Schema.decodeUnknownEffect(ListParams);
+const decodeCallParams = Schema.decodeUnknownEffect(CallParams);
+const decodeArguments = Schema.decodeUnknownEffect(Arguments);
+const rpcFailure = (failure) => HttpServerResponse.jsonUnsafe({
+    jsonrpc: "2.0",
+    id: failure.id ?? null,
+    error: { code: failure.code, message: failure.message, data: failure.data },
+}, { status: failure.status });
+const rpcResult = (id, result) => HttpServerResponse.jsonUnsafe({ jsonrpc: "2.0", id, result });
+const mismatch = (id, message) => rpcFailure({ id, status: 400, code: HEADER_MISMATCH, message: `Header mismatch: ${message}` });
+const invalidParams = (id, message) => rpcFailure({ id, status: 400, code: INVALID_PARAMS, message });
+const argumentError = (path, message) => ActorError.make({ reason: InvalidInput.make({ code: "decode", issues: [{ path, message }] }) });
+/** The value a header carries, decoded when a client sent it in the Base64 sentinel form. */
+const headerValue = (value) => {
+    const encoded = BASE64_SENTINEL.exec(value)?.[1];
+    if (encoded === undefined)
+        return Option.some(value);
+    return Result.match(Base64.decodeString(encoded), {
+        onFailure: () => Option.none(),
+        onSuccess: Option.some,
+    });
+};
+/**
+ * Checks a call's arguments against the parameters its tool advertises, in
+ * the order the HTTP route checks its own: a command without a command id is
+ * `missing_command_id`, and every other fault names the argument.
+ */
+const toolCall = Effect.fnUntraced(function* (tool, args) {
+    const allowed = new Set();
+    if (tool.takesId)
+        allowed.add("id");
+    if (tool.takesCommandId)
+        allowed.add("commandId");
+    if (tool.input !== "none")
+        allowed.add("input");
+    const unexpected = Object.keys(args).find((key) => !allowed.has(key));
+    if (unexpected !== undefined)
+        return yield* argumentError(unexpected, "Unexpected key");
+    const { id, commandId, input } = yield* decodeArguments(args).pipe(Effect.mapError((error) => undecodable(error)));
+    if (tool.takesId && id === undefined)
+        return yield* argumentError("id", "Missing key");
+    if (tool.takesCommandId && commandId === undefined)
+        return yield* invalidInput("missing_command_id");
+    if (tool.input === "required" && input === undefined)
+        return yield* argumentError("input", "Missing key");
+    return { tool, id, commandId, input };
+});
+const toolResult = (tool, result, _meta) => {
+    if (!result.ok)
+        return {
+            resultType: "complete",
+            content: [{ type: "text", text: JSON.stringify(result.body) }],
+            isError: true,
+            _meta,
+        };
+    if (result.value === undefined)
+        return { resultType: "complete", content: [], _meta };
+    const content = [{ type: "text", text: JSON.stringify(result.value) }];
+    return tool.structured
+        ? { resultType: "complete", content, structuredContent: result.value, _meta }
+        : { resultType: "complete", content, _meta };
+};
+/**
+ * Answers one MCP request over Streamable HTTP for the caller the endpoint's
+ * route already authenticated. The revision is stateless: every request names
+ * its protocol version, so there is no handshake, session, or stream, and a
+ * tool call is one HTTP response. A notification is accepted and ignored.
+ */
+export const handleMcp = Effect.fnUntraced(function* (endpoint, request) {
+    const json = yield* Effect.try(() => strictUtf8.decode(request.body)).pipe(Effect.flatMap(decodeText), Effect.option);
+    if (Option.isNone(json))
+        return rpcFailure({ id: undefined, status: 400, code: PARSE_ERROR, message: "Parse error" });
+    const parsed = yield* decodeMessage(json.value).pipe(Effect.option);
+    if (Option.isNone(parsed))
+        return rpcFailure({
+            id: undefined,
+            status: 400,
+            code: INVALID_REQUEST,
+            message: "Invalid request",
+        });
+    const message = parsed.value;
+    const id = message.id;
+    if (id === undefined)
+        return HttpServerResponse.empty({ status: 202 });
+    const meta = yield* decodeParams(message.params ?? {}).pipe(Effect.option);
+    if (Option.isNone(meta))
+        return invalidParams(id, `Missing ${VERSION_META} or ${CAPABILITIES_META} in _meta`);
+    const requested = meta.value._meta[VERSION_META];
+    const versionHeader = Headers.get(request.headers, "mcp-protocol-version");
+    if (Option.isNone(versionHeader))
+        return mismatch(id, "MCP-Protocol-Version is required");
+    if (versionHeader.value.trim() !== requested)
+        return mismatch(id, "MCP-Protocol-Version does not match the request's protocol version");
+    if (requested !== MCP_VERSION)
+        return rpcFailure({
+            id,
+            status: 400,
+            code: UNSUPPORTED_VERSION,
+            message: "Unsupported protocol version",
+            data: { supported: [MCP_VERSION], requested },
+        });
+    const methodHeader = Headers.get(request.headers, "mcp-method");
+    if (Option.isNone(methodHeader) || methodHeader.value !== message.method)
+        return mismatch(id, "Mcp-Method does not match the request's method");
+    const serverInfo = { [SERVER_INFO_META]: endpoint.info };
+    if (message.method === "server/discover")
+        return rpcResult(id, {
+            resultType: "complete",
+            supportedVersions: [MCP_VERSION],
+            capabilities: { tools: {} },
+            ttlMs: 0,
+            cacheScope: "public",
+            _meta: serverInfo,
+        });
+    if (message.method === "tools/list") {
+        const list = yield* decodeListParams(message.params ?? {}).pipe(Effect.option);
+        if (Option.isNone(list) || list.value.cursor !== undefined)
+            return invalidParams(id, "Invalid params");
+        return rpcResult(id, {
+            resultType: "complete",
+            tools: endpoint.tools.map((tool) => tool.descriptor),
+            ttlMs: 0,
+            cacheScope: "public",
+            _meta: serverInfo,
+        });
+    }
+    if (message.method !== "tools/call")
+        return rpcFailure({ id, status: 404, code: METHOD_NOT_FOUND, message: "Method not found" });
+    const params = yield* decodeCallParams(message.params ?? {}).pipe(Effect.option);
+    if (Option.isNone(params))
+        return invalidParams(id, "Invalid params");
+    const nameHeader = Option.flatMap(Headers.get(request.headers, "mcp-name"), headerValue);
+    if (Option.isNone(nameHeader) || nameHeader.value !== params.value.name)
+        return mismatch(id, "Mcp-Name does not match the request's tool name");
+    const tool = endpoint.tools.find((candidate) => candidate.name === params.value.name);
+    if (tool === undefined)
+        return invalidParams(id, `Unknown tool: ${params.value.name}`);
+    const call = yield* toolCall(tool, params.value.arguments ?? {}).pipe(Effect.result);
+    const result = Result.isFailure(call)
+        ? { ok: false, body: yield* actorErrorBody(call.failure) }
+        : yield* endpoint.call(call.success);
+    return rpcResult(id, toolResult(tool, result, serverInfo));
+});

package/dist/serve/mcp/tools.d.ts

@@ -0,0 +1,37 @@
+import { Effect, Schema } from "effect";
+import type { ServedDefinition, ServedMember } from "../../actor/served.ts";
+/** What a tool call's `input` argument carries. */
+type ToolInput = "none" | "optional" | "required";
+/** The served member a tool runs. */
+interface ToolRoute {
+    readonly definition: ServedDefinition;
+    readonly member: ServedMember;
+}
+/** One MCP tool with the arguments its OpenAPI operation takes. */
+export interface McpTool {
+    readonly name: string;
+    /** The tool as `tools/list` describes it. */
+    readonly descriptor: Schema.JsonObject;
+    /** Whether the tool declares an output schema, so its result carries structured content. */
+    readonly structured: boolean;
+    /** The member the tool runs; absent for the tool that mints command ids. */
+    readonly route: ToolRoute | undefined;
+    /** Whether the call names the actor, which every operation with an `{id}` path parameter needs. */
+    readonly takesId: boolean;
+    /** Whether the call carries a command id, which every operation with an `Idempotency-Key` header needs. */
+    readonly takesCommandId: boolean;
+    readonly input: ToolInput;
+}
+/**
+ * The MCP tools of a served OpenAPI document: one per public command,
+ * reducer, and query, and one that mints command ids. Each tool takes exactly
+ * the parameters and body its operation takes, and its schemas are that
+ * operation's, so the two protocols cannot describe a member differently.
+ * Internal members have no operation and so no tool.
+ */
+export declare const mcpTools: (options: {
+    readonly document: unknown;
+    readonly basePath: string;
+    readonly definitions: ReadonlyArray<ServedDefinition>;
+}) => Effect.Effect<McpTool[], never, never>;
+export {};

package/dist/serve/mcp/tools.js

@@ -0,0 +1,125 @@
+import { Effect, Schema } from "effect";
+import { memberPath, MINT_OPERATION } from "../api.js";
+const JsonObject = Schema.Record(Schema.String, Schema.Json);
+const Content = Schema.Struct({
+    "application/json": Schema.optionalKey(Schema.Struct({ schema: JsonObject })),
+});
+const Operation = Schema.Struct({
+    parameters: Schema.optionalKey(Schema.Array(Schema.Struct({
+        name: Schema.String,
+        in: Schema.String,
+        schema: Schema.optionalKey(Schema.Struct({ description: Schema.optionalKey(Schema.String) })),
+    }))),
+    requestBody: Schema.optionalKey(Schema.Struct({ required: Schema.optionalKey(Schema.Boolean), content: Content })),
+    responses: Schema.Struct({
+        "200": Schema.optionalKey(Schema.Struct({ content: Schema.optionalKey(Content) })),
+    }),
+});
+/** The parts of a served OpenAPI document that tools are derived from. */
+const Document = Schema.Struct({
+    paths: Schema.Record(Schema.String, Schema.Struct({ post: Schema.optionalKey(Operation) })),
+    components: Schema.Struct({ schemas: Schema.Record(Schema.String, JsonObject) }),
+});
+const decodeDocument = Schema.decodeUnknownEffect(Document);
+const decodeObject = Schema.decodeUnknownEffect(Schema.fromJsonString(JsonObject));
+const encodeText = Schema.encodeEffect(Schema.fromJsonString(Schema.Json));
+const COMMAND_ID_PARAMETER = "idempotency-key";
+const REFERENCE = /"\$ref":"#\/components\/schemas\/([^"]+)"/g;
+const REFERENCE_TARGET = '"$ref":"#/$defs/$1"';
+/**
+ * A schema a tool can carry alone. A tool list has no document for a `$ref`
+ * to resolve against, so the components a schema references, and the ones
+ * those reference, move into its `$defs`. A reference is a `$ref` property
+ * whose value is a whole string, so scanning the serialized schema finds them
+ * all.
+ */
+const standalone = Effect.fnUntraced(function* (schema, components) {
+    const names = [];
+    const pending = [yield* encodeText(schema)];
+    for (let index = 0; index < pending.length; index += 1)
+        for (const [, name = ""] of pending[index].matchAll(REFERENCE)) {
+            if (names.includes(name))
+                continue;
+            names.push(name);
+            pending.push(yield* encodeText(components[name]));
+        }
+    const defs = Object.fromEntries(names.map((name) => [name, components[name]]));
+    const carried = names.length === 0 ? schema : Object.assign({}, schema, { $defs: defs });
+    const text = yield* encodeText(carried);
+    return yield* decodeObject(text.replaceAll(REFERENCE, REFERENCE_TARGET));
+}, Effect.orDie);
+const toolDescription = (name, kind) => kind === "query"
+    ? `Reads ${name}. It takes no command id and is safe to retry.`
+    : `Runs ${name} once per commandId. Retrying with the same commandId and input returns the stored result without running it again; the same commandId with different input is refused, and an expired commandId is never replaced.`;
+const MINT_DESCRIPTION = "Mints a command id. Send it with a command call and reuse it, with the same input, on every retry of that call; a new id is a new operation.";
+const ID_DESCRIPTION = "The actor's id: the key the served route takes as its `{id}` path segment.";
+/**
+ * The MCP tools of a served OpenAPI document: one per public command,
+ * reducer, and query, and one that mints command ids. Each tool takes exactly
+ * the parameters and body its operation takes, and its schemas are that
+ * operation's, so the two protocols cannot describe a member differently.
+ * Internal members have no operation and so no tool.
+ */
+export const mcpTools = Effect.fnUntraced(function* (options) {
+    const { paths, components } = yield* decodeDocument(options.document).pipe(Effect.orDie);
+    const derive = Effect.fnUntraced(function* (path, route) {
+        const operation = paths[path]?.post;
+        if (operation === undefined)
+            return yield* Effect.die(new Error(`Actor.serve: the OpenAPI document has no POST operation at ${path}`));
+        const parameters = operation.parameters ?? [];
+        const takesId = parameters.some((parameter) => parameter.in === "path" && parameter.name === "id");
+        const commandId = parameters.find((parameter) => parameter.in === "header" && parameter.name === COMMAND_ID_PARAMETER);
+        const body = operation.requestBody?.content["application/json"]?.schema;
+        const output = operation.responses["200"]?.content?.["application/json"]?.schema;
+        const input = body === undefined
+            ? "none"
+            : operation.requestBody?.required === true
+                ? "required"
+                : "optional";
+        const properties = {};
+        const required = [];
+        if (takesId) {
+            properties["id"] = { type: "string", description: ID_DESCRIPTION };
+            required.push("id");
+        }
+        if (commandId !== undefined) {
+            properties["commandId"] = {
+                type: "string",
+                description: commandId.schema?.description ?? "The command id.",
+            };
+            required.push("commandId");
+        }
+        if (body !== undefined)
+            properties["input"] = body;
+        if (input === "required")
+            required.push("input");
+        const name = route === undefined ? MINT_OPERATION : `${route.definition.name}.${route.member.tag}`;
+        const isQuery = route?.member.kind === "query";
+        const base = {
+            name,
+            description: route === undefined ? MINT_DESCRIPTION : toolDescription(name, route.member.kind),
+            inputSchema: yield* standalone({ type: "object", properties, required, additionalProperties: false }, components.schemas),
+            annotations: { readOnlyHint: isQuery, idempotentHint: route !== undefined },
+        };
+        const descriptor = output === undefined
+            ? base
+            : Object.assign({}, base, { outputSchema: yield* standalone(output, components.schemas) });
+        const tool = {
+            name,
+            descriptor,
+            structured: output !== undefined,
+            route,
+            takesId,
+            takesCommandId: commandId !== undefined,
+            input,
+        };
+        return tool;
+    });
+    const tools = [yield* derive(`${options.basePath}/command-ids`, undefined)];
+    for (const definition of options.definitions)
+        for (const member of definition.members) {
+            const path = `${options.basePath}${memberPath({ definition, member })}`;
+            tools.push(yield* derive(path.replace(":id", "{id}"), { definition, member }));
+        }
+    return tools;
+});

package/dist/serve/origin.d.ts

@@ -0,0 +1,6 @@
+import { type HttpServerRequest } from "effect/http";
+/** Same origin means the transport's scheme and the Host header, not forwarded headers. */
+export declare const isSameOrigin: ({ request, origin, }: {
+    readonly request: HttpServerRequest.HttpServerRequest;
+    readonly origin: string;
+}) => boolean;

package/dist/serve/origin.js

@@ -0,0 +1,21 @@
+import { Option, Schema } from "effect";
+import { Headers } from "effect/http";
+const NodeSource = Schema.is(Schema.Struct({
+    socket: Schema.Struct({ encrypted: Schema.optionalKey(Schema.Boolean) }),
+}));
+/** The transport's scheme, never a client's forwarded-protocol assertion. */
+const scheme = (request) => {
+    if (NodeSource(request.source))
+        return request.source.socket.encrypted === true ? "https:" : "http:";
+    if (URL.canParse(request.originalUrl))
+        return new URL(request.originalUrl).protocol;
+    return undefined;
+};
+/** Same origin means the transport's scheme and the Host header, not forwarded headers. */
+export const isSameOrigin = ({ request, origin, }) => {
+    const host = Headers.get(request.headers, "host");
+    if (Option.isNone(host) || !URL.canParse(origin))
+        return false;
+    const parsed = new URL(origin);
+    return parsed.host === host.value && parsed.protocol === scheme(request);
+};

package/dist/serve/sessions/feed.d.ts

@@ -0,0 +1,79 @@
+import { Effect, Stream } from "effect";
+import type { ActorError } from "../../errors/actor.ts";
+import { RetentionGap, UnknownCursor } from "../../errors/events.ts";
+import type { InternalActors } from "../../runtime/actors.ts";
+import type { ActorRef, Caller } from "../../identity/caller.ts";
+import type { HeldConnection } from "../../runtime/connections/holder.ts";
+/** At most this many `event` filters per feed. */
+export declare const MAX_FEED_FILTERS = 16;
+/** The JSON body a cursor error is served as, before a stream starts or as a feed's last message. */
+export declare const cursorErrorBody: (error: UnknownCursor | RetentionGap) => Effect.Effect<{
+    readonly _tag: "UnknownCursor";
+    readonly cursor: string;
+} | {
+    readonly _tag: "RetentionGap";
+    readonly cursor: string;
+}, never, never>;
+/** What a feed reads and who reads it. */
+interface FeedOptions {
+    readonly actors: InternalActors["Service"];
+    /** The actor whose committed events the feed serves. */
+    readonly ref: ActorRef;
+    /** The event tags the feed serves; the holder authorizes each one. */
+    readonly tags: ReadonlyArray<string>;
+    readonly caller: Caller;
+    /** The credential's expiry in epoch milliseconds, which ends the feed. */
+    readonly expiresAt: number | undefined;
+}
+/**
+ * Opens a feed at this runner's holder: the framework feed member, authorized
+ * per event tag, whose row makes the owner broadcast every committed feed
+ * event. The actor must already exist; a feed never creates one.
+ */
+export declare const openFeed: (options: FeedOptions) => Effect.Effect<{
+    connectionId: string;
+    cursor: string;
+    messages: Stream.Stream<{
+        readonly _tag: "Frame";
+        readonly frame: string;
+        readonly cursor?: string | undefined;
+        readonly event?: string | undefined;
+    } | {
+        readonly _tag: "Progress";
+        readonly job: string;
+        readonly jobId: string;
+        readonly attempt: number;
+        readonly seq: number;
+        readonly frame: string;
+    } | {
+        readonly _tag: "Resync";
+        readonly after: string | undefined;
+        readonly reason: "OwnerLost";
+        readonly deadlineMs: number;
+    } | {
+        readonly _tag: "ResyncReplayed";
+    }, ActorError, never>;
+    send: (frame: string) => Effect.Effect<void, ActorError, never>;
+    resyncDone: Effect.Effect<void, never, never>;
+    authorized: Effect.Effect<boolean, never, never>;
+    writable: Effect.Effect<void, never, never>;
+    reauthenticate: (expiresAt: number | undefined) => Effect.Effect<undefined, ActorError, never>;
+    close: Effect.Effect<void, never, never>;
+}, ActorError, never>;
+/**
+ * The events of a feed after `after`, as SSE text: first the committed events
+ * read from `actor_events`, then live ones from the holder, deduplicated by
+ * cursor so the race between the two neither loses nor repeats one. After an
+ * owner loss, a gap, or a full buffer, the feed rereads from the last cursor
+ * it sent instead of ending, so a client sees one gap-free stream; any other
+ * end is its last message. The `actor_events` table is the source of truth: the
+ * holder resyncs a feed itself, and once the new owner answers the feed rereads
+ * and goes on. A feed lists no job, so the owner never sends it progress.
+ */
+export declare const feedStream: ({ options, first, after, }: {
+    readonly options: FeedOptions;
+    /** The feed the caller opened before its first read, so no commit falls between them. */
+    readonly first: HeldConnection;
+    readonly after: string | undefined;
+}) => Stream.Stream<Uint8Array<ArrayBufferLike>, never, never>;
+export {};

package/dist/serve/sessions/feed.js

@@ -0,0 +1,115 @@
+import { Effect, Match, Option, Predicate, Queue, Schema, Stream } from "effect";
+import { RetentionGap, UnknownCursor } from "../../errors/events.js";
+import { FEED_MEMBER, FeedFrame } from "../../runtime/connections/protocol.js";
+import { actorErrorBody } from "../../protocol/wire.js";
+import { message, withKeepalive } from "./sse.js";
+/** Events a feed reads from `actor_events` per statement. */
+const FEED_PAGE = 256;
+/** At most this many `event` filters per feed. */
+export const MAX_FEED_FILTERS = 16;
+const decodeFeedFrame = Schema.decodeEffect(Schema.fromJsonString(FeedFrame));
+const decodeStored = Schema.decodeEffect(Schema.fromJsonString(Schema.Json));
+const encodeCursorError = Schema.encodeEffect(Schema.Union([UnknownCursor, RetentionGap]));
+/** The JSON body a cursor error is served as, before a stream starts or as a feed's last message. */
+export const cursorErrorBody = (error) => encodeCursorError(error).pipe(Effect.orDie);
+/** One feed event as its SSE message's `data` carries it. */
+const FeedData = Schema.Struct({
+    event: Schema.Json,
+    commandId: Schema.String,
+    timestamp: Schema.Finite,
+});
+const encodeData = Schema.encodeEffect(FeedData);
+/**
+ * An SSE message: one event named by its tag and identified by its cursor, so
+ * `Last-Event-ID` resumes after it.
+ */
+const eventMessage = (event) => Effect.gen(function* () {
+    const data = yield* encodeData({
+        event: yield* decodeStored(event.value),
+        commandId: event.commandId,
+        timestamp: event.timestampMs,
+    });
+    return yield* message({ event: event.tag, data, id: event.cursor });
+}).pipe(Effect.orDie);
+/**
+ * The feed's last message: the error that ended it, as a served response body
+ * would carry it. It has no `id` line, so it introduces no cursor: a reader
+ * tells it from an event named `end`, which always carries a new one.
+ */
+const endMessage = (error) => Effect.gen(function* () {
+    const body = Predicate.isTagged(error, "ActorError")
+        ? yield* actorErrorBody(error)
+        : yield* cursorErrorBody(error);
+    return yield* message({ event: "end", data: body });
+});
+/** Ends that a feed survives by reopening at its holder and rereading from its cursor. */
+const recoverable = (error) => Predicate.isTagged(error.reason, "SessionEnded") &&
+    ["SlowConsumer", "OwnerLost", "ActorUnavailable"].includes(error.reason.cause);
+/**
+ * Opens a feed at this runner's holder: the framework feed member, authorized
+ * per event tag, whose row makes the owner broadcast every committed feed
+ * event. The actor must already exist; a feed never creates one.
+ */
+export const openFeed = (options) => options.actors.holder
+    .open({
+    ref: options.ref,
+    member: FEED_MEMBER,
+    caller: options.caller,
+    params: "",
+    expiresAt: options.expiresAt,
+    feed: options.tags,
+})
+    .pipe(Effect.catchTag("OpenRejected", () => Effect.die(new Error("A feed has no open handler"))));
+/**
+ * The events of a feed after `after`, as SSE text: first the committed events
+ * read from `actor_events`, then live ones from the holder, deduplicated by
+ * cursor so the race between the two neither loses nor repeats one. After an
+ * owner loss, a gap, or a full buffer, the feed rereads from the last cursor
+ * it sent instead of ending, so a client sees one gap-free stream; any other
+ * end is its last message. The `actor_events` table is the source of truth: the
+ * holder resyncs a feed itself, and once the new owner answers the feed rereads
+ * and goes on. A feed lists no job, so the owner never sends it progress.
+ */
+export const feedStream = ({ options, first, after, }) => Stream.callback((out) => Effect.gen(function* () {
+    const wanted = new Set(options.tags);
+    let last = BigInt(after ?? "0");
+    let held = first;
+    yield* Effect.addFinalizer(() => held.close);
+    const emit = (event) => Effect.gen(function* () {
+        if (BigInt(event.cursor) <= last)
+            return;
+        last = BigInt(event.cursor);
+        yield* Queue.offer(out, yield* eventMessage(event));
+    });
+    const catchUp = Effect.gen(function* () {
+        while (true) {
+            const page = yield* options.actors.readFeed(options.ref, options.tags, String(last), FEED_PAGE);
+            for (const event of page)
+                yield* emit(event);
+            if (page.length < FEED_PAGE)
+                return;
+        }
+    });
+    const live = (connection) => connection.messages.pipe(Stream.runForEach((item) => Match.value(item).pipe(Match.tagsExhaustive({
+        Frame: (frame) => frame.event === undefined
+            ? Effect.void
+            : decodeFeedFrame(frame.frame).pipe(Effect.orDie, Effect.flatMap((decoded) => wanted.has(decoded.tag)
+                ? emit({ ...decoded, cursor: frame.event })
+                : Effect.void)),
+        Resync: () => Effect.void,
+        ResyncReplayed: () => catchUp.pipe(Effect.andThen(connection.resyncDone)),
+        Progress: () => Effect.void,
+    }))));
+    const run = Effect.gen(function* () {
+        while (true) {
+            yield* catchUp;
+            const ended = yield* live(held).pipe(Effect.flip, Effect.option);
+            if (Option.isNone(ended))
+                return;
+            if (!Predicate.isTagged(ended.value, "ActorError") || !recoverable(ended.value))
+                return yield* ended.value;
+            held = yield* openFeed(options);
+        }
+    });
+    yield* run.pipe(Effect.catch((error) => endMessage(error).pipe(Effect.flatMap((text) => Queue.offer(out, text)))), Effect.andThen(Queue.end(out)), Effect.forkScoped);
+})).pipe(withKeepalive);