Sessions

A session is one run of an agent. Starting it returns immediately: the agent works in a cloud sandbox while your code decides whether to wait, watch, or walk away.

Start and wait

sessions.run() starts a session and returns a SessionHandle over it. wait() polls until the session settles:

import { Ellipsis } from '@ellipsis-dev/sdk';

const client = new Ellipsis({
  apiKey: process.env.ELLIPSIS_API_TOKEN!,
});

const handle = await client.sessions.run({
  prompt: 'Fix the flaky test in ci/',
  repository: 'acme/api',
});
const session = await handle.wait({ timeoutMs: 900_000 });
console.log(session.status);

run() takes exactly the options sessions.start() takes, and handle.session holds the newest snapshot the handle has seen. handle.id is the session id, which is what you store if you want to pick the session back up later.

What "settled" means

wait() resolves when the session reaches a terminal status, completed, error, cancelled, or stopped, or when a keyed conversation parks with session_state of idle or closed. Parking matters: a durable conversation finishes each turn with a terminal per-execution status while the conversation itself is still alive, so waiting only on status would resolve early on the first turn and never on the last.

wait() polls every 3 seconds by default. Pass pollIntervalMs to change that, and timeoutMs to bound the wait; exceeding it rejects, which leaves the session running.

The same rule is exported as a function, for code that has a session and needs the verdict without a handle:

import { isSettled } from '@ellipsis-dev/sdk';

if (isSettled(session)) {
  // nothing more will happen without new input
}

Message a running session

send() posts into the session's inbox. The message is delivered at the next turn boundary, and it wakes a parked session:

await handle.send('Also update the changelog');

Pass an idempotency key to make a retried send safe:

await handle.send('Also update the changelog', {
  idempotencyKey: 'changelog-ask-1',
});

Stop and refresh

await handle.refresh(); // re-fetch the session snapshot
await handle.stop(); // stop the agent now

stop() ends the run; the session's history stays readable afterward.

Pick up an existing session

sessions.handle() builds a handle over a session you already have the id of, which is how a second process resumes watching:

const handle = await client.sessions.handle('session_7Hq2mX4p');
console.log(handle.session.status);

Without the handle

run() and handle() are the only two methods on this namespace that are not generated from the spec. Everything else is a direct call, and the handle is optional:

const response = await client.sessions.start({
  prompt: 'Fix the flaky test in ci/',
});
const sessionId = response.session.id;

The full list of session operations, with each one's parameters and response, is in the API reference.