agentenkit 0.3.0 → 0.4.0

package/README.md

@@ -16,14 +16,14 @@ now describe that behaviour.
 
 ## Running locally, with nothing to stand up
 
-There is no `createDevRuntime`. Assembling the platform is four adapters and one wire,
+There is no `createDevRuntime`. Assembling the platform is five adapters and one wire,
 and seeing them is the point — swapping any of them for the durable equivalent later is
 then obvious rather than magic.
 
 ```ts
 import { Database } from 'bun:sqlite';           // or node:sqlite — see openSqlite
 import { setupAgentCore } from 'agentenkit';
-import { SqliteStorage } from 'agentenkit/adapters/sqlite';
+import { SqliteRunStreams, SqliteStorage } from 'agentenkit/adapters/sqlite';
 import { InlineQueue } from 'agentenkit/adapters/inline';
 import { MemoryBus, MemoryKv } from 'agentenkit/adapters/memory';
 import { SqliteAdminStore } from 'agentenkit/admin/sqlite';
@@ -36,6 +36,7 @@ const queue = new InlineQueue();
 
 export const runtime = await setupAgentCore({
   storage: new SqliteStorage(db),      // ← later: PrismaStorage, or your own
+  streams: new SqliteRunStreams(db),   // ← later: RedisRunStreams, PrismaRunStreams
   admin: SqliteAdminStore.open(db),     // ← later: PostgresAdminStore
   bus: new MemoryBus(),                // ← later: RedisBus
   kv: new MemoryKv(),                  // ← later: RedisKv
@@ -79,7 +80,7 @@ import { createClient } from 'redis';
 import { PrismaClient } from '@prisma/client';
 import { setupAgentCore } from 'agentenkit';
 import { PrismaStorage } from 'agentenkit/adapters/prisma';
-import { RedisBus, RedisKv } from 'agentenkit/adapters/redis';
+import { RedisBus, RedisKv, RedisRunStreams } from 'agentenkit/adapters/redis';
 import { QStashQueue } from 'agentenkit/adapters/qstash';
 
 const redis = createClient({ url: process.env.REDIS_URL });
@@ -93,6 +94,7 @@ export const runtime = await setupAgentCore({
     { url: 'https://app.example.com/api/queue/agent-run' },
   ),
   kv: new RedisKv(redis),
+  streams: new RedisRunStreams(redis),             // ← one stream per run segment
   // `admin` omitted on purpose: with AGENTIC_KIT_ADMIN_DATABASE_URL set, the
   // platform opens Postgres for its own history (§2.9). Pass one to override.
   resolveModel: (name) => ({ instance: () => models[name], contextWindow: 128_000 }),
@@ -110,16 +112,27 @@ await chat.run({ prompt: 'hi', state: { orgId } });      // persist + enqueue
 await chat.stop(threadId);                               // one write: state → CANCELLED (§2.1)
 await runtime.hitl.respond({ threadId, toolCallId, approved, payload, state });  // §2.5
 await runtime.getThreadSnapshot(threadId, state);        // hydrate a client (§2.2)
-const { stream, headers } = runtime.events.sse(threadId, { since, signal }); // SSE, any framework
-for await (const e of runtime.events.follow(threadId, { signal })) { … }     // or iterate
-const missed = await runtime.events.since(threadId, lastSeq);              // raw replay
-const unsub  = await runtime.events.subscribe(threadId, handler);          // raw tail
+const { stream, headers } = runtime.events.sse(threadId, { cursor, lastMessageId, signal }); // SSE, any framework
+for await (const frame of runtime.events.follow(threadId, { cursor, signal })) { … }    // or iterate
+for await (const item of runtime.streams.read(streamId, null, signal)) { … }          // one run stream
+const missed = await runtime.events.since(threadId, lastSeq);              // the thread record, raw
+const unsub  = await runtime.events.subscribe(threadId, handler);          // raw tail of the bus
 await runtime.worker.handleJob(job);                     // queue consumer (§2.8)
-await runtime.events.publishEvent(threadId, 'MY_EVENT', payload); // your own event, same pipe
+await runtime.events.publishEvent(threadId, 'MY_EVENT', payload);                     // your own event, live only
+await runtime.events.publishEvent(threadId, 'MY_EVENT', payload, { durable: true }); // …or kept in the record
+await runtime.pruneEvents({ dryRun: true });             // after upgrading: clear old stream-only rows
 ```
 
+A follow yields frames: `{ kind: 'thread', event }` (a record entry or a
+notice), `{ kind: 'stream', streamId, item }` (a run stream item) and
+`{ kind: 'snapshot', snapshot }` (sent once when the stream the client was
+reading is gone). The cursor is one string, `<seq> <streamId> <offset>`; every
+SSE frame that moves it carries it as its `id:`, so EventSource sends it back
+as `Last-Event-ID`. See [Run streams](../../docs/run-streams.md).
+
 Tools get `publishEvent` on their second argument, bound to their thread; see
-[Custom events](../../docs/custom-events.md).
+[Custom events](../../docs/custom-events.md). It is live only unless you pass
+`{ durable: true }`.
 
 The Next.js routes in [`examples/nextjs-app`](../../examples/nextjs-app) show the HTTP
 wiring — each handler is a few lines over the runtime.
@@ -154,10 +167,16 @@ declare module 'agentenkit' {
 
 | Port | Role | Reference adapter |
 | :--- | :--- | :--- |
-| `Storage` | threads / messages / events / usage — incl. atomic `claimState` | `PrismaStorage`, `SqliteStorage` |
+| `Storage` | threads / messages / the thread record / usage — incl. atomic `claimState` | `PrismaStorage`, `SqliteStorage` |
 | `EventBus` | live fan-out + HITL death notices (at-most-once) | `RedisBus`, `UpstashBus` |
 | `Queue` | durable run dispatch (at-least-once) | `QStashQueue`, `InlineQueue` (dev) |
-| `Kv` | hot state cache, HITL handoff keys, seq/attempt counters | `RedisKv`, `UpstashKv` |
+| `Kv` | hot state cache, HITL handoff keys, segment/attempt counters | `RedisKv`, `UpstashKv` |
+| `RunStreams` | one short-lived stream per run segment | `RedisRunStreams`, `UpstashRunStreams`, `PrismaRunStreams`, `SqliteRunStreams` |
+
+Leave `streams` out and they are kept in memory, with a warning logged once.
+Only that process can read them, so when web servers and workers run apart,
+pass a real one. `PrismaRunStreams` needs the `RunStream` and `RunStreamEvent`
+models from [the example schema](../../examples/nextjs-app/prisma/schema.prisma).
 
 Implement any of them for your own stack — `core/` imports nothing else. The
 [`Memory*` adapters](./src/adapters/memory.ts) are a complete implementation used by the
@@ -207,7 +226,7 @@ platform's own tables. You do not implement `AdminStore`; you read it back:
 await runtime.admin.overview();          // threads and runs by state, plus what's in flight
 await runtime.admin.listRuns({ state: ['FAILED'], since });
 await runtime.admin.stats({ since });    // p50/p95 duration and queue wait, tokens, failures
-await runtime.admin.getRun(runId);       // one run: steps, nested runs, timeline, spend
+await runtime.admin.getRun(runId);       // one run: steps, nested runs, its record entries, spend
 ```
 
 Its schema migrates itself, from numbered migration files. `setupAgentCore`
@@ -236,7 +255,8 @@ reading your database at all.
 
 ## Adapter invariants (§3.4)
 
-1. `events.append` receives `seq` from `kv.incr('agent:seq:{threadId}')` — monotonic per thread.
+1. `events.append` takes an entry without a `seq` and the store mints it — monotonic per
+   thread, never repeated.
 2. `threads.claimState` must be atomic (one conditional UPDATE) — exactly one caller wins.
 3. `queue.enqueue` is at-least-once and the engine is idempotent. An adapter that cannot
    honour `delaySeconds` may deliver immediately, but must never throw for it — a HITL
@@ -251,7 +271,7 @@ reading your database at all.
 | Spec | Where in the package |
 | :--- | :--- |
 | §2.1 Detached execution, stop, run identity | `core/run.ts`, `core/stop.ts`, `core/engine.ts`, `core/keys.ts` |
-| §2.2 Multi-user stream | `ports/bus.ts` + `runtime.events` |
+| §2.2 Multi-user stream | `ports/bus.ts`, `ports/streams.ts`, `core/follow.ts` + `runtime.events` |
 | §2.5 HITL park, respond, expiry, reclaim | `core/hitl.ts`, `core/reclaim.ts` |
 | §2.6 Context ceiling & compaction | `core/context.ts` |
 | §2.7 Subagents as nested runs | `core/subagent.ts`, `core/loop.ts` |

package/dist/adapters/inline.d.ts

@@ -1,5 +1,5 @@
 import type { RunJob } from '../core/types.js';
-import type { EnqueueOptions, Queue } from '../ports/queue.js';
+import { type EnqueueOptions, type Queue, type QueueStats, type QueuedJob } from '../ports/queue.js';
 /** An in-process queue that actually dispatches (§2.8).
  *
  *  `MemoryQueue` only collects jobs, which is right for tests that drive the
@@ -9,7 +9,9 @@ import type { EnqueueOptions, Queue } from '../ports/queue.js';
  *  whole design rests on.
  *
  *  It honours `delaySeconds`, so the HITL expiry (§2.5) and the lock-conflict
- *  redrive (§2.8) work in development exactly as they do against a real queue.
+ *  redrive (§2.8) work in development exactly as they do against a real queue,
+ *  however long the delay. A `key` dedupes against the jobs still waiting,
+ *  and `cancel` withdraws them.
  *
  *  What it is NOT: durable. A process restart loses whatever was in flight,
  *  which is precisely what the durable adapters exist to fix. Development
@@ -17,11 +19,23 @@ import type { EnqueueOptions, Queue } from '../ports/queue.js';
 export declare class InlineQueue implements Queue {
     private handler?;
     private readonly pending;
-    /** Wired by setupAgentCore once the worker exists — the queue and the worker
-     *  each need the other, so one of them has to be attached afterwards. */
+    /** Jobs that came due before `bind`: held, not dropped. */
+    private readonly unbound;
+    /** Attach the worker once the runtime exists — the queue and the worker each
+     *  need the other, so one of them has to be wired afterwards:
+     *  `queue.bind((job) => runtime.worker.handleJob(job))`. A job that came
+     *  due before this runs is delivered now rather than lost. */
     bind(handler: (job: RunJob) => Promise<unknown>): void;
     enqueue(job: RunJob, opts?: EnqueueOptions): Promise<void>;
-    /** Drop everything still scheduled — for tests and clean shutdown. */
+    /** Set the job's timer, in steps no longer than one timer can hold. */
+    private arm;
+    cancel(key: string): Promise<void>;
+    find(runId: string): Promise<QueuedJob | null>;
+    stats(): Promise<QueueStats>;
+    private deliver;
+    /** Drop everything still scheduled — for tests and clean shutdown. What it
+     *  drops is logged: a job lost without a trace looks like a queue that does
+     *  nothing. */
     clear(): void;
 }
 //# sourceMappingURL=inline.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"inline.d.ts","sourceRoot":"","sources":["../../src/adapters/inline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/D;;;;;;;;;;;;;YAaY;AACZ,qBAAa,WAAY,YAAW,KAAK;IACvC,OAAO,CAAC,OAAO,CAAC,CAAoC;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4C;IAEpE;6EACyE;IACzE,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;IAIhD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAYhE,sEAAsE;IACtE,KAAK,IAAI,IAAI;CAId"}
+{"version":3,"file":"inline.d.ts","sourceRoot":"","sources":["../../src/adapters/inline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,UAAU,EACf,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAa3B;;;;;;;;;;;;;;;YAeY;AACZ,qBAAa,WAAY,YAAW,KAAK;IACvC,OAAO,CAAC,OAAO,CAAC,CAAoC;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC;;;kEAG8D;IAC9D,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;IAKhD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAShE,uEAAuE;IACvE,OAAO,CAAC,GAAG;IAWL,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASlC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAa9C,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAUlC,OAAO,CAAC,OAAO;IAef;;mBAEe;IACf,KAAK,IAAI,IAAI;CAOd"}

package/dist/adapters/inline.js

@@ -1,3 +1,7 @@
+import { DuplicateJobError, } from '../ports/queue.js';
+/** The longest delay one timer can hold: past about 24.8 days a timer fires
+ *  at once. A longer delay is waited out in steps of this. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
 /** An in-process queue that actually dispatches (§2.8).
  *
  *  `MemoryQueue` only collects jobs, which is right for tests that drive the
@@ -7,7 +11,9 @@
  *  whole design rests on.
  *
  *  It honours `delaySeconds`, so the HITL expiry (§2.5) and the lock-conflict
- *  redrive (§2.8) work in development exactly as they do against a real queue.
+ *  redrive (§2.8) work in development exactly as they do against a real queue,
+ *  however long the delay. A `key` dedupes against the jobs still waiting,
+ *  and `cancel` withdraws them.
  *
  *  What it is NOT: durable. A process restart loses whatever was in flight,
  *  which is precisely what the durable adapters exist to fix. Development
@@ -15,27 +21,94 @@
 export class InlineQueue {
     handler;
     pending = new Set();
-    /** Wired by setupAgentCore once the worker exists — the queue and the worker
-     *  each need the other, so one of them has to be attached afterwards. */
+    /** Jobs that came due before `bind`: held, not dropped. */
+    unbound = [];
+    /** Attach the worker once the runtime exists — the queue and the worker each
+     *  need the other, so one of them has to be wired afterwards:
+     *  `queue.bind((job) => runtime.worker.handleJob(job))`. A job that came
+     *  due before this runs is delivered now rather than lost. */
     bind(handler) {
         this.handler = handler;
+        for (const job of this.unbound.splice(0))
+            this.deliver(job);
     }
     async enqueue(job, opts) {
-        const timer = setTimeout(() => {
-            this.pending.delete(timer);
-            // Detached on purpose: a queue consumer's failure is the worker's
-            // business (§2.8 redrive), never the enqueuer's.
-            void this.handler?.(job)?.catch(() => undefined);
-        }, (opts?.delaySeconds ?? 0) * 1000);
+        if (opts?.key && [...this.pending].some((p) => p.key === opts.key)) {
+            throw new DuplicateJobError(opts.key);
+        }
+        const p = { job, key: opts?.key, runAt: Date.now() + (opts?.delaySeconds ?? 0) * 1000 };
+        this.pending.add(p);
+        this.arm(p);
+    }
+    /** Set the job's timer, in steps no longer than one timer can hold. */
+    arm(p) {
+        const wait = Math.max(0, p.runAt - Date.now());
+        p.timer = setTimeout(() => {
+            if (Date.now() < p.runAt)
+                return this.arm(p); // a long delay, not due yet
+            this.pending.delete(p);
+            this.deliver(p.job);
+        }, Math.min(wait, MAX_TIMER_MS));
         // Never hold a process open just because an expiry is scheduled.
-        timer.unref?.();
-        this.pending.add(timer);
+        p.timer.unref?.();
+    }
+    async cancel(key) {
+        if (!key)
+            return;
+        for (const p of this.pending) {
+            if (p.key !== key)
+                continue;
+            clearTimeout(p.timer);
+            this.pending.delete(p);
+        }
+    }
+    async find(runId) {
+        let found;
+        for (const p of this.pending) {
+            if (runId && p.job.runId === runId && (!found || p.runAt < found.runAt))
+                found = p;
+        }
+        return found
+            ? {
+                id: '', runId, threadId: found.job.threadId, kind: found.job.kind, attempts: 0,
+                runAt: new Date(found.runAt), position: -1,
+            }
+            : null;
+    }
+    async stats() {
+        const now = Date.now();
+        let delayed = 0;
+        for (const p of this.pending)
+            if (p.runAt > now)
+                delayed++;
+        return {
+            ready: this.pending.size - delayed + this.unbound.length, delayed, inFlight: 0, dead: 0,
+            oldestReadyMs: 0, paused: false, claimErrors: 0,
+        };
+    }
+    deliver(job) {
+        if (!this.handler) {
+            this.unbound.push(job);
+            return;
+        }
+        // Detached on purpose: a queue consumer's failure is the worker's
+        // business (§2.8 redrive), never the enqueuer's. It is still logged:
+        // swallowed, a broken worker looks like a queue that does nothing.
+        void Promise.resolve()
+            .then(() => this.handler(job))
+            .catch((err) => console.error('InlineQueue: job failed', { threadId: job.threadId, runId: job.runId }, err));
     }
-    /** Drop everything still scheduled — for tests and clean shutdown. */
+    /** Drop everything still scheduled — for tests and clean shutdown. What it
+     *  drops is logged: a job lost without a trace looks like a queue that does
+     *  nothing. */
     clear() {
-        for (const t of this.pending)
-            clearTimeout(t);
+        const dropped = this.pending.size + this.unbound.length;
+        for (const p of this.pending)
+            clearTimeout(p.timer);
         this.pending.clear();
+        this.unbound.length = 0;
+        if (dropped > 0)
+            console.warn(`InlineQueue: cleared with ${dropped} job(s) still waiting`);
     }
 }
 //# sourceMappingURL=inline.js.map

package/dist/adapters/inline.js.map

@@ -1 +1 @@
-{"version":3,"file":"inline.js","sourceRoot":"","sources":["../../src/adapters/inline.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;YAaY;AACZ,MAAM,OAAO,WAAW;IACd,OAAO,CAAqC;IACnC,OAAO,GAAG,IAAI,GAAG,EAAiC,CAAC;IAEpE;6EACyE;IACzE,IAAI,CAAC,OAA0C;QAC7C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAW,EAAE,IAAqB;QAC9C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3B,kEAAkE;YAClE,iDAAiD;YACjD,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACnD,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACrC,iEAAiE;QAChE,KAA2C,CAAC,KAAK,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,sEAAsE;IACtE,KAAK;QACH,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO;YAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}
+{"version":3,"file":"inline.js","sourceRoot":"","sources":["../../src/adapters/inline.ts"],"names":[],"mappings":"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"}

package/dist/adapters/memory.d.ts

@@ -1,24 +1,39 @@
-import type { AgentEvent, ExecutionState, MessageDTO, NewMessage, NewUsage, RunJob, ThreadDTO, UsageFilter, UsageTotals } from '../core/types.js';
+import type { AgentEvent, ExecutionState, MessageDTO, NewMessage, NewThreadEvent, ThreadEventFilter, NewUsage, RunJob, ThreadDTO, ThreadTransition, UsageFilter, UsageTotals } from '../core/types.js';
 import type { Storage } from '../ports/storage.js';
 import type { EventBus } from '../ports/bus.js';
-import type { EnqueueOptions, Queue } from '../ports/queue.js';
+import { type EnqueueOptions, type Queue, type QueueStats, type QueuedJob } from '../ports/queue.js';
 import type { Kv } from '../ports/kv.js';
+import { type RunStreams, type StreamMeta } from '../ports/streams.js';
+import { type StreamEnd, type StreamEvent, type StreamItem } from '../core/stream-events.js';
 /** In-memory Kv — tests and local prototyping. Expiry is enforced lazily on
  *  read; incr is synchronous internally, so concurrent callers can never
  *  collide on the same counter (§3.4). */
 export declare class MemoryKv implements Kv {
     private m;
+    private lastSweep;
+    /** Expired keys nobody reads again are dropped as writes come in, at most
+     *  once a minute: no timer to leak, and the map does not grow for ever. */
+    private sweep;
     get(key: string): Promise<string | null>;
     set(key: string, value: string, opts?: {
         exSeconds?: number;
         onlyIfNotExists?: boolean;
     }): Promise<boolean>;
     del(key: string): Promise<void>;
+    setIfValue(key: string, expected: string, value: string, opts?: {
+        exSeconds?: number;
+    }): Promise<boolean>;
+    delIfValue(key: string, expected: string): Promise<boolean>;
+    incrWithExpiry(key: string, exSeconds: number): Promise<number>;
     incr(key: string): Promise<number>;
 }
+/** How many of the latest published events a MemoryBus keeps in `published`:
+ *  enough for any test, bounded for a dev server that runs for days. */
+export declare const PUBLISHED_KEPT = 10000;
 /** Synchronous in-memory bus. Publishes are delivered to subscribers in order. */
 export declare class MemoryBus implements EventBus {
     private subs;
+    /** The latest PUBLISHED_KEPT events published, in order. */
     readonly published: AgentEvent[];
     publish(threadId: string, event: AgentEvent): Promise<void>;
     subscribe(threadId: string, handler: (e: AgentEvent) => void): Promise<() => void>;
@@ -32,7 +47,19 @@ export declare class MemoryQueue implements Queue {
     readonly items: RunJob[];
     /** Delivery delay requested per enqueue, index-aligned with `items`. */
     readonly delays: Array<number | undefined>;
+    /** Each job's key and priority, kept on the job itself so a test that
+     *  shifts `items` by hand leaves nothing out of step. */
+    private readonly meta;
+    /** Refuses a fresh dispatch past this many waiting jobs; 0 is unbounded. */
+    maxDepth: number;
     enqueue(job: RunJob, opts?: EnqueueOptions): Promise<void>;
+    /** The key a queued job was enqueued under. */
+    keyOf(job: RunJob): string | undefined;
+    /** The priority a queued job was enqueued with. */
+    priorityOf(job: RunJob): number;
+    cancel(key: string): Promise<void>;
+    find(runId: string): Promise<QueuedJob | null>;
+    stats(): Promise<QueueStats>;
     drain(handler: (job: RunJob) => Promise<void>): Promise<number>;
 }
 /** Full in-memory Storage — tests, demos, and a template for custom adapters. */
@@ -47,6 +74,9 @@ export declare class MemoryStorage implements Storage {
         setState(t: string, state: ExecutionState): Promise<void>;
         delete: (t: string) => Promise<void>;
         claimState(t: string, from: ExecutionState, to: ExecutionState): Promise<boolean>;
+        /** Each thread's current run (ThreadTransition). */
+        runs: Map<string, string>;
+        transition(t: string, tr: ThreadTransition): Promise<boolean>;
     };
     messages: {
         store: Map<string, MessageDTO[]>;
@@ -58,10 +88,15 @@ export declare class MemoryStorage implements Storage {
     };
     events: {
         store: Map<string, AgentEvent[]>;
-        append(t: string, e: AgentEvent): Promise<void>;
+        append(t: string, e: NewThreadEvent): Promise<AgentEvent>;
+        list(t: string, f?: ThreadEventFilter): Promise<AgentEvent[]>;
         listSince(t: string, sinceSeq: number): Promise<AgentEvent[]>;
         latest(t: string, type: string): Promise<AgentEvent | null>;
         listByType(t: string, type: string): Promise<AgentEvent[]>;
+        prune(types: string[], opts: {
+            limit: number;
+            dryRun?: boolean;
+        }): Promise<Record<string, number>>;
     };
     usage: {
         recorded: (NewUsage & {
@@ -71,4 +106,31 @@ export declare class MemoryStorage implements Storage {
         total(t: string, filter?: UsageFilter): Promise<UsageTotals>;
     };
 }
+/** In-memory RunStreams — tests and local prototyping. The offset is the
+ *  item's 1-based position. Expiry is checked on every call, and an open
+ *  drops every expired stream, so a dev server that runs for days holds only
+ *  live and recent streams. */
+export declare class MemoryRunStreams implements RunStreams {
+    private streams;
+    private live;
+    private drop;
+    private sweep;
+    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<{
+        meta: {
+            threadId: string;
+            runId: string;
+        };
+        items: StreamItem[];
+        end: StreamEnd | null;
+    } | null>;
+    close(streamId: string, end: StreamEnd, graceMs: number): Promise<void>;
+    delete(streamId: string): Promise<void>;
+    private wake;
+    /** Streams held now, expired ones included until the next sweep — lets a
+     *  test prove a stream was deleted. */
+    get size(): number;
+}
 //# sourceMappingURL=memory.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAElJ,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAKzC;;0CAE0C;AAC1C,qBAAa,QAAS,YAAW,EAAE;IACjC,OAAO,CAAC,CAAC,CAA+B;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM;IAMf,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE;IAWxF,GAAG,CAAC,GAAG,EAAE,MAAM;IACf,IAAI,CAAC,GAAG,EAAE,MAAM;CAOvB;AAED,kFAAkF;AAClF,qBAAa,SAAU,YAAW,QAAQ;IACxC,OAAO,CAAC,IAAI,CAAmD;IAC/D,QAAQ,CAAC,SAAS,EAAE,UAAU,EAAE,CAAM;IAEhC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU;IAI3C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI;IAMlE;8DAC0D;IAC1D,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAGtC;AAED;wFACwF;AACxF,qBAAa,WAAY,YAAW,KAAK;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAM;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAAM;IAC1C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc;IAI1C,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;CAUtE;AAED,iFAAiF;AACjF,qBAAa,aAAc,YAAW,OAAO;IAC3C,OAAO;;eAEQ,MAAM;sBACC;YAAE,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE;;oBASpB,MAAM,SAAS,cAAc;oBAQ7B,MAAM;sBAOJ,MAAM,QAAQ,cAAc,MAAM,cAAc;MAMpE;IAEF,QAAQ;;kBAEU,MAAM,KAAK,UAAU;gBAUvB,MAAM,SAAS;YAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;SAAE;sBAKpC,MAAM,aAAa,MAAM;MAM7C;IAEF,MAAM;;kBAEY,MAAM,KAAK,UAAU;qBAKlB,MAAM,YAAY,MAAM;kBAI3B,MAAM,QAAQ,MAAM;sBAKhB,MAAM,QAAQ,MAAM;MAIxC;IAEF,KAAK;kBACa,CAAC,QAAQ,GAAG;YAAE,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC,EAAE;kBACnC,MAAM,KAAK,QAAQ;iBACpB,MAAM,WAAU,WAAW,GAAQ,OAAO,CAAC,WAAW,CAAC;MAOtE;CAIH"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"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"}