@soba-so/sdk 0.0.5

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright © 2026 Soba. All rights reserved.
+
+This software is licensed, not sold, and it is not open source.
+
+Subject to your agreement with Soba, you are granted a non-exclusive,
+non-transferable, non-sublicensable, revocable licence to install this package
+and use it in your own applications for the sole purpose of interfacing with
+the Soba service.
+
+You may not redistribute it, publish it, sell it, sublicense it, incorporate it
+into another distributed library, or create and distribute derivative works of
+it. No rights are granted in the Soba name or logo.
+
+This software is provided "as is", without warranty of any kind, express or
+implied. To the maximum extent permitted by law, Soba shall not be liable for
+any claim, damages or other liability arising from the software or its use.
+
+Nothing here limits any right you have that cannot be limited by the law that
+applies to you.

package/README.md

@@ -0,0 +1,144 @@
+# @soba-so/sdk
+
+**One request that comes back finished, executed on compute the end user owns.**
+
+```js
+import { Soba } from "@soba-so/sdk"
+
+const soba = new Soba({ apiKey: process.env.SOBA_KEY })
+
+const run = await soba.run({
+  user: session.user.id,
+  model: "auto",
+  prompt: "Summarise everything I saved this week",
+  tools: [listNotes, readNote],   // your code, executed in your app
+})
+
+for await (const event of run) {
+  if (event.type === "delta") process.stdout.write(event.text)
+  if (event.type === "done") console.log(event.usage)
+}
+```
+
+## Why this exists alongside `chat/completions`
+
+`POST /v1/chat/completions` is stateless and **the caller owns the loop**: you
+send messages, you get a tool call back, you execute it, you send everything
+again. That works for a model. It cannot work for an agent.
+
+Claude Code and Codex run their own loop, and they never hand a tool call back to
+wait on an HTTP round trip. So reaching them means **Soba owns the loop**, and
+your tools have to be registered up front rather than returned mid-conversation.
+That is the whole difference between the two entry points, and this package is
+the second one.
+
+If you only need models, you do not need this package at all: point an OpenAI
+client at `https://api.soba.so/v1` and pass `user`.
+
+## What it is
+
+A convenience over `POST /v1/runs`, not a different product. It adds four things
+that are tedious to write once and easy to write wrongly:
+
+| | |
+|---|---|
+| The stream | Server-sent events parsed into the five [event types](https://soba.so/docs/reference/events) |
+| The tool loop | A `tool_call` arrives, **your** function runs here, the result goes back |
+| Approvals | An escalation is answered, and **fails closed** if it cannot be |
+| Failure | The three kinds of failure told apart, and retries only where they are safe |
+
+## The shapes
+
+```ts
+new Soba({ apiKey, baseURL, maxRetries, connectTimeoutMs, onWarning })
+
+soba.run({ user, prompt | messages, system, model, runtime, tools, route, policy, approve, signal })
+
+soba.users.get(id)        // plan, allowance, usage this period
+soba.users.compute(id)    // each connected machine and its live state
+soba.usage.list(query)    // the ledger, in integer micros
+soba.plans.list()
+soba.request(method, path, options)   // the escape hatch
+```
+
+`await soba.run(…)` resolves when the response **headers** arrive, not when the
+run finishes. That is the same boundary the API draws: a failure before the first
+byte throws here, and a failure after it arrives as a terminal `error` event.
+
+### `user` is required, and cannot be defaulted
+
+It is how a run is attributed to a person, therefore how it is metered, and
+therefore how Soba knows whose machine it may reach. Sending a run without one is
+refused locally rather than at the server, because it is the mistake every
+integration makes exactly once.
+
+### Tools are your code
+
+The schema travels to the model. The implementation never leaves your process.
+
+```js
+import { tool } from "@soba-so/sdk"
+
+const listNotes = tool({
+  name: "listNotes",
+  description: "List the notes this user saved.",
+  inputSchema: { type: "object", properties: { since: { type: "string" } } },
+  execute: async ({ since }, ctx) => db.notes.since(ctx.user, since),
+})
+```
+
+Throwing inside `execute` is **not** a run failure: the error is handed to the
+model as a failed call, which it can see and work around. `ctx.signal` is aborted
+when the run ends, and long tools should honour it.
+
+### Approvals fail closed
+
+A tool inside the machine's askable set needs a live answer. No approver, a
+throw, or anything that is not the string `"allow"` is a denial, because an
+approval channel that fails open turns "ask" into "allow".
+
+```js
+await soba.run({
+  user, prompt,
+  approve: async ({ tool, input, cwd }) => (tool === "bash" ? "deny" : "allow"),
+})
+```
+
+### Retries happen in one place, and only before the first byte
+
+`POST /v1/runs` is not idempotent: retrying a run that already started is a
+second run, billed as one. So the SDK retries `429`, `5xx` and transport
+failures **before** a response arrives and never after, and it does not retry
+`409 no_compute` at all: that clears when a laptop wakes up, which is minutes
+away, not milliseconds. Your app owns that decision.
+
+## Errors
+
+One class, `SobaError`, carrying `code`, `type`, `status`, `retryable` and
+`retryAfterMs`. A stream that ends without `done` or `error` is
+`stream_truncated`: a transport failure, retryable, and deliberately distinct
+from a delivered `error` event, which is final.
+
+## The HTTP contract
+
+Everything here is the documented API plus three answer-back routes, which exist
+because a tool loop needs a return path and an SSE stream only goes one way:
+
+| | |
+|---|---|
+| `POST /v1/runs` | Start a run. Responds `text/event-stream` with the run id in `Soba-Run-Id` |
+| `POST /v1/runs/:id/tool_result` | `{ callId, result, isError }` |
+| `POST /v1/runs/:id/approval` | `{ approvalId, decision, reason? }` |
+| `POST /v1/runs/:id/cancel` | Best effort. The local stream drops immediately |
+
+The stream carries the run's [events](https://soba.so/docs/reference/events), plus
+a tool call or an approval request when one is waiting on you. Anything the SDK does
+not recognise is skipped rather than fatal, so a server that ships ahead of your
+installed version does not break the stream.
+
+## Types
+
+Ships its own `.d.ts`. Every shape above — the run options, the event types, the
+usage record, `SobaError` — is typed, with no separate `@types` package to install.
+
+© 2026 Soba. All rights reserved. Licensed for use with the Soba service; see LICENSE.

package/dist/client.d.ts

@@ -0,0 +1,111 @@
+import type { Message, RouteRequest, RunPolicy } from "./protocol.js";
+import type { ConnectedMachine, PlanSummary, SobaUser, UsagePage, UsageQuery } from "./resources.js";
+import { type Approver, Run } from "./run.js";
+import { type ToolDefinition } from "./tools.js";
+/**
+ * Where a run goes when nobody says otherwise.
+ *
+ * `api.`, which now exists — for months it had no DNS record, and the default
+ * pointed at `www` because a host that answers beat a host that does not.
+ *
+ * `www` was never right, only reachable. A run needs a socket held open for its
+ * whole duration and a round trip to Postgres per turn; Vercel gives neither,
+ * so `/v1/runs` is not served there and never will be. It 404s. Everything else
+ * in this API — sessions, pairing, machines — IS served there, which is why the
+ * two hosts both exist and why only this one is the run endpoint.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.soba.so/v1";
+export interface SobaOptions {
+    /** Defaults to `SOBA_KEY`, then `SOBA_API_KEY`. Shaped `sk_soba_<id>.<secret>`. */
+    apiKey?: string;
+    /** Defaults to `SOBA_BASE_URL`, then https://api.soba.so/v1. */
+    baseURL?: string;
+    fetch?: typeof globalThis.fetch;
+    /** Retries before the first byte only. Never after a stream has started. */
+    maxRetries?: number;
+    /** How long to wait for response HEADERS. The run itself is not capped here. */
+    connectTimeoutMs?: number;
+    headers?: Record<string, string>;
+    /** Told about failures that have nowhere else to go: an undeliverable tool
+     *  result, a cancel the broker never heard. Silent by default. */
+    onWarning?: (message: string, detail?: unknown) => void;
+    /** An app key is a SERVER credential. Shipping it to a browser hands every
+     *  visitor the ability to spend your account. Only set this for a trusted
+     *  first-party context you control. */
+    dangerouslyAllowBrowser?: boolean;
+}
+export interface RunParams {
+    /**
+     * The end user this run belongs to. Load-bearing, and the SDK refuses without
+     * it: it is how a run is attributed to a person, therefore how it is metered,
+     * and therefore how Soba knows whose machine it may reach.
+     */
+    user: string;
+    /** A single user turn. Shorthand for `messages: [{role:"user", content}]`. */
+    prompt?: string;
+    messages?: Message[];
+    system?: string;
+    /** Defaults to "auto": let the route decide. */
+    model?: string;
+    /** Name a specific runtime only when you have a reason to. `route` is the
+     *  declaration that survives a user connecting something different. */
+    runtime?: string;
+    /** Your code, executed in your app. Schemas go to the model; nothing else moves. */
+    tools?: readonly ToolDefinition[];
+    /** Which economics this run may use. A plan compiles to one on every run, so
+     *  most apps never write this by hand. */
+    route?: RouteRequest;
+    /** What the run REQUESTS of the machine. The machine's own grant still wins. */
+    policy?: RunPolicy;
+    /** Answers escalations for tools inside the machine's askable set. Absent
+     *  means every escalation is denied. */
+    approve?: Approver;
+    metadata?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * The Soba client.
+ *
+ * ```js
+ * const soba = new Soba({ apiKey: process.env.SOBA_KEY })
+ * const run = await soba.run({ user: session.user.id, prompt: "…" })
+ * for await (const event of run) …
+ * ```
+ *
+ * `soba.run()` exists alongside `chat/completions` for one reason:
+ * `chat/completions` is stateless and the CALLER owns the agent loop, so it
+ * reaches models. Claude Code and Codex run their own loop and never hand a
+ * tool call back to wait on an HTTP round trip, so reaching them means SOBA
+ * owns the loop, and that is this call.
+ */
+export declare class Soba {
+    #private;
+    readonly users: {
+        /** What this user has: plan, allowance, usage this period, what they connected. */
+        get(id: string): Promise<SobaUser>;
+        /** Each connected machine, its runtimes, cost classes and live state. */
+        compute(id: string): Promise<ConnectedMachine[]>;
+    };
+    readonly usage: {
+        list(query?: UsageQuery): Promise<UsagePage>;
+    };
+    readonly plans: {
+        list(): Promise<PlanSummary[]>;
+    };
+    constructor(options?: SobaOptions);
+    get baseURL(): string;
+    /**
+     * Start a run and get back something you iterate.
+     *
+     * Resolves when the response HEADERS arrive, not when the run finishes. That
+     * is the same boundary the API draws: a failure before the first byte throws
+     * here, and a failure after it arrives as a terminal `error` event.
+     */
+    run(params: RunParams): Promise<Run>;
+    /** The escape hatch. Every typed read above is this call with a shape on it. */
+    request<T>(method: "GET" | "POST" | "DELETE", path: string, options?: {
+        query?: Record<string, string | number | boolean | undefined>;
+        body?: unknown;
+        signal?: AbortSignal;
+    }): Promise<T>;
+}

package/dist/errors.d.ts

@@ -0,0 +1,67 @@
+export type SobaErrorCode = 
+/** 400 malformed, or caught here before the round trip */
+"invalid_request"
+/** 422 no user. It cannot be defaulted: a run with no user cannot be metered */
+ | "user_required"
+/** 401 missing, malformed, revoked, or another app's key */
+ | "unauthorized"
+/** 402 the plan is exhausted and its overage is `stop` */
+ | "payment_required"
+/** 403 asked for something this key may not have, e.g. a metered class on a dev key */
+ | "forbidden"
+/** 404 no such model or runtime alias */
+ | "not_found"
+/** 409 nothing this run is allowed to use is connected and awake */
+ | "no_compute"
+/** 429 back off; `retryAfterMs` says how long */
+ | "rate_limited"
+/** 5xx ours */
+ | "server_error"
+/** the request never reached a server */
+ | "connection"
+/** no response headers within `connectTimeoutMs` */
+ | "timeout"
+/** the stream ended without `done` or `error`: transport, not outcome */
+ | "stream_truncated"
+/** a delivered terminal `error` event, surfaced by `run.text()` */
+ | "run_failed"
+/** the caller aborted */
+ | "canceled" | "unknown";
+export interface SobaErrorInit {
+    message: string;
+    code: SobaErrorCode;
+    /** The server's own `error.type`, when it sent one. */
+    type?: string;
+    status?: number;
+    retryable?: boolean;
+    retryAfterMs?: number;
+    runId?: string;
+    cause?: unknown;
+}
+/**
+ * `retryable` is advice, not an instruction, and it is deliberately FALSE for
+ * `no_compute`. That failure clears when a laptop wakes up, so retrying it on a
+ * millisecond backoff inside the SDK would spin against a machine that is
+ * asleep. Minutes, not milliseconds, and the app owns that decision.
+ */
+export declare class SobaError extends Error {
+    readonly code: SobaErrorCode;
+    readonly type: string;
+    readonly status: number | undefined;
+    readonly retryable: boolean;
+    readonly retryAfterMs: number | undefined;
+    readonly runId: string | undefined;
+    constructor(init: SobaErrorInit);
+}
+export declare function codeForStatus(status: number): SobaErrorCode;
+/**
+ * Build an error from a failed response. The envelope is
+ * `{ error: { type, message, code } }` on every endpoint, but a proxy, a
+ * gateway timeout page or an HTML error can arrive here too, so nothing about
+ * the body is assumed.
+ */
+export declare function errorFromResponse(response: Response): Promise<SobaError>;
+/** RFC 7231 allows seconds or an HTTP date. Both appear in the wild. */
+export declare function retryAfterMs(header: string | null): number | undefined;
+/** Anything thrown by `fetch` or an abort, normalised. */
+export declare function asSobaError(err: unknown): SobaError;

package/dist/http.d.ts

@@ -0,0 +1,33 @@
+import { SobaError } from "./errors.js";
+export interface HttpConfig {
+    baseURL: string;
+    apiKey: string;
+    headers: Record<string, string>;
+    fetch: typeof globalThis.fetch;
+    /** Covers HEADERS ONLY. A run streams for minutes; a deadline that kept
+     *  running would kill the answer it was meant to protect. */
+    connectTimeoutMs: number;
+    maxRetries: number;
+}
+export interface RequestOptions {
+    method: "GET" | "POST" | "DELETE";
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    accept?: string;
+    signal?: AbortSignal;
+    /** Default true. Set false for anything that must happen at most once. */
+    retry?: boolean;
+}
+export declare function httpRequest(cfg: HttpConfig, opts: RequestOptions): Promise<Response>;
+export declare function requestJson<T>(cfg: HttpConfig, opts: RequestOptions): Promise<T>;
+export declare function buildUrl(baseURL: string, path: string, query?: Record<string, string | number | boolean | undefined>): string;
+/**
+ * Exponential backoff with jitter, and `Retry-After` wins when the server sent
+ * one. The jitter is not decoration: a fleet of servers retrying a rate limit
+ * in lockstep re-creates the burst that caused it.
+ */
+export declare function backoffMs(attempt: number, last: SobaError | undefined): number;
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/** Forward one signal's abort onto a controller, and stop forwarding on demand. */
+export declare function chain(parent: AbortSignal | undefined, child: AbortController): () => void;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { DEFAULT_BASE_URL, type RunParams, Soba, type SobaOptions } from "./client.js";
+export { SobaError, type SobaErrorCode } from "./errors.js";
+export { type AgentEvent, type AgentEventType, type CostClass, isCostClass, isMetered, isTerminal, METERED_CLASSES, type Message, type PermissionMode, type RouteRequest, type RunPolicy, type RunUsage, TOOL_SLUGS, type ToolSchema, type ToolSlug, } from "./protocol.js";
+export type { Allowance, ConnectedMachine, MachineRuntime, PlanSummary, SobaUser, UsagePage, UsageQuery, UsageRow, } from "./resources.js";
+export { type ApprovalDecision, type ApprovalRequest, type Approver, Run, } from "./run.js";
+export { type ToolContext, type ToolDefinition, tool } from "./tools.js";
+export { VERSION } from "./version.js";

package/dist/index.mjs

@@ -0,0 +1,4 @@
+var s=class extends Error{code;type;status;retryable;retryAfterMs;runId;constructor(e){super(e.message,e.cause===void 0?void 0:{cause:e.cause}),this.name="SobaError",this.code=e.code,this.type=e.type??e.code,this.status=e.status,this.retryable=e.retryable??F.has(e.code),this.retryAfterMs=e.retryAfterMs,this.runId=e.runId}},F=new Set(["rate_limited","server_error","connection","timeout","stream_truncated"]),j={400:"invalid_request",401:"unauthorized",402:"payment_required",403:"forbidden",404:"not_found",409:"no_compute",422:"user_required",429:"rate_limited"};function W(t){let e=j[t];return e||(t>=500?"server_error":t>=400?"invalid_request":"unknown")}async function k(t){let e=t.status,n="";try{n=await t.text()}catch{}let r=B(n);return new s({code:r?.code??W(e),type:r?.type,message:r?.message??G(e,t.statusText,n),status:e,retryAfterMs:J(t.headers.get("retry-after")),runId:t.headers.get("soba-run-id")??void 0})}function B(t){if(!t)return null;let e;try{e=JSON.parse(t)}catch{return null}if(!e||typeof e!="object")return null;let n=e.error;if(!n||typeof n!="object")return null;let r=n;return{message:typeof r.message=="string"&&r.message?r.message:void 0,type:typeof r.type=="string"&&r.type?r.type:void 0,code:K.has(r.code)?r.code:void 0}}var K=new Set(["invalid_request","user_required","unauthorized","payment_required","forbidden","not_found","no_compute","rate_limited","server_error","connection","timeout","stream_truncated","run_failed","canceled","unknown"]);function G(t,e,n){let r=n.trim().slice(0,200),o=r?`: ${r}`:"";return`Soba returned ${t}${e?` ${e}`:""}${o}`}function J(t){if(!t)return;let e=Number(t);if(Number.isFinite(e)&&e>=0)return Math.round(e*1e3);let n=Date.parse(t);if(!Number.isNaN(n))return Math.max(0,n-Date.now())}function f(t){if(t instanceof s)return t;let e=t;return e?.name==="AbortError"||e?.name==="TimeoutError"?new s({code:"canceled",message:e.message||"The request was aborted.",retryable:!1,cause:t}):new s({code:"connection",message:e?.message?`Could not reach Soba: ${e.message}`:"Could not reach Soba.",cause:t})}var w="0.0.5";var H=8e3,Y=3e4;async function g(t,e){let n=Q(t.baseURL,e.path,e.query),r=e.retry===!1?1:Math.max(0,t.maxRetries)+1,o;for(let i=0;i<r;i++){i>0&&await Z(X(i,o),e.signal);let a=new AbortController,c=S(e.signal,a),m=setTimeout(()=>{a.abort(new s({code:"timeout",message:`Soba did not answer within ${t.connectTimeoutMs}ms.`}))},t.connectTimeoutMs),d;try{d=await t.fetch(n,{method:e.method,headers:z(t,e),body:e.body===void 0?void 0:JSON.stringify(e.body),signal:a.signal})}catch(l){if(c(),o=f(a.signal.aborted?a.signal.reason??l:l),!o.retryable||i===r-1)throw o;continue}finally{clearTimeout(m)}if(d.ok)return d;if(c(),o=await k(d),!o.retryable||i===r-1)throw o}throw o??new s({code:"unknown",message:"The request failed with no error."})}async function C(t,e){let n=await g(t,{accept:"application/json",...e}),r=await n.text();if(r)try{return JSON.parse(r)}catch(o){throw new s({code:"server_error",message:`Soba returned a body that is not JSON: ${r.slice(0,200)}`,status:n.status,cause:o})}}function z(t,e){let n={authorization:`Bearer ${t.apiKey}`,accept:e.accept??"application/json","user-agent":V(),...t.headers};return e.body!==void 0&&(n["content-type"]="application/json"),n}function V(){let t=typeof process>"u"?"":` node/${process.versions?.node??"?"}`;return`soba-sdk/${w}${t}`}function Q(t,e,n){let r=t.replace(/\/+$/,""),o=new URL(`${r}${e.startsWith("/")?e:`/${e}`}`);for(let[i,a]of Object.entries(n??{}))a!==void 0&&o.searchParams.set(i,String(a));return o.toString()}function X(t,e){if(e?.retryAfterMs!==void 0)return Math.min(e.retryAfterMs,Y);let n=Math.min(H,500*2**(t-1));return Math.round(n*(.5+Math.random()/2))}function Z(t,e){return new Promise((n,r)=>{if(e?.aborted)return r(f(e.reason));let o=setTimeout(()=>{e?.removeEventListener("abort",i),n()},t);function i(){clearTimeout(o),r(f(e?.reason))}e?.addEventListener("abort",i,{once:!0})})}function S(t,e){if(!t)return()=>{};if(t.aborted)return e.abort(t.reason),()=>{};let n=()=>e.abort(t.reason);return t.addEventListener("abort",n,{once:!0}),()=>t.removeEventListener("abort",n)}var _=["open-weights","frontier"];function ee(t){return _.includes(t)}function te(t){return t==="user-hardware"||t==="user-subscription"||t==="open-weights"||t==="frontier"}function T(t){return t.type==="done"||t.type==="error"}var ne=["search","fetch","read","write","edit","bash","files","agent","todo","think","sources","tool"];var U=new Set(["delta","thinking","status","done","error"]);function v(t){let e;try{e=JSON.parse(t)}catch{return null}if(!e||typeof e!="object"||Array.isArray(e))return null;let n=e,r=u(n.runId);if(typeof n.type=="string"&&U.has(n.type)){let o=I(n);return o?{kind:"event",runId:r,event:o}:null}switch(n.type){case"event":{if(!n.event||typeof n.event!="object")return null;let o=I(n.event);return o?{kind:"event",runId:r,event:o}:null}case"usage":{let o=P(n.usage);return o?{kind:"usage",runId:r,usage:o}:null}case"tool_call":{let o=u(n.callId),i=u(n.name);return!o||!i?null:{kind:"tool_call",runId:r,callId:o,name:i,input:n.input}}case"approval_request":{let o=u(n.approvalId),i=u(n.tool);return!o||!i?null:{kind:"approval",runId:r,approvalId:o,tool:i,input:n.input,cwd:u(n.cwd)}}default:return null}}function I(t){let e=typeof t.type=="string"&&U.has(t.type)?t.type:null;if(!e)return null;let n={type:e},r=u(t.text);r!==void 0&&(n.text=r);let o=u(t.message);o!==void 0&&(n.message=o);let i=u(t.tool);i!==void 0&&(n.tool=i);let a=u(t.tier);a!==void 0&&(n.tier=a);let c=P(t.usage);return c&&(n.usage=c),n}function P(t){if(!t||typeof t!="object")return null;let e=t,n={model:u(e.model)??"unknown",inputTokens:y(e.inputTokens),outputTokens:y(e.outputTokens),cacheReadTokens:y(e.cacheReadTokens),cacheWriteTokens:y(e.cacheWriteTokens),webSearches:y(e.webSearches)},r=u(e.costClass);r!==void 0&&(n.costClass=r);let o=u(e.provider);return o!==void 0&&(n.provider=o),typeof e.costMicros=="number"&&Number.isFinite(e.costMicros)&&(n.costMicros=e.costMicros),n}function u(t){return typeof t=="string"&&t.length>0?t:void 0}function y(t){return typeof t=="number"&&Number.isFinite(t)?t:0}async function*O(t){let e=t.body;if(!e)throw new s({code:"connection",message:"The run response arrived with no body to stream.",status:t.status});let n=t.headers.get("content-type")??"",r=n.includes("ndjson")||n.includes("jsonlines"),o=e.getReader(),i=new TextDecoder,a="",c=[];try{for(;;){let d=await o.read();if(d.done)break;for(a+=i.decode(d.value,{stream:!0});;){let l=a.indexOf(`
+`);if(l===-1)break;let b=q(a.slice(0,l));if(a=a.slice(l+1),r){let p=b.trim()?v(b):null;p&&(yield p);continue}if(b===""){let p=c.join(`
+`);if(c=[],p==="[DONE]")return;let A=p?v(p):null;A&&(yield A);continue}M(b,c)}}!r&&a&&M(q(a),c);let m=r?a.trim():c.join(`
+`);if(m&&m!=="[DONE]"){let d=v(m);d&&(yield d)}}finally{o.cancel().catch(()=>{})}}function M(t,e){if(t.startsWith(":"))return;let n=t.indexOf(":");if(n===-1||t.slice(0,n)!=="data")return;let r=t.slice(n+1);e.push(r.startsWith(" ")?r.slice(1):r)}function q(t){return t.endsWith("\r")?t.slice(0,-1):t}function re(t){return t}function D(t){let e=new Map;for(let n of t??[]){if(!n?.name)throw new s({code:"invalid_request",message:"Every tool needs a name."});if(typeof n.execute!="function")throw new s({code:"invalid_request",message:`Tool "${n.name}" has no execute function. A tool Soba cannot call is not a tool.`});if(e.has(n.name))throw new s({code:"invalid_request",message:`Two tools are named "${n.name}". Tool names must be unique within a run.`});e.set(n.name,n)}return e}function L(t){return[...t.values()].map(e=>({name:e.name,description:e.description??"",inputSchema:e.inputSchema??{type:"object"}}))}function N(t){if(t===void 0)return null;if(typeof t=="string")return t;try{return JSON.parse(JSON.stringify(t))}catch{return String(t)}}function R(t){return t instanceof Error?t.message||t.name:typeof t=="string"?t:String(t)}var h=class{#e;#n;#r;#a=!1;#t;#o=new AbortController;#s=new AbortController;#i=new Set;#u;constructor(e){this.#t=e,this.#e=e.response.headers.get("soba-run-id")??"",this.#u=S(e.signal,this.#o)}get runId(){return this.#e}get tier(){return this.#n}get usage(){return this.#r}[Symbol.asyncIterator](){return this.#d()}async text(){let e="";for await(let n of this)if(n.type==="delta"&&n.text&&(e+=n.text),n.type==="error")throw new s({code:"run_failed",message:n.message??"The run ended with an error.",runId:this.#e,retryable:!1});return e}async cancel(){if(this.#o.abort(new s({code:"canceled",message:"The run was cancelled."})),this.#s.abort(new s({code:"canceled",message:"The run was cancelled."})),!!this.#e)try{await g(this.#t.config,{method:"POST",path:`/runs/${encodeURIComponent(this.#e)}/cancel`,retry:!1})}catch(e){this.#t.onWarning("Could not tell Soba the run was cancelled.",e)}}async*#d(){if(this.#a)throw new s({code:"invalid_request",message:"This run has already been consumed. A run's events can only be read once.",runId:this.#e});this.#a=!0;let e=!1;try{for await(let n of O(this.#t.response)){if(n.runId&&!this.#e&&(this.#e=n.runId),n.kind==="event"){let r=n.event;if(r.tier&&(this.#n=r.tier),r.usage&&(this.#r=r.usage),e=T(r),yield r,e)return;continue}if(n.kind==="usage"){this.#r=n.usage;continue}this.#l(this.#p(n))}throw new s({code:"stream_truncated",message:"The run stream ended without a `done` or `error` event.",runId:this.#e})}finally{e||this.#s.abort(new s({code:"canceled",message:"The run ended before this tool finished."})),await Promise.allSettled([...this.#i]),this.#o.abort(),this.#u()}}#l(e){this.#i.add(e),e.finally(()=>this.#i.delete(e)).catch(()=>{})}async#p(e){if(e.kind==="tool_call")return this.#f(e);if(e.kind==="approval")return this.#g(e)}async#f(e){let n=this.#t.tools.get(e.name),r,o=!1;if(!n)r=`No tool named "${e.name}" is registered by this app.`,o=!0;else{let i={runId:this.#e,user:this.#t.user,callId:e.callId,signal:this.#s.signal};try{r=await n.execute(e.input,i)}catch(a){r=R(a),o=!0}}await this.#c(`/runs/${encodeURIComponent(this.#e)}/tool_result`,{callId:e.callId,result:N(r),isError:o})}async#g(e){let n="deny",r;if(!this.#t.approve)r="This app did not supply an approver, so escalations are denied.";else try{let o={runId:this.#e,approvalId:e.approvalId,tool:e.tool,input:e.input};e.cwd&&(o.cwd=e.cwd),n=await this.#t.approve(o)==="allow"?"allow":"deny"}catch(o){r=R(o)}await this.#c(`/runs/${encodeURIComponent(this.#e)}/approval`,{approvalId:e.approvalId,decision:n,...r?{reason:r}:{}})}async#c(e,n){if(!this.#e){this.#t.onWarning("Soba sent a frame before the run had an id, so it could not be answered.",n);return}try{await(await g(this.#t.config,{method:"POST",path:e,body:n})).text()}catch(r){this.#t.onWarning(`Could not deliver an answer to ${e}.`,f(r))}}};var $="https://api.soba.so/v1",oe=3e4,se=2,x=class{#e;#n;users;usage;plans;constructor(e={}){let n=e.apiKey??E("SOBA_KEY")??E("SOBA_API_KEY");if(!n)throw new s({code:"unauthorized",message:"No Soba API key. Pass `apiKey`, or set SOBA_KEY. Keys are shaped sk_soba_<id>.<secret> and come from your dashboard."});if(ie()&&!e.dangerouslyAllowBrowser)throw new s({code:"invalid_request",message:"A Soba app key is a server credential and this looks like a browser. Call Soba from your server, or pass dangerouslyAllowBrowser if you are certain."});if(this.#n=e.onWarning??(()=>{}),this.#e={apiKey:n,baseURL:e.baseURL??E("SOBA_BASE_URL")??$,headers:e.headers??{},fetch:e.fetch??globalThis.fetch,connectTimeoutMs:e.connectTimeoutMs??oe,maxRetries:e.maxRetries??se},typeof this.#e.fetch!="function")throw new s({code:"invalid_request",message:"No global fetch. Run on Node 22 or newer, or pass your own `fetch`."});this.users={get:r=>this.request("GET",`/users/${encodeURIComponent(r)}`),compute:r=>this.request("GET",`/users/${encodeURIComponent(r)}/compute`)},this.usage={list:r=>this.request("GET","/usage",{query:{...r}})},this.plans={list:()=>this.request("GET","/plans")}}get baseURL(){return this.#e.baseURL}async run(e){if(!e.user)throw new s({code:"user_required",status:422,message:"`user` is required. A run with no user cannot be attributed or metered, so it cannot be defaulted."});if(!e.prompt&&!e.messages?.length)throw new s({code:"invalid_request",status:400,message:"A run needs a `prompt` or a non-empty `messages`."});let n=D(e.tools),r={user:e.user,model:e.model??"auto"};e.prompt&&(r.prompt=e.prompt),e.messages?.length&&(r.messages=e.messages),e.system&&(r.system=e.system),e.runtime&&(r.runtime=e.runtime),n.size&&(r.tools=L(n)),e.route&&(r.route=e.route),e.policy&&(r.policy=e.policy),e.metadata&&(r.metadata=e.metadata);let o=await g(this.#e,{method:"POST",path:"/runs",body:r,accept:"text/event-stream",signal:e.signal});return new h({config:this.#e,response:o,user:e.user,tools:n,approve:e.approve,onWarning:this.#n,signal:e.signal})}async request(e,n,r={}){return C(this.#e,{method:e,path:n,...r})}};function E(t){if(typeof process>"u")return;let e=process.env?.[t];return e||void 0}function ie(){let t=globalThis;return typeof t.window=="object"&&typeof t.window?.document=="object"}export{$ as DEFAULT_BASE_URL,_ as METERED_CLASSES,h as Run,x as Soba,s as SobaError,ne as TOOL_SLUGS,w as VERSION,te as isCostClass,ee as isMetered,T as isTerminal,re as tool};

package/dist/protocol.d.ts

@@ -0,0 +1,94 @@
+/**
+ * WHO PAYS for a run.
+ *
+ *   user-hardware      the user's own silicon. Free to everyone
+ *   user-subscription  a plan the user already pays for. Free to the broker
+ *   open-weights       an open model on GPU bought wholesale. METERED
+ *   frontier           a frontier provider API. METERED
+ */
+export type CostClass = "user-hardware" | "user-subscription" | "open-weights" | "frontier";
+/** The classes somebody has to be billed for. The user-* classes are already paid. */
+export declare const METERED_CLASSES: readonly ["open-weights", "frontier"];
+export declare function isMetered(c: CostClass): boolean;
+export declare function isCostClass(v: unknown): v is CostClass;
+/** Token and tool usage from a completed run: what a meter bills against. */
+export interface RunUsage {
+    /** Which economics served this run. Present so a usage frame is self-describing. */
+    costClass?: CostClass;
+    /** What it cost, in micros, for the metered classes. Absent when nothing is owed. */
+    costMicros?: number;
+    /** Provider-neutral model alias, e.g. "sonnet", "gpt-5-codex". */
+    model: string;
+    /** Which provider actually served it, since aliases collide. */
+    provider?: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    webSearches: number;
+}
+/** FROZEN. New information arrives as optional fields on these, never as a new type. */
+export type AgentEventType = "delta" | "thinking" | "status" | "done" | "error";
+export interface AgentEvent {
+    type: AgentEventType;
+    /** `delta`: the NEW text, append it. `thinking`: the RUNNING TOTAL, replace it. */
+    text?: string;
+    /** `status` / `error`: human-readable copy, safe to show a user. */
+    message?: string;
+    /** On a `status` raised by a tool: a stable slug the UI maps to an icon. */
+    tool?: string;
+    /** On `done`: what the run consumed. Absent when the runtime cannot report it. */
+    usage?: RunUsage;
+    /** Which economics is serving this run, announced on the opening `status`,
+     *  BEFORE any output. A visible downgrade beats a silent one. */
+    tier?: CostClass;
+}
+export declare function isTerminal(e: AgentEvent): boolean;
+/** Stable tool slugs. Adapters map their runtime's native names onto these. */
+export declare const TOOL_SLUGS: readonly ["search", "fetch", "read", "write", "edit", "bash", "files", "agent", "todo", "think", "sources", "tool"];
+export type ToolSlug = (typeof TOOL_SLUGS)[number];
+/** One turn of a conversation. `prompt` is shorthand for a single user message. */
+export interface Message {
+    role: "user" | "assistant";
+    content: string;
+}
+/** An app-defined tool as it travels on the wire: schema only, no implementation. */
+export interface ToolSchema {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's input. */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * - "ask"  escalations round-trip to an approver (see `askTools`)
+ * - "deny" anything outside the allowlist fails the call, the run continues
+ * - "auto" the runtime proceeds within the resolved allowlist, no prompting
+ */
+export type PermissionMode = "ask" | "deny" | "auto";
+/**
+ * What a run REQUESTS. Never a grant: the machine's owner has their own policy
+ * and the worker resolves the two by intersection, so this can only ever narrow
+ * what the machine already allows.
+ */
+export interface RunPolicy {
+    cwd?: string;
+    allowTools?: string[];
+    denyTools?: string[];
+    askTools?: string[];
+    timeoutMs?: number;
+    permissionMode?: PermissionMode;
+    allowNetwork?: string[];
+}
+/**
+ * WHICH ECONOMICS a run may use. You declare intent, not a runtime, which is
+ * what lets one call site back a free-forever app and an enterprise app.
+ */
+export interface RouteRequest {
+    /** Ordered preference. The first reachable class wins. */
+    prefer: CostClass[];
+    /** Classes usable at all. Omitted = anything the broker can reach.
+     *  A HARD CEILING, enforced on the worker as well as the broker. */
+    allow?: CostClass[];
+    /** Ceiling on what one run may cost, in micros. Metered classes only. */
+    maxCostMicros?: number;
+}

package/dist/resources.d.ts

@@ -0,0 +1,85 @@
+import type { CostClass } from "./protocol.js";
+export interface PlanSummary {
+    id: string;
+    name: string;
+    priceMicros?: number;
+    interval?: "month" | "year" | string;
+    /** What a user earns for connecting their own compute, as a credit. */
+    connectedRewardMicros?: number;
+    /** What happens past the allowance. */
+    overage?: "stop" | "meter" | string;
+}
+export interface Allowance {
+    includedMicros?: number;
+    usedMicros?: number;
+    /** Credit earned by connecting compute, spent before money. */
+    earnedMicros?: number;
+    periodStart?: string;
+    periodEnd?: string;
+}
+/** `GET /v1/users/:id` — what this user has. */
+export interface SobaUser {
+    id: string;
+    email?: string | null;
+    plan?: PlanSummary | null;
+    allowance?: Allowance | null;
+    /** Whether anything of theirs can serve a run right now. */
+    connected?: boolean;
+    machines?: number;
+    createdAt?: string;
+}
+export interface MachineRuntime {
+    id: string;
+    displayName: string;
+    version?: string | null;
+    models?: string[];
+    costClass: CostClass;
+    supportsTools?: boolean;
+    /** TRI-STATE. `null` means the worker could not tell, which is not `false`. */
+    authenticated?: boolean | null;
+    authHint?: string | null;
+}
+/** `GET /v1/users/:id/compute` — one connected machine and its live state. */
+export interface ConnectedMachine {
+    id: string;
+    label?: string | null;
+    platform?: string | null;
+    arch?: string | null;
+    state: "online" | "offline" | "busy" | string;
+    alwaysOn?: boolean;
+    active?: number;
+    capacity?: number;
+    lastSeenAt?: string | null;
+    runtimes: MachineRuntime[];
+}
+/** `GET /v1/usage` — one row, self-describing about who paid for it. */
+export interface UsageRow {
+    runId: string;
+    user: string;
+    createdAt: string;
+    model: string;
+    provider?: string | null;
+    costClass: CostClass;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    webSearches: number;
+    costMicros: number;
+    /** What this run saved: zero on a metered run, the counterfactual otherwise. */
+    avoidedCostMicros: number;
+    environment?: string | null;
+}
+export interface UsageQuery {
+    user?: string;
+    /** ISO 8601. */
+    from?: string;
+    to?: string;
+    environment?: "development" | "preview" | "production" | string;
+    limit?: number;
+    cursor?: string;
+}
+export interface UsagePage {
+    data: UsageRow[];
+    nextCursor?: string | null;
+}

package/dist/run.d.ts

@@ -0,0 +1,54 @@
+import { type HttpConfig } from "./http.js";
+import { type AgentEvent, type CostClass, type RunUsage } from "./protocol.js";
+import { type ToolDefinition } from "./tools.js";
+export type ApprovalDecision = "allow" | "deny";
+export interface ApprovalRequest {
+    runId: string;
+    approvalId: string;
+    /** The tool the model wants to use. */
+    tool: string;
+    input: unknown;
+    /** The directory the run is working in, when the runtime reports one. */
+    cwd?: string;
+}
+export type Approver = (request: ApprovalRequest) => ApprovalDecision | Promise<ApprovalDecision>;
+export interface RunInit {
+    config: HttpConfig;
+    response: Response;
+    user: string;
+    tools: Map<string, ToolDefinition>;
+    approve: Approver | undefined;
+    onWarning: (message: string, detail?: unknown) => void;
+    signal: AbortSignal | undefined;
+}
+/**
+ * A run in flight.
+ *
+ * `await soba.run()` resolves as soon as the response headers arrive, which is
+ * the boundary docs/errors.md draws: a failure before the first byte is an HTTP
+ * status you catch, and a failure after it is a terminal `error` event you read.
+ *
+ * Iterate it once. Tool calls and approvals are answered underneath the
+ * iteration, so a consumer that only cares about text never has to know they
+ * happened.
+ */
+export declare class Run implements AsyncIterable<AgentEvent> {
+    #private;
+    constructor(init: RunInit);
+    /** Empty only until the first frame, if the server omitted the header. */
+    get runId(): string;
+    /** Which economics served this run, from the opening `status`. */
+    get tier(): CostClass | undefined;
+    /** What the run consumed. Absent until `done`, and absent after it when the
+     *  runtime could not report it, which is exactly when the run was free. */
+    get usage(): RunUsage | undefined;
+    [Symbol.asyncIterator](): AsyncIterator<AgentEvent>;
+    /** Drain the run and return the assembled text. Throws on a terminal error. */
+    text(): Promise<string>;
+    /**
+     * Stop the run. Best effort by design: the local stream is dropped
+     * immediately, and the broker is told so the machine stops working, but a
+     * subprocess that has already produced tokens has already produced them.
+     */
+    cancel(): Promise<void>;
+}

package/dist/stream.d.ts

@@ -0,0 +1,31 @@
+import type { AgentEvent, RunUsage } from "./protocol.js";
+export type StreamFrame = {
+    kind: "event";
+    runId?: string;
+    event: AgentEvent;
+} | {
+    kind: "usage";
+    runId?: string;
+    usage: RunUsage;
+} | {
+    kind: "tool_call";
+    runId?: string;
+    callId: string;
+    name: string;
+    input: unknown;
+} | {
+    kind: "approval";
+    runId?: string;
+    approvalId: string;
+    tool: string;
+    input: unknown;
+    cwd?: string;
+};
+export declare function parseStreamFrame(raw: string): StreamFrame | null;
+/**
+ * Yield frames off a live response body.
+ *
+ * SSE by default; newline-delimited JSON when the server says so, which is what
+ * a hand-rolled test server is likely to send.
+ */
+export declare function readFrames(response: Response): AsyncGenerator<StreamFrame>;

package/dist/tools.d.ts

@@ -0,0 +1,42 @@
+import type { ToolSchema } from "./protocol.js";
+export interface ToolContext {
+    /** The run that asked. */
+    runId: string;
+    /** The end user the run is attributed to. */
+    user: string;
+    /** This specific call, which the result is keyed to. */
+    callId: string;
+    /** Aborted when the run ends or the caller cancels. Honour it in long tools. */
+    signal: AbortSignal;
+}
+export interface ToolDefinition<Input = Record<string, unknown>> {
+    name: string;
+    /** What the tool does, in the model's words. This is prompt, not documentation. */
+    description?: string;
+    /** JSON Schema for the input. Omitted means an object with no declared fields. */
+    inputSchema?: Record<string, unknown>;
+    /**
+     * Your code. Return anything JSON-serialisable; a string is passed through
+     * verbatim. Throwing is not a run failure: the error is handed to the model
+     * as a failed call, which it can see and work around.
+     */
+    execute(input: Input, ctx: ToolContext): unknown | Promise<unknown>;
+}
+/** Identity, for the type inference. `tool({...})` reads better than a cast. */
+export declare function tool<Input = Record<string, unknown>>(def: ToolDefinition<Input>): ToolDefinition<Input>;
+/**
+ * Index the tools by name, refusing a duplicate rather than letting the second
+ * one win silently. Two tools with one name is a bug the model surfaces as
+ * baffling behaviour hours later.
+ */
+export declare function indexTools(tools: readonly ToolDefinition[] | undefined): Map<string, ToolDefinition>;
+/** What goes on the wire: schema only. `execute` is stripped here, not by luck. */
+export declare function toolSchemas(byName: Map<string, ToolDefinition>): ToolSchema[];
+/**
+ * Make a tool's return value safe to put in a JSON body. A value that cannot
+ * be serialised (a BigInt, a cycle, a class instance with a throwing getter)
+ * becomes its string form rather than an exception that would strand the run
+ * waiting for a result that never arrives.
+ */
+export declare function jsonSafe(value: unknown): unknown;
+export declare function errorText(err: unknown): string;

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.0.5";

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@soba-so/sdk",
+  "version": "0.0.5",
+  "description": "One request that comes back finished, executed on compute the end user owns.",
+  "license": "UNLICENSED",
+  "homepage": "https://soba.so/docs/runs",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/build-sdk.mjs",
+    "prepublishOnly": "node ../../scripts/build-sdk.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "soba",
+    "agent",
+    "claude",
+    "codex",
+    "runs",
+    "byoc"
+  ],
+  "devDependencies": {
+    "@soba-so/protocol": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}