open-managed-agents 0.1.0

package/dist/src/control-plane/events/broadcaster.js

@@ -0,0 +1,217 @@
+/**
+ * SessionEventBroadcaster — replay-then-tail fanout over a session's event log.
+ *
+ * On publish: persist via EventStore, then push to any live subscribers on this
+ * session (persist-before-publish, ADR 0007 Pattern 2).
+ *
+ * On subscribe: register a live-event listener BEFORE replaying durable history,
+ * buffer live events while replay runs, dedupe by event ID on drain, then yield
+ * live events until aborted (replay-then-tail, ADR 0007 Pattern 1). Replay is
+ * paginated; live queue is bounded — on overflow we drop the queue and re-drain
+ * from the store via cursor. Mirrors Flue's bounded-buffer + refetch shape.
+ *
+ * Race we're guarding against:
+ *   t0: subscriber arrives with lastSeenId X
+ *   t1: subscriber registers live listener
+ *   t2: a new event Y is published (lands in live queue)
+ *   t3: store.list() reads — may include Y, may not, depending on timing
+ * Without buffering live events during replay and dedup-on-drain, Y is either
+ * delivered twice or not at all.
+ *
+ * Overflow recovery: if the live queue exceeds MAX_BUFFER while the subscriber
+ * is suspended (slow consumer / long replay), we drop the buffer and re-drain
+ * from store starting after the last-yielded ID. This bounds memory usage at
+ * MAX_BUFFER events per subscription regardless of publish rate.
+ */
+const DEFAULT_PAGE_SIZE = 500;
+const DEFAULT_MAX_BUFFER = 10_000;
+export class SessionEventBroadcaster {
+    store;
+    subscribers = new Map();
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Fan out already-persisted events to live subscribers for their sessions.
+     *
+     * IMPORTANT: this method does not persist. Callers that need durability must
+     * persist first (e.g. `appendBatch`) before notifying.
+     */
+    publishPersisted(events) {
+        for (const event of events) {
+            const subs = this.subscribers.get(subscriptionKey(event.workspace_id, event.session_id));
+            if (!subs)
+                continue;
+            for (const sub of subs) {
+                sub.push(event);
+            }
+        }
+    }
+    closeSession(workspaceId, sessionId) {
+        const subs = this.subscribers.get(subscriptionKey(workspaceId, sessionId));
+        if (!subs)
+            return;
+        for (const sub of subs) {
+            sub.close();
+        }
+    }
+    /**
+     * AsyncIterable yielding events for `sessionId` in stable ID order, deduped.
+     * Replays history with `id > lastSeenId` via paginated cursor, then tails
+     * live events until the supplied signal aborts.
+     */
+    async *subscribe(workspaceId, sessionId, opts = {}) {
+        const pageSize = positiveIntegerOrThrow(opts.pageSize ?? DEFAULT_PAGE_SIZE, "pageSize");
+        const maxBuffer = positiveIntegerOrThrow(opts.maxBuffer ?? DEFAULT_MAX_BUFFER, "maxBuffer");
+        const liveQueue = [];
+        let overflowed = false;
+        let closed = false;
+        let wake = null;
+        const wakeSubscriber = () => {
+            if (!wake)
+                return;
+            const w = wake;
+            wake = null;
+            w();
+        };
+        const sub = {
+            push(event) {
+                if (overflowed) {
+                    // Already overflowed; drop. Will recover via store-drain.
+                    return;
+                }
+                liveQueue.push(event);
+                if (liveQueue.length > maxBuffer) {
+                    // Drop the entire buffer; we'll refetch from the store using the
+                    // last-yielded ID as the cursor. This bounds memory at maxBuffer.
+                    overflowed = true;
+                    liveQueue.length = 0;
+                }
+                wakeSubscriber();
+            },
+            close() {
+                closed = true;
+                wakeSubscriber();
+            },
+        };
+        // CRITICAL: register live listener BEFORE replaying. Any event published
+        // during replay lands in liveQueue (or trips overflow); dedup by
+        // `id <= lastYieldedId` handles the overlap.
+        this.addSubscriber(workspaceId, sessionId, sub);
+        const onAbort = () => {
+            wakeSubscriber();
+        };
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+        let lastYieldedId = opts.lastSeenId;
+        const aborted = () => opts.signal?.aborted ?? false;
+        /**
+         * Drain the store from current `lastYieldedId` to end, yielding each event.
+         * Paginated — keeps loading pages until a partial page (or empty) tells us
+         * we've caught up.
+         */
+        const store = this.store;
+        function* drainStore() {
+            while (true) {
+                const page = store.list(workspaceId, sessionId, {
+                    afterId: lastYieldedId,
+                    limit: pageSize,
+                });
+                if (page.length === 0)
+                    return;
+                for (const event of page) {
+                    yield event;
+                }
+                if (page.length < pageSize)
+                    return;
+            }
+        }
+        try {
+            // 1. Initial replay (paginated).
+            for (const event of drainStore()) {
+                if (aborted())
+                    return;
+                lastYieldedId = event.id;
+                yield event;
+            }
+            // 2. Drain live + tail with overflow recovery.
+            while (true) {
+                if (aborted())
+                    return;
+                // Handle overflow: drop buffer, re-drain from store.
+                if (overflowed) {
+                    overflowed = false;
+                    liveQueue.length = 0;
+                    for (const event of drainStore()) {
+                        if (aborted())
+                            return;
+                        // dedup-by-cursor: drainStore already starts after lastYieldedId,
+                        // so every event is new.
+                        lastYieldedId = event.id;
+                        yield event;
+                    }
+                    continue;
+                }
+                // Drain whatever's currently in the live queue.
+                while (liveQueue.length > 0) {
+                    if (aborted())
+                        return;
+                    if (overflowed)
+                        break; // race: overflow happened during this drain
+                    const event = liveQueue.shift();
+                    // Dedup against the cursor — anything we've already yielded has
+                    // id <= lastYieldedId.
+                    if (lastYieldedId !== undefined && event.id <= lastYieldedId) {
+                        continue;
+                    }
+                    lastYieldedId = event.id;
+                    yield event;
+                }
+                if (overflowed)
+                    continue; // re-enter overflow handler
+                if (aborted())
+                    return;
+                if (closed)
+                    return;
+                // Sleep until next event or abort.
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+            }
+        }
+        finally {
+            this.removeSubscriber(workspaceId, sessionId, sub);
+            opts.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    /** For tests/introspection. Not part of the public broadcaster contract. */
+    subscriberCount(sessionId, workspaceId = "wrk_default") {
+        return this.subscribers.get(subscriptionKey(workspaceId, sessionId))?.size ?? 0;
+    }
+    addSubscriber(workspaceId, sessionId, sub) {
+        const key = subscriptionKey(workspaceId, sessionId);
+        let set = this.subscribers.get(key);
+        if (!set) {
+            set = new Set();
+            this.subscribers.set(key, set);
+        }
+        set.add(sub);
+    }
+    removeSubscriber(workspaceId, sessionId, sub) {
+        const key = subscriptionKey(workspaceId, sessionId);
+        const set = this.subscribers.get(key);
+        if (!set)
+            return;
+        set.delete(sub);
+        if (set.size === 0)
+            this.subscribers.delete(key);
+    }
+}
+function subscriptionKey(workspaceId, sessionId) {
+    return JSON.stringify([workspaceId, sessionId]);
+}
+function positiveIntegerOrThrow(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer`);
+    }
+    return value;
+}

package/dist/src/control-plane/events/constants.js

@@ -0,0 +1,2 @@
+export const MAX_EVENTS_PER_REQUEST = 200;
+export const MAX_EVENT_PAYLOAD_BYTES = 64 * 1024;

package/dist/src/control-plane/events/persist.js

@@ -0,0 +1,39 @@
+import { newEventId } from "../../types/events.js";
+import { invalidRequest } from "../errors.js";
+import { MAX_EVENT_PAYLOAD_BYTES } from "./constants.js";
+export function materializePersistedEvents(workspaceId, sessionId, drafts, now) {
+    return drafts.map((draft) => {
+        const payloadJson = JSON.stringify(draft.payload);
+        if (new TextEncoder().encode(payloadJson).byteLength > MAX_EVENT_PAYLOAD_BYTES) {
+            throw invalidRequest(`Serialized event payload exceeds ${MAX_EVENT_PAYLOAD_BYTES} bytes`);
+        }
+        return {
+            id: newEventId(),
+            workspace_id: workspaceId,
+            session_id: sessionId,
+            type: draft.type,
+            processed_at: now,
+            payload: draft.payload,
+            created_at: now,
+        };
+    });
+}
+export function persistAndPublish(store, broadcaster, events) {
+    // Keep persist-then-notify in the same sync tick. Do not `await` between
+    // appendBatch and publishPersisted; that would open a replay gap.
+    store.appendBatch(events);
+    broadcaster.publishPersisted(events);
+}
+export function persistRuntimeChangesAndPublish(store, broadcaster, events, changes) {
+    // Same persist-then-notify invariant as persistAndPublish, with runtime
+    // ledger mutations committed in the same SQLite transaction as the events.
+    store.appendBatchWithRuntimeChanges(events, changes);
+    broadcaster.publishPersisted(events);
+}
+export function persistRuntimeChangesCompleteIdempotencyAndPublish(store, broadcaster, events, changes, completion) {
+    // The idempotency response must commit in the same transaction as the domain
+    // event/runtime writes, or a crash can leave a committed side effect with no
+    // replayable response.
+    store.appendBatchWithRuntimeChangesAndCompleteIdempotency(events, changes, completion);
+    broadcaster.publishPersisted(events);
+}

package/dist/src/control-plane/events/request.js

@@ -0,0 +1,190 @@
+import { isJsonObject, isJsonValue, } from "../../types/json.js";
+import { invalidRequest } from "../errors.js";
+import { MAX_EVENTS_PER_REQUEST } from "./constants.js";
+import { toManagedAgentsEvent } from "./types.js";
+const SUPPORTED_USER_EVENT_TYPES = new Set([
+    "user.message",
+    "user.interrupt",
+    "user.custom_tool_result",
+    "user.tool_confirmation",
+]);
+export function parseSendRequest(input) {
+    const obj = objectInput(input);
+    const value = obj.events;
+    if (!Array.isArray(value)) {
+        throw invalidRequest("`events` must be a non-empty array");
+    }
+    if (value.length === 0) {
+        throw invalidRequest("`events` must be a non-empty array");
+    }
+    if (value.length > MAX_EVENTS_PER_REQUEST) {
+        throw invalidRequest(`\`events\` must contain at most ${MAX_EVENTS_PER_REQUEST} items`);
+    }
+    const events = value.map((item, index) => parseUserEvent(item, index));
+    rejectMixedInterruptAndMessage(events);
+    return { events };
+}
+export function eventPayload(event) {
+    const { type: _type, ...payload } = event;
+    return payload;
+}
+export function toSendResponseEvent(row) {
+    if (!row)
+        throw new Error("Persisted event row missing");
+    const event = toManagedAgentsEvent(row);
+    if (row.type === "user.tool_confirmation") {
+        return { ...event, processed_at: null };
+    }
+    return event;
+}
+export function sameToolConfirmation(completed, event) {
+    return (completed.result === event.result &&
+        (completed.denyMessage ?? null) === (event.deny_message ?? null));
+}
+export function sameCustomToolResult(left, right) {
+    return (left.custom_tool_use_id === right.custom_tool_use_id &&
+        JSON.stringify(left.content ?? null) === JSON.stringify(right.content ?? null) &&
+        (left.is_error ?? false) === (right.is_error ?? false));
+}
+export function sameCustomToolResultPayload(payload, event) {
+    return (payload.custom_tool_use_id === event.custom_tool_use_id &&
+        JSON.stringify(payload.content ?? null) === JSON.stringify(event.content ?? null) &&
+        (payload.is_error ?? false) === (event.is_error ?? false));
+}
+export function hasToolResultForToolUseId(rows, toolUseId) {
+    return rows.some((row) => (row.type === "agent.tool_result" &&
+        row.payload.tool_use_id === toolUseId) ||
+        (row.type === "agent.mcp_tool_result" &&
+            row.payload.mcp_tool_use_id === toolUseId));
+}
+export function lostToolConfirmationPayload(toolUseId) {
+    return {
+        tool_use_id: toolUseId,
+        content: [
+            {
+                type: "text",
+                text: `Tool confirmation ${toolUseId} was accepted, but runtime state is no longer available and the builtin tool execution outcome is unknown.`,
+            },
+        ],
+        is_error: true,
+    };
+}
+export function lostMcpToolConfirmationPayload(toolUseId) {
+    return {
+        mcp_tool_use_id: toolUseId,
+        content: [
+            {
+                type: "text",
+                text: `Tool confirmation ${toolUseId} was accepted, but runtime state is no longer available and the MCP tool execution outcome is unknown.`,
+            },
+        ],
+        is_error: true,
+    };
+}
+export function objectInput(input) {
+    if (!isJsonObject(input)) {
+        throw invalidRequest("Request body must be a JSON object");
+    }
+    return input;
+}
+export function nonEmptyString(value, field) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    throw invalidRequest(`\`${field}\` must be a non-empty string`);
+}
+function rejectMixedInterruptAndMessage(events) {
+    const hasInterrupt = events.some((event) => event.type === "user.interrupt");
+    if (!hasInterrupt)
+        return;
+    const hasMessage = events.some((event) => event.type === "user.message");
+    if (!hasMessage)
+        return;
+    throw invalidRequest("`events` cannot mix user.interrupt and user.message in one request");
+}
+function parseUserEvent(input, index) {
+    const event = objectInput(input);
+    if ("session_id" in event) {
+        throw invalidRequest(`\`events[${index}].session_id\` is not allowed; session ID comes from the URL path`);
+    }
+    const type = nonEmptyString(event.type, `events[${index}].type`);
+    if (!SUPPORTED_USER_EVENT_TYPES.has(type)) {
+        throw invalidRequest(`\`events[${index}].type\` must be one of user.message, user.interrupt, user.custom_tool_result, user.tool_confirmation`);
+    }
+    if (!isJsonValue(event)) {
+        throw invalidRequest(`\`events[${index}]\` must be JSON-compatible`);
+    }
+    if (type === "user.message") {
+        const content = parseContentArray(event.content, `events[${index}].content`);
+        return { type: "user.message", content };
+    }
+    if (type === "user.interrupt") {
+        return { type: "user.interrupt" };
+    }
+    if (type === "user.custom_tool_result") {
+        const customToolUseId = nonEmptyString(event.custom_tool_use_id, `events[${index}].custom_tool_use_id`);
+        const contentValue = event.content;
+        return {
+            type: "user.custom_tool_result",
+            custom_tool_use_id: customToolUseId,
+            ...(contentValue === undefined
+                ? {}
+                : {
+                    content: parseContentArray(contentValue, `events[${index}].content`),
+                }),
+            ...optionalBooleanSpread(event.is_error, `events[${index}].is_error`),
+        };
+    }
+    const toolUseId = nonEmptyString(event.tool_use_id, `events[${index}].tool_use_id`);
+    const result = event.result;
+    if (result !== "allow" && result !== "deny") {
+        throw invalidRequest(`\`events[${index}].result\` must be \`allow\` or \`deny\``);
+    }
+    const denyMessage = event.deny_message;
+    if (result === "allow" && denyMessage !== undefined) {
+        throw invalidRequest(`\`events[${index}].deny_message\` is only valid when result is \`deny\``);
+    }
+    if (result === "deny" &&
+        denyMessage !== undefined &&
+        denyMessage !== null &&
+        typeof denyMessage !== "string") {
+        throw invalidRequest(`\`events[${index}].deny_message\` must be a string or null`);
+    }
+    const normalizedDenyMessage = denyMessage === undefined || denyMessage === null || typeof denyMessage === "string"
+        ? denyMessage
+        : undefined;
+    return {
+        type: "user.tool_confirmation",
+        tool_use_id: toolUseId,
+        result,
+        ...(normalizedDenyMessage === undefined
+            ? {}
+            : { deny_message: normalizedDenyMessage }),
+    };
+}
+function parseContentArray(input, field) {
+    if (!Array.isArray(input) || input.length === 0) {
+        throw invalidRequest(`\`${field}\` must be a non-empty array`);
+    }
+    return input.map((block, index) => parseContentBlock(block, `${field}[${index}]`));
+}
+function parseContentBlock(input, field) {
+    const block = objectInput(input);
+    if (!isJsonValue(block)) {
+        throw invalidRequest(`\`${field}\` must be JSON-compatible`);
+    }
+    const type = nonEmptyString(block.type, `${field}.type`);
+    if (type === "text") {
+        return {
+            type,
+            text: nonEmptyString(block.text, `${field}.text`),
+        };
+    }
+    return block;
+}
+function optionalBooleanSpread(value, field) {
+    if (value === undefined)
+        return {};
+    if (typeof value === "boolean")
+        return { is_error: value };
+    throw invalidRequest(`\`${field}\` must be a boolean`);
+}

package/dist/src/control-plane/events/routes.js

@@ -0,0 +1,159 @@
+import { Hono } from "hono";
+import { parseJsonBody, parseLimit, parseOrder } from "../http.js";
+import { invalidRequest } from "../errors.js";
+import { requestFingerprint, validateIdempotencyKey, } from "../request-idempotency.js";
+import { workspaceIdFrom } from "../workspace.js";
+import { sseEventFrame } from "./sse.js";
+export function sessionEventsRoutes(service, admission) {
+    const app = new Hono();
+    app.post("/", async (c) => {
+        const sessionId = requiredSessionId(c.req.param("sessionId"));
+        const idempotencyKey = c.req.header("idempotency-key");
+        if (idempotencyKey !== undefined) {
+            const rawBody = new Uint8Array(await c.req.raw.arrayBuffer());
+            const body = parseJsonBytes(rawBody);
+            const method = c.req.method.toUpperCase();
+            const concretePath = new URL(c.req.url).pathname;
+            const response = service.sendIdempotent(workspaceIdFrom(c), sessionId, body, {
+                method,
+                concretePath,
+                key: validateIdempotencyKey(idempotencyKey),
+                routeLabel: "POST /v1/sessions/{session_id}/events",
+                fingerprintSha256: requestFingerprint(method, concretePath, rawBody),
+            }, {
+                signal: c.req.raw.signal,
+                requestId: c.get("requestId"),
+            });
+            return jsonResponse(response.body, response.status, c.get("requestId"), response.headers);
+        }
+        const body = await parseJsonBody(c.req);
+        return c.json({
+            data: service.send(workspaceIdFrom(c), sessionId, body, {
+                signal: c.req.raw.signal,
+            }),
+        }, 200);
+    });
+    app.get("/", (c) => {
+        const sessionId = requiredSessionId(c.req.param("sessionId"));
+        const limit = parseLimit(c.req.query("limit"));
+        const page = parsePage(c.req.query("page"));
+        const order = parseOrder(c.req.query("order"));
+        const types = parseTypesQuery(c.req.url);
+        return c.json(service.list(workspaceIdFrom(c), sessionId, {
+            ...(limit === undefined ? {} : { limit }),
+            ...(page === undefined ? {} : { page }),
+            ...(order === undefined ? {} : { order }),
+            ...(types.length === 0 ? {} : { types }),
+        }), 200);
+    });
+    app.get("/stream", (c) => {
+        const sessionId = requiredSessionId(c.req.param("sessionId"));
+        rejectUnsupportedEventDeltas(c.req.url);
+        // 0113 D9: the stream's cost is its lifetime (a bounded live queue per
+        // subscription), so the slot is held until the stream closes.
+        const releaseStream = admission?.sseStreams.acquire(workspaceIdFrom(c));
+        const abortController = new AbortController();
+        c.req.raw.signal.addEventListener("abort", () => abortController.abort(), {
+            once: true,
+        });
+        let events;
+        try {
+            events = service.stream(workspaceIdFrom(c), sessionId, {
+                lastEventId: c.req.header("last-event-id"),
+                signal: abortController.signal,
+            });
+        }
+        catch (error) {
+            releaseStream?.();
+            throw error;
+        }
+        const requestId = c.get("requestId");
+        return new Response(toSseBody(events, abortController, releaseStream), {
+            status: 200,
+            headers: {
+                "content-type": "text/event-stream",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+                "request-id": requestId,
+            },
+        });
+    });
+    return app;
+}
+function requiredSessionId(value) {
+    if (value === undefined || value.length === 0) {
+        throw invalidRequest("Session ID path parameter is required");
+    }
+    return value;
+}
+function parseJsonBytes(bytes) {
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch (error) {
+        throw invalidRequest("Request body must be valid JSON", String(error));
+    }
+}
+function jsonResponse(body, status, requestId, extraHeaders = {}) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            "content-type": "application/json",
+            "request-id": requestId,
+            ...extraHeaders,
+        },
+    });
+}
+function parsePage(value) {
+    if (value === undefined || value.length === 0)
+        return undefined;
+    if (!value.startsWith("sevt_")) {
+        throw invalidRequest("`page` must be a valid event cursor");
+    }
+    return value;
+}
+function parseTypesQuery(url) {
+    const params = new URL(url).searchParams;
+    const values = params.getAll("types[]");
+    return values.filter((value) => value.length > 0);
+}
+function rejectUnsupportedEventDeltas(url) {
+    if (new URL(url).searchParams.has("event_deltas[]")) {
+        throw invalidRequest("`event_deltas[]` is not supported; OMA streams complete persisted events and emits buffered `agent.message` text");
+    }
+}
+function toSseBody(events, abortController, onClose) {
+    const encoder = new TextEncoder();
+    const iterator = events[Symbol.asyncIterator]();
+    return new ReadableStream({
+        // Demand-gated on purpose: pull() runs only when the consumer has drained
+        // the stream's internal queue, so a slow/stalled client suspends the
+        // broadcaster iterator and its bounded live-queue overflow→refetch
+        // protection holds. An eager start() loop here drains the broadcaster
+        // into unbounded response/socket buffering (#127). A rejected pull()
+        // errors the stream, matching the previous controller.error() path.
+        async pull(controller) {
+            let next;
+            try {
+                next = await iterator.next();
+            }
+            catch (error) {
+                onClose?.();
+                throw error;
+            }
+            if (next.done) {
+                onClose?.();
+                controller.close();
+                return;
+            }
+            controller.enqueue(encoder.encode(sseEventFrame(next.value)));
+        },
+        async cancel() {
+            onClose?.();
+            abortController.abort();
+            if (typeof iterator.return === "function") {
+                await iterator.return();
+            }
+        },
+    });
+}