@wice24/tars-sdk 0.1.8 → 0.2.3

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { Agent, AgentVersion, ClientTool, CreateAgentInput, FileMeta, McpCredentialInput, McpCredentialStatus, SessionEvent, ModelInfo, 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, ListMcpToolsInput, McpCredentialInput, McpCredentialStatus, McpServerTools, 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;
@@ -106,6 +124,20 @@ export declare class TarsClient {
             ok: boolean;
         }>;
     };
+    readonly mcp: {
+        /**
+         * Dial an MCP server once with the stored credential, list its tools, hang
+         * up — no session, nothing journaled. The source of truth for writing a
+         * `tools` / `blocked_tools` policy: what the server offers NOW, not what a
+         * registry says. Throws `TarsApiError` 404 `missing_credential` when
+         * `auth: 'required'` and no credential is stored for the end user or the
+         * tenant (none stored, or its refresh failed), 502 with the turn-time code
+         * (`mcp_authentication_failed_error` / `mcp_connection_failed_error`) when
+         * the dial fails or times out (15 s), and 503 `internal_error` when TARS's
+         * own credential store is unavailable.
+         */
+        listTools: (input: ListMcpToolsInput) => Promise<McpServerTools>;
+    };
     readonly skills: {
         create: (input: {
             slug: string;

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) => ({
@@ -144,6 +155,30 @@ export class TarsClient {
             return this.request('DELETE', `/v1/mcp-credentials?${params}`);
         },
     };
+    // ── MCP servers ──────────────────────────────────────────────
+    mcp = {
+        /**
+         * Dial an MCP server once with the stored credential, list its tools, hang
+         * up — no session, nothing journaled. The source of truth for writing a
+         * `tools` / `blocked_tools` policy: what the server offers NOW, not what a
+         * registry says. Throws `TarsApiError` 404 `missing_credential` when
+         * `auth: 'required'` and no credential is stored for the end user or the
+         * tenant (none stored, or its refresh failed), 502 with the turn-time code
+         * (`mcp_authentication_failed_error` / `mcp_connection_failed_error`) when
+         * the dial fails or times out (15 s), and 503 `internal_error` when TARS's
+         * own credential store is unavailable.
+         */
+        listTools: (input) => {
+            const params = new URLSearchParams({ name: input.name, url: input.url });
+            if (input.transport)
+                params.set('transport', input.transport);
+            if (input.auth)
+                params.set('auth', input.auth);
+            if (input.endUserId)
+                params.set('end_user_id', input.endUserId);
+            return this.request('GET', `/v1/mcp-servers/tools?${params}`);
+        },
+    };
     // ── skills ───────────────────────────────────────────────────
     // Versioned skill bundles (zip with SKILL.md at root), pinned per agent.
     skills = {
@@ -155,7 +190,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 +203,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));
@@ -289,7 +324,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,
@@ -315,7 +350,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));
@@ -356,7 +391,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 }),
@@ -373,7 +408,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;
@@ -67,18 +83,46 @@ export type SessionEvent = {
     type: 'turn_end';
     reason: 'completed' | 'interrupted' | 'error';
     usage?: {
+        /** UNCACHED input tokens only. Cache reads and writes are reported
+         *  separately below, so the full prompt is the sum of all three. */
         inputTokens?: number;
         outputTokens?: number;
+        /** Input tokens served from the provider's prompt cache. */
         cacheReadTokens?: number;
+        /** Input tokens written to the provider's prompt cache. */
         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;
     transport: 'http' | 'sse';
     auth: 'none' | 'required';
+    /**
+     * Expose only these of the server's tools to the model (its own names, as
+     * the server lists them — not the `server__tool` prefixed form). Omitted or
+     * null = every tool. Names the server doesn't offer are ignored. Non-empty,
+     * ≤256 entries, no duplicates. Mutually exclusive with `blocked_tools`.
+     */
+    tools?: string[] | null;
+    /**
+     * Hide these of the server's tools from the model and expose every other
+     * one — the complement of `tools`, for a connector that is on by default
+     * and needs a few tools removed without naming the whole inventory. Same
+     * validation as `tools`; setting both is a `validation_error`.
+     */
+    blocked_tools?: string[] | null;
 }
 export interface ClientTool<I = any> {
     name: string;
@@ -112,6 +156,7 @@ export interface Agent {
     mcp_servers: McpServer[] | null;
     skills: SkillPin[] | null;
     environment: AgentEnvironment | null;
+    reasoning: ReasoningConfig | null;
     created_at: string;
     updated_at: string;
 }
@@ -219,6 +264,28 @@ export interface McpCredentialStatus {
     expires_at: string | null;
     updated_at: string;
 }
+/** How `mcp.listTools` names the server: the same fields a declaration
+ *  carries (so the credential lookup and the dial match a turn's), plus whose
+ *  credential to use. `transport` defaults to `'http'`, `auth` to `'none'`. */
+export interface ListMcpToolsInput {
+    name: string;
+    url: string;
+    transport?: 'http' | 'sse';
+    auth?: 'none' | 'required';
+    /** Resolve this end user's credential first, then the tenant-level one;
+     *  omit for tenant-level only. Only read when `auth` is `'required'`. */
+    endUserId?: string;
+}
+/** One tool as the server lists it. `description` is capped at 500
+ *  characters (an ellipsis marks a cut); `null` when the server gave none. */
+export interface McpToolInfo {
+    name: string;
+    description: string | null;
+}
+export interface McpServerTools {
+    server: string;
+    tools: McpToolInfo[];
+}
 export interface AgentVersion {
     version: number;
     name: string;
@@ -232,6 +299,7 @@ export interface AgentVersion {
 export interface CreateAgentInput {
     skills?: SkillPin[];
     environment?: AgentEnvironment;
+    reasoning?: ReasoningConfig | null;
     name: string;
     system: string;
     model?: string;
@@ -260,6 +328,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.8",
+  "version": "0.2.3",
   "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": {