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

package/dist/learn.js

@@ -0,0 +1,174 @@
+/**
+ * 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 { RateLimitError } from './errors.js';
+import { idOf } from './machines.js';
+import { parseJudgement, parseLearnResult, parseLearnRun, } from './types.js';
+/** A conversion is two model calls of up to a minute or two each, plus one retry. */
+const LEARN_TIMEOUT_MS = 600_000;
+const JUDGE_TIMEOUT_MS = 180_000;
+/** The last log lines of a run sent with an evaluation; the API takes 20 KB per result. */
+const EVAL_LOG_LINES = 30;
+/** How often `wait` reads a learn job; a job's steps take tens of seconds to minutes. */
+const LEARN_POLL_INTERVAL_MS = 10_000;
+const turnId = (t) => {
+    const id = typeof t === 'string' ? t : t.id;
+    if (!id)
+        throw new Error('This turn has no id: the message was answered without starting one.');
+    return id;
+};
+function evaluationJson(e) {
+    const r = e.result;
+    return {
+        inputs: e.inputs,
+        ...(r && {
+            result: {
+                result: r.result,
+                logs: r.logs.slice(-EVAL_LOG_LINES),
+                ...(r.error && { error: { kind: r.error.kind, message: r.error.message } }),
+            },
+        }),
+        ...(e.judgement !== undefined && {
+            judgement: typeof e.judgement === 'string' ? e.judgement : e.judgement.id,
+        }),
+        ...(e.passed !== undefined && { passed: e.passed }),
+        ...(e.note !== undefined && { note: e.note }),
+    };
+}
+export class Learn {
+    http;
+    constructor(http) {
+        this.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`.
+     */
+    async create(turns, opts = {}) {
+        const body = { turns: turns.map(turnId) };
+        // The old names go out as sent, so code that uses them keeps working with an older API.
+        if (opts.taskTemplate !== undefined)
+            body.taskTemplate = opts.taskTemplate;
+        else if (opts.template !== undefined)
+            body.template = opts.template;
+        if (opts.inputs !== undefined)
+            body.inputs = opts.inputs;
+        if (opts.initialCode !== undefined)
+            body.initialCode = opts.initialCode;
+        if (opts.evaluations)
+            body.evaluations = opts.evaluations.map(evaluationJson);
+        if (opts.guidance !== undefined)
+            body.guidance = opts.guidance;
+        else if (opts.feedback !== undefined)
+            body.feedback = opts.feedback;
+        if (opts.machine !== undefined)
+            body.machineId = idOf(opts.machine);
+        for (const k of [
+            'history',
+            'runsWithoutReset',
+            'maxIterations',
+            'rollouts',
+            'criteria',
+            'reset',
+            'judgeInitialAgentRun',
+            'continueWithAgent',
+            'rolloutMinutes',
+            'agentRunMinutes',
+            'continuationMinutes',
+            'maxJobMinutes',
+        ]) {
+            if (opts[k] !== undefined)
+                body[k] = opts[k];
+        }
+        if (opts.model !== undefined)
+            body.model = opts.model;
+        if (opts.idempotencyKey !== undefined)
+            body.idempotency_key = opts.idempotencyKey;
+        return parseLearnResult(await this.http.json('POST', '/v1/agents/learn', {
+            json: body,
+            timeoutMs: opts.timeoutMs ?? LEARN_TIMEOUT_MS,
+        }));
+    }
+    /** A learn call's result, or a job's progress so far. */
+    async get(learnId) {
+        return parseLearnResult(await this.http.json('GET', `/v1/agents/learn/${encodeURIComponent(learnId)}`));
+    }
+    /**
+     * Read a learn job until it ends (`succeeded`, `failed` or `stopped`). `timeoutMs` throws a
+     * `TimeoutError` (DOMException) with the job still running; it keeps running.
+     */
+    async wait(job, opts = {}) {
+        const learnId = typeof job === 'string' ? job : job.id;
+        const poll = opts.pollMs ?? LEARN_POLL_INTERVAL_MS;
+        const deadline = opts.timeoutMs === undefined ? null : Date.now() + opts.timeoutMs;
+        for (;;) {
+            let r;
+            try {
+                r = await this.get(learnId);
+            }
+            catch (err) {
+                if (!(err instanceof RateLimitError))
+                    throw err;
+                await sleep((err.retryAfter ?? 30) * 1000);
+                continue;
+            }
+            if (r.status !== 'running')
+                return r;
+            if (deadline !== null && Date.now() + poll > deadline) {
+                throw new DOMException(`Learn job ${learnId} is still running.`, 'TimeoutError');
+            }
+            await sleep(poll);
+        }
+    }
+    /**
+     * 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.
+     */
+    async cancel(job) {
+        const learnId = typeof job === 'string' ? job : job.id;
+        await this.http.json('POST', `/v1/agents/learn/${encodeURIComponent(learnId)}/cancel`);
+    }
+    /** One run of a learn job's code: what it returned and logged, and its judgement. */
+    async rollout(job, iteration, rollout) {
+        const learnId = typeof job === 'string' ? job : job.id;
+        return parseLearnRun(await this.http.json('GET', `/v1/agents/learn/${encodeURIComponent(learnId)}/iterations/${iteration}/rollouts/${rollout}`));
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class Judge {
+    http;
+    constructor(http) {
+        this.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.
+     */
+    async create(turns, criteria, opts = {}) {
+        const body = { turns: turns.map(turnId), criteria };
+        if (opts.task !== undefined)
+            body.task = opts.task;
+        if (opts.idempotencyKey !== undefined)
+            body.idempotency_key = opts.idempotencyKey;
+        return parseJudgement(await this.http.json('POST', '/v1/agents/judge', {
+            json: body,
+            timeoutMs: opts.timeoutMs ?? JUDGE_TIMEOUT_MS,
+        }));
+    }
+    async get(judgementId) {
+        return parseJudgement(await this.http.json('GET', `/v1/agents/judge/${encodeURIComponent(judgementId)}`));
+    }
+}
+//# sourceMappingURL=learn.js.map

package/dist/learn.js.map

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

package/dist/machines.d.ts

@@ -0,0 +1,15 @@
+import type { Http } from './http.js';
+import { type LiveView, type Machine } from './types.js';
+export type MachineRef = Machine | string;
+/** Machines: the computers Sai works on. Cloud computers, or the customer's own PC with the Sai app. */
+export declare class Machines {
+    private readonly http;
+    constructor(http: Http);
+    list(): Promise<Machine[]>;
+    get(machineId: string): Promise<Machine>;
+    /** A view-only stream of the screen (Apache Guacamole). The machine must be running. */
+    live(machine: MachineRef): Promise<LiveView>;
+    /** @internal */
+    resolveId(machine: MachineRef | undefined): Promise<string>;
+}
+export declare function idOf(machine: MachineRef): string;

package/dist/machines.js

@@ -0,0 +1,47 @@
+import { BadRequestError, NotFoundError } from './errors.js';
+import { parseMachine } from './types.js';
+/** Machines: the computers Sai works on. Cloud computers, or the customer's own PC with the Sai app. */
+export class Machines {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async list() {
+        const d = await this.http.json('GET', '/v1/agents/machines');
+        return (d.machines ?? []).map(parseMachine);
+    }
+    async get(machineId) {
+        const m = (await this.list()).find((x) => x.id === machineId);
+        if (!m)
+            throw new NotFoundError(`Machine ${machineId} not found on this account.`, { status: 404 });
+        return m;
+    }
+    /** A view-only stream of the screen (Apache Guacamole). The machine must be running. */
+    async live(machine) {
+        const id = idOf(machine);
+        const d = await this.http.json('POST', `/v1/agents/machines/${encodeURIComponent(id)}/live`);
+        return {
+            machineId: typeof d.machineId === 'string' ? d.machineId : id,
+            websocketUrl: String(d.websocketUrl),
+            width: Number(d.width ?? 0),
+            height: Number(d.height ?? 0),
+        };
+    }
+    /** @internal */
+    async resolveId(machine) {
+        if (machine)
+            return idOf(machine);
+        const machines = await this.list();
+        if (machines.length === 1)
+            return machines[0].id;
+        if (machines.length === 0) {
+            throw new BadRequestError('No computer on this account. Create one in the Sai app or the portal.', { status: 400 });
+        }
+        const names = machines.map((m) => (m.name ? `${m.id} (${m.name})` : m.id)).join(', ');
+        throw new BadRequestError(`Several computers on this account; pass machine. Candidates: ${names}`, { status: 400 });
+    }
+}
+export function idOf(machine) {
+    return typeof machine === 'string' ? machine : machine.id;
+}
+//# sourceMappingURL=machines.js.map

package/dist/machines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machines.js","sourceRoot":"","sources":["../src/machines.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE5D,OAAO,EAAE,YAAY,EAA+B,MAAM,YAAY,CAAA;AAItE,wGAAwG;AACxG,MAAM,OAAO,QAAQ;IACU;IAA7B,YAA6B,IAAU;QAAV,SAAI,GAAJ,IAAI,CAAM;IAAG,CAAC;IAE3C,KAAK,CAAC,IAAI;QACR,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAC5B,KAAK,EACL,qBAAqB,CACtB,CAAA;QACD,OAAO,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;IAC7C,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,SAAiB;QACzB,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,CAAC,CAAA;QAC7D,IAAI,CAAC,CAAC;YACJ,MAAM,IAAI,aAAa,CAAC,WAAW,SAAS,6BAA6B,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;QAC7F,OAAO,CAAC,CAAA;IACV,CAAC;IAED,wFAAwF;IACxF,KAAK,CAAC,IAAI,CAAC,OAAmB;QAC5B,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,CAAA;QACxB,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAC5B,MAAM,EACN,uBAAuB,kBAAkB,CAAC,EAAE,CAAC,OAAO,CACrD,CAAA;QACD,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;YAC7D,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC;YACpC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;YAC3B,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;SAC9B,CAAA;IACH,CAAC;IAED,gBAAgB;IAChB,KAAK,CAAC,SAAS,CAAC,OAA+B;QAC7C,IAAI,OAAO;YAAE,OAAO,IAAI,CAAC,OAAO,CAAC,CAAA;QACjC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAA;QAClC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,QAAQ,CAAC,CAAC,CAAE,CAAC,EAAE,CAAA;QACjD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,eAAe,CACvB,uEAAuE,EACvE,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAA;QACH,CAAC;QACD,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACrF,MAAM,IAAI,eAAe,CACvB,gEAAgE,KAAK,EAAE,EACvE,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAA;IACH,CAAC;CACF;AAED,MAAM,UAAU,IAAI,CAAC,OAAmB;IACtC,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAA;AAC3D,CAAC"}

package/dist/sessions.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Sessions: a conversation with Sai on one computer. Sai decides every click.
+ *
+ * Maps to `/v1/agents/*`: `new-session`, `message` (wait=false), `events`,
+ * `approve`, `abort`. Every message gets a turn id (`turn.id`, read with
+ * `sai.turns`); a message with `inputs`, `outputSchema` or `successCriteria`
+ * is structured and its turn also returns a typed result.
+ */
+import type { Http } from './http.js';
+import { type MachineRef, type Machines } from './machines.js';
+import { type Approval, type Attachment, type Check, type Event, type TurnRecord, type TurnRecordStatus, type TurnResult, type TurnStatus } from './types.js';
+/**
+ * What an `onApproval` handler answers: a response (`yes`, `no`, `task`), a
+ * `[response, selections]` pair for a choice, or null to leave the approval
+ * pending (e.g. a human answers it in a browser).
+ */
+export type ApprovalAnswer = string | [string, string[][]] | null;
+export type ApprovalHandler = (approval: Approval) => ApprovalAnswer | Promise<ApprovalAnswer>;
+export interface SendOptions {
+    /** An id from `sai.models.list()` (or `auto`); sticks to the session until changed. */
+    model?: string;
+    attachments?: Attachment[];
+    /** Values for the `{{name}}` placeholders in the message. Makes the message structured. */
+    inputs?: Record<string, string | number | boolean>;
+    /** JSON Schema (at most 32 KB) the turn's output must match. Makes the message structured. */
+    outputSchema?: Record<string, unknown>;
+    /**
+     * A guideline for a judge, or yes/no checks, the turn is checked against.
+     * Makes the message structured.
+     */
+    successCriteria?: string | Check[];
+    /** The same key again returns the earlier turn and sends nothing. */
+    idempotencyKey?: string;
+    /** Keep a screenshot and the action for each step (`sai.turns.trajectory()`). */
+    recordTrajectory?: boolean;
+    /**
+     * Run the turn this message starts without approval cards, as if "Trust for
+     * this task" had been answered; the grant ends with the turn. A message that
+     * steers a running turn changes nothing.
+     */
+    autonomous?: boolean;
+}
+export interface WaitOptions {
+    onApproval?: ApprovalHandler;
+    /** Throws a `TimeoutError` (DOMException) with the turn still running. */
+    timeoutMs?: number;
+    /** Seconds the server may hold one poll; it caps at 60. */
+    pollWait?: number;
+}
+export declare class Sessions {
+    private readonly http;
+    private readonly machines;
+    constructor(http: Http, machines: Machines);
+    /**
+     * Start a fresh conversation on a computer: the next message has no memory
+     * of earlier ones. `machine` may be omitted with one computer.
+     */
+    create(opts?: {
+        machine?: MachineRef;
+    }): Promise<Session>;
+    /** Reattach to a session started elsewhere, e.g. to poll or abort it. */
+    resume(sessionId: string, opts?: {
+        machine?: MachineRef;
+    }): Session;
+}
+/** A conversation with Sai. Each `send()` is a turn; turns share context. */
+export declare class Session {
+    private readonly http;
+    machineId: string | null;
+    id: string | null;
+    constructor(http: Http, machineId: string | null, id: string | null);
+    /**
+     * Give Sai a task, or steer the running one. Returns at once. Sent while a
+     * turn is running, the message steers that turn (`turn.queued` is true).
+     *
+     * Any of `inputs`, `outputSchema` or `successCriteria` makes the message
+     * structured: the message is a template whose `{{name}}` placeholders are
+     * filled from `inputs`, the output must match `outputSchema`, and the turn
+     * is checked against `successCriteria`. `wait()` then also returns the
+     * turn's record in `result.record`. A structured message is refused with
+     * `ConflictError` (`session_busy`) while a turn is running. These go to the
+     * API as `options`.
+     */
+    send(message: string, opts?: SendOptions): Promise<Turn>;
+    /** `send()` then `wait()`: the answer, or where it stopped. */
+    run(message: string, opts?: SendOptions & WaitOptions): Promise<TurnResult>;
+    /** Stop the running turn. Pending approvals are denied. False if nothing was running. */
+    abort(): Promise<boolean>;
+    /**
+     * Answer an approval: `yes`, `no`, or `task` (allow for the rest of the task).
+     * A `choice` approval needs `selections`, one list of option values per
+     * question. Throws `LinkOnlyApprovalError` (with `approvalUrl`) when only a
+     * browser can answer it. Resolves to `approved`, `approved_task` or `denied`.
+     */
+    respond(approval: Approval | string, response?: string, opts?: {
+        selections?: string[][];
+    }): Promise<string>;
+}
+/**
+ * One message's work. Iterate `events()` to watch it, or `wait()` for the
+ * result. `id` is the turn the message started, or the running turn it joined
+ * (`sai.turns.get(turn)`); null when the message was answered without one.
+ */
+export declare class Turn {
+    #private;
+    readonly session: Session;
+    private readonly http;
+    readonly queued: boolean;
+    readonly id: string | null;
+    private cursor;
+    private last;
+    private readonly structured;
+    private readonly replay;
+    private readonly local;
+    constructor(session: Session, http: Http, queued: boolean, done?: TurnResult | null, turn?: {
+        id: string | null;
+        structured: boolean;
+        replay?: TurnRecord;
+    });
+    get status(): TurnStatus;
+    /** The last known state, or null before the first poll. */
+    get result(): TurnResult | null;
+    /**
+     * Yield events until the turn is idle or errors. It keeps going through
+     * `needs_approval`: answer with `turn.respond(ev.approval, ...)` inside the
+     * loop, or let a human answer a link-only approval in a browser. Without
+     * `raw`, framing, reasoning and tool-call frames are skipped.
+     */
+    events(opts?: {
+        raw?: boolean;
+        pollWait?: number;
+    }): AsyncGenerator<Event>;
+    /**
+     * Wait until the turn is done, or stops on an approval nobody answered.
+     * Without `onApproval`, resolves with `status === 'needs_approval'` and the
+     * `approval` so the caller can decide. With it, the handler's answer is sent
+     * and waiting continues; a handler returning null leaves the approval to
+     * someone else (a link-only one to a human) and keeps waiting. For a
+     * structured message, it then waits for the turn's record (`result.record`:
+     * output, evidence), which is worked out after the turn.
+     */
+    wait(opts?: WaitOptions): Promise<TurnResult>;
+    respond(approval: Approval | string, response?: string, opts?: {
+        selections?: string[][];
+    }): Promise<string>;
+    abort(): Promise<boolean>;
+}
+/**
+ * Read the turn's record until its status is in `stop`. Throws a `TimeoutError`
+ * (DOMException) past `deadline` (epoch ms).
+ */
+export declare function waitTurnRecord(http: Http, turnId: string, deadline: number | null, stop?: readonly TurnRecordStatus[]): Promise<TurnRecord>;