Sessions

A session is an interactive, multi-turn conversation with an agent. Sessions are durable — create one, have a conversation, close your script, come back tomorrow, and pick up exactly where you left off.

Each session gets its own Linux sandbox with a full filesystem, shell, and installed runtimes.

Create a Session

const agent = client.agent("build");
const session = await agent.createSession({ title: "Build Todo App" });

Send Messages

Use session.send() to send a message and stream the response:

const result = await session.send("Create a REST API with Hono", {
    onText: delta => process.stdout.write(delta),
    onToolStart: part => console.log(`[tool] ${part.tool} started`),
    onToolComplete: part => console.log(`[tool] ${part.tool} done`),
});

console.log(result.text); // full response
console.log(result.parts); // all parts (text, tools, etc.)

The conversation is stateful — each send() builds on the previous context:

await session.send("Create a REST API with Hono");
await session.send("Now add authentication");
await session.send("Add tests for the auth middleware");

Resume a Session

Sessions persist across processes. Save the ID and resume later:

// Save this somewhere
const sessionId = session.id;

// Later — even from a different machine
const resumed = client.session(sessionId);
const info = await resumed.getInfo();
console.log(`Resumed "${info.title}" — status: ${info.status}`);

await resumed.send("Continue where we left off");

Fork a Session

Fork creates a copy of a session at its current state. Explore a different approach without losing the original:

const fork = await agent.forkSession(session.id);
await fork.send("Actually, try a different approach using Fastify instead");

// Original session is untouched
const original = client.session(session.id);
await original.send("Keep going with the Hono approach");

Session Management

// Get session info
const info = await session.getInfo();
console.log(info.title, info.status);

// Get message history
const messages = await session.getMessages();

// Get usage metrics
const metrics = await session.getMetrics();
console.log(`${metrics.toolCalls} tool calls, $${metrics.cost.toFixed(4)}`);

// Get the agent's todo list
const todos = await session.getTodos();

// Trigger context compaction (summarize long conversations)
await session.summarize();

// Undo to a specific message
await session.revert(messageId);

// Cancel current turn
await session.abort();

// End session and its sandbox
await session.end();

List Sessions

const sessions = await client.listSessions({ limit: 20, archived: false });
for (const s of sessions) {
    console.log(`${s.id} — ${s.title} (${s.status})`);
}

Full Example

import { createClient } from "swarmlord";

const client = createClient({
    apiKey: process.env.SWARMLORD_API_KEY!,
});

const agent = client.agent("build");

// Create and use a session
const session = await agent.createSession({ title: "Fibonacci" });

await session.send("Write a fibonacci function in TypeScript to /workspace/fib.ts", {
    onText: delta => process.stdout.write(delta),
});

// Resume from just an ID
const resumed = client.session(session.id);
await resumed.send("Add memoization to the fibonacci function", {
    onText: delta => process.stdout.write(delta),
});

// Fork to try an alternative
const fork = await agent.forkSession(session.id);
await fork.send("Rewrite it as an iterative solution instead", {
    onText: delta => process.stdout.write(delta),
});

// Compare
const originalMsgs = await session.getMessages();
const forkMsgs = await fork.getMessages();
console.log(`Original: ${originalMsgs.length} messages`);
console.log(`Fork: ${forkMsgs.length} messages`);

// Cleanup
await fork.end();
await session.end();