@wice24/tars-sdk 0.1.7 → 0.2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { Agent, AgentVersion, ClientTool, CreateAgentInput, FileMeta, McpCredentialInput, McpCredentialStatus, SessionEvent, SessionInfo, SessionListItem, UpdateAgentInput, UploadFileInput, UsageSummary, SessionUsageRow, DailyUsageRow, McpServer, Skill, SkillVersion, ApiKeyInfo, ClientIdentity, ClientRole, PlatformStats, Tenant } from './types.js';
+import type { Agent, AgentVersion, ClientTool, CreateAgentInput, FileMeta, McpCredentialInput, McpCredentialStatus, ReasoningConfig, SessionEvent, ModelInfo, SessionInfo, SessionListItem, UpdateAgentInput, UploadFileInput, UsageSummary, SessionUsageRow, DailyUsageRow, McpServer, Skill, SkillVersion, ApiKeyInfo, ClientIdentity, ClientRole, PlatformStats, Tenant } from './types.js';
 type ToolHandler = (input: any) => unknown | Promise<unknown>;
 export * from './types.js';
 export declare class TarsApiError extends Error {
@@ -11,12 +11,28 @@ export interface TarsClientOptions {
     baseUrl?: string;
     /** Injectable fetch (tests, custom agents/proxies). Defaults to global fetch. */
     fetchImpl?: typeof globalThis.fetch;
+    /**
+     * Admin keys only: scope every request to this tenant id (sent as the
+     * `X-Tars-Tenant` header). Act-as is READ-ONLY — GETs return the target
+     * tenant's data; any write is refused with 403 `act_as_read_only`, and so
+     * is live SSE (`sessions.stream` / `resumeStream` — sandbox reattachment is
+     * a side effect): read the journal via `sessions.get` / `sessions.events`
+     * instead. Non-admin keys get 403 `admin_required`; an unknown tenant id
+     * 404s on every call; an empty value 400s. The effective role is always
+     * `tenant`, so `admin.*` calls under act-as also get 403 `admin_required`
+     * — use a client WITHOUT this option to administrate.
+     */
+    actAsTenant?: string;
 }
 export declare class TarsClient {
     private readonly baseUrl;
     private readonly apiKey;
     private readonly fetchImpl;
+    private readonly actAsTenant?;
     constructor(options: TarsClientOptions);
+    /** Every request path — JSON, uploads, SSE — sends these, so act-as scoping
+     *  can never silently miss a surface. */
+    private authHeaders;
     private request;
     readonly agents: {
         create: (input: CreateAgentInput) => Promise<Agent>;
@@ -47,6 +63,8 @@ export declare class TarsClient {
             /** Appended to the agent's system prompt for this session only. */
             systemSuffix?: string;
             tools?: ClientTool[];
+            /** Per-session thinking-depth override (mirrors `model`). */
+            reasoning?: ReasoningConfig;
         }) => Promise<TarsSession>;
         list: (opts?: {
             limit?: number;
@@ -202,6 +220,20 @@ export declare class TarsClient {
      * the provider call.
      */
     providers(): Promise<string[]>;
+    /**
+     * The models this instance can route AND price — ids are full
+     * `provider/model` specs. `openrouter/*` entries mirror OpenRouter's live
+     * catalog, so those ids are guaranteed to exist right now; direct entries
+     * come from the deployment's curated pricing table. Offer models from this
+     * list rather than hardcoding ids that can drift.
+     *
+     * The list is "what is known now", not "everything routable": `openrouter`
+     * entries are absent before the instance's first successful catalog
+     * refresh, and a deployment routing only `custom/*` has no priced entries
+     * at all. When it comes back empty, fall back to `providers()` plus your
+     * own lineup instead of rendering an empty picker.
+     */
+    models(): Promise<ModelInfo[]>;
     readonly usage: {
         get: (filter?: {
             from?: string | Date;

package/dist/index.js

@@ -13,6 +13,7 @@ export class TarsClient {
     baseUrl;
     apiKey;
     fetchImpl;
+    actAsTenant;
     constructor(options) {
         if (!options.apiKey)
             throw new Error('TarsClient: apiKey is required');
@@ -20,13 +21,22 @@ export class TarsClient {
         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);
+        this.actAsTenant = options.actAsTenant;
     }
     // ── low-level HTTP ───────────────────────────────────────────
+    /** Every request path — JSON, uploads, SSE — sends these, so act-as scoping
+     *  can never silently miss a surface. */
+    authHeaders() {
+        return {
+            authorization: `Bearer ${this.apiKey}`,
+            ...(this.actAsTenant ? { 'x-tars-tenant': this.actAsTenant } : {}),
+        };
+    }
     async request(method, path, body) {
         const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
             method,
             headers: {
-                authorization: `Bearer ${this.apiKey}`,
+                ...this.authHeaders(),
                 ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
             },
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
@@ -64,6 +74,7 @@ export class TarsClient {
                 ...(input.metadata ? { metadata: input.metadata } : {}),
                 ...(input.mcpServers?.length ? { mcp_servers: input.mcpServers } : {}),
                 ...(input.systemSuffix ? { system_suffix: input.systemSuffix } : {}),
+                ...(input.reasoning ? { reasoning: input.reasoning } : {}),
                 ...(input.tools?.length
                     ? {
                         custom_tools: input.tools.map((t) => ({
@@ -155,7 +166,7 @@ export class TarsClient {
         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' },
+                headers: { ...this.authHeaders(), 'content-type': 'application/zip' },
                 body: zipBytes,
             });
             if (!res.ok)
@@ -168,7 +179,7 @@ export class TarsClient {
          */
         downloadVersion: async (id, version) => {
             const res = await this.fetchImpl(`${this.baseUrl}/v1/skills/${id}/versions/${version}/content`, {
-                headers: { authorization: `Bearer ${this.apiKey}` },
+                headers: this.authHeaders(),
             });
             if (!res.ok)
                 throw new TarsApiError(res.status, await res.json().catch(() => undefined));
@@ -228,6 +239,23 @@ export class TarsClient {
         const body = await this.request('GET', '/v1/providers');
         return body.providers ?? [];
     }
+    /**
+     * The models this instance can route AND price — ids are full
+     * `provider/model` specs. `openrouter/*` entries mirror OpenRouter's live
+     * catalog, so those ids are guaranteed to exist right now; direct entries
+     * come from the deployment's curated pricing table. Offer models from this
+     * list rather than hardcoding ids that can drift.
+     *
+     * The list is "what is known now", not "everything routable": `openrouter`
+     * entries are absent before the instance's first successful catalog
+     * refresh, and a deployment routing only `custom/*` has no priced entries
+     * at all. When it comes back empty, fall back to `providers()` plus your
+     * own lineup instead of rendering an empty picker.
+     */
+    async models() {
+        const body = await this.request('GET', '/v1/models');
+        return body.models ?? [];
+    }
     // ── usage ────────────────────────────────────────────────────
     usage = {
         // Aggregated token/cost usage for this tenant, with per-model, per-agent,
@@ -272,7 +300,7 @@ export class TarsClient {
             const res = await this.fetchImpl(`${this.baseUrl}/v1/files?name=${encodeURIComponent(input.name)}`, {
                 method: 'POST',
                 headers: {
-                    authorization: `Bearer ${this.apiKey}`,
+                    ...this.authHeaders(),
                     'content-type': input.mime ?? 'application/octet-stream',
                 },
                 body: bytes,
@@ -298,7 +326,7 @@ export class TarsClient {
         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}` },
+                headers: this.authHeaders(),
             });
             if (!res.ok || !res.body) {
                 throw new TarsApiError(res.status, await res.json().catch(() => undefined));
@@ -339,7 +367,7 @@ export class TarsClient {
         const res = await this.fetchImpl(`${this.baseUrl}/v1/sessions/${sessionId}/messages`, {
             method: 'POST',
             headers: {
-                authorization: `Bearer ${this.apiKey}`,
+                ...this.authHeaders(),
                 'content-type': 'application/json',
             },
             body: JSON.stringify({ text }),
@@ -356,7 +384,7 @@ export class TarsClient {
     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}` },
+            headers: this.authHeaders(),
         });
         if (!res.ok || !res.body) {
             const payload = await res.json().catch(() => undefined);

package/dist/types.d.ts

@@ -57,7 +57,23 @@ export type SessionEvent = {
 } | {
     type: 'connect_required';
     server: string;
+}
+/** Every MCP dial's OUTCOME, successes included (one per server per turn):
+ *  `connect_required`/`error` cover only the failure paths — this is the
+ *  diagnostic twin that makes a healthy connector visible. */
+ | ({
+    type: 'mcp_connect';
+    server: string;
+} & ({
+    status: 'connected';
+    tool_count: number;
+} | {
+    status: 'failed';
+    code: AgentErrorCode;
+    message: string;
 } | {
+    status: 'missing_credential';
+})) | {
     type: 'error';
     code: AgentErrorCode;
     message: string;
@@ -73,7 +89,17 @@ export type SessionEvent = {
         cacheWriteTokens?: number;
     };
 });
-export type BuiltInTool = 'bash' | 'read_file' | 'write_file';
+export type BuiltInTool = 'bash' | 'read_file' | 'write_file' | 'edit_file' | 'glob' | 'grep' | 'web_fetch';
+/**
+ * Extended-thinking depth. Provider-neutral: TARS maps it to Anthropic's
+ * `effort` (with adaptive thinking) or OpenRouter's `reasoning.effort`
+ * (`max` → `xhigh`). Omit for the provider default. The reasoning text itself
+ * is never streamed or journaled — only its depth is configurable.
+ */
+export type ReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+export interface ReasoningConfig {
+    effort: ReasoningEffort;
+}
 export interface McpServer {
     name: string;
     url: string;
@@ -112,6 +138,7 @@ export interface Agent {
     mcp_servers: McpServer[] | null;
     skills: SkillPin[] | null;
     environment: AgentEnvironment | null;
+    reasoning: ReasoningConfig | null;
     created_at: string;
     updated_at: string;
 }
@@ -129,6 +156,24 @@ export interface SkillVersion {
     size_bytes: number;
     created_at: string;
 }
+/** One routable-and-priced model from `GET /v1/models`. Prices are USD per
+ *  million tokens; `id` is the full `provider/model` spec, usable as-is when
+ *  creating agents/sessions. The list is "what is known now" — see
+ *  `TarsClient.models()` for the empty/partial cases. */
+export interface ModelInfo {
+    id: string;
+    name: string;
+    pricing: {
+        input: number;
+        output: number;
+        /** Absent ≠ free: TARS bills an unpublished cache-read price at the
+         *  `input` rate (conservative upper bound). */
+        cache_read?: number;
+        /** Absent ≠ free: billed at the `input` rate when unpublished. Providers
+         *  with genuinely free cache writes report an explicit 0. */
+        cache_write?: number;
+    };
+}
 export interface ApiKeyInfo {
     id: string;
     key_prefix: string;
@@ -214,6 +259,7 @@ export interface AgentVersion {
 export interface CreateAgentInput {
     skills?: SkillPin[];
     environment?: AgentEnvironment;
+    reasoning?: ReasoningConfig | null;
     name: string;
     system: string;
     model?: string;
@@ -242,6 +288,25 @@ export interface SessionInfo {
         input_schema: Record<string, unknown>;
         timeout_sec?: number;
     }> | null;
+    /**
+     * The EFFECTIVE system prompt the session's turns run with — agent base
+     * prompt + session system_suffix + skills appendix, fused at creation.
+     * Optional: absent from servers predating this field.
+     */
+    system_prompt?: string;
+    /**
+     * The EFFECTIVE thinking depth the session's turns run with (the agent's,
+     * or the per-session override). null = provider default; absent from
+     * servers predating this field.
+     */
+    reasoning?: ReasoningConfig | null;
+    /**
+     * The un-merged per-session suffix, when a non-empty one was passed at
+     * creation. Also null on sessions created before this release: the audit
+     * column went unwritten historically (the suffix is still fused into
+     * system_prompt there), and old rows cannot be backfilled.
+     */
+    system_suffix?: string | null;
     archived?: boolean;
     last_seq?: number;
     events?: SessionEvent[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wice24/tars-sdk",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Client SDK for TARS — the self-hosted managed-agents platform (sessions, streaming turns, client tools, MCP credentials, skills, files, usage, tenant administration)",
   "type": "module",
   "exports": {