@wice24/tars-sdk 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @wice24/tars-sdk
+
+TypeScript client for [TARS](https://github.com/meridian-capital/tars) — a
+self-hosted managed-agents platform: server-side agent loops in sandboxes,
+an append-only session event log with SSE streaming + replay, client-executed
+tools, per-end-user MCP credentials, skills, files, and usage metering.
+
+```bash
+npm install @wice24/tars-sdk
+```
+
+## Quickstart
+
+```ts
+import { TarsClient } from '@wice24/tars-sdk';
+
+const tars = new TarsClient({
+  apiKey: process.env.TARS_API_KEY!,   // tars_sk_…
+  baseUrl: 'https://your-tars-host',
+});
+
+const agent = await tars.agents.create({
+  name: 'assistant',
+  system: 'You are a helpful assistant.',
+  model: 'anthropic/claude-sonnet-5',
+});
+
+const session = await tars.sessions.create({ agentId: agent.id });
+for await (const event of session.send('Summarize the attached file.')) {
+  if (event.type === 'text_delta') process.stdout.write(event.text);
+}
+```
+
+## Streaming surfaces
+
+- `session.send(text)` — yields the turn's events; client-executed tools you
+  registered (`sessions.create({ tools })` / `session.onToolCall`) are run and
+  their results returned to the turn automatically.
+- `session.sendRaw(text)` — same events, **no auto-dispatch**: hosts that own
+  their tool dispatcher consume this.
+- `session.stream({ after })` — full event log: replay after a seq cursor,
+  then live-tail. Survives page refreshes and server restarts.
+- `session.resume({ after })` — current-turn reconnect: replay after the
+  cursor, then close immediately when idle or right after `turn_end`.
+  Never re-dispatches client tools.
+- `session.interrupt()` — abort the in-flight turn; partial text is kept.
+
+Every event carries a monotonic `seq` — persist the last one you rendered and
+reconnect with it.
+
+## Beyond sessions
+
+`tars.agents` (versioned configs, skills pins, MCP servers, sandbox
+environment), `tars.skills` (zip bundles with a `SKILL.md`, immutable
+versions), `tars.files` (upload / mount / outputs), `tars.mcpCredentials`
+(per-end-user or tenant-wide, OAuth refresh with rotation), `tars.usage`,
+`tars.apiKeys`, and `tars.completions` for cheap one-shot generations.
+
+## Testing
+
+Inject `fetchImpl` to stub transport:
+
+```ts
+const tars = new TarsClient({ apiKey: 'tars_sk_test', fetchImpl: myStub });
+```
+
+## Requirements
+
+Node 18+ (global `fetch`). ESM only.

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+import type { Agent, AgentVersion, ClientTool, CreateAgentInput, FileMeta, McpCredentialInput, McpCredentialStatus, SessionEvent, SessionInfo, SessionListItem, UpdateAgentInput, UploadFileInput, UsageSummary, McpServer, Skill, SkillVersion, ApiKeyInfo } from './types.js';
+type ToolHandler = (input: any) => unknown | Promise<unknown>;
+export * from './types.js';
+export declare class TarsApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message?: string);
+}
+export interface TarsClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    /** Injectable fetch (tests, custom agents/proxies). Defaults to global fetch. */
+    fetchImpl?: typeof globalThis.fetch;
+}
+export declare class TarsClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(options: TarsClientOptions);
+    private request;
+    readonly agents: {
+        create: (input: CreateAgentInput) => Promise<Agent>;
+        list: (options?: {
+            includeArchived?: boolean;
+        }) => Promise<Agent[]>;
+        get: (id: string) => Promise<Agent>;
+        update: (id: string, patch: UpdateAgentInput) => Promise<Agent>;
+        archive: (id: string) => Promise<{
+            ok: boolean;
+        }>;
+        unarchive: (id: string) => Promise<{
+            ok: boolean;
+        }>;
+        versions: (id: string) => Promise<AgentVersion[]>;
+    };
+    readonly sessions: {
+        create: (input: {
+            agentId: string;
+            model?: string;
+            endUserId?: string;
+            title?: string;
+            /** String-KV scoping/labels (owner_id/app_id conventions). */
+            metadata?: Record<string, string>;
+            /** Extra MCP servers for THIS session (per-user connectors); the
+             *  agent's declared servers win on name collision. */
+            mcpServers?: McpServer[];
+            /** Appended to the agent's system prompt for this session only. */
+            systemSuffix?: string;
+            tools?: ClientTool[];
+        }) => Promise<TarsSession>;
+        list: (opts?: {
+            limit?: number;
+            cursor?: string;
+            /** Filter by metadata keys, e.g. { owner_id: 'u1', app_id: 'coral' }. */
+            metadata?: Record<string, string>;
+            includeArchived?: boolean;
+        }) => Promise<{
+            sessions: SessionListItem[];
+            nextCursor: string | null;
+        }>;
+        rename: (id: string, title: string) => Promise<{
+            ok: boolean;
+        }>;
+        /** Replace the session's extra MCP server set (takes effect next turn;
+         *  409s while a turn is in flight). */
+        setMcpServers: (id: string, servers: McpServer[]) => Promise<{
+            ok: boolean;
+        }>;
+        /** Abort the in-flight turn, if any. Idempotent. */
+        interrupt: (id: string) => Promise<{
+            ok: boolean;
+            interrupted: boolean;
+        }>;
+        usage: (id: string) => Promise<{
+            session_id: string;
+            model: string;
+            input_tokens: number;
+            output_tokens: number;
+            cache_read_tokens: number;
+            cache_write_tokens: number;
+            cost_usd: number | null;
+            turns: number;
+        }>;
+        get: (id: string) => Promise<SessionInfo>;
+        open: (id: string, opts?: {
+            tools?: ClientTool[];
+        }) => Promise<TarsSession>;
+        destroy: (id: string) => Promise<{
+            ok: boolean;
+        }>;
+    };
+    readonly mcpCredentials: {
+        set: (input: {
+            server: string;
+            auth: McpCredentialInput;
+            endUserId?: string;
+        }) => Promise<void>;
+        list: (endUserId?: string) => Promise<McpCredentialStatus[]>;
+        delete: (server: string, endUserId?: string) => Promise<{
+            ok: boolean;
+        }>;
+    };
+    readonly skills: {
+        create: (input: {
+            slug: string;
+            displayTitle: string;
+        }) => Promise<Skill>;
+        list: () => Promise<Skill[]>;
+        get: (id: string) => Promise<Skill>;
+        versions: (id: string) => Promise<SkillVersion[]>;
+        /** Upload a new immutable version from zip bytes. */
+        pushVersion: (id: string, zipBytes: Uint8Array) => Promise<{
+            skill_id: string;
+            slug: string;
+            version: number;
+            files: number;
+        }>;
+    };
+    readonly apiKeys: {
+        create: (input?: {
+            name?: string;
+        }) => Promise<{
+            id: string;
+            key: string;
+            key_prefix: string;
+        }>;
+        list: () => Promise<ApiKeyInfo[]>;
+        revoke: (id: string) => Promise<{
+            ok: boolean;
+        }>;
+    };
+    readonly completions: {
+        create: (input: {
+            prompt: string;
+            model?: string;
+            system?: string;
+            maxTokens?: number;
+        }) => Promise<{
+            text: string;
+            usage: {
+                input_tokens: number;
+                output_tokens: number;
+            };
+        }>;
+    };
+    readonly usage: {
+        get: (filter?: {
+            from?: string | Date;
+            to?: string | Date;
+            sessionId?: string;
+            endUserId?: string;
+        }) => Promise<UsageSummary>;
+    };
+    readonly files: {
+        upload: (input: UploadFileInput) => Promise<FileMeta>;
+        uploadText: (name: string, content: string, mime?: string) => Promise<FileMeta>;
+        list: (filter?: {
+            sessionId?: string;
+            name?: string;
+        }) => Promise<FileMeta[]>;
+        get: (id: string) => Promise<FileMeta>;
+        download: (id: string) => Promise<{
+            body: ReadableStream<Uint8Array>;
+            contentType: string;
+        }>;
+        downloadBytes: (id: string) => Promise<Uint8Array>;
+    };
+    mountFile(sessionId: string, input: {
+        fileId: string;
+        mountPath?: string;
+    }): Promise<{
+        mount_path: string;
+        size_bytes: number;
+    }>;
+    /** Send one user message and stream the turn's raw events. No client-tool
+     *  auto-dispatch happens here — callers that registered tool handlers want
+     *  TarsSession.send(); adapters that dispatch themselves want this (or
+     *  TarsSession.sendRaw). */
+    streamMessage(sessionId: string, text: string): Promise<AsyncGenerator<SessionEvent>>;
+    /** Follow the session event log: replay after `after`, then live-tail.
+     *  mode 'turn' is the reconnect shape: closes immediately when the session
+     *  is idle, else closes right after the in-flight turn's turn_end. */
+    streamEvents(sessionId: string, after: number, opts?: {
+        mode?: 'turn';
+    }): Promise<AsyncGenerator<SessionEvent>>;
+    /** @internal used by TarsSession to return a client tool result */
+    submitToolResult(sessionId: string, callId: string, output: unknown, isError: boolean): Promise<void>;
+}
+export declare class TarsSession {
+    private readonly client;
+    readonly info: SessionInfo;
+    private readonly toolHandlers;
+    constructor(client: TarsClient, info: SessionInfo, toolHandlers?: Map<string, ToolHandler>);
+    get id(): string;
+    onToolCall(name: string, execute: ToolHandler): this;
+    send(text: string): AsyncGenerator<SessionEvent>;
+    private fulfill;
+    sendRaw(text: string): AsyncGenerator<SessionEvent>;
+    stream(opts?: {
+        after?: number;
+    }): AsyncGenerator<SessionEvent>;
+    resume(opts?: {
+        after?: number;
+    }): AsyncGenerator<SessionEvent>;
+    mountFile(fileId: string, mountPath?: string): Promise<{
+        mount_path: string;
+        size_bytes: number;
+    }>;
+    attachFile(input: UploadFileInput & {
+        mountPath?: string;
+    }): Promise<{
+        file: FileMeta;
+        mount_path: string;
+    }>;
+    destroy(): Promise<{
+        ok: boolean;
+    }>;
+}

package/dist/index.js

@@ -0,0 +1,402 @@
+export * from './types.js';
+export class TarsApiError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message ?? `TARS API error ${status}: ${JSON.stringify(body)}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'TarsApiError';
+    }
+}
+export class TarsClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error('TarsClient: apiKey is required');
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? 'http://localhost:3001').replace(/\/$/, '');
+        // Bind: an unbound global fetch throws "Illegal invocation" in browsers.
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    }
+    // ── low-level HTTP ───────────────────────────────────────────
+    async request(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.apiKey}`,
+                ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const payload = await res.json().catch(() => undefined);
+        if (!res.ok)
+            throw new TarsApiError(res.status, payload);
+        return payload;
+    }
+    // ── agents ───────────────────────────────────────────────────
+    agents = {
+        create: (input) => this.request('POST', '/v1/agents', input),
+        list: async (options) => {
+            const qs = options?.includeArchived ? '?include_archived=true' : '';
+            const { agents } = await this.request('GET', `/v1/agents${qs}`);
+            return agents;
+        },
+        get: (id) => this.request('GET', `/v1/agents/${id}`),
+        update: (id, patch) => this.request('PATCH', `/v1/agents/${id}`, patch),
+        archive: (id) => this.request('POST', `/v1/agents/${id}/archive`),
+        unarchive: (id) => this.request('POST', `/v1/agents/${id}/unarchive`),
+        versions: async (id) => {
+            const { versions } = await this.request('GET', `/v1/agents/${id}/versions`);
+            return versions;
+        },
+    };
+    // ── sessions ─────────────────────────────────────────────────
+    sessions = {
+        create: async (input) => {
+            const info = await this.request('POST', '/v1/sessions', {
+                agent_id: input.agentId,
+                ...(input.model ? { model: input.model } : {}),
+                ...(input.endUserId ? { end_user_id: input.endUserId } : {}),
+                ...(input.title ? { title: input.title } : {}),
+                ...(input.metadata ? { metadata: input.metadata } : {}),
+                ...(input.mcpServers?.length ? { mcp_servers: input.mcpServers } : {}),
+                ...(input.systemSuffix ? { system_suffix: input.systemSuffix } : {}),
+                ...(input.tools?.length
+                    ? {
+                        custom_tools: input.tools.map((t) => ({
+                            name: t.name,
+                            description: t.description,
+                            input_schema: t.inputSchema,
+                            ...(t.timeoutSec ? { timeout_sec: t.timeoutSec } : {}),
+                        })),
+                    }
+                    : {}),
+            });
+            const handlers = new Map((input.tools ?? []).map((t) => [t.name, t.execute]));
+            return new TarsSession(this, info, handlers);
+        },
+        list: async (opts) => {
+            const params = new URLSearchParams();
+            if (opts?.limit)
+                params.set('limit', String(opts.limit));
+            if (opts?.cursor)
+                params.set('cursor', opts.cursor);
+            if (opts?.includeArchived)
+                params.set('include_archived', 'true');
+            for (const [k, v] of Object.entries(opts?.metadata ?? {}))
+                params.set(`metadata.${k}`, v);
+            const qs = params.size ? `?${params}` : '';
+            const res = await this.request('GET', `/v1/sessions${qs}`);
+            return { sessions: res.sessions, nextCursor: res.next_cursor };
+        },
+        rename: (id, title) => this.request('PATCH', `/v1/sessions/${id}`, { title }),
+        /** Replace the session's extra MCP server set (takes effect next turn;
+         *  409s while a turn is in flight). */
+        setMcpServers: (id, servers) => this.request('PATCH', `/v1/sessions/${id}`, { mcp_servers: servers }),
+        /** Abort the in-flight turn, if any. Idempotent. */
+        interrupt: (id) => this.request('POST', `/v1/sessions/${id}/interrupt`),
+        usage: (id) => this.request('GET', `/v1/sessions/${id}/usage`),
+        get: (id) => this.request('GET', `/v1/sessions/${id}`),
+        // Re-open an existing session (e.g. after a page refresh or on another
+        // device) — sessions are durable server-side resources. Re-supply `tools`
+        // to keep fulfilling client tool calls (handlers are code, not stored).
+        open: async (id, opts) => {
+            const info = await this.request('GET', `/v1/sessions/${id}`);
+            const handlers = new Map((opts?.tools ?? []).map((t) => [t.name, t.execute]));
+            return new TarsSession(this, info, handlers);
+        },
+        destroy: (id) => this.request('DELETE', `/v1/sessions/${id}`),
+    };
+    // ── MCP credentials ──────────────────────────────────────────
+    // The tenant supplies a credential (obtained via their own OAuth) for an
+    // external MCP server; TARS stores it in Key Vault and injects it when the
+    // agent calls that server. Scope to an end-user via endUserId, or omit for a
+    // tenant-level credential.
+    mcpCredentials = {
+        set: (input) => this.request('PUT', '/v1/mcp-credentials', {
+            server: input.server,
+            auth: input.auth,
+            ...(input.endUserId ? { end_user_id: input.endUserId } : {}),
+        }),
+        list: async (endUserId) => {
+            const qs = endUserId ? `?end_user_id=${encodeURIComponent(endUserId)}` : '';
+            const { credentials } = await this.request('GET', `/v1/mcp-credentials${qs}`);
+            return credentials;
+        },
+        delete: (server, endUserId) => {
+            const params = new URLSearchParams({ server });
+            if (endUserId)
+                params.set('end_user_id', endUserId);
+            return this.request('DELETE', `/v1/mcp-credentials?${params}`);
+        },
+    };
+    // ── usage ────────────────────────────────────────────────────
+    // Versioned skill bundles (zip with SKILL.md at root), pinned per agent.
+    skills = {
+        create: (input) => this.request('POST', '/v1/skills', { slug: input.slug, display_title: input.displayTitle }),
+        list: async () => (await this.request('GET', '/v1/skills')).skills,
+        get: (id) => this.request('GET', `/v1/skills/${id}`),
+        versions: async (id) => (await this.request('GET', `/v1/skills/${id}/versions`)).versions,
+        /** Upload a new immutable version from zip bytes. */
+        pushVersion: async (id, zipBytes) => {
+            const res = await this.fetchImpl(`${this.baseUrl}/v1/skills/${id}/versions`, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${this.apiKey}`, 'content-type': 'application/zip' },
+                body: zipBytes,
+            });
+            if (!res.ok)
+                throw new TarsApiError(res.status, await res.json().catch(() => ({})));
+            return res.json();
+        },
+    };
+    apiKeys = {
+        create: (input) => this.request('POST', '/v1/api-keys', { ...(input?.name ? { name: input.name } : {}) }),
+        list: async () => (await this.request('GET', '/v1/api-keys')).keys,
+        revoke: (id) => this.request('DELETE', `/v1/api-keys/${id}`),
+    };
+    // Cheap non-session completion (titles and other one-shots) — routed
+    // through the same provider seam as agent turns.
+    completions = {
+        create: (input) => this.request('POST', '/v1/completions', {
+            prompt: input.prompt,
+            ...(input.model ? { model: input.model } : {}),
+            ...(input.system ? { system: input.system } : {}),
+            ...(input.maxTokens ? { max_tokens: input.maxTokens } : {}),
+        }),
+    };
+    usage = {
+        // Aggregated token/cost usage for this tenant, with per-model, per-agent,
+        // and per-end-user breakdowns. Dates are ISO 8601; sessionId narrows to one
+        // session; endUserId narrows to (and is the key to bill) one tenant user.
+        get: async (filter) => {
+            const params = new URLSearchParams();
+            if (filter?.from)
+                params.set('from', new Date(filter.from).toISOString());
+            if (filter?.to)
+                params.set('to', new Date(filter.to).toISOString());
+            if (filter?.sessionId)
+                params.set('session_id', filter.sessionId);
+            if (filter?.endUserId)
+                params.set('end_user_id', filter.endUserId);
+            const qs = params.size ? `?${params}` : '';
+            return this.request('GET', `/v1/usage${qs}`);
+        },
+    };
+    // ── files ────────────────────────────────────────────────────
+    files = {
+        // Upload bytes to the File API (registry + blob storage). Not tied to a
+        // session until mounted (or produced by an agent as an output).
+        upload: async (input) => {
+            const bytes = typeof input.content === 'string'
+                ? new TextEncoder().encode(input.content)
+                : input.content;
+            const res = await this.fetchImpl(`${this.baseUrl}/v1/files?name=${encodeURIComponent(input.name)}`, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.apiKey}`,
+                    'content-type': input.mime ?? 'application/octet-stream',
+                },
+                body: bytes,
+            });
+            const payload = await res.json().catch(() => undefined);
+            if (!res.ok)
+                throw new TarsApiError(res.status, payload);
+            return payload;
+        },
+        uploadText: (name, content, mime = 'text/plain') => this.files.upload({ name, content, mime }),
+        // List/search files — filter by session (includes agent outputs and files
+        // mounted into it) and/or exact name.
+        list: async (filter) => {
+            const params = new URLSearchParams();
+            if (filter?.sessionId)
+                params.set('session_id', filter.sessionId);
+            if (filter?.name)
+                params.set('name', filter.name);
+            const qs = params.size ? `?${params}` : '';
+            const { files } = await this.request('GET', `/v1/files${qs}`);
+            return files;
+        },
+        get: (id) => this.request('GET', `/v1/files/${id}`),
+        download: async (id) => {
+            const res = await this.fetchImpl(`${this.baseUrl}/v1/files/${id}/content`, {
+                headers: { authorization: `Bearer ${this.apiKey}` },
+            });
+            if (!res.ok || !res.body) {
+                throw new TarsApiError(res.status, await res.json().catch(() => undefined));
+            }
+            return {
+                body: res.body,
+                contentType: res.headers.get('content-type') ?? 'application/octet-stream',
+            };
+        },
+        downloadBytes: async (id) => {
+            const { body } = await this.files.download(id);
+            const chunks = [];
+            for await (const chunk of body)
+                chunks.push(chunk);
+            const total = chunks.reduce((n, c) => n + c.length, 0);
+            const out = new Uint8Array(total);
+            let offset = 0;
+            for (const c of chunks) {
+                out.set(c, offset);
+                offset += c.length;
+            }
+            return out;
+        },
+    };
+    // Copies an uploaded file into a session's sandbox. Default mount path is
+    // /mnt/session/uploads/<name>; idempotent for the same file+path.
+    async mountFile(sessionId, input) {
+        return this.request('POST', `/v1/sessions/${sessionId}/files`, {
+            file_id: input.fileId,
+            ...(input.mountPath ? { mount_path: input.mountPath } : {}),
+        });
+    }
+    /** Send one user message and stream the turn's raw events. No client-tool
+     *  auto-dispatch happens here — callers that registered tool handlers want
+     *  TarsSession.send(); adapters that dispatch themselves want this (or
+     *  TarsSession.sendRaw). */
+    async streamMessage(sessionId, text) {
+        const res = await this.fetchImpl(`${this.baseUrl}/v1/sessions/${sessionId}/messages`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${this.apiKey}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({ text }),
+        });
+        if (!res.ok || !res.body) {
+            const payload = await res.json().catch(() => undefined);
+            throw new TarsApiError(res.status, payload);
+        }
+        return parseSse(res.body);
+    }
+    /** Follow the session event log: replay after `after`, then live-tail.
+     *  mode 'turn' is the reconnect shape: closes immediately when the session
+     *  is idle, else closes right after the in-flight turn's turn_end. */
+    async streamEvents(sessionId, after, opts) {
+        const qs = `after=${after}` + (opts?.mode ? `&mode=${opts.mode}` : '');
+        const res = await this.fetchImpl(`${this.baseUrl}/v1/sessions/${sessionId}/stream?${qs}`, {
+            headers: { authorization: `Bearer ${this.apiKey}` },
+        });
+        if (!res.ok || !res.body) {
+            const payload = await res.json().catch(() => undefined);
+            throw new TarsApiError(res.status, payload);
+        }
+        return parseSse(res.body);
+    }
+    /** @internal used by TarsSession to return a client tool result */
+    async submitToolResult(sessionId, callId, output, isError) {
+        await this.request('POST', `/v1/sessions/${sessionId}/tool-results`, {
+            tool_call_id: callId,
+            output,
+            is_error: isError,
+        });
+    }
+}
+// One live agent session: send messages, iterate events.
+export class TarsSession {
+    client;
+    info;
+    toolHandlers;
+    constructor(client, info, toolHandlers = new Map()) {
+        this.client = client;
+        this.info = info;
+        this.toolHandlers = toolHandlers;
+    }
+    get id() {
+        return this.info.id;
+    }
+    // Register (or replace) a client tool handler after construction — handy when
+    // reopening a session. Mirrors passing `tools` to sessions.create/open.
+    onToolCall(name, execute) {
+        this.toolHandlers.set(name, execute);
+        return this;
+    }
+    // Sends one user message; yields this turn's events as they stream. When the
+    // agent calls a client-executed tool, the SDK runs the registered handler and
+    // returns its result to the turn transparently — the caller still sees the
+    // tool_call / tool_result events.
+    async *send(text) {
+        const inflight = [];
+        try {
+            for await (const event of await this.client.streamMessage(this.info.id, text)) {
+                if (event.type === 'tool_call' && event.client_executed && event.id) {
+                    const handler = this.toolHandlers.get(event.tool);
+                    if (handler)
+                        inflight.push(this.fulfill(handler, event.id, event.input));
+                    // No handler → the backend times out this call as an error result.
+                }
+                yield event;
+            }
+        }
+        finally {
+            // Surface handler/POST failures and avoid dangling work after the stream.
+            await Promise.allSettled(inflight);
+        }
+    }
+    async fulfill(handler, callId, input) {
+        try {
+            const output = await handler(input);
+            await this.client.submitToolResult(this.info.id, callId, output, false);
+        }
+        catch (err) {
+            await this.client.submitToolResult(this.info.id, callId, { error: String(err) }, true);
+        }
+    }
+    // send() without the client-tool auto-dispatch: yields the turn's raw
+    // events and leaves tool_call handling entirely to the caller. This is the
+    // adapter-facing surface — a host that owns its own dispatcher (heartbeats,
+    // per-turn credentials) must not have the SDK racing it.
+    async *sendRaw(text) {
+        yield* await this.client.streamMessage(this.info.id, text);
+    }
+    // Follow the session's full event stream: replays history after `after`
+    // (default: from the beginning), then keeps yielding live events. Survives
+    // page refreshes and server restarts — reconnect with the last seq you saw.
+    async *stream(opts) {
+        yield* await this.client.streamEvents(this.info.id, opts?.after ?? -1);
+    }
+    // Reconnect to the CURRENT turn only: replay everything after `after`, then
+    // (idle → the stream closes immediately; turn in flight → live events until
+    // its turn_end). Never re-dispatches client tools — results already posted
+    // stay posted; unresolved calls keep their park on the server.
+    async *resume(opts) {
+        yield* await this.client.streamEvents(this.info.id, opts?.after ?? -1, { mode: 'turn' });
+    }
+    mountFile(fileId, mountPath) {
+        return this.client.mountFile(this.info.id, { fileId, mountPath });
+    }
+    // Upload + mount in one step — "attach a file to the chat".
+    async attachFile(input) {
+        const file = await this.client.files.upload(input);
+        const { mount_path } = await this.mountFile(file.id, input.mountPath);
+        return { file, mount_path };
+    }
+    destroy() {
+        return this.client.sessions.destroy(this.info.id);
+    }
+}
+// Minimal SSE parser: yields the JSON payload of each `data:` frame.
+async function* parseSse(body) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for await (const chunk of body) {
+        buffer += decoder.decode(chunk, { stream: true });
+        let sep;
+        while ((sep = buffer.indexOf('\n\n')) !== -1) {
+            const frame = buffer.slice(0, sep);
+            buffer = buffer.slice(sep + 2);
+            const data = frame
+                .split('\n')
+                .filter((line) => line.startsWith('data: '))
+                .map((line) => line.slice(6))
+                .join('');
+            if (data)
+                yield JSON.parse(data);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,247 @@
+export type SessionStatus = 'provisioning' | 'running' | 'stopped' | 'failed';
+/** Turn lifecycle as clients see it — distinct from SessionStatus, which is
+ *  sandbox lifecycle. */
+export type TurnState = 'idle' | 'running' | 'awaiting_tool';
+export type ToolSource = 'builtin' | 'client' | 'mcp';
+export type AgentErrorCode = 'mcp_authentication_failed_error' | 'mcp_connection_failed_error' | 'model_request_failed_error' | 'model_overloaded_error' | 'model_rate_limited_error' | 'billing_error' | 'sandbox_failed_error' | 'unknown_error';
+export type SessionEvent = {
+    seq: number;
+    ts: string;
+} & ({
+    type: 'status';
+    status: SessionStatus;
+} | {
+    type: 'user_message';
+    text: string;
+    attachments?: Array<{
+        file_id: string;
+        name: string;
+        mime: string;
+    }>;
+} | {
+    type: 'turn_start';
+    turn: number;
+} | {
+    type: 'text_start';
+    id: string;
+} | {
+    type: 'text_delta';
+    id: string;
+    text: string;
+} | {
+    type: 'text_end';
+    id: string;
+    text: string;
+} | {
+    type: 'tool_call';
+    tool: string;
+    input: unknown;
+    id: string;
+    source: ToolSource;
+    server?: string;
+    client_executed?: boolean;
+} | {
+    type: 'tool_result';
+    tool: string;
+    output: unknown;
+    isError?: boolean;
+    id: string;
+    source: ToolSource;
+    server?: string;
+} | {
+    type: 'output_file';
+    fileId: string;
+    name: string;
+    sandboxPath: string;
+    sizeBytes: number;
+} | {
+    type: 'connect_required';
+    server: string;
+} | {
+    type: 'error';
+    code: AgentErrorCode;
+    message: string;
+    server?: string;
+    retry_status: 'terminal' | 'exhausted';
+} | {
+    type: 'turn_end';
+    reason: 'completed' | 'interrupted' | 'error';
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+    };
+});
+export type BuiltInTool = 'bash' | 'read_file' | 'write_file';
+export interface McpServer {
+    name: string;
+    url: string;
+    transport: 'http' | 'sse';
+    auth: 'none' | 'required';
+}
+export interface ClientTool<I = any> {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (input: I) => unknown | Promise<unknown>;
+    timeoutSec?: number;
+}
+export interface SkillPin {
+    skill_id: string;
+    version: number;
+}
+export interface AgentEnvironment {
+    snapshot?: string;
+    packages?: {
+        pip?: string[];
+        npm?: string[];
+        apt?: string[];
+    };
+}
+export interface Agent {
+    id: string;
+    status: 'active' | 'archived';
+    version: number;
+    name: string;
+    description: string | null;
+    model: string;
+    system: string;
+    tools: BuiltInTool[] | null;
+    metadata: Record<string, unknown> | null;
+    mcp_servers: McpServer[] | null;
+    skills: SkillPin[] | null;
+    environment: AgentEnvironment | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Skill {
+    id: string;
+    slug: string;
+    display_title: string;
+    latest_version: number;
+    created_at: string;
+}
+export interface SkillVersion {
+    version: number;
+    name: string | null;
+    description: string | null;
+    size_bytes: number;
+    created_at: string;
+}
+export interface ApiKeyInfo {
+    id: string;
+    key_prefix: string;
+    name: string | null;
+    created_at: string;
+    revoked_at: string | null;
+}
+export type McpCredentialInput = {
+    type: 'bearer';
+    token: string;
+} | {
+    type: 'oauth';
+    access_token: string;
+    refresh_token: string;
+    token_url: string;
+    client_id: string;
+    client_secret?: string;
+    scope?: string;
+    expires_at?: string;
+};
+export interface McpCredentialStatus {
+    server: string;
+    end_user_id: string | null;
+    auth_type: 'bearer' | 'oauth';
+    expires_at: string | null;
+    updated_at: string;
+}
+export interface AgentVersion {
+    version: number;
+    name: string;
+    description: string | null;
+    model: string;
+    system: string;
+    tools: BuiltInTool[] | null;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+}
+export interface CreateAgentInput {
+    skills?: SkillPin[];
+    environment?: AgentEnvironment;
+    name: string;
+    system: string;
+    model?: string;
+    description?: string | null;
+    tools?: BuiltInTool[] | null;
+    metadata?: Record<string, unknown> | null;
+    mcp_servers?: McpServer[] | null;
+}
+export type UpdateAgentInput = Partial<CreateAgentInput>;
+export interface SessionInfo {
+    id: string;
+    status: SessionStatus;
+    turn_state?: TurnState;
+    running?: boolean;
+    agentId?: string;
+    agentVersion?: number;
+    endUserId?: string | null;
+    model: string;
+    sandboxId: string | null;
+    title?: string | null;
+    metadata?: Record<string, string> | null;
+    archived?: boolean;
+    last_seq?: number;
+    events?: SessionEvent[];
+}
+export interface FileMeta {
+    id: string;
+    name: string;
+    mime: string;
+    size_bytes: number;
+    source: 'upload' | 'output';
+    session_id: string | null;
+    sandbox_path: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface UploadFileInput {
+    name: string;
+    content: string | Uint8Array;
+    mime?: string;
+}
+export interface UsageBreakdownRow {
+    input_tokens: number;
+    output_tokens: number;
+    cost_usd: number | null;
+    turns: number;
+}
+export interface UsageSummary {
+    totals: {
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+        turns: number;
+    };
+    by_model: (UsageBreakdownRow & {
+        model: string;
+    })[];
+    by_agent: (UsageBreakdownRow & {
+        agent_id: string | null;
+    })[];
+    by_user: (UsageBreakdownRow & {
+        end_user_id: string | null;
+    })[];
+}
+export interface SessionListItem {
+    id: string;
+    status: string;
+    turn_state: TurnState;
+    model: string;
+    agent_id: string | null;
+    end_user_id: string | null;
+    title: string | null;
+    metadata: Record<string, string> | null;
+    created_at: string;
+    updated_at: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Wire types for the TARS public API. The SDK is a standalone published
+// package — these are intentionally duplicated from the backend, because the
+// HTTP API (not shared code) is the contract.
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@wice24/tars-sdk",
+  "version": "0.1.0",
+  "description": "Client SDK for TARS \u2014 the self-hosted managed-agents platform (sessions, streaming turns, client tools, MCP credentials, skills, files, usage)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "@types/node": "^26.1.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "vitest": "^3.2.4"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meridian-capital/tars.git",
+    "directory": "sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agents",
+    "ai",
+    "mcp",
+    "anthropic",
+    "sdk"
+  ]
+}