@xandreed/plugin-sessions 0.13.0 → 0.14.0

package/README.md

@@ -1,5 +1,5 @@
 # @xandreed/plugin-sessions
 
-Efferent composable agent framework, 0.13.0. Node 24 or Bun.
+Efferent composable agent framework, 0.14.0. Node 24 or Bun.
 
 Documentation: https://github.com/xandreeddev/efferent

package/dist/plugin.adapter.d.ts

@@ -1,8 +1,11 @@
-import { SessionLog, Sessions, TurnAdmission } from "@xandreed/core";
+import { SessionLog, Sessions, TurnActivity, TurnAdmission } from "@xandreed/core";
 /**
  * Sessions over the host's SessionLog: one event log per session, one open
  * turn at a time, leases by lease or by process, the inbox and forks. The
- * host admits every turn (TurnAdmissionOpen admits all).
+ * host admits every turn (TurnAdmissionOpen admits all). It also provides
+ * `TurnActivity`, the turns this process holds open or is beginning
+ * (`processActivity`, `awaitIdle`). By default a turn's lease is 60 s, renewed by its writes and
+ * by a keep-alive every 20 s.
  */
 export declare const sessionsPlugin: import("@xandreed/core").TypedPlugin<{
     readonly ownership: {
@@ -44,8 +47,8 @@ export declare const sessionsPlugin: import("@xandreed/core").TypedPlugin<{
         readonly batch: number;
     };
     readonly retries: number;
-}, Sessions, never, SessionLog | TurnAdmission>;
-/** Sessions as a typed layer: provides Sessions; requires SessionLog and TurnAdmission. */
+}, Sessions | TurnActivity, import("@xandreed/core").HarnessError, SessionLog | TurnAdmission>;
+/** Sessions as a typed layer: provides Sessions and TurnActivity; requires SessionLog and TurnAdmission. */
 export declare const SessionsPluginLive: (options?: Partial<{
     readonly ownership: {
         readonly mode: "lease";
@@ -66,5 +69,5 @@ export declare const SessionsPluginLive: (options?: Partial<{
         readonly batch: number;
     };
     readonly retries: number;
-}> | undefined) => import("effect/Layer").Layer<Sessions, import("@xandreed/core").HarnessError, SessionLog | TurnAdmission>;
+}> | undefined) => import("effect/Layer").Layer<Sessions | TurnActivity, import("@xandreed/core").HarnessError, SessionLog | TurnAdmission>;
 export default sessionsPlugin;

package/dist/plugin.adapter.js

@@ -1,14 +1,14 @@
-import { definePlugin, SessionLog, Sessions, TurnAdmission } from "@xandreed/core";
+import { definePlugin, SessionLog, Sessions, TurnActivity, TurnAdmission } from "@xandreed/core";
 import { SessionsConfig, sessionsDefaults } from "./sessions-state.entity.js";
 import { SessionsLive } from "./sessions.adapter.js";
 export const sessionsPlugin = definePlugin({
   id: "@xandreed/plugin-sessions",
-  version: "0.13.0",
+  version: "0.14.0",
   scope: "runtime",
   config: SessionsConfig,
   defaults: sessionsDefaults,
   requires: [SessionLog, TurnAdmission],
-  provides: [Sessions],
+  provides: [Sessions, TurnActivity],
   layer: SessionsLive
 }), SessionsPluginLive = sessionsPlugin.live;
 export default sessionsPlugin;

package/dist/sessions-state.entity.d.ts

@@ -61,7 +61,16 @@ export declare const Ownership: Schema.Union<readonly [Schema.Struct<{
     readonly mode: Schema.Literal<"lease">;
     /** How long an open turn is held without a write (storage time). */
     readonly ttlMs: Schema.Int;
-    /** `none`: the lease is fixed at begin; `on-commit`: each write extends it; `everyMs`: a keep-alive also extends it. */
+    /**
+     * `none`: the lease is fixed at begin; `on-commit`: each write extends it;
+     * `everyMs`: each write extends it, and so does a keep-alive every
+     * `everyMs` while the turn is open (the first one interval after the
+     * begin), so a silent step (a slow model call, a long tool) keeps it.
+     * `everyMs` is at most half of `ttlMs`, so a renewal lands before the
+     * lease runs out even when one is late. A renewal is queued in order
+     * with the turn's writes: it cannot pass a `write` or `transact` still
+     * running, so keep those shorter than the lease.
+     */
     readonly renew: Schema.Union<readonly [Schema.Literals<readonly ["none", "on-commit"]>, Schema.Struct<{
         readonly everyMs: Schema.Int;
     }>]>;
@@ -84,7 +93,16 @@ export declare const SessionsConfig: Schema.Struct<{
         readonly mode: Schema.Literal<"lease">;
         /** How long an open turn is held without a write (storage time). */
         readonly ttlMs: Schema.Int;
-        /** `none`: the lease is fixed at begin; `on-commit`: each write extends it; `everyMs`: a keep-alive also extends it. */
+        /**
+         * `none`: the lease is fixed at begin; `on-commit`: each write extends it;
+         * `everyMs`: each write extends it, and so does a keep-alive every
+         * `everyMs` while the turn is open (the first one interval after the
+         * begin), so a silent step (a slow model call, a long tool) keeps it.
+         * `everyMs` is at most half of `ttlMs`, so a renewal lands before the
+         * lease runs out even when one is late. A renewal is queued in order
+         * with the turn's writes: it cannot pass a `write` or `transact` still
+         * running, so keep those shorter than the lease.
+         */
         readonly renew: Schema.Union<readonly [Schema.Literals<readonly ["none", "on-commit"]>, Schema.Struct<{
             readonly everyMs: Schema.Int;
         }>]>;
@@ -108,4 +126,5 @@ export declare const SessionsConfig: Schema.Struct<{
     readonly retries: Schema.Int;
 }>;
 export type SessionsConfig = typeof SessionsConfig.Type;
+/** By default a turn is leased for 60 s, renewed by every write and by a keep-alive every 20 s. */
 export declare const sessionsDefaults: SessionsConfig;

package/dist/sessions-state.entity.functions.d.ts

@@ -1,5 +1,5 @@
 import { Effect, Option, Schema } from "effect";
-import type { JsonObject, SessionHead, SessionView, TurnEndReason } from "@xandreed/core";
+import type { InboxItem, JsonObject, SessionHead, SessionView, TurnEndReason } from "@xandreed/core";
 import type { HeldTurn, HolderProcess, InboxSlot, Ownership, ProcessLiveness, SessionsState as State } from "./sessions-state.entity.js";
 /** A session's state before its first turn: a fork counts from its parent's turns. */
 export declare const initialState: (head: SessionHead) => State;
@@ -7,6 +7,10 @@ export declare const initialState: (head: SessionHead) => State;
 export declare const stateOf: (head: SessionHead) => Effect.Effect<State, Schema.SchemaError>;
 /** The state as the head stores it. */
 export declare const stateJson: (state: State) => JsonObject;
+/** What `inbox.queued` stores of a delivered item. */
+export declare const queuedData: (item: InboxItem) => JsonObject;
+/** What `inbox.dropped` stores of an item as many turns took and failed as the inbox allows. */
+export declare const droppedData: (id: string) => JsonObject;
 /** Who asks whether a turn is held: this Sessions instance, and how it tells whether a process runs. */
 export interface Holder {
     readonly instance: string;

package/dist/sessions-state.entity.functions.js

@@ -1,4 +1,5 @@
 import { Effect, Option, Schema } from "effect";
+import { InboxDroppedData, InboxQueuedData } from "@xandreed/core";
 import { SessionsState } from "./sessions-state.entity.js";
 const decodeState = Schema.decodeUnknownEffect(SessionsState), encodeState = Schema.encodeSync(SessionsState);
 export const initialState = (head) => ({
@@ -8,6 +9,8 @@ export const initialState = (head) => ({
   title: Option.none(),
   inbox: []
 }), stateOf = (head) => head.state.sessions === void 0 ? Effect.succeed(initialState(head)) : decodeState(head.state.sessions), stateJson = (state) => ({ sessions: encodeState(state) });
+const encodeQueued = Schema.encodeSync(InboxQueuedData), encodeDropped = Schema.encodeSync(InboxDroppedData);
+export const queuedData = (item) => ({ ...encodeQueued({ id: item.id, source: item.source, content: item.content }) }), droppedData = (id) => ({ ...encodeDropped({ id, reason: "attempts" }) });
 const processHolds = (open, holder) => open.holder === holder.instance ? Effect.succeed(!0) : Option.match(open.process, {
   onNone: () => Effect.succeed(!1),
   onSome: (running) => Option.match(holder.process, {

package/dist/sessions-state.entity.js

@@ -15,7 +15,9 @@ export const InboxSlot = Schema.Struct({
     mode: Schema.Literal("lease"),
     ttlMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1000)),
     renew: Schema.Union([Schema.Literals(["none", "on-commit"]), Schema.Struct({ everyMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(100)) })])
-  }),
+  }).annotate({
+    description: 'A turn is held for ttlMs (storage time) after its begin and after each renewal. renew: "none" fixes the lease at begin, "on-commit" extends it with each write, { everyMs } also extends it with a keep-alive every everyMs while the turn is open (the first one interval after the begin). everyMs must be at most half of ttlMs (everyMs * 2 <= ttlMs), or the options fail with config.options.'
+  }).check(Schema.makeFilter((lease) => typeof lease.renew !== "object" || lease.renew.everyMs * 2 <= lease.ttlMs ? void 0 : `renew.everyMs (${lease.renew.everyMs}) must be at most half of ttlMs (${lease.ttlMs}), so a keep-alive lands before the lease runs out`)),
   Schema.Struct({ mode: Schema.Literal("process") })
 ]), SessionsConfig = Schema.Struct({
   ownership: Ownership,
@@ -30,7 +32,7 @@ export const InboxSlot = Schema.Struct({
   }),
   retries: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 64 }))
 }), sessionsDefaults = {
-  ownership: { mode: "lease", ttlMs: 60000, renew: "on-commit" },
+  ownership: { mode: "lease", ttlMs: 60000, renew: { everyMs: 20000 } },
   titleChars: 80,
   inbox: { maxPending: 20, attempts: 2 },
   writer: { capacity: 1024, batch: 64 },

package/dist/sessions.adapter.d.ts

@@ -1,5 +1,5 @@
 import { Layer } from "effect";
-import { SessionLog, Sessions, TurnAdmission } from "@xandreed/core";
+import { HarnessError, SessionLog, Sessions, TurnActivity, TurnAdmission } from "@xandreed/core";
 import type { ProcessLiveness, SessionsConfig } from "./sessions-state.entity.js";
 /**
  * Sessions over a SessionLog. The state (turns, the open turn, the title,
@@ -9,7 +9,12 @@ import type { ProcessLiveness, SessionsConfig } from "./sessions-state.entity.js
  * compare-and-swap loop that plans again after a conflict. Under process
  * ownership, `liveness` names this process in the turns it holds and tells
  * whether another's still runs (by default, by host, pid and `kill(pid, 0)`).
+ * It also provides `TurnActivity`: each begin from the moment it is asked
+ * for until its writer is handed over (or it fails), then each turn until
+ * its writer's scope closes. An ownership the schema
+ * refuses (a keep-alive slower than half the lease) fails the layer with
+ * `config.options`.
  */
 export declare const SessionsLive: (config: SessionsConfig, options?: {
     readonly liveness?: ProcessLiveness;
-}) => Layer.Layer<Sessions, never, SessionLog | TurnAdmission>;
+}) => Layer.Layer<Sessions | TurnActivity, HarnessError, SessionLog | TurnAdmission>;

package/dist/sessions.adapter.js

@@ -1,31 +1,42 @@
-import { Clock, Effect, Exit, Layer, Option, PubSub, Ref, Scope, Stream } from "effect";
+import { Clock, Context, Effect, Exit, Layer, Option, PubSub, Ref, Schema, Scope, Stream, SubscriptionRef } from "effect";
 import {
   canonicalJson,
   ConversationId,
   EntryId,
+  HarnessError,
+  harnessDefectsAsFailures,
   InboxFull,
   KeyConflict,
+  normalizeUserMessage,
   NothingPending,
+  NotResumable,
   RESERVED_KINDS,
+  resumeRefusal,
   ReservedKind,
+  sameUserMessage,
   SessionBusy,
   SessionLog,
   SessionLogError,
   SessionMissing,
   Sessions,
+  TurnActivity,
   TurnAdmission,
   TurnDuplicate,
   turnEndedDraft,
+  turnEndedOf,
+  turnEndingOf,
   turnStartedDraft,
   turnStartedOf,
   UserMessage
 } from "@xandreed/core";
 import { processLiveness } from "./process-liveness.adapter.js";
-import { closedState, heldTurn, pendingOf, stateJson, stateOf, titleOf, viewOf } from "./sessions-state.entity.functions.js";
+import { closedState, droppedData, heldTurn, pendingOf, queuedData, stateJson, stateOf, titleOf, viewOf } from "./sessions-state.entity.functions.js";
+import { Ownership } from "./sessions-state.entity.js";
 import { makeTurnWriter } from "./turn-writer.adapter.js";
 const storage = (code) => (error) => new SessionLogError({ code, message: error.message }), standalone = (drafts) => drafts.map((draft) => ({ kind: draft.kind, turn: Option.none(), data: draft.data }));
-export const SessionsLive = (config, options) => Layer.effect(Sessions, Effect.gen(function* () {
-  const log = yield* SessionLog, admission = yield* TurnAdmission, ownership = config.ownership, instance = yield* Effect.sync(() => crypto.randomUUID()), liveness = options?.liveness ?? processLiveness, holder = { instance, liveness, process: ownership.mode === "process" ? yield* liveness.current : Option.none() }, signals = yield* PubSub.unbounded(), writers = yield* Ref.make(new Map), wake = (id) => PubSub.publish(signals, id).pipe(Effect.asVoid), freshId = Effect.sync(() => ConversationId.make(crypto.randomUUID())), stateFrom = (head) => stateOf(head).pipe(Effect.mapError(storage("session.state"))), owned = (address) => log.head(address.id).pipe(Effect.flatMap((head) => head.header.owner === address.owner ? Effect.succeed(head) : Effect.fail(new SessionMissing({ session: address.id })))), viewFrom = (head) => stateFrom(head).pipe(Effect.flatMap((state) => viewOf(head, state, ownership, holder))), guarded = (address, plan, stored = () => Effect.void) => {
+export const SessionsLive = (config, options) => Layer.effectContext(Effect.gen(function* () {
+  yield* Schema.decodeUnknownEffect(Ownership)(config.ownership).pipe(Effect.mapError((error) => new HarnessError({ code: "config.options", plugin: "@xandreed/plugin-sessions", message: `ownership: ${error.message}` })));
+  const log = yield* SessionLog, admission = yield* TurnAdmission, ownership = config.ownership, instance = yield* Effect.sync(() => crypto.randomUUID()), liveness = options?.liveness ?? processLiveness, holder = { instance, liveness, process: ownership.mode === "process" ? yield* liveness.current : Option.none() }, signals = yield* PubSub.unbounded(), writers = yield* Ref.make(new Map), inFlight = yield* SubscriptionRef.make({ held: new Map, beginning: 0 }), heldKey = (id, turn) => `${id}:${turn}`, beginSettled = SubscriptionRef.update(inFlight, (now) => ({ ...now, beginning: now.beginning - 1 })), wake = (id) => PubSub.publish(signals, id).pipe(Effect.asVoid), freshId = Effect.sync(() => ConversationId.make(crypto.randomUUID())), stateFrom = (head) => stateOf(head).pipe(Effect.mapError(storage("session.state"))), owned = (address) => log.head(address.id).pipe(Effect.flatMap((head) => head.header.owner === address.owner ? Effect.succeed(head) : Effect.fail(new SessionMissing({ session: address.id })))), viewFrom = (head) => stateFrom(head).pipe(Effect.flatMap((state) => viewOf(head, state, ownership, holder))), guarded = (address, plan, stored = () => Effect.void) => {
     const attempt = (tries) => Effect.gen(function* () {
       const head = yield* owned(address), planned = yield* plan(head, yield* stateFrom(head));
       if (planned.drafts.length === 0 && Option.isNone(planned.next))
@@ -48,118 +59,160 @@ export const SessionsLive = (config, options) => Layer.effect(Sessions, Effect.g
     return attempt(0);
   }, reaped = (head, state) => Effect.gen(function* () {
     if (Option.isNone(state.open) || Option.isSome(yield* heldTurn(head, state, ownership, holder)))
-      return { drafts: [], state };
-    const turn = state.open.value.turn, after = closedState(state, "interrupted", config.inbox.attempts, !0), closing = yield* turnEndedDraft(turn, { reason: "interrupted", failure: Option.some({ code: "turn.lease", message: "the turn's holder stopped writing" }) }).pipe(Effect.mapError(storage("session.encode"))), dropped = after.dropped.map((id) => ({ kind: "inbox.dropped", turn: Option.some(turn), data: { id, reason: "attempts" } }));
-    return { drafts: [closing, ...dropped], state: after.state };
+      return { drafts: [], state, closed: Option.none() };
+    const turn = state.open.value.turn, after = closedState(state, "interrupted", config.inbox.attempts, !0), closing = yield* turnEndedDraft(turn, { reason: "interrupted", failure: Option.some({ code: "turn.lease", message: "the turn's holder stopped writing" }) }).pipe(Effect.mapError(storage("session.encode"))), dropped = after.dropped.map((id) => ({ kind: "inbox.dropped", turn: Option.some(turn), data: droppedData(id) }));
+    return { drafts: [closing, ...dropped], state: after.state, closed: Option.some(turn) };
   }), keyed = (id, key) => log.read(id, { after: 0, limit: Option.none(), kinds: ["turn.started"] }).pipe(Effect.flatMap((events) => Option.match(Option.fromNullishOr(events.find((event) => event.data.key === key)), {
     onNone: () => Effect.succeed(Option.none()),
     onSome: (event) => Effect.succeed(Option.some({ turn: Option.getOrElse(event.turn, () => 0), event }))
-  }))), inboxItems = (id, ids) => log.read(id, { after: 0, limit: Option.none(), kinds: ["inbox.queued"] }).pipe(Effect.map((events) => ids.flatMap((wanted) => Option.toArray(Option.fromNullishOr(events.find((event) => event.data.id === wanted))).map((event) => ({
+  }))), turnsOf = (id, reapedNow) => log.read(id, { after: 0, limit: Option.none(), kinds: ["turn.started", "turn.ended"] }).pipe(Effect.flatMap((events) => Effect.gen(function* () {
+    const numbered = (event) => Option.getOrElse(event.turn, () => 0), endings = new Map(yield* Effect.forEach(events.filter((event) => event.kind === "turn.ended"), (event) => turnEndedOf(event).pipe(Effect.map((ended) => [numbered(event), ended.reason]))));
+    return yield* Effect.forEach(events.filter((event) => event.kind === "turn.started"), (event) => turnStartedOf(event).pipe(Effect.map((started) => ({
+      turn: numbered(event),
+      origin: started.origin,
+      resumes: Option.fromNullishOr(started.resumes),
+      ended: Option.contains(reapedNow, numbered(event)) ? Option.some("interrupted") : Option.fromNullishOr(endings.get(numbered(event)))
+    }))));
+  }).pipe(Effect.mapError(storage("session.decode"))))), inboxItems = (id, ids) => log.read(id, { after: 0, limit: Option.none(), kinds: ["inbox.queued"] }).pipe(Effect.map((events) => ids.flatMap((wanted) => Option.toArray(Option.fromNullishOr(events.find((event) => event.data.id === wanted))).map((event) => ({
     id: wanted,
     source: typeof event.data.source === "object" && event.data.source !== null ? event.data.source : {},
     content: typeof event.data.content === "string" && event.data.content.length > 0 ? event.data.content : `(inbox item ${wanted})`
   }))))), unhanded = (address, turn, exit) => guarded(address, (_head, state) => Effect.gen(function* () {
     if (!Option.exists(state.open, (open) => open.turn === turn && open.holder === instance))
       return { drafts: [], next: Option.none(), result: void 0 };
-    const reason = Exit.hasInterrupts(exit) ? "interrupted" : "failed", after = closedState(state, reason, config.inbox.attempts, !1), closing = yield* turnEndedDraft(turn, { reason, failure: Option.some({ code: "turn.unended", message: "the turn's scope closed before it ended" }) }).pipe(Effect.mapError(storage("session.encode"))), dropped = after.dropped.map((id) => ({ kind: "inbox.dropped", turn: Option.some(turn), data: { id, reason: "attempts" } }));
+    const interrupted = Exit.hasInterrupts(exit), reason = interrupted ? "interrupted" : "failed", after = closedState(state, reason, config.inbox.attempts, !1), closing = yield* turnEndedDraft(turn, {
+      reason,
+      failure: Option.some(interrupted ? { code: "turn.interrupted", message: "the turn's begin was interrupted before its writer was handed over" } : { code: "turn.unended", message: "the turn's scope closed before it ended" })
+    }).pipe(Effect.mapError(storage("session.encode"))), dropped = after.dropped.map((id) => ({ kind: "inbox.dropped", turn: Option.some(turn), data: droppedData(id) }));
     return { drafts: [closing, ...dropped], next: Option.some(after.state), result: void 0 };
-  })).pipe(Effect.timeout("10 seconds"), Effect.ignore), begin = (address, input) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
-    const scope = yield* Effect.scope, at = yield* Clock.currentTimeMillis, toAdmit = { session: address, origin: input._tag === "User" ? "user" : "inbox", runId: input.runId, key: input._tag === "User" ? input.key : input.runId }, unowned = yield* Ref.make(Option.none());
-    yield* Scope.addFinalizerExit(scope, (exit) => Ref.get(unowned).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: (turn) => unhanded(address, turn, exit) }))));
-    const begun = yield* restore(admission.admit(toAdmit, guarded(address, (head, stored) => Effect.gen(function* () {
-      const reap = yield* reaped(head, stored), state = reap.state;
-      if (input._tag === "User") {
-        const previous = yield* keyed(address.id, input.key);
-        if (Option.isSome(previous)) {
-          const started = yield* turnStartedOf(previous.value.event).pipe(Effect.mapError(storage("session.decode"))), same = started.userMessage.text === input.userMessage.text && canonicalJson(started.command) === canonicalJson(input.command);
-          return yield* Effect.fail(same ? new TurnDuplicate({ session: address.id, turn: previous.value.turn, open: Option.exists(state.open, (open) => open.turn === previous.value.turn) }) : new KeyConflict({ session: address.id, key: input.key, turn: previous.value.turn }));
+  })).pipe(Effect.timeout("10 seconds"), Effect.ignore), openTurn = (address, input) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+    const scope = yield* Effect.scope, at = yield* Clock.currentTimeMillis, meta = input.meta ?? {}, resumes = input._tag === "User" ? Option.fromNullishOr(input.resumes) : Option.none(), unnumbered = Option.filter(resumes, (turn) => !(Number.isSafeInteger(turn) && turn >= 1));
+    if (Option.isSome(unnumbered))
+      return yield* Effect.fail(new NotResumable({ session: address.id, turn: unnumbered.value, reason: "missing" }));
+    const resuming = Option.match(resumes, { onNone: () => ({}), onSome: (turn) => ({ resumes: turn }) }), toAdmit = { session: address, origin: input._tag === "User" ? "user" : "inbox", runId: input.runId, key: input._tag === "User" ? input.key : input.runId, meta, ...resuming }, unowned = yield* Ref.make(Option.none());
+    yield* SubscriptionRef.update(inFlight, (now) => ({ ...now, beginning: now.beginning + 1 }));
+    yield* Scope.addFinalizerExit(scope, (exit) => Ref.get(unowned).pipe(Effect.flatMap(Option.match({
+      onNone: () => Effect.void,
+      onSome: (turn) => unhanded(address, turn, exit).pipe(Effect.ensuring(beginSettled))
+    }))));
+    return yield* Effect.gen(function* () {
+      const begun = yield* restore(admission.admit(toAdmit, guarded(address, (head, stored) => Effect.gen(function* () {
+        const reap = yield* reaped(head, stored), state = reap.state;
+        if (input._tag === "User") {
+          const previous = yield* keyed(address.id, input.key);
+          if (Option.isSome(previous)) {
+            const started = yield* turnStartedOf(previous.value.event).pipe(Effect.mapError(storage("session.decode"))), same = sameUserMessage(started.userMessage, input.userMessage) && canonicalJson(started.command) === canonicalJson(input.command) && started.resumes === input.resumes;
+            return yield* Effect.fail(same ? new TurnDuplicate({ session: address.id, turn: previous.value.turn, open: Option.exists(state.open, (open) => open.turn === previous.value.turn) }) : new KeyConflict({ session: address.id, key: input.key, turn: previous.value.turn }));
+          }
         }
-      }
-      if (Option.isSome(state.open))
-        return yield* Effect.fail(new SessionBusy({ session: address.id, turn: state.open.value.turn }));
-      const waiting = input._tag === "Inbox" ? pendingOf(state).map((slot) => slot.id) : [];
-      if (input._tag === "Inbox" && waiting.length === 0)
-        return yield* Effect.fail(new NothingPending({ session: address.id }));
-      const claimed = yield* inboxItems(address.id, waiting), userMessage = input._tag === "User" ? input.userMessage : new UserMessage({ text: claimed.map((item) => item.content).join(`
+        if (Option.isSome(state.open))
+          return yield* Effect.fail(new SessionBusy({ session: address.id, turn: state.open.value.turn }));
+        if (Option.isSome(resumes)) {
+          const refusal = resumeRefusal(resumes.value, yield* turnsOf(address.id, reap.closed));
+          if (Option.isSome(refusal))
+            return yield* Effect.fail(new NotResumable({ session: address.id, turn: resumes.value, reason: refusal.value }));
+        }
+        const waiting = input._tag === "Inbox" ? pendingOf(state).map((slot) => slot.id) : [];
+        if (input._tag === "Inbox" && waiting.length === 0)
+          return yield* Effect.fail(new NothingPending({ session: address.id }));
+        const claimed = yield* inboxItems(address.id, waiting), userMessage = input._tag === "User" ? input.userMessage : new UserMessage({ text: claimed.map((item) => item.content).join(`
 
 `) }), turn = state.turns + 1, key = input._tag === "User" ? input.key : input.runId, open = {
-        turn,
-        runId: input.runId,
-        key,
-        origin: input._tag === "User" ? "user" : "inbox",
-        holder: instance,
-        expiresAt: ownership.mode === "lease" ? Option.some(head.now + ownership.ttlMs) : Option.none(),
-        process: holder.process
-      }, next = {
-        ...state,
-        turns: turn,
-        open: Option.some(open),
-        title: Option.orElse(state.title, () => input._tag === "User" ? Option.some(titleOf(input.userMessage.text, config.titleChars)) : Option.none()),
-        inbox: state.inbox.map((slot) => waiting.includes(slot.id) ? { ...slot, claimedBy: Option.some(turn) } : slot)
-      }, starting = yield* turnStartedDraft(turn, {
-        runId: input.runId,
-        key,
-        origin: open.origin,
-        userMessage,
-        command: input._tag === "User" ? input.command : {},
-        claimed: waiting,
-        entry: EntryId.make(`${input.runId}:0`),
-        at
-      }).pipe(Effect.mapError(storage("session.encode"))), admitted = {
-        session: address,
-        turn,
-        runId: input.runId,
-        key,
-        origin: open.origin,
-        userMessage,
-        command: input._tag === "User" ? input.command : {},
-        claimed
-      };
-      return { drafts: [...reap.drafts, starting], next: Option.some(next), result: { admitted, next } };
-    }), (opened) => Ref.set(unowned, Option.some(opened.admitted.turn))))), committed = yield* Option.match(begun.committed, {
-      onNone: () => Effect.fail(new SessionLogError({ code: "session.begin", message: "the turn was not committed" })),
-      onSome: Effect.succeed
-    }), started = yield* Option.match(Option.fromNullishOr(committed.events.at(-1)), {
-      onNone: () => Effect.fail(new SessionLogError({ code: "session.begin", message: "the turn's start was not stored" })),
-      onSome: Effect.succeed
-    });
-    yield* Effect.addFinalizer(() => Ref.update(writers, (all) => new Map([...all].filter(([id, open]) => id !== address.id || open.turn !== begun.result.admitted.turn))));
-    const open = yield* makeTurnWriter({
-      log,
-      config,
-      instance,
-      header: begun.head.header,
-      admitted: begun.result.admitted,
-      started,
-      position: { revision: committed.revision, seq: committed.seq, state: begun.result.next, storageAt: committed.at },
-      wake: wake(address.id)
-    }, scope);
-    yield* Ref.set(unowned, Option.none());
-    yield* Ref.update(writers, (all) => new Map([...all, [address.id, { ...open, turn: begun.result.admitted.turn }]]));
-    return open.writer;
-  })), closeLocal = (id, reason, turn) => Ref.get(writers).pipe(Effect.flatMap((all) => Option.match(Option.fromNullishOr(all.get(id)), {
+          turn,
+          runId: input.runId,
+          key,
+          origin: input._tag === "User" ? "user" : "inbox",
+          holder: instance,
+          expiresAt: ownership.mode === "lease" ? Option.some(head.now + ownership.ttlMs) : Option.none(),
+          process: holder.process
+        }, next = {
+          ...state,
+          turns: turn,
+          open: Option.some(open),
+          title: Option.orElse(state.title, () => input._tag === "User" && input.userMessage.text.length > 0 ? Option.some(titleOf(input.userMessage.text, config.titleChars)) : Option.none()),
+          inbox: state.inbox.map((slot) => waiting.includes(slot.id) ? { ...slot, claimedBy: Option.some(turn) } : slot)
+        }, starting = yield* turnStartedDraft(turn, {
+          runId: input.runId,
+          key,
+          origin: open.origin,
+          userMessage,
+          command: input._tag === "User" ? input.command : {},
+          claimed: waiting,
+          entry: EntryId.make(`${input.runId}:0`),
+          at,
+          ...input.meta === void 0 ? {} : { meta: input.meta },
+          ...resuming
+        }).pipe(Effect.mapError(storage("session.encode"))), admitted = {
+          session: address,
+          turn,
+          runId: input.runId,
+          key,
+          origin: open.origin,
+          userMessage,
+          command: input._tag === "User" ? input.command : {},
+          claimed,
+          meta,
+          ...resuming
+        };
+        return { drafts: [...reap.drafts, starting], next: Option.some(next), result: { admitted, next } };
+      }), (opened) => Ref.set(unowned, Option.some(opened.admitted.turn))))), committed = yield* Option.match(begun.committed, {
+        onNone: () => Effect.fail(new SessionLogError({ code: "session.begin", message: "the turn was not committed" })),
+        onSome: Effect.succeed
+      }), started = yield* Option.match(Option.fromNullishOr(committed.events.at(-1)), {
+        onNone: () => Effect.fail(new SessionLogError({ code: "session.begin", message: "the turn's start was not stored" })),
+        onSome: Effect.succeed
+      }), turn = begun.result.admitted.turn;
+      yield* Effect.addFinalizer(() => Ref.update(writers, (all) => new Map([...all].filter(([id, open]) => id !== address.id || open.turn !== turn))).pipe(Effect.andThen(SubscriptionRef.update(inFlight, (now) => ({ ...now, held: new Map([...now.held].filter(([key]) => key !== heldKey(address.id, turn))) })))));
+      const open = yield* makeTurnWriter({
+        log,
+        config,
+        instance,
+        header: begun.head.header,
+        admitted: begun.result.admitted,
+        started,
+        position: { revision: committed.revision, seq: committed.seq, state: begun.result.next, storageAt: committed.at },
+        wake: wake(address.id)
+      }, scope);
+      yield* Ref.set(unowned, Option.none());
+      yield* Ref.update(writers, (all) => new Map([...all, [address.id, { ...open, turn }]]));
+      const since = yield* Clock.currentTimeMillis;
+      yield* SubscriptionRef.update(inFlight, (now) => ({
+        held: new Map([...now.held, [heldKey(address.id, turn), { session: address.id, turn, since }]]),
+        beginning: now.beginning - 1
+      }));
+      return open;
+    }).pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : Ref.get(unowned).pipe(Effect.flatMap((committed) => Option.isSome(committed) ? Effect.void : beginSettled))));
+  })), normalized = (input) => input._tag === "User" ? normalizeUserMessage(input.userMessage).pipe(Effect.map((userMessage) => ({ ...input, userMessage }))) : Effect.succeed(input), begin = (address, input) => normalized(input).pipe(Effect.flatMap((ready) => openTurn(address, ready)), Effect.map((open) => open.writer)), closeLocal = (id, reason, turn) => Ref.get(writers).pipe(Effect.flatMap((all) => Option.match(Option.fromNullishOr(all.get(id)), {
     onNone: () => Effect.void,
     onSome: (open) => Option.match(turn, { onNone: () => !0, onSome: (wanted) => wanted === open.turn }) ? open.close(reason) : Effect.void
   }))), drain = (address, run, options) => {
-    const maxTurns = options?.maxTurns ?? 3, once = Effect.scoped(Effect.gen(function* () {
-      const writer = yield* begin(address, { _tag: "Inbox", runId: yield* Effect.sync(() => crypto.randomUUID()) }), exit = yield* Effect.exit(run(writer));
-      if (exit._tag === "Failure")
-        yield* Effect.logWarning(`inbox turn ${writer.admitted.turn} of ${address.id} failed`);
-      yield* writer.end({
-        reason: exit._tag === "Success" ? "completed" : "failed",
-        failure: exit._tag === "Success" ? Option.none() : Option.some({ code: "inbox.turn", message: "the inbox turn failed" })
-      }).pipe(Effect.ignore);
+    const maxTurns = options?.maxTurns ?? 3, meta = options?.meta, once = Effect.scoped(Effect.gen(function* () {
+      const runId = yield* Effect.sync(() => crypto.randomUUID()), open = yield* openTurn(address, meta === void 0 ? { _tag: "Inbox", runId } : { _tag: "Inbox", runId, meta }), exit = yield* Effect.exit(harnessDefectsAsFailures(run(open.writer))), ending = turnEndingOf(Exit.map(exit, () => ({ outcome: "completed" })));
+      if (ending.reason === "interrupted")
+        yield* open.markTried;
+      yield* Option.match(ending.failure, {
+        onNone: () => Effect.void,
+        onSome: (failure) => Effect.logWarning(`inbox turn ${open.writer.admitted.turn} of ${address.id} ended ${ending.reason}: ${failure.code}`)
+      });
+      yield* open.writer.end(ending).pipe(Effect.ignore);
       return !0;
     })).pipe(Effect.catchTags({
       NothingPending: () => Effect.succeed(!1),
       SessionBusy: () => Effect.succeed(!1),
       TurnDuplicate: () => Effect.succeed(!1),
       KeyConflict: () => Effect.succeed(!1),
+      NotResumable: () => Effect.succeed(!1),
       TurnRefused: (refused) => Effect.logWarning(`inbox turn of ${address.id} refused: ${refused.message}`).pipe(Effect.as(!1))
     })), loop = (turns) => turns >= maxTurns ? Effect.succeed({ turns }) : once.pipe(Effect.flatMap((ran) => ran ? loop(turns + 1) : Effect.succeed({ turns })));
     return loop(0);
-  };
-  return Sessions.of({
+  }, activity = TurnActivity.of({
+    current: SubscriptionRef.get(inFlight).pipe(Effect.map((now) => ({
+      open: [...now.held.values()].sort((left, right) => left.since - right.since),
+      beginning: now.beginning
+    }))),
+    idle: SubscriptionRef.changes(inFlight).pipe(Stream.filter((now) => now.held.size === 0 && now.beginning === 0), Stream.take(1), Stream.runDrain)
+  });
+  return Context.make(TurnActivity, activity).pipe(Context.add(Sessions, Sessions.of({
     create: (input) => Effect.gen(function* () {
       const head = yield* log.create({
         id: input.id ?? (yield* freshId),
@@ -238,11 +291,11 @@ export const SessionsLive = (config, options) => Layer.effect(Sessions, Effect.g
         return yield* Effect.fail(new InboxFull({ session: address.id, pending: pendingOf(state).length }));
       const next = { ...state, inbox: [...state.inbox, { id: item.id, attempts: 0, claimedBy: Option.none() }] };
       return {
-        drafts: [...reap.drafts, { kind: "inbox.queued", turn: Option.none(), data: { id: item.id, source: item.source, content: item.content } }],
+        drafts: [...reap.drafts, { kind: "inbox.queued", turn: Option.none(), data: queuedData(item) }],
         next: Option.some(next),
         result: { delivered: !0, pending: pendingOf(next).length }
       };
     })).pipe(Effect.map((done) => done.result)),
     drain
-  });
+  })));
 }));

package/dist/sessions.conformance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/turn-writer.adapter.d.ts

@@ -26,6 +26,8 @@ export interface OpenWriter {
     readonly writer: TurnWriter;
     readonly close: (reason: TurnClosed["reason"]) => Effect.Effect<void>;
     readonly ended: Effect.Effect<boolean>;
+    /** Count the inbox items the turn took as tried, though it wrote nothing (a drain `run` that interrupted itself). */
+    readonly markTried: Effect.Effect<void>;
 }
 /**
  * The open turn's writer. Items are stored strictly in queue order by one

package/dist/turn-writer.adapter.js

@@ -1,12 +1,12 @@
-import { Clock, Deferred, Effect, Exit, HashSet, Option, Queue, Ref, Schedule, Scope, Semaphore } from "effect";
+import { Clock, Deferred, Effect, Exit, HashSet, Option, Queue, Ref, Scope, Semaphore } from "effect";
 import { HarnessError, turnEndedDraft, TurnClosed } from "@xandreed/core";
-import { closedState, pendingOf, stateJson, stateOf } from "./sessions-state.entity.functions.js";
+import { closedState, droppedData, pendingOf, stateJson, stateOf } from "./sessions-state.entity.functions.js";
 const harness = (code, message) => new HarnessError({ code, message }), groupsOf = (items) => items.reduce((groups, item) => {
   const last = groups.at(-1);
   return last?._tag === "Append" && item._tag === "Append" ? [...groups.slice(0, -1), { _tag: "Append", drafts: [...last.drafts, ...item.drafts] }] : [...groups, item];
 }, []);
 export const makeTurnWriter = (input, scope) => Effect.gen(function* () {
-  const { log, config, admitted } = input, id = admitted.session.id, ownership = config.ownership, queue = yield* Queue.bounded(config.writer.capacity), failed = yield* Ref.make(Option.none()), ended = yield* Ref.make(!1), sealed = yield* Ref.make(!1), tried = yield* Ref.make(!1), admission = yield* Semaphore.make(1), ending = yield* Ref.make(Option.none()), waiting = yield* Ref.make(HashSet.empty()), closed = yield* Deferred.make(), foreign = yield* Ref.make([]), position = yield* Ref.make({ ...input.position, localAt: yield* Clock.currentTimeMillis }), refuseWaiting = (error) => Ref.get(waiting).pipe(Effect.flatMap((all) => Effect.forEach(all, (refuse) => refuse(error), { discard: !0 }))), close = (reason) => Effect.gen(function* () {
+  const { log, config, admitted } = input, id = admitted.session.id, ownership = config.ownership, queue = yield* Queue.bounded(config.writer.capacity), failed = yield* Ref.make(Option.none()), ended = yield* Ref.make(!1), sealed = yield* Ref.make(!1), tried = yield* Ref.make(!1), admission = yield* Semaphore.make(1), ending = yield* Ref.make(Option.none()), attempted = yield* Ref.make(Option.none()), waiting = yield* Ref.make(HashSet.empty()), closed = yield* Deferred.make(), foreign = yield* Ref.make([]), position = yield* Ref.make({ ...input.position, localAt: yield* Clock.currentTimeMillis }), refuseWaiting = (error) => Ref.get(waiting).pipe(Effect.flatMap((all) => Effect.forEach(all, (refuse) => refuse(error), { discard: !0 }))), close = (reason) => Effect.gen(function* () {
     if (yield* Ref.get(ended))
       return;
     const error = harness("turn.closed", `turn ${admitted.turn} was ${reason}`);
@@ -75,8 +75,9 @@ export const makeTurnWriter = (input, scope) => Effect.gen(function* () {
     yield* admit(result, { _tag: "Commit", commit: Effect.exit(commit).pipe(Effect.flatMap((exit) => Deferred.done(result, exit)), Effect.asVoid) }, tries);
     return yield* Deferred.await(result);
   }), flush = Deferred.make().pipe(Effect.flatMap((done) => admission.withPermits(1)(refuseIfFailed.pipe(Effect.andThen(enqueue(done, { _tag: "Marker", done })))).pipe(Effect.andThen(Deferred.await(done))))), endNow = (ending) => Effect.gen(function* () {
+    yield* Ref.set(attempted, Option.some(ending));
     const done = yield* commitPlan((at) => Effect.gen(function* () {
-      const after = closedState(at.state, ending.reason, config.inbox.attempts, yield* Ref.get(tried)), closing = yield* turnEndedDraft(admitted.turn, ending).pipe(Effect.mapError((error) => harness("session.encode", error.message))), dropped = after.dropped.map((item) => ({ kind: "inbox.dropped", data: { id: item, reason: "attempts" } }));
+      const after = closedState(at.state, ending.reason, config.inbox.attempts, yield* Ref.get(tried)), closing = yield* turnEndedDraft(admitted.turn, ending).pipe(Effect.mapError((error) => harness("session.encode", error.message))), dropped = after.dropped.map((item) => ({ kind: "inbox.dropped", data: droppedData(item) }));
       return { drafts: [{ kind: closing.kind, data: closing.data }, ...dropped], next: after.state, result: pendingOf(after.state).length };
     }), { renew: !1 });
     yield* Ref.set(ended, !0);
@@ -96,15 +97,13 @@ export const makeTurnWriter = (input, scope) => Effect.gen(function* () {
     return yield* Deferred.await(result);
   });
   if (ownership.mode === "lease" && typeof ownership.renew === "object") {
-    const renew = inOrder(commitPlan((at) => Effect.gen(function* () {
+    const every = `${ownership.renew.everyMs} millis`, renew = inOrder(commitPlan((at) => Effect.gen(function* () {
       return { drafts: [], next: renewed(at.state, yield* storageNow, !0), result: void 0 };
     }), { renew: !1 }), !1).pipe(Effect.ignore);
-    yield* Effect.forkIn(renew.pipe(Effect.repeat(Schedule.spaced(`${ownership.renew.everyMs} millis`)), Effect.asVoid), scope);
+    yield* Effect.forkIn(Effect.sleep(every).pipe(Effect.andThen(renew), Effect.forever, Effect.asVoid), scope);
   }
-  yield* Scope.addFinalizerExit(scope, (exit) => Ref.get(ended).pipe(Effect.flatMap((done) => done ? Effect.void : end({
-    reason: Exit.hasInterrupts(exit) ? "interrupted" : "failed",
-    failure: Option.some({ code: "turn.unended", message: "the turn's scope closed before it ended" })
-  }).pipe(Effect.timeout("10 seconds"), Effect.ignore)), Effect.ensuring(Effect.gen(function* () {
+  const unended = (exit) => Exit.hasInterrupts(exit) ? { reason: "interrupted", failure: Option.some({ code: "turn.interrupted", message: "the turn's scope was interrupted before it ended" }) } : { reason: "failed", failure: Option.some({ code: "turn.unended", message: "the turn's scope closed before it ended" }) };
+  yield* Scope.addFinalizerExit(scope, (exit) => Ref.get(ended).pipe(Effect.flatMap((done) => done ? Effect.void : Ref.get(attempted).pipe(Effect.flatMap((last) => end(Option.getOrElse(last, () => unended(exit)))), Effect.timeout("10 seconds"), Effect.ignore)), Effect.ensuring(Effect.gen(function* () {
     const error = harness("turn.closed", `turn ${admitted.turn}'s scope closed`);
     yield* Ref.update(failed, Option.orElse(() => Option.some(error)));
     yield* Queue.shutdown(queue);
@@ -125,7 +124,7 @@ export const makeTurnWriter = (input, scope) => Effect.gen(function* () {
     flush,
     end,
     closed: Deferred.await(closed)
-  }, close, ended: Ref.get(ended) };
+  }, close, ended: Ref.get(ended), markTried: Ref.set(tried, !0) };
 });
 const historyOf = (log, header, started, kinds, includeCurrent = !1) => {
   const ancestors = (lineage) => Option.match(lineage, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xandreed/plugin-sessions",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "engines": {
     "node": ">=24",
     "bun": ">=1.3.0"
@@ -14,7 +14,7 @@
     }
   },
   "dependencies": {
-    "@xandreed/core": "0.13.0",
+    "@xandreed/core": "0.14.0",
     "effect": "4.0.7"
   },
   "private": false,