AuraClient

Thin client for the Strangeworks Aura public /api/v1 surface.

Authenticates with a company API key (sk-aura-…). chat delivers a turn live over the project WebSocket (key on the upgrade header) and reconciles the final message via /chat/sync; when the socket can’t be held open it degrades to dispatch + poll.

Constructors

Constructor

new AuraClient(options): AuraClient;

Parameters

Parameter	Type
`options`	`AuraClientOptions`

Returns

AuraClient

Properties

Property	Modifier	Type	Description
`baseUrl`	`readonly`	`string`	The Aura origin this client talks to, without a trailing slash.

Methods

cancel()

cancel(projectId, conversationId?): Promise<boolean>;

Stop a running turn, scoped to conversationId when given and to the whole project otherwise. Returns whether anything was cancelled.

Parameters

Parameter	Type
`projectId`	`string`
`conversationId?`	`string`

Returns

Promise<boolean>

chat()

chat(
   projectId,
   content,
   opts?): Promise<{
}>;

Send a message, follow the turn live, and return the reply to this dispatch. onDelta receives assistant text as it is generated and onToolActivity each tool start/completion, streamed over the project WebSocket. The stream is liveness only — the returned message always comes from a final /chat/sync reconcile, and when the socket can’t be opened or dies mid-turn the call silently degrades to a polling wait (see waitForIdleReply): the reply is unaffected, only the live callbacks stop.

The wait is pinned to the conversation the dispatch resolved to, so a concurrent activate or createConversation on the same project cannot make it watch another thread.

A socket that dies announces itself, but one that goes half-open does not; it simply stops delivering, and a turn’s terminal event with it. So the wait never concludes anything from silence: whenever the stream has been quiet for quietProbeMs, and again before the deadline is allowed to expire, the turn’s state is read back from the server. A turn that has finished is returned, however its stream_end was lost.

Throws AuraTurnTimeoutError on timeout — it carries the pinned conversation id to pass to cancel, and the turn keeps running server-side — and AuraTurnCancelledError when the turn ended partially or opts.signal aborts, carrying whatever partial output was streamed or stored, so a caller that stopped the turn can still show what it produced.

Parameters

Parameter	Type
`projectId`	`string`
`content`	`string`
`opts`	`ChatTurnOptions`

Returns

Promise<{ }>

checkDeployment()

checkDeployment(name): Promise<{
}>;

Run the server-side run contract against a deployment: does it have a solver package under run/ and a dataset under data/?

Parameters

Parameter	Type
`name`	`string`

Returns

Promise<{ }>

ok, plus missing and warnings naming what a project created from this deployment would fail on.

checkout()

checkout(
   projectId,
   source,
   conversationId?): Promise<{
}>;

Point the project’s workspace at source, which the server dispatches on segment count: one segment is a snapshot id or a tag name, two is a <group>/<name> deployment handle, three is a <group>/<project>/<name> in-project snapshot tag.

Rejects with a 409 while a turn is in flight, and while another checkout or snapshot already holds the workspace — a checkout clears the tree before it copies, so two of them interleaved would leave files from both sources.

Parameters

Parameter	Type
`projectId`	`string`
`source`	`string`
`conversationId?`	`string`

Returns

Promise<{ }>

createConversation()

createConversation(projectId, title?): Promise<{
}>;

Start a new conversation in a project.

Parameters

Parameter	Type	Description
`projectId`	`string`	-
`title?`	`string`	Optional label; the server names it if omitted.

Returns

Promise<{ }>

createDashboardTicket()

createDashboardTicket(projectId): Promise<{
}>;

Mint a short-lived view ticket for the project’s run dashboard.

The dashboard is a live web app in the project’s sandbox. The ticket stands in for your API key in a place a key must never go — a URL a browser opens, or an <iframe src>. It is scoped to this one project’s dashboard, is read-only, and expires; mint another when it does.

path is returned relative to the API origin, so the response never has to guess which hostname you reached; dashboardUrl composes the two.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<{ }>

Throws

AuraApiError 409 if the project has no run dashboard yet.

createDeployment()

createDeployment(name): Promise<{
}>;

Create an empty deployment. Upload its files with deployFromFolder or uploadFile against a { source: "deployment", deploymentName } container, then confirm it with checkDeployment.

Parameters

Parameter	Type	Description
`name`	`string`	Deployment name — lowercase letters, digits and hyphens.

Returns

Promise<{ }>

createProject()

createProject(input): Promise<{
}>;

Create a project, optionally seeded from a published deployment. A project seeded from a deployment lands directly in run mode, so the run agent is usable on it immediately.

Parameters

Parameter	Type	Description
`input`	{ `description?`: `string`; `fromDeployment?`: `string`; `name`: `string`; `shortDescription?`: `string`; }	-
`input.description?`	`string`	-
`input.fromDeployment?`	`string`	A deployment handle, “/”. The wire field is `from`.
`input.name`	`string`	-
`input.shortDescription?`	`string`	-

Returns

Promise<{ }>

Throws

AuraApiError when the deployment handle is unknown or fails its run contract.

dashboardUrl()

dashboardUrl(projectId): Promise<string>;

The absolute URL of the project’s run dashboard, ticket included.

A one-call shorthand for createDashboardTicket when all you want is somewhere to point a browser. Use the ticket itself when you need to know when it expires.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<string>

deleteConversation()

deleteConversation(projectId, conversationId): Promise<void>;

Delete one conversation and its messages. The project is untouched.

Parameters

Parameter	Type
`projectId`	`string`
`conversationId`	`string`

Returns

Promise<void>

deleteDeployment()

deleteDeployment(name): Promise<{
}>;

Delete a deployment: its files are purged and its name is freed for reuse.

Irreversible — there is no undelete, and a new deployment claiming the same name starts empty. Projects already seeded from this deployment keep their own copy of the workspace and are not touched; the returned seeded_project_count reports how many there were.

Requires an admin, which every API key satisfies.

Parameters

Parameter	Type
`name`	`string`

Returns

Promise<{ }>

Throws

AuraApiError with status 404 when no such deployment exists.

deleteDeploymentInstructions()

deleteDeploymentInstructions(name): Promise<void>;

Parameters

Parameter	Type
`name`	`string`

Returns

Promise<void>

deleteDeploymentSkill()

deleteDeploymentSkill(name, skill): Promise<void>;

Parameters

Parameter	Type
`name`	`string`
`skill`	`string`

Returns

Promise<void>

deleteFile()

deleteFile(
   container,
   path,
   conversationId?): Promise<{
}>;

Remove one file from a container. Not recursive — pass a file path, not a directory.

Parameters

Parameter	Type	Description
`container`	`FileContainer`	-
`path`	`string`	-
`conversationId?`	`string`	Announce the deletion on this conversation; see uploadFile.

Returns

Promise<{ }>

deleteProject()

deleteProject(projectId): Promise<void>;

Delete a project and everything in it — conversations, executions, snapshots and the workspace. Not recoverable.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<void>

deleteProjectInstructions()

deleteProjectInstructions(projectId): Promise<void>;

Delete every instruction block the project holds — never the deployment’s.

Both its own and its copy of the deployment’s, since both are the project’s. The deployment keeps its own, so siblings are unaffected and this project gets the rules back via pullAgentConfig.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<void>

deleteProjectSkill()

deleteProjectSkill(projectId, skill): Promise<void>;

Remove a skill from the project, whichever scope holds it — never the deployment’s.

The deployment keeps its own copy, so siblings are unaffected and this project gets the skill back via pullAgentConfig.

Parameters

Parameter	Type
`projectId`	`string`
`skill`	`string`

Returns

Promise<void>

getAgentStatus()

getAgentStatus(projectId): Promise<{
}>;

Whether a turn is in flight, without inferring it from /chat/sync.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<{ }>

getConversationState()

getConversationState(projectId, conversationId?): Promise<{
}>;

An atomic snapshot of a conversation: the messages the server has stored, plus whether a turn is in flight.

Parameters

Parameter	Type	Description
`projectId`	`string`	-
`conversationId?`	`string`	Defaults to the project’s active conversation at the time of the call, so pass it explicitly when polling a specific thread.

Returns

Promise<{ }>

getDeployment()

getDeployment(name): Promise<{
}>;

One deployment by name.

Parameters

Parameter	Type
`name`	`string`

Returns

Promise<{ }>

Throws

AuraApiError with status 404 when no such deployment exists.

getDeploymentInstructions()

getDeploymentInstructions(name): Promise<{
}>;

content is null when the deployment ships no instructions; a 404 means no such deployment.

Parameters

Parameter	Type
`name`	`string`

Returns

Promise<{ }>

getDeploymentSkill()

getDeploymentSkill(name, skill): Promise<{
}>;

One skill in full, file bodies included.

Separate from listDeploymentSkills, which carries filenames only — describing twenty skills should not ship every byte of all of them.

Parameters

Parameter	Type
`name`	`string`
`skill`	`string`

Returns

Promise<{ }>

Throws

AuraApiError with status 404 when the deployment ships no such skill.

getExecution()

getExecution(projectId, executionId): Promise<{
}>;

One solve execution by id.

Parameters

Parameter	Type
`projectId`	`string`
`executionId`	`string`

Returns

Promise<{ }>

getProject()

getProject(projectId): Promise<{
}>;

One project in full.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<{ }>

Throws

AuraApiError with status 404 when no such project exists.

getProjectInstructions()

getProjectInstructions(projectId): Promise<{
}>;

Both blocks in force for a project: the deployment scope, and the project’s own.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<{ }>

getProjectSkill()

getProjectSkill(projectId, skill): Promise<{
}>;

One of the project’s skills in full, with which scope is in force for it.

The project’s own copy when it has one, since that is the copy a turn mounts — the shadowed deployment one would describe rules that do not apply.

Parameters

Parameter	Type
`projectId`	`string`
`skill`	`string`

Returns

Promise<{ }>

Throws

AuraApiError with status 404 when no such skill is in force.

getSnapshot()

getSnapshot(projectId, ref): Promise<{
}>;

One snapshot, including its files — which the list response omits.

Parameters

Parameter	Type	Description
`projectId`	`string`	-
`ref`	`string`	A snapshot id or a tag name defined in this project.

Returns

Promise<{ }>

getUsage()

getUsage(window?): Promise<{
}>;

Company-wide usage, with the slice attributable to no user or key broken out as unattributed.

Parameters

Parameter	Type
`window?`	`UsageWindow`

Returns

Promise<{ }>

getWorkspace()

getWorkspace(projectId): Promise<{
}>;

Read what the workspace is on, and whether a checkout is rewriting it.

checkout_in_flight comes from the lock a running checkout holds, so it is a level to poll rather than an event to have received — useful before issuing a checkout of your own, which the server refuses with a 409 while another one holds the workspace.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<{ }>

listApiKeyUsage()

listApiKeyUsage(window?): Promise<object[]>;

Usage grouped per API key, spend-descending. Reads all pages. Revoked keys keep their history and come back flagged revoked.

Parameters

Parameter	Type
`window?`	`UsageWindow`

Returns

Promise<object[]>

listConversations()

listConversations(projectId): Promise<object[]>;

A project’s conversations, newest first. Reads all pages.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<object[]>

listDeployments()

listDeployments(): Promise<object[]>;

Every deployment in your company, newest first. Reads all pages.

Returns

Promise<object[]>

listDeploymentSkills()

listDeploymentSkills(name): Promise<object[]>;

The customer skills this deployment ships, which its projects pull.

Parameters

Parameter	Type
`name`	`string`

Returns

Promise<object[]>

listExecutions()

listExecutions(projectId): Promise<object[]>;

Solve executions for the project, most recent first — the run the agent triggered.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<object[]>

listFiles()

listFiles(container, pathPrefix?): Promise<object[]>;

The files currently in a container. Reads all pages.

Parameters

Parameter	Type	Description
`container`	`FileContainer`	-
`pathPrefix?`	`string`	Restrict to one subtree, e.g. `"solutions/"`.

Returns

Promise<object[]>

listProjects()

listProjects(): Promise<object[]>;

Every project in your company, as summaries rather than full projects. Reads all pages.

Returns

Promise<object[]>

listProjectSkills()

listProjectSkills(projectId): Promise<{
}>;

The skills in force for a project, split by the scope that set them.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<{ }>

listSnapshots()

listSnapshots(projectId, filters?): Promise<object[]>;

A project’s snapshots, newest first, so index 0 is the most recent. Reads all pages.

Parameters

Parameter	Type	Description
`projectId`	`string`	-
`filters`	`SnapshotFilters`	Narrow the list server-side; omitted fields don’t filter, and the given ones combine (AND). `{ kind: "solve", hasSolution: true }` is the “give me the solutions” query.

Returns

Promise<object[]>

listTags(projectId): Promise<object[]>;

A project’s snapshot tags. Reads all pages.

Parameters

Parameter	Type
`projectId`	`string`

Returns

Promise<object[]>

listUserUsage()

listUserUsage(window?): Promise<object[]>;

Usage grouped per user, spend-descending. Reads all pages. Key-driven spend is under listApiKeyUsage.

Parameters

Parameter	Type
`window?`	`UsageWindow`

Returns

Promise<object[]>

pullAgentConfig()

pullAgentConfig(
   projectId,
   fromDeployment,
   options?): Promise<{
}>;

Pull a deployment’s instructions and/or skills into the project’s deployment scope.

The non-destructive half of a checkout: the project takes the operator’s current rules without checkout overwriting work in flight. Replaces the deployment scope rather than merging, so a retired rule stops applying; the project’s own scope is untouched. Both kinds are pulled unless narrowed.

Parameters

Parameter	Type
`projectId`	`string`
`fromDeployment`	`string`
`options?`	{ `instructions?`: `boolean`; `skills?`: `boolean`; }
`options.instructions?`	`boolean`
`options.skills?`	`boolean`

Returns

Promise<{ }>

readFile()

readFile(container, path): Promise<{
}>;

Read one file. text is set for text files, base64 for binary.

Parameters

Parameter	Type
`container`	`FileContainer`
`path`	`string`

Returns

Promise<{ }>

renameSnapshot()

renameSnapshot(
   projectId,
   snapshotId,
   label): Promise<{
}>;

Set, change, or clear a snapshot’s label — its display title. A label is not a ref; to fetch a snapshot by name, tag it (setTag) instead.

Parameters

Parameter	Type	Description
`projectId`	`string`	-
`snapshotId`	`string`	-
`label`	`string` \| `null`	The new label, or `null` to clear it (which also unpins the snapshot from retention pruning, unless it also carries a tag).

Returns

Promise<{ }>

sendMessage()

sendMessage(projectId, input): Promise<{
}>;

Dispatch a message without waiting for the agent’s reply — chat is the one-await version. Use this when you want to drive the polling yourself with getConversationState.

Parameters

Parameter	Type
`projectId`	`string`
`input`	`object` & `SendChatOptions`

Returns

Promise<{ }>

The dispatch result, including the stored user message and its sequence — which is what identifies the reply to this message.

setDeploymentInstructions()

setDeploymentInstructions(name, content): Promise<{
}>;

Parameters

Parameter	Type
`name`	`string`
`content`	`string`

Returns

Promise<{ }>

setDeploymentSkill()

setDeploymentSkill(
   name,
   skill,
   files): Promise<{
}>;

Create or replace one customer skill.

files is keyed by path relative to the skill’s own directory and must include SKILL.md. The whole file set is replaced rather than merged, so a file dropped locally does not linger server-side.

Parameters

Parameter	Type
`name`	`string`
`skill`	`string`
`files`	`Record`<`string`, `string`>

Returns

Promise<{ }>

setProjectInstructions()

setProjectInstructions(projectId, content): Promise<{
}>;

Parameters

Parameter	Type
`projectId`	`string`
`content`	`string`

Returns

Promise<{ }>

setProjectSkill()

setProjectSkill(
   projectId,
   skill,
   files): Promise<{
}>;

Create or replace one of the project’s own skills.

Naming it after one of the deployment’s skills shadows it for this project alone, leaving the deployment untouched. files is keyed by path relative to the skill’s own directory and must include SKILL.md.

Parameters

Parameter	Type
`projectId`	`string`
`skill`	`string`
`files`	`Record`<`string`, `string`>

Returns

Promise<{ }>

setTag()

setTag(
   projectId,
   name,
   snapshotId): Promise<{
}>;

Point a tag at a snapshot, creating it or moving an existing one. Idempotent.

Parameters

Parameter	Type	Description
`projectId`	`string`	-
`name`	`string`	The tag name, e.g. `"best-known"`.
`snapshotId`	`string`	-

Returns

Promise<{ }>

uploadFile()

uploadFile(
   container,
   path,
   body,
   contentType,
   conversationId?): Promise<{
}>;

Upload one file via the unified files API: plan → PUT the bytes to the plan URL → complete. The byte PUT targets the plan URL directly (presigned on R2, a tokenized backend URL in dev) with only the plan’s headers — never the API key.

Parameters

Parameter	Type	Description
`container`	`FileContainer`	-
`path`	`string`	Destination inside the container. A workspace destination must name a directory (`data/orders.csv`, not `orders.csv`).
`body`	`string` \| `Uint8Array`<`ArrayBufferLike`>	-
`contentType`	`string`	-
`conversationId?`	`string`	Announce the write on this conversation, so the project’s agent re-reads the file on its next turn instead of trusting what it read earlier. Workspace only. Refused with a 409 while a turn is in flight, since a notice written mid-turn would never be seen; omit it to write silently.

Returns

Promise<{ }>

Throws

AuraError for a root-level workspace path, before any request.

zipUrl()

zipUrl(container, path?): Promise<string>;

A URL serving the container as a zip, or path’s subtree when given.

Returns the URL rather than the bytes because that is what the API hands back — always the tokenized /raw leg for zips, since a zip is assembled on demand and cannot be presigned. The token is single-use and is the credential, so fetch it without the API key, and only once.

Parameters

Parameter	Type
`container`	`FileContainer`
`path?`	`string`

Returns

Promise<string>