10xgraph-client 0.6.0 → 1.0.0-rc.2

package/dist/cjs/endpoints/files.d.ts

@@ -0,0 +1,115 @@
+/**
+ * File upload and retrieval endpoints for multimodal messages.
+ */
+import { RequestContext } from '../request.js';
+export interface FileUploadContext extends RequestContext {
+}
+export interface FileUploadResponse {
+    data: {
+        file_id: string;
+        mime_type: string;
+        size_bytes: number;
+        filename: string;
+        extracted_text: string | null;
+        url: string;
+        direct_url?: string | null;
+        direct_url_expires_at?: number | null;
+    };
+    metadata?: {
+        request_id: string;
+        timestamp: string;
+        message: string;
+    };
+}
+export interface FileInfoResponse {
+    data: {
+        file_id: string;
+        mime_type: string;
+        size_bytes: number;
+        filename?: string | null;
+        extracted_text: string | null;
+        direct_url?: string | null;
+        direct_url_expires_at?: number | null;
+    };
+    metadata?: {
+        request_id: string;
+        timestamp: string;
+        message: string;
+    };
+}
+export interface FileAccessUrlResponse {
+    data: {
+        file_id: string;
+        url: string;
+        expires_at?: number | null;
+        mime_type: string;
+    };
+    metadata?: {
+        request_id: string;
+        timestamp: string;
+        message: string;
+    };
+}
+export interface MultimodalConfigResponse {
+    data: {
+        media_storage_type: string;
+        media_max_size_mb: number;
+        document_handling: string;
+    };
+    metadata?: {
+        request_id: string;
+        timestamp: string;
+        message: string;
+    };
+}
+/**
+ * Upload a file (image, audio, document) to the server.
+ *
+ * @param ctx - Connection context
+ * @param file - A File, Blob, or { data: Blob; filename: string } object
+ * @returns FileUploadResponse with file_id and metadata
+ */
+export declare function uploadFile(ctx: FileUploadContext, file: File | Blob | {
+    data: Blob;
+    filename: string;
+}): Promise<FileUploadResponse>;
+/**
+ * Download a file by its file_id. Returns raw Blob.
+ */
+export declare function getFile(ctx: FileUploadContext, fileId: string): Promise<Blob>;
+export interface ListFilesRequest {
+    /** Page size (server default 50, maximum 200). */
+    limit?: number;
+    /** Number of files to skip. */
+    offset?: number;
+}
+export interface FileListItem {
+    file_id: string;
+    filename: string | null;
+    mime_type: string;
+    size_bytes: number;
+    url: string;
+    /** Unix seconds, or null when the store records no timestamp. */
+    created_at: number | null;
+}
+export interface ListFilesResponse {
+    data: {
+        files: FileListItem[];
+        has_more: boolean;
+        offset: number;
+        limit: number;
+    };
+    metadata?: {
+        request_id: string;
+        timestamp: string;
+        message: string;
+    };
+}
+/**
+ * List the caller's uploaded files. A store that cannot enumerate its files
+ * (for example a cloud store) answers 501, which is thrown as a TenxGraphError.
+ */
+export declare function listFiles(ctx: FileUploadContext, params?: ListFilesRequest): Promise<ListFilesResponse>;
+export declare function getFileInfo(ctx: FileUploadContext, fileId: string): Promise<FileInfoResponse>;
+export declare function getFileAccessUrl(ctx: FileUploadContext, fileId: string): Promise<FileAccessUrlResponse>;
+export declare function getMultimodalConfig(ctx: FileUploadContext): Promise<MultimodalConfigResponse>;

package/dist/cjs/endpoints/fixGraph.d.ts

@@ -0,0 +1,33 @@
+import { ResponseMetadata } from './metadata.js';
+import { RequestContext } from '../request.js';
+export interface FixGraphContext extends RequestContext {
+}
+export interface FixGraphRequest {
+    thread_id: string;
+    config?: Record<string, any>;
+}
+export interface FixGraphResponse {
+    data: {
+        success: boolean;
+        message: string;
+        removed_count: number;
+        state?: Record<string, any>;
+    };
+    metadata: ResponseMetadata;
+}
+/**
+ * Repair a thread whose run stopped after the model asked for tools but before
+ * the results were saved.
+ *
+ * The server removes an assistant message when any of its tool calls has no
+ * matching tool result (matched by tool call id), then removes tool result
+ * messages whose call no longer exists. If the thread is paused (interrupt,
+ * client tool call or human approval), the unanswered calls of the latest
+ * assistant message are kept. Messages without tool calls are never touched.
+ * When nothing needs fixing, removed_count is 0 and the state is not written.
+ *
+ * @param context - Request context with baseUrl, auth, timeout
+ * @param request - Fix request with thread_id and optional config
+ * @returns Promise<FixGraphResponse> with fix operation result
+ */
+export declare function fixGraph(context: FixGraphContext, request: FixGraphRequest): Promise<FixGraphResponse>;

package/dist/cjs/endpoints/forgetMemories.d.ts

@@ -0,0 +1,21 @@
+import { ResponseMetadata } from './metadata.js';
+import { MemoryType } from './storeMemory.js';
+import { RequestContext } from '../request.js';
+export interface ForgetMemoriesContext extends RequestContext {
+}
+export interface ForgetMemoriesRequest {
+    config?: Record<string, any>;
+    options?: Record<string, any>;
+    memory_type?: MemoryType;
+    category?: string;
+    filters?: Record<string, any>;
+}
+export interface ForgetMemoriesData {
+    success: boolean;
+    data: Record<string, any>;
+}
+export interface ForgetMemoriesResponse {
+    data: ForgetMemoriesData;
+    metadata: ResponseMetadata;
+}
+export declare function forgetMemories(context: ForgetMemoriesContext, request: ForgetMemoriesRequest): Promise<ForgetMemoriesResponse>;

package/dist/cjs/endpoints/getMemory.d.ts

@@ -0,0 +1,18 @@
+import { ResponseMetadata } from './metadata.js';
+import { RequestContext } from '../request.js';
+import { MemoryResult } from './searchMemory.js';
+export interface GetMemoryContext extends RequestContext {
+}
+export interface GetMemoryRequest {
+    memoryId: string;
+    config?: Record<string, any>;
+    options?: Record<string, any>;
+}
+export interface GetMemoryData {
+    memory: MemoryResult;
+}
+export interface GetMemoryResponse {
+    data: GetMemoryData;
+    metadata: ResponseMetadata;
+}
+export declare function getMemory(context: GetMemoryContext, request: GetMemoryRequest): Promise<GetMemoryResponse>;

package/dist/cjs/endpoints/graph.d.ts

@@ -0,0 +1,50 @@
+import { ResponseMetadata } from './metadata.js';
+import { RequestContext } from '../request.js';
+export interface GraphContext extends RequestContext {
+}
+export interface GraphNode {
+    id: string;
+    name: string;
+}
+export interface GraphEdge {
+    id: string;
+    source: string;
+    target: string;
+}
+/** Live (realtime) init options the server honors. */
+export interface GraphRealtimeOptions {
+    /** Init-frame keys applied from the client (subset of voice, modalities, vad, system_prompt). */
+    client_overrides: string[];
+    /** Accepted values for the init `model`; empty means the client cannot choose. */
+    models: string[];
+    model_selectable: boolean;
+    /** The client may narrow (never widen) the agent's tool tags. */
+    tools_tags: boolean;
+}
+export interface GraphInfo {
+    node_count: number;
+    edge_count: number;
+    checkpointer: boolean;
+    checkpointer_type: string | null;
+    publisher: boolean;
+    store: boolean;
+    interrupt_before: string[] | null;
+    interrupt_after: string[] | null;
+    context_type: string | null;
+    id_generator: string | null;
+    id_type: string | null;
+    state_type: string | null;
+    state_fields: string[] | null;
+    /** Live options the server honors; null when the graph is not a realtime agent. */
+    realtime_options?: GraphRealtimeOptions | null;
+}
+export interface GraphData {
+    info: GraphInfo;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+export interface GraphResponse {
+    data: GraphData;
+    metadata: ResponseMetadata;
+}
+export declare function graph(context: GraphContext): Promise<GraphResponse>;

package/dist/cjs/endpoints/graphTools.d.ts

@@ -0,0 +1,31 @@
+import { ResponseMetadata } from './metadata.js';
+import { RequestContext } from '../request.js';
+export interface GraphToolsContext extends RequestContext {
+}
+export type ToolSource = 'local' | 'mcp' | 'remote';
+export interface GraphTool {
+    name: string;
+    description: string;
+    source: ToolSource;
+    /** JSON Schema of the tool parameters (OpenAI function-calling shape). */
+    parameters: Record<string, any>;
+}
+export interface GraphToolNode {
+    node_name: string;
+    tool_count: number;
+    tools: GraphTool[];
+}
+export interface GraphToolsData {
+    node_count: number;
+    tool_count: number;
+    nodes: GraphToolNode[];
+}
+export interface GraphToolsResponse {
+    data: GraphToolsData;
+    metadata: ResponseMetadata;
+}
+/**
+ * Fetch the tools exposed by every ToolNode in the graph, grouped by node.
+ * Each tool is tagged with its source (local / mcp / remote).
+ */
+export declare function graphTools(context: GraphToolsContext): Promise<GraphToolsResponse>;

package/dist/cjs/endpoints/invoke.d.ts

@@ -0,0 +1,66 @@
+import { Message } from '../message.js';
+import { AgentState } from '../agent.js';
+import { ToolExecutor } from '../tools.js';
+import { RequestContext } from '../request.js';
+export interface InvokeContext extends RequestContext {
+    toolExecutor?: ToolExecutor;
+    /** Caller-supplied signal; aborting it cancels the in-flight request. */
+    signal?: AbortSignal;
+}
+export interface InvokeRequest {
+    messages: any[];
+    initial_state?: Record<string, any>;
+    config?: Record<string, any>;
+    recursion_limit?: number;
+    /** What to do when another run is active on the same thread (server default: 'wait'). */
+    on_busy?: 'wait' | 'cancel';
+    /** Value that answers an open interrupt. Send together with `interrupt_id`. */
+    resume?: unknown;
+    /** Id of the interrupt being answered by `resume`. */
+    interrupt_id?: string;
+    response_granularity?: 'full' | 'partial' | 'low';
+}
+export interface InvokeMetadata {
+    is_new_thread: boolean;
+    thread_id: string;
+}
+export interface InvokeResponse {
+    data: {
+        messages: Message[];
+        state?: AgentState;
+        context?: Message[];
+        summary?: string | null;
+        meta: InvokeMetadata;
+    };
+    metadata: {
+        request_id: string;
+        timestamp: string;
+        message: string;
+    };
+}
+export interface InvokeResult {
+    messages: Message[];
+    state?: AgentState;
+    context?: Message[];
+    summary?: string | null;
+    meta: InvokeMetadata;
+    all_messages: Message[];
+    iterations: number;
+    recursion_limit_reached: boolean;
+}
+export interface InvokePartialResult {
+    iteration: number;
+    messages: Message[];
+    state?: AgentState;
+    context?: Message[];
+    summary?: string | null;
+    meta: InvokeMetadata;
+    has_tool_calls: boolean;
+    is_final: boolean;
+}
+export type InvokeCallback = (partial: InvokePartialResult) => void | Promise<void>;
+/**
+ * Invoke the graph with automatic tool execution loop
+ * @param onPartialResult - Optional callback to receive results as they arrive
+ */
+export declare function invoke(context: InvokeContext, request: InvokeRequest, onPartialResult?: InvokeCallback): Promise<InvokeResult>;

package/dist/cjs/endpoints/listMemories.d.ts

@@ -0,0 +1,24 @@
+import { ResponseMetadata } from './metadata.js';
+import { RequestContext } from '../request.js';
+import { MemoryResult } from './searchMemory.js';
+export interface ListMemoriesContext extends RequestContext {
+}
+export interface ListMemoriesRequest {
+    config?: Record<string, any>;
+    options?: Record<string, any>;
+    limit?: number;
+    /** Memories to skip, for paging. Use `next_offset` from the previous page. Needs 10xgraph-api with paging support. */
+    offset?: number;
+}
+export interface ListMemoriesData {
+    memories: MemoryResult[];
+    /** True when more memories follow this page. Absent on servers without paging. */
+    has_more?: boolean;
+    /** Offset to request next, or null on the last page. */
+    next_offset?: number | null;
+}
+export interface ListMemoriesResponse {
+    data: ListMemoriesData;
+    metadata: ResponseMetadata;
+}
+export declare function listMemories(context: ListMemoriesContext, request: ListMemoriesRequest): Promise<ListMemoriesResponse>;

package/dist/cjs/endpoints/metadata.d.ts

@@ -0,0 +1,5 @@
+export interface ResponseMetadata {
+    request_id: string;
+    timestamp: string;
+    message: string;
+}

package/dist/cjs/endpoints/observability.d.ts

@@ -0,0 +1,111 @@
+import { ResponseMetadata } from './metadata.js';
+import { RequestContext } from '../request.js';
+export interface ObservabilityContext extends RequestContext {
+}
+/** Compact view of a complete message seen during a node visit. */
+export interface ObsMessageSummary {
+    role: 'user' | 'assistant' | 'tool' | 'system' | string;
+    text?: string;
+    tool_calls?: Array<{
+        id: string;
+        name: string;
+    }>;
+    tool_results?: Array<{
+        call_id: string;
+        is_error: boolean;
+    }>;
+}
+/**
+ * One span in the run tree: `root` > `node` (one per visit) > `llm` and `tool`.
+ * The tree is built from `parent`. Fields marked 1.0.0 are absent on older servers.
+ * Values in `inputs` / `outputs` are clipped at 4000 characters
+ * (a clipped value is a string ending in `...[truncated N chars]`).
+ *
+ * `inputs` / `outputs` by kind:
+ * - root: `{ user_message }` / `{ assistant_message }`
+ * - node: `{ incoming_message }` (approximate) / `{ messages: ObsMessageSummary[] }`
+ * - llm: `null` (the prompt is not recorded) / `{ text?, tool_calls? }`
+ * - tool: `{ args }` / `{ result }`
+ */
+export interface ObsSpan {
+    id: string;
+    name: string;
+    kind: 'root' | 'node' | 'llm' | 'tool';
+    parent: string | null;
+    start_ms: number;
+    duration_ms: number;
+    model?: string | null;
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    /** ok | error | running. */
+    status?: 'ok' | 'error' | 'running';
+    /** Error text when `status` is `error`. */
+    error?: string | null;
+    inputs?: Record<string, unknown> | null;
+    outputs?: Record<string, unknown> | null;
+    /** Graph step (node spans), else null. */
+    step?: number | null;
+    /** 1-based visit count of this node name (node spans), else null. */
+    visit?: number | null;
+    total_tokens?: number | null;
+    reasoning_tokens?: number | null;
+    /** Tool spans only. */
+    tool_name?: string | null;
+    tool_call_id?: string | null;
+}
+export interface ObsEvent {
+    id: string;
+    type: string;
+    node: string;
+    offset_ms: number;
+    summary: string;
+}
+export interface ObsTokenUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    reasoning_tokens: number;
+    total_tokens: number;
+}
+export interface ObsRun {
+    run_id: string;
+    thread_id: string;
+    status: string;
+    started_at: number | null;
+    finished_at: number | null;
+    duration_ms: number;
+    spans: ObsSpan[];
+    events: ObsEvent[];
+    usage: ObsTokenUsage;
+    llm_calls: number;
+    tool_calls: number;
+    /** Number of node visits (distinct node names on servers older than 1.0.0). */
+    iterations: number;
+    /** First error text seen in the run, else null. */
+    error?: string | null;
+    /** First model seen in the run, else null. */
+    model?: string | null;
+    models?: string[];
+    /** Human-readable limits of this run's trace (may be empty). */
+    notes?: string[];
+}
+/** Why `run` is null. */
+export type ObsEmptyReason = 'disabled_in_production' | 'store_unavailable' | 'no_runs';
+export interface ObservabilityData {
+    thread_id: string;
+    run_count: number;
+    run_ids: string[];
+    run: ObsRun | null;
+    /** False when the local trace store is off (for example MODE=production). */
+    enabled?: boolean;
+    /** Why `run` is null: tracing off, store missing, or no runs captured yet. */
+    reason?: ObsEmptyReason | null;
+}
+export interface ObservabilityResponse {
+    data: ObservabilityData;
+    metadata: ResponseMetadata;
+}
+/**
+ * Fetch the reconstructed observability trace (spans, events, cost) for a thread.
+ * Returns the latest run by default, or a specific run when `runId` is given.
+ */
+export declare function observability(context: ObservabilityContext, threadId: string, runId?: string): Promise<ObservabilityResponse>;

package/dist/cjs/endpoints/ping.d.ts

@@ -0,0 +1,9 @@
+import { ResponseMetadata } from './metadata.js';
+import { RequestContext } from '../request.js';
+export interface PingContext extends RequestContext {
+}
+export interface PingResponse {
+    data: string;
+    metadata: ResponseMetadata;
+}
+export declare function ping(context: PingContext): Promise<PingResponse>;

package/dist/cjs/endpoints/realtime.d.ts

@@ -0,0 +1,154 @@
+import { RequestContext } from '../request.js';
+import { WsAuthContext } from '../ws.js';
+export declare const REALTIME_OUTPUT_SAMPLE_RATE = 24000;
+export declare const REALTIME_INPUT_SAMPLE_RATE = 16000;
+export type ResponseModality = 'AUDIO' | 'TEXT';
+export interface RealtimeVADConfig {
+    enabled?: boolean;
+    start_sensitivity?: string | null;
+    end_sensitivity?: string | null;
+    prefix_padding_ms?: number | null;
+    silence_duration_ms?: number | null;
+}
+export interface RealtimeInit {
+    /**
+     * e.g. "gemini-3.8-live". Honoured only when the server lists it in
+     * `websocket.realtime_models`; otherwise the agent's own model is used.
+     */
+    model?: string;
+    /**
+     * Omit to let the server create the thread; the id arrives in the `session_started` event and
+     * is read from `session.threadId`. Pass an id to continue a thread (the server must allow it:
+     * under the default `runs.thread_ids: "server"` it must be one the server already knows).
+     */
+    thread_id?: string;
+    voice?: string;
+    modalities?: ResponseModality | ResponseModality[];
+    vad?: RealtimeVADConfig;
+    system_prompt?: string;
+    /** Can only narrow the agent's own tag filter. */
+    tools_tags?: string[];
+    /** Forward-compatible passthrough; unknown keys are ignored by the server. */
+    [k: string]: unknown;
+}
+/** Downstream JSON events. Audio arrives separately as binary via the `audio` channel. */
+export type RealtimeEvent = {
+    type: 'session_started';
+    thread_id: string;
+} | {
+    type: 'input_transcript';
+    text: string;
+    finished: boolean;
+} | {
+    type: 'output_transcript';
+    text: string;
+    finished: boolean;
+} | {
+    type: 'tool_call';
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    id: string;
+    result: unknown;
+} | {
+    type: 'turn_complete';
+} | {
+    type: 'interrupted';
+} | {
+    type: 'session_update';
+    resumption_handle?: string | null;
+} | {
+    type: 'go_away';
+    time_left?: string | null;
+} | {
+    type: 'agent_changed';
+    author: string;
+} | {
+    type: 'error';
+    code?: string | null;
+    message: string;
+    fatal: boolean;
+};
+export type RealtimeEventType = RealtimeEvent['type'];
+export interface RealtimeReconnectOptions {
+    enabled?: boolean;
+    baseDelay?: number;
+    maxDelay?: number;
+    maxAttempts?: number;
+}
+export interface RealtimeOptions {
+    reconnect?: RealtimeReconnectOptions;
+    onAudio?: (pcm16: Uint8Array, sampleRate: number) => void;
+    onEvent?: (e: RealtimeEvent) => void;
+    onError?: (e: Extract<RealtimeEvent, {
+        type: 'error';
+    }>) => void;
+}
+export type RealtimeContext = RequestContext & WsAuthContext & {
+    /** Resolves the current bearer token; called on every (re)connect so a refreshed token is used. */
+    getAuthToken?: () => string | null | undefined;
+};
+type ChannelMap = {
+    audio: (pcm16: Uint8Array, sampleRate: number) => void;
+    event: (e: RealtimeEvent) => void;
+    open: () => void;
+    close: (code: number) => void;
+    reconnecting: (attempt: number) => void;
+    reconnected: () => void;
+} & {
+    [K in RealtimeEventType]: (e: Extract<RealtimeEvent, {
+        type: K;
+    }>) => void;
+};
+type ChannelName = keyof ChannelMap;
+/**
+ * A transport-only realtime audio session over `/v1/graph/live`.
+ *
+ * Send PCM16 input via `sendAudio`; receive PCM16 output via `.on('audio', ...)`.
+ * All non-audio events arrive via `.on('event', ...)` and per-type channels.
+ * Mic capture and audio playback are the caller's responsibility.
+ */
+export declare class RealtimeSession {
+    /**
+     * The thread this session runs on: the caller's `thread_id`, or the id the server created.
+     * `null` until the `session_started` event arrives, when the caller gave none.
+     */
+    threadId: string | null;
+    resumptionHandle: string | null;
+    ready: Promise<void>;
+    private ctx;
+    private init;
+    private ws;
+    private listeners;
+    private resolveReady;
+    private rejectReady;
+    private readyResolved;
+    private closedByUser;
+    private fatal;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private stableTimer;
+    private readonly reconnectCfg;
+    constructor(ctx: RealtimeContext, init: RealtimeInit, options?: RealtimeOptions);
+    /**
+     * Frames are dropped unless the socket is open; await `session.ready` (or the `open`
+     * event) before sending, so mic callbacks that fire early do not throw.
+     */
+    sendAudio(pcm16: Uint8Array | ArrayBuffer): void;
+    sendText(text: string): void;
+    activityStart(): void;
+    activityEnd(): void;
+    close(): void;
+    on<K extends ChannelName>(event: K, listener: ChannelMap[K]): this;
+    off<K extends ChannelName>(event: K, listener: ChannelMap[K]): this;
+    private emit;
+    private sendControl;
+    private clearTimers;
+    private connect;
+    private handleMessage;
+    private maybeReconnect;
+    private reconnect;
+}
+export {};