Conventions

Four things hold everywhere in the SDK.

Every `list*` reads all pages

A list* method returns the whole collection, not the server’s first page — it keeps reading until it has everything, adopting whatever page size the server honoured.

const projects = await aura.listProjects();                            // all of them
const files = await aura.listFiles({ source: "workspace", projectId }); // all of them

This avoids a class of silent bug: deploy prunes remote files by diffing a listing, so a short read would delete files that are still there. The cost is that a large collection takes several round-trips inside one await.

Types are generated, not hand-written

Request and response types come from the backend’s OpenAPI spec, filtered to the public /api/v1 surface, and are re-exported by name:

import type { Project, Execution, Snapshot, FileEntry } from "@strangeworks/aura-sdk";

Because they are generated, a response type is exactly what the server sends. The REST reference documents what is inside each one; the API reference documents the methods that return them.

Four error types, one base

AuraApiError (the call was rejected), AuraResponseError (the answer was unreadable), AuraTurnCancelledError (a turn stopped early) and AuraTurnTimeoutError (your wait elapsed) all extend AuraError, so one catch covers everything and instanceof tells them apart. Errors has the detail.

Snapshots are the only container writes can’t reach

uploadFile / deleteFile write through the same FileContainer you already pass to listFiles / readFile: a workspace or deployment container accepts the write, a snapshot container rejects it — a run’s captured state has to stay retrievable. Prefer asking the agent in a turn to change a project’s inputs; reach for these methods directly for out-of-band writes, like staging a dashboard file. See File containers for when to use which container.