agentenkit 0.7.0 → 0.11.0

package/dist/adapters/flow.d.ts

@@ -0,0 +1,160 @@
+import type { Duration, Flow, FlowEnv, FlowFunction } from '@clevix/flow';
+import { type EnqueueOptions, type Queue, type QueueStats, type QueuedJob } from '../ports/queue.js';
+import type { AgentCore } from '../ports/runtime.js';
+import type { EventBus } from '../ports/bus.js';
+import type { Kv } from '../ports/kv.js';
+import { type RunStreams, type StreamEnd, type StreamEvent, type StreamItem, type StreamMeta, type StreamSnapshot } from '../ports/streams.js';
+import type { AgentEvent, RunJob } from '../core/types.js';
+/** The function ID the queue starts and the worker serves, unless both are
+ *  given another. */
+export declare const FLOW_FUNCTION_ID = "agentenkit-run";
+/** The event the function lists as its trigger. Nothing sends it: runs come
+ *  from `flow.start`. Flow needs every function to have a trigger. */
+export declare const FLOW_JOB_EVENT = "agentenkit/job";
+/** What one run of the function carries. */
+export interface FlowJobData {
+    job: RunJob;
+    /** The singleton key: the enqueue's key, or the job's dispatch id. */
+    key: string;
+    /** In seconds, for `priority.run`. */
+    priority: number;
+    /** Epoch ms. The run sleeps until then before it runs the job. */
+    notBefore?: number;
+}
+export interface FlowQueueOptions {
+    /** The function to start. Defaults to `agentenkit-run`. Must match the
+     *  ID given to `agentRunFunction`. */
+    functionId?: string;
+    /** Cloudflare Workers: the handler's `env`, where the Flow keys live. */
+    env?: FlowEnv;
+}
+/** Queue adapter over Clevix Flow.
+ *
+ *  Each job is one run of one Flow function (see `agentRunFunction`),
+ *  started with `flow.start`. A key is the function's singleton key in
+ *  `skip` mode, so at most one live run holds it, and it is free again as
+ *  soon as that run ends. A delay is a sleep at the start of the run, so the
+ *  key stays held while the job waits. `cancel` cancels the run that holds a
+ *  key. `find` and `stats` read Flow's runs index, which lags the runs by a
+ *  few seconds.
+ *
+ *  Needs Flow SDK 0.7.0 or later and an engine with the run routes. */
+export declare class FlowQueue implements Queue {
+    private readonly flow;
+    private readonly opts;
+    private readonly functionId;
+    constructor(flow: Flow, opts?: FlowQueueOptions);
+    private get env();
+    enqueue(job: RunJob, opts?: EnqueueOptions): Promise<void>;
+    cancel(key: string): Promise<void>;
+    find(runId: string): Promise<QueuedJob | null>;
+    stats(): Promise<QueueStats>;
+}
+export interface AgentRunFunctionOptions {
+    /** Defaults to `agentenkit-run`. Must match `FlowQueue`'s `functionId`.
+     *  At most 56 characters, since the failure function adds `-failure`. */
+    id?: string;
+    /** How many jobs of one `partitionKey` run at once. Unset: no limit.
+     *  Job priorities only take effect under a limit. */
+    concurrency?: number;
+    /** Flow's retries for a job that throws. Flow's default when unset. */
+    retries?: number;
+    /** How long Flow waits for one job. Defaults to 14 minutes, Flow's most.
+     *  When a job runs longer, Flow stops waiting and tries the step again,
+     *  but nothing stops the first call: it keeps running. The retry finds the
+     *  run lock held and does nothing, so keep segments shorter than this
+     *  (`segmentTimeoutMs`). */
+    stepTimeout?: Duration;
+}
+/** The Flow function that runs `FlowQueue`'s jobs. Serve it with the app's
+ *  other Flow functions.
+ *
+ *  A job runs in one step. `handleJob` only throws for what a queue should
+ *  retry (an unknown agent, a store that is down), so Flow's retries cover
+ *  delivery; agentic-kit retries a failed run itself. When Flow gives up, the
+ *  failure function hands the job to `handleDeadJob`, which fails the run. */
+export declare function agentRunFunction(flow: Flow, core: Pick<AgentCore, 'worker'>, opts?: AgentRunFunctionOptions): FlowFunction;
+/** The channel a thread's events go on. */
+export declare function flowThreadChannel(threadId: string): Promise<string>;
+export interface FlowBusOptions {
+    /** Holds events too big for one realtime message (over about 60 KB). */
+    kv: Kv;
+    /** How often each subscriber gets a HEARTBEAT notice. Default one minute. */
+    heartbeatMs?: number;
+    /** How long `subscribe` waits for its socket to open before it returns
+     *  anyway. Default 10 seconds. */
+    openTimeoutMs?: number;
+    /** Cloudflare Workers: the handler's `env`, where the Flow keys live. */
+    env?: FlowEnv;
+    /** A WebSocket class, where the runtime has none. */
+    WebSocket?: typeof WebSocket;
+}
+/** EventBus over Clevix Flow realtime.
+ *
+ *  Each thread has its own channel, and a process opens one socket per thread
+ *  it follows, shared by every subscriber in the process. Realtime keeps
+ *  nothing and drops what comes while a socket reconnects: the bus is
+ *  at-most-once anyway, and a follower fills any gap from the log. An event
+ *  over about 60 KB waits in the kv for a minute, and the channel carries its
+ *  key. While anyone subscribes, each subscriber gets a HEARTBEAT notice
+ *  (seq 0) every `heartbeatMs`, as with the other buses.
+ *
+ *  Needs Flow SDK 0.7.0 or later. */
+export declare class FlowBus implements EventBus {
+    private readonly flow;
+    private readonly opts;
+    private readonly channels;
+    private heartbeat?;
+    constructor(flow: Flow, opts: FlowBusOptions);
+    private get env();
+    publish(threadId: string, event: AgentEvent): Promise<void>;
+    subscribe(threadId: string, handler: (event: AgentEvent) => void): Promise<() => void>;
+    /** Opens the thread's socket. `open` settles when it is open, or after
+     *  `openTimeoutMs`: an event published before then may be missed, which a
+     *  follower's gap read covers. */
+    private connect;
+    private receive;
+    private deliver;
+    private startHeartbeat;
+    private stopHeartbeat;
+}
+/** The Flow stream a run stream is kept in. */
+export declare function flowStreamId(streamId: string): Promise<string>;
+export interface FlowStreamsOptions {
+    /** Holds items too big for one stream item (over about 60 KB). */
+    kv: Kv;
+    /** How long such an item stays in the kv. Default 8 days: past Flow's
+     *  longest time to live, so it outlives its stream. */
+    refTtlMs?: number;
+    /** Cloudflare Workers: the handler's `env`, where the Flow keys live. */
+    env?: FlowEnv;
+    /** A WebSocket class, where the runtime has none. */
+    WebSocket?: typeof WebSocket;
+}
+/** RunStreams over Clevix Flow streams.
+ *
+ *  Flow keeps the items, gives offsets, and lets a reader start from any
+ *  offset and follow live, which is what a run stream needs. An item over
+ *  about 60 KB is kept in the kv and the stream carries its key; readers get
+ *  the event back. Flow keeps a stream at most 7 days and a grace window at
+ *  most 7 days, so longer times are cut to that. A stream holds at most
+ *  20,000 items and 32 MB; an append past that fails.
+ *
+ *  Needs Flow SDK 0.7.0 or later. */
+export declare class FlowStreams implements RunStreams {
+    private readonly flow;
+    private readonly opts;
+    constructor(flow: Flow, opts: FlowStreamsOptions);
+    private get env();
+    open(streamId: string, meta: StreamMeta, ttlMs: number): Promise<void>;
+    append(streamId: string, events: StreamEvent[]): Promise<string[]>;
+    read(streamId: string, after: string | null, signal?: AbortSignal): AsyncIterable<StreamItem>;
+    snapshot(streamId: string, after?: string | null): Promise<StreamSnapshot | null>;
+    close(streamId: string, end: StreamEnd, graceMs: number): Promise<void>;
+    delete(streamId: string): Promise<void>;
+    private call;
+    /** A Flow item as a run stream item: the event, read back from the kv when
+     *  the stream holds its key. Null when that kv copy has expired. */
+    private decode;
+}
+//# sourceMappingURL=flow.d.ts.map

package/dist/adapters/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../src/adapters/flow.ts"],"names":[],"mappings":"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"}

package/dist/adapters/flow.js

@@ -0,0 +1,484 @@
+import { DuplicateJobError, PayloadTooLargeError } from '../ports/queue.js';
+import { StreamClosedError, StreamGoneError, } from '../ports/streams.js';
+import { isStreamEnd } from '../core/stream-events.js';
+/** The function ID the queue starts and the worker serves, unless both are
+ *  given another. */
+export const FLOW_FUNCTION_ID = 'agentenkit-run';
+/** The event the function lists as its trigger. Nothing sends it: runs come
+ *  from `flow.start`. Flow needs every function to have a trigger. */
+export const FLOW_JOB_EVENT = 'agentenkit/job';
+/** A run's data is at most 1 MB on Flow. */
+const MAX_DATA_BYTES = 1_000_000;
+/** Flow's `priority.run` is in seconds, from -600 to 600. */
+const PRIORITY_SECONDS = 60;
+const MAX_PRIORITY = 600;
+const ACTIVE = ['queued', 'running', 'sleeping', 'waiting', 'waiting_for_app', 'paused'];
+/** Queue adapter over Clevix Flow.
+ *
+ *  Each job is one run of one Flow function (see `agentRunFunction`),
+ *  started with `flow.start`. A key is the function's singleton key in
+ *  `skip` mode, so at most one live run holds it, and it is free again as
+ *  soon as that run ends. A delay is a sleep at the start of the run, so the
+ *  key stays held while the job waits. `cancel` cancels the run that holds a
+ *  key. `find` and `stats` read Flow's runs index, which lags the runs by a
+ *  few seconds.
+ *
+ *  Needs Flow SDK 0.7.0 or later and an engine with the run routes. */
+export class FlowQueue {
+    flow;
+    opts;
+    functionId;
+    constructor(flow, opts = {}) {
+        this.flow = flow;
+        this.opts = opts;
+        this.functionId = opts.functionId ?? FLOW_FUNCTION_ID;
+    }
+    get env() {
+        return this.opts.env ? { env: this.opts.env } : {};
+    }
+    async enqueue(job, opts) {
+        // An unkeyed job still needs a singleton key, or every unkeyed job would
+        // share one. Its dispatch id is its own; a second start of the same
+        // dispatch is the same job, so it is dropped without an error.
+        const key = opts?.key || job.dispatchId || crypto.randomUUID();
+        const data = {
+            job,
+            key,
+            priority: Math.max(-MAX_PRIORITY, Math.min(MAX_PRIORITY, (opts?.priority ?? 0) * PRIORITY_SECONDS)),
+            ...(opts?.delaySeconds && opts.delaySeconds > 0
+                ? { notBefore: Date.now() + Math.ceil(opts.delaySeconds * 1000) }
+                : {}),
+        };
+        if (new TextEncoder().encode(JSON.stringify(data)).length > MAX_DATA_BYTES)
+            throw new PayloadTooLargeError();
+        // Twice at most: a singleton answer with no active run means the run that
+        // held the key ended in between, so the key is free now.
+        for (let i = 0; i < 2; i++) {
+            const res = await this.flow.start(this.functionId, { data: data, ...this.env });
+            if (res.started)
+                return;
+            if (res.reason === 'singleton') {
+                if (res.activeRunId === null)
+                    continue;
+                if (opts?.key)
+                    throw new DuplicateJobError(opts.key);
+                return;
+            }
+            if (res.reason === 'paused')
+                throw new Error(`flow: function ${this.functionId} is paused`);
+            throw new Error(`flow: no function ${this.functionId}; is the app served and synced?`);
+        }
+        // Both tries found the key held by a run that had just ended. No run
+        // started, so the caller must hear it, or the job is lost.
+        throw new Error(`flow: no run started for key ${key}; the key was still being freed`);
+    }
+    async cancel(key) {
+        await this.flow.runs.cancel({ function: this.functionId, singletonKey: key }, this.env);
+    }
+    async find(runId) {
+        const page = await this.flow.runs.list({
+            function: this.functionId, tags: { runId }, status: ACTIVE, limit: 50, ...this.env,
+        });
+        // Newest first: the earliest is the last one.
+        const run = page.items[page.items.length - 1];
+        return run ? queuedJob(run) : null;
+    }
+    async stats() {
+        const [counts, queued] = await Promise.all([
+            this.flow.runs.counts({ function: this.functionId, ...this.env }),
+            this.flow.runs.list({ function: this.functionId, status: ['queued'], limit: 200, ...this.env }),
+        ]);
+        // Newest first. With more than one page this is the oldest of the
+        // newest 200, so it can read low.
+        const oldest = queued.items[queued.items.length - 1];
+        return {
+            ready: counts.queued + counts.waiting_for_app,
+            delayed: counts.sleeping + counts.waiting,
+            inFlight: counts.running,
+            dead: counts.failed,
+            oldestReadyMs: oldest ? Math.max(0, Date.now() - oldest.createdAt) : 0,
+            paused: counts.paused > 0,
+            claimErrors: 0,
+        };
+    }
+}
+function queuedJob(run) {
+    return {
+        id: run.id,
+        runId: run.tags.runId ?? '',
+        threadId: run.tags.threadId ?? '',
+        kind: (run.tags.kind || undefined),
+        attempts: 0,
+        runAt: new Date(run.createdAt),
+        position: -1,
+    };
+}
+/** The Flow function that runs `FlowQueue`'s jobs. Serve it with the app's
+ *  other Flow functions.
+ *
+ *  A job runs in one step. `handleJob` only throws for what a queue should
+ *  retry (an unknown agent, a store that is down), so Flow's retries cover
+ *  delivery; agentic-kit retries a failed run itself. When Flow gives up, the
+ *  failure function hands the job to `handleDeadJob`, which fails the run. */
+export function agentRunFunction(flow, core, opts = {}) {
+    return flow.createFunction({
+        id: opts.id ?? FLOW_FUNCTION_ID,
+        singleton: { key: 'event.data.key', mode: 'skip' },
+        tags: { runId: 'event.data.job.runId', threadId: 'event.data.job.threadId', kind: 'event.data.job.kind' },
+        priority: { run: 'event.data.priority' },
+        ...(opts.concurrency ? { concurrency: { limit: opts.concurrency, key: 'event.data.job.partitionKey' } } : {}),
+        ...(opts.retries !== undefined ? { retries: opts.retries } : {}),
+        timeouts: { step: opts.stepTimeout ?? '14m' },
+        onFailure: async ({ event, error, attempts }) => {
+            const data = event.data?.event?.data;
+            if (!data?.job)
+                return;
+            await core.worker.handleDeadJob(data.job, attempts, new Error(error?.message ?? 'the Flow run failed'));
+        },
+    }, { event: FLOW_JOB_EVENT }, async ({ event, step }) => {
+        const data = event.data;
+        if (data.notBefore)
+            await step.sleepUntil('delay', data.notBefore);
+        return step.run('handle', () => core.worker.handleJob(data.job));
+    });
+}
+// ---- names and big values, shared by the bus and the streams ----
+/** Flow's charset for channel and stream names. */
+const NAME_RE = /^[A-Za-z0-9:_.-]{1,256}$/;
+/** Under Flow's 64 KB cap on one message or one stream item, with room for
+ *  the rest of the request. A value over it goes through the kv. */
+const MAX_INLINE_BYTES = 60_000;
+const byteLength = (s) => new TextEncoder().encode(s).length;
+async function sha256Hex(s) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(s));
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** `prefix + id` when Flow allows it, else `prefix + "h." + sha256(id)`. */
+async function flowName(prefix, id) {
+    const name = prefix + id;
+    if (NAME_RE.test(name) && name !== '.' && name !== '..' && name !== 'token' && name !== 'connect')
+        return name;
+    return `${prefix}h.${await sha256Hex(id)}`;
+}
+// ---- FlowBus ----
+/** The channel a thread's events go on. */
+export function flowThreadChannel(threadId) {
+    return flowName('agentenkit.thread.', threadId);
+}
+const BUS_TOPIC = 'events';
+/** How long an event too big for one message waits in the kv. */
+const BUS_REF_SECONDS = 60;
+/** EventBus over Clevix Flow realtime.
+ *
+ *  Each thread has its own channel, and a process opens one socket per thread
+ *  it follows, shared by every subscriber in the process. Realtime keeps
+ *  nothing and drops what comes while a socket reconnects: the bus is
+ *  at-most-once anyway, and a follower fills any gap from the log. An event
+ *  over about 60 KB waits in the kv for a minute, and the channel carries its
+ *  key. While anyone subscribes, each subscriber gets a HEARTBEAT notice
+ *  (seq 0) every `heartbeatMs`, as with the other buses.
+ *
+ *  Needs Flow SDK 0.7.0 or later. */
+export class FlowBus {
+    flow;
+    opts;
+    channels = new Map();
+    heartbeat;
+    constructor(flow, opts) {
+        this.flow = flow;
+        this.opts = opts;
+    }
+    get env() {
+        return this.opts.env ? { env: this.opts.env } : {};
+    }
+    async publish(threadId, event) {
+        const raw = JSON.stringify(event);
+        let frame = { event };
+        if (byteLength(raw) > MAX_INLINE_BYTES) {
+            const ref = `agentenkit:flowbus:${threadId}:${crypto.randomUUID()}`;
+            await this.opts.kv.set(ref, raw, { exSeconds: BUS_REF_SECONDS });
+            frame = { ref };
+        }
+        const channel = await flowThreadChannel(threadId);
+        await this.flow.realtime.publish({ channel, topic: BUS_TOPIC, data: frame }, this.env);
+    }
+    async subscribe(threadId, handler) {
+        let ch = this.channels.get(threadId);
+        if (!ch)
+            ch = this.connect(threadId);
+        ch.handlers.add(handler);
+        this.startHeartbeat();
+        await ch.open;
+        if (ch.failed) {
+            ch.handlers.delete(handler);
+            if (this.channels.size === 0)
+                this.stopHeartbeat();
+            throw ch.failed.error;
+        }
+        let done = false;
+        const mine = ch;
+        return () => {
+            if (done)
+                return;
+            done = true;
+            mine.handlers.delete(handler);
+            if (mine.handlers.size === 0 && this.channels.get(threadId) === mine) {
+                this.channels.delete(threadId);
+                mine.stop();
+            }
+            if (this.channels.size === 0)
+                this.stopHeartbeat();
+        };
+    }
+    /** Opens the thread's socket. `open` settles when it is open, or after
+     *  `openTimeoutMs`: an event published before then may be missed, which a
+     *  follower's gap read covers. */
+    connect(threadId) {
+        let opened;
+        const open = new Promise((resolve) => (opened = resolve));
+        const timer = setTimeout(opened, this.opts.openTimeoutMs ?? 10_000);
+        timer.unref?.();
+        let stop;
+        let stopped = false;
+        const ch = {
+            handlers: new Set(),
+            open,
+            queue: Promise.resolve(),
+            stop: () => {
+                stopped = true;
+                clearTimeout(timer);
+                opened();
+                stop?.();
+            },
+        };
+        this.channels.set(threadId, ch);
+        flowThreadChannel(threadId)
+            .then((channel) => {
+            if (stopped)
+                return;
+            stop = this.flow.realtime.subscribe({
+                channel,
+                topics: [BUS_TOPIC],
+                ...this.env,
+                ...(this.opts.WebSocket ? { WebSocket: this.opts.WebSocket } : {}),
+                onState: (state) => {
+                    if (state === 'open') {
+                        clearTimeout(timer);
+                        opened();
+                    }
+                },
+                onMessage: (message) => {
+                    ch.queue = ch.queue.then(() => this.receive(ch, message.data));
+                },
+            });
+        })
+            .catch((error) => {
+            // No socket (no WebSocket class, bad options): every subscriber
+            // waiting on it gets the error, as Go's Subscribe returns it.
+            ch.failed = { error };
+            if (this.channels.get(threadId) === ch)
+                this.channels.delete(threadId);
+            clearTimeout(timer);
+            opened();
+        });
+        return ch;
+    }
+    async receive(ch, frame) {
+        let event;
+        try {
+            if ('event' in frame) {
+                event = frame.event;
+            }
+            else {
+                const raw = await this.opts.kv.get(frame.ref);
+                if (raw === null)
+                    return; // expired: the follower reads it from the log
+                event = JSON.parse(raw);
+            }
+            event.createdAt = new Date(event.createdAt);
+        }
+        catch {
+            return; // a malformed frame never kills the subscription
+        }
+        this.deliver(ch.handlers, event);
+    }
+    deliver(handlers, event) {
+        for (const handler of [...handlers]) {
+            try {
+                handler(event);
+            }
+            catch {
+                // one throwing handler must not stop the others
+            }
+        }
+    }
+    startHeartbeat() {
+        if (this.heartbeat)
+            return;
+        this.heartbeat = setInterval(() => {
+            for (const [threadId, ch] of this.channels) {
+                this.deliver(ch.handlers, { threadId, seq: 0, type: 'HEARTBEAT', payload: null, createdAt: new Date() });
+            }
+        }, this.opts.heartbeatMs ?? 60_000);
+        this.heartbeat.unref?.();
+    }
+    stopHeartbeat() {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = undefined;
+    }
+}
+// ---- FlowStreams ----
+/** The Flow stream a run stream is kept in. */
+export function flowStreamId(streamId) {
+    return flowName('agentenkit.', streamId);
+}
+/** Flow's limits on one stream call. */
+const MAX_APPEND_ITEMS = 100;
+const MAX_APPEND_BYTES = 900_000;
+const MAX_STREAM_MS = 7 * 24 * 60 * 60_000;
+/** RunStreams over Clevix Flow streams.
+ *
+ *  Flow keeps the items, gives offsets, and lets a reader start from any
+ *  offset and follow live, which is what a run stream needs. An item over
+ *  about 60 KB is kept in the kv and the stream carries its key; readers get
+ *  the event back. Flow keeps a stream at most 7 days and a grace window at
+ *  most 7 days, so longer times are cut to that. A stream holds at most
+ *  20,000 items and 32 MB; an append past that fails.
+ *
+ *  Needs Flow SDK 0.7.0 or later. */
+export class FlowStreams {
+    flow;
+    opts;
+    constructor(flow, opts) {
+        this.flow = flow;
+        this.opts = opts;
+    }
+    get env() {
+        return this.opts.env ? { env: this.opts.env } : {};
+    }
+    async open(streamId, meta, ttlMs) {
+        const id = await flowStreamId(streamId);
+        const ttl = Math.min(MAX_STREAM_MS, Math.max(1000, Math.ceil(ttlMs)));
+        await this.flow.streams.open(id, { meta: { threadId: meta.threadId, runId: meta.runId }, ttl, ...this.env });
+    }
+    async append(streamId, events) {
+        if (events.length === 0)
+            return [];
+        const id = await flowStreamId(streamId);
+        const items = [];
+        for (const event of events) {
+            const raw = JSON.stringify(event);
+            if (byteLength(raw) <= MAX_INLINE_BYTES) {
+                items.push({ json: event, bytes: byteLength(raw) });
+                continue;
+            }
+            const ref = { agentenkitRef: `agentenkit:flowstream:${streamId}:${crypto.randomUUID()}` };
+            await this.opts.kv.set(ref.agentenkitRef, raw, { exSeconds: Math.ceil((this.opts.refTtlMs ?? 8 * 24 * 60 * 60_000) / 1000) });
+            items.push({ json: ref, bytes: byteLength(JSON.stringify(ref)) });
+        }
+        // In batches Flow takes: 100 items and under 1 MB a call.
+        const offsets = [];
+        let batch = [];
+        let size = 0;
+        const flush = async () => {
+            if (batch.length === 0)
+                return;
+            offsets.push(...(await this.call(streamId, () => this.flow.streams.append(id, batch, this.env))));
+            batch = [];
+            size = 0;
+        };
+        for (const item of items) {
+            if (batch.length === MAX_APPEND_ITEMS || size + item.bytes > MAX_APPEND_BYTES)
+                await flush();
+            batch.push(item.json);
+            size += item.bytes;
+        }
+        await flush();
+        return offsets;
+    }
+    async *read(streamId, after, signal) {
+        const id = await flowStreamId(streamId);
+        const items = this.flow.streams.read(id, {
+            ...(after ? { after } : {}),
+            ...(signal ? { signal } : {}),
+            ...(this.opts.WebSocket ? { WebSocket: this.opts.WebSocket } : {}),
+            ...this.env,
+        });
+        try {
+            for await (const item of items) {
+                const decoded = await this.decode(item);
+                if (decoded)
+                    yield decoded;
+            }
+        }
+        catch (err) {
+            throw mapStreamError(streamId, err);
+        }
+    }
+    async snapshot(streamId, after) {
+        const id = await flowStreamId(streamId);
+        const snap = await this.call(streamId, () => this.flow.streams.snapshot(id, { ...(after ? { after } : {}), ...this.env }));
+        if (!snap)
+            return null;
+        const items = [];
+        for (const item of snap.items) {
+            const decoded = await this.decode(item);
+            if (decoded)
+                items.push(decoded);
+        }
+        // The end item is the last one; `end` is the event, without its offset.
+        let end = null;
+        const last = items[items.length - 1];
+        if (snap.ended && last && isStreamEnd(last)) {
+            const { offset: _, ...event } = last;
+            end = event;
+        }
+        const meta = snap.meta;
+        return {
+            meta: { threadId: meta?.threadId ?? '', runId: meta?.runId ?? '' },
+            items,
+            end,
+        };
+    }
+    async close(streamId, end, graceMs) {
+        const id = await flowStreamId(streamId);
+        const grace = Math.min(MAX_STREAM_MS, Math.max(0, Math.ceil(graceMs)));
+        await this.call(streamId, () => this.flow.streams.close(id, { end: end, grace, ...this.env }));
+    }
+    async delete(streamId) {
+        const id = await flowStreamId(streamId);
+        await this.flow.streams.delete(id, this.env);
+    }
+    async call(streamId, fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            throw mapStreamError(streamId, err);
+        }
+    }
+    /** A Flow item as a run stream item: the event, read back from the kv when
+     *  the stream holds its key. Null when that kv copy has expired. */
+    async decode(item) {
+        let event = item.item;
+        if (event && typeof event === 'object' && 'agentenkitRef' in event) {
+            const raw = await this.opts.kv.get(event.agentenkitRef);
+            if (raw === null)
+                return null;
+            event = JSON.parse(raw);
+        }
+        return { ...event, offset: item.offset };
+    }
+}
+/** Flow's stream errors as the port's, by name: the adapter does not load
+ *  `@clevix/flow` itself. */
+function mapStreamError(streamId, err) {
+    const name = err?.name;
+    if (name === 'StreamGoneError')
+        return new StreamGoneError(streamId);
+    if (name === 'StreamClosedError')
+        return new StreamClosedError(streamId);
+    return err;
+}
+//# sourceMappingURL=flow.js.map