@hostler/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ankit Gupta
+
+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

@@ -0,0 +1,45 @@
+# @hostler/sdk
+
+TypeScript SDK for the [Hostler](https://hostler.dev) API: managed agents,
+sessions, live event streams, and client-tool execution.
+
+Full documentation: **https://hostler.dev/docs/sdk**
+
+```ts
+import { Hostler } from "@hostler/sdk";
+
+const hostler = new Hostler({ apiKey: process.env.HOSTLER_KEY! });
+
+const agent = await hostler.agents.create({
+  name: "inventory-assistant",
+  harness: "pi",
+  model: { provider: "anthropic", id: "claude-haiku-4-5" },
+  system: "You are a warehouse assistant. Use get_inventory for stock questions.",
+  clientTools: [
+    {
+      name: "get_inventory",
+      description: "Look up current warehouse stock for an item.",
+      inputSchema: { type: "object", properties: { item: { type: "string" } }, required: ["item"] },
+    },
+  ],
+});
+
+const session = await hostler.sessions.create({ agentId: agent.id });
+
+// One call: sends the message, streams events, executes your client tools
+// when the agent asks for them, resolves when the turn completes.
+const { text } = await session.run("How many widgets are in stock?", {
+  tools: {
+    get_inventory: async (input) => ({ item: input, count: 42 }),
+  },
+});
+console.log(text);
+
+await session.terminate();
+```
+
+Lower-level surface: `session.send()`, `session.stream()` (SSE with automatic
+reconnect and replay), `session.submitToolResult()`, `session.confirmTool()`,
+`session.outputFiles()`.
+
+Requires Node 18+ (or any runtime with `fetch`). Zero dependencies.

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+/** The Hostler client: `new Hostler({ apiKey })` and the resource surfaces. */
+import { Transport } from "./transport.ts";
+import { Session } from "./session.ts";
+import type { Agent, AgentConfig, CreateSessionOptions, SessionInfo } from "./types.ts";
+export interface HostlerOptions {
+    /**
+     * A team API key (`cpk_...`) minted in the console's Settings page.
+     * Typed to accept `process.env.X` directly; a missing value throws at
+     * construction rather than on the first request.
+     */
+    apiKey: string | undefined;
+    /** API origin. Defaults to https://hostler.dev; self-hosted deployments pass their own. */
+    baseUrl?: string;
+    /** Custom fetch implementation (tests, instrumentation). Defaults to the global. */
+    fetch?: typeof fetch;
+}
+export declare const DEFAULT_BASE_URL = "https://hostler.dev";
+export declare class Hostler {
+    readonly agents: AgentsResource;
+    readonly sessions: SessionsResource;
+    constructor(options: HostlerOptions);
+}
+export declare class AgentsResource {
+    #private;
+    constructor(transport: Transport);
+    /** Register an agent (version 1). */
+    create(config: AgentConfig): Promise<Agent>;
+    list(): Promise<Agent[]>;
+    /** Latest version, or a specific one via `version`. */
+    get(id: string, options?: {
+        version?: number;
+    }): Promise<Agent>;
+    /** Append a new immutable version (existing sessions keep the one they pinned). */
+    createVersion(id: string, config: AgentConfig): Promise<Agent>;
+}
+export declare class SessionsResource {
+    #private;
+    constructor(transport: Transport);
+    /** Launch a sandbox running the agent and return a handle to drive it. */
+    create(options: CreateSessionOptions): Promise<Session>;
+    list(): Promise<SessionInfo[]>;
+    /** Handle to an existing session (verifies it exists; 404 throws). */
+    get(id: string): Promise<Session>;
+}

package/dist/client.js

@@ -0,0 +1,64 @@
+/** The Hostler client: `new Hostler({ apiKey })` and the resource surfaces. */
+import { Transport } from "./transport.js";
+import { Session } from "./session.js";
+export const DEFAULT_BASE_URL = "https://hostler.dev";
+export class Hostler {
+    agents;
+    sessions;
+    constructor(options) {
+        const apiKey = options.apiKey;
+        if (apiKey === undefined || apiKey === "")
+            throw new Error("Hostler: apiKey is required");
+        const transport = new Transport({
+            apiKey,
+            baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+            fetch: options.fetch ?? ((...args) => fetch(...args)),
+        });
+        this.agents = new AgentsResource(transport);
+        this.sessions = new SessionsResource(transport);
+    }
+}
+export class AgentsResource {
+    #transport;
+    constructor(transport) {
+        this.#transport = transport;
+    }
+    /** Register an agent (version 1). */
+    create(config) {
+        return this.#transport.request("POST", "/v1/agents", config);
+    }
+    async list() {
+        const body = await this.#transport.request("GET", "/v1/agents");
+        return body.agents;
+    }
+    /** Latest version, or a specific one via `version`. */
+    get(id, options = {}) {
+        const query = options.version !== undefined ? `?version=${options.version}` : "";
+        return this.#transport.request("GET", `/v1/agents/${id}${query}`);
+    }
+    /** Append a new immutable version (existing sessions keep the one they pinned). */
+    createVersion(id, config) {
+        return this.#transport.request("POST", `/v1/agents/${id}/versions`, config);
+    }
+}
+export class SessionsResource {
+    #transport;
+    constructor(transport) {
+        this.#transport = transport;
+    }
+    /** Launch a sandbox running the agent and return a handle to drive it. */
+    async create(options) {
+        const row = await this.#transport.request("POST", "/v1/sessions", options);
+        return new Session(this.#transport, row.id);
+    }
+    list() {
+        return this.#transport
+            .request("GET", "/v1/sessions")
+            .then((body) => body.sessions);
+    }
+    /** Handle to an existing session (verifies it exists; 404 throws). */
+    async get(id) {
+        await this.#transport.request("GET", `/v1/sessions/${id}`);
+        return new Session(this.#transport, id);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Hostler, AgentsResource, SessionsResource, DEFAULT_BASE_URL, type HostlerOptions } from "./client.ts";
+export { Session, type ConfirmDecision, type RunOptions, type RunResult, type StreamOptions, type ToolHandler, } from "./session.ts";
+export { HostlerError } from "./transport.ts";
+export type { Agent, AgentConfig, ClientToolDefinition, CreateSessionOptions, ModelConfig, OutputFile, SessionEvent, SessionInfo, SessionResourceMount, SessionStatus, StopReason, ToolConfirmation, ToolResult, ToolResultContent, } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Hostler, AgentsResource, SessionsResource, DEFAULT_BASE_URL } from "./client.js";
+export { Session, } from "./session.js";
+export { HostlerError } from "./transport.js";

package/dist/session.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The session handle: send messages, stream the event log, answer client
+ * tools, and drive whole turns with `run()`.
+ */
+import { type Transport } from "./transport.ts";
+import type { OutputFile, SessionEvent, SessionInfo, StopReason, ToolConfirmation, ToolResult } from "./types.ts";
+export interface StreamOptions {
+    /** Replay events with seq greater than this, then go live. Defaults to 0 (full history). */
+    since?: number;
+    /** Ends the stream (the generator returns cleanly) when aborted. */
+    signal?: AbortSignal;
+}
+/**
+ * Executes one client-tool call in your process. Return a string (used
+ * verbatim) or any JSON-serializable value (stringified). Throwing produces
+ * an error tool-result; the thrown message is shown to the model verbatim.
+ */
+export type ToolHandler = (input: unknown, call: {
+    toolCallId: string;
+    name: string;
+}) => unknown;
+export type ConfirmDecision = "allow" | "deny" | {
+    result: "allow" | "deny";
+    denyMessage?: string;
+};
+export interface RunOptions {
+    /**
+     * Handlers for the agent's client tools, keyed by tool name. Every parked
+     * client-tool call is answered from this map; a call with no handler gets
+     * an error result so the turn can complete. Use `stream()` instead if you
+     * want to observe without answering.
+     */
+    tools?: Record<string, ToolHandler>;
+    /**
+     * Decides approval-gated (`always_ask`) tool calls. When omitted, such
+     * calls stay parked — e.g. for an operator to approve in the console — and
+     * the run waits for that decision.
+     */
+    onConfirm?: (call: {
+        toolCallId: string;
+        name: string;
+        input: unknown;
+    }) => ConfirmDecision | Promise<ConfirmDecision>;
+    /** Observe every event as the run streams it. */
+    onEvent?: (event: SessionEvent) => void;
+    /** Aborting throws HostlerError("run aborted") from run(). */
+    signal?: AbortSignal;
+}
+export interface RunResult {
+    /** The agent's final message this turn, or null if it produced none. */
+    text: string | null;
+    stopReason: StopReason;
+}
+export declare class Session {
+    #private;
+    readonly id: string;
+    constructor(transport: Transport, id: string);
+    info(): Promise<SessionInfo>;
+    /** Queue a user message; the turn runs asynchronously (watch `stream()`). */
+    send(text: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Abort the current turn; the session settles to idle. */
+    interrupt(): Promise<void>;
+    /** Tear down the sandbox. Output files are captured first and stay downloadable. */
+    terminate(): Promise<SessionInfo>;
+    /** One-shot JSON read of the event log (no streaming). */
+    events(options?: {
+        since?: number;
+    }): Promise<SessionEvent[]>;
+    /** Answer a parked client-tool call. Exactly one of content/error. */
+    submitToolResult(result: ToolResult, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Allow or deny an approval-gated tool call. */
+    confirmTool(confirmation: ToolConfirmation, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    outputFiles(): Promise<OutputFile[]>;
+    readOutputFile(path: string): Promise<Uint8Array>;
+    /**
+     * Live event stream: replays history past `since`, then follows the session
+     * until it terminates. Reconnects automatically (resuming from the last
+     * seen seq) when the connection drops; HTTP errors (401/404/...) throw.
+     */
+    stream(options?: StreamOptions): AsyncGenerator<SessionEvent, void, void>;
+    /**
+     * Send a message and drive the turn to completion: streams events, answers
+     * parked client-tool calls from `tools`, routes approval requests to
+     * `onConfirm`, and resolves when the session settles (end_turn, interrupted,
+     * or error). Throws if the session terminates mid-run or `signal` aborts.
+     */
+    run(text: string, options?: RunOptions): Promise<RunResult>;
+}

package/dist/session.js

@@ -0,0 +1,342 @@
+/**
+ * The session handle: send messages, stream the event log, answer client
+ * tools, and drive whole turns with `run()`.
+ */
+import { HostlerError } from "./transport.js";
+import { SseParser } from "./sse.js";
+const INITIAL_RECONNECT_MS = 500;
+const MAX_RECONNECT_MS = 10_000;
+export class Session {
+    id;
+    #transport;
+    constructor(transport, id) {
+        this.#transport = transport;
+        this.id = id;
+    }
+    info() {
+        return this.#transport.request("GET", `/v1/sessions/${this.id}`);
+    }
+    /** Queue a user message; the turn runs asynchronously (watch `stream()`). */
+    async send(text, options = {}) {
+        await this.#transport.request("POST", `/v1/sessions/${this.id}/messages`, { text }, options);
+    }
+    /** Abort the current turn; the session settles to idle. */
+    async interrupt() {
+        await this.#transport.request("POST", `/v1/sessions/${this.id}/interrupt`, undefined);
+    }
+    /** Tear down the sandbox. Output files are captured first and stay downloadable. */
+    terminate() {
+        return this.#transport.request("DELETE", `/v1/sessions/${this.id}`);
+    }
+    /** One-shot JSON read of the event log (no streaming). */
+    async events(options = {}) {
+        const since = options.since ?? 0;
+        const body = await this.#transport.request("GET", `/v1/sessions/${this.id}/events?since=${since}`);
+        return body.events;
+    }
+    /** Answer a parked client-tool call. Exactly one of content/error. */
+    async submitToolResult(result, options = {}) {
+        await this.#transport.request("POST", `/v1/sessions/${this.id}/tool_results`, result, options);
+    }
+    /** Allow or deny an approval-gated tool call. */
+    async confirmTool(confirmation, options = {}) {
+        await this.#transport.request("POST", `/v1/sessions/${this.id}/tool_confirmations`, confirmation, options);
+    }
+    async outputFiles() {
+        const body = await this.#transport.request("GET", `/v1/sessions/${this.id}/output_files`);
+        return body.files;
+    }
+    async readOutputFile(path) {
+        const res = await this.#transport.requestRaw(`/v1/sessions/${this.id}/output_files/${path.split("/").map(encodeURIComponent).join("/")}`);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    /**
+     * Live event stream: replays history past `since`, then follows the session
+     * until it terminates. Reconnects automatically (resuming from the last
+     * seen seq) when the connection drops; HTTP errors (401/404/...) throw.
+     */
+    async *stream(options = {}) {
+        let since = options.since ?? 0;
+        let backoffMs = INITIAL_RECONNECT_MS;
+        const external = options.signal;
+        while (true) {
+            if (external?.aborted)
+                return;
+            // One controller per connection so returning from the generator (or the
+            // caller aborting) tears the fetch down instead of leaking the socket.
+            const connection = new AbortController();
+            const onExternalAbort = () => connection.abort();
+            external?.addEventListener("abort", onExternalAbort, { once: true });
+            try {
+                let res;
+                try {
+                    res = await this.#transport.requestRaw(`/v1/sessions/${this.id}/events?since=${since}`, {
+                        accept: "text/event-stream",
+                        signal: connection.signal,
+                    });
+                }
+                catch (e) {
+                    if (external?.aborted)
+                        return;
+                    // 4xx means the request itself is wrong (bad key, unknown session) —
+                    // retrying can't help. 5xx and network failures are transient (e.g.
+                    // the ALB while the control plane restarts) — retry with backoff.
+                    if (e instanceof HostlerError && e.status >= 400 && e.status < 500)
+                        throw e;
+                    await sleep(backoffMs, external);
+                    backoffMs = Math.min(backoffMs * 2, MAX_RECONNECT_MS);
+                    continue;
+                }
+                if (res.body === null)
+                    throw new HostlerError("event stream had no body", 0);
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                const parser = new SseParser();
+                let sawEvent = false;
+                try {
+                    while (true) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        for (const frame of parser.push(decoder.decode(value, { stream: true }))) {
+                            const event = JSON.parse(frame.data);
+                            if (event.seq <= since)
+                                continue; // reconnect replay overlap
+                            since = event.seq;
+                            sawEvent = true;
+                            backoffMs = INITIAL_RECONNECT_MS; // healthy connection: reset
+                            yield event;
+                            if (event.type === "session.status_terminated")
+                                return;
+                        }
+                    }
+                }
+                catch (e) {
+                    if (external?.aborted)
+                        return;
+                    // Mid-stream read failure: fall through to reconnect below.
+                    void e;
+                }
+                if (external?.aborted)
+                    return;
+                // A clean close with zero events can mean the session terminated with
+                // our cursor already past the terminal event (the server replays
+                // nothing and just closes) — reconnecting would loop forever.
+                if (!sawEvent) {
+                    try {
+                        const info = await this.info();
+                        if (info.status === "terminated")
+                            return;
+                    }
+                    catch (e) {
+                        // The probe can hit the same restarting control plane that just
+                        // closed the stream — only a 4xx is conclusive; anything else
+                        // falls through to the normal reconnect backoff.
+                        if (e instanceof HostlerError && e.status >= 400 && e.status < 500)
+                            throw e;
+                    }
+                }
+                // Server closed without a terminal event (e.g. a deploy) — reconnect.
+                await sleep(backoffMs, external);
+                backoffMs = Math.min(backoffMs * 2, MAX_RECONNECT_MS);
+            }
+            finally {
+                external?.removeEventListener("abort", onExternalAbort);
+                connection.abort();
+            }
+        }
+    }
+    /**
+     * Send a message and drive the turn to completion: streams events, answers
+     * parked client-tool calls from `tools`, routes approval requests to
+     * `onConfirm`, and resolves when the session settles (end_turn, interrupted,
+     * or error). Throws if the session terminates mid-run or `signal` aborts.
+     */
+    async run(text, options = {}) {
+        if (options.signal?.aborted)
+            throw new HostlerError("run aborted", 0);
+        const tools = options.tools ?? {};
+        const signal = options.signal;
+        const signalOpt = signal !== undefined ? { signal } : {};
+        // INVARIANT: once `signal` aborts, run() issues no further side-effecting
+        // request — a cancelled run must not resolve tool calls or confirmations
+        // behind the caller's back. Every helper below checks the signal before
+        // each POST and ties the POST itself to it.
+        const aborted = () => signal?.aborted === true;
+        // A call can be answered elsewhere (console operator) or cleared by an
+        // interrupt/termination between our seeing it and answering — then the
+        // answer 404s (no parked call) or 409s (not live). The stream's status
+        // events settle the run in those cases; don't fail it on the race.
+        const tolerate = async (action) => {
+            try {
+                await action;
+            }
+            catch (e) {
+                if (e instanceof HostlerError && (e.status === 404 || e.status === 409))
+                    return;
+                if (aborted())
+                    return; // aborted mid-POST: the final abort throw owns the outcome
+                throw e;
+            }
+        };
+        const answerCall = async (toolCallId, call) => {
+            if (aborted())
+                return;
+            const handler = tools[call.name];
+            if (handler === undefined) {
+                await tolerate(this.submitToolResult({ toolCallId, error: `no handler registered for tool "${call.name}"` }, signalOpt));
+                return;
+            }
+            try {
+                const value = await handler(call.input, { toolCallId, name: call.name });
+                if (aborted())
+                    return; // handler finished after cancellation: discard
+                await tolerate(this.submitToolResult({ toolCallId, content: stringifyResult(value) }, signalOpt));
+            }
+            catch (e) {
+                if (aborted())
+                    return;
+                await tolerate(this.submitToolResult({ toolCallId, error: e instanceof Error ? e.message : String(e) }, signalOpt));
+            }
+        };
+        const decideAsk = async (call) => {
+            if (options.onConfirm === undefined)
+                return; // leave it for a console operator
+            if (aborted())
+                return;
+            const decision = await options.onConfirm(call);
+            if (aborted())
+                return;
+            const normalized = typeof decision === "string" ? { result: decision } : decision;
+            await tolerate(this.confirmTool({ toolCallId: call.toolCallId, ...normalized }, signalOpt));
+        };
+        // Cursor first; the stream replays everything after it, so nothing
+        // between the send and the first read can be missed.
+        const history = await this.events();
+        if (aborted())
+            throw new HostlerError("run aborted", 0);
+        const since = history.at(-1)?.seq ?? 0;
+        // agent.tool_use carries the input; agent.tool_pending marks the call as
+        // parked for us. Correlate the two by toolCallId.
+        const toolInputs = new Map();
+        // Seed from history: calls parked BEFORE this run started still block the
+        // session, and the stream won't replay their events past our cursor —
+        // answer them now or the run would hang on them forever.
+        const resolved = new Set();
+        const confirmed = new Set();
+        for (const event of history) {
+            if (event.type === "agent.tool_result")
+                resolved.add(event.toolCallId);
+            else if (event.type === "user.tool_confirmation")
+                confirmed.add(event.toolCallId);
+        }
+        const parkedAsks = [];
+        const parkedCalls = [];
+        for (const event of history) {
+            if (event.type === "agent.tool_use" && !resolved.has(event.toolCallId)) {
+                if (event.locale === "client") {
+                    toolInputs.set(event.toolCallId, { name: event.name, input: event.input });
+                }
+                if (event.evaluatedPermission === "ask" && !confirmed.has(event.toolCallId)) {
+                    parkedAsks.push({ toolCallId: event.toolCallId, name: event.name, input: event.input });
+                }
+            }
+            else if (event.type === "agent.tool_pending" && event.pendingState === "async" && !resolved.has(event.toolCallId)) {
+                parkedCalls.push(event.toolCallId);
+            }
+        }
+        for (const ask of parkedAsks)
+            await decideAsk(ask);
+        for (const toolCallId of parkedCalls) {
+            const call = toolInputs.get(toolCallId);
+            if (call === undefined)
+                continue;
+            toolInputs.delete(toolCallId);
+            await answerCall(toolCallId, call);
+        }
+        // Re-check after the (async) history fetch and seeding, and tie the send
+        // itself to the signal: an abort landing anywhere in that window must not
+        // start a turn the caller no longer wants.
+        if (options.signal?.aborted)
+            throw new HostlerError("run aborted", 0);
+        const stream = this.stream({ since, ...(options.signal !== undefined ? { signal: options.signal } : {}) });
+        try {
+            await this.send(text, { ...(options.signal !== undefined ? { signal: options.signal } : {}) });
+        }
+        catch (e) {
+            if (options.signal?.aborted)
+                throw new HostlerError("run aborted", 0);
+            throw e;
+        }
+        let lastMessage = null;
+        let lastError = null;
+        for await (const event of stream) {
+            options.onEvent?.(event);
+            switch (event.type) {
+                case "agent.message":
+                    lastMessage = event.text;
+                    break;
+                case "agent.tool_use":
+                    if (event.locale === "client") {
+                        toolInputs.set(event.toolCallId, { name: event.name, input: event.input });
+                    }
+                    if (event.evaluatedPermission === "ask") {
+                        await decideAsk({ toolCallId: event.toolCallId, name: event.name, input: event.input });
+                    }
+                    break;
+                case "agent.tool_pending": {
+                    if (event.pendingState !== "async")
+                        break; // approvals are onConfirm's job
+                    const call = toolInputs.get(event.toolCallId);
+                    if (call === undefined)
+                        break; // not a client tool call we saw start
+                    toolInputs.delete(event.toolCallId);
+                    await answerCall(event.toolCallId, call);
+                    break;
+                }
+                case "session.status_idle":
+                    // requires_action idles are our cue to keep working the loop above;
+                    // anything else ends the turn.
+                    if (event.stopReason.type !== "requires_action") {
+                        return { text: lastMessage, stopReason: event.stopReason };
+                    }
+                    break;
+                case "session.error":
+                    // retryable errors may be followed by more work; non-retryable ones
+                    // are followed by termination — keep the detail for that throw.
+                    if (!event.retryable)
+                        lastError = event.message;
+                    break;
+                case "session.status_terminated":
+                    throw new HostlerError(`session terminated during run: ${event.reason}${lastError !== null ? ` (${lastError})` : ""}`, 0);
+                default:
+                    break;
+            }
+        }
+        if (options.signal?.aborted)
+            throw new HostlerError("run aborted", 0);
+        throw new HostlerError("event stream ended before the turn completed", 0);
+    }
+}
+function stringifyResult(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === undefined)
+        return "";
+    return JSON.stringify(value);
+}
+function sleep(ms, signal) {
+    // An already-aborted signal never fires its abort listeners — check first
+    // or an abort landing before the sleep waits out the full backoff.
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        function done() {
+            signal?.removeEventListener("abort", done);
+            clearTimeout(timer);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}

package/dist/sse.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal SSE frame parser for the events endpoint. The server writes frames
+ * as `id: <seq>\ndata: <JSON>\n\n` plus comment heartbeats (`: ping`), so this
+ * implements just the subset of the SSE grammar the control plane emits —
+ * multi-line `data:` joining and comment skipping included for spec safety.
+ */
+export interface SseFrame {
+    id?: string;
+    data: string;
+}
+export declare class SseParser {
+    #private;
+    /** Feed a decoded chunk; returns every complete frame it terminated. */
+    push(chunk: string): SseFrame[];
+}

package/dist/sse.js

@@ -0,0 +1,46 @@
+/**
+ * Minimal SSE frame parser for the events endpoint. The server writes frames
+ * as `id: <seq>\ndata: <JSON>\n\n` plus comment heartbeats (`: ping`), so this
+ * implements just the subset of the SSE grammar the control plane emits —
+ * multi-line `data:` joining and comment skipping included for spec safety.
+ */
+export class SseParser {
+    #buffer = "";
+    /** Feed a decoded chunk; returns every complete frame it terminated. */
+    push(chunk) {
+        this.#buffer += chunk;
+        const frames = [];
+        let idx;
+        while ((idx = this.#buffer.indexOf("\n\n")) !== -1) {
+            const raw = this.#buffer.slice(0, idx);
+            this.#buffer = this.#buffer.slice(idx + 2);
+            const frame = parseFrame(raw);
+            if (frame !== null)
+                frames.push(frame);
+        }
+        return frames;
+    }
+}
+function parseFrame(raw) {
+    let id;
+    const data = [];
+    for (const line of raw.split("\n")) {
+        if (line.startsWith(":"))
+            continue; // comment (heartbeat)
+        const colon = line.indexOf(":");
+        if (colon === -1)
+            continue;
+        const field = line.slice(0, colon);
+        // Per the SSE spec a single space after the colon is not part of the value.
+        let value = line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "id")
+            id = value;
+        else if (field === "data")
+            data.push(value);
+    }
+    if (data.length === 0)
+        return null; // comment-only frame (heartbeat)
+    return { ...(id !== undefined ? { id } : {}), data: data.join("\n") };
+}

package/dist/transport.d.ts

@@ -0,0 +1,29 @@
+/** HTTP plumbing shared by the resource classes and the session handle. */
+export declare class HostlerError extends Error {
+    /** HTTP status of the failing response, or 0 when the failure wasn't an HTTP error. */
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export interface TransportOptions {
+    apiKey: string;
+    baseUrl: string;
+    fetch: typeof fetch;
+}
+interface RawRequestInit {
+    accept?: string;
+    signal?: AbortSignal;
+}
+export declare class Transport {
+    #private;
+    constructor(options: TransportOptions);
+    /**
+     * JSON request/response. Non-2xx responses throw HostlerError with the
+     * server's `{ "error": "..." }` message.
+     */
+    request<T>(method: string, path: string, body?: unknown, init?: {
+        signal?: AbortSignal;
+    }): Promise<T>;
+    /** Raw response for streaming (SSE) and binary (output files) reads. */
+    requestRaw(path: string, init?: RawRequestInit): Promise<Response>;
+}
+export {};

package/dist/transport.js

@@ -0,0 +1,74 @@
+/** HTTP plumbing shared by the resource classes and the session handle. */
+export class HostlerError extends Error {
+    /** HTTP status of the failing response, or 0 when the failure wasn't an HTTP error. */
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "HostlerError";
+        this.status = status;
+    }
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null;
+}
+export class Transport {
+    #apiKey;
+    #baseUrl;
+    #fetch;
+    constructor(options) {
+        this.#apiKey = options.apiKey;
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.#fetch = options.fetch;
+    }
+    /**
+     * JSON request/response. Non-2xx responses throw HostlerError with the
+     * server's `{ "error": "..." }` message.
+     */
+    async request(method, path, body, init = {}) {
+        const res = await this.#fetch(`${this.#baseUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.#apiKey}`,
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            ...(init.signal !== undefined ? { signal: init.signal } : {}),
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new HostlerError(errorMessage(text, res.status), res.status);
+        const payload = text === "" ? undefined : JSON.parse(text);
+        // The one deliberate widening in the SDK: 2xx bodies are trusted to match
+        // the declared wire types — they are pinned against the real control-plane
+        // server by the cross-package integration test — rather than re-validated
+        // on every call.
+        return payload;
+    }
+    /** Raw response for streaming (SSE) and binary (output files) reads. */
+    async requestRaw(path, init = {}) {
+        const res = await this.#fetch(`${this.#baseUrl}${path}`, {
+            method: "GET",
+            headers: {
+                authorization: `Bearer ${this.#apiKey}`,
+                ...(init.accept !== undefined ? { accept: init.accept } : {}),
+            },
+            ...(init.signal !== undefined ? { signal: init.signal } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new HostlerError(errorMessage(text, res.status), res.status);
+        }
+        return res;
+    }
+}
+function errorMessage(bodyText, status) {
+    try {
+        const parsed = JSON.parse(bodyText);
+        if (isRecord(parsed) && typeof parsed["error"] === "string")
+            return parsed["error"];
+    }
+    catch {
+        // non-JSON error body — fall through to the generic message
+    }
+    return `HTTP ${status}: ${bodyText.slice(0, 200)}`;
+}

package/dist/types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Wire types for the Hostler /v1 API. These mirror the server's contract
+ * (control-plane/src/http.ts request schemas, control-plane/src/db.ts row
+ * shapes, and the runtime's SessionEvent union in runtime/src/types.ts) —
+ * the SDK is published standalone, so the shapes are declared here rather
+ * than imported, and the cross-repo integration test pins them against the
+ * real server.
+ */
+export interface ModelConfig {
+    provider: string;
+    id: string;
+    /** Override the provider's default API endpoint. */
+    upstreamBaseUrl?: string;
+    [extra: string]: unknown;
+}
+export interface ClientToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's input. */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * An agent's versioned configuration. `name`, `harness`, and `model` are
+ * validated by the server; further fields (toolConfigs, mcpServers, skills,
+ * ...) pass through to the runtime, which owns those contracts.
+ */
+export interface AgentConfig {
+    name: string;
+    /** Which agent harness runs in the sandbox (e.g. "pi"). */
+    harness: string;
+    model: ModelConfig;
+    /** System prompt. */
+    system?: string;
+    /**
+     * Which of the harness's own built-in tools run in the sandbox. `[]`
+     * disables all of them; omit for the harness default.
+     */
+    sandboxTools?: string[];
+    /** Tools executed by YOUR application via the tool_results loop. */
+    clientTools?: ClientToolDefinition[];
+    [extra: string]: unknown;
+}
+/** One immutable version of an agent, as stored by the control plane. */
+export interface Agent {
+    id: string;
+    version: number;
+    config: AgentConfig;
+    createdAt: string;
+}
+export type SessionStatus = "starting" | "running" | "idle" | "terminated";
+export interface SessionInfo {
+    id: string;
+    agentId: string;
+    agentVersion: number;
+    status: SessionStatus;
+    title: string | null;
+    createdAt: string;
+    terminatedAt: string | null;
+    environmentId: string | null;
+    vaultIds: string[];
+    deploymentId: string | null;
+}
+export interface SessionResourceMount {
+    type: "memory_store";
+    memoryStoreId: string;
+    access?: "read_write" | "read_only";
+    instructions?: string;
+}
+export interface CreateSessionOptions {
+    agentId: string;
+    /** Pin a specific agent version; omit for the latest. */
+    agentVersion?: number;
+    title?: string;
+    environmentId?: string;
+    vaultIds?: string[];
+    resources?: SessionResourceMount[];
+}
+export interface OutputFile {
+    /** Path relative to the session's outputs directory. */
+    path: string;
+    sizeBytes: number;
+}
+export type StopReason = {
+    type: "end_turn";
+} | {
+    type: "requires_action";
+    toolCallIds: string[];
+} | {
+    type: "interrupted";
+} | {
+    type: "error";
+    message: string;
+};
+export type ToolResultContent = {
+    type: "text";
+    text: string;
+};
+interface EventBase {
+    /** Monotonic per-session sequence — the cursor for `since` / Last-Event-ID. */
+    seq: number;
+    /** Unique event id, `sevt_<...>`. */
+    id: string;
+    /** ms epoch when the event was appended. */
+    ts: number;
+}
+/**
+ * The append-only session event log. New event types may be added by the
+ * server over time — consumers should ignore types they don't recognize
+ * rather than treating the union as closed.
+ */
+export type SessionEvent = EventBase & ({
+    type: "session.status_running";
+} | {
+    type: "session.status_idle";
+    stopReason: StopReason;
+} | {
+    type: "session.status_terminated";
+    reason: string;
+} | {
+    type: "session.error";
+    message: string;
+    retryable: boolean;
+} | {
+    type: "user.message";
+    text: string;
+} | {
+    type: "user.interrupt";
+} | {
+    type: "agent.message_delta";
+    text: string;
+} | {
+    type: "agent.message";
+    text: string;
+} | {
+    type: "agent.thinking_delta";
+    text: string;
+} | {
+    type: "agent.tool_use";
+    toolCallId: string;
+    name: string;
+    input: unknown;
+    /** "client" = your application executes it; "sandbox" = harness-local; "mcp" = runtime-side MCP dispatch. */
+    locale: "client" | "sandbox" | "mcp";
+    /** Present for client/mcp tools: "ask" means the call is parked awaiting a tool confirmation. */
+    evaluatedPermission?: "allow" | "ask";
+} | {
+    type: "user.tool_confirmation";
+    toolCallId: string;
+    result: "allow" | "deny";
+    denyMessage?: string;
+} | {
+    type: "span.model_request_start";
+    requestId: string;
+} | {
+    type: "span.model_request_end";
+    requestId: string;
+    httpStatus: number;
+    usage?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+} | {
+    type: "span.outcome_evaluation_start";
+    outcomeId: string;
+    iteration: number;
+} | {
+    type: "span.outcome_evaluation_end";
+    outcomeId: string;
+    iteration: number;
+    result: "satisfied" | "needs_revision" | "max_iterations_reached" | "failed" | "interrupted";
+    explanation: string;
+} | {
+    type: "session.updated";
+    changed: string[];
+} | {
+    type: "agent.tool_pending";
+    toolCallId: string;
+    name: string;
+    pendingState: "approval" | "async";
+    description?: string;
+} | {
+    type: "agent.tool_result";
+    toolCallId: string;
+    name: string;
+    isError: boolean;
+    content: ToolResultContent[];
+} | {
+    type: "span.model_usage";
+    usage: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        costUsd?: number;
+    };
+});
+/** Exactly one of `content` or `error` — the server rejects both/neither. */
+export type ToolResult = {
+    toolCallId: string;
+    content: string;
+    error?: undefined;
+} | {
+    toolCallId: string;
+    error: string;
+    content?: undefined;
+};
+export interface ToolConfirmation {
+    toolCallId: string;
+    result: "allow" | "deny";
+    /** Shown to the model verbatim on deny (defaults to "denied by user"). */
+    denyMessage?: string;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Wire types for the Hostler /v1 API. These mirror the server's contract
+ * (control-plane/src/http.ts request schemas, control-plane/src/db.ts row
+ * shapes, and the runtime's SessionEvent union in runtime/src/types.ts) —
+ * the SDK is published standalone, so the shapes are declared here rather
+ * than imported, and the cross-repo integration test pins them against the
+ * real server.
+ */
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@hostler/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Hostler API: managed agents, sessions, live event streams, and client-tool execution.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://hostler.dev/docs/sdk",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --test-timeout=60000 'test/*.test.ts'"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.0"
+  }
+}