Sessions

import { createAgent } from '@lousho/build-ai-agent';

const chat = createAgent({ instructions: 'Be brief.', provider });

const session = chat.session(); // in memory, new generated id
await session.send('My name is Ali.');
const { text } = await session.send('What is my name?'); // sees the first exchange

console.log(session.id, session.messages.length);

​

The session object

• 'wait' (the default): it waits and runs as its own turn, as above.
• 'queue': its input joins that turn, like run.enqueue(): it is added after the current step’s tool results and the turn’s next model call sees it. The call resolves with that turn’s result (its own signal does not apply to the turn), and the transcript saved when the turn ends holds the queued user message in order. A joining stream() yields only the turn’s run.done; the turn’s events, input.queued and input.applied included, stream on the run that started it. If the turn ends before it could take the input (it finished, paused or was aborted), the call runs as the next turn after all. If the turn fails, the call rejects with the same error; in a durable session the input stays in the turn’s checkpoint and resume() applies it.
• 'steer': like 'queue', but the input joins through run.steer(): if the turn’s model call has not emitted anything yet, it is aborted and made again with the new message, and tool calls of the turn that have not started are not run. Otherwise it waits for the next safe point, as with 'queue'. The call resolves with the turn’s result, and the same fallbacks apply.

import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });
const session = agent.session({ id: 'user-42', turnPolicy: 'queue' });

const first = session.send('Find flights to Rome.');
const second = session.send('Only direct ones, please.'); // joins the first turn
console.log((await second) === (await first)); // true: one turn, one result

​

Streaming a session turn

import { createAgent } from '@lousho/build-ai-agent';

const chat = createAgent({ instructions: 'Be brief.', provider });
const session = chat.session();

for await (const event of session.stream('My name is Ali.')) {
  if (event.type === 'text.delta') process.stdout.write(event.text);
}
// The turn is already saved: this call sees it.
const { text } = await session.send('What is my name?');

• It builds the same message list as send() and queues behind earlier calls on the session (send() and stream() can be mixed).
• When the run ends, the new user message and the run’s output are saved exactly as send() saves them, and only then is run.done delivered. When the for await loop ends, or run.result resolves, the transcript is complete. The events carry the runId of the returned handle.
• An aborted run (signal, or breaking out of the loop early) or a failed one leaves the transcript as it was before the call, like send(). A run that was already finished when the loop was left is saved. A failed run ends the stream with error and run.done (finishReason: 'error'), and run.result rejects. This includes a store that fails to load or save: the turn then has no run.start.
• A run that pauses on a needsApproval tool ends with approval.requested and run.done ('awaiting-approval'), exactly as send() resolves, and the transcript holds the turn up to the pause. agent.approvals.resolve() continues it as the session’s next turn. An approve callback does not apply to streams, as with agent.stream().

​

Durable sessions

import { createAgent } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';

const agent = createAgent({ provider, store: new SqliteStore('./.lousho/agent.db') });

// After a restart: finish the turn that was running, if any.
const finished = await agent.resume('user-42'); // ExecutionResult, or null when nothing was pending
console.log(finished?.text, await agent.session({ id: 'user-42' }).pending()); // pending() is null now

• createAgent({ store }) takes any AgentStore ({ sessions?, checkpoints?, approvals? }, see Choosing a store): agent.session({ id }) keeps its transcript in store.sessions and checkpoints in store.checkpoints, and store.approvals holds approval pauses. A session’s own store (a SessionStore, or a { sessions, checkpoints } object) and checkpointStore win over the agent’s, part by part.
• agent.resume(id) is agent.session({ id }).resume(), except that it first finishes a run started with agent.send(message, { sessionId: id }) (see Durable execution).
• Each turn runs with sessionId: '<session id>.turn-<n>' (n is the length of the transcript when the turn started), so a new process finds the interrupted turn without any extra bookkeeping. A finished turn joins the transcript, exactly as a plain send() does, and its checkpoint is deleted.
• resume() continues the turn through the executor’s resume path (input: []): tool calls whose results were recorded do not run again, and a recorded model response is not requested again. A tool that was running when the process died does run again (at-least-once, see Durable execution).
• send() and stream() resume a pending turn first, then send the new message, so the model sees the finished turn (the resumed turn’s events are not streamed). Use pending() to check first, or discardPending() to drop the unfinished turn instead.
• A turn that pauses on a needsApproval tool stays in its checkpoint, not in the transcript, until it finishes. While it waits, resume(), send() and stream() throw SessionAwaitingApprovalError (with its approvalId), and agent.approvals.resolve({ id, approved }) continues the turn in this session. After a restart, open the session and call resume() (or send()) once before resolving, so the agent knows which session the approval belongs to; give both agents the same durable store (or approvalStore).
• An aborted turn is dropped (its checkpoint is deleted), as without a checkpoint store. clear() deletes a pending turn too.

​

Stores

import type { Message } from '@lousho/build-ai-agent';

interface SessionStore {
  load(id: string): Promise<Message[] | undefined>;
  save(id: string, messages: readonly Message[]): Promise<void>;
  delete(id: string): Promise<void>;
}

• MemorySessionStore (the default, one new store per session) lives as long as the process. Share one instance between sessions to look them up by id.
• FileSessionStore(dir) writes one JSON file per session (<dir>/<id>.json), atomically (temp file, then rename), creating dir on first save.

import { createAgent, FileSessionStore } from '@lousho/build-ai-agent';

const agent = createAgent({ provider });
const store = new FileSessionStore('./.lousho/sessions');

const first = agent.session({ id: 'user-42', store });
await first.send('My name is Ali.');

// Later, even in another process or another createAgent() instance:
const again = agent.session({ id: 'user-42', store });
await again.send('What is my name?'); // "Ali"

​

Choosing a store

import {
  createAgent,
  FileSessionStore,
  LocalStorageCheckpointStore,
  StorageServiceApprovalStore,
  type AgentStore,
} from '@lousho/build-ai-agent';

// `storage` is a StorageService rooted where the files should go.
const store: AgentStore = {
  sessions: new FileSessionStore('./.lousho/sessions'),
  checkpoints: new LocalStorageCheckpointStore(storage),
  approvals: new StorageServiceApprovalStore(storage),
};
const agent = createAgent({ provider, store });

import { createAgent, AgentExecutor } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';

const store = new SqliteStore('./.lousho/agent.db'); // or ':memory:'
const agent = createAgent({ provider, store }); // transcripts, per-step checkpoints and approvals
await agent.session({ id: 'user-42' }).send('Hello');

// With AgentExecutor directly, pass the parts:
// AgentExecutor.execute({ ..., sessionId, checkpointStore: store.checkpoints, approvalStore: store.approvals })

store.prune({ olderThanMs: 7 * 24 * 60 * 60 * 1000 }); // { sessions, checkpoints, approvals } deleted
store.close();

• The directory is created if missing. The schema is versioned with PRAGMA user_version and migrated on open; a database written by a newer release is refused.
• WAL mode and a 5 s busy timeout let two processes share the file. An approval can be resolved by only one of them.
• Checkpoints and approval snapshots are stored as opaque JSON, so new fields round-trip unchanged.
• prune() removes sessions and checkpoints not updated within olderThanMs, and approvals resolved that long ago; unresolved approvals are kept.
• A file that is not a SQLite database fails with an error naming the path; using the store after close() throws a clear error.

​

Project instructions