@circuitorg/agent-sdk 1.0.0

package/README.md

@@ -0,0 +1,149 @@
+# Circuit Agent SDK - Typescript
+
+> **Clean, type-safe TypeScript SDK for building cross-chain agents on the circuit platform**
+
+A TypeScript SDK for building automated agents to deploy on Circuit. Features a simple API surface with just **2 main methods** and full type safety.
+
+> **💡 Best used with [Circuit Agents CLI](https://github.com/circuitorg/agents-cli)** - Deploy, manage, and test your agents with ease
+
+## ✨ Features
+
+- **🎯 Simple API**: Only 2 main methods - `addMessage()` and `signAndSend()`
+- **🔒 Type Safety**: Network parameter determines valid request shapes automatically
+- **🚀 Cross-Chain**: Unified interface for EVM and Solana networks
+
+## 🚀 Quick Start
+### Install the SDK
+```bash
+npm install @circuitorg/agents-sdk
+# or
+yarn add @circuitorg/agents-sdk
+# or
+bun add @circuitorg/agents-sdk
+```
+
+### Sample SDK Usage
+>**NOTE:** The fastest, and recommended, way to get started is to setup an agent via the circuit [CLI](https://github.com/circuitorg/agents-cli)'s 'circuit agent init' command. This will setup a sample agent directory with the necessary agent wireframe, and configure the cli to allow you for easy testing and deployment. You just simply need to add in your secret formula to the execution and stop functions. 
+
+```typescript
+import { AgentSdk } from "@circuitorg/agents-sdk";
+
+// Initialize the sdk
+const sdk = new AgentSdk({
+  sessionId: 123,
+});
+```
+
+## 🎯 Core SDK API (Only 2 Methods!)
+
+### 1. Add Messages to Timeline
+
+```typescript
+await sdk.addMessage({ 
+  type: "observe", 
+  shortMessage: "Starting swap operation" 
+});
+```
+
+### 2. Sign & Send Transactions
+
+#### Ethereum (any EVM chain)
+
+```typescript
+// Native ETH transfer
+await sdk.signAndSend({
+  network: "ethereum:1", // Chain ID in network string
+  request: {
+    toAddress: "0x742d35cc6634C0532925a3b8D65e95f32B6b5582" as `0x${string}`,
+    data: "0x" as `0x${string}`,
+    value: "1000000000000000000" // 1 ETH in wei
+  },
+  message: "Sending 1 ETH"
+});
+
+// Contract interaction
+await sdk.signAndSend({
+  network: "ethereum:42161", // Arbitrum
+  request: {
+    toAddress: "0xTokenContract..." as `0x${string}`,
+    data: "0xa9059cbb..." as `0x${string}`, // encoded transfer()
+    value: "0"
+  }
+});
+```
+
+#### Solana
+
+```typescript
+await sdk.signAndSend({
+  network: "solana",
+  request: {
+    hexTransaction: "010001030a0b..." // serialized VersionedTransaction
+  }
+});
+```
+
+
+## 🔧 Sample Agent Structure
+
+### SDK Configuration
+
+```typescript
+import { Agent, AgentSdk, ExecutionFunctionContract, StopFunctionContract } from "@circuitorg/agents-sdk";
+
+// Agent execution function using the new AgentSdk v1.0 API
+const executionFunction: ExecutionFunctionContract = async (request) => {
+  console.log(`🚀 Agent execution called for session ${request.sessionId}`);
+  
+  const sdk = new AgentSdk({
+    sessionId: request.sessionId,
+  });
+
+  try {
+    // Get user's wallet address (use vitalik.eth for demo if no address provided)
+    const userAddress = request.sessionWalletAddress
+    
+    await sdk.addMessage({ 
+      type: "observe", 
+      shortMessage: `🚀 Agent SDK v1.0 demo - Hello ${userAddress}`
+    });
+  
+    return { success: true};
+  } catch (error) {
+    await sdk.addMessage({ 
+      type: "error", 
+      shortMessage: `Agent execution error: ${error instanceof Error ? error.message : 'Unknown error'}` 
+    });
+    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
+  }
+};
+
+const stopFunction: StopFunctionContract = async (request) => {
+  const sdk = new AgentSdk({ 
+    sessionId: request.sessionId,
+    testing: true 
+  });
+  
+  try {
+    await sdk.addMessage({ 
+      type: "observe", 
+      shortMessage: "🛑 Agent stopping with new SDK v1.0" 
+    });
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error instanceof Error ? error.message : "Unknown error" };
+  }
+};
+
+// DONT MODIFY BELOW THIS
+const agent = new Agent({ executionFunction, stopFunction });
+
+// Start the server for local development
+agent.run();
+
+// Export the agent for Cloudflare Workers
+export default agent.getWorkerExport();
+
+```
+
+

package/index.d.ts

@@ -0,0 +1,475 @@
+import * as hono from 'hono';
+import { z } from 'zod';
+
+/**
+ * Core type definitions for the Agent SDK
+ */
+
+/**
+ * Configuration for the SDK client
+ */
+interface SDKConfig {
+    /** Session ID for the current agent instance */
+    sessionId: number;
+    /** Enable verbose logging for debugging */
+    verbose?: boolean;
+    /** Enable testing mode to return mock responses */
+    testing?: boolean;
+    /** Optional base URL for local development (auto-detected if omitted) */
+    baseUrl?: string;
+}
+
+/**
+ * Network type definitions and guard functions
+ */
+type Network = `ethereum:${number}` | "solana";
+/**
+ * Type guard to check if network is Ethereum-based
+ * @param network - Network to check
+ * @returns true if network is ethereum:chainId format
+ */
+declare function isEthereumNetwork(network: Network): network is `ethereum:${number}`;
+/**
+ * Type guard to check if network is Solana
+ * @param network - Network to check
+ * @returns true if network is "solana"
+ */
+declare function isSolanaNetwork(network: Network): network is "solana";
+/**
+ * Extract chain ID from Ethereum network string
+ * @param network - Ethereum network string
+ * @returns Chain ID as number
+ */
+declare function getChainIdFromNetwork(network: `ethereum:${number}`): number;
+
+/**
+ * Request type definitions with conditional shapes based on network
+ */
+
+/**
+ * Main signAndSend request type with network-specific conditional shapes
+ */
+type SignAndSendRequest = {
+    network: Network;
+    /** Optional short message to be attached to the transaction for observability */
+    message?: string;
+} & ({
+    network: `ethereum:${number}`;
+    request: {
+        toAddress: `0x${string}`;
+        data: `0x${string}`;
+        value: string;
+    };
+} | {
+    network: "solana";
+    request: {
+        hexTransaction: string;
+    };
+});
+/**
+ * Message request for addMessage function
+ */
+type AddMessageRequest = {
+    type: "observe" | "validate" | "reflect" | "error" | "warning";
+    shortMessage: string;
+};
+
+/**
+ * Response type definitions
+ */
+/**
+ * Standard response from signAndSend operations
+ */
+type SignAndSendResponse = {
+    /** Internal transaction ID for tracking */
+    internalTransactionId: number;
+    /** Transaction hash once broadcast */
+    txHash: string;
+    /** Optional transaction URL (explorer link) */
+    transactionUrl?: string;
+};
+
+/**
+ * Main AgentSdk class with simplified API surface
+ */
+
+/**
+ * Main SDK entrypoint used by agents to interact with the Circuit backend.
+ *
+ * Provides a minimal, type-safe surface with two core methods that cover the
+ * majority of agent interactions:
+ *
+ * - `addMessage()` — emit timeline messages for observability and UX
+ * - `signAndSend()` — sign and broadcast transactions across networks
+ *
+ * Quick start:
+ * ```ts
+ * import { AgentSdk } from "@circuit/agent-sdk";
+ *
+ * const sdk = new AgentSdk({
+ *   sessionId: 12345,
+ * });
+ *
+ * await sdk.addMessage({ type: "observe", shortMessage: "Starting" });
+ * const tx = await sdk.signAndSend({
+ *   network: "ethereum:42161",
+ *   request: {
+ *     toAddress: "0xabc..." as `0x${string}`,
+ *     data: "0x" as `0x${string}`,
+ *     value: "0"
+ *   },
+ *   message: "Funding user"
+ * });
+ * ```
+ */
+declare class AgentSdk {
+    private client;
+    private config;
+    /**
+     * Create a new `AgentSdk` instance.
+     *
+     * @param config - SDK configuration
+     * @param config.sessionId - Numeric session identifier that scopes auth and actions
+     * @param config.verbose - When true, prints detailed request/response logs
+     * @param config.testing - When true, short-circuits network calls with mock values
+     * @param config.baseUrl - Override API base URL (detected automatically otherwise)
+     * @example
+     * ```ts
+     * const sdk = new AgentSdk({ sessionId: 42, verbose: true });
+     * ```
+     */
+    constructor(config: SDKConfig);
+    private log;
+    /**
+     * Add a message to the agent timeline.
+     *
+     * Messages show up in session traces and UIs and are useful for observability,
+     * human-in-the-loop reviews, and debugging.
+     *
+     * @param message - Timeline message
+     * @param message.type - One of: `"observe" | "validate" | "reflect" | "error" | "warning"`
+     * @param message.shortMessage - Short, human-readable message (<= 250 chars)
+     * @returns Resolves when the message is accepted by the backend
+     * @example
+     * ```ts
+     * await sdk.addMessage({ type: "observe", shortMessage: "Starting swap" });
+     * ```
+     */
+    addMessage(message: AddMessageRequest): Promise<void>;
+    /**
+     * Sign and broadcast a transaction on the specified network.
+     *
+     * The backend performs validation and policy checks; you only need to provide
+     * the minimal request shape for the selected network.
+     *
+     * @param request - Network-specific transaction input
+     * @param request.network - `"solana"` or `"ethereum:${number}"`
+     * @param request.message - Optional human-readable context message (short), stored with the transaction
+     * @param request.request - Transaction payload
+     * - For Ethereum: `{ toAddress, data, value }`
+     *   - `toAddress`: recipient contract or EOA as `0x${string}`
+     *   - `data`: calldata as `0x${string}` (use `"0x"` for simple transfers)
+     *   - `value`: stringified wei amount
+     * - For Solana: `{ hexTransaction }`
+     *   - `hexTransaction`: serialized `VersionedTransaction` as hex string
+     * @returns Promise resolving to `{ internalTransactionId, txHash, transactionUrl? }`
+     * @throws Error if the network is unsupported or the backend rejects the request
+     * @example
+     * ```ts
+     * // Ethereum (Arbitrum) native transfer
+     * await sdk.signAndSend({
+     *   network: "ethereum:42161",
+     *   request: {
+     *     toAddress: "0xabc..." as `0x${string}`,
+     *     data: "0x" as `0x${string}`,
+     *     value: "1000000000000000" // 0.001 ETH
+     *   },
+     *   message: "Self-transfer demo"
+     * });
+     *
+     * // Solana
+     * await sdk.signAndSend({
+     *   network: "solana",
+     *   request: { hexTransaction: "01ab..." },
+     *   message: "Swap with Jupiter"
+     * });
+     * ```
+     */
+    signAndSend(request: SignAndSendRequest): Promise<SignAndSendResponse>;
+    /**
+     * Handle EVM transaction signing and broadcasting
+     */
+    private handleEvmTransaction;
+    /**
+     * Handle Solana transaction signing and broadcasting
+     */
+    private handleSolanaTransaction;
+    /**
+     * Send messages to the agent timeline (migrated from AgentToolset)
+     */
+    private messageSend;
+}
+
+/**
+ * Low-level HTTP client used internally by the SDK.
+ *
+ * - Automatically detects Cloudflare Worker environment and uses service bindings
+ * - Falls back to HTTP requests for standard environments
+ * - For local development, automatically reads auth token from ~/.config/circuit/auth.json
+ * - Adds session ID and agent slug headers automatically
+ * - Emits verbose request/response logs when `SDKConfig.verbose` is enabled
+ *
+ * Although exported for advanced scenarios, most users should interact with
+ * higher-level abstractions like `AgentSdk` and `AgentUtils`.
+ */
+declare class APIClient {
+    private config;
+    private baseUrl;
+    private isCloudflareWorker;
+    private hasServiceBinding;
+    /**
+     * Create an API client.
+     * @param config - SDK configuration
+     * @param config.sessionId - Numeric session identifier propagated as header
+     * @param config.baseUrl - Override base URL for local development (auto-detected if omitted)
+     * @param config.verbose - Enable detailed logs for debugging
+     */
+    constructor(config: SDKConfig);
+    private getAgentSlug;
+    private getAuthHeaders;
+    private loadAuthConfig;
+    private log;
+    /**
+     * Perform a JSON HTTP request.
+     *
+     * Automatically uses service bindings when available, otherwise falls back to HTTP.
+     * Throws with a helpful message when the response is not ok.
+     *
+     * @param endpoint - API path beginning with `/v1/...`
+     * @param options - Fetch options (method, headers, body)
+     * @returns Parsed JSON response
+     * @throws Error when `response.ok` is false
+     */
+    private makeRequest;
+    /**
+     * HTTP GET convenience method.
+     * @param endpoint - API path beginning with `/v1/...`
+     */
+    get<T>(endpoint: string): Promise<T>;
+    /**
+     * HTTP POST convenience method sending a JSON body.
+     * @param endpoint - API path beginning with `/v1/...`
+     * @param data - Optional JSON payload to serialize
+     */
+    post<T>(endpoint: string, data?: any): Promise<T>;
+}
+
+/**
+ * Request object for agent functions containing session and wallet information.
+ * Provided to your `execution`, `chat`, and `stop` handlers.
+ */
+declare const AgentRequestSchema: z.ZodObject<{
+    sessionId: z.ZodNumber;
+    sessionWalletAddress: z.ZodString;
+    otherParameters: z.ZodOptional<z.ZodObject<{}, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Standard response format for agent functions (execute and stop commands).
+ */
+declare const AgentResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Health check response format.
+ */
+declare const HealthResponseSchema: z.ZodObject<{
+    status: z.ZodString;
+}, z.core.$strip>;
+type AgentRequest = z.infer<typeof AgentRequestSchema>;
+type AgentResponse = z.infer<typeof AgentResponseSchema>;
+type HealthResponse = z.infer<typeof HealthResponseSchema>;
+/**
+ * Contract for agent execution functions. Called to perform the agent's main task.
+ * @param request - Contains session info and wallet address to operate with
+ * @returns Promise resolving to a success/error response
+ * @example
+ * ```typescript
+ * // Execution function implementation
+ * const executionFunction: ExecutionFunctionContract = async (request) => {
+ *   const agentToolset = new AgentToolset({ sessionId: request.sessionId });
+ *
+ *   try {
+ *     // Send status message
+ *     await agentToolset.messageSend([{
+ *       type: "observe",
+ *       shortMessage: "Starting agent execution..."
+ *     }]);
+ *
+ *     // Example: Send a transaction
+ *     const { txResult, broadcastResult } = await agentToolset.transactionSignAndBroadcast({
+ *       chainId: 1,
+ *       toAddress: request.sessionWalletAddress,
+ *       data: "0x",
+ *       valueWei: "1000000000000000000" // 1 ETH
+ *     });
+ *
+ *     if (broadcastResult.status === "broadcasted") {
+ *       return {
+ *         success: true,
+ *         message: "Transaction executed successfully"
+ *       };
+ *     }
+ *
+ *     return {
+ *       success: false,
+ *       error: "Transaction failed to broadcast",
+ *       message: "Execution failed"
+ *     };
+ *   } catch (error) {
+ *     return {
+ *       success: false,
+ *       error: error instanceof Error ? error.message : "Unknown error",
+ *       message: "Execution failed"
+ *     };
+ *   }
+ * };
+ * ```
+ */
+type ExecutionFunctionContract = (request: AgentRequest) => Promise<AgentResponse>;
+/**
+ * Contract for agent stop/winddown function. Called to gracefully shut down and
+ * run cleanup logic (e.g. withdrawing positions, updating schedules).
+ * @param request - Contains session information and wallet address to operate with
+ * @returns Promise resolving to a success/error response
+ * @example
+ * ```typescript
+ * // Winddown function implementation
+ * const stopFunction: StopFunctionContract = async (request) => {
+ *   const agentToolset = new AgentToolset({ sessionId: request.sessionId });
+ *
+ *   try {
+ *     // Notify about shutdown
+ *     await agentToolset.messageSend([{
+ *       type: "observe",
+ *       shortMessage: "Agent shutting down...",
+ *       longMessage: "Cleaning up resources and saving state"
+ *     }]);
+ *
+ *     // Example: Update sleep interval before shutdown
+ *     await agentToolset.sessionUpdateSleepInterval({
+ *       sleepMinutes: 60 // Set longer interval during inactive period
+ *     });
+ *
+ *     // Example: Final status message
+ *     await agentToolset.messageSend([{
+ *       type: "observe",
+ *       shortMessage: "Shutdown complete",
+ *       longMessage: `Agent ${request.sessionId} successfully shut down`
+ *     }]);
+ *
+ *     return {
+ *       success: true,
+ *       message: "Agent stopped successfully"
+ *     };
+ *   } catch (error) {
+ *     return {
+ *       success: false,
+ *       error: error instanceof Error ? error.message : "Failed to clean up",
+ *       message: "Stop operation failed"
+ *     };
+ *   }
+ * };
+ * ```
+ */
+type StopFunctionContract = (request: AgentRequest) => Promise<AgentResponse>;
+/**
+ * Contract for agent chat functions. Handle interactive messaging with the agent.
+ * @param request - Contains session information and wallet address to operate with
+ * @returns Promise resolving to a success/error response
+ * @example
+ * ```typescript
+ * // Chat function implementation
+ * const chatFunction: ChatFunctionContract = async (request) => {
+ *   const agentToolset = new AgentToolset({ sessionId: request.sessionId });
+ *
+ *   await agentToolset.messageSend([{
+ *     type: "observe",
+ *     shortMessage: "Processing chat message",
+ *     longMessage: `Received message for wallet ${request.sessionWalletAddress}`
+ *   }]);
+ *
+ *   return {
+ *     success: true,
+ *     message: "Chat message processed"
+ *   };
+ * };
+ * ```
+ */
+type ChatFunctionContract = (request: AgentRequest) => Promise<AgentResponse>;
+/**
+ * Contract for agent health check functions. Handle health status requests.
+ * @returns Promise resolving to an object with a status field
+ * @example
+ * ```typescript
+ * // Health check function implementation
+ * const healthCheckFunction: HealthCheckFunctionContract = async () => {
+ *   // Check database connection, external services, etc.
+ *   const isHealthy = await checkSystemHealth();
+ *
+ *   return {
+ *     status: isHealthy ? "healthy" : "unhealthy",
+ *     // Optional additional fields
+ *     uptime: process.uptime(),
+ *     timestamp: new Date().toISOString()
+ *   };
+ * };
+ * ```
+ */
+type HealthCheckFunctionContract = () => Promise<HealthResponse>;
+/**
+ * Configuration object for creating a new agent
+ */
+interface AgentConfig {
+    /** Main execution function that implements the agent's core logic */
+    executionFunction: ExecutionFunctionContract;
+    /** Optional chat function for handling interactive messaging */
+    chatFunction?: ChatFunctionContract;
+    /** Optional winddown function for cleanup operations, this is called when the agent is stopped */
+    stopFunction?: StopFunctionContract;
+    /** Optional health check function for monitoring agent health status */
+    healthCheckFunction?: HealthCheckFunctionContract;
+}
+/**
+ * HTTP server wrapper for agent functions.
+ *
+ * Exposes the following endpoints:
+ * - `POST /execute` — required, calls your execution function
+ * - `POST /chat` — optional, when a `chatFunction` is provided
+ * - `POST /stop` and `DELETE /` — optional, when a `stopFunction` is provided
+ * - `GET /health` — always available, uses provided or default health check
+ */
+declare class Agent {
+    private app;
+    private executionFunction;
+    private chatFunction?;
+    private stopFunction?;
+    private healthCheckFunction?;
+    /**
+     * Create a new `Agent` with the provided handlers.
+     * @param config - Execution function is required; chat/stop/health are optional.
+     */
+    constructor(config: AgentConfig);
+    private setupRoutes;
+    private getPortFromPackageJson;
+    run(port?: number): {
+        fetch: (request: Request, Env?: unknown, executionCtx?: hono.ExecutionContext) => Response | Promise<Response>;
+    } | undefined;
+    /** Get the worker export for Cloudflare Workers environments. */
+    getWorkerExport(): {
+        fetch: (request: Request, Env?: unknown, executionCtx?: hono.ExecutionContext) => Response | Promise<Response>;
+    };
+}
+
+export { APIClient, type AddMessageRequest, Agent, AgentSdk, type ExecutionFunctionContract, type Network, type SDKConfig, type SignAndSendRequest, type SignAndSendResponse, type StopFunctionContract, getChainIdFromNetwork, isEthereumNetwork, isSolanaNetwork };

package/index.js

@@ -0,0 +1 @@
+var __getOwnPropNames=Object.getOwnPropertyNames,__require=(t=>"undefined"!=typeof require?require:"undefined"!=typeof Proxy?new Proxy(t,{get:(t,e)=>("undefined"!=typeof require?require:t)[e]}):t)(function(t){if("undefined"!=typeof require)return require.apply(this,arguments);throw Error('Dynamic require of "'+t+'" is not supported')}),__commonJS=(t,e)=>function(){return e||(0,t[__getOwnPropNames(t)[0]])((e={exports:{}}).exports,e),e.exports},require_auth_loader=__commonJS({"src/utils/auth-loader.cjs"(exports,module){function loadAuthFromFileSystem(){try{if("undefined"==typeof process||!process.env?.HOME)return;const fs=eval("require")("fs"),path=eval("require")("path"),authPath=path.join(process.env.HOME,".config","circuit","auth.json");if(!fs.existsSync(authPath))return;const authContent=fs.readFileSync(authPath,"utf-8");return JSON.parse(authContent)}catch(t){return}}module.exports={loadAuthFromFileSystem:loadAuthFromFileSystem}}});import{z}from"zod";var API_BASE_URL_LOCAL="https://agents.circuit.org",MessageTypeSchema=z.enum(["observe","validate","reflect","error","warning"]),MessageSchema=z.object({type:MessageTypeSchema,shortMessage:z.string().max(250)}),MessagesRequestSchema=z.array(MessageSchema),MessagesResponseSchema=z.object({status:z.number(),message:z.string()}),TransactionSendRequestSchema=z.object({chainId:z.number(),toAddress:z.string(),data:z.string(),valueWei:z.string(),message:z.string().max(250).optional(),gas:z.number().optional(),maxFeePerGas:z.string().optional(),maxPriorityFeePerGas:z.string().optional()}),SolanaTransactionRequestSchema=z.object({hexTransaction:z.string(),message:z.string().max(250).optional()}),APIClient=class{config;baseUrl;isCloudflareWorker(){return"undefined"!=typeof globalThis&&void 0!==globalThis.Cloudflare}hasServiceBinding(){return this.isCloudflareWorker()&&void 0!==globalThis.AGENT_TOOLSET_SERVICE}constructor(t){this.config=t,this.baseUrl=t.baseUrl||API_BASE_URL_LOCAL}getAgentSlug(){return"undefined"!=typeof process&&process.env?.CIRCUIT_AGENT_SLUG?process.env.CIRCUIT_AGENT_SLUG:void 0!==globalThis.CIRCUIT_AGENT_SLUG?globalThis.CIRCUIT_AGENT_SLUG:void 0}getAuthHeaders(){const t={};t["X-Session-Id"]=this.config.sessionId.toString();const e=this.getAgentSlug();if(e&&(t["X-Agent-Slug"]=e),!this.hasServiceBinding())try{const e=this.loadAuthConfig();e?.sessionToken&&(t.Authorization=`Bearer ${e.sessionToken}`)}catch(t){}return t}loadAuthConfig(){try{const{loadAuthFromFileSystem:t}=require_auth_loader();return t()}catch(t){this.config.verbose}}log(t,e){this.config.verbose}async makeRequest(t,e={}){const s={...{"Content-Type":"application/json",...this.getAuthHeaders()},...e.headers};let r;if(this.log("=== REQUEST DETAILS ==="),this.log("Endpoint:",t),this.log("Method:",e.method||"GET"),this.log("Headers:",s),this.log("Body:",e.body),this.log("Session ID:",this.config.sessionId),this.log("Agent Slug:",this.getAgentSlug()||"not set"),this.log("Using Service Binding:",this.hasServiceBinding()),this.log("====================="),this.hasServiceBinding()){const n=globalThis.AGENT_TOOLSET_SERVICE,o=`https://agents.circuit.org${t}`,a={...e,headers:s};r=await n.fetch(o,a)}else{const n=`${this.baseUrl}${t}`,o={...e,headers:s};r=await fetch(n,o)}if(this.log("=== RESPONSE DETAILS ==="),this.log("Status:",r.status),this.log("Status Text:",r.statusText),this.log("Response Headers:",Object.fromEntries(r.headers.entries())),this.log("======================"),!r.ok){const t=await r.json().catch(()=>({}));throw this.log("=== ERROR RESPONSE ==="),this.log("Error Data:",t),this.log("===================="),new Error(t.message||`HTTP ${r.status}: ${r.statusText}`)}const n=await r.json();return this.log("=== SUCCESS RESPONSE ==="),this.log("Response Data:",n),this.log("======================"),n}async get(t){return this.makeRequest(t,{method:"GET"})}async post(t,e){return this.makeRequest(t,{method:"POST",body:e?JSON.stringify(e):void 0})}};function isEthereumNetwork(t){return t.startsWith("ethereum:")}function isSolanaNetwork(t){return"solana"===t}function getChainIdFromNetwork(t){return Number(t.split(":")[1])}var AgentSdk=class{client;config;constructor(t){this.config=t,this.client=new APIClient(t)}log(t,e){this.config.verbose}async addMessage(t){this.log("=== ADD MESSAGE ==="),this.log("Message:",t),this.log("===================");const e=[{type:t.type,shortMessage:t.shortMessage}];await this.messageSend(e)}async signAndSend(t){if(this.log("=== SIGN AND SEND ==="),this.log("Request:",t),this.log("Testing mode:",this.config.testing),this.log("===================="),this.config.testing)return{internalTransactionId:123,txHash:isEthereumNetwork(t.network)?"0xTEST":"TEST_SOL_TX",transactionUrl:void 0};if(isEthereumNetwork(t.network)){const e=getChainIdFromNetwork(t.network);if("toAddress"in t.request)return this.handleEvmTransaction({chainId:e,toAddress:t.request.toAddress,data:t.request.data,valueWei:t.request.value,message:t.message})}if(isSolanaNetwork(t.network)&&"hexTransaction"in t.request)return this.handleSolanaTransaction({hexTransaction:t.request.hexTransaction,message:t.message});throw new Error(`Unsupported network: ${t.network}`)}async handleEvmTransaction(t){const e=await this.client.post("/v1/transactions/evm",t),s=await this.client.post(`/v1/transactions/evm/${e.internalTransactionId}/broadcast`);return{internalTransactionId:e.internalTransactionId,txHash:s.txHash,transactionUrl:s.transactionUrl}}async handleSolanaTransaction(t){const e=await this.client.post("/v1/transactions/solana",t),s=await this.client.post(`/v1/transactions/solana/${e.internalTransactionId}/broadcast`);return{internalTransactionId:e.internalTransactionId,txHash:s.txHash,transactionUrl:s.transactionUrl}}async messageSend(t){return this.config.testing?{status:200,message:"Messages added successfully (TESTING)"}:this.client.post("/v1/messages",t)}};import{zValidator}from"@hono/zod-validator";import{Hono}from"hono";import{cors}from"hono/cors";import{z as z2}from"zod";var AgentRequestSchema=z2.object({sessionId:z2.number(),sessionWalletAddress:z2.string(),otherParameters:z2.object().optional()}),AgentResponseSchema=z2.object({success:z2.boolean(),error:z2.string().optional(),message:z2.string().optional()}),HealthResponseSchema=z2.object({status:z2.string()}),Agent=class{app;executionFunction;chatFunction;stopFunction;healthCheckFunction;constructor(t){this.app=new Hono,this.executionFunction=t.executionFunction,this.chatFunction=t.chatFunction,this.stopFunction=t.stopFunction,this.healthCheckFunction=t.healthCheckFunction||(async()=>({status:"healthy"})),this.app.use("*",cors()),this.setupRoutes()}setupRoutes(){this.app.post("/execute",zValidator("json",AgentRequestSchema),async t=>{try{const e=t.req.valid("json"),s=await this.executionFunction(e);return t.json(s)}catch(e){return t.json({success:!1,error:e instanceof Error?e.message:"Unknown error",message:"Execution failed"},500)}}),this.chatFunction&&this.app.post("/chat",zValidator("json",AgentRequestSchema),async t=>{try{const e=t.req.valid("json"),s=await(this.chatFunction?.(e));return t.json(s)}catch(e){return t.json({success:!1,error:e instanceof Error?e.message:"Unknown error",message:"Chat failed"},500)}}),this.stopFunction&&(this.app.post("/stop",zValidator("json",AgentRequestSchema),async t=>{try{const e=t.req.valid("json"),s=await(this.stopFunction?.(e));return t.json(s)}catch(e){return t.json({success:!1,error:e instanceof Error?e.message:"Unknown error",message:"Stop operation failed"},500)}}),this.app.delete("/",zValidator("json",AgentRequestSchema),async t=>{try{const e=t.req.valid("json"),s=await(this.stopFunction?.(e));return t.json(s)}catch(e){return t.json({success:!1,error:e instanceof Error?e.message:"Unknown error",message:"Stop operation failed"},500)}})),this.app.get("/health",async t=>{try{const e=await(this.healthCheckFunction?.());return t.json(e)}catch(e){return t.json({status:"unhealthy",error:e instanceof Error?e.message:"Unknown error",timestamp:(new Date).toISOString()},500)}})}getPortFromPackageJson(){try{const t=__require("fs"),e=__require("path").join(process.cwd(),"package.json");if(t.existsSync(e)){const s=JSON.parse(t.readFileSync(e,"utf-8"));if(s.circuit?.port)return Number.parseInt(s.circuit.port,10)}}catch(t){}return null}run(port){const isCloudflareWorker="undefined"!=typeof globalThis&&void 0!==globalThis.Cloudflare;if(isCloudflareWorker)return this.getWorkerExport();const bunEnv=globalThis.Bun?.env,envPort=process.env.AGENT_PORT||bunEnv?.AGENT_PORT,packageJsonPort=this.getPortFromPackageJson();let finalPort=port;!finalPort&&envPort&&(finalPort=Number.parseInt(envPort,10)),!finalPort&&packageJsonPort&&(finalPort=packageJsonPort),finalPort||(finalPort=3e3);try{const req=eval("require"),{serve:serve}=req("@hono/node-server");serve({fetch:this.app.fetch,port:finalPort})}catch(t){process.exit(1)}}getWorkerExport(){return{fetch:this.app.fetch}}};function createAgentHandler(t,e,s,r){return new Agent({executionFunction:t,chatFunction:e,stopFunction:s,healthCheckFunction:r})}export{APIClient,Agent,AgentSdk,getChainIdFromNetwork,isEthereumNetwork,isSolanaNetwork};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@circuitorg/agent-sdk",
+  "version": "1.0.0",
+  "description": "typescript sdk for the Agent Toolset Service",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "postbuild": "cp package.json dist && cp README.md dist",
+    "dev": "tsup --watch",
+    "test": "jest --passWithNoTests",
+    "test:package": "./scripts/test-package.sh",
+    "test:install": "./scripts/test-install.sh",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write ."
+  },
+  "keywords": [
+    "agent",
+    "toolset",
+    "sdk",
+    "blockchain",
+    "transactions"
+  ],
+  "author": "circuitorg",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/circuitorg/agents-sdk/issues"
+  },
+  "homepage": "https://github.com/circuitorg/agents-sdk#readme",
+  "sideEffects": false,
+  "browser": {
+    "ws": "./src/stubs/ws-stub.js",
+    "@solana/rpc-subscriptions": "./src/stubs/subscriptions-stub.js",
+    "@solana/rpc-subscriptions-spec": "./src/stubs/subscriptions-stub.js",
+    "@solana/rpc-subscriptions-channel-websocket": "./src/stubs/subscriptions-stub.js",
+    "@solana/subscribable": "./src/stubs/subscriptions-stub.js",
+    "@solana/transaction-confirmation": "./src/stubs/subscriptions-stub.js"
+  },
+  "dependencies": {
+    "@hono/zod-validator": "^0.7.2",
+    "@solana-program/system": "^0.7.0",
+    "@solana/kit": "^2.3.0",
+    "@solana/transactions": "^2.3.0",
+    "hono": "^4.9.1",
+    "zod": "^4.0.17"
+  },
+  "optionalDependencies": {
+    "@hono/node-server": "^1.18.2",
+    "@solana-program/token": "0.5.1",
+    "@solana-program/token-2022": "0.4.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.7.0",
+    "@types/jest": "29.5.14",
+    "@types/node": "^20.19.7",
+    "dts-bundle-generator": "^9.5.1",
+    "esbuild": "^0.25.9",
+    "jest": "29.7.0",
+    "terser": "^5.43.1",
+    "tsup": "^8.5.0",
+    "typescript": "5.8.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/circuitorg/agents-sdk.git"
+  }
+}

package/stubs/subscriptions-stub.js

@@ -0,0 +1,5 @@
+export default {};
+export const createSolanaRpcSubscriptions = () => {
+  throw new Error("Subscriptions disabled in SDK");
+};
+

package/stubs/ws-stub.js

@@ -0,0 +1,3 @@
+export default {};
+export const WebSocket = undefined;
+

package/utils/auth-loader.cjs

@@ -0,0 +1,29 @@
+// This file is intentionally in JavaScript to avoid TypeScript/bundler transformations
+// It provides a way to load auth config from the file system in Node.js environments
+
+function loadAuthFromFileSystem() {
+  try {
+    // Check if we're in a Node.js environment
+    if (typeof process === 'undefined' || !process.env?.HOME) {
+      return undefined;
+    }
+
+    // Use dynamic require to avoid bundler processing
+    const fs = eval("require")('fs');
+    const path = eval("require")('path');
+    
+    const authPath = path.join(process.env.HOME, '.config', 'circuit', 'auth.json');
+    
+    if (!fs.existsSync(authPath)) {
+      return undefined;
+    }
+    
+    const authContent = fs.readFileSync(authPath, 'utf-8');
+    return JSON.parse(authContent);
+  } catch (error) {
+    // Silently fail if we can't read the auth config
+    return undefined;
+  }
+}
+
+module.exports = { loadAuthFromFileSystem };