Class: Thread<TContext, TOutput>

Defined in: packages/kernl/src/thread/thread.ts:90

A thread drives the execution loop for an agent.

Ground principles:

1. Event log is source of truth.

   • Persistent storage (e.g. Postgres) is treated as an append-only per-thread log of ThreadEvents: monotonic seq, no gaps, no updates/deletes.
   • Thread.state, tick, etc. are projections of that log, not an alternative source of truth.

2. Single writer per thread.

   • At most one executor is allowed for a given tid at a time.
   • Callers are responsible for enforcing this (e.g. locking/versioning) so two processes cannot interleave or race on seq or state.

3. Persist before use / observation.

   • Before an event can:
     • influence a future tick (i.e. be part of history fed back into the model), or
     • be considered “delivered” to a client, it SHOULD be durably written to storage when storage is configured.

4. Transaction boundaries match semantic steps.

   • The intended strategy is to buffer within a tick, then atomically persist all new events + state at the end of tick().
   • After a crash, you only ever see whole ticks or none, never half a tick, from the store’s point of view.

5. Recovery is replay.

   • On restart, callers rebuild a Thread from the stored event log (plus optional snapshots).
   • Any incomplete tick or pending tool call is handled by a clear, deterministic policy at a higher layer (e.g. re-run, mark failed, or require manual intervention).

On storage failures:

“If storage is configured, it is authoritative” → fail hard on persist errors rather than treating persistence as best-effort.

If a storage implementation is present, persist(...) is expected to throw on failure, and that error should bubble out of _execute() / stream() and stop the thread.

Type Parameters

Constructors

Constructor

new Thread<TContext, TOutput>(options: ThreadOptions<TContext, TOutput>): Thread<TContext, TOutput>;

Defined in: packages/kernl/src/thread/thread.ts:117

Parameters

Returns

Thread<TContext, TOutput>

Properties

Methods

append()

append(...items: LanguageModelItem[]): ThreadEvent[];

Defined in: packages/kernl/src/thread/thread.ts:375

Append one or more items to history + enrich w/ runtime headers.

Core rule:

An event becomes a ThreadEvent (and gets seq/timestamp) exactly when it is appended to history. <

Parameters

Returns

ThreadEvent[]

cancel()

cancel(): void;

Defined in: packages/kernl/src/thread/thread.ts:397

Cancel the running thread

TODO: Emit thread.stop when cancelled (neither result nor error set)

Returns

void

execute()

execute(): Promise<ThreadExecuteResult<ResolvedAgentResponse<TOutput>>>;

Defined in: packages/kernl/src/thread/thread.ts:152

Blocking execution - runs until terminal state or interruption

Returns

Promise<ThreadExecuteResult<ResolvedAgentResponse<TOutput>>>

stream()

stream(): AsyncIterable<ThreadStreamEvent>;

Defined in: packages/kernl/src/thread/thread.ts:170

Streaming execution - returns async iterator of events

All runs (new or resumed) emit:

• Exactly one thread.start
• Zero or more model.call.* and tool.call.*
• Exactly one thread.stop (with result on success, error on failure)

Returns

AsyncIterable<ThreadStreamEvent>