@wice24/tars-sdk 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-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';
+import type { Agent, AgentVersion, ClientTool, CreateAgentInput, FileMeta, ListMcpToolsInput, McpCredentialInput, McpCredentialStatus, McpServerTools, ReasoningConfig, SessionEvent, ModelInfo, ProviderKeys, ProviderStatusReport, 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';
+/** The providers `providerKeys` accepts. */
+export declare const KEYED_PROVIDERS: readonly ["anthropic", "openai", "openrouter", "tensorx"];
 export declare class TarsApiError extends Error {
     readonly status: number;
     readonly body: unknown;
@@ -23,12 +25,27 @@ export interface TarsClientOptions {
      * — use a client WITHOUT this option to administrate.
      */
     actAsTenant?: string;
+    /**
+     * Your own LLM provider keys, by provider (`openrouter`, `openai`,
+     * `anthropic`, `tensorx`). Sent with EVERY request (one
+     * `x-tars-key-<provider>` header each) and used for that request's model
+     * calls — session turns, completions, the model catalog — so usage bills to
+     * your provider accounts. TARS never stores them. A provider you omit
+     * routes on the instance's key only while that instance's cutover fallback
+     * is on; otherwise its models are refused with 400
+     * `provider_not_configured`. Check with `providerStatus()`.
+     *
+     * SERVER-SIDE clients only: in a browser these keys would ship to every
+     * user of your app.
+     */
+    providerKeys?: ProviderKeys;
 }
 export declare class TarsClient {
     private readonly baseUrl;
     private readonly apiKey;
     private readonly fetchImpl;
     private readonly actAsTenant?;
+    private readonly providerKeyHeaders;
     constructor(options: TarsClientOptions);
     /** Every request path — JSON, uploads, SSE — sends these, so act-as scoping
      *  can never silently miss a surface. */
@@ -228,20 +245,28 @@ export declare class TarsClient {
         }>;
     };
     /**
-     * Which model providers this instance is keyed for (`anthropic`, `openai`,
-     * `openrouter`, `custom`). Ask before OFFERING models: a picker listing GPT
-     * models on an instance with no OpenAI key produces turns that all fail at
-     * the provider call.
+     * Which model providers YOU can route now (`anthropic`, `openai`,
+     * `openrouter`, `tensorx`, `custom`): those you passed in `providerKeys`,
+     * plus the instance's while its cutover fallback is on, plus `custom` on an
+     * instance pointed at a local runtime. Ask before OFFERING models: a picker
+     * listing GPT models without an OpenAI key produces turns that all fail.
      */
     providers(): Promise<string[]>;
+    /**
+     * Every provider with whether you can route it and on whose key
+     * (`request` = your `providerKeys`, `instance` = the deployment's), plus
+     * whether the instance still falls back to its own keys. What a settings
+     * page shows: all providers, the inactive ones disabled.
+     */
+    providerStatus(): Promise<ProviderStatusReport>;
     /**
      * 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
+     * `provider/model` specs. `openrouter/*` and `tensorx/*` entries mirror
+     * those providers' live catalogs, so those ids 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`
+     * The list is "what is known now", not "everything routable": catalog
      * 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

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from './types.js';
+/** The providers `providerKeys` accepts. */
+export const KEYED_PROVIDERS = ['anthropic', 'openai', 'openrouter', 'tensorx'];
 export class TarsApiError extends Error {
     status;
     body;
@@ -14,6 +16,7 @@ export class TarsClient {
     apiKey;
     fetchImpl;
     actAsTenant;
+    providerKeyHeaders;
     constructor(options) {
         if (!options.apiKey)
             throw new Error('TarsClient: apiKey is required');
@@ -22,6 +25,13 @@ export class TarsClient {
         // Bind: an unbound global fetch throws "Illegal invocation" in browsers.
         this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
         this.actAsTenant = options.actAsTenant;
+        const unknown = Object.keys(options.providerKeys ?? {}).filter((p) => !KEYED_PROVIDERS.includes(p));
+        if (unknown.length > 0) {
+            throw new Error(`TarsClient: unknown providerKeys ${unknown.join(', ')} (expected ${KEYED_PROVIDERS.join(', ')})`);
+        }
+        this.providerKeyHeaders = Object.fromEntries(Object.entries(options.providerKeys ?? {})
+            .filter(([, key]) => typeof key === 'string' && key.trim() !== '')
+            .map(([provider, key]) => [`x-tars-key-${provider}`, key.trim()]));
     }
     // ── low-level HTTP ───────────────────────────────────────────
     /** Every request path — JSON, uploads, SSE — sends these, so act-as scoping
@@ -30,6 +40,7 @@ export class TarsClient {
         return {
             authorization: `Bearer ${this.apiKey}`,
             ...(this.actAsTenant ? { 'x-tars-tenant': this.actAsTenant } : {}),
+            ...this.providerKeyHeaders,
         };
     }
     async request(method, path, body) {
@@ -176,6 +187,8 @@ export class TarsClient {
                 params.set('auth', input.auth);
             if (input.endUserId)
                 params.set('end_user_id', input.endUserId);
+            if (input.schemas)
+                params.set('schemas', '1');
             return this.request('GET', `/v1/mcp-servers/tools?${params}`);
         },
     };
@@ -254,23 +267,33 @@ export class TarsClient {
         }),
     };
     /**
-     * Which model providers this instance is keyed for (`anthropic`, `openai`,
-     * `openrouter`, `custom`). Ask before OFFERING models: a picker listing GPT
-     * models on an instance with no OpenAI key produces turns that all fail at
-     * the provider call.
+     * Which model providers YOU can route now (`anthropic`, `openai`,
+     * `openrouter`, `tensorx`, `custom`): those you passed in `providerKeys`,
+     * plus the instance's while its cutover fallback is on, plus `custom` on an
+     * instance pointed at a local runtime. Ask before OFFERING models: a picker
+     * listing GPT models without an OpenAI key produces turns that all fail.
      */
     async providers() {
         const body = await this.request('GET', '/v1/providers');
         return body.providers ?? [];
     }
+    /**
+     * Every provider with whether you can route it and on whose key
+     * (`request` = your `providerKeys`, `instance` = the deployment's), plus
+     * whether the instance still falls back to its own keys. What a settings
+     * page shows: all providers, the inactive ones disabled.
+     */
+    async providerStatus() {
+        return this.request('GET', '/v1/providers/status');
+    }
     /**
      * 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
+     * `provider/model` specs. `openrouter/*` and `tensorx/*` entries mirror
+     * those providers' live catalogs, so those ids 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`
+     * The list is "what is known now", not "everything routable": catalog
      * 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

package/dist/types.d.ts

@@ -67,6 +67,23 @@ export type SessionEvent = {
 } & ({
     status: 'connected';
     tool_count: number;
+    /** Estimated tokens this server's kept tool definitions (names,
+     *  descriptions, input schemas) add to every request of the turn,
+     *  at ~4 chars/token — size connectors against each other and
+     *  against the rest of the prompt. Absent on rows journaled
+     *  before 0.2.5. */
+    schema_tokens?: number;
+    /** The tool names the model received from this server (its own
+     *  unprefixed names, in server order) — what `tool_count` counts.
+     *  Absent on rows journaled by servers before 0.2.4. */
+    tools?: string[];
+    /** Offered by the server but removed by the declaration's policy:
+     *  the `blocked_tools` it offered (deny), or everything not in
+     *  `tools` (allow). Empty with no policy. Absent before 0.2.4. */
+    filtered_out?: string[];
+    /** Either list was cut — at 256 names, a 200-character name, or
+     *  the row's character budget; `tool_count` stays exact. */
+    truncated?: true;
 } | {
     status: 'failed';
     code: AgentErrorCode;
@@ -96,8 +113,9 @@ export type SessionEvent = {
 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
+ * `effort` (with adaptive thinking), OpenRouter's `reasoning.effort`
+ * (`max` → `xhigh`), or TensorX's `reasoning_effort` (`xhigh`/`max` →
+ * `high`; models there may ignore it). 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';
@@ -174,6 +192,24 @@ export interface SkillVersion {
     size_bytes: number;
     created_at: string;
 }
+/** Providers a client brings its own key for (`TarsClientOptions.providerKeys`). */
+export type KeyedProvider = 'anthropic' | 'openai' | 'openrouter' | 'tensorx';
+/** Every routable provider; `custom` is configured per instance, never per client. */
+export type ProviderName = KeyedProvider | 'custom';
+export type ProviderKeys = Partial<Record<KeyedProvider, string>>;
+export interface ProviderStatus {
+    provider: ProviderName;
+    /** Can this client route a model on it right now? */
+    active: boolean;
+    /** Whose key would route it: yours (`request`), the instance's, or none. */
+    source: 'request' | 'instance' | null;
+}
+export interface ProviderStatusReport {
+    providers: ProviderStatus[];
+    /** True while the instance still routes providers you sent no key for on
+     *  its own keys (the cutover fallback). */
+    instance_fallback: boolean;
+}
 /** 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
@@ -275,12 +311,34 @@ export interface ListMcpToolsInput {
     /** 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;
+    /** Also return each tool's `input_schema` and its FULL description — the
+     *  exact definition the model is shown, for weighing a connector's prompt
+     *  cost per tool. Off (default): picker shape, descriptions capped. */
+    schemas?: boolean;
 }
 /** One tool as the server lists it. `description` is capped at 500
- *  characters (an ellipsis marks a cut); `null` when the server gave none. */
+ *  characters (an ellipsis marks a cut) unless `schemas` was requested;
+ *  `null` when the server gave none. */
+/** The MCP spec's tool annotations, as the server sent them (these five
+ *  keys only). Hints for grouping and labelling tools in a picker, never
+ *  guarantees: a policy (`tools` / `blocked_tools`) must not trust them. */
+export interface McpToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
 export interface McpToolInfo {
     name: string;
     description: string | null;
+    /** Human-readable name: the tool's `title`, else `annotations.title`,
+     *  else null when the server gave neither. */
+    title: string | null;
+    /** The server's annotations; null when it sent none. */
+    annotations: McpToolAnnotations | null;
+    /** The input JSON Schema as listed — present only with `schemas: true`. */
+    input_schema?: Record<string, unknown>;
 }
 export interface McpServerTools {
     server: string;
@@ -309,6 +367,33 @@ export interface CreateAgentInput {
     mcp_servers?: McpServer[] | null;
 }
 export type UpdateAgentInput = Partial<CreateAgentInput>;
+/** A client-executed tool as a session stores it: the wire declaration,
+ *  without `execute` (that runs in your app) — the same shape as a
+ *  `SessionInfo.custom_tools` element. */
+export interface SessionClientTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    timeout_sec?: number;
+}
+/**
+ * The complete tool surface a session's turns are built with, as declared:
+ * the enabled built-ins with the descriptions the model is shown, the
+ * client-executed tools, and the MCP servers with their `tools` /
+ * `blocked_tools` policy. What each MCP server actually contributed on a
+ * given turn is in that turn's `mcp_connect` event (`tools` / `filtered_out`).
+ */
+export interface SessionToolSurface {
+    /** `input_schema`: the JSON Schema (draft-7) the model is shown for the
+     *  tool — size it to know what the built-ins cost in context. */
+    builtin: Array<{
+        name: BuiltInTool;
+        description: string;
+        input_schema: Record<string, unknown>;
+    }>;
+    client: SessionClientTool[];
+    mcp_servers: McpServer[];
+}
 export interface SessionInfo {
     id: string;
     status: SessionStatus;
@@ -328,6 +413,12 @@ export interface SessionInfo {
         input_schema: Record<string, unknown>;
         timeout_sec?: number;
     }> | null;
+    /**
+     * The declared tool surface (built-ins, client tools, MCP servers with
+     * policy) the session's turns run with. Optional: absent from servers
+     * predating this field.
+     */
+    tools?: SessionToolSurface;
     /**
      * The EFFECTIVE system prompt the session's turns run with — agent base
      * prompt + session system_suffix + skills appendix, fused at creation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wice24/tars-sdk",
-  "version": "0.2.3",
+  "version": "0.3.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": {
@@ -12,13 +12,6 @@
   "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",
@@ -40,5 +33,12 @@
     "mcp",
     "anthropic",
     "sdk"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}