@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/channels/kit/delivery.d.ts

@@ -0,0 +1,35 @@
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import type { AgentEvent } from "../../agent.ts";
+import type { ChannelFailure } from "./preview-kit.ts";
+import { PortFailure } from "../../effect-port.ts";
+/** Snapshot/edit renderers share terminal ownership; platform-specific settle policies stay injected. */
+export declare function renderReply(events: Stream.Stream<AgentEvent, PortFailure>, opts: {
+    label: string;
+    onEvent: (event: AgentEvent) => void;
+    finish: Effect.Effect<void>;
+    answer: () => string;
+    settle: (text: string) => Effect.Effect<void, PortFailure>;
+    formatError: (failure: ChannelFailure) => string | undefined;
+    /** The finished reply, handed over before it is delivered — where a channel records it for recovery. */
+    onAnswered?: (answer: string) => void;
+}): Effect.Effect<void, PortFailure, Scope.Scope>;
+export interface PreviewPump {
+    touch(): void;
+    /** Cancel pacing, join an issued write, and prevent any subsequent frame. */
+    finish: Effect.Effect<void>;
+}
+export declare function previewPump(opts: {
+    flush: () => Promise<void>;
+    throttleMs: number;
+    /** Slack's mutation slot precedes a write; stopping the pump can discard this pending frame. */
+    beforeFlush?: Effect.Effect<void>;
+    onError: (error: unknown) => void;
+}): Effect.Effect<PreviewPump, never, Scope.Scope>;
+export interface SerialWriter {
+    enqueue(work: () => Promise<void>): void;
+    /** End admission and join every accepted operation, including its caller-owned failure policy. */
+    finish: Effect.Effect<void, PortFailure>;
+}
+export declare function serialWriter(): Effect.Effect<SerialWriter, never, Scope.Scope>;

package/dist/channels/kit/delivery.js

@@ -0,0 +1,129 @@
+/** Scoped outbound writers. Frames coalesce; native append/status operations retain every queued write. */
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
+import { log } from "../../log.js";
+import { PortFailure, portJoin } from "../../effect-port.js";
+/** Snapshot/edit renderers share terminal ownership; platform-specific settle policies stay injected. */
+export function renderReply(events, opts) {
+    return Effect.gen(function* () {
+        let finalized = false;
+        const notify = (failure, phase) => Effect.try({ try: () => opts.formatError(failure) ?? "", catch: (cause) => new PortFailure(cause) }).pipe(Effect.flatMap(opts.settle), Effect.catchTag("PortFailure", (error) => Effect.sync(() => log.error(`${opts.label} failed to deliver the ${phase} notice: ${String(error.cause)}`))));
+        yield* Effect.addFinalizer(() => Effect.gen(function* () {
+            yield* opts.finish;
+            if (!finalized)
+                yield* notify({ details: "the turn ended without completing", retryable: false }, "abnormal-turn");
+        }));
+        yield* Stream.runForEachWhile(events, (event) => {
+            if (event.type !== "completed" && event.type !== "failed") {
+                return Effect.try({
+                    try: () => {
+                        opts.onEvent(event);
+                        return true;
+                    },
+                    catch: (cause) => new PortFailure(cause),
+                });
+            }
+            return Effect.gen(function* () {
+                yield* opts.finish;
+                finalized = true;
+                if (event.type === "completed") {
+                    const answer = opts.answer();
+                    yield* Effect.try({
+                        try: () => opts.onAnswered?.(answer),
+                        catch: (cause) => new PortFailure(cause),
+                    });
+                    yield* opts.settle(answer);
+                }
+                else {
+                    yield* notify({
+                        details: event.details,
+                        retryable: event.retryable,
+                        ...(event.code !== undefined ? { code: event.code } : {}),
+                    }, "agent-failure");
+                    return yield* Effect.fail(new PortFailure(new Error(`agent failed: ${event.details} (retryable=${event.retryable})`)));
+                }
+                return false;
+            }).pipe(Effect.uninterruptible);
+        });
+        if (!finalized)
+            yield* Effect.fail(new PortFailure(new Error("stream ended without a terminal event")));
+    });
+}
+export function previewPump(opts) {
+    return Effect.gen(function* () {
+        const scope = yield* Effect.scope;
+        const run = Effect.runSyncWith(yield* Effect.context());
+        let fiber;
+        let stopped = false;
+        let dirty = false;
+        let reported = false;
+        const work = Effect.gen(function* () {
+            while (dirty && !stopped) {
+                dirty = false;
+                if (opts.beforeFlush)
+                    yield* opts.beforeFlush;
+                // An issued mutation may have reached the platform. Join it, including publishing its id
+                // and diagnosing its outcome, before the final writer takes over.
+                yield* portJoin(opts.flush).pipe(Effect.catchTag("PortFailure", (error) => Effect.sync(() => {
+                    if (!reported) {
+                        reported = true;
+                        opts.onError(error.cause);
+                    }
+                })), Effect.uninterruptible);
+                if (dirty && !stopped)
+                    yield* Effect.sleep(opts.throttleMs);
+            }
+        });
+        const finish = Effect.gen(function* () {
+            stopped = true;
+            if (!fiber)
+                return;
+            yield* Fiber.interrupt(fiber);
+            const exit = yield* Fiber.await(fiber);
+            if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause))
+                yield* Effect.failCause(exit.cause);
+        });
+        yield* Effect.addFinalizer(() => finish);
+        return {
+            touch: () => {
+                if (stopped)
+                    return;
+                dirty = true;
+                const exit = fiber?.pollUnsafe();
+                if (fiber && (!exit || Exit.isFailure(exit)))
+                    return;
+                // The first placeholder starts before a fast source can reach its terminal event.
+                fiber = run(Effect.forkIn(work, scope, { startImmediately: true }));
+            },
+            finish,
+        };
+    });
+}
+export function serialWriter() {
+    return Effect.gen(function* () {
+        const queue = yield* Queue.unbounded();
+        const work = Effect.gen(function* () {
+            for (;;) {
+                const next = yield* Queue.take(queue);
+                yield* portJoin(next).pipe(Effect.uninterruptible);
+            }
+        }).pipe(Effect.catchTag("Done", () => Effect.void));
+        const fiber = yield* Effect.forkScoped(work);
+        const finish = Effect.sync(() => {
+            Queue.endUnsafe(queue);
+        }).pipe(Effect.andThen(Fiber.join(fiber)));
+        // This finalizer precedes forkScoped's interruption: accepted append/status writes must drain.
+        yield* Effect.addFinalizer(() => finish.pipe(Effect.orDie));
+        return {
+            enqueue: (next) => {
+                if (!Queue.offerUnsafe(queue, next))
+                    throw new Error("delivery writer is closed");
+            },
+            finish,
+        };
+    });
+}

package/dist/channels/kit/event-stream.d.ts

@@ -0,0 +1,5 @@
+import type * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import { PortFailure } from "../../effect-port.ts";
+/** Acquire lazily; interruption closes the source, while natural exhaustion needs no extra return. */
+export declare function eventStream<A>(open: () => AsyncIterable<A>, label: string): Stream.Stream<A, PortFailure, Scope.Scope>;

package/dist/channels/kit/event-stream.js

@@ -0,0 +1,29 @@
+/** Own an Agent's AsyncIterable inside a typed, demand-driven channel stream. */
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { log } from "../../log.js";
+import { PortFailure } from "../../effect-port.js";
+/** Acquire lazily; interruption closes the source, while natural exhaustion needs no extra return. */
+export function eventStream(open, label) {
+    return Stream.fromPull(Effect.gen(function* () {
+        let exhausted = false;
+        const iterator = yield* Effect.acquireRelease(Effect.try({ try: () => open()[Symbol.asyncIterator](), catch: (cause) => new PortFailure(cause) }), (iterator) => {
+            const close = iterator.return?.bind(iterator);
+            if (!close || exhausted)
+                return Effect.void;
+            return Effect.promise(close).pipe(Effect.onError((cause) => Effect.sync(() => log.warn(`${label} source cleanup failed: ${String(Cause.squash(cause))}`))));
+        });
+        return Effect.gen(function* () {
+            const result = yield* Effect.tryPromise({
+                try: () => iterator.next(),
+                catch: (cause) => new PortFailure(cause),
+            });
+            if (result.done) {
+                exhausted = true;
+                return yield* Cause.done();
+            }
+            return [result.value];
+        });
+    }));
+}

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

@@ -1,20 +1,32 @@
+import * as Stream from "effect/Stream";
+import { type Agent, type AgentEvent, type Prompt, type Scope } from "../../agent.ts";
+import { type PortFailure } from "../../effect-port.ts";
 /**
- * Shared pieces of the channels' invoke-turn modules (telegram/feishu/slack `invoke-turn.ts`) — the
- * halves that are channel-independent, so a retry-policy or prompt-wording change lands ONCE:
- *
- *   - {@link streamTurnWithBusyRetry}: the busy-retry loop around `agent.invoke`, with the
- *     `onCompleted` durable-commit point;
- *   - the prompt-suffix wording: {@link attachedFilesManifest}, {@link backgroundImagesManifest},
- *     {@link missingAttachmentsNote}, {@link attributedFileName}.
- *
- * None of it asks what the agent can DO with an attachment. A channel resolves platform resources and
- * states what it found; deciding whether to open a file is the agent's, and one assembled without a
- * file tool answers that it cannot — visibly, at the moment it is asked.
+ * One turn, end to end: resolve the platform inputs, then stream `agent.invoke` with the shared
+ * busy-wait. All three chat channels wrote this out, and the copies had already disagreed about the
+ * one thing that is actually a per-platform judgement (whether a load failure is worth a redelivery)
+ * while agreeing on everything that is not.
  *
- * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
- * message-scoped Feishu keys, Slack file objects) are real differences.
+ * A resolution failure becomes a `failed` EVENT. It must never throw out of the stream: the SPEC
+ * forbids it (MUST 2), and the turn's own settlement path is what tells the user — an exception here
+ * would take the reply with it.
  */
-import { type Agent, type AgentEvent, type Prompt, type Scope } from "../../agent.ts";
+export declare function turnStream<R>(opts: {
+    agent: Agent;
+    label: string;
+    /** Resolve this turn's platform inputs (download attachments, walk a reply chain). */
+    resolve: () => Promise<R>;
+    /** What the resolved inputs make of the turn: where it runs, and what it asks. */
+    turn: (resolved: R) => {
+        scope: Scope;
+        prompt: Prompt;
+    };
+    /** Whether a failed resolution is worth a platform redelivery. Stated per channel because it IS a
+     *  platform question — Slack reads its API error's status, and a transport that cannot tell says
+     *  yes, since a retried download is cheap next to an unanswered ask. */
+    retryableLoadFailure: (cause: unknown) => boolean;
+    busyRetry?: BusyRetry;
+}): Stream.Stream<AgentEvent, PortFailure>;
 /** How the busy-wait paces: retry the invoke every `delayMs` while the session's lease is held by an
  *  EXTERNAL turn (a self-scheduled wake, a concurrent embedder invoke), up to `maxWaitMs` total. The
  *  channel's own turns never collide (the turn-queue serializes per session), so a busy reject here is
@@ -25,12 +37,10 @@ export interface BusyRetry {
 }
 export declare const DEFAULT_BUSY_RETRY: BusyRetry;
 /**
- * Stream one Agent turn with the shared busy-wait. `onCompleted` (if given) fires on the turn's
- * `completed` event — the durable-commit point: only then does the turn provably live in the session,
- * so a failure or crash at ANY earlier point leaves the caller's pre-ACK state (turn intent, context
- * buffer) intact for replay/the next summon. The caller uses it to remove the turn intent AND commit
- * the context buffer, in that order, so a crash between the two clears cannot replay a
- * context-stripped turn.
+ * Stream one Agent turn with the shared busy-wait. The durable-commit point is NOT here: an answer becomes durable
+ * where its text is known and about to be written to the chat (the renderer's `onAnswered`), because "the model
+ * finished" and "the user has it" are different events. Source pulls remain demand-driven, including while final
+ * platform delivery runs.
  *
  * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn holds this session's
  * lease and OUR turn never started — replay-safe. Retry (bounded) instead of yielding it: the user
@@ -39,14 +49,31 @@ export declare const DEFAULT_BUSY_RETRY: BusyRetry;
  * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
  * is ever re-run.
  */
-export declare function streamTurnWithBusyRetry(agent: Agent, 
-/** The full scope, not a session string — channels that set extension fields (lineage) pass them
- *  through here; channels that don't pass `{ session }` and nothing changes. */
-scope: Scope, prompt: Prompt, options: {
+export declare function busyRetryStream(agent: Agent, scope: Scope, prompt: Prompt, { label, busyRetry }: {
     label: string;
-    onCompleted?: () => void;
     busyRetry?: BusyRetry;
-}): AsyncIterable<AgentEvent>;
+}): Stream.Stream<AgentEvent, PortFailure>;
+/**
+ * Load the turn's BACKGROUND refs — what was folded in from earlier un-summoned discussion, not the
+ * ask itself. Per-ref degradation is the whole meaning of that tier: one expired file costs a warn
+ * and a place in the missing-attachments count ({@link missingAttachmentsNote}), never the answer it
+ * merely accompanies, and never its still-readable siblings. Parallel, input order kept.
+ *
+ * PRIMARY refs are the opposite policy and stay with their channel: a failure there throws, so the
+ * agent never runs on an input the user pointed at and we failed to load.
+ *
+ * Shared by all three channels; `what` is the only part that is the platform's.
+ */
+export declare function loadBackground<R, T>(refs: readonly R[], load: (ref: R) => Promise<T>, opts: {
+    label: string;
+    what: string;
+}): Promise<{
+    loaded: {
+        ref: R;
+        value: T;
+    }[];
+    lost: number;
+}>;
 /** What the attached-files manifest renders per file: display name, byte size, absolute local path. */
 export interface ManifestFile {
     name: string;

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

@@ -2,8 +2,9 @@
  * Shared pieces of the channels' invoke-turn modules (telegram/feishu/slack `invoke-turn.ts`) — the
  * halves that are channel-independent, so a retry-policy or prompt-wording change lands ONCE:
  *
- *   - {@link streamTurnWithBusyRetry}: the busy-retry loop around `agent.invoke`, with the
- *     `onCompleted` durable-commit point;
+ *   - {@link turnStream}: resolve inputs → ask the agent, with a load failure arriving as a `failed`
+ *     EVENT rather than a thrown iteration (SPEC MUST 2);
+ *   - {@link busyRetryStream}: the busy-retry loop around `agent.invoke`;
  *   - the prompt-suffix wording: {@link attachedFilesManifest}, {@link backgroundImagesManifest},
  *     {@link missingAttachmentsNote}, {@link attributedFileName}.
  *
@@ -12,10 +13,39 @@
  * file tool answers that it cannot — visibly, at the moment it is asked.
  *
  * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
- * message-scoped Feishu keys, Slack file objects) are real differences.
+ * message-scoped Feishu keys, Slack file objects) are real differences. The two TIERS' failure
+ * policies are not: see {@link loadBackground}.
  */
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
 import { SESSION_BUSY_CODE } from "../../agent.js";
+import { eventStream } from "./event-stream.js";
+import { portJoin } from "../../effect-port.js";
 import { log } from "../../log.js";
+/**
+ * One turn, end to end: resolve the platform inputs, then stream `agent.invoke` with the shared
+ * busy-wait. All three chat channels wrote this out, and the copies had already disagreed about the
+ * one thing that is actually a per-platform judgement (whether a load failure is worth a redelivery)
+ * while agreeing on everything that is not.
+ *
+ * A resolution failure becomes a `failed` EVENT. It must never throw out of the stream: the SPEC
+ * forbids it (MUST 2), and the turn's own settlement path is what tells the user — an exception here
+ * would take the reply with it.
+ */
+export function turnStream(opts) {
+    return Stream.unwrap(portJoin(opts.resolve).pipe(Effect.map((resolved) => {
+        const { scope, prompt } = opts.turn(resolved);
+        return busyRetryStream(opts.agent, scope, prompt, {
+            label: opts.label,
+            ...(opts.busyRetry ? { busyRetry: opts.busyRetry } : {}),
+        });
+    }), Effect.catchTag("PortFailure", ({ cause }) => Effect.succeed(Stream.succeed({
+        type: "failed",
+        details: `could not load attachment: ${String(cause)}`,
+        retryable: opts.retryableLoadFailure(cause),
+    })))));
+}
 // Each retry is a lease-check-level reject (tryAcquire runs before the session is bound) — waiting is nearly
 // free, and the loop exits within one delay of the holder finishing. So the cap is sized to outlast a
 // real tool-using wake turn (minutes), not to be short: 10 min. CEILING: a holder that runs longer than
@@ -23,12 +53,10 @@ import { log } from "../../log.js";
 // turn forever.
 export const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
 /**
- * Stream one Agent turn with the shared busy-wait. `onCompleted` (if given) fires on the turn's
- * `completed` event — the durable-commit point: only then does the turn provably live in the session,
- * so a failure or crash at ANY earlier point leaves the caller's pre-ACK state (turn intent, context
- * buffer) intact for replay/the next summon. The caller uses it to remove the turn intent AND commit
- * the context buffer, in that order, so a crash between the two clears cannot replay a
- * context-stripped turn.
+ * Stream one Agent turn with the shared busy-wait. The durable-commit point is NOT here: an answer becomes durable
+ * where its text is known and about to be written to the chat (the renderer's `onAnswered`), because "the model
+ * finished" and "the user has it" are different events. Source pulls remain demand-driven, including while final
+ * platform delivery runs.
  *
  * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn holds this session's
  * lease and OUR turn never started — replay-safe. Retry (bounded) instead of yielding it: the user
@@ -37,31 +65,60 @@ export const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
  * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
  * is ever re-run.
  */
-export async function* streamTurnWithBusyRetry(agent, 
-/** The full scope, not a session string — channels that set extension fields (lineage) pass them
- *  through here; channels that don't pass `{ session }` and nothing changes. */
-scope, prompt, options) {
-    const { label, onCompleted, busyRetry = DEFAULT_BUSY_RETRY } = options;
-    const session = scope.session;
-    const deadline = Date.now() + busyRetry.maxWaitMs;
-    for (;;) {
-        let retryBusy = false;
-        let first = true;
-        for await (const e of agent.invoke(scope, prompt)) {
-            if (first && e.type === "failed" && e.code === SESSION_BUSY_CODE && Date.now() + busyRetry.delayMs < deadline) {
-                retryBusy = true; // fail-fast reject — the stream ends after this event; wait and re-invoke
-                break;
-            }
-            first = false;
-            if (e.type === "completed")
-                onCompleted?.(); // the turn is durably in the session — commit point
-            yield e;
+export function busyRetryStream(agent, scope, prompt, { label, busyRetry = DEFAULT_BUSY_RETRY }) {
+    return Stream.unwrap(Effect.map(Clock.currentTimeMillis, (started) => {
+        const deadline = started + busyRetry.maxWaitMs;
+        const attempt = () => Stream.suspend(() => {
+            let retryBusy = false;
+            let first = true;
+            return eventStream(() => agent.invoke(scope, prompt), `${label} (session=${scope.session})`).pipe(Stream.takeWhileEffect((event) => Effect.gen(function* () {
+                if (first &&
+                    event.type === "failed" &&
+                    event.code === SESSION_BUSY_CODE &&
+                    (yield* Clock.currentTimeMillis) + busyRetry.delayMs < deadline) {
+                    retryBusy = true;
+                    return false;
+                }
+                first = false;
+                return true;
+            })), Stream.scoped, 
+            // concat closes the attempt's scope (and its iterator) before the wait or next invoke.
+            Stream.concat(Stream.suspend(() => retryBusy
+                ? Stream.unwrap(Effect.gen(function* () {
+                    log.info(`${label} session ${scope.session} is busy (an external turn holds it) — retrying in ${busyRetry.delayMs}ms`);
+                    yield* Effect.sleep(busyRetry.delayMs);
+                    return attempt();
+                }))
+                : Stream.empty)));
+        });
+        return attempt();
+    }));
+}
+/**
+ * Load the turn's BACKGROUND refs — what was folded in from earlier un-summoned discussion, not the
+ * ask itself. Per-ref degradation is the whole meaning of that tier: one expired file costs a warn
+ * and a place in the missing-attachments count ({@link missingAttachmentsNote}), never the answer it
+ * merely accompanies, and never its still-readable siblings. Parallel, input order kept.
+ *
+ * PRIMARY refs are the opposite policy and stay with their channel: a failure there throws, so the
+ * agent never runs on an input the user pointed at and we failed to load.
+ *
+ * Shared by all three channels; `what` is the only part that is the platform's.
+ */
+export async function loadBackground(refs, load, opts) {
+    const loaded = [];
+    let lost = 0;
+    const results = await Promise.allSettled(refs.map(load));
+    for (const [index, result] of results.entries()) {
+        const ref = refs[index];
+        if (result.status === "fulfilled")
+            loaded.push({ ref, value: result.value });
+        else {
+            lost++;
+            log.warn(`${opts.label} could not load an earlier (buffered) ${opts.what}: ${String(result.reason)}`);
         }
-        if (!retryBusy)
-            return;
-        log.info(`${label} session ${session} is busy (an external turn holds it) — retrying in ${busyRetry.delayMs}ms`);
-        await new Promise((r) => setTimeout(r, busyRetry.delayMs));
     }
+    return { loaded, lost };
 }
 /**
  * The downloaded-file manifest appended to the prompt: name, size, path. Empty input renders nothing.

package/dist/channels/kit/preview-kit.d.ts

@@ -1,12 +1,6 @@
 /**
- * Channel-neutral live-preview pieces shared by every messaging channel's preview renderer
- * (telegram/preview.ts, feishu/preview.ts, slack/preview.ts): the turn-view REDUCER (the one
- * event → view-state machine every renderer consumes), its line renderers, the terminal-failure
- * shape a channel hands to its `onError`, the customer-facing wording for it, and the serialized
- * single-writer pump. DELIVERY stays per-platform — message edits vs streaming cards vs chat.update,
- * pacing constants, reveal timing, and terminal-write policies are real platform differences — but
- * everything platform-independent lives here, so a new event type or a wording change lands in ONE
- * place instead of one hunk per channel.
+ * Channel-neutral live-preview pieces shared by every messaging channel's preview renderer (telegram/preview.ts,
+ * feishu/preview.ts, slack/preview.ts).
  */
 import type { AgentEvent, Json } from "../../agent.ts";
 /** A terminal failure, as a channel hands it to its `onError`. */
@@ -16,13 +10,12 @@ export interface ChannelFailure {
     /** The engine's failure code, when it set one. */
     code?: string;
 }
-/** The customer-facing default: neutral, no leaked internals. Differentiate on retryability and always
- *  offer a next step (Slack agent-design: never leave the user with a dead-end "something went wrong").
- *  The non-retryable branch keeps the "something went wrong" phrase deliberately — it is neutral (we only
- *  know a boolean, never the specific limitation) and shared verbatim across channels. */
+/** The customer-facing default: neutral, no leaked internals. */
 export declare function defaultErrorMessage(failed: ChannelFailure): string;
-/** Customer-facing live-preview line for an engine-internal retry backoff (the advisory `retrying`
- *  event): neutral, no leaked internals — the reason stays in operator logs. */
+/**
+ * Customer-facing live-preview line for an engine-internal retry backoff (the advisory `retrying` event): neutral, no
+ * leaked internals — the reason stays in operator logs.
+ */
 export declare const RETRY_NOTICE = "\u23F3 Temporary problem \u2014 retrying\u2026";
 /** The placeholder shown before any reasoning/tool/text arrives. */
 export declare const THINKING_PLACEHOLDER = "\uD83D\uDCAD Thinking\u2026";
@@ -31,12 +24,7 @@ interface ToolLine {
     label: string;
     status: "running" | "ok" | "error";
 }
-/**
- * The channel-neutral view STATE of one in-flight turn. Renderers own everything after this state:
- * when to reveal the young answer (age vs timer), how to format (HTML / card markdown / mrkdwn),
- * and how to deliver frames. Terminal events are deliberately NOT view state — completed/failed
- * resolve the preview into a final write, which is each platform's terminal-write policy.
- */
+/** The channel-neutral view STATE of one in-flight turn. */
 export interface TurnView {
     thinking: string;
     tools: ToolLine[];
@@ -49,69 +37,27 @@ export interface TurnView {
     retrying: boolean;
 }
 export declare function createTurnView(): TurnView;
-/**
- * Apply one event to the view state. Returns true when the view changed (the caller repaints).
- * This is the ONE place the shared view rules live: tool labels are humanized with a compact arg
- * summary, and any progress event closes an open retry notice (a stale "retrying" line must never
- * outlive actual progress). Terminal events only close the notice — they are the caller's business.
- */
-export declare function applyTurnEvent(view: TurnView, e: AgentEvent): boolean;
+export declare function applyTurnEvent(view: TurnView, e: AgentEvent, now?: number): boolean;
 /** The tool-activity block: one `🔧 label …/✓/✗` line per call, in call order. */
 export declare function toolLines(view: TurnView): string;
-/** The reasoning peek: the most recent tail of the (growing) reasoning, one line, code-point safe.
- *  Process, not the answer — renderers show it live only, never in the persisted final message. */
+/** The reasoning peek: the most recent tail of the (growing) reasoning, one line, code-point safe. */
 export declare function thinkingLine(view: TurnView, maxTail: number): string;
 /**
- * The shared answer-reveal policy: the answer stays hidden until its first delta has aged one
- * throttle window (`ageMs` — each platform passes its own pacing constant). The pump's leading-edge
- * flush would otherwise turn the very first content delta (often a lone character or unbalanced
- * markup) into its own frame — the short-reply flicker (placeholder → "O" → "OK."). Aging is
- * anchored at delta ARRIVAL (`answerSince`, set by the reducer) so an in-flight write can't skew the
- * clock, and there is deliberately NO timer at the boundary: a young answer surfaces on the next
- * content-driven pass, so a turn completing within the window delivers the final answer only.
+ * The shared answer-reveal policy: the answer stays hidden until its first delta has aged one throttle window (`ageMs`
+ * — each platform passes its own pacing constant).
  */
-export declare function revealedAnswer(view: TurnView, ageMs: number): string;
+export declare function revealedAnswer(view: TurnView, ageMs: number, now?: number): string;
 /** Compose body parts (thinking/tools/retry/answer) into one frame: skip empties, blank-line joins. */
 export declare function composeTurnBody(parts: readonly string[]): string;
 /**
- * The serialized live-preview writer shared by the edit/snapshot renderers (telegram, feishu).
- * Events mark the view dirty; the pump repaints to the LATEST view with at most ONE write in
- * flight, paced by `throttleMs`. One-in-flight is the whole point: concurrent writes can land out
- * of order — an older frame over a newer one is the "shows 3-4 steps, blanks, re-fills" flicker —
- * so a single writer keeps frames monotonic (and makes feishu's strictly-increasing card `sequence`
- * correct by construction). NOT used by slack-classic: its pacing lives inside the flush (the 3s
- * chat.update rate slot), not at the frame boundary.
- */
-export interface PreviewPump {
-    /** Mark the view dirty and ensure the single writer runs (an in-flight write picks the new state
-     *  up on its next loop). Synchronous — callers never await a network write. */
-    touch(): void;
-    /** Stop the pump, cut an in-flight throttle short, and await any in-flight write — so the
-     *  caller's terminal write is strictly the LAST one (no stale frame landing after the answer). */
-    finish(): Promise<void>;
-}
-export declare function createPreviewPump(opts: {
-    /** Write the LATEST view. Best-effort — the terminal write is authoritative. */
-    flush: () => Promise<void>;
-    /** Pace + coalesce a burst into one write; finish() interrupts a throttle in progress. */
-    throttleMs: number;
-    /** Called for the FIRST failing flush only (the pump keeps running): a never-rendering preview
-     *  must be diagnosable, not silent — and not a log flood. */
-    onError: (error: unknown) => void;
-}): PreviewPump;
-/**
- * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md`
- * rather than just `🔧 read`. Generic (a channel knows no tool schemas): show the salient value — the
- * first primitive field, conventionally the subject (path / command / query / url) — else compact JSON.
+ * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md` rather than just
+ * `🔧 read`.
  */
 export declare function summarizeToolArgs(args: Json): string;
 /**
- * A plain-language label for a tool call, following Slack's agent-design guidance to name what a tool
- * does rather than expose a raw identifier ("Create issue", not "create_issue"; "Github: create issue",
- * not "mcp__github__create_issue"). Deliberately generic and engine-neutral: it only reshapes the
- * identifier string — it never invents semantics and never exposes arguments. An `mcp__server__tool`
- * identifier becomes `server: tool`; any other identifier has its separators normalized to spaces and
- * its first letter capitalized.
+ * A plain-language label for a tool call, following Slack's agent-design guidance to name what a tool does rather than
+ * expose a raw identifier ("Create issue", not "create_issue"; "Github: create issue", not
+ * "mcp__github__create_issue").
  */
 export declare function humanizeToolName(name: string): string;
 export {};