merco-agents 0.1.1

package/index.d.ts

@@ -0,0 +1,423 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/** Wrapper for AgentBuilder to expose to JavaScript */
+export declare class AgentBuilderWrapper {
+  name(name: string): AgentBuilderWrapper
+  description(description: string): AgentBuilderWrapper
+  role(role: JsAgentRole): AgentBuilderWrapper
+  llmConfig(config: JsAgentModelConfig): AgentBuilderWrapper
+  capabilities(capabilities: JsAgentCapabilities): AgentBuilderWrapper
+  tools(toolNames: Array<string>): AgentBuilderWrapper
+  storage(storage: JsStorageHandler): AgentBuilderWrapper
+  build(): Promise<JsAgent>
+}
+
+/** JavaScript wrapper for Agent */
+export declare class JsAgent {
+  /** Get agent ID */
+  get id(): string
+  /** Get agent name */
+  get name(): string
+  /** Get agent description */
+  get description(): string
+  /** Execute a task */
+  call(task: JsTask): Promise<JsAgentResponse>
+  /** Execute a task with string input */
+  callStr(input: string): Promise<JsAgentResponse>
+  /** Execute a task with session */
+  callWithSession(task: JsTask, sessionKey?: string | undefined | null): Promise<JsAgentResponse>
+  /** Execute a task with user context */
+  callWithUser(task: JsTask, userId?: string | undefined | null): Promise<JsAgentResponse>
+  /** Stream a task execution with callbacks */
+  callStream(task: JsTask, handler: JsStreamingHandler): Promise<void>
+  /** Stream a task execution with string input */
+  callStrStream(input: string, handler: JsStreamingHandler): Promise<void>
+  /** Stream a task execution with session */
+  callStreamWithSession(task: JsTask, sessionKey: string | undefined | null, handler: JsStreamingHandler): Promise<void>
+}
+
+/** JavaScript wrapper for Session */
+export declare class JsSession {
+  /** Create a new session */
+  static new(name: string): JsSession
+  /** Create a session with description */
+  static withDescription(name: string, description: string): JsSession
+  /** Get session ID */
+  get id(): bigint
+  /** Get session name */
+  get name(): string
+  /** Get session description */
+  get description(): string | null
+  /** Get message count */
+  messageCount(): bigint
+  /** Get total tokens */
+  totalTokens(): bigint
+  /** Get tool call count */
+  toolCallCount(): bigint
+  /** Get unique tools used */
+  uniqueToolsUsed(): Array<string>
+  /** Get last activity timestamp */
+  lastActivity(): string
+  /** Serialize session to JSON */
+  toJson(): string
+  /** Deserialize session from JSON */
+  static fromJson(json: string): JsSession
+}
+
+/** JavaScript wrapper for StorageHandler */
+export declare class JsStorageHandler {
+  /** Create a new session */
+  createSession(session: JsSession): Promise<void>
+  /** Get a session by ID */
+  getSession(id: number): Promise<JsSession | null>
+  /** List all sessions */
+  listSessions(): Promise<Array<JsSession>>
+  /** Update a session */
+  updateSession(session: JsSession): Promise<void>
+  /** Delete a session by ID */
+  deleteSession(id: number): Promise<void>
+  /** Close the storage connection */
+  close(): Promise<void>
+}
+
+/** JavaScript callback-based streaming handler */
+export declare class JsStreamingHandler {
+  /** Creates a new instance of JsStreamingHandler */
+  static new(): JsStreamingHandler
+  /** Sets the callback for handling streaming chunks */
+  withOnChunk(callback: (arg: JsStreamingChunk) => void): JsStreamingHandler
+  /** Sets the callback for handling the final response */
+  withOnFinal(callback: (arg: JsStreamingResponse) => void): JsStreamingHandler
+  /** Sets the callback for handling errors */
+  withOnError(callback: (arg: string) => void): JsStreamingHandler
+  /**
+   * Sets the callback for handling tool call start events
+   * The callback should return a boolean: true to allow execution, false to reject
+   * The callback receives a JsToolCallStart object with tool_name, call_id, and execution_id.
+   * The callback should call tool_call_start_complete(execution_id, allow) to return the result.
+   */
+  withOnToolCallStart(callback: (arg: JsToolCallStart) => boolean): JsStreamingHandler
+  /** Sets the callback for handling tool call after execution events */
+  withOnToolCallAfterExecution(callback: (arg: JsToolCallExecuted) => void): JsStreamingHandler
+}
+
+/** JavaScript wrapper for Task */
+export declare class JsTask {
+  /** Create a new text task */
+  constructor(description: string, expectedOutput?: string | undefined | null)
+  /** Create a new task with JSON output format */
+  static newWithJson(description: string, expectedOutput: string | undefined | null, requiredFields: Array<JsJsonField>, optionalFields: Array<JsJsonField>, strict: boolean): JsTask
+  /** Create a simple JSON task */
+  static newSimpleJson(description: string, expectedOutput: string | undefined | null, requiredFields: Array<[string, JsJsonFieldType]>, strict: boolean): JsTask
+  /** Validate output against task format */
+  validate(output: string): boolean
+  /** Get task description */
+  get description(): string
+  /** Get expected output */
+  get expectedOutput(): string | null
+}
+
+/** Create a new agent using the builder pattern */
+export declare function agentBuilder(): Promise<AgentBuilderWrapper>
+
+/** JavaScript representation of AgentCapabilities */
+export interface JsAgentCapabilities {
+  maxConcurrentTasks: number
+  supportedOutputFormats: Array<JsOutputFormat>
+}
+
+/** JavaScript representation of AgentModelConfig */
+export interface JsAgentModelConfig {
+  modelName: string
+  temperature: number
+  maxTokens: number
+  llmConfig: JsLlmConfig
+  reasoningEffort?: JsReasoningEffort
+}
+
+/** JavaScript representation of AgentResponse */
+export interface JsAgentResponse {
+  content: string
+  success: boolean
+  executionTimeMs: number
+  inputTokens: number
+  outputTokens: number
+  totalTokens: number
+  toolsUsed: Array<string>
+  toolCalls: Array<string>
+  toolCallsCount: number
+  toolExecutionTimeMs: number
+  outputFormat: string
+  modelUsed: string
+  temperature: number
+  error?: string
+  errorCode?: string
+  timestamp: string
+  metadata?: string
+  sessionInfo?: JsSessionInfo
+  reasoning?: string
+  reasoningSummary?: string
+  encryptedReasoningItems?: Array<string>
+}
+
+/** JavaScript representation of AgentRole */
+export interface JsAgentRole {
+  name: string
+  description: string
+  metadata?: string
+  developerInstructions?: string
+}
+
+/** JavaScript representation of ChunkType */
+export declare const enum JsChunkType {
+  Text = 0,
+  Reasoning = 1,
+  ToolCall = 2,
+  ToolCallResult = 3
+}
+
+/** JavaScript representation of JsonField */
+export interface JsJsonField {
+  name: string
+  fieldType: JsJsonFieldType
+  description?: string
+}
+
+/** JavaScript representation of JsonFieldType */
+export declare const enum JsJsonFieldType {
+  String = 0,
+  Number = 1,
+  Boolean = 2,
+  Array = 3,
+  Object = 4
+}
+
+/**
+ * JavaScript representation of JSON Schema for tool parameters
+ * Matches the structure of merco_llmproxy::JsonSchema
+ *
+ * Note: properties is a JSON string that will be parsed into a serde_json::Map.
+ * This allows TypeScript to pass a typed object which gets serialized to JSON.
+ */
+export interface JsJsonSchema {
+  /** The schema type, typically "object" for tool parameters */
+  schemaType?: string
+  /**
+   * Properties of the schema as a JSON string (will be parsed)
+   * In TypeScript, pass a plain object - it will be serialized automatically
+   */
+  properties?: string
+  /** List of required property names */
+  required?: Array<string>
+}
+
+/** JavaScript representation of LlmConfig */
+export interface JsLlmConfig {
+  provider: JsProvider
+  apiKey?: string
+  baseUrl?: string
+  headers?: string
+}
+
+/** JavaScript representation of OutputFormat (for agent capabilities) */
+export declare const enum JsOutputFormat {
+  Text = 0,
+  Json = 1,
+  Markdown = 2,
+  Html = 3,
+  MultiModal = 4
+}
+
+/** JavaScript representation of PostgresConfig */
+export interface JsPostgresConfig {
+  host: string
+  port?: number
+  database: string
+  username: string
+  password: string
+  schema?: string
+  sslMode?: string
+  maxConnections?: number
+  minConnections?: number
+  connectionTimeout?: number
+  idleTimeout?: number
+}
+
+/** JavaScript representation of Provider enum */
+export declare const enum JsProvider {
+  OpenAI = 0,
+  Anthropic = 1,
+  Google = 2,
+  Ollama = 3,
+  Custom = 4
+}
+
+/** JavaScript representation of reasoning event */
+export interface JsReasoning {
+  reasoningChunk: string
+  accumulatedReasoning: string
+}
+
+/** JavaScript representation of ReasoningEffort */
+export declare const enum JsReasoningEffort {
+  Low = 0,
+  Medium = 1,
+  High = 2
+}
+
+/** JavaScript representation of SessionInfo */
+export interface JsSessionInfo {
+  sessionId: number
+  sessionName: string
+  totalMessages: number
+  totalTokens: number
+  toolCallsCount: number
+  uniqueToolsUsed: Array<string>
+  lastActivity: string
+}
+
+/** JavaScript representation of SqliteConfig */
+export interface JsSqliteConfig {
+  databasePath: string
+  createIfMissing?: boolean
+  journalMode?: string
+  synchronous?: string
+  cacheSize?: number
+  foreignKeys?: boolean
+  maxConnections?: number
+  connectionTimeout?: number
+  busyTimeout?: number
+}
+
+/** JavaScript representation of StreamingChunk */
+export interface JsStreamingChunk {
+  chunkType: JsChunkType
+  content: string
+  isFinal: boolean
+  accumulatedContent: string
+  toolCalls?: Array<string>
+  hasToolCalls: boolean
+  usage?: JsStreamingUsage
+  finishReason?: string
+  timestamp: string
+  metadata?: string
+  reasoning?: string
+  accumulatedReasoning?: string
+  toolCallName?: string
+  toolCallId?: string
+  toolCallArgs?: string
+  toolCallResult?: string
+  toolCallExecutionTimeMs?: number
+  reasoningSummary?: string
+}
+
+/** JavaScript representation of StreamingResponse */
+export interface JsStreamingResponse {
+  content: string
+  success: boolean
+  executionTimeMs: number
+  totalTokens: number
+  toolsUsed: Array<string>
+  toolCalls: Array<string>
+  outputFormat: string
+  modelUsed: string
+  temperature: number
+  error?: string
+  errorCode?: string
+  timestamp: string
+  metadata?: string
+  reasoning?: string
+  reasoningSummary?: string
+  encryptedReasoningItems?: Array<string>
+}
+
+/** JavaScript representation of StreamingUsage */
+export interface JsStreamingUsage {
+  promptTokens: number
+  completionTokens: number
+  totalTokens: number
+  reasoningTokens?: number
+}
+
+/** JavaScript representation of ToolCall */
+export interface JsToolCall {
+  toolName: string
+  parameters: string
+  result: string
+  executionTimeMs: number
+  error?: string
+  outputFormat: string
+}
+
+/** JavaScript representation of tool call executed event */
+export interface JsToolCallExecuted {
+  toolName: string
+  callId: string
+  result: string
+  executionTimeMs: number
+  error?: string
+}
+
+/** JavaScript representation of tool call ready event */
+export interface JsToolCallReady {
+  toolName: string
+  callId: string
+  completeArgs: string
+}
+
+/** JavaScript representation of tool call start event */
+export interface JsToolCallStart {
+  toolName: string
+  callId: string
+  executionId?: string
+}
+
+/** JavaScript representation of tool call streaming event */
+export interface JsToolCallStreaming {
+  toolName: string
+  callId: string
+  partialArgs: string
+}
+
+/** Create storage from URL */
+export declare function storageCreateFromUrl(url: string): Promise<JsStorageHandler>
+
+/** Create PostgreSQL storage */
+export declare function storageCreatePostgres(config: JsPostgresConfig): Promise<JsStorageHandler>
+
+/** Create SQLite storage */
+export declare function storageCreateSqlite(config: JsSqliteConfig): Promise<JsStorageHandler>
+
+/**
+ * Store result from tool call start callback (called from JS side)
+ * The JS callback should call this function with the execution_id and allow boolean
+ */
+export declare function toolCallStartComplete(executionId: string, allow: boolean): void
+
+/**
+ * Store result from JS tool execution (called from JS side via a special API)
+ * This is called by the JS wrapper function automatically
+ */
+export declare function toolCompleteExecution(executionId: string, result: string, isError: boolean): void
+
+/** List all registered tools */
+export declare function toolList(): Array<string>
+
+/**
+ * Register a tool from JavaScript function
+ * The callback can be synchronous: (args: object) => any
+ * Or asynchronous: (args: object) => Promise<any>
+ * The function receives parsed JSON arguments and should return a value (or Promise of value)
+ *
+ * Note: The function will receive a string containing JSON with __execution_id and __args.
+ * The user's function should parse this and call tool_complete_execution when done.
+ * A helper wrapper will be provided in the JS/TS layer to simplify this.
+ */
+export declare function toolRegister(name: string, description: string, parameters: JsJsonSchema, callback: (arg: string) => void): void
+
+/**
+ * Unregister a tool
+ * Note: merco_llmproxy doesn't currently support unregistering tools.
+ * This function is kept for API compatibility but does nothing.
+ */
+export declare function toolUnregister(name: string): void

package/lib/index.d.ts

@@ -0,0 +1,282 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/** Wrapper for AgentBuilder to expose to JavaScript */
+export declare class AgentBuilderWrapper {
+  name(name: string): AgentBuilderWrapper
+  description(description: string): AgentBuilderWrapper
+  role(role: JsAgentRole): AgentBuilderWrapper
+  llmConfig(config: JsAgentModelConfig): AgentBuilderWrapper
+  capabilities(capabilities: JsAgentCapabilities): AgentBuilderWrapper
+  storage(storage: JsStorageHandler): AgentBuilderWrapper
+  build(): Promise<JsAgent>
+}
+
+/** JavaScript wrapper for Agent */
+export declare class JsAgent {
+  /** Get agent ID */
+  get id(): string
+  /** Get agent name */
+  get name(): string
+  /** Get agent description */
+  get description(): string
+  /** Execute a task */
+  call(task: JsTask): Promise<JsAgentResponse>
+  /** Execute a task with string input */
+  callStr(input: string): Promise<JsAgentResponse>
+  /** Execute a task with session */
+  callWithSession(task: JsTask, sessionKey?: string | undefined | null): Promise<JsAgentResponse>
+  /** Execute a task with user context */
+  callWithUser(task: JsTask, userId?: string | undefined | null): Promise<JsAgentResponse>
+  /**
+   * Stream a task execution with callbacks
+   * Note: callbacks parameter is temporarily removed due to Function type limitations in #[napi(object)]
+   * This will be re-implemented with a different approach
+   */
+  callStream(task: JsTask, callbacks?: string | undefined | null): Promise<void>
+  /** Stream a task execution with string input */
+  callStrStream(input: string, callbacks?: string | undefined | null): Promise<void>
+  /** Stream a task execution with session */
+  callStreamWithSession(task: JsTask, sessionKey?: string | undefined | null, callbacks?: string | undefined | null): Promise<void>
+}
+
+/** JavaScript wrapper for Session */
+export declare class JsSession {
+  /** Create a new session */
+  static new(name: string): JsSession
+  /** Create a session with description */
+  static withDescription(name: string, description: string): JsSession
+  /** Get session ID */
+  get id(): bigint
+  /** Get session name */
+  get name(): string
+  /** Get session description */
+  get description(): string | null
+  /** Get message count */
+  messageCount(): bigint
+  /** Get total tokens */
+  totalTokens(): bigint
+  /** Get tool call count */
+  toolCallCount(): bigint
+  /** Get unique tools used */
+  uniqueToolsUsed(): Array<string>
+  /** Get last activity timestamp */
+  lastActivity(): string
+  /** Serialize session to JSON */
+  toJson(): string
+  /** Deserialize session from JSON */
+  static fromJson(json: string): JsSession
+}
+
+/** JavaScript wrapper for StorageHandler */
+export declare class JsStorageHandler {
+  /** Create a new session */
+  createSession(session: JsSession): Promise<void>
+  /** Get a session by ID */
+  getSession(id: number): Promise<JsSession | null>
+  /** List all sessions */
+  listSessions(): Promise<Array<JsSession>>
+  /** Update a session */
+  updateSession(session: JsSession): Promise<void>
+  /** Delete a session by ID */
+  deleteSession(id: number): Promise<void>
+  /** Close the storage connection */
+  close(): Promise<void>
+}
+
+/** JavaScript wrapper for Task */
+export declare class JsTask {
+  /** Create a new text task */
+  constructor(description: string, expectedOutput?: string | undefined | null)
+  /** Create a new task with JSON output format */
+  static newWithJson(description: string, expectedOutput: string | undefined | null, requiredFields: Array<JsJsonField>, optionalFields: Array<JsJsonField>, strict: boolean): JsTask
+  /** Create a simple JSON task */
+  static newSimpleJson(description: string, expectedOutput: string | undefined | null, requiredFields: Array<[string, JsJsonFieldType]>, strict: boolean): JsTask
+  /** Validate output against task format */
+  validate(output: string): boolean
+  /** Get task description */
+  get description(): string
+  /** Get expected output */
+  get expectedOutput(): string | null
+}
+
+/** Create a new agent using the builder pattern */
+export declare function agentBuilder(): Promise<AgentBuilderWrapper>
+
+/** JavaScript representation of AgentCapabilities */
+export interface JsAgentCapabilities {
+  maxConcurrentTasks: number
+  supportedOutputFormats: Array<JsOutputFormat>
+}
+
+/** JavaScript representation of AgentModelConfig */
+export interface JsAgentModelConfig {
+  modelName: string
+  temperature: number
+  maxTokens: number
+  llmConfig: JsLlmConfig
+}
+
+/** JavaScript representation of AgentResponse */
+export interface JsAgentResponse {
+  content: string
+  success: boolean
+  executionTimeMs: number
+  inputTokens: number
+  outputTokens: number
+  totalTokens: number
+  toolsUsed: Array<string>
+  toolCalls: Array<string>
+  toolCallsCount: number
+  toolExecutionTimeMs: number
+  outputFormat: string
+  modelUsed: string
+  temperature: number
+  error?: string
+  timestamp: string
+  metadata?: string
+  sessionInfo?: JsSessionInfo
+}
+
+/** JavaScript representation of AgentRole */
+export interface JsAgentRole {
+  name: string
+  description: string
+  metadata?: string
+}
+
+/** JavaScript representation of JsonField */
+export interface JsJsonField {
+  name: string
+  fieldType: JsJsonFieldType
+  description?: string
+}
+
+/** JavaScript representation of JsonFieldType */
+export declare const enum JsJsonFieldType {
+  String = 0,
+  Number = 1,
+  Boolean = 2,
+  Array = 3,
+  Object = 4
+}
+
+/** JavaScript representation of LlmConfig */
+export interface JsLlmConfig {
+  provider: JsProvider
+  apiKey?: string
+  baseUrl?: string
+  headers?: string
+}
+
+/** JavaScript representation of OutputFormat (for agent capabilities) */
+export declare const enum JsOutputFormat {
+  Text = 0,
+  Json = 1,
+  Markdown = 2,
+  Html = 3,
+  MultiModal = 4
+}
+
+/** JavaScript representation of PostgresConfig */
+export interface JsPostgresConfig {
+  host: string
+  port?: number
+  database: string
+  username: string
+  password: string
+  schema?: string
+  sslMode?: string
+  maxConnections?: number
+  minConnections?: number
+  connectionTimeout?: number
+  idleTimeout?: number
+}
+
+/** JavaScript representation of Provider enum */
+export declare const enum JsProvider {
+  OpenAI = 0,
+  Anthropic = 1,
+  Google = 2,
+  Ollama = 3,
+  Custom = 4
+}
+
+/** JavaScript representation of SessionInfo */
+export interface JsSessionInfo {
+  sessionId: number
+  sessionName: string
+  totalMessages: number
+  totalTokens: number
+  toolCallsCount: number
+  uniqueToolsUsed: Array<string>
+  lastActivity: string
+}
+
+/** JavaScript representation of SqliteConfig */
+export interface JsSqliteConfig {
+  databasePath: string
+  createIfMissing?: boolean
+  journalMode?: string
+  synchronous?: string
+  cacheSize?: number
+  foreignKeys?: boolean
+  maxConnections?: number
+  connectionTimeout?: number
+  busyTimeout?: number
+}
+
+/** JavaScript representation of StreamingChunk */
+export interface JsStreamingChunk {
+  content: string
+  isFinal: boolean
+  accumulatedContent: string
+  toolCalls?: Array<string>
+  hasToolCalls: boolean
+  usage?: JsStreamingUsage
+  finishReason?: string
+  timestamp: string
+  metadata?: string
+}
+
+/** JavaScript representation of StreamingResponse */
+export interface JsStreamingResponse {
+  content: string
+  success: boolean
+  executionTimeMs: number
+  totalTokens: number
+  toolsUsed: Array<string>
+  toolCalls: Array<string>
+  outputFormat: string
+  modelUsed: string
+  temperature: number
+  error?: string
+  timestamp: string
+  metadata?: string
+}
+
+/** JavaScript representation of StreamingUsage */
+export interface JsStreamingUsage {
+  promptTokens: number
+  completionTokens: number
+  totalTokens: number
+}
+
+/** Create storage from URL */
+export declare function storageCreateFromUrl(url: string): Promise<JsStorageHandler>
+
+/** Create PostgreSQL storage */
+export declare function storageCreatePostgres(config: JsPostgresConfig): Promise<JsStorageHandler>
+
+/** Create SQLite storage */
+export declare function storageCreateSqlite(config: JsSqliteConfig): Promise<JsStorageHandler>
+
+/** List all registered tools */
+export declare function toolList(): Array<string>
+
+/** Register a tool from JavaScript function */
+export declare function toolRegister(name: string, description: string, parameters: string, callback: (arg?: unknown) => unknown): void
+
+/** Unregister a tool */
+export declare function toolUnregister(name: string): void
+
+