@wice24/tars-sdk 0.2.4 → 0.3.1

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, CompactResult, 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;
@@ -15,20 +17,35 @@ export interface TarsClientOptions {
      * 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
+     * is live SSE (`streamEvents` / `TarsSession.stream` / `resume` — 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;
+    /**
+     * 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. */
@@ -41,11 +58,15 @@ export declare class TarsClient {
         }) => Promise<Agent[]>;
         get: (id: string) => Promise<Agent>;
         update: (id: string, patch: UpdateAgentInput) => Promise<Agent>;
+        /** Archived agents refuse new sessions (409) and updates; existing
+         *  sessions keep running. */
         archive: (id: string) => Promise<{
             ok: boolean;
+            status: "archived";
         }>;
         unarchive: (id: string) => Promise<{
             ok: boolean;
+            status: "active";
         }>;
         versions: (id: string) => Promise<AgentVersion[]>;
     };
@@ -79,6 +100,20 @@ export declare class TarsClient {
         rename: (id: string, title: string) => Promise<{
             ok: boolean;
         }>;
+        /**
+         * One page of the session's journal — the same events `get()` inlines,
+         * for incremental readers on long sessions. `afterSeq` is the last seq
+         * you hold (-1 = from the start); `limit` 1..1000 (default 500).
+         * `has_more` says another page follows. Allowed under act-as, unlike the
+         * live stream.
+         */
+        events: (id: string, opts?: {
+            afterSeq?: number;
+            limit?: number;
+        }) => Promise<{
+            events: SessionEvent[];
+            has_more: 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<{
@@ -95,6 +130,17 @@ export declare class TarsClient {
             ok: boolean;
             interrupted: boolean;
         }>;
+        /**
+         * Compact the session's context now: the older history is folded into a
+         * checkpoint summary and the recent tail kept verbatim — what the
+         * platform does on its own as a session nears its model's context
+         * window (the `compaction` event either way). Idle sessions only
+         * (`turn_in_progress` otherwise). `instructions` is an optional focus
+         * for the summary ("keep every SQL statement verbatim").
+         */
+        compact: (id: string, opts?: {
+            instructions?: string;
+        }) => Promise<CompactResult>;
         usage: (id: string) => Promise<{
             session_id: string;
             model: string;
@@ -146,12 +192,17 @@ export declare class TarsClient {
         list: () => Promise<Skill[]>;
         get: (id: string) => Promise<Skill>;
         versions: (id: string) => Promise<SkillVersion[]>;
-        /** Upload a new immutable version from zip bytes. */
+        /** Upload a new immutable version from zip bytes. `name` / `description`
+         *  are what SKILL.md's front matter declared (null when absent); `files`
+         *  counts the bundle's entries. */
         pushVersion: (id: string, zipBytes: Uint8Array) => Promise<{
             skill_id: string;
             slug: string;
             version: number;
+            name: string | null;
+            description: string | null;
             files: number;
+            size_bytes: number;
         }>;
         /**
          * Download one immutable version's zip bytes — exactly what `pushVersion`
@@ -160,12 +211,14 @@ export declare class TarsClient {
         downloadVersion: (id: string, version: number) => Promise<Uint8Array>;
     };
     readonly apiKeys: {
+        /** Mint another key for this tenant. `key` is returned ONCE. */
         create: (input?: {
             name?: string;
         }) => Promise<{
             id: string;
             key: string;
             key_prefix: string;
+            name: string | null;
         }>;
         list: () => Promise<ApiKeyInfo[]>;
         revoke: (id: string) => Promise<{
@@ -224,24 +277,37 @@ export declare class TarsClient {
             usage: {
                 input_tokens: number;
                 output_tokens: number;
+                cache_read_tokens: number;
+                cache_write_tokens: number;
+                cost_usd?: number;
+                cost_source?: "provider";
+                upstream_cost_usd?: number;
             };
         }>;
     };
     /**
-     * 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
@@ -276,6 +342,8 @@ export declare class TarsClient {
         fileId: string;
         mountPath?: string;
     }): Promise<{
+        ok: boolean;
+        file_id: string;
         mount_path: string;
         size_bytes: number;
     }>;
@@ -310,6 +378,8 @@ export declare class TarsSession {
         after?: number;
     }): AsyncGenerator<SessionEvent>;
     mountFile(fileId: string, mountPath?: string): Promise<{
+        ok: boolean;
+        file_id: string;
         mount_path: string;
         size_bytes: number;
     }>;
@@ -324,6 +394,10 @@ export declare class TarsSession {
         ok: boolean;
         interrupted: boolean;
     }>;
+    /** Compact the context now — see `TarsClient.sessions.compact`. */
+    compact(opts?: {
+        instructions?: string;
+    }): Promise<CompactResult>;
     destroy(): Promise<{
         ok: boolean;
     }>;

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) {
@@ -56,6 +67,8 @@ export class TarsClient {
         },
         get: (id) => this.request('GET', `/v1/agents/${id}`),
         update: (id, patch) => this.request('PATCH', `/v1/agents/${id}`, patch),
+        /** Archived agents refuse new sessions (409) and updates; existing
+         *  sessions keep running. */
         archive: (id) => this.request('POST', `/v1/agents/${id}/archive`),
         unarchive: (id) => this.request('POST', `/v1/agents/${id}/unarchive`),
         versions: async (id) => {
@@ -104,6 +117,22 @@ export class TarsClient {
             return { sessions: res.sessions, nextCursor: res.next_cursor };
         },
         rename: (id, title) => this.request('PATCH', `/v1/sessions/${id}`, { title }),
+        /**
+         * One page of the session's journal — the same events `get()` inlines,
+         * for incremental readers on long sessions. `afterSeq` is the last seq
+         * you hold (-1 = from the start); `limit` 1..1000 (default 500).
+         * `has_more` says another page follows. Allowed under act-as, unlike the
+         * live stream.
+         */
+        events: async (id, opts) => {
+            const params = new URLSearchParams();
+            if (opts?.afterSeq !== undefined)
+                params.set('after_seq', String(opts.afterSeq));
+            if (opts?.limit)
+                params.set('limit', String(opts.limit));
+            const qs = params.size ? `?${params}` : '';
+            return this.request('GET', `/v1/sessions/${id}/events${qs}`);
+        },
         /** 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 }),
@@ -120,6 +149,15 @@ export class TarsClient {
         }),
         /** Abort the in-flight turn, if any. Idempotent. */
         interrupt: (id) => this.request('POST', `/v1/sessions/${id}/interrupt`),
+        /**
+         * Compact the session's context now: the older history is folded into a
+         * checkpoint summary and the recent tail kept verbatim — what the
+         * platform does on its own as a session nears its model's context
+         * window (the `compaction` event either way). Idle sessions only
+         * (`turn_in_progress` otherwise). `instructions` is an optional focus
+         * for the summary ("keep every SQL statement verbatim").
+         */
+        compact: (id, opts) => this.request('POST', `/v1/sessions/${id}/compact`, opts ?? {}),
         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
@@ -176,6 +214,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}`);
         },
     };
@@ -186,7 +226,9 @@ export class TarsClient {
         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. */
+        /** Upload a new immutable version from zip bytes. `name` / `description`
+         *  are what SKILL.md's front matter declared (null when absent); `files`
+         *  counts the bundle's entries. */
         pushVersion: async (id, zipBytes) => {
             const res = await this.fetchImpl(`${this.baseUrl}/v1/skills/${id}/versions`, {
                 method: 'POST',
@@ -212,6 +254,7 @@ export class TarsClient {
     };
     // ── api keys / identity ──────────────────────────────────────
     apiKeys = {
+        /** Mint another key for this tenant. `key` is returned ONCE. */
         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}`),
@@ -244,7 +287,14 @@ export class TarsClient {
     };
     // ── completions / providers (any key) ────────────────────────
     // Cheap non-session completion (titles and other one-shots) — routed
-    // through the same provider seam as agent turns.
+    // through the same provider seam as agent turns, on this client's
+    // `providerKeys` (400 `provider_not_configured` when the model's provider
+    // is not routable). `maxTokens` defaults to 256 and is capped at 1024;
+    // `model` defaults to `openrouter/anthropic/claude-haiku-4-5`. In `usage`,
+    // the cache counts make a caching claim checkable from outside; `cost_usd`
+    // is present only when the provider reported a bill (`cost_source:
+    // 'provider'`), and `upstream_cost_usd`, under BYOK through OpenRouter, is
+    // what the vendor charged the key's owner.
     completions = {
         create: (input) => this.request('POST', '/v1/completions', {
             prompt: input.prompt,
@@ -254,23 +304,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
@@ -508,6 +568,10 @@ export class TarsSession {
     interrupt() {
         return this.client.sessions.interrupt(this.info.id);
     }
+    /** Compact the context now — see `TarsClient.sessions.compact`. */
+    compact(opts) {
+        return this.client.sessions.compact(this.info.id, opts);
+    }
     destroy() {
         return this.client.sessions.destroy(this.info.id);
     }

package/dist/types.d.ts

@@ -67,6 +67,12 @@ 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.3.0. */
+    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. */
@@ -90,7 +96,44 @@ export type SessionEvent = {
     message: string;
     server?: string;
     retry_status: 'terminal' | 'exhausted';
+}
+/**
+ * Context compaction: the older history was folded into a summary
+ * checkpoint and the recent tail kept verbatim, so the session stays under
+ * the model's context window. Nested discriminant on `status`, like
+ * mcp_connect: `started` opens the (possibly long) summarization,
+ * `completed` carries the checkpoint the model now runs on, `failed` says
+ * the history is unchanged. `reason`: `auto` = the threshold check before
+ * a model call, `overflow` = the provider rejected the prompt as too long,
+ * `manual` = `sessions.compact()`.
+ */
+ | ({
+    type: 'compaction';
+    reason: CompactionReason;
+} & ({
+    status: 'started';
 } | {
+    status: 'completed';
+    /** The checkpoint text the model sees in place of the summarized
+     *  messages — the tenant-visible record of what was kept. */
+    summary: string;
+    /** Estimated prompt tokens before and after (chars/4 over the
+     *  history; the provider's own count lands on the next turn_end). */
+    tokens_before: number;
+    tokens_after: number;
+    /** How many history messages the summary replaced, and how many
+     *  recent ones stayed verbatim after it. */
+    summarized_messages: number;
+    kept_messages: number;
+    /** The model that wrote the summary; `fallback` when the
+     *  summarizer failed during overflow recovery and a deterministic
+     *  checkpoint (the dropped requests, listed) was written instead. */
+    model: string;
+} | {
+    status: 'failed';
+    code: AgentErrorCode;
+    message: string;
+})) | {
     type: 'turn_end';
     reason: 'completed' | 'interrupted' | 'error';
     usage?: {
@@ -102,13 +145,39 @@ export type SessionEvent = {
         cacheReadTokens?: number;
         /** Input tokens written to the provider's prompt cache. */
         cacheWriteTokens?: number;
+        /** The LAST model step's full prompt size (uncached + cache read +
+         *  cache write) as the provider counted it — what the next turn
+         *  starts from, and the exact figure for a context gauge. The
+         *  buckets above are SUMS over the turn's steps. Absent on turns
+         *  that ended before a step completed. */
+        contextTokens?: number;
     };
 });
+/** Why a compaction ran — see the `compaction` event. */
+export type CompactionReason = 'auto' | 'overflow' | 'manual';
+/** `sessions.compact()` — the no-op success (`compacted: false`) means the
+ *  history was too short to fold; a summarizer failure is a thrown
+ *  `TarsApiError` (502, code `compaction_failed`) and leaves the history as
+ *  is. */
+export type CompactResult = {
+    ok: true;
+    compacted: true;
+    /** Estimated prompt tokens before and after (chars/4 over the history). */
+    tokens_before: number;
+    tokens_after: number;
+    summarized_messages: number;
+    kept_messages: number;
+} | {
+    ok: true;
+    compacted: false;
+    reason: 'nothing_to_compact';
+};
 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';
@@ -177,6 +246,9 @@ export interface Skill {
     display_title: string;
     latest_version: number;
     created_at: string;
+    /** Present on `get()` / `list()`; the `create()` echo omits both. */
+    client_id?: string;
+    updated_at?: string;
 }
 export interface SkillVersion {
     version: number;
@@ -185,6 +257,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
@@ -192,6 +282,9 @@ export interface SkillVersion {
 export interface ModelInfo {
     id: string;
     name: string;
+    /** Context window in tokens, when the provider's catalog publishes one
+     *  (OpenRouter, TensorX). Absent for the direct routes. */
+    context_window?: number;
     pricing: {
         input: number;
         output: number;
@@ -274,6 +367,9 @@ export interface McpCredentialStatus {
     auth_type: 'bearer' | 'oauth';
     expires_at: string | null;
     updated_at: string;
+    /** Can TARS renew this credential itself? `false` on an oauth credential
+     *  means it will dead-end at `connect_required` when it expires. */
+    refreshable: boolean;
 }
 /** 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
@@ -286,12 +382,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;
@@ -337,9 +455,12 @@ export interface SessionClientTool {
  * 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[];
@@ -459,8 +580,12 @@ export interface DailyUsageRow {
 }
 export interface SessionListItem {
     id: string;
+    /** A `SessionStatus` value (typed loosely for compatibility). */
     status: string;
     turn_state: TurnState;
+    /** Only meaningful with `includeArchived`; absent from servers predating
+     *  this field. */
+    archived?: boolean;
     model: string;
     agent_id: string | null;
     end_user_id: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wice24/tars-sdk",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "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"
+  }
+}