@fungi.computer/shiitake 0.8.0 → 0.9.0

package/README.md

@@ -22,6 +22,34 @@ To add your own behaviour, start the extension guide at
 We don't take VC money. Fungi is built in the open and proudly backed by its
 community.
 
+## Observe a Session
+
+`session.watch()` returns an owner-atomic snapshot and live `changes`; close the
+watch when the consumer leaves. `session.subscribe({ after })` replays strictly
+after an opaque Woodstock cursor, then joins the same per-Session live feed.
+Woodstock remains the only durable history owner.
+
+Watchers share one projection producer and encoded frame per Session. Each
+watcher can retain at most 256 frames or 1 MiB of encoded UTF-8, whichever comes
+first. Overflow drops that backlog and delivers one `reset` with a fresh
+snapshot, even if no later write arrives. There are at most 64 live watchers per
+Agent; closing one releases its capacity. Closing the last watcher stops the
+Session's producer and heartbeat.
+
+The byte limit also applies to a single frame: an encoded frame over 1 MiB
+cannot enter even an empty watcher queue. Every watcher whose frame exceeds that
+limit resets, including an otherwise fast watcher. This is a per-watcher check,
+not a reset of other Sessions or of watchers whose filtered frame and backlog
+fit. The fresh Woodstock baseline is the recovery path; silently exceeding the
+queue bound or adding a second chunked wire protocol is not.
+
+A typed `{ kind: "heartbeat" }` arrives every 15 seconds. It is not durable and
+never carries or advances a cursor. Durable rows deduplicate by owner sequence;
+message progress uses message identity and revision, not the durable cursor. The
+HTTP client treats 45 seconds without a delivered event as an unavailable,
+possibly busy feed. Silence does not prove the service stopped: Local clients
+must check the service owner's database lease before claiming that.
+
 ## Recover an uncertain send
 
 Both local and HTTP Sessions expose

package/dist/client-wire.js

@@ -164,6 +164,7 @@ export const SessionSnapshotSchema = Schema.Struct({
     context: Schema.optionalKey(SessionContextSchema),
 });
 export const SessionFrameSchema = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("heartbeat") }),
     Schema.Struct({
         kind: Schema.Literal("activity"),
         activity: SessionActivitySchema,

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import type { SessionAttention } from "./session-attention.js";
+export { sessionHeartbeatIntervalMs, sessionSilenceDeadlineMs, } from "./session-liveness.js";
 import type { CommandSettlement } from "./internal/contracts.js";
 export type { CommandSettlement } from "./internal/contracts.js";
 export { type SessionAttention } from "./session-attention.js";
@@ -342,6 +343,9 @@ export type SessionSnapshot = Readonly<{
 }>;
 /** One bounded replay or live frame. */
 export type SessionFrame = Readonly<{
+    /** Process-local liveness only: never a durable cursor or activity fact. */
+    kind: "heartbeat";
+}> | Readonly<{
     /** Process-local activity change for the Session's current queue head. */
     kind: "activity";
     activity: SessionActivity;

package/dist/client.js

@@ -1,3 +1,4 @@
+export { sessionHeartbeatIntervalMs, sessionSilenceDeadlineMs, } from "./session-liveness.js";
 export {} from "./session-attention.js";
 export { createShiitakeClient, } from "./remote-client.js";
 export { bindAgentExtension, bindSessionExtension, } from "./extension-client.js";

package/dist/delegation.d.ts

@@ -103,11 +103,11 @@ export declare function agentMailRoute(namespace: PostRoute<never, never>["names
     };
 } | {
     readonly key: string;
+    readonly content: string;
     readonly reply: {
         readonly outcome: "undeliverable";
         readonly reason: "recipient_offline";
     };
-    readonly content: string;
     readonly to: {
         readonly agentId: string;
         readonly kind: "agent";
@@ -162,11 +162,11 @@ export declare function agentMailRoute(namespace: PostRoute<never, never>["names
     };
 } | {
     readonly key: string;
+    readonly content: string;
     readonly reply: {
         readonly outcome: "undeliverable";
         readonly reason: "recipient_offline";
     };
-    readonly content: string;
     readonly to: {
         readonly agentId: string;
         readonly kind: "agent";
@@ -221,11 +221,11 @@ export declare function agentMailRoute(namespace: PostRoute<never, never>["names
     };
 } | {
     readonly key: string;
+    readonly content: string;
     readonly reply: {
         readonly outcome: "undeliverable";
         readonly reason: "recipient_offline";
     };
-    readonly content: string;
     readonly to: {
         readonly agentId: string;
         readonly kind: "agent";
@@ -280,11 +280,11 @@ export declare function agentMailRoute(namespace: PostRoute<never, never>["names
     };
 } | {
     readonly key: string;
+    readonly content: string;
     readonly reply: {
         readonly outcome: "undeliverable";
         readonly reason: "recipient_offline";
     };
-    readonly content: string;
     readonly to: {
         readonly agentId: string;
         readonly kind: "agent";

package/dist/http-routes.d.ts

@@ -513,7 +513,6 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
                 readonly content: string;
                 readonly usage: readonly {
                     model: string;
-                    provider: import("@fungi.computer/mule/effect").ProviderId;
                     usage: {
                         input: number;
                         output: number;
@@ -530,6 +529,7 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
                             total: number;
                         };
                     };
+                    provider: import("@fungi.computer/mule/effect").ProviderId;
                 }[];
                 readonly toolCalls: number;
                 readonly waitingOnYou: readonly {
@@ -711,7 +711,7 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
                     } | {
                         toolCallId: string;
                         role: "toolResult";
-                        timestamp: number;
+                        toolName: string;
                         content: ({
                             type: "text";
                             text: string;
@@ -721,7 +721,6 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
                             data: string;
                             mimeType: string;
                         })[];
-                        toolName: string;
                         usage?: {
                             input: number;
                             output: number;
@@ -753,6 +752,7 @@ export declare function createShiitakeHttpRoutes(resolveSession: ShiitakeSession
                             complete: boolean;
                         } | undefined;
                         isError: boolean;
+                        timestamp: number;
                         durationMs?: number | undefined;
                     };
                 }[];

package/dist/http-routes.js

@@ -4,6 +4,7 @@ import { Hono } from "hono";
 import { streamSSE, } from "hono/streaming";
 import { validator } from "hono/validator";
 import * as Schema from "effect/Schema";
+import { encodeSessionFrame } from "./internal/observation-kernel.js";
 import { ShiitakeError, toShiitakeErrorWire } from "./errors.js";
 import { JsonValueSchema } from "./internal/json-value.js";
 import { decodeClientIdentity, decodeClientEventsQuery, decodeClientReadQuery, decodeClientSettlementQuery, decodeClientSessionCommandRequest, decodeClientSessionCreationRequest, decodeClientPageCursor, decodeClientSessionId, } from "./internal/client-boundary.js";
@@ -84,7 +85,7 @@ function frameEvent(frame) {
         : frame.kind === "reset"
             ? (frame.cursor ?? "")
             : undefined;
-    const event = { event: "frame", data: JSON.stringify(frame) };
+    const event = { event: "frame", data: encodeSessionFrame(frame).data };
     return id === undefined ? event : { ...event, id };
 }
 async function writeSessionEvents(stream, session, request) {

package/dist/internal/coordinator.d.ts

@@ -1,13 +1,14 @@
 import type { BirdDogMail } from "@fungi.computer/bird-dog";
 import type { VerifiedAgentReply } from "./woodstock/index.js";
 import * as Effect from "effect/Effect";
+import type * as Context from "effect/Context";
 import { ShiitakeError } from "../errors.js";
 import type { Json } from "../extensions.js";
 import type { ShiitakeEffectOwner, ShiitakeEffectOptions } from "./effect-contracts.js";
 import type { RuntimeCoordinator } from "./runtime-coordinator.js";
 import { type GrantsDelivery } from "./woodstock/index.js";
 /** Construct the Effect-native coordinator over the private owner modules. */
-export declare function openCoordinator(options: ShiitakeEffectOptions, runtime: RuntimeCoordinator): ShiitakeEffectOwner;
+export declare function openCoordinator(options: ShiitakeEffectOptions, runtime: RuntimeCoordinator, ownerContext: Context.Context<never>): ShiitakeEffectOwner;
 /**
  * Accept one addressed mail envelope; the door decodes it as a prompt. `reply`
  * is the host's authentication of a delegated Agent's reply; only then does

package/dist/internal/coordinator.js

@@ -4,14 +4,12 @@ import { acceptedNotice } from "@fungi.computer/bird-dog/effect";
 import { FungiMessageMetaSchema } from "@fungi.computer/agar/agents";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import * as Stream from "effect/Stream";
 import { ShiitakeError } from "../errors.js";
-import { decodeClientReadOptions, decodeClientSettlementRequest, requireDecoded, decodeClientSessionCommand, decodeClientSessionId, decodeClientSubscribeOptions, } from "./client-boundary.js";
-import { mergeObservationSignals, openObservationKernel, publishAgentExecutionChange, publishOwnerObservation, } from "./observation-kernel.js";
+import { decodeClientSettlementRequest, requireDecoded, decodeClientSessionCommand, decodeClientSessionId, } from "./client-boundary.js";
+import { openObservationKernel, publishAgentExecutionChange, publishOwnerObservation, } from "./observation-kernel.js";
+import { openSessionObservation } from "./session-observation.js";
 import { checkHostMeta } from "./host-meta.js";
-import { readSessionActivity, } from "./session-status.js";
-import { prepareSessionContext } from "./session-context.js";
-import { progressPosition, readProcessProgressDelta, abortSession, cancelSession, branchSession, recordOperatorLine, forkSession, readSession, readCommandSettlement, readSessionModelPreference, readSessionReplayPage, readSessionInbox, readLatestPendingPrompt, createSession, deleteSession, deliverSessionGrants, readSessionGrants, setSessionModelPreference, setSessionTitle, readAdmissionIdentity, assertAdmissionIdentity, } from "./woodstock/index.js";
+import { abortSession, cancelSession, branchSession, recordOperatorLine, forkSession, readCommandSettlement, readSessionModelPreference, readSessionInbox, readLatestPendingPrompt, createSession, deleteSession, deliverSessionGrants, readSessionGrants, setSessionModelPreference, setSessionTitle, readAdmissionIdentity, assertAdmissionIdentity, } from "./woodstock/index.js";
 /** Generic Agent-scope extension controls over the runtime's one call door. */
 function agentExtensions(runtime) {
     return Object.freeze({
@@ -20,29 +18,6 @@ function agentExtensions(runtime) {
         call: (extensionId, command, input) => runtime.assertOpen.pipe(Effect.andThen(runtime.extensions.call({ scope: "agent" }, extensionId, command, input))),
     });
 }
-function currentSessionWork(runtime, sessionId) {
-    return runtime
-        .readQueueHead(sessionId)
-        .pipe(Effect.flatMap((head) => (head.state === "queued"
-        ? runtime.runningWork(head.jobId)
-        : Effect.succeed(null)).pipe(Effect.map((runningWork) => ({ head, runningWork })))));
-}
-function currentSessionActivity(options, runtime, sessionId) {
-    return currentSessionWork(runtime, sessionId).pipe(Effect.map(({ head, runningWork }) => readSessionActivity(options.store, sessionId, head, runningWork)));
-}
-/** Carry the Session's context use on a baseline, when it has one. */
-function withContext(snapshot, context) {
-    return context === undefined
-        ? snapshot
-        : Object.freeze({ ...snapshot, context });
-}
-/** Read the baseline and its context use for one Session. */
-function readSessionWithContext(options, runtime, sessionId, input) {
-    return currentSessionWork(runtime, sessionId).pipe(Effect.flatMap(({ head, runningWork }) => readSession(options.store, sessionId, () => readSessionActivity(options.store, sessionId, head, runningWork), input, () => runtime.extensions.project(sessionId), (snapshot) => ({
-        snapshot,
-        context: prepareSessionContext(options, sessionId, snapshot.cursor, input?.before === undefined),
-    }))), Effect.flatMap(({ snapshot, context }) => context.pipe(Effect.map((value) => withContext(snapshot, value)))));
-}
 function sessionOwnerOperation(runtime, sessionId, operation) {
     return runtime.assertOpen.pipe(Effect.andThen(Effect.try({
         try: () => operation(decodeClientSessionId(sessionId)),
@@ -67,190 +42,6 @@ function decodeSessionCommand(sessionId, input) {
             : new ShiitakeError("contract", "invalid", "Session command is invalid"),
     });
 }
-function decodeSubscriptionInput(sessionId, input) {
-    return Effect.try({
-        try: () => Object.freeze({
-            sessionId: decodeClientSessionId(sessionId),
-            options: decodeClientSubscribeOptions(input),
-        }),
-        catch: (error) => error instanceof ShiitakeError
-            ? error
-            : new ShiitakeError("contract", "invalid", "Subscribe options are invalid"),
-    });
-}
-function resetFrame(options, runtime, sessionId, includeSandboxFailures = false) {
-    return runtime.assertOpen.pipe(Effect.andThen(readSessionWithContext(options, runtime, sessionId, {
-        includeSandboxFailures,
-    })), Effect.map((baseline) => Object.freeze({
-        kind: "reset",
-        reason: "history_unavailable",
-        cursor: baseline.cursor,
-        baseline,
-    })));
-}
-function continueFromReset(frame) {
-    return [
-        [frame],
-        Option.some({
-            after: frame.cursor ?? undefined,
-            delivery: frame.baseline.hasMore ? "replay" : "live",
-            awaitSignal: !frame.baseline.hasMore,
-        }),
-    ];
-}
-function subscriptionFrames(options, runtime, registration, sessionId, after, delivery, includeSandboxFailures = false, baselineProgress = null) {
-    let position = progressPosition(baselineProgress);
-    let toolOutput = [];
-    const reset = () => resetFrame(options, runtime, sessionId, includeSandboxFailures).pipe(Effect.map((frame) => {
-        position = progressPosition(frame.baseline.progress);
-        toolOutput = frame.baseline.toolOutput;
-        return continueFromReset(frame);
-    }));
-    const liveFrames = (activity) => {
-        const queue = activity.facts.queue;
-        const delta = queue.state !== "running"
-            ? null
-            : readProcessProgressDelta(options.store, sessionId, queue.commandId, position);
-        if (delta === undefined)
-            return undefined;
-        const frames = [];
-        if (delta !== null) {
-            frames.push({
-                kind: "progress",
-                progress: delta,
-                activity: activity.facts,
-            });
-            position = {
-                messageId: delta.messageId,
-                revision: delta.revision,
-                text: delta.text.offset + delta.text.append.length,
-                thinking: delta.thinking.offset + delta.thinking.append.length,
-            };
-        }
-        if (toolOutput.length !== activity.toolOutput.length ||
-            toolOutput.some((slot, index) => slot !== activity.toolOutput[index])) {
-            toolOutput = activity.toolOutput;
-            frames.push({
-                kind: "tool_output",
-                toolOutput,
-                activity: activity.facts,
-            });
-        }
-        return frames;
-    };
-    const initial = {
-        after,
-        delivery,
-        awaitSignal: false,
-    };
-    return Stream.paginate(initial, (state) => (state.awaitSignal
-        ? registration.awaitSignal.pipe(Effect.flatMap((signal) => registration.pollSignal.pipe(Effect.map((pending) => pending === undefined
-            ? signal
-            : mergeObservationSignals(signal, pending)))))
-        : registration.pollSignal).pipe(Effect.flatMap((signal) => {
-        if (signal === "closed")
-            return Effect.succeed([[], Option.none()]);
-        if (signal === "reset")
-            return reset();
-        return runtime.assertOpen.pipe(Effect.andThen(currentSessionActivity(options, runtime, sessionId)), Effect.flatMap((activity) => {
-            registration.setQueued(activity.facts.queue.state === "queued");
-            if ((signal === "progress" || signal === "activity") &&
-                state.delivery === "live") {
-                const frames = liveFrames(activity);
-                if (frames === undefined)
-                    return reset();
-                return Effect.succeed([
-                    [
-                        ...(signal === "activity"
-                            ? [
-                                {
-                                    kind: "activity",
-                                    activity: activity.facts,
-                                },
-                            ]
-                            : []),
-                        ...frames,
-                    ],
-                    Option.some({ ...state, awaitSignal: true }),
-                ]);
-            }
-            return readSessionReplayPage(options.store, sessionId, state.after, state.delivery, activity, () => runtime.extensions.project(sessionId), includeSandboxFailures, (page) => {
-                const latestCursor = page.kind === "page"
-                    ? page.frames
-                        .flatMap((frame) => frame.kind === "progress" ||
-                        frame.kind === "activity" ||
-                        frame.kind === "tool_output"
-                        ? []
-                        : [frame.cursor])
-                        .at(-1)
-                    : undefined;
-                // Prepare a figure only for the final moving update,
-                // while its cursor and stored context share the read.
-                const context = page.kind === "page" &&
-                    !page.hasMore &&
-                    page.frames.some((frame) => frame.kind === "update" &&
-                        frame.cursor !== state.after)
-                    ? prepareSessionContext(options, sessionId, latestCursor ?? null)
-                    : Effect.succeed(undefined);
-                return { page, latestCursor, context };
-            }).pipe(Effect.flatMap(({ page, latestCursor, context, }) => {
-                if (page.kind === "reset")
-                    return reset();
-                if (!page.hasMore)
-                    toolOutput = activity.toolOutput;
-                const progressFrames = page.hasMore
-                    ? []
-                    : liveFrames(activity);
-                if (progressFrames === undefined)
-                    return reset();
-                const next = {
-                    after: latestCursor ?? state.after,
-                    delivery: page.hasMore ? state.delivery : "live",
-                    awaitSignal: !page.hasMore,
-                };
-                return context.pipe(Effect.map((context) => [
-                    [
-                        ...(context === undefined
-                            ? page.frames
-                            : page.frames.map((frame) => frame.kind === "update" &&
-                                frame.cursor === latestCursor
-                                ? Object.freeze({ ...frame, context })
-                                : frame)),
-                        ...progressFrames,
-                    ],
-                    Option.some(next),
-                ]));
-            }));
-        }));
-    })));
-}
-function subscribeSession(options, runtime, observation, sessionId, input) {
-    return Stream.unwrap(runtime.assertOpen.pipe(Effect.andThen(decodeSubscriptionInput(sessionId, input)), Effect.flatMap((decoded) => Effect.acquireRelease(observation.register(decoded.sessionId), (registration) => Effect.sync(registration.close)).pipe(Effect.map((registration) => subscriptionFrames(options, runtime, registration, decoded.sessionId, decoded.options.after, "replay", decoded.options.includeSandboxFailures === true))))));
-}
-function decodeWatchInput(sessionId, input) {
-    return Effect.try({
-        try: () => Object.freeze({
-            sessionId: decodeClientSessionId(sessionId),
-            options: decodeClientReadOptions(input),
-        }),
-        catch: (error) => error instanceof ShiitakeError
-            ? error
-            : new ShiitakeError("contract", "invalid", "Watch options are invalid"),
-    });
-}
-function watchSession(options, runtime, observation, sessionId, input) {
-    return runtime.assertOpen.pipe(Effect.andThen(decodeWatchInput(sessionId, input)), Effect.flatMap((decoded) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
-        const registration = yield* observation.register(decoded.sessionId);
-        return yield* restore(runtime.assertOpen.pipe(Effect.andThen(readSessionWithContext(options, runtime, decoded.sessionId, decoded.options)), Effect.map((snapshot) => {
-            registration.setQueued(snapshot.activity.queue.state === "queued");
-            return Object.freeze({
-                snapshot,
-                changes: subscriptionFrames(options, runtime, registration, decoded.sessionId, snapshot.cursor ?? undefined, "live", decoded.options.includeSandboxFailures === true, snapshot.progress).pipe(Stream.ensuring(Effect.sync(registration.close))),
-                close: Effect.sync(registration.close),
-            });
-        }))).pipe(Effect.onError(() => Effect.sync(registration.close)));
-    }))));
-}
 /**
  * Admit one user prompt, mail prompt or compaction request through the
  * accepted-command door.
@@ -359,8 +150,9 @@ function checkCommandMeta(options, meta) {
     });
 }
 /** Construct the Effect-native coordinator over the private owner modules. */
-export function openCoordinator(options, runtime) {
+export function openCoordinator(options, runtime, ownerContext) {
     const observation = openObservationKernel(options.store);
+    const sessionObservation = openSessionObservation(options, runtime, observation, ownerContext);
     /** One Session handle; `meta` is the host metadata its prompts carry. */
     const sessionFor = (sessionId, meta) => {
         function command(input) {
@@ -407,7 +199,7 @@ export function openCoordinator(options, runtime) {
             extension: (extensionId) => Object.freeze({
                 call: (command, input, caller) => runtime.assertOpen.pipe(Effect.andThen(runtime.extensions.call({ scope: "session", sessionId }, extensionId, command, input, caller))),
             }),
-            read: (input) => runtime.assertOpen.pipe(Effect.andThen(readSessionWithContext(options, runtime, sessionId, input))),
+            read: (input) => runtime.assertOpen.pipe(Effect.andThen(sessionObservation.read(sessionId, input))),
             readSettlement: (commandId, timeoutMs = 0) => Effect.scoped(Effect.gen(function* () {
                 yield* runtime.assertOpen;
                 const decoded = yield* Effect.try({
@@ -437,8 +229,8 @@ export function openCoordinator(options, runtime) {
                     }
                 }).pipe(Effect.timeoutOption(decoded.timeoutMs), Effect.map(Option.getOrUndefined));
             })),
-            subscribe: (input) => subscribeSession(options, runtime, observation, sessionId, input),
-            watch: (input) => watchSession(options, runtime, observation, sessionId, input),
+            subscribe: (input) => sessionObservation.subscribe(sessionId, input),
+            watch: (input) => sessionObservation.watch(sessionId, input),
         });
     };
     const agent = Object.freeze({
@@ -450,7 +242,7 @@ export function openCoordinator(options, runtime) {
         listSessions: (after) => runtime.assertOpen.pipe(Effect.andThen(readSessionInbox(options.store, after))),
         extensions: agentExtensions(runtime),
         session: (sessionId) => sessionFor(sessionId, undefined),
-        close: runtime.beginClose.pipe(Effect.andThen(observation.close)),
+        close: runtime.beginClose.pipe(Effect.andThen(sessionObservation.close), Effect.andThen(observation.close)),
     });
     return Object.freeze({
         ...agent,

package/dist/internal/observation-kernel.d.ts

@@ -1,6 +1,25 @@
 import * as Effect from "effect/Effect";
+import type { SessionFrame } from "../client.js";
 import { ShiitakeError } from "../errors.js";
 import type { SqliteOwner } from "./contracts.js";
+/** The feed shares one frame's JSON and byte accounting across its watchers. */
+export declare function encodeSessionFrame(frame: SessionFrame): Readonly<{
+    data: string;
+    bytes: number;
+}>;
+/** One watcher has its own bounded backlog, not its own projection producer. */
+export type SessionFrameQueue = Readonly<{
+    take: Effect.Effect<SessionFrame | "reset" | "closed", ShiitakeError>;
+    /** Record the join before reading; retain later frames for cursor deduplication. */
+    checkpoint: (revision?: number) => void;
+    close: () => void;
+}>;
+/** Bounded dropping fan-out; Woodstock, never this queue, owns replay. */
+export declare function openSessionFrameFeed(onIdle: () => void): {
+    register(includeSandboxFailures?: boolean): SessionFrameQueue;
+    publish(frame: SessionFrame, revision?: number): void;
+    end(error?: ShiitakeError): void;
+};
 /** Finite process-local signal; durable owner state remains authoritative. */
 export type ObservationSignal = "closed" | "reset" | "durable" | "activity" | "progress";
 export type ObservationReason = "durable" | "activity" | "progress" | "settlement";
@@ -8,6 +27,8 @@ export type ObservationReason = "durable" | "activity" | "progress" | "settlemen
 export declare function hasOwnerObservers(store: SqliteOwner, sessionId: string): boolean;
 /** One scoped process-local observation registration. */
 export type ObservationRegistration = Readonly<{
+    /** Owner-hint revision for the snapshot/live join, never a wire cursor. */
+    revision: number;
     /** Inspect and consume one pending finite signal without waiting. */
     pollSignal: Effect.Effect<ObservationSignal | undefined>;
     /** Await and consume one finite observation signal. */

package/dist/internal/observation-kernel.js

@@ -1,8 +1,128 @@
 import * as Effect from "effect/Effect";
+import * as Pull from "effect/Pull";
+import * as Queue from "effect/Queue";
 import { ShiitakeError } from "../errors.js";
 import { reportCatchFailure } from "./failure.js";
 const MAX_OBSERVATIONS = 64;
 const MAX_PENDING_HINTS = 256;
+const encodedFrames = new WeakMap();
+const frameEncoder = new TextEncoder();
+/** The feed shares one frame's JSON and byte accounting across its watchers. */
+export function encodeSessionFrame(frame) {
+    const cached = encodedFrames.get(frame);
+    if (cached !== undefined)
+        return cached;
+    const data = JSON.stringify(frame);
+    const encoded = Object.freeze({
+        data,
+        bytes: frameEncoder.encode(data).byteLength,
+    });
+    encodedFrames.set(frame, encoded);
+    return encoded;
+}
+function withoutSandboxFailures(frame) {
+    if (frame.kind === "update" && frame.sandboxFailures !== undefined) {
+        const value = { ...frame };
+        delete value.sandboxFailures;
+        return value;
+    }
+    if (frame.kind === "reset" && frame.baseline.sandboxFailures !== undefined) {
+        const baseline = { ...frame.baseline };
+        delete baseline.sandboxFailures;
+        return { ...frame, baseline };
+    }
+    return frame;
+}
+/** Bounded dropping fan-out; Woodstock, never this queue, owns replay. */
+export function openSessionFrameFeed(onIdle) {
+    const listeners = new Set();
+    let ended = false;
+    let failure;
+    const clear = (listener) => {
+        Effect.runSync(Queue.clear(listener.frames));
+        listener.bytes = 0;
+    };
+    return {
+        register(includeSandboxFailures = false) {
+            const listener = {
+                frames: Effect.runSync(Queue.dropping(256)),
+                bytes: 0,
+                lagged: false,
+                closed: false,
+                observed: -1,
+                includeSandboxFailures,
+            };
+            listeners.add(listener);
+            const take = Effect.suspend(() => {
+                if (listener.closed)
+                    return Effect.succeed("closed");
+                if (failure !== undefined)
+                    return Effect.fail(failure);
+                if (listener.lagged)
+                    return Effect.succeed("reset");
+                if (ended)
+                    return Effect.succeed("closed");
+                return Queue.take(listener.frames).pipe(Pull.catchDone(() => Effect.succeed("closed")), Effect.flatMap((frame) => {
+                    if (failure !== undefined)
+                        return Effect.fail(failure);
+                    if (frame !== "reset" && frame !== "closed")
+                        listener.bytes -= encodeSessionFrame(frame).bytes;
+                    return Effect.succeed(frame);
+                }));
+            });
+            return Object.freeze({
+                take,
+                checkpoint: (revision = -1) => {
+                    clear(listener);
+                    listener.lagged = false;
+                    listener.observed = revision;
+                },
+                close: () => {
+                    if (listener.closed)
+                        return;
+                    listener.closed = true;
+                    clear(listener);
+                    listeners.delete(listener);
+                    Queue.endUnsafe(listener.frames);
+                    if (listeners.size === 0)
+                        onIdle();
+                },
+            });
+        },
+        publish(frame, revision = Infinity) {
+            if (ended)
+                return;
+            const publicFrame = withoutSandboxFailures(frame);
+            for (const listener of listeners) {
+                if (listener.closed || listener.lagged || revision <= listener.observed)
+                    continue;
+                const value = listener.includeSandboxFailures ? frame : publicFrame;
+                const { bytes } = encodeSessionFrame(value);
+                if (listener.bytes + bytes > 1_048_576 ||
+                    !Queue.offerUnsafe(listener.frames, value)) {
+                    clear(listener);
+                    // Keep exactly one reset obligation; no incoming backlog can grow it.
+                    listener.lagged = true;
+                    Queue.offerUnsafe(listener.frames, "reset");
+                }
+                else {
+                    listener.bytes += bytes;
+                }
+            }
+        },
+        end(error) {
+            if (ended)
+                return;
+            ended = true;
+            failure = error;
+            for (const listener of listeners) {
+                clear(listener);
+                listener.lagged = false;
+                Queue.endUnsafe(listener.frames);
+            }
+        },
+    };
+}
 const ownerPublishers = new WeakMap();
 /** Actual live-view demand, excluding exact-command settlement waiters. */
 export function hasOwnerObservers(store, sessionId) {
@@ -39,7 +159,10 @@ function queueObservation(listener, reason) {
                 : "progress";
 }
 function deliverObservation(listener, reason) {
-    if (listener.closed || listener.reset)
+    if (listener.closed)
+        return;
+    listener.revision += 1;
+    if (listener.reset)
         return;
     const wake = listener.wake;
     if (wake === undefined) {
@@ -169,6 +292,7 @@ export function openObservationKernel(store) {
             if (active.size >= MAX_OBSERVATIONS)
                 return Effect.fail(new ShiitakeError("runtime", "rejected", "Observation capacity is exhausted"));
             const listener = {
+                revision: 0,
                 sessionId,
                 settlementOnly: interest === "settlement",
                 closed: false,
@@ -199,6 +323,9 @@ export function openObservationKernel(store) {
                 });
             });
             return Effect.succeed(Object.freeze({
+                get revision() {
+                    return listener.revision;
+                },
                 pollSignal,
                 awaitSignal,
                 close: () => {