@wice24/tars-sdk 0.2.0 → 0.2.4

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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';
+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 {
@@ -124,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

@@ -155,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 = {

package/dist/types.d.ts

@@ -67,6 +67,17 @@ export type SessionEvent = {
 } & ({
     status: 'connected';
     tool_count: 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;
@@ -83,9 +94,13 @@ 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;
     };
 });
@@ -105,6 +120,20 @@ export interface McpServer {
     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;
@@ -246,6 +275,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;
@@ -269,6 +320,30 @@ 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 {
+    builtin: Array<{
+        name: BuiltInTool;
+        description: string;
+    }>;
+    client: SessionClientTool[];
+    mcp_servers: McpServer[];
+}
 export interface SessionInfo {
     id: string;
     status: SessionStatus;
@@ -288,6 +363,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.0",
+  "version": "0.2.4",
   "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": {