v0.0.31 — Sessions Client for Historical Traces

Standalone Sessions Client (#36)

Query past sessions and download full trace files programmatically — the API equivalent of the dashboard traces page.

TypeScript:

import { sessions } from "@evolvingmachines/sdk";

const session = sessions(); // uses EVOLVE_API_KEY
const page = await session.list({ limit: 10, state: "ended", agent: "claude", tagPrefix: "my-proj", sort: "cost" });
const info = await session.get(page.items[0].id);
const events = await session.events(info.id, { since: 50 });
const path = await session.download(info.id, { to: "./traces" });

Python:

from evolve import sessions

async with sessions() as session:
    page = await session.list(limit=10, state='ended', agent='claude', tag_prefix='my-proj', sort='cost')
    info = await session.get(page.items[0].id)
    events = await session.events(info.id, since=50)
    path = await session.download(info.id, to='./traces')

4 Methods

Method	Returns	Description
list()	SessionPage	Paginated listing with state, agent, tagPrefix, sort filters
get()	SessionInfo	Single session metadata (cost, runtimeStatus, toolStats, etc.)
events()	SessionEvent[]	Parsed JSONL events with delta fetching via since
download()	string	Streams raw .jsonl trace to disk, returns file path

SessionInfo Fields

id, tag, agent, model, provider, sandboxId, state, runtimeStatus, cost, createdAt, endedAt, stepCount, toolStats

Dashboard Changes

• shapeSessionForApi() — centralized response shaper, strips internal fields
• Streaming download via S3 presigned URL redirect (no buffering)
• Dual auth on all session endpoints (Bearer API key + NextAuth session)

Test Coverage

• TS SDK: 62 unit tests + 10 integration tests against live dashboard
• Python SDK: 15 unit tests + 10 integration tests against live dashboard
• Dashboard: 13 unit tests for shapeSessionForApi and runtime status resolution

Gateway-only — requires EVOLVE_API_KEY.

Install

npm install @evolvingmachines/sdk@0.0.31   # TypeScript
pip install evolve-sdk==0.0.31             # Python