@wice24/tars-sdk 0.3.0 → 0.3.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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';
+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. */
@@ -17,9 +17,9 @@ 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.
@@ -58,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[]>;
     };
@@ -96,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<{
@@ -112,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;
@@ -163,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`
@@ -177,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<{
@@ -241,6 +277,11 @@ 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;
             };
         }>;
     };
@@ -301,6 +342,8 @@ export declare class TarsClient {
         fileId: string;
         mountPath?: string;
     }): Promise<{
+        ok: boolean;
+        file_id: string;
         mount_path: string;
         size_bytes: number;
     }>;
@@ -335,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;
     }>;
@@ -349,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

@@ -67,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) => {
@@ -115,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 }),
@@ -131,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
@@ -199,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',
@@ -225,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}`),
@@ -257,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,
@@ -531,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

@@ -71,7 +71,7 @@ export type SessionEvent = {
      *  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. */
+     *  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.
@@ -96,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?: {
@@ -108,8 +145,33 @@ 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
@@ -184,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;
@@ -217,6 +282,9 @@ export interface ProviderStatusReport {
 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;
@@ -299,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
@@ -509,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.3.0",
+  "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": {