@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/channels/kit/turn-queue.d.ts

@@ -1,21 +1,17 @@
+/** Per-session FIFO execution. */
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
 export interface TurnQueue<T> {
-    /** Schedule onto the session's serial chain (runs after that session's previous turn). */
     accept(rec: T): void;
-    /** Resolve once no turn is in flight (every per-session chain has drained). A test/observability seam
-     *  — the production runtime does NOT drain on shutdown (SIGTERM exits mid-turn by design; see the module
-     *  header), so this is not a graceful-drain hook; it just lets a caller await the fire-and-forget turns. */
+    /** Observation only: production shutdown does not drain channel turns. */
     idle(): Promise<void>;
 }
 export declare function createTurnQueue<T extends {
     session: string;
 }>(opts: {
-    /** Log prefix naming the consumer (e.g. "[telegram]") — the queue itself is channel-neutral. */
     label: string;
-    /** Executes ONE turn. The queue wraps it: dequeue in FIFO order per session. The runner owns its
-     *  own error surface; a rejection that escapes anyway is caught and logged here (never a silent
-     *  unhandled rejection), but the runner's own catch is where diagnosis belongs. */
-    run: (rec: T) => Promise<void>;
-    /** Fired synchronously when a record is scheduled BEHIND an active turn — the caller's hook for
-     *  queue feedback to the user (e.g. an "⏳ queued" notice). */
+    /** The queue diagnoses escaped failures and closes this turn's resources before its successor runs. */
+    run: (rec: T) => Effect.Effect<void, unknown, Scope.Scope>;
+    /** Synchronous queue feedback for a turn behind an active or queued predecessor. */
     onQueuedBehind?: (rec: T) => void;
 }): TurnQueue<T>;

package/dist/channels/kit/turn-queue.js

@@ -1,54 +1,36 @@
-/**
- * Per-session serial turn execution: one turn at a time per session (FIFO chains), different
- * sessions concurrent. IN-MEMORY — the runtime queue holds no durability of its own. The engine lease
- * is the corruption floor beneath this; this adds the group-UX queue (a second summon waits its turn
- * instead of colliding on the lease and being dropped as "busy").
- *
- * Channel-neutral (records are opaque beyond a `session` key), shared by the stateful chat channels
- * (Telegram, Feishu/Lark, Slack). Durability is layered ON TOP by the caller: turn-store.ts
- * persists an accepted turn's intent pre-ACK and replays a crash-surviving one on the next start (L1,
- * process-crash recovery, at-least-once). Exactly-once / deterministic step-replay (L2) is the K-axis
- * backend — an external queue with distributed locking (SPEC §11) — not this in-memory queue.
- */
+/** Per-session FIFO execution. */
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import { log } from "../../log.js";
 import { beginWork } from "../busy.js";
+import { portError } from "../../effect-port.js";
 export function createTurnQueue(opts) {
     const { label, run, onQueuedBehind } = opts;
-    // Per-session serial chains: a second turn for the same session waits its turn (FIFO) instead of
-    // colliding on the engine lease and being dropped as "busy". Different sessions run concurrently.
     const chains = new Map();
     return {
         accept(rec) {
             if (chains.has(rec.session))
                 onQueuedBehind?.(rec);
-            // Process-wide busy signal (busy.ts): an accepted turn counts as in-flight work from acceptance
-            // until its run settles — serving surfaces that must not idle mid-turn (the AgentCore adapter's
-            // /ping) read it. Counted here, not in run(), so a QUEUED turn (accepted, waiting on the chain)
-            // already reads as busy.
+            const prev = chains.get(rec.session);
+            // Admission counts immediately, including while waiting behind another turn.
             const workDone = beginWork();
-            const prev = chains.get(rec.session) ?? Promise.resolve();
-            const task = async () => {
-                try {
-                    await run(rec);
-                }
-                catch (e) {
-                    log.error(`${label} turn runner rejected (session=${rec.session}; own your error surface in run()): ${String(e)}`);
-                }
-            };
-            const next = prev.then(task, task); // run after this session's previous turn, in arrival order
-            chains.set(rec.session, next);
-            void next.finally(() => {
+            const fiber = Effect.runFork(Effect.scoped(Effect.gen(function* () {
+                // Publish the tail before execution can finish or submit another turn.
+                yield* Effect.yieldNow;
+                if (prev)
+                    yield* Fiber.await(prev);
+                yield* run(rec);
+            })).pipe(Effect.catchCause((cause) => Effect.sync(() => log.error(`${label} turn runner rejected (session=${rec.session}; own your error surface in run()): ${String(portError(cause))}`))), Effect.ensuring(Effect.sync(() => {
                 workDone();
-                if (chains.get(rec.session) === next)
-                    chains.delete(rec.session); // drop the entry when drained
-            });
+                if (chains.get(rec.session) === fiber)
+                    chains.delete(rec.session);
+            }))));
+            chains.set(rec.session, fiber);
         },
-        async idle() {
-            // Await outstanding chains until none remain — a chain may schedule a follow-up turn, and each
-            // deletes its own map entry on settle, so an emptied map means every turn ran to completion. The
-            // tasks catch their own rejections, but allSettled keeps idle() itself total regardless.
+        idle: () => Effect.runPromise(Effect.gen(function* () {
+            // A finishing turn may enqueue more work.
             while (chains.size > 0)
-                await Promise.allSettled([...chains.values()]);
-        },
+                yield* Fiber.awaitAll([...chains.values()]);
+        })),
     };
 }

package/dist/channels/kit/turn-runner.d.ts

@@ -1,7 +1,13 @@
+/** The durable-turn LIFECYCLE the stateful chat channels share, over the kit's parts. */
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import { type PortFailure } from "../../effect-port.ts";
 import type { ContextBuffer } from "./context-buffer.ts";
 import { type TurnRecordBase, type TurnStore } from "./turn-store.ts";
-/** A pending turn is the persisted intent minus its attempt count, plus live-only fields the
- *  channel adds (a notice's message id) — never persisted, reconstructed fresh on replay. */
+/**
+ * A pending turn is the persisted intent minus its attempt count, plus live-only fields the channel adds (a notice's
+ * message id).
+ */
 export type PendingBase<S extends TurnRecordBase> = Omit<S, "attempts">;
 export interface TurnRunnerOptions<R extends PendingBase<S>, S extends TurnRecordBase, E> {
     label: string;
@@ -19,40 +25,48 @@ export interface TurnRunnerOptions<R extends PendingBase<S>, S extends TurnRecor
     bufferKey(rec: R): string;
     /** The place, for the lifecycle log line (`chat=… thread=…`). */
     where(rec: R): string;
-    /** Queue feedback when a turn is scheduled BEHIND an active one. Returns what the runner awaits at
-     *  dequeue (so the turn reliably takes the notice over instead of racing it) and, optionally, how
-     *  to cancel a notice that has not fired yet. `done` may reject — posting the notice is a platform
-     *  call — and the runner logs that and runs the turn anyway. */
+    /** Queue feedback when a turn is scheduled BEHIND an active one. */
     onQueuedBehind?(rec: R): {
         done: Promise<void>;
         cancel?: () => void;
     };
-    /** Runs before the attempt is counted. Answer false to leave the intent untouched for a later run
-     *  (Slack: its transport is known to be down, so an Agent turn now would have nowhere to answer). */
+    /** Runs before the attempt is counted. */
     beforeRun?(rec: R): Promise<boolean>;
-    /** The attempt could not be recorded (disk failure): a restart replays the turn, so say so on any
-     *  notice it holds rather than leaving it pinned at "Queued". */
+    /**
+     * The attempt could not be recorded (disk failure): a restart replays the turn, so say so on any notice it holds
+     * rather than leaving it pinned at "Queued".
+     */
     onDeferred(rec: R): void;
     /** The turn started the ceiling's worth of times without finishing: tell the asker. */
     notifyDropped(rec: R): void;
-    /** Run the turn. `onCompleted` is the durable-commit point (the turn's `completed` event): it drops
-     *  the intent and commits the folded discussion, in that order. A throw is logged as the turn's
-     *  failure; the intent is dropped either way. */
     execute(rec: R, discussion: {
         text: string;
         consumed: E[];
-    }, onCompleted: () => void): Promise<void>;
+    }, 
+    /** Called with the finished reply just before it is delivered — the point the answer becomes recoverable. */
+    onAnswered: (answer: string) => void): Effect.Effect<void, PortFailure, Scope.Scope>;
+    /**
+     * Deliver an answer a previous run generated but never confirmed delivering: no model, no tools, and no live
+     * preview — the one the answer was written for died with its process.
+     *
+     * A notice THIS process put up is a different thing and must still be settled: a record recovered behind another
+     * turn in the same session goes through `onQueuedBehind` like any other, so it can hold a fresh "queued" message
+     * or status that only this call can take over or clear.
+     */
+    deliverAnswer(rec: R, answer: string): Effect.Effect<void, PortFailure, Scope.Scope>;
 }
 export interface TurnRunner<R, S> {
-    /** Accept a turn: persist its intent (pre-ACK — a failed write throws so the platform redelivers),
-     *  record the delivery id, enqueue. Recovery re-enqueues without re-persisting. */
+    /**
+     * Accept a turn: persist its intent (pre-ACK — a failed write throws so the platform redelivers), record the
+     * delivery id, enqueue.
+     */
     submit(rec: R, persist: boolean): void;
-    /** Re-enqueue the turns a prior crash left mid-flight; returns them so a channel can continue its
-     *  arrival counter. */
+    /** Re-enqueue the turns a prior crash left mid-flight; returns them so a channel can continue its arrival counter. */
     recover(): S[];
     /** Resolve once no turn is in flight — the test/observability seam. */
     idle(): Promise<void>;
 }
+export declare function runQueuedTurn<R extends PendingBase<S>, S extends TurnRecordBase, E>(options: TurnRunnerOptions<R, S, E>, rec: R): Effect.Effect<void, PortFailure>;
 export declare function createTurnRunner<R extends PendingBase<S> & {
     id: string;
     session: string;

package/dist/channels/kit/turn-runner.js

@@ -1,66 +1,111 @@
-/**
- * The durable-turn LIFECYCLE the stateful chat channels share, over the kit's parts: accept
- * (persist pre-ACK, dedup, enqueue) → dequeue (settle the queue notice, count the attempt against
- * the poison ceiling, fold the buffered discussion) → execute → end (log, drop the intent). Telegram,
- * Slack and Feishu each wrote this out; the copies had already drifted in small ways that were not
- * decisions (which one deletes its notice on defer, which one logs the duration on failure).
- *
- * What stays with the platform is everything that names a platform object: how a queue notice is
- * mounted and taken over, what the prompt looks like, how attachments resolve, what a dropped turn
- * says and where. Those arrive as hooks; the ORDER they run in is this module's.
- */
+/** The durable-turn LIFECYCLE the stateful chat channels share, over the kit's parts. */
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import { log } from "../../log.js";
+import { portError, portJoin } from "../../effect-port.js";
 import { createTurnQueue } from "./turn-queue.js";
 import { commitAnsweredTurn } from "./turn-store.js";
+export function runQueuedTurn(options, rec) {
+    return Effect.gen(function* () {
+        const { label, store, buffer, beforeRun } = options;
+        if (beforeRun && !(yield* portJoin(() => beforeRun(rec))))
+            return;
+        const decision = store.startAttempt(rec.id);
+        if (decision === "exceeded") {
+            const stranded = rec.answer;
+            if (stranded === undefined) {
+                options.notifyDropped(rec);
+                return;
+            }
+            // The ceiling is about EXECUTION — a turn that may be crashing the process must stop being run. Delivering a
+            // recorded answer costs one message and no model call, so the record the store just dropped gets one last
+            // send instead of "please ask again" over an answer that exists.
+            return yield* Effect.scoped(options.deliverAnswer(rec, stranded)).pipe(Effect.matchEffect({
+                // The store has already said, at error level, that this turn will not be run again. Silence after that
+                // reads as "nothing happened"; this line is what distinguishes it from a delivered answer.
+                onSuccess: () => Effect.sync(() => log.info(`${label} turn ${rec.id} hit the execution ceiling, but the answer it had already recorded was ` +
+                    `delivered (session=${rec.session})`)),
+                onFailure: (error) => Effect.sync(() => {
+                    log.error(`${label} turn ${rec.id} hit the execution ceiling and its recorded answer could not be delivered ` +
+                        `either (session=${rec.session}) — the answer is gone: ${String(error.cause)}`);
+                    // The record is off disk, so nothing will retry this. The asker is owed an ending — without one, a
+                    // queue notice this turn put up stays in the chat forever reading "Queued".
+                    options.notifyDropped(rec);
+                }),
+            }));
+        }
+        if (decision === "defer") {
+            options.onDeferred(rec);
+            return;
+        }
+        const startedAt = Date.now();
+        // A recovered answer skips the buffer entirely: its discussion was committed when the answer was recorded, and
+        // peeking again would consume entries this turn never folded in.
+        const recovered = rec.answer;
+        let answered = recovered !== undefined;
+        // One stable prefix, so every `turn done:`/`turn failed:` has a `turn start:` to grep back to; what kind of work
+        // it is rides along as a field.
+        log.info(`${label} turn start: turn=${rec.id} session=${rec.session} ${options.where(rec)}` +
+            `${recovered === undefined ? "" : " mode=re-delivery (answer recovered from a prior run)"}`);
+        const work = recovered !== undefined
+            ? Effect.suspend(() => options.deliverAnswer(rec, recovered))
+            : Effect.suspend(() => {
+                const bufferKey = options.bufferKey(rec);
+                const discussion = buffer.peek(bufferKey);
+                return options.execute(rec, discussion, (answer) => {
+                    // Only a recorded answer is recoverable — an untracked run has no record to keep it in.
+                    answered = commitAnsweredTurn(store, buffer, {
+                        id: rec.id,
+                        bufferKey,
+                        consumed: discussion.consumed,
+                        answer,
+                    });
+                });
+            });
+        const delivered = yield* Effect.scoped(work).pipe(Effect.matchEffect({
+            onSuccess: () => Effect.sync(() => {
+                log.info(`${label} turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
+                return true;
+            }),
+            onFailure: (error) => Effect.sync(() => {
+                log.error(`${label} turn failed: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms): ${String(error.cause)}`);
+                return false;
+            }),
+        }));
+        // An answer that exists but did not reach the chat is the one failure worth another start: re-delivering it costs
+        // one message and no model call, and `startAttempt` bounds how often that is tried. Everything else — delivered,
+        // or failed before there was an answer — is done here. Interruption never reaches this removal.
+        if (delivered || !answered) {
+            store.remove(rec.id);
+            return;
+        }
+        log.warn(`${label} turn ${rec.id} produced an answer that was not delivered (session=${rec.session}) — ` +
+            `keeping it to re-deliver on the next start`);
+    });
+}
 export function createTurnRunner(options) {
-    const { label, store, buffer, seen, onQueuedBehind } = options;
+    const { label, store, seen, onQueuedBehind } = options;
     const notices = new Map();
     const queue = createTurnQueue({
         label,
-        onQueuedBehind: onQueuedBehind && ((rec) => notices.set(rec.id, onQueuedBehind(rec))),
-        run: async (rec) => {
-            // Runs at DEQUEUE time (serialized). The queue wait is over: cancel a notice that has not
-            // fired, then settle so the turn's preview handle is final — in the common path this await is
-            // instant. BEFORE the ceiling check so a dropped or deferred turn can take the notice over too.
+        onQueuedBehind: onQueuedBehind &&
+            ((rec) => {
+                const notice = onQueuedBehind(rec);
+                // Observe rejection at acceptance, even if dequeue is minutes away.
+                const done = Effect.runFork(portJoin(() => notice.done).pipe(Effect.catchCause((cause) => Effect.sync(() => log.warn(`${label} queue notice failed: turn=${rec.id} session=${rec.session}: ${String(portError(cause))}`)))));
+                notices.set(rec.id, { done, cancel: notice.cancel });
+            }),
+        run: (rec) => Effect.gen(function* () {
             const notice = notices.get(rec.id);
-            notice?.cancel?.();
-            // The notice is the PLATFORM's feedback, not the turn: a failed post must not throw out of the
-            // run, which would leak the persisted intent (removed only below) into a replay that burns an
-            // attempt against the ceiling. Logged, then the turn proceeds without its handle.
-            await notice?.done.catch((error) => log.warn(`${label} queue notice failed: turn=${rec.id} session=${rec.session}: ${String(error)}`));
             notices.delete(rec.id);
-            if (options.beforeRun && !(await options.beforeRun(rec)))
-                return;
-            const decision = store.startAttempt(rec.id);
-            if (decision === "exceeded") {
-                options.notifyDropped(rec);
-                return;
+            if (notice) {
+                // A broken cancel hook must still join any post already in flight.
+                yield* Effect.addFinalizer(() => Fiber.await(notice.done));
+                notice.cancel?.();
+                yield* Fiber.await(notice.done);
             }
-            if (decision === "defer") {
-                options.onDeferred(rec);
-                return;
-            }
-            const startedAt = Date.now();
-            log.info(`${label} turn start: turn=${rec.id} session=${rec.session} ${options.where(rec)}`);
-            // Snapshot the discussion at dequeue; commit only this snapshot on `completed`, so a message
-            // arriving while the turn runs stays buffered for the next answered turn.
-            const bufferKey = options.bufferKey(rec);
-            const discussion = buffer.peek(bufferKey);
-            try {
-                await options.execute(rec, discussion, () => commitAnsweredTurn(store, buffer, { id: rec.id, bufferKey, consumed: discussion.consumed }));
-                log.info(`${label} turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
-            }
-            catch (error) {
-                log.error(`${label} turn failed: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms): ${String(error)}`);
-            }
-            finally {
-                // Fallback removal for the caught-error paths (a `failed` event or a transport throw): those
-                // never reach the completed hook. Idempotent. Only an INTERRUPTED run (this finally never
-                // runs — a crash or SIGTERM deploy) leaves the record for replay; a transport throw is
-                // dropped, not retried (safe retry needs an L2 delivery key).
-                store.remove(rec.id);
-            }
-        },
+            yield* runQueuedTurn(options, rec);
+        }),
     });
     const submit = (rec, persist) => {
         if (persist) {

package/dist/channels/kit/turn-store.d.ts

@@ -1,58 +1,58 @@
 import type { ContextBuffer } from "./context-buffer.ts";
-/** What every persisted turn record carries regardless of channel: identity, the session whose FIFO
- *  chain it runs on, and how many times it has STARTED executing without finishing (0 until its first
- *  run; bumped at each `startAttempt`). The channel's record type extends this with everything its
- *  runner needs to re-execute the turn — a new execution field added there propagates into the
- *  persisted record by construction. */
+/** What every persisted turn record carries regardless of channel. */
 export interface TurnRecordBase {
     id: string;
     session: string;
     attempts: number;
+    /**
+     * The completed reply, recorded BEFORE it is delivered. Its presence is the difference between the two things a
+     * pending record can mean: absent = the turn still has to run, present = the model already ran and only delivery
+     * is owed. A restart therefore re-delivers an answer instead of paying for it again.
+     */
+    answer?: string;
 }
 export interface TurnStore<T extends TurnRecordBase> {
-    /** Persist an accepted turn before the ACK. A failed write throws (→ HTTP response / WS ACK 500, so the platform redelivers). */
+    /** Persist an accepted turn before the ACK. */
     add(rec: T): void;
-    /** Remove a finished turn. Post-ACK: a failed write is logged, never thrown (must not abort delivery). */
+    /**
+     * Record the completed reply so a restart can deliver it without running the turn again. `false` = there was no
+     * record to write it to (an untracked run), so this answer has no recovery copy.
+     */
+    answered(id: string, answer: string): boolean;
     remove(id: string): void;
-    /** Every persisted turn a crash left behind, in ARRIVAL order (the channel's `order`), to re-enqueue
-     *  on the next start. Read-only — the ceiling is enforced per turn at `startAttempt`, so a never-run
-     *  turn's budget is untouched by a restart. Order matters: the queue rebuilds each session's FIFO
-     *  chain from re-enqueue order. */
+    /**
+     * Every persisted turn a crash left behind, in ARRIVAL order (the channel's `order`), to re-enqueue on the next
+     * start.
+     */
     recover(): T[];
-    /** Called when a turn is about to RUN (dequeued). Returns:
-     *   - "run": bumped its persisted execution count; go ahead.
-     *   - "exceeded": over {@link MAX_TURN_ATTEMPTS} starts without finishing (killed mid-run every time,
-     *     whatever the cause); the record is dropped and the runner notifies the asker.
-     *   - "defer": the bump could not be persisted — skip this cycle (fail closed: an unpersisted count
-     *     would let a poison turn re-run forever); the record stays on disk and replays on the next start
-     *     (a restart is required — disk recovery alone does not re-run it). The runner does NOT notify.
-     *  An id with no record returns "run" (untracked): a completed turn's `remove` cleared it, so the
-     *  redelivery-double-run tail (see the header's pre-ACK window) lands here. */
+    /** Called when a turn is about to RUN (dequeued). */
     startAttempt(id: string): "run" | "exceeded" | "defer";
 }
 export interface TurnStoreOptions<T extends TurnRecordBase> {
     /** Log prefix naming the consumer (e.g. "[telegram]") — the store itself is channel-neutral. */
     label: string;
-    /** Shape validation at the IO boundary: valid JSON of the WRONG SHAPE must degrade like a corrupt
-     *  file (warn + empty), not flow in as trusted data. */
+    /**
+     * Shape validation at the IO boundary: valid JSON of the WRONG SHAPE must degrade like a corrupt file (warn +
+     * empty), not flow in as trusted data.
+     */
     isRecord: (t: unknown) => t is T;
-    /** Arrival order for {@link TurnStore.recover} — the channel knows what its ids/fields encode
-     *  (telegram: numeric update_id; lark: an explicit per-record seq). */
+    /**
+     * Arrival order for {@link TurnStore.recover} — the channel knows what its ids/fields encode (telegram: numeric
+     * update_id; lark: an explicit per-record seq).
+     */
     order: (a: T, b: T) => number;
 }
 /**
- * End an ANSWERED turn: drop its durable intent, then commit the discussion it folded in.
+ * An ANSWERED turn: record the reply for delivery, then commit the discussion it folded in. The intent is NOT
+ * dropped here — generating an answer is not the same event as that answer reaching the chat, and the runner drops
+ * the record only once delivery has settled.
  *
- * The ORDER is the safety property, which is why this is a function and not two lines at each call
- * site. A crash between the two writes may re-fold already-answered context into the next summon —
- * additive and harmless. The reverse order leaves intent on disk with its context already consumed,
- * so the replay runs the same turn with its context stripped.
- *
- * Called from the turn's `completed` event, when the fold provably lives in the durable session.
+ * Returns whether the answer became recoverable, so a caller does not claim a recovery that has nothing on disk.
  */
 export declare function commitAnsweredTurn<T extends TurnRecordBase, E>(store: TurnStore<T>, buffer: ContextBuffer<E>, turn: {
     id: string;
     bufferKey: string;
     consumed: E[];
-}): void;
+    answer: string;
+}): boolean;
 export declare function createTurnStore<T extends TurnRecordBase>(path: string, opts: TurnStoreOptions<T>): TurnStore<T>;