@simular-ai/sai-sdk 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simular, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,305 @@
-# Temporary Holding Version
+# @simular-ai/sai-sdk (TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript SDK for the [Sai API](https://platform.simular.ai/documentation). Hand desktop work to Sai on
+a computer (a Sai cloud computer, or your own PC with the Sai app) and get the answer back, or drive a
+cloud computer yourself.
+
+Status: **alpha (0.1)**. The surface may still change before 1.0. It matches the
+[Python SDK](../python/README.md) method for method.
+
+| Layer          | What it is                                    | Status           |
+| -------------- | --------------------------------------------- | ---------------- |
+| `sai.sessions` | A conversation with Sai on one computer       | available        |
+| `sai.control`  | Drive a cloud computer directly with Simulang | research preview |
+| `sai.turns`    | A turn's record: typed output, evidence       | available        |
+
+## Install
+
+```bash
+npm install @simular-ai/sai-sdk
+export SAI_API_KEY=sapi_...   # create one at https://platform.simular.ai
+```
+
+Node 18.17 or later (it uses the built-in `fetch`). No runtime dependencies. ESM only.
+
+## Give Sai a task
+
+```ts
+import { Sai } from '@simular-ai/sai-sdk'
+
+const sai = new Sai()
+const [pc] = await sai.machines.list()
+
+const session = await sai.sessions.create({ machine: pc })
+const result = await session.run('Open Notepad, type hello, save it to the desktop as hello.txt')
+
+console.log(result.status) // idle | needs_approval | error
+console.log(result.text) // Sai's answer
+console.log(result.usage) // tokens and cost for this task
+```
+
+`machine` can be left out when the account has one computer. More `session.run(...)` calls continue
+the same conversation; `sai.sessions.create()` starts a new one with no memory of the old.
+
+### Watch it work
+
+```ts
+const turn = await session.send("Find last month's invoices in Downloads and total them")
+for await (const ev of turn.events()) {
+  if (ev.kind === 'step') console.log('  ', ev.text)
+  else if (ev.kind === 'approval') await turn.respond(ev.approval!, 'yes')
+}
+const result = await turn.wait()
+```
+
+`ev.kind` is one of `step`, `message`, `approval`, `tool_error`, `error`, `finished`.
+`turn.events({ raw: true })` adds the wire frames (reasoning, tool calls) as `other`.
+
+### Approvals
+
+`run()` / `wait()` resolve with `status === 'needs_approval'` unless you pass a handler:
+
+```ts
+const result = await session.run('Clean up the temp folder', {
+  onApproval: (a) => {
+    if (a.isLinkOnly) {
+      console.log('Approve in a browser:', a.url)
+      return null // a person answers it; keep waiting
+    }
+    if (a.type === 'choice') return ['yes', a.questions.map((q: any) => [q.options[0].value])]
+    return 'yes'
+  },
+})
+```
+
+For an unattended run with nobody to answer, `autonomous: true` runs the turn without approval
+cards, as if `'task'` (trust for the rest of the task) had been answered up front. The grant ends
+with the turn. Approvals that only a person can complete in a browser (`isLinkOnly`) still stop the
+turn.
+
+```ts
+await session.run("Export last month's invoices to CSV", { autonomous: true })
+```
+
+### Files, models, stopping
+
+```ts
+const report = await sai.files.upload('report.pdf') // or { data: bytes, name: 'report.pdf' }
+await session.run('Summarise the attached report', { attachments: [report] })
+
+const allowed = (await sai.models.list()).filter((m) => m.allowed).map((m) => m.id)
+await session.run('...', { model: 'anthropic/claude-opus-5-5' }) // sticks to the session
+
+const turn = await session.send('...')
+await turn.abort()
+```
+
+## Get typed results
+
+Any message can also return structured data. Pass `outputSchema` and the turn's record comes back in
+`result.record`, with `output` matching the schema:
+
+```ts
+const session = await sai.sessions.create({ machine: pc })
+const result = await session.run(
+  'Open Notepad, type "hello" and save it on the Desktop as hello.txt. Return the saved file\'s path.',
+  {
+    outputSchema: {
+      type: 'object',
+      properties: { path: { type: 'string' } },
+      required: ['path'],
+    },
+  },
+)
+if (result.ok) console.log((result.record?.output as { path: string }).path)
+else console.log(result.record?.reasonCode) // e.g. output_invalid, with result.record.rawAnswer
+```
+
+More options, all optional (the SDK sends them to the API as `options`):
+
+| Option             | What it does                                                                 |
+| ------------------ | ---------------------------------------------------------------------------- |
+| `inputs`           | Fill `{{name}}` placeholders in the message; every placeholder needs a value |
+| `outputSchema`     | JSON Schema (at most 32 KB) the output must match                            |
+| `successCriteria`  | A guideline for a judge, or `{ id, check, returnEvidence? }` yes/no checks   |
+| `idempotencyKey`   | The same key again returns the earlier turn and sends nothing                |
+| `recordTrajectory` | Keep a screenshot and the action for each step                               |
+
+`inputs`, `outputSchema` or `successCriteria` make the message _structured_. A structured message
+behaves like any other (same session, same computer); it only adds the typed result. It is rejected with
+`ConflictError` (`code === 'session_busy'`) while the session is working, because it starts a turn of
+its own. A plain message sent then joins the running turn instead.
+
+```ts
+const result = await session.run(
+  'Save "Invoice {{invoice_number}}: {{amount}} USD" on the Desktop as {{file_name}}. Return its path.',
+  {
+    inputs: { invoice_number: 'INV-1001', amount: '42.50', file_name: 'inv-1001.txt' },
+    outputSchema: {
+      type: 'object',
+      properties: { path: { type: 'string' } },
+      required: ['path'],
+    },
+    successCriteria: [
+      {
+        id: 'saved',
+        check: 'The file is saved and contains the invoice line',
+        returnEvidence: true,
+      },
+    ],
+    idempotencyKey: 'inv-1001', // a retry returns this turn and sends nothing
+    recordTrajectory: true,
+  },
+)
+const record = result.record
+console.log(record?.status) // succeeded | failed
+console.log(record?.evidence) // [{ id: 'saved', passed: true, score: 0.94, evidence: '...' }]
+console.log(record?.usage) // tokens of the agent's model calls in this turn
+```
+
+`result.ok` is true only when the turn succeeded. On `failed`, `record.reasonCode` says why
+(`agent_error`, `output_invalid`, `criteria_not_met`, ...); the output is never a partial object.
+
+**Reading a turn later.** Every message gets a turn id, `turn.id` (plain messages too):
+
+```ts
+const turn = await session.send('...')
+let record = await sai.turns.get(turn) // never waits; `finalizing` while the result is worked out
+record = await sai.turns.wait(turn, { timeoutMs: 600_000 }) // until succeeded, failed or needs_input
+for (const step of await sai.turns.trajectory(turn)) {
+  // needs recordTrajectory: true
+  console.log(step.index, step.title, step.code)
+  if (step.hasScreenshot)
+    await writeFile(`step${step.index}.jpg`, await sai.turns.screenshot(turn, step.index))
+}
+```
+
+Each takes a `Turn`, a `TurnRecord` or the id string. `record.status` is `running`, `needs_input` (an
+approval is pending: answer it on `sai.sessions.resume(record.sessionId)`), `finalizing`, `succeeded` or
+`failed`.
+
+## Drive a computer yourself
+
+Direct control runs [Simulang](https://platform.simular.ai/documentation/concepts/direct-control)
+blocks on a cloud computer. While the lease is open, Sai's own tasks on that computer wait, so always close it.
+
+```ts
+const lease = await sai.control.open({ machine: pc })
+try {
+  console.log((await lease.shell('hostname')).stdout)
+
+  const r = await lease.exec(`
+    var page = await machine.browser.newtab('https://example.com')
+    var snap = await page.snapshot()
+    snap.title
+  `)
+  console.log(r.result) // Example Domain
+  await writeFile(`page.${r.screenshotMimeType!.split('/')[1]}`, r.screenshot!) // jpeg or png
+} finally {
+  await lease.close()
+}
+```
+
+With TypeScript 5.2+ and a runtime that supports explicit resource management, `await using lease = ...`
+closes it for you.
+
+`exec()` resolves with an `ExecResult`; a block that threw still resolves, so check `r.error`
+(`exception`, `timeout`, `interrupted`). Use `var`, not `let`/`const`, for values the next block needs.
+`lease.screenshot()` grabs the whole screen; it needs the computer's screen-capture service, and where that is
+off it throws `BlockError`.
+
+## Learn code from turns (research preview)
+
+`sai.learn` turns what the agent did into Simulang code you own, and repairs that code when it breaks.
+`sai.judge` checks recorded turns against criteria you choose afterwards. The turns must be sent with
+`recordTrajectory: true`.
+
+```ts
+const turn = await session.send('Open {{site}} and read the title of the top story', {
+  inputs: { site: 'https://news.ycombinator.com' },
+  recordTrajectory: true,
+})
+await sai.turns.wait(turn)
+
+const learned = await sai.learn.create([turn]) // about two minutes
+console.log(
+  learned.template,
+  learned.parameters.map((p) => p.name),
+)
+console.log(learned.code) // async function main(params = { site: "..." }) { ... }
+
+await using lease = await sai.control.open({ machine: pc })
+const r = await lease.run(learned, { site: 'https://lobste.rs' }) // inputs over the defaults
+console.log(r.result) // what main returned
+
+// It broke on a new site: repair it from the run (or from feedback, or a new turn that solved it)
+const fixed = await sai.learn.create([], {
+  initialCode: learned.code,
+  evaluations: [{ inputs: { site: 'https://lobste.rs' }, result: r, passed: false }],
+})
+console.log(fixed.changes)
+
+const judgement = await sai.judge.create(
+  [turn],
+  [{ id: 'title', check: 'The agent reported a story title' }],
+)
+console.log(judgement.verdict, judgement.criteria[0]?.score)
+```
+
+`learned.status` is `failed` when the code still has `learned.validation.errors` after one retry.
+Pass a judgement as `{ ..., judgement }` in an evaluation to repair code from its evidence.
+
+## Run Sai for your customers
+
+With an [Organisation](https://platform.simular.ai/documentation/organisations), each customer is a
+Tenant. Your backend manages Tenants with an Organisation Key, and acts as one with a Tenant token.
+
+```ts
+const org = new Sai({ apiKey: 'sapi_...', orgId: 'org_...' }) // an Organisation Key; or SAI_API_KEY, SAI_ORG_ID
+
+const tenant = await org.tenants.create('Riverside Clinic', { externalId: 'clinic-4821' })
+const code = await org.tenants.createEnrollment(tenant) // hand code.token to your installer
+console.log(await org.tenantMachines.list(tenant))
+
+const clinic = await org.tenants.client(tenant) // acts as the Tenant; renews its token
+const session = await clinic.sessions.create()
+await session.run("Open the calendar and read today's appointments")
+```
+
+- `tenants.list({ status, externalId, limit, cursor })` resolves with one page: `page.tenants`,
+  `page.nextCursor`. `externalId` finds your customer's Tenant without storing `tenant.id`.
+- `tenants.update(tenant, { name, metadata, status: 'disabled' | 'active' })`; `tenants.delete(tenant)`
+  disables it and revokes every machine.
+- `tenants.token(tenant)` is the raw exchange: a one-hour `TenantToken` to pass as
+  `new Sai({ apiKey: token.token })`.
+- `tenantMachines.get(tenant, machineId)`, `tenantMachines.revoke(tenant, machine)`.
+
+## Errors
+
+Every non-2xx response throws a `SaiError` subclass with `status`, `code`, `message` and `retryAfter`:
+`AuthenticationError` (401), `BadRequestError` (400), `PermissionDeniedError` (403), `NotFoundError`
+(404), `ConflictError` (409), `LinkOnlyApprovalError` (`approvalUrl`), `GoneError` (410),
+`SpendCapReachedError` (403, the key reached its monthly limit; `resetsAt`), `RateLimitError` (429),
+`ServiceUnavailableError` (503), `ConnectionError`, `BlockError`.
+
+A task that ran out of credit ends with `result.status === 'error'` and `result.errorCode` set to
+`insufficient_credits` or `free_computer_time_exhausted`: stop retrying for today.
+
+## Configuration
+
+| Option      | Env           | Default                  |
+| ----------- | ------------- | ------------------------ |
+| `apiKey`    | `SAI_API_KEY` | required                 |
+| `baseUrl`   | `SAI_API_URL` | `https://api.simular.ai` |
+| `timeoutMs` |               | 60 000 per request       |
+| `fetch`     |               | global `fetch`           |
+| `orgId`     | `SAI_ORG_ID`  | for `tenants.token()`    |
+
+## Development
+
+```bash
+cd typescript
+npm install
+npm test
+npm run typecheck
+```

package/dist/client.d.ts

@@ -0,0 +1,78 @@
+import { Control } from './control.js';
+import { Http, type Credential, type FetchLike } from './http.js';
+import { Machines } from './machines.js';
+import { Sessions } from './sessions.js';
+import { TenantMachines, Tenants } from './tenants.js';
+import { Turns } from './turns.js';
+import { Judge, Learn } from './learn.js';
+import { type Account, type Attachment, type Model } from './types.js';
+export interface SaiOptions {
+    /** Defaults to `process.env.SAI_API_KEY`. */
+    apiKey?: string;
+    /** Defaults to `process.env.SAI_API_URL`, then `https://api.simular.ai`. */
+    baseUrl?: string;
+    /** Per request. Default 60 000. */
+    timeoutMs?: number;
+    versionTag?: string;
+    /** Replace `fetch`, e.g. in tests. */
+    fetch?: FetchLike;
+    /**
+     * The Organisation that `tenants.token()` and `tenants.client()` exchange for. Defaults to
+     * `process.env.SAI_ORG_ID`. Only an Organisation Key needs it.
+     */
+    orgId?: string;
+}
+/**
+ * The Sai API client.
+ *
+ * ```ts
+ * const sai = new Sai() // SAI_API_KEY, and SAI_API_URL if set
+ * const session = await sai.sessions.create()
+ * console.log((await session.run('Open Notepad and type hello')).text)
+ * ```
+ */
+export declare class Sai {
+    readonly machines: Machines;
+    readonly sessions: Sessions;
+    readonly turns: Turns;
+    /** Recorded turns → Simulang code, and code repair (research preview). */
+    readonly learn: Learn;
+    /** Judge recorded turns against new criteria (research preview). */
+    readonly judge: Judge;
+    readonly control: Control;
+    readonly models: Models;
+    readonly files: Files;
+    readonly account: AccountResource;
+    /** Your customers under an Organisation. Takes an Organisation Key. */
+    readonly tenants: Tenants;
+    /** A Tenant's enrolled computers. Takes an Organisation Key. */
+    readonly tenantMachines: TenantMachines;
+    /** @param credential internal: `tenants.client()` passes a token source instead of `apiKey`. */
+    constructor(opts?: SaiOptions, credential?: Credential);
+}
+export declare class Models {
+    private readonly http;
+    constructor(http: Http);
+    /** Models a session can run on; `allowed` says whether this plan may use each. */
+    list(): Promise<Model[]>;
+}
+export declare class Files {
+    private readonly http;
+    constructor(http: Http);
+    /**
+     * Upload one file (max 25 MB) to attach to a message. Pass a path (Node), or
+     * the bytes with a name.
+     */
+    upload(file: string | {
+        data: Uint8Array | Blob;
+        name: string;
+    }, opts?: {
+        name?: string;
+    }): Promise<Attachment>;
+}
+export declare class AccountResource {
+    private readonly http;
+    constructor(http: Http);
+    /** Plan and spendable credit. Slow-ish (billing lookup): not for a poll loop. */
+    get(): Promise<Account>;
+}

package/dist/client.js

@@ -0,0 +1,110 @@
+import { Control } from './control.js';
+import { DEFAULT_BASE_URL, Http } from './http.js';
+import { Machines } from './machines.js';
+import { Sessions } from './sessions.js';
+import { TenantMachines, Tenants } from './tenants.js';
+import { Turns } from './turns.js';
+import { Judge, Learn } from './learn.js';
+import { parseAccount, parseAttachment, parseModel, } from './types.js';
+/**
+ * The Sai API client.
+ *
+ * ```ts
+ * const sai = new Sai() // SAI_API_KEY, and SAI_API_URL if set
+ * const session = await sai.sessions.create()
+ * console.log((await session.run('Open Notepad and type hello')).text)
+ * ```
+ */
+export class Sai {
+    machines;
+    sessions;
+    turns;
+    /** Recorded turns → Simulang code, and code repair (research preview). */
+    learn;
+    /** Judge recorded turns against new criteria (research preview). */
+    judge;
+    control;
+    models;
+    files;
+    account;
+    /** Your customers under an Organisation. Takes an Organisation Key. */
+    tenants;
+    /** A Tenant's enrolled computers. Takes an Organisation Key. */
+    tenantMachines;
+    /** @param credential internal: `tenants.client()` passes a token source instead of `apiKey`. */
+    constructor(opts = {}, credential) {
+        const env = typeof process !== 'undefined' ? process.env : {};
+        const key = credential ?? opts.apiKey ?? env.SAI_API_KEY;
+        if (!key) {
+            throw new Error('No API key: pass apiKey or set SAI_API_KEY. Create one at https://platform.simular.ai.');
+        }
+        const http = new Http(key, opts.baseUrl ?? env.SAI_API_URL ?? DEFAULT_BASE_URL, opts.timeoutMs ?? 60_000, opts.versionTag, opts.fetch ?? ((input, init) => fetch(input, init)));
+        this.machines = new Machines(http);
+        this.sessions = new Sessions(http, this.machines);
+        this.turns = new Turns(http);
+        this.learn = new Learn(http);
+        this.judge = new Judge(http);
+        this.control = new Control(http);
+        this.models = new Models(http);
+        this.files = new Files(http);
+        this.account = new AccountResource(http);
+        this.tenants = new Tenants(http, opts.orgId ?? env.SAI_ORG_ID, (c) => new Sai(opts, c));
+        this.tenantMachines = new TenantMachines(http);
+    }
+}
+export class Models {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Models a session can run on; `allowed` says whether this plan may use each. */
+    async list() {
+        const d = await this.http.json('GET', '/v1/agents/models');
+        return (d.models ?? []).map(parseModel);
+    }
+}
+export class Files {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Upload one file (max 25 MB) to attach to a message. Pass a path (Node), or
+     * the bytes with a name.
+     */
+    async upload(file, opts = {}) {
+        let data;
+        let name;
+        if (typeof file === 'string') {
+            const { readFile } = await import('node:fs/promises');
+            const { basename } = await import('node:path');
+            data = new Uint8Array(await readFile(file));
+            name = opts.name ?? basename(file);
+        }
+        else {
+            data = file.data;
+            name = opts.name ?? file.name;
+        }
+        const d = await this.http.json('POST', '/v1/agents/upload', {
+            body: data instanceof Blob ? data : new Blob([data]),
+            // The server reads only a body that has a Content-Type; it derives the MIME type from the name.
+            headers: {
+                'Content-Type': 'application/octet-stream',
+                'x-filename': encodeURIComponent(name),
+            },
+            timeoutMs: 120_000,
+        });
+        return parseAttachment(d);
+    }
+}
+export class AccountResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Plan and spendable credit. Slow-ish (billing lookup): not for a poll loop. */
+    async get() {
+        return parseAccount(await this.http.json('GET', '/v1/agents/account'));
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/control.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Direct control: drive a cloud computer with Simulang. No agent.
+ *
+ * Maps to `/v1/machines/{id}/control`, a lease on the machine: at most one per
+ * machine, so the machine id is the handle. Research preview, open to every
+ * account; model calls the code makes (`callLLM`, `ground`, `stateSatisfies`)
+ * are billed as usual.
+ */
+import type { Http } from './http.js';
+import { type MachineRef } from './machines.js';
+import { type ExecResult, type LearnResult } from './types.js';
+export declare class Control {
+    private readonly http;
+    constructor(http: Http);
+    /**
+     * Take a cloud computer. Resolves once the lease holds it, up to ~3
+     * minutes when a Sai task holds it or it has to start; at once if the lease
+     * is already open. Close it when done (`await using`, or `try/finally`):
+     * Sai's tasks on that computer wait until then.
+     */
+    open(opts: {
+        machine: MachineRef;
+    }): Promise<ControlLease>;
+}
+export declare class ControlLease {
+    private readonly http;
+    readonly machineId: string;
+    readonly idleTimeoutSec: number;
+    private closed;
+    private readonly path;
+    constructor(http: Http, machineId: string, idleTimeoutSec: number);
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Run one Simulang (JavaScript) block. Use `var` for anything the next block
+     * needs. A block that throws, times out or is interrupted still resolves:
+     * check `result.error`. Throws `GoneError` once the lease has ended (closed,
+     * idle, taken by a Sai task, or the computer stopped answering): open again.
+     */
+    exec(code: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<ExecResult>;
+    /**
+     * Run code from `sai.learn.create()`: its `main` with `inputs` over the parameters' defaults
+     * (an argument to `main` replaces its whole default object, so missing inputs keep their
+     * defaults). `main`'s return value is `result.result`. A string runs as code with `inputs` as is.
+     */
+    run(learned: LearnResult | string, inputs?: Record<string, string | number | boolean>, opts?: {
+        timeoutMs?: number;
+    }): Promise<ExecResult>;
+    /** Run a shell command: `{ stdout, stderr, exitCode, timedOut }`. */
+    shell(command: string, opts?: {
+        cwd?: string;
+        timeoutMs?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+        timedOut: boolean;
+    }>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, text: string): Promise<void>;
+    /**
+     * The whole screen as image bytes (usually JPEG; use `exec` for the MIME type). Needs the
+     * computer's screen-capture service; throws `BlockError` where it is off (a page or app
+     * snapshot still carries an image).
+     */
+    screenshot(): Promise<Uint8Array>;
+    /** Stop the running block at its next step. False if nothing was running. */
+    interrupt(): Promise<boolean>;
+    /** `{ status: open|closed, closedReason?, lastExecAt, ... }`. */
+    get(): Promise<Record<string, unknown>>;
+    /** Clear the REPL and release the computer. Safe to call twice. */
+    close(): Promise<void>;
+}