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

package/dist/control.js

@@ -0,0 +1,137 @@
+/**
+ * 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 { BlockError, GoneError } from './errors.js';
+import { idOf } from './machines.js';
+import { parseExecResult } from './types.js';
+function controlPath(machineId) {
+    return `/v1/machines/${encodeURIComponent(machineId)}/control`;
+}
+export class Control {
+    http;
+    constructor(http) {
+        this.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.
+     */
+    async open(opts) {
+        const machineId = idOf(opts.machine);
+        const d = await this.http.json('POST', controlPath(machineId), {
+            timeoutMs: 240_000,
+        });
+        return new ControlLease(this.http, machineId, Number(d.expiresAfterIdleSec ?? 0));
+    }
+}
+export class ControlLease {
+    http;
+    machineId;
+    idleTimeoutSec;
+    closed = false;
+    path;
+    constructor(http, machineId, idleTimeoutSec) {
+        this.http = http;
+        this.machineId = machineId;
+        this.idleTimeoutSec = idleTimeoutSec;
+        this.path = controlPath(machineId);
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    /**
+     * 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.
+     */
+    async exec(code, opts = {}) {
+        const body = { code };
+        if (opts.timeoutMs !== undefined)
+            body.timeoutMs = opts.timeoutMs;
+        const d = await this.http.json('POST', `${this.path}/exec`, {
+            json: body,
+            timeoutMs: (opts.timeoutMs ?? 120_000) + 45_000,
+        });
+        return parseExecResult(d);
+    }
+    /**
+     * 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.
+     */
+    async run(learned, inputs = {}, opts = {}) {
+        const code = typeof learned === 'string' ? learned : learned.code;
+        const defaults = typeof learned === 'string'
+            ? {}
+            : Object.fromEntries(learned.parameters.map((p) => [p.name, p.defaultValue]));
+        return this.exec(`${code}\nawait main(${JSON.stringify({ ...defaults, ...inputs })})`, opts);
+    }
+    /** Run a shell command: `{ stdout, stderr, exitCode, timedOut }`. */
+    async shell(command, opts = {}) {
+        const args = { command };
+        if (opts.cwd)
+            args.cwd = opts.cwd;
+        const r = await this.exec(`await machine.exec(${JSON.stringify(args)})`, {
+            timeoutMs: opts.timeoutMs,
+        });
+        raiseOnBlockError(r);
+        return r.result;
+    }
+    async readFile(path) {
+        const r = await this.exec(`await machine.readFile(${JSON.stringify({ path })})`);
+        raiseOnBlockError(r);
+        return r.result;
+    }
+    async writeFile(path, text) {
+        const r = await this.exec(`await machine.writeToFile(${JSON.stringify({ path, text, overwrite: true })})`);
+        raiseOnBlockError(r);
+    }
+    /**
+     * 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).
+     */
+    async screenshot() {
+        const r = await this.exec('var __sai_page = await machine.pageContent(); null');
+        raiseOnBlockError(r);
+        if (!r.screenshot) {
+            throw new BlockError('exception', r.screenshotOmitted ? 'screenshot too large to return' : 'no screenshot');
+        }
+        return r.screenshot;
+    }
+    /** Stop the running block at its next step. False if nothing was running. */
+    async interrupt() {
+        const d = await this.http.json('POST', `${this.path}/interrupt`);
+        return Boolean(d?.interrupted);
+    }
+    /** `{ status: open|closed, closedReason?, lastExecAt, ... }`. */
+    get() {
+        return this.http.json('GET', this.path);
+    }
+    /** Clear the REPL and release the computer. Safe to call twice. */
+    async close() {
+        if (this.closed)
+            return;
+        try {
+            await this.http.request('DELETE', this.path);
+        }
+        catch (err) {
+            if (!(err instanceof GoneError))
+                throw err;
+        }
+        this.closed = true;
+    }
+}
+function raiseOnBlockError(r) {
+    if (r.error)
+        throw new BlockError(r.error.kind, r.error.message);
+}
+//# sourceMappingURL=control.js.map

package/dist/control.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A non-2xx response from the Sai API. `code` is the machine-readable `error`
+ * string when the server sent one (`machine_busy`, `link_only`, ...); `message`
+ * is the human text; `body` is the parsed JSON body, unchanged.
+ */
+export declare class SaiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly body: Record<string, unknown>;
+    readonly retryAfter: number | undefined;
+    constructor(message: string, opts?: {
+        status?: number;
+        code?: string;
+        body?: Record<string, unknown>;
+        retryAfter?: number;
+        cause?: unknown;
+    });
+}
+/** The API could not be reached (DNS, TLS, timeout). */
+export declare class ConnectionError extends SaiError {
+}
+/** 400: the request was invalid, e.g. several computers and no `machine`. */
+export declare class BadRequestError extends SaiError {
+}
+/** 401: no key, or the key is unknown or revoked. */
+export declare class AuthenticationError extends SaiError {
+}
+/** 403: the key is valid but the account may not do this (plan, ownership). */
+export declare class PermissionDeniedError extends SaiError {
+}
+/** 404. */
+export declare class NotFoundError extends SaiError {
+}
+/** 409: e.g. `machine_busy`, `link_only`, approval no longer pending. */
+export declare class ConflictError extends SaiError {
+}
+/**
+ * 410 `control_closed`: the control lease has ended (closed, sat idle, lost
+ * the computer to a Sai task, or the computer stopped answering). `body.reason`
+ * says which. Open a new one.
+ */
+export declare class GoneError extends SaiError {
+}
+/** 429: a rate limit, or a free-plan budget that resets daily. */
+export declare class RateLimitError extends SaiError {
+}
+/** 503: the computer did not come online, or no capacity. Honor `retryAfter`. */
+export declare class ServiceUnavailableError extends SaiError {
+}
+/**
+ * A control helper's Simulang block failed on the computer. `kind` is
+ * `exception`, `timeout` or `interrupted`.
+ */
+export declare class BlockError extends SaiError {
+    readonly kind: string;
+    constructor(kind: string, message: string);
+}
+/** The approval must be answered by a human in a browser: open `approvalUrl`. */
+export declare class LinkOnlyApprovalError extends ConflictError {
+    get approvalUrl(): string | undefined;
+}
+/**
+ * 403 `spend_cap_reached`: the key reached its monthly spend limit, or (on a
+ * cloud machine create, `body.scope === 'tenant'`) the Tenant reached its budget. Not
+ * retryable: the limit resets at `resetsAt` (ISO 8601, 00:00 UTC on the 1st),
+ * or raise it for the key in the portal.
+ */
+export declare class SpendCapReachedError extends PermissionDeniedError {
+    get resetsAt(): string | undefined;
+}
+export declare function errorFor(status: number, body: Record<string, unknown>, retryAfter: number | undefined): SaiError;

package/dist/errors.js

@@ -0,0 +1,114 @@
+/**
+ * A non-2xx response from the Sai API. `code` is the machine-readable `error`
+ * string when the server sent one (`machine_busy`, `link_only`, ...); `message`
+ * is the human text; `body` is the parsed JSON body, unchanged.
+ */
+export class SaiError extends Error {
+    status;
+    code;
+    body;
+    retryAfter;
+    constructor(message, opts = {}) {
+        super(message, opts.cause === undefined ? undefined : { cause: opts.cause });
+        this.name = new.target.name;
+        this.status = opts.status ?? 0;
+        this.code = opts.code;
+        this.body = opts.body ?? {};
+        this.retryAfter = opts.retryAfter;
+    }
+}
+/** The API could not be reached (DNS, TLS, timeout). */
+export class ConnectionError extends SaiError {
+}
+/** 400: the request was invalid, e.g. several computers and no `machine`. */
+export class BadRequestError extends SaiError {
+}
+/** 401: no key, or the key is unknown or revoked. */
+export class AuthenticationError extends SaiError {
+}
+/** 403: the key is valid but the account may not do this (plan, ownership). */
+export class PermissionDeniedError extends SaiError {
+}
+/** 404. */
+export class NotFoundError extends SaiError {
+}
+/** 409: e.g. `machine_busy`, `link_only`, approval no longer pending. */
+export class ConflictError extends SaiError {
+}
+/**
+ * 410 `control_closed`: the control lease has ended (closed, sat idle, lost
+ * the computer to a Sai task, or the computer stopped answering). `body.reason`
+ * says which. Open a new one.
+ */
+export class GoneError extends SaiError {
+}
+/** 429: a rate limit, or a free-plan budget that resets daily. */
+export class RateLimitError extends SaiError {
+}
+/** 503: the computer did not come online, or no capacity. Honor `retryAfter`. */
+export class ServiceUnavailableError extends SaiError {
+}
+/**
+ * A control helper's Simulang block failed on the computer. `kind` is
+ * `exception`, `timeout` or `interrupted`.
+ */
+export class BlockError extends SaiError {
+    kind;
+    constructor(kind, message) {
+        super(`${kind}: ${message}`, { code: kind });
+        this.kind = kind;
+    }
+}
+/** The approval must be answered by a human in a browser: open `approvalUrl`. */
+export class LinkOnlyApprovalError extends ConflictError {
+    get approvalUrl() {
+        const url = this.body.approvalUrl;
+        return typeof url === 'string' ? url : undefined;
+    }
+}
+/**
+ * 403 `spend_cap_reached`: the key reached its monthly spend limit, or (on a
+ * cloud machine create, `body.scope === 'tenant'`) the Tenant reached its budget. Not
+ * retryable: the limit resets at `resetsAt` (ISO 8601, 00:00 UTC on the 1st),
+ * or raise it for the key in the portal.
+ */
+export class SpendCapReachedError extends PermissionDeniedError {
+    get resetsAt() {
+        const at = this.body.resetsAt;
+        return typeof at === 'string' ? at : undefined;
+    }
+}
+const BY_CODE = {
+    link_only: LinkOnlyApprovalError,
+    spend_cap_reached: SpendCapReachedError,
+};
+const BY_STATUS = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    410: GoneError,
+    429: RateLimitError,
+    503: ServiceUnavailableError,
+};
+export function errorFor(status, body, retryAfter) {
+    const err = body.error;
+    const detail = body.message;
+    // Two body shapes: `{ error: "<human text>" }` (/v1/agents) and
+    // `{ error: "<code>", message: "<human text>" }` (/v1/machines/{id}/control, newer errors).
+    const code = typeof err === 'string' && (detail !== undefined || looksLikeCode(err)) ? err : undefined;
+    let message = typeof detail === 'string' ? detail : typeof err === 'string' ? err : `HTTP ${status}`;
+    if (status === 401)
+        message += ' (SAI_API_KEY was rejected: it may be revoked.)';
+    const Cls = (code !== undefined && Object.hasOwn(BY_CODE, code) ? BY_CODE[code] : undefined) ??
+        BY_STATUS[status] ??
+        SaiError;
+    // The `Retry-After` header wins; `retryAfterSeconds` is the same value in the body (`rate_limited`).
+    const wait = retryAfter ?? (typeof body.retryAfterSeconds === 'number' ? body.retryAfterSeconds : undefined);
+    return new Cls(message, { status, code, body, retryAfter: wait });
+}
+function looksLikeCode(s) {
+    return s.length > 0 && !s.includes(' ') && s === s.toLowerCase();
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/http.d.ts

@@ -0,0 +1,22 @@
+export declare const DEFAULT_BASE_URL = "https://api.simular.ai";
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** The bearer token, or a function that returns it before each request. */
+export type Credential = string | (() => Promise<string>);
+export interface RequestOptions {
+    json?: unknown;
+    params?: Record<string, string | number | undefined>;
+    body?: BodyInit;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+/** The one place requests are made: auth header, error mapping, timeouts. */
+export declare class Http {
+    private readonly credential;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    private readonly headers;
+    constructor(credential: Credential, baseUrl: string, timeoutMs: number, versionTag: string | undefined, fetchImpl: FetchLike);
+    request(method: string, path: string, opts?: RequestOptions): Promise<Response>;
+    json<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+}

package/dist/http.js

@@ -0,0 +1,83 @@
+import { ConnectionError, errorFor } from './errors.js';
+import { VERSION } from './version.js';
+export const DEFAULT_BASE_URL = 'https://api.simular.ai';
+/** The one place requests are made: auth header, error mapping, timeouts. */
+export class Http {
+    credential;
+    timeoutMs;
+    fetchImpl;
+    baseUrl;
+    headers;
+    constructor(credential, baseUrl, timeoutMs, versionTag, fetchImpl) {
+        this.credential = credential;
+        this.timeoutMs = timeoutMs;
+        this.fetchImpl = fetchImpl;
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+        this.headers = { 'User-Agent': `sai-typescript/${VERSION}` };
+        if (typeof credential === 'string')
+            this.headers.Authorization = `Bearer ${credential}`;
+        // routes the request to a tagged API revision
+        if (versionTag)
+            this.headers['x-sai-version'] = versionTag;
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(opts.params ?? {})) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+        const headers = { ...this.headers, ...opts.headers };
+        if (typeof this.credential === 'function') {
+            headers.Authorization = `Bearer ${await this.credential()}`;
+        }
+        let body = opts.body;
+        if (opts.json !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(opts.json);
+        }
+        let res;
+        try {
+            res = await this.fetchImpl(url.toString(), {
+                method,
+                headers,
+                body,
+                signal: AbortSignal.timeout(opts.timeoutMs ?? this.timeoutMs),
+            });
+        }
+        catch (err) {
+            const name = err instanceof Error ? err.name : '';
+            if (name === 'TimeoutError' || name === 'AbortError') {
+                throw new ConnectionError(`Request to ${url.host} timed out.`, { cause: err });
+            }
+            const cause = err instanceof Error ? err.cause : undefined;
+            const detail = cause?.message ?? (err instanceof Error ? err.message : String(err));
+            throw new ConnectionError(`Could not reach the Sai API at ${url.host}: ${detail}. Check the network and SAI_API_URL.`, { cause: err });
+        }
+        if (res.status >= 400)
+            throw await toError(res);
+        return res;
+    }
+    async json(method, path, opts = {}) {
+        const res = await this.request(method, path, opts);
+        const text = await res.text();
+        return (text ? JSON.parse(text) : null);
+    }
+}
+async function toError(res) {
+    const text = await res.text().catch(() => '');
+    let body;
+    try {
+        const parsed = JSON.parse(text);
+        body =
+            parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+                ? parsed
+                : { error: String(parsed) };
+    }
+    catch {
+        body = { error: text.slice(0, 500) || res.statusText };
+    }
+    const raw = res.headers.get('retry-after');
+    const retryAfter = raw !== null && raw !== '' && !Number.isNaN(Number(raw)) ? Number(raw) : undefined;
+    return errorFor(res.status, body, retryAfter);
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * TypeScript SDK for the Sai API.
+ *
+ * - `sai.sessions`: give Sai a task on a computer and get the answer back.
+ * - `sai.learn`, `sai.judge`: turn recorded turns or a task into Simulang code, repair it, run
+ *   judge and repair it on a machine (policy iteration), judge turns.
+ * - `sai.control`: drive a cloud computer yourself with Simulang.
+ * - `sai.machines`, `sai.models`, `sai.files`, `sai.account`.
+ * - `sai.tenants`, `sai.tenantMachines`: your customers under an Organisation (an Organisation Key).
+ */
+export { Sai, type SaiOptions } from './client.js';
+export { AuthenticationError, BadRequestError, BlockError, ConflictError, ConnectionError, GoneError, LinkOnlyApprovalError, NotFoundError, PermissionDeniedError, RateLimitError, SaiError, ServiceUnavailableError, SpendCapReachedError, } from './errors.js';
+export { ControlLease } from './control.js';
+export type { MachineRef } from './machines.js';
+export type { TenantMachineRef, TenantRef } from './tenants.js';
+export type { TurnRef } from './turns.js';
+export type { JudgeOptions, LearnOptions } from './learn.js';
+export { Session, Turn, type ApprovalAnswer, type ApprovalHandler, type SendOptions, type WaitOptions, } from './sessions.js';
+export { EVENT_KINDS, TURN_RECORD_STATUSES, TURN_STATUSES, type Account, type Approval, type Attachment, type Check, type CriterionResult, type Enrollment, type Evaluation, type Event, type Evidence, type EventKind, type ExecError, type ExecResult, type Judgement, type LearnIteration, type LearnParameter, type LearnReset, type LearnResult, type LearnRollout, type LearnRun, type LearnTestResult, type LiveView, type Machine, type Model, type Tenant, type TenantMachine, type TenantPage, type TenantToken, type TrajectoryStep, type TurnRecord, type TurnRecordStatus, type TurnResult, type TurnStatus, type Usage, } from './types.js';
+export { VERSION } from './version.js';

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * TypeScript SDK for the Sai API.
+ *
+ * - `sai.sessions`: give Sai a task on a computer and get the answer back.
+ * - `sai.learn`, `sai.judge`: turn recorded turns or a task into Simulang code, repair it, run
+ *   judge and repair it on a machine (policy iteration), judge turns.
+ * - `sai.control`: drive a cloud computer yourself with Simulang.
+ * - `sai.machines`, `sai.models`, `sai.files`, `sai.account`.
+ * - `sai.tenants`, `sai.tenantMachines`: your customers under an Organisation (an Organisation Key).
+ */
+export { Sai } from './client.js';
+export { AuthenticationError, BadRequestError, BlockError, ConflictError, ConnectionError, GoneError, LinkOnlyApprovalError, NotFoundError, PermissionDeniedError, RateLimitError, SaiError, ServiceUnavailableError, SpendCapReachedError, } from './errors.js';
+export { ControlLease } from './control.js';
+export { Session, Turn, } from './sessions.js';
+export { EVENT_KINDS, TURN_RECORD_STATUSES, TURN_STATUSES, } from './types.js';
+export { VERSION } from './version.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,GAAG,EAAmB,MAAM,aAAa,CAAA;AAClD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,UAAU,EACV,aAAa,EACb,eAAe,EACf,SAAS,EACT,qBAAqB,EACrB,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,QAAQ,EACR,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAK3C,OAAO,EACL,OAAO,EACP,IAAI,GAKL,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,aAAa,GAkCd,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/dist/learn.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Learn and judge (research preview): turn recorded turns, or a task the agent does first, into
+ * Simulang code you own; repair that code; run, judge and repair it on a machine until it passes
+ * (policy iteration); and judge turns against criteria you choose now.
+ *
+ * Maps to `/v1/agents/learn` and `/v1/agents/judge`.
+ */
+import type { Http } from './http.js';
+import { type MachineRef } from './machines.js';
+import type { TurnRef } from './turns.js';
+import { type LearnRun, type Check, type Evaluation, type Judgement, type LearnResult } from './types.js';
+export interface LearnOptions {
+    /**
+     * The task, with `{{name}}` placeholders: `'Submit claim for {{patient}} to {{payer}}'`. Without
+     * `turns`, the agent does this task first. With `turns`, it defaults to the first turn's.
+     */
+    taskTemplate?: string;
+    /** @deprecated Use `taskTemplate`. */
+    template?: string;
+    /** A value for every placeholder; with `turns`, defaults to the first turn's. */
+    inputs?: Record<string, string | number | boolean>;
+    /** Code to repair (with `maxIterations` 0), or to start the run-judge-repair loop from. */
+    initialCode?: string;
+    /** How `initialCode` did on runs (a repair only). */
+    evaluations?: Evaluation[];
+    /** What you know about the task, for writing and repairing the code, e.g. "the Save button is under the ⋯ menu". */
+    guidance?: string;
+    /** @deprecated Use `guidance`. */
+    feedback?: string;
+    /** For a repair: what earlier versions of the code changed and how they failed, so the repair does not repeat them. */
+    history?: string;
+    /**
+     * For a conversion: the code will be run again and again with no reset in between, so it opens
+     * the app or URL itself instead of assuming the screen it starts on.
+     */
+    runsWithoutReset?: boolean;
+    /**
+     * Code versions to run, judge and repair: 0 (the default) only writes the code; 3 allows up to
+     * two repairs. At most 5.
+     */
+    maxIterations?: number;
+    /** Runs per code version; a version passes when all of them pass. Default 3, at most 5. */
+    rollouts?: number;
+    /** The machine to run on; optional with one machine. */
+    machine?: MachineRef;
+    /** What "done" means for the judge; default: the task as written, with its inputs. */
+    criteria?: string | Check[];
+    /** Run before the agent run and before every run of the code: Simulang `code`, or a `task` for the agent. */
+    reset?: {
+        code: string;
+    } | {
+        task: string;
+    };
+    /** Judge the agent run first; if it fails, the job stops with the judgement and writes no code. */
+    judgeInitialAgentRun?: boolean;
+    /** After a failed run, let the agent finish the task; its turn feeds the repair. */
+    continueWithAgent?: boolean;
+    /** Limit of each run of the code, in minutes. Default 15. */
+    rolloutMinutes?: number;
+    /** Limit of the agent run and of each reset task, in minutes. Default 15. */
+    agentRunMinutes?: number;
+    /** Limit of each continuation, in minutes. Default 15. */
+    continuationMinutes?: number;
+    /** Limit of the whole job, in minutes. Default 615, at most 690. */
+    maxJobMinutes?: number;
+    /** A model id from `sai.models.list()`; without it, Sai picks the model. */
+    model?: string;
+    /** The same key again returns the earlier result and runs nothing. */
+    idempotencyKey?: string;
+    timeoutMs?: number;
+}
+export declare class Learn {
+    private readonly http;
+    constructor(http: Http);
+    /**
+     * Make Simulang code, and optionally run, judge and repair it on a machine.
+     *
+     * - `create(turns)`: code from recorded turns (ordered, one session, each sent with
+     *   `recordTrajectory`). Answers with the code; a longer task takes longer.
+     * - `create([], { initialCode, guidance | evaluations })`: a repair. Answers with the code.
+     * - `create(turns, { maxIterations: 3 })` or `create([], { taskTemplate, inputs, maxIterations: 3 })`:
+     *   a job on the machine (from `turns`, or after the agent does the task). Answers at once with
+     *   `status: 'running'`; read it with `wait()`.
+     *
+     * A result with `validation.errors` comes back `failed`.
+     */
+    create(turns: TurnRef[], opts?: LearnOptions): Promise<LearnResult>;
+    /** A learn call's result, or a job's progress so far. */
+    get(learnId: string): Promise<LearnResult>;
+    /**
+     * Read a learn job until it ends (`succeeded`, `failed` or `stopped`). `timeoutMs` throws a
+     * `TimeoutError` (DOMException) with the job still running; it keeps running.
+     */
+    wait(job: LearnResult | string, opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<LearnResult>;
+    /**
+     * Stop a learn job at once, whatever step it is on. It keeps the last complete results and
+     * reads `stopped` / `cancelled` once it has ended, normally within seconds.
+     */
+    cancel(job: LearnResult | string): Promise<void>;
+    /** One run of a learn job's code: what it returned and logged, and its judgement. */
+    rollout(job: LearnResult | string, iteration: number, rollout: number): Promise<LearnRun>;
+}
+export interface JudgeOptions {
+    /** Default: the first turn's message. */
+    task?: string;
+    idempotencyKey?: string;
+    timeoutMs?: number;
+}
+export declare class Judge {
+    private readonly http;
+    constructor(http: Http);
+    /**
+     * Judge recorded `turns` (one session, as one task) against `criteria`: a sentence for a model
+     * to judge, or a list of `Check`s. Nothing runs again, and the turns do not change.
+     */
+    create(turns: TurnRef[], criteria: string | Check[], opts?: JudgeOptions): Promise<Judgement>;
+    get(judgementId: string): Promise<Judgement>;
+}