Sessions

A session is one conversation: a stable id, an append-only message log, an in-memory provider view, and any persistent tasks. Sessions are persisted through a SessionStore — by default a SQLite file at .skawld/sessions.db — so an interrupted run can be resumed verbatim by id.

const session = await agent.session();

for await (const event of session.run("Summarize CHANGELOG.md")) {
  switch (event.type) {
    case "assistant":
      // streamed text + tool_use blocks from the model
      break;
    case "tool_call_start":
      console.log("→ calling", event.tool_name);
      break;
    case "tool_call_end":
      console.log("✓", event.tool_name, event.ok ? "ok" : "failed");
      break;
    case "result":
      console.log("done in", event.elapsed_ms, "ms");
      return;
  }
}

#session.run()

A session is created with agent.session(). Each call to session.run(prompt, opts?) kicks off a single turn of the agent loop and returns an async iterator of events. The iterator runs until the loop terminates (a result event with subtype "success", "aborted", or "error") or the consumer breaks out of the for-await loop.

#Handling the event stream

The iterator yields one of the event types in the Event union. A typical loop handles these explicitly and lets the rest fall through:

for await (const event of session.run(prompt, { signal })) {
  switch (event.type) {
    case "system":
      // First event of every run: run_id, model, tools, permission_mode, cwd
      break;
    case "partial_assistant":
      // Streamed deltas: { kind: "text" | "thinking" | "tool_use_input", ... }
      if (event.delta.kind === "text") process.stdout.write(event.delta.text);
      break;
    case "assistant":
      // Complete assistant message (text + tool_use blocks) committed to history
      break;
    case "tool_call_start":
      console.log("→", event.tool_name, event.input);
      break;
    case "tool_call_end":
      console.log(event.is_error ? "✗" : "✓", event.tool_name, event.duration_ms, "ms");
      break;
    case "permission_request":
      // canUseTool is being awaited; UI can mirror the request queue here
      break;
    case "usage":
      // Per-turn and cumulative token counts
      break;
    case "compaction":
      console.log("compacted", event.messages_before, "→", event.messages_after);
      break;
    case "result":
      // subtype: "success" | "aborted" | "error"
      console.log("done:", event.subtype, "in", event.duration_ms, "ms");
      return;
    case "error":
      console.error(event.error.name, event.error.message);
      break;
  }
}

Breaking out of the for-await loop, calling .return() on the iterator, or letting it be garbage-collected all trigger an internal cleanup hook that clears the session’s active run state. It is therefore safe to abandon a run mid-stream — the next call to session.run() will succeed on a fresh controller.

#session.abort()

#Session properties

Most session state is internal and reached only through run(), but a few fields are public and stable across resume:

#Resuming a session

Pass an id to agent.session() to resume a prior conversation. The agent calls store.create({ id, meta }), which is idempotent — if the id already exists the stored record is returned and your meta is ignored. If the id is new, a fresh row is inserted with that id. There is no "not found" error path: an unknown id silently becomes a new session with that id.

import { Agent } from "@skawld/agent-sdk";
import { InMemorySessionStore } from "@skawld/agent-sdk/sessions";

const agent = new Agent({
  provider,
  model: "gpt-5",
  sessionStore: new InMemorySessionStore(),
});

// resume an existing conversation by id
const session = await agent.session({ id: "ops-help-2026-05-28" });

What is restored on resume:

• Full message history. All messages in seq order are loaded via store.loadMessages(id) and used as the provider view. Both providerView and fullHistory start identical — compaction divergence only happens within the current process.
• Invoked skills. The ordered invokedSkills list is read off the session record and re-emitted as a skill_invoked event sequence at the start of the next run.
• Tasks and task edges. Tasks created by the task tools survive across processes; resume sees the same task ids and dependency graph the previous run wrote.
• Metadata. The original meta object is loaded. Supplying meta alongside an existing id has no effect — use session.updateMeta() to change it.

#Session stores

A SessionStore is the persistence boundary for sessions, messages, invoked skills, and tasks. The SDK ships two — implement the interface yourself to back sessions with Postgres, Redis, or any remote KV.

#SessionStore interface

Every method is async. Implementations are expected to assign monotonic seq values to messages and to bump updated_at on every write. Both bundled stores wrap multi-statement writes in a transaction; a custom store should match that behavior or accept the risk of partially-applied appends.

interface SessionStore {
  // ----- sessions -----
  create(record: { id?: string; meta?: Record<string, unknown> }): Promise<SessionRecord>;
  load(id: string): Promise<SessionRecord | undefined>;
  list(opts?: { limit?: number; offset?: number }): Promise<SessionRecord[]>;
  updateMeta(id: string, meta: Record<string, unknown>): Promise<SessionRecord>;
  delete(id: string): Promise<void>;

  // ----- messages -----
  loadMessages(id: string): Promise<StoredMessage[]>;
  appendMessages(id: string, messages: Message[]): Promise<StoredMessage[]>;

  // ----- invoked skills -----
  setInvokedSkills(id: string, skills: InvokedSkillRecord[]): Promise<void>;

  // ----- tasks -----
  createTask(sessionId: string, input: CreateTaskInput): Promise<Task>;
  getTask(sessionId: string, taskId: string): Promise<Task | undefined>;
  listTasks(sessionId: string): Promise<Task[]>;
  updateTask(sessionId: string, taskId: string, patch: TaskPatch): Promise<Task | undefined>;
  deleteTask(sessionId: string, taskId: string): Promise<boolean>;

  // ----- lifecycle -----
  close?(): Promise<void>;
}

#Built-in stores

#SqliteSessionStore

The default store. Constructed lazily on the first agent.session() call — instantiating an Agent never touches disk on its own. Both Bun and Node are supported; the constructor picks bun:sqlite under Bun and better-sqlite3 under Node at module load time.

The schema (sessions, messages, invoked_skills_json, tasks, task_edges, task_counters) is created on first open by executing a single inline DDL block — there is no migration system, no version table, and no schema-mutation surface. Schema changes between SDK versions are handled by the SDK; the store does not negotiate them.

Concurrency: every multi-statement write (appendMessages, createTask, updateTask) runs inside db.transaction(). Within one process the driver serializes; across processes you get SQLite’s file-lock semantics. close() closes the underlying database handle.

#InMemorySessionStore

Pure in-process state — five Maps, one constructor() with no arguments. Implements the same cycle-detection on task edges as the SQLite store, so tests exercising the task graph behave identically.

import { Agent } from "@skawld/agent-sdk";
import { InMemorySessionStore } from "@skawld/agent-sdk/sessions";

const agent = new Agent({
  provider,
  model: "claude-opus-4-5",
  sessionStore: new InMemorySessionStore(),
});

#Writing a custom store

Implement SessionStore end to end — there are no optional methods other than close. The skeleton below shows the full surface; wire each stub to your backend (Postgres rows, Redis hashes, a REST KV, whatever). The types come from @skawld/agent-sdk/sessions.

import type {
  SessionStore,
  SessionRecord,
  StoredMessage,
  Task,
  TaskPatch,
  CreateTaskInput,
} from "@skawld/agent-sdk/sessions";
import type { Message, InvokedSkillRecord } from "@skawld/agent-sdk";

export class MyStore implements SessionStore {
  constructor(private readonly db: MyBackend) {}

  // ----- sessions -----
  async create(r: { id?: string; meta?: Record<string, unknown> }): Promise<SessionRecord> { /* … */ }
  async load(id: string): Promise<SessionRecord | undefined> { /* … */ }
  async list(opts?: { limit?: number; offset?: number }): Promise<SessionRecord[]> { /* … */ }
  async updateMeta(id: string, meta: Record<string, unknown>): Promise<SessionRecord> { /* … */ }
  async delete(id: string): Promise<void> { /* cascade to messages + tasks + edges */ }

  // ----- messages -----
  async loadMessages(id: string): Promise<StoredMessage[]> { /* ORDER BY seq ASC */ }
  async appendMessages(id: string, messages: Message[]): Promise<StoredMessage[]> {
    // assign monotonic seq starting at MAX(seq)+1, bump updated_at, atomically
  }

  // ----- invoked skills -----
  async setInvokedSkills(id: string, skills: InvokedSkillRecord[]): Promise<void> { /* overwrite */ }

  // ----- tasks -----
  async createTask(sid: string, input: CreateTaskInput): Promise<Task> { /* … */ }
  async getTask(sid: string, taskId: string): Promise<Task | undefined> { /* … */ }
  async listTasks(sid: string): Promise<Task[]> { /* ORDER BY CAST(id AS INTEGER) */ }
  async updateTask(sid: string, taskId: string, patch: TaskPatch): Promise<Task | undefined> {
    // honor "deleted" status, validate cycles on add_blocks/add_blocked_by
  }
  async deleteTask(sid: string, taskId: string): Promise<boolean> { /* + cascade edges */ }

  // ----- lifecycle -----
  async close(): Promise<void> { await this.db.close(); }
}

const agent = new Agent({ provider, model: "claude-opus-4-5", sessionStore: new MyStore(db) });

#Lifecycle and cleanup

The store is owned by the agent. Three rules cover everything:

• Lazy construction. If you do not pass sessionStore to the agent, the default SqliteSessionStore is only instantiated on the first agent.session() call. An agent that is created and then never used to start a session does not touch disk and does not need close().
• agent.close() closes the store. It calls store.close?.() only if the store was actually allocated. For SqliteSessionStore that closes the SQLite handle; for InMemorySessionStore it is a no-op (no close defined).
• One agent, many sessions. Reusing one Agent across many session ids is the intended pattern. Each Session instance has its own append history, tracker state, and abort controller — they are isolated. The shared surface is the underlying store and the agent’s tools, model, permissions, and skills.

#Tasks and todo persistence

The task tools (TaskCreate, TaskList, TaskGet, TaskUpdate) write through the same store the session uses. A task is a tuple of id (numeric string, monotonically assigned per session starting at "1"), subject, description, optional active_form and owner, status ("pending", "in_progress", "completed"), free-form metadata, and two arrays of task ids: blocks and blocked_by.

Tasks survive resume. When you reopen a session by id, calling TaskList returns the same ordered set the previous run wrote, with the same numeric ids, the same dependency edges, and the same status. The dependency graph is validated for cycles on every edge addition — adding a blocks or blocked_by edge that would form a cycle throws "Dependency cycle detected" and leaves the graph unchanged.

Deleting a task (either via deleteTask or by patching status to "deleted" through updateTask) removes the row and every edge touching it. Deleting a session via store.delete(id) cascades to its tasks, edges, and counter.