@agenttool/sdk 0.2.1 → 0.2.2

package/dist/client.d.ts

@@ -4,6 +4,7 @@
 import { EconomyClient } from "./economy.js";
 import { MemoryClient } from "./memory.js";
 import { ToolsClient } from "./tools.js";
+import { TracesClient } from "./traces.js";
 import { VerifyClient } from "./verify.js";
 /**
  * Unified client for the agenttool.dev platform.
@@ -20,6 +21,7 @@ import { VerifyClient } from "./verify.js";
  * const out = await at.tools.execute("print(42)");      // sandbox
  * const v = await at.verify.check("claim");             // verify
  * const w = await at.economy.createWallet({ name: "w" }); // wallet
+ * const t = await at.traces.store({ observations: ["saw X"], conclusion: "do Y" }); // trace
  * ```
  */
 export declare class AgentTool {
@@ -28,6 +30,7 @@ export declare class AgentTool {
     private _tools;
     private _verify;
     private _economy;
+    private _traces;
     /**
      * Create a new AgentTool client.
      *
@@ -46,5 +49,7 @@ export declare class AgentTool {
     get verify(): VerifyClient;
     /** Access the Economy/Wallet API. */
     get economy(): EconomyClient;
+    /** Access the Traces (reasoning provenance) API. */
+    get traces(): TracesClient;
     toString(): string;
 }

package/dist/client.js

@@ -5,6 +5,7 @@ import { AgentToolError } from "./errors.js";
 import { EconomyClient } from "./economy.js";
 import { MemoryClient } from "./memory.js";
 import { ToolsClient } from "./tools.js";
+import { TracesClient } from "./traces.js";
 import { VerifyClient } from "./verify.js";
 /**
  * Unified client for the agenttool.dev platform.
@@ -21,6 +22,7 @@ import { VerifyClient } from "./verify.js";
  * const out = await at.tools.execute("print(42)");      // sandbox
  * const v = await at.verify.check("claim");             // verify
  * const w = await at.economy.createWallet({ name: "w" }); // wallet
+ * const t = await at.traces.store({ observations: ["saw X"], conclusion: "do Y" }); // trace
  * ```
  */
 export class AgentTool {
@@ -29,6 +31,7 @@ export class AgentTool {
     _tools;
     _verify;
     _economy;
+    _traces;
     /**
      * Create a new AgentTool client.
      *
@@ -70,6 +73,11 @@ export class AgentTool {
         this._economy ??= new EconomyClient(this.http);
         return this._economy;
     }
+    /** Access the Traces (reasoning provenance) API. */
+    get traces() {
+        this._traces ??= new TracesClient(this.http);
+        return this._traces;
+    }
     toString() {
         return `AgentTool(baseUrl=${JSON.stringify(this.http.baseUrl)})`;
     }

package/dist/index.d.ts

@@ -11,4 +11,5 @@
  */
 export { AgentTool } from "./client.js";
 export { AgentToolError } from "./errors.js";
+export type { Trace, StoreTraceOptions, SearchTracesOptions, TraceSearchResult, TraceChain } from "./traces.js";
 export type { CreateWalletOptions, ExecuteResult, Memory, ScrapeResult, SearchMemoryOptions, SearchResponse, SearchResult, StoreOptions, UsageStats, VerifyResult, Wallet, } from "./types.js";

package/dist/tools.js

@@ -31,7 +31,7 @@ export class ToolsClient {
             query,
             num_results: options?.num_results ?? 5,
         };
-        const data = (await this.post("/v1/search", body));
+        const data = (await this.post("/v1/search/search", body));
         // Normalize: API may return results at top level or nested
         const results = Array.isArray(data)
             ? data
@@ -49,7 +49,7 @@ export class ToolsClient {
      * @returns ScrapeResult with the page content.
      */
     async scrape(url) {
-        const data = await this.post("/v1/scrape", { url });
+        const data = await this.post("/v1/scrape/scrape", { url });
         return data;
     }
     /**

package/dist/traces.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Traces client for the agent-trace reasoning provenance API.
+ */
+import type { HttpConfig } from "./memory.js";
+/** A stored reasoning trace. */
+export interface Trace {
+    id: string;
+    trace_id: string;
+    agent_id?: string;
+    project_id: string;
+    session_id?: string;
+    created_at: string;
+    decision_type: string;
+    decision_summary: string;
+    output_ref?: string;
+    observations: string[];
+    hypothesis?: string;
+    conclusion: string;
+    confidence?: number;
+    alternatives?: string[];
+    signals?: Record<string, unknown>;
+    files_read?: string[];
+    key_facts?: string[];
+    external_signals?: Record<string, unknown>;
+    tags?: string[];
+    parent_trace_id?: string;
+}
+/** Options for storing a trace. */
+export interface StoreTraceOptions {
+    /** Free-form observation strings that led to the decision. */
+    observations: string[];
+    /** What was concluded / decided. */
+    conclusion: string;
+    /** One of: tool_call | memory_write | plan | decision | verification | other */
+    decision_type?: string;
+    /** Short human-readable summary of the decision. */
+    decision_summary?: string;
+    agent_id?: string;
+    session_id?: string;
+    output_ref?: string;
+    hypothesis?: string;
+    confidence?: number;
+    alternatives?: string[];
+    tags?: string[];
+    parent_trace_id?: string;
+    files_read?: string[];
+    key_facts?: string[];
+}
+/** A search result entry. */
+export interface TraceSearchResult {
+    trace: Trace;
+    score: number;
+}
+/** Options for searching traces. */
+export interface SearchTracesOptions {
+    /** Maximum number of results (default 10). */
+    limit?: number;
+    /** Filter by agent_id. */
+    agent_id?: string;
+    /** Filter by session_id. */
+    session_id?: string;
+    /** Filter by tag. */
+    tag?: string;
+}
+/** A reasoning chain (parent + children). */
+export interface TraceChain {
+    parent: Trace;
+    children: Trace[];
+    depth: number;
+}
+/**
+ * Client for the agent-trace reasoning provenance API.
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ *
+ * // Store a reasoning trace
+ * const trace = await at.traces.store({
+ *   observations: ["User asked about pricing", "Checked tier table"],
+ *   conclusion: "User is on Free tier, eligible to upgrade",
+ *   decision_type: "decision",
+ *   tags: ["billing", "upgrade"],
+ * });
+ *
+ * // Search traces semantically
+ * const results = await at.traces.search("billing decisions", { limit: 5 });
+ *
+ * // Retrieve a specific trace
+ * const t = await at.traces.get(trace.trace_id);
+ * ```
+ */
+export declare class TracesClient {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpConfig);
+    /**
+     * Store a reasoning trace.
+     *
+     * @param options - Trace content (observations + conclusion required).
+     * @returns The created Trace object with its trace_id.
+     */
+    store(options: StoreTraceOptions): Promise<Trace>;
+    /**
+     * Retrieve a trace by its trace_id.
+     *
+     * @param traceId - The trace_id returned by store().
+     */
+    get(traceId: string): Promise<Trace>;
+    /**
+     * Search traces by semantic similarity.
+     *
+     * @param query - Natural language query.
+     * @param options - Filters: limit, agent_id, session_id, tag.
+     * @returns Ranked list of matching traces with similarity scores.
+     */
+    search(query: string, options?: SearchTracesOptions): Promise<TraceSearchResult[]>;
+    /**
+     * Retrieve the reasoning chain for a trace (parent + all children).
+     *
+     * @param traceId - The parent trace_id.
+     */
+    chain(traceId: string): Promise<TraceChain>;
+    /**
+     * Delete a trace.
+     *
+     * @param traceId - The trace_id to delete.
+     */
+    delete(traceId: string): Promise<void>;
+    private _errorDetail;
+}

package/dist/traces.js

@@ -0,0 +1,167 @@
+/**
+ * Traces client for the agent-trace reasoning provenance API.
+ */
+import { AgentToolError } from "./errors.js";
+/**
+ * Client for the agent-trace reasoning provenance API.
+ *
+ * @example
+ * ```ts
+ * const at = new AgentTool();
+ *
+ * // Store a reasoning trace
+ * const trace = await at.traces.store({
+ *   observations: ["User asked about pricing", "Checked tier table"],
+ *   conclusion: "User is on Free tier, eligible to upgrade",
+ *   decision_type: "decision",
+ *   tags: ["billing", "upgrade"],
+ * });
+ *
+ * // Search traces semantically
+ * const results = await at.traces.search("billing decisions", { limit: 5 });
+ *
+ * // Retrieve a specific trace
+ * const t = await at.traces.get(trace.trace_id);
+ * ```
+ */
+export class TracesClient {
+    http;
+    /** @internal */
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Store a reasoning trace.
+     *
+     * @param options - Trace content (observations + conclusion required).
+     * @returns The created Trace object with its trace_id.
+     */
+    async store(options) {
+        const body = {
+            observations: options.observations,
+            conclusion: options.conclusion,
+            decision_type: options.decision_type ?? "decision",
+            decision_summary: options.decision_summary ?? options.conclusion.slice(0, 120),
+        };
+        if (options.agent_id !== undefined)
+            body.agent_id = options.agent_id;
+        if (options.session_id !== undefined)
+            body.session_id = options.session_id;
+        if (options.output_ref !== undefined)
+            body.output_ref = options.output_ref;
+        if (options.hypothesis !== undefined)
+            body.hypothesis = options.hypothesis;
+        if (options.confidence !== undefined)
+            body.confidence = options.confidence;
+        if (options.alternatives !== undefined)
+            body.alternatives = options.alternatives;
+        if (options.tags !== undefined)
+            body.tags = options.tags;
+        if (options.parent_trace_id !== undefined)
+            body.parent_trace_id = options.parent_trace_id;
+        if (options.files_read !== undefined)
+            body.files_read = options.files_read;
+        if (options.key_facts !== undefined)
+            body.key_facts = options.key_facts;
+        const resp = await globalThis.fetch(`${this.http.baseUrl}/v1/traces`, {
+            method: "POST",
+            headers: this.http.headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            const detail = await this._errorDetail(resp);
+            throw new AgentToolError(`Traces API error (${resp.status}): ${detail}`);
+        }
+        const created = (await resp.json());
+        // Return the full trace by fetching it
+        return this.get(created.trace_id);
+    }
+    /**
+     * Retrieve a trace by its trace_id.
+     *
+     * @param traceId - The trace_id returned by store().
+     */
+    async get(traceId) {
+        const resp = await globalThis.fetch(`${this.http.baseUrl}/v1/traces/${traceId}`, {
+            headers: this.http.headers,
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            const detail = await this._errorDetail(resp);
+            throw new AgentToolError(`Traces API error (${resp.status}): ${detail}`);
+        }
+        return (await resp.json());
+    }
+    /**
+     * Search traces by semantic similarity.
+     *
+     * @param query - Natural language query.
+     * @param options - Filters: limit, agent_id, session_id, tag.
+     * @returns Ranked list of matching traces with similarity scores.
+     */
+    async search(query, options) {
+        const body = {
+            query,
+            limit: options?.limit ?? 10,
+        };
+        if (options?.agent_id !== undefined)
+            body.agent_id = options.agent_id;
+        if (options?.session_id !== undefined)
+            body.session_id = options.session_id;
+        if (options?.tag !== undefined)
+            body.tag = options.tag;
+        const resp = await globalThis.fetch(`${this.http.baseUrl}/v1/traces/search`, {
+            method: "POST",
+            headers: this.http.headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            const detail = await this._errorDetail(resp);
+            throw new AgentToolError(`Traces API error (${resp.status}): ${detail}`);
+        }
+        return (await resp.json());
+    }
+    /**
+     * Retrieve the reasoning chain for a trace (parent + all children).
+     *
+     * @param traceId - The parent trace_id.
+     */
+    async chain(traceId) {
+        const resp = await globalThis.fetch(`${this.http.baseUrl}/v1/traces/chain/${traceId}`, {
+            headers: this.http.headers,
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            const detail = await this._errorDetail(resp);
+            throw new AgentToolError(`Traces API error (${resp.status}): ${detail}`);
+        }
+        return (await resp.json());
+    }
+    /**
+     * Delete a trace.
+     *
+     * @param traceId - The trace_id to delete.
+     */
+    async delete(traceId) {
+        const resp = await globalThis.fetch(`${this.http.baseUrl}/v1/traces/${traceId}`, {
+            method: "DELETE",
+            headers: this.http.headers,
+            signal: AbortSignal.timeout(this.http.timeout),
+        });
+        if (resp.status >= 400) {
+            const detail = await this._errorDetail(resp);
+            throw new AgentToolError(`Traces API error (${resp.status}): ${detail}`);
+        }
+    }
+    async _errorDetail(resp) {
+        try {
+            const json = (await resp.json());
+            return json.detail ?? resp.statusText;
+        }
+        catch {
+            return resp.statusText;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenttool/sdk",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "TypeScript SDK for agenttool.dev — memory and tools for AI agents",
   "type": "module",
   "main": "dist/index.js",