EtherDocs
Integrate/SDK

TypeScript SDK ​

@ether-os/os-sdk is the supported TypeScript client for harness integration. It wraps REST and provides a WebSocket helper for task subscription.

npm: @ether-os/os-sdk
Source: ether-core/packages/ether-os-sdk
Reference consumer: Ether Code

Install ​

bash
npm install @ether-os/os-sdk

Monorepo dev (link from ether-core):

json
{
  "dependencies": {
    "@ether-os/os-sdk": "file:../ether-core/packages/ether-os-sdk"
  }
}

Client setup ​

typescript
import { EtherOsClient } from "@ether-os/os-sdk";

const client = new EtherOsClient({
  baseUrl: "https://api.tryether.ai",
  token: process.env.ETHER_TOKEN!,
  appId: "my-harness",
});

Core methods ​

MethodAPI
claimExecution(taskId)POST …/claim
heartbeat(taskId, runId)POST …/heartbeat
reportStep(taskId, step)POST …/steps
interrupt(taskId, runId, question, options?)POST …/interrupt
submitResult(taskId, result)POST …/result
fetchContext(taskId, slices?)GET …/context
fetchContextDocument(taskId, docId)GET …/context/doc/…
subscribeTask(taskId, onMessage)WebSocket helper

End-to-end helper ​

Ether Code wraps the SDK in @ether-code/harness-core:

typescript
import { claimAndRun } from "@ether-code/harness-core";

await claimAndRun(client, taskId);

You can pass a custom execute function for your model loop while keeping claim/submit on the SDK.

Types ​

Exported types include:

  • ExecutionBundle — prompt, scope, context handles, callbacks
  • ClaimExecutionResponse
  • ExecutionResult
  • ContextDocument
  • HarnessStep

These mirror ether-harness-contract Rust types and OpenAPI schemas.

Rust integrators ​

Use the ether-harness-contract crate for types, or generate clients from harness-v1.yaml. Do not depend on private ether-api internals.