@balchemyai/agent-sdk 0.1.0

package/README.md

@@ -0,0 +1,282 @@
+# @balchemyai/agent-sdk
+
+TypeScript SDK for Balchemy external AI agents. Handles onboarding (SIWE wallet-based or walletless Identity flow), MCP tool access, token lifecycle management, and real-time SSE event streaming.
+
+## Installation
+
+```sh
+npm install @balchemyai/agent-sdk
+```
+
+## Auth Paths
+
+### Path 1 — SIWE (wallet-based)
+
+Use this when your agent controls a Solana or EVM wallet and can sign messages.
+
+```ts
+import { BalchemyAgentSdk } from "@balchemyai/agent-sdk";
+
+const sdk = new BalchemyAgentSdk({
+  apiBaseUrl: "https://api.balchemy.ai/api",
+});
+
+// 1. Request a nonce and SIWS message
+const { message, nonce } = await sdk.requestSiweNonce({
+  address: "YOUR_WALLET_ADDRESS",
+  chainId: 8453,
+  domain: "youragent.example.com",
+  uri: "https://youragent.example.com",
+  statement: "Sign in to Balchemy",
+});
+
+// 2. Sign `message` with your wallet (off-chain, using your signing library)
+const signature = await wallet.signMessage(message);
+
+// 3. Onboard
+const response = await sdk.onboardWithSiwe({
+  message,
+  signature,
+  agentId: "your-agent-unique-id",
+  scope: "trade", // "read" | "trade"
+});
+
+const mcp = sdk.connectMcp({
+  endpoint: response.mcp.endpoint,
+  apiKey: response.mcp.apiKey ?? "",
+});
+```
+
+### Path 2 — Identity / Walletless
+
+Use this when your agent has an HMAC-signed identity token (for balchemy native) or ES256 JWT (for external providers) from a provider registered with Balchemy.
+
+```ts
+import { BalchemyAgentSdk } from "@balchemyai/agent-sdk";
+
+const sdk = new BalchemyAgentSdk({
+  apiBaseUrl: "https://api.balchemy.ai/api",
+});
+
+const response = await sdk.onboardWithIdentity({
+  provider: "your-registered-provider-id",
+  identityToken: "YOUR_PROVIDER_JWT",
+  agentId: "your-agent-unique-id",
+  chainId: 8453,
+  scope: "trade",
+});
+
+const mcp = sdk.connectMcp({
+  endpoint: response.mcp.endpoint,
+  apiKey: response.mcp.apiKey ?? "",
+});
+```
+
+## Using the MCP Client
+
+```ts
+// List available tools
+const { tools } = await mcp.listTools();
+
+// Natural language query
+const reply = await mcp.askBot({ message: "What is the price of SOL?" });
+
+// Execute an agent instruction
+const result = await mcp.agentExecute({
+  instruction: "Find a low-risk setup on Base with 50 USDC",
+});
+
+// EVM quote (read-only, no wallet interaction)
+const quote = await mcp.evmQuote({
+  chainId: 8453,
+  sellToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
+  buyToken:  "0x4200000000000000000000000000000000000006", // WETH on Base
+  sellAmount: "50000000", // 50 USDC (6 decimals)
+});
+
+// EVM swap (submit: false = pending order, submit: true = on-chain execution)
+const swap = await mcp.evmSwap({
+  chainId: 8453,
+  sellToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  buyToken:  "0x4200000000000000000000000000000000000006",
+  sellAmount: "50000000",
+  submit: true,
+});
+```
+
+## Tool Exposure and Scope
+
+By default the MCP endpoint exposes **7 tools**: `ask_bot`, `trade_command`, `agent_execute`, `agent_research`, `agent_portfolio`, `agent_status`, `agent_config`.
+
+The full catalog of **106 tools** is available when the platform flag `MCP_EXPOSE_GRANULAR_TOOLS=true` is enabled on the bot. Contact the Balchemy team to enable granular tool access for your integration.
+
+Tool scopes:
+
+| Scope | Access |
+|-------|--------|
+| `"read"` | Read-only tools — market data, portfolio views, research |
+| `"trade"` | All read tools + trade execution tools |
+
+Pass `scope` during onboarding to receive an MCP key with the appropriate permissions.
+
+## Error Handling
+
+All SDK methods throw `AgentSdkError` on failure.
+
+```ts
+import { AgentSdkError } from "@balchemyai/agent-sdk";
+import type { AgentSdkErrorCode } from "@balchemyai/agent-sdk";
+
+try {
+  const result = await mcp.agentExecute({ instruction: "..." });
+} catch (err: unknown) {
+  if (err instanceof AgentSdkError) {
+    const code: AgentSdkErrorCode = err.code;
+    // "auth_error" | "policy_error" | "rate_limit" | "provider_auth_error"
+    // | "network_error" | "execution_error" | "invalid_response"
+    console.error(`[${code}] ${err.message}`, err.details);
+  }
+}
+```
+
+## Tool Response Helpers
+
+```ts
+import { getToolText, parseToolJson, isToolError } from "@balchemyai/agent-sdk";
+
+const response = await mcp.agentPortfolio();
+
+if (isToolError(response)) {
+  console.error("Tool returned an error:", getToolText(response));
+} else {
+  const data = parseToolJson(response); // T | null
+  console.log(data);
+}
+```
+
+## Token Management
+
+```ts
+import { TokenStore } from "@balchemyai/agent-sdk";
+
+const store = new TokenStore({
+  // Called when the stored token nears expiry — return a fresh OnboardingResponse
+  refreshFn: async () => {
+    return sdk.onboardWithIdentity({ ... });
+  },
+});
+
+await store.set(response);
+const token = await store.get(); // auto-refreshes if expiry < threshold
+```
+
+## Identity Access Token
+
+The `OnboardingResponse` includes an `identityAccess` field when the platform issues a short-lived access token alongside the MCP key.
+
+```ts
+import type { IdentityAccess } from "@balchemyai/agent-sdk";
+
+const access: IdentityAccess | undefined = response.identityAccess;
+if (access) {
+  console.log(access.scope);     // "read" | "trade"
+  console.log(access.expiresAt); // ISO timestamp
+}
+```
+
+## SSE Event Streaming
+
+```ts
+import { SseEventStream } from "@balchemyai/agent-sdk";
+import type { SseEvent } from "@balchemyai/agent-sdk";
+
+const stream = new SseEventStream(
+  "https://api.balchemy.ai/api/events",
+  response.mcp.apiKey ?? "",
+  { reconnectDelayMs: 2000, maxReconnects: 5 }
+);
+
+// Async iterator
+for await (const event of stream) {
+  const e: SseEvent = event;
+  console.log(e.event, e.data);
+}
+
+// Or callback-based
+const unsubscribe = stream.subscribe(
+  (event) => console.log(event),
+  (err)   => console.error(err)
+);
+// later: unsubscribe();
+```
+
+## Identity Token Revocation
+
+```ts
+// Revoke a token by JTI
+await sdk.revokeIdentityToken({ jti: "the-token-jti", ttlSeconds: 86400 });
+
+// Check revocation status
+const { revoked } = await sdk.getIdentityTokenRevokeStatus({ jti: "the-token-jti" });
+```
+
+## Platform Endpoints Reference
+
+| Endpoint | Path | Auth |
+|----------|------|------|
+| MCP server | `POST /api/mcp/{publicId}` | `Authorization: Bearer <mcp-api-key>` |
+| SIWE nonce | `POST /api/nest/auth/evm/nonce` | Public |
+| SIWE onboarding | `POST /api/public/erc8004/onboarding/siwe` | Public |
+| Walletless onboarding | `POST /api/public/erc8004/onboarding/identity` | Public |
+| Token revoke | `POST /api/public/erc8004/onboarding/tokens/revoke` | Public |
+| JWKS | `GET /.well-known/jwks.json` | Public |
+| MCP discovery | `GET /.well-known/mcp.json` | Public |
+| Agent directory | `GET /api/nest/agents/verified/page` | Public |
+
+> Note: the JWKS endpoint is served at `/.well-known/jwks.json` (root-relative, **not** under `/api`).
+
+## Platform Operator Setup
+
+To enable agent onboarding, the following environment variables must be configured on the backend:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AGENT_WALLETLESS_ONBOARDING_ENABLED` | For walletless path | Set to `true` to enable the identity/walletless onboarding endpoint. Default: `false`. |
+| `SIWE_DOMAIN_ALLOWLIST` | For SIWE path | Comma-separated list of allowed domains for SIWE message verification (e.g. `youragent.example.com,localhost`). |
+| `ERC8004_IDENTITY_PROVIDERS` | For walletless path | Comma-separated list of allowed identity provider IDs (e.g. `github-actions,openclaw`). |
+| `AGENT_IDENTITY_ISSUER_PRIVATE_KEY_PEM` | For identity tokens | ES256 private key (PEM or base64) for signing agent identity access tokens. Required if issuing short-lived identity tokens. |
+| `API_URL` | Always | Base API URL used to build MCP endpoint URLs in onboarding responses (e.g. `https://api.balchemy.ai/api`). |
+
+## Getting Started (Quickstart)
+
+1. Install the SDK:
+   ```sh
+   npm install @balchemyai/agent-sdk
+   ```
+
+2. Create an MCP API key for your bot via the Hub UI: `Hub > Your Bot > API Keys > Create Key`.
+
+3. Choose an auth path:
+   - **SIWE (wallet-based):** Your agent must control an EVM wallet and can sign messages.
+   - **Walletless (identity token):** Your agent has an HMAC-signed identity token (balchemy native) or ES256 JWT (external provider) from a registered provider. The platform operator must set `AGENT_WALLETLESS_ONBOARDING_ENABLED=true`.
+
+4. Run the relevant code example in the [Auth Paths](#auth-paths) section above.
+
+5. Use the returned `mcp.endpoint` and `mcp.apiKey` to make MCP tool calls.
+
+6. The MCP key is scoped — `"read"` for read-only tools, `"trade"` for trade execution tools. Choose at onboarding time via the `scope` parameter.
+
+## Notes
+
+- `agent_seed_request` is disabled on the platform. The `requestSeed()` method exists for backward compatibility but always throws a deterministic `AgentSdkError` with code `"execution_error"`.
+- `apiBaseUrl` must include the `/api` path segment and must **not** have a trailing slash.
+- The JWKS endpoint is at `/.well-known/jwks.json` (root-relative). Do not prefix with `/api`.
+- If walletless onboarding returns HTTP 403 with `code: "FEATURE_DISABLED"`, the platform operator needs to set `AGENT_WALLETLESS_ONBOARDING_ENABLED=true`.
+
+## Docs
+
+- [Error and retry strategy](docs/error-retry-strategy.md)
+- [Python parity backlog](docs/python-parity-backlog.md)
+- [Partner integration checklist](docs/partner-integration-checklist.md)
+- [Release policy](docs/release-policy.md)
+- Full API reference: [https://balchemy.ai/docs](https://balchemy.ai/docs)

package/dist/agent-loop/agent-loop.d.ts

@@ -0,0 +1,54 @@
+import type { AgentLoopConfig, AgentStatus } from './types';
+export declare class AgentLoop {
+    private readonly config;
+    private readonly sseEndpoint;
+    private readonly costTracker;
+    private readonly llm;
+    private readonly decisionHandler;
+    private readonly mcp;
+    private readonly modelRouter;
+    private readonly telemetry;
+    private webhookReceiver;
+    private sseStream;
+    private unsubscribeSse;
+    private status;
+    private startedAt;
+    private eventsReceived;
+    private decisionsExecuted;
+    private tradesExecuted;
+    private lastEventAt;
+    private lastTradeAt;
+    private seenTraceIds;
+    private portfolioCache;
+    private rulesCache;
+    /** publicId extracted from the MCP endpoint path (last path segment). */
+    private readonly publicId;
+    constructor(config: AgentLoopConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getStatus(): AgentStatus;
+    /**
+     * Send a user message to the bot via the ask_bot MCP tool.
+     * Parses the JSON envelope returned by the server and extracts the `reply`
+     * field if present; otherwise returns the raw text.
+     * On network / tool error, calls `config.onError` and returns an error string.
+     */
+    sendMessage(message: string): Promise<string>;
+    private handleEvent;
+    private processEvent;
+    /**
+     * Fetch the agent portfolio via `agent_portfolio` MCP tool.
+     * Result is cached for 30 seconds. On failure, returns an empty snapshot
+     * so the decision loop continues with degraded context.
+     */
+    private fetchPortfolio;
+    /**
+     * Fetch compressed behavior rules from the MCP resource
+     * `balchemy://behavior-rules/{publicId}`.
+     * Result is cached for 5 minutes. On failure, returns empty string
+     * so decisions still proceed without rule context.
+     */
+    private fetchBehaviorRules;
+    private createLlmAdapter;
+}
+//# sourceMappingURL=agent-loop.d.ts.map

package/dist/agent-loop/agent-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../../src/agent-loop/agent-loop.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EAMZ,MAAM,SAAS,CAAC;AAejB,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiB;IAC7C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,cAAc,CAA6B;IAEnD,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,YAAY,CAAqB;IAEzC,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,UAAU,CAA2B;IAE7C,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,MAAM,EAAE,eAAe;IAuC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B,SAAS,IAAI,WAAW;IAkBxB;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBnD,OAAO,CAAC,WAAW;YAsCL,YAAY;IAmF1B;;;;OAIG;YACW,cAAc;IAmB5B;;;;;OAKG;YACW,kBAAkB;IAmBhC,OAAO,CAAC,gBAAgB;CAuBzB"}

package/dist/agent-loop/agent-loop.js

@@ -0,0 +1,328 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentLoop = void 0;
+const sse_event_stream_1 = require("../streaming/sse-event-stream");
+const mcp_client_1 = require("../mcp/mcp-client");
+const llm_cost_tracker_1 = require("./llm-cost-tracker");
+const decision_handler_1 = require("./decision-handler");
+const webhook_receiver_1 = require("./webhook-receiver");
+const openai_1 = require("./llm-adapters/openai");
+const anthropic_1 = require("./llm-adapters/anthropic");
+const model_router_1 = require("./model-router");
+const telemetry_reporter_1 = require("./telemetry-reporter");
+const PORTFOLIO_TTL_MS = 30_000; // 30 seconds
+const RULES_TTL_MS = 5 * 60_000; // 5 minutes
+class AgentLoop {
+    config;
+    sseEndpoint;
+    costTracker;
+    llm;
+    decisionHandler;
+    mcp;
+    modelRouter;
+    telemetry;
+    webhookReceiver = null;
+    sseStream = null;
+    unsubscribeSse = null;
+    status = 'stopped';
+    startedAt = 0;
+    eventsReceived = 0;
+    decisionsExecuted = 0;
+    tradesExecuted = 0;
+    lastEventAt;
+    lastTradeAt;
+    seenTraceIds = new Set();
+    portfolioCache = null;
+    rulesCache = null;
+    /** publicId extracted from the MCP endpoint path (last path segment). */
+    publicId;
+    constructor(config) {
+        this.config = config;
+        this.sseEndpoint = config.sseEndpoint ??
+            `${config.mcpEndpoint}/events/sse`;
+        // Extract publicId from endpoint (last path segment after filtering empty segments)
+        this.publicId = config.mcpEndpoint.split('/').filter(Boolean).pop() ?? '';
+        this.costTracker = new llm_cost_tracker_1.LlmCostTracker({
+            maxDailyUsd: config.maxDailyLlmCost ?? 5,
+        });
+        this.llm = this.createLlmAdapter();
+        this.decisionHandler = new decision_handler_1.DecisionHandler(this.llm, this.costTracker, {
+            maxConsecutiveFailures: config.maxConsecutiveFailures ?? 3,
+        });
+        this.mcp = (0, mcp_client_1.connectMcp)({
+            endpoint: config.mcpEndpoint,
+            apiKey: config.apiKey,
+            fetchFn: config.mcpFetchFn,
+        });
+        // ModelRouter activates only when both cheapModel and fullModel are configured.
+        if (config.cheapModel && config.fullModel) {
+            this.modelRouter = new model_router_1.ModelRouter({
+                cheapModel: config.cheapModel,
+                fullModel: config.fullModel,
+            });
+        }
+        else {
+            this.modelRouter = null;
+        }
+        // Derive the telemetry endpoint from the MCP endpoint:
+        //   https://api.balchemy.ai/mcp/abc123  →  https://api.balchemy.ai/api/agent-telemetry/abc123
+        const telemetryEndpoint = config.mcpEndpoint.replace(/\/mcp\//, '/api/agent-telemetry/');
+        this.telemetry = new telemetry_reporter_1.TelemetryReporter(telemetryEndpoint, config.apiKey);
+    }
+    async start() {
+        this.status = 'starting';
+        this.startedAt = Date.now();
+        this.telemetry.start();
+        // Start webhook receiver if configured
+        if (this.config.webhookPort && this.config.webhookSecret) {
+            this.webhookReceiver = new webhook_receiver_1.WebhookReceiver({
+                secret: this.config.webhookSecret,
+                port: this.config.webhookPort,
+            });
+            await this.webhookReceiver.start((event) => this.handleEvent(event));
+        }
+        // Start SSE stream
+        this.sseStream = new sse_event_stream_1.SseEventStream(this.sseEndpoint, this.config.apiKey, {
+            maxReconnects: 0, // unlimited
+            reconnectDelayMs: 2000,
+            maxReconnectDelayMs: 30_000,
+            jitterFactor: 0.25,
+        });
+        this.unsubscribeSse = this.sseStream.subscribe((sseEvent) => {
+            const event = {
+                id: sseEvent.id,
+                type: sseEvent.event,
+                data: sseEvent.data,
+                timestamp: Date.now(),
+                source: 'sse',
+            };
+            this.handleEvent(event);
+        }, (err) => {
+            this.config.onError?.(err instanceof Error ? err : new Error(String(err)));
+        });
+        this.status = 'running';
+        this.config.onStatusChange?.(this.getStatus());
+    }
+    async stop() {
+        this.status = 'stopped';
+        this.unsubscribeSse?.();
+        this.sseStream?.close();
+        await this.webhookReceiver?.stop();
+        this.telemetry.stop();
+        this.config.onStatusChange?.(this.getStatus());
+    }
+    getStatus() {
+        return {
+            status: this.status,
+            uptime: this.startedAt > 0 ? Date.now() - this.startedAt : 0,
+            eventsReceived: this.eventsReceived,
+            decisionsExecuted: this.decisionsExecuted,
+            tradesExecuted: this.tradesExecuted,
+            llmCallsToday: 0,
+            llmCostToday: this.costTracker.getTodaySpend(),
+            maxDailyLlmCost: this.config.maxDailyLlmCost ?? 5,
+            consecutiveLlmFailures: this.decisionHandler.getConsecutiveFailures(),
+            lastEventAt: this.lastEventAt,
+            lastTradeAt: this.lastTradeAt,
+            sseConnected: this.status === 'running',
+            webhookActive: this.webhookReceiver !== null,
+        };
+    }
+    /**
+     * Send a user message to the bot via the ask_bot MCP tool.
+     * Parses the JSON envelope returned by the server and extracts the `reply`
+     * field if present; otherwise returns the raw text.
+     * On network / tool error, calls `config.onError` and returns an error string.
+     */
+    async sendMessage(message) {
+        try {
+            const response = await this.mcp.callTool('ask_bot', { message });
+            const text = response.content?.find((c) => c.type === 'text')?.text ?? '';
+            try {
+                const parsed = JSON.parse(text);
+                const reply = parsed['reply'] ?? parsed['text'];
+                return typeof reply === 'string' ? reply : text;
+            }
+            catch {
+                return text;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.config.onError?.(new Error(`ask_bot failed: ${msg}`));
+            return `Error: ${msg}`;
+        }
+    }
+    handleEvent(event) {
+        // Deduplicate across SSE + webhook
+        if (event.id && this.seenTraceIds.has(event.id))
+            return;
+        if (event.id) {
+            this.seenTraceIds.add(event.id);
+            // Limit set size
+            if (this.seenTraceIds.size > 10_000) {
+                const first = this.seenTraceIds.values().next().value;
+                if (first)
+                    this.seenTraceIds.delete(first);
+            }
+        }
+        this.eventsReceived++;
+        this.lastEventAt = Date.now();
+        this.config.onEvent?.(event);
+        // Check budget
+        if (!this.costTracker.canCallLlm()) {
+            if (this.status !== 'budget_exhausted') {
+                this.status = 'budget_exhausted';
+                this.config.onStatusChange?.(this.getStatus());
+            }
+            return;
+        }
+        // Check if decision handler is paused (too many failures)
+        if (this.decisionHandler.isPaused()) {
+            if (this.status !== 'llm_failing') {
+                this.status = 'llm_failing';
+                this.config.onStatusChange?.(this.getStatus());
+            }
+            return;
+        }
+        // Process asynchronously
+        void this.processEvent(event);
+    }
+    async processEvent(event) {
+        try {
+            // Fetch portfolio and behavior rules (both cached)
+            const [portfolio, compressedRules] = await Promise.all([
+                this.fetchPortfolio(),
+                this.fetchBehaviorRules(),
+            ]);
+            // Apply model routing if configured
+            let selectedModel = null;
+            let modelTier = null;
+            if (this.modelRouter) {
+                const score = this.modelRouter.score(event);
+                selectedModel = this.modelRouter.selectModel(event);
+                modelTier = score >= 60 ? 'full' : 'cheap';
+                this.decisionHandler.setModel(selectedModel);
+                this.telemetry.reportModelRoute({
+                    eventType: event.type,
+                    score,
+                    selectedModel,
+                    tier: modelTier,
+                });
+            }
+            const llmCallStart = Date.now();
+            const decision = await this.decisionHandler.handleEvent(event, {
+                compressedRules,
+                portfolioValue: portfolio.totalValueSol ?? 0,
+                portfolioSummary: portfolio.summary,
+            });
+            const llmLatencyMs = Date.now() - llmCallStart;
+            // Report LLM call metrics — DecisionHandler exposes last call stats via getCostTracker
+            const lastCall = this.decisionHandler.getLastCallStats();
+            if (lastCall) {
+                this.telemetry.reportLlmCall({
+                    model: lastCall.model,
+                    inputTokens: lastCall.inputTokens,
+                    outputTokens: lastCall.outputTokens,
+                    latencyMs: llmLatencyMs,
+                    costUsd: lastCall.costUsd,
+                });
+            }
+            if (!decision || decision.action === 'hold')
+                return;
+            this.decisionsExecuted++;
+            this.config.onDecision?.(decision);
+            this.telemetry.reportDecision({
+                action: decision.action,
+                token: decision.token,
+                amount: decision.amount,
+                confidence: decision.confidence,
+                reasoning: decision.reasoning,
+            });
+            // Execute via MCP
+            if (decision.action === 'buy' || decision.action === 'sell') {
+                const tradeResponse = await this.mcp.callTool('trade_command', {
+                    intent: decision.action,
+                    token: decision.token,
+                    amount: decision.amount,
+                });
+                this.tradesExecuted++;
+                this.lastTradeAt = Date.now();
+                // Fire trade result callback
+                const resultText = tradeResponse.content?.find((c) => c.type === 'text')?.text ?? '';
+                this.config.onTradeResult?.({
+                    action: decision.action,
+                    token: decision.token,
+                    amount: decision.amount,
+                    response: resultText,
+                });
+            }
+        }
+        catch (err) {
+            this.config.onError?.(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    /**
+     * Fetch the agent portfolio via `agent_portfolio` MCP tool.
+     * Result is cached for 30 seconds. On failure, returns an empty snapshot
+     * so the decision loop continues with degraded context.
+     */
+    async fetchPortfolio() {
+        const now = Date.now();
+        if (this.portfolioCache && (now - this.portfolioCache.fetchedAt) < PORTFOLIO_TTL_MS) {
+            return this.portfolioCache.snapshot;
+        }
+        try {
+            const response = await this.mcp.agentPortfolio();
+            const parsed = (0, mcp_client_1.parseToolJson)(response);
+            const snapshot = parsed ?? {};
+            this.portfolioCache = { snapshot, fetchedAt: now };
+            return snapshot;
+        }
+        catch {
+            // Graceful degradation — continue with empty snapshot
+            this.config.onError?.(new Error('agent_portfolio fetch failed — continuing with empty snapshot'));
+            return {};
+        }
+    }
+    /**
+     * Fetch compressed behavior rules from the MCP resource
+     * `balchemy://behavior-rules/{publicId}`.
+     * Result is cached for 5 minutes. On failure, returns empty string
+     * so decisions still proceed without rule context.
+     */
+    async fetchBehaviorRules() {
+        const now = Date.now();
+        if (this.rulesCache && (now - this.rulesCache.fetchedAt) < RULES_TTL_MS) {
+            return this.rulesCache.compressed;
+        }
+        const uri = `balchemy://behavior-rules/${this.publicId}`;
+        try {
+            const contents = await this.mcp.readResource(uri);
+            const compressed = contents[0]?.text ?? '';
+            this.rulesCache = { compressed, fetchedAt: now };
+            return compressed;
+        }
+        catch {
+            // Graceful degradation — continue without rule context
+            this.config.onError?.(new Error('behavior-rules resource fetch failed — continuing without rules'));
+            return '';
+        }
+    }
+    createLlmAdapter() {
+        switch (this.config.llmProvider) {
+            case 'anthropic':
+                return new anthropic_1.AnthropicAdapter(this.config.llmApiKey, this.config.llmModel, this.config.llmTimeoutMs);
+            case 'openai':
+                return new openai_1.OpenAiAdapter(this.config.llmApiKey, this.config.llmModel, this.config.llmTimeoutMs, this.config.llmBaseUrl);
+            case 'custom':
+                throw new Error('Custom LLM adapter must be provided via config.llmAdapter');
+            default: {
+                const exhaustive = this.config.llmProvider;
+                throw new Error(`Unknown LLM provider: ${exhaustive}`);
+            }
+        }
+    }
+}
+exports.AgentLoop = AgentLoop;
+//# sourceMappingURL=agent-loop.js.map