JavaScript SDK reference

This reference describes @erstan/sdk@0.1.0-beta.1, a JavaScript ESM package with TypeScript declarations for Node.js 22+. See the quickstart for current private-beta availability and installation.

Client configuration

import { ErstanClient } from '@erstan/sdk';

const client = new ErstanClient({
  apiKey: process.env.ERSTAN_API_KEY,
  apiBase: 'https://api.erstan.com',
  timeoutMs: 60_000,
  maxRetries: 2,
  retryDelayMs: 500,
  maxRetryDelayMs: 30_000,
});

Option	Behavior
`apiKey`	Key string or synchronous/async credential provider. Defaults to `ERSTAN_API_KEY`. Keep it in trusted local/server code.
`apiBase`	API origin only. Defaults to `ERSTAN_API_BASE`, then production. HTTPS is required except for loopback development. Set it explicitly for QA.
`timeoutMs`	Total deadline per API operation, including credentials, response body, and retries; default 60,000 ms.
`maxRetries`	Retries for eligible operations, not all writes; default 2.
`retryDelayMs`	Initial retry delay; default 500 ms.
`maxRetryDelayMs`	Maximum retry delay; default 30,000 ms. A longer `Retry-After` returns the error instead of retrying too early.
`fetch`	Optional Fetch-compatible implementation, useful for application adapters and offline tests.

Every method accepts request options as its last argument: signal, timeoutMs, and maxRetries. Waiting methods also accept waitTimeoutMs (default 300,000 ms) and pollIntervalMs (default 1,000 ms). The wait deadline starts after launch or continuation acceptance, or on entry to wait; it does not include submission. traceEvents additionally accepts maxPages (default 1,000). Convenience run/wait operations pin one credential for the sequence. Separate calls use the provider’s current key. Erstan restricts run access to the exact key that created the run, so replacing a key is not a recovery path for old runs.

Published Agents and runs

All methods below are on client. Optional request options are omitted from the table unless needed to distinguish a signature.

Method	Returns / purpose
`agents.listPublished(options?)`	`{ agents }`, the currently runnable published inventory; not paginated.
`agents.getPublished(agentId, options?)`	Published Agent details, lanes, input schemas, and attachment policy.
`agents.run(agentId, body, options?)`	Run handle with `runId`, `agentId`, `laneId`, and `status`.
`agents.runAndWait(agentId, body, options?)`	Starts a run, then returns a `RunWaitResult`.
`runs.get(runId, options?)`	Current run status, output, and any pending interaction.
`runs.wait(runId, options?)`	Observes an existing run until a terminal result, actionable interaction, or other pause.
`runs.continue(runId, body, options?)`	Sends a follow-up to a terminal run; returns the continuation’s run handle.
`runs.continueAndWait(runId, body, options?)`	Continues and follows the returned run ID, including forks.
`runs.reply(runId, body, options?)`	Answers the exact current user-input interaction.
`runs.decideApproval(runId, body, options?)`	Submits an explicit approve/reject decision for the current approval interaction.
`runs.cancel(runId, options?)`	Requests remote cancellation, which may initially report `cancelling`.
`runs.trace(runId, query?, options?)`	One bounded page of persisted trace events.
`runs.traceEvents(runId, query?, options?)`	Async iterator over persisted trace events with bounded paging.

Run bodies contain input, optional laneId, attachments, and idempotencyKey. Select the Agent and lane intentionally; do not pick the first available Agent automatically. Attachments use { name, type, base64 } or { name, type, storageKey }, subject to the lane policy and 25 MB request limit. The SDK does not read local file paths or upload files implicitly. Runtime control fields such as Skill selections do not belong in business input. Continuation bodies include message and may include an idempotencyKey. Always follow the returned run ID. See Run Agents for continuation and lane constraints.

Waiting and human interactions

RunWaitResult.reason is completed, failed, cancelled, interaction, waiting, or unknown_status. The result includes run; finalResponse is typed as unknown. Failed Agent execution is a result, not an HTTP exception. Only an actionable pending interaction can be answered. reply uses the current interactionId plus message or structured answers; decideApproval uses { interactionId, action: 'approve' | 'reject' }. Retained/resuming interrupts and asynchronous batches keep polling. Other pauses and unknown future statuses return control. Nothing auto-approves or answers for the user. Aborting a request or timing out observation does not cancel remote work. Persist accepted run IDs and resume with runs.wait. Cancellation is a separate intentional call and cannot undo external effects that already occurred.

Durable trace paging

Trace queries accept cursor, limit, eventTypes, includePayloads, and payloadMaxChars. Payloads are opt-in and remain potentially sensitive even after server redaction. Sequence values stay strings.

// client is an ErstanClient; runId identifies a run started with the same key.
for await (const event of client.runs.traceEvents(runId, {
  eventTypes: ['node_completed'],
  includePayloads: false,
}, { maxPages: 100 })) {
  console.log(event.sequence, event.eventType);
}

This is durable event retrieval, not a live token stream or an indefinite tail. The iterator stops at the last available page, preserves filters, and rejects repeated cursors. Reaching its page limit raises a protocol error; use trace with an explicit cursor for manual paging. Breaking iteration does not cancel the run.

Agent and Skill authoring

context.get() returns workspaceId, actor, scopes, available teams, and capabilities. Check the expected workspace before making changes. The beta SDK requires stagedAuthoring: true and authoringContract: '2026-09-09.1' for authoring. Preview additionally requires guardedPreviews; explicit Skill selections also require draftSkillOverrides. An older or disabled server raises ErstanCapabilityError before the authoring call. Published runtime methods do not depend on staged-authoring support.

Method	Returns / purpose
`context.get(options?)`	Workspace identity, access context, and capabilities.
`agents.list(query?, options?)` / `skills.list(query?, options?)`	Readable authoring inventory, including drafts, with `agents` or `skills`, `limit`, and opaque `nextCursor`.
`agents.get(id, options?)` / `skills.get(id, options?)`	Current authoring response with `agent` or `skill`, revision, current/published versions, and permissions.
`agents.create(body, writeOptions)` / `skills.create(body, writeOptions)`	Saves a new draft.
`agents.update(id, body, guardedOptions)` / `skills.update(id, body, guardedOptions)`	Saves changes as a draft without promoting published content.
`agents.validate(body, options?)` / `skills.validate(body, options?)`	Validation result with `valid` and diagnostics; no save, execution, or publication.
`agents.publish(id, guardedOptions)` / `skills.publish(id, guardedOptions)`	Validates and publishes the exact approved current content.
`agents.listVersions(id, query?, options?)` / `skills.listVersions(id, query?, options?)`	Paginated version summaries.
`agents.getVersion(id, version, options?)`	Historical Agent authoring response; its history revision cannot authorize current writes.
`skills.getVersion(id, version, options?)`	Historical Skill version object and complete package, not a current write guard.
`agents.preview(id, body, guardedOptions)`	Starts a real hosted preview of the exact guarded remote draft; returns a run handle.
`catalog.nodes(query?, options?)`	Live node definitions and field detail.
`catalog.tools(query?, options?)` / `catalog.skills(query?, options?)`	Live pinnable tool/Skill catalogs, not the complete draft authoring inventory.
`catalog.guide(options?)`	Current authoring rules.

agents.list/get are authoring reads, not aliases for listPublished/getPublished. Authoring list queries accept cursor, limit, and query. Pass nextCursor unchanged for the next page; do not invent offset pagination. Catalog queries and node fields follow the included TypeScript declarations and live guide. Catalog discovery is currently unavailable to team-restricted keys; do not broaden a key automatically to work around that restriction. Agent creation requires a target teamId, name, and complete nodes and edges. Updates replace supplied node/edge arrays in full; preserve unrelated content and unknown graph fields. Agent validation accepts proposed content or an agentId. Skill creation and updates use a complete packageJson; create also requires name. Skill validation accepts { packageJson, ... }. Preserve every related file, action declaration, and extension field. Full offline JSON/ZIP codecs are in the separate @erstan/skill-package package.

Permissions and lifecycle

SDK operation	Required API-key scopes
Authoring reads/history/catalogs	`agents:read`
Authoring inventory lists	`agents:read` + `agents:list`
Creation, updates, validation, publication	`agents:read` + `agents:write`
Draft preview	`agents:read` + `agents:write` + `agents:run`
Observe preview runs and traces	`runs:read`, using the creating key

These are additive to current workspace/team permissions and server capabilities. A key that can validate through REST also has authoring write authority; it is not a validation-only credential for untrusted PR code. Saving stages Skill content while the previous published package remains live. Agent name, description, category, tags, difficulty, and estimated time stage with the graph and promote together; behavior type stays immutable after first publication. Validation, preview, and publication are independent operations. Publishing does not require a successful test receipt or a particular workflow. Publish required Skills explicitly before the Agent. Agent publication never publishes dependencies for you. Publishing a shared Skill affects future consumers, while snapshot-backed admitted runs and their continuations retain their selected packages. Legacy runs without snapshot evidence cannot be assumed to have that guarantee. Multiple resource writes are not an atomic deployment.

Guards, idempotency, and preview

writeOptions requires { idempotencyKey }. guardedOptions requires both { revision, idempotencyKey }; the SDK sends the revision as If-Match. Keep content and its returned revision together. Historical version reads are read-only. After a 412 conflict, re-read and reconcile rather than replacing the guard on stale local edits.

// Use the baseline paired with the content you reviewed; this saves a draft only.
const { agent } = await client.agents.get(agentId);
const saved = await client.agents.update(agentId, {
  description: 'Revised description for review.',
}, { revision: agent.revision, idempotencyKey: updateKey });
// Persist saved.agent content and saved.agent.revision together for the next step.

Preview bodies contain input, optional laneId, and optional top-level skillVersions: [{ skillId, version }]. Each selected Skill requires edit permission and must fit the Agent’s existing Skill policy. Unselected Skills and child Agents retain published content. Preview never runs unsaved local files, auto-publishes dependencies, or bypasses approvals. It seals the selected graph; later edits or publication can fork and advance the version. Preview can incur costs and external effects, so invoke it only deliberately. For identical authoring intent, same-key response recovery is available for 24 hours; retained tombstones prevent duplicate dispatch afterward. This is at-most-once dispatch, not multi-resource atomicity. A lost response, authoring_outcome_unknown, or expired receipt requires reconciliation before any new mutation. Never blindly generate a fresh key to repeat an uncertain write, or reuse a key with changed content or guards.

Errors and retry behavior

ErstanError is the base error. ErstanAPIError exposes status, code, details, requestId, eventId, and retryAfterMs when available. Subclasses distinguish authentication, permission, not-found, validation, conflict, capability, and rate-limit errors. Configuration, connection, timeout, abort, and protocol errors also have distinct classes. ErstanWaitTimeoutError includes runId and the last observed run when available; other observation errors may also carry them. See API errors for server codes. Safe reads retry transient network errors and HTTP 408/429/500/502/503/504. Run starts and continuations retry only with a non-empty body idempotencyKey. Cancellation is idempotent. Replies and approval decisions never retry automatically; inspect the current interaction after uncertainty. Authoring mutations use their explicit keys and guarded receipt contract. Authorization, validation, and conflict errors are not resolved by automatic retry.

Advanced MCP access

import { ErstanMcpClient } from '@erstan/sdk/mcp';

const mcp = new ErstanMcpClient({ apiBase: 'https://api.erstan.com' });
const { tools } = await mcp.listTools();
const result = await mcp.callTool('get_agent_builder_guide');
if (result.isError) {
  throw new Error('Inspect the MCP tool error before continuing.');
}

listTools(query?, options?), callTool(name, args?, options?), and request(method, params?, options?) target Erstan’s stateless JSON-response /v1/mcp endpoint using the same API-key configuration. This is not a generic MCP transport or OAuth client: SSE, sessions, and notifications are unsupported. Tool calls are not automatically retried, and isError remains part of the result. JSON-RPC failures raise ErstanMcpError from the MCP subpath. Use the live tool schema: MCP Skill updates/publication use expectedVersion, not REST revision headers, and MCP Skill mutations have no idempotency argument. REST/SDK history and cancellation methods do not imply equivalent MCP tools. For host-managed OAuth, use the plugin.

Developer API

JavaScript SDK (beta)

Partners

API Reference

JavaScript SDK reference

Client configuration

Published Agents and runs

Waiting and human interactions

Durable trace paging

Agent and Skill authoring

Permissions and lifecycle

Guards, idempotency, and preview

Errors and retry behavior

Advanced MCP access

​Client configuration

​Published Agents and runs

​Waiting and human interactions

​Durable trace paging

​Agent and Skill authoring

​Permissions and lifecycle

​Guards, idempotency, and preview

​Errors and retry behavior

​Advanced MCP access

Client configuration

Published Agents and runs

Waiting and human interactions

Durable trace paging

Agent and Skill authoring

Permissions and lifecycle

Guards, idempotency, and preview

Errors and retry behavior

Advanced MCP access