> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarmlord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Every conversation is a long-lived, streamable session.

A **session** is one live conversation with an agent. Each session has its own memory and its own event stream.

```mermaid theme={null}
flowchart LR
    create(["createSession"])
    send(["send"])
    stream(["stream events"])
    completed(["session.completed"])
    fork(["new session, shared history"])
    aborted(["session.aborted"])
    replay(["replay missed events"])

    create --> send
    send --> stream
    stream --> completed
    send -- "fork" --> fork
    send -- "abort" --> aborted
    send -- "events?sinceSeq=N" --> replay

    classDef active fill:#ff5d73,stroke:#e63e5c,color:#fff;
    classDef terminal fill:#1f2937,stroke:#ff5d73,color:#ff8aa0;
    classDef result fill:#1f2937,stroke:#4b5563,color:#e5e7eb;

    class create,send,stream active;
    class completed,aborted terminal;
    class fork,replay result;
```

## Create one

```ts theme={null}
const session = await client.agent("hello-agent").createSession();
```

## Get a reply

```ts theme={null}
const { value } = await session
  .send({ parts: [{ type: "text", text: "Say hi." }] })
  .result<string>();
```

`result()` resolves on the first terminal event.

## Stream the events

```ts theme={null}
for await (const ev of session.stream({ parts: [{ type: "text", text: "Hi" }] })) {
  if (ev.type === "part.appended" && ev.part.type === "text") {
    process.stdout.write(ev.part.text);
  }
  if (ev.type === "session.completed") break;
}
```

## Multi-turn

A session keeps state between sends:

```ts theme={null}
const session = await client.agent("multi-turn").createSession();
await session.send({ parts: [{ type: "text", text: "My name is Ada." }] }).result();
const { value } = await session.send({ parts: [{ type: "text", text: "What's my name?" }] }).result();
// → "Your name is Ada."
```

## Fork

Snapshot a session and continue both branches independently:

```ts theme={null}
const forkRes = await fetch(`https://api.swarmlord.ai/session/${root.id}/fork`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
});
const { id } = await forkRes.json();
const forked = client.session(id);
```

## Resume

Reconnect to a session and replay missed events:

```ts theme={null}
import { streamSession } from "swarmlord";

const stream = streamSession(session.id, {
  opts: { apiKey },
  sinceSeq: lastSeen,
});
```

Recent events are kept around for replay — any practical reconnect window is covered.

## Abort

```ts theme={null}
await session.abort();
```

Cancels the in-flight model call and emits `session.aborted`.

## Terminal guarantee

Every session reaches a terminal event (`session.completed`, `session.completed_degraded`, or `session.aborted`). Consumers never hang.

See [Events](/api/events) for the full vocabulary.