@blockrun/clawrouter 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,357 @@
+/**
+ * OpenClaw Plugin Types (locally defined)
+ *
+ * OpenClaw's plugin SDK uses duck typing — these match the shapes
+ * expected by registerProvider() and the plugin system.
+ * Defined locally to avoid depending on internal OpenClaw paths.
+ */
+type ModelApi = "openai-completions" | "openai-responses" | "anthropic-messages" | "google-generative-ai" | "github-copilot" | "bedrock-converse-stream";
+type ModelDefinitionConfig = {
+    id: string;
+    name: string;
+    api?: ModelApi;
+    reasoning: boolean;
+    input: Array<"text" | "image">;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    headers?: Record<string, string>;
+};
+type ModelProviderConfig = {
+    baseUrl: string;
+    apiKey?: string;
+    api?: ModelApi;
+    headers?: Record<string, string>;
+    authHeader?: boolean;
+    models: ModelDefinitionConfig[];
+};
+type AuthProfileCredential = {
+    apiKey?: string;
+    type?: string;
+    [key: string]: unknown;
+};
+type ProviderAuthResult = {
+    profiles: Array<{
+        profileId: string;
+        credential: AuthProfileCredential;
+    }>;
+    configPatch?: Record<string, unknown>;
+    defaultModel?: string;
+    notes?: string[];
+};
+type WizardPrompter = {
+    text: (opts: {
+        message: string;
+        validate?: (value: string) => string | undefined;
+    }) => Promise<string | symbol>;
+    note: (message: string) => void;
+    progress: (message: string) => {
+        stop: (message?: string) => void;
+    };
+};
+type ProviderAuthContext = {
+    config: Record<string, unknown>;
+    agentDir?: string;
+    workspaceDir?: string;
+    prompter: WizardPrompter;
+    runtime: {
+        log: (message: string) => void;
+    };
+    isRemote: boolean;
+    openUrl: (url: string) => Promise<void>;
+};
+type ProviderAuthMethod = {
+    id: string;
+    label: string;
+    hint?: string;
+    kind: "oauth" | "api_key" | "token" | "device_code" | "custom";
+    run: (ctx: ProviderAuthContext) => Promise<ProviderAuthResult>;
+};
+type ProviderPlugin = {
+    id: string;
+    label: string;
+    docsPath?: string;
+    aliases?: string[];
+    envVars?: string[];
+    models?: ModelProviderConfig;
+    auth: ProviderAuthMethod[];
+    formatApiKey?: (cred: AuthProfileCredential) => string;
+};
+type PluginLogger = {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+};
+type OpenClawPluginApi = {
+    id: string;
+    name: string;
+    version?: string;
+    description?: string;
+    source: string;
+    config: Record<string, unknown> & {
+        models?: {
+            providers?: Record<string, ModelProviderConfig>;
+        };
+    };
+    pluginConfig?: Record<string, unknown>;
+    logger: PluginLogger;
+    registerProvider: (provider: ProviderPlugin) => void;
+    registerTool: (tool: unknown, opts?: unknown) => void;
+    registerHook: (events: string | string[], handler: unknown, opts?: unknown) => void;
+    registerHttpRoute: (params: {
+        path: string;
+        handler: unknown;
+    }) => void;
+    registerService: (service: unknown) => void;
+    registerCommand: (command: unknown) => void;
+    resolvePath: (input: string) => string;
+    on: (hookName: string, handler: unknown, opts?: unknown) => void;
+};
+type OpenClawPluginDefinition = {
+    id?: string;
+    name?: string;
+    description?: string;
+    version?: string;
+    register?: (api: OpenClawPluginApi) => void | Promise<void>;
+    activate?: (api: OpenClawPluginApi) => void | Promise<void>;
+};
+
+/**
+ * Smart Router Types
+ *
+ * Four classification tiers — REASONING is distinct from COMPLEX because
+ * reasoning tasks need different models (o3, gemini-pro) than general
+ * complex tasks (gpt-4o, sonnet-4).
+ */
+type Tier = "SIMPLE" | "MEDIUM" | "COMPLEX" | "REASONING";
+type RoutingDecision = {
+    model: string;
+    tier: Tier;
+    confidence: number;
+    method: "rules" | "llm";
+    reasoning: string;
+    costEstimate: number;
+    baselineCost: number;
+    savings: number;
+};
+type TierConfig = {
+    primary: string;
+    fallback: string[];
+};
+type ScoringConfig = {
+    tokenCountThresholds: {
+        simple: number;
+        complex: number;
+    };
+    codeKeywords: string[];
+    reasoningKeywords: string[];
+    simpleKeywords: string[];
+    technicalKeywords: string[];
+    creativeKeywords: string[];
+};
+type ClassifierConfig = {
+    ambiguousZone: [number, number];
+    llmModel: string;
+    llmMaxTokens: number;
+    llmTemperature: number;
+    promptTruncationChars: number;
+    cacheTtlMs: number;
+};
+type OverridesConfig = {
+    maxTokensForceComplex: number;
+    structuredOutputMinTier: Tier;
+};
+type RoutingConfig = {
+    version: string;
+    classifier: ClassifierConfig;
+    scoring: ScoringConfig;
+    tiers: Record<Tier, TierConfig>;
+    overrides: OverridesConfig;
+};
+
+/**
+ * Tier → Model Selection
+ *
+ * Maps a classification tier to the cheapest capable model.
+ * Builds RoutingDecision metadata with cost estimates and savings.
+ */
+
+type ModelPricing = {
+    inputPrice: number;
+    outputPrice: number;
+};
+
+/**
+ * Default Routing Config
+ *
+ * All routing parameters as a TypeScript constant.
+ * Operators override via openclaw.yaml plugin config.
+ */
+
+declare const DEFAULT_ROUTING_CONFIG: RoutingConfig;
+
+/**
+ * Smart Router Entry Point
+ *
+ * Classifies requests and routes to the cheapest capable model.
+ * Uses hybrid approach: rules first (< 1ms), LLM fallback for ambiguous cases.
+ */
+
+type RouterOptions = {
+    config: RoutingConfig;
+    modelPricing: Map<string, ModelPricing>;
+    payFetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    apiBase: string;
+};
+/**
+ * Route a request to the cheapest capable model.
+ *
+ * 1. Check overrides (large context, structured output)
+ * 2. Run rule-based classifier
+ * 3. If ambiguous, run LLM classifier
+ * 4. Select model for tier
+ * 5. Return RoutingDecision with metadata
+ */
+declare function route(prompt: string, systemPrompt: string | undefined, maxOutputTokens: number, options: RouterOptions): Promise<RoutingDecision>;
+
+/**
+ * Local x402 Proxy Server
+ *
+ * Sits between OpenClaw's pi-ai (which makes standard OpenAI-format requests)
+ * and BlockRun's API (which requires x402 micropayments).
+ *
+ * Flow:
+ *   pi-ai → http://localhost:{port}/v1/chat/completions
+ *        → proxy forwards to https://blockrun.ai/api/v1/chat/completions
+ *        → gets 402 → @x402/fetch signs payment → retries
+ *        → streams response back to pi-ai
+ *
+ * Phase 2 additions:
+ *   - Smart routing: when model is "blockrun/auto", classify query and pick cheapest model
+ *   - Usage logging: log every request as JSON line to ~/.openclaw/blockrun/logs/
+ */
+
+type ProxyOptions = {
+    walletKey: string;
+    apiBase?: string;
+    port?: number;
+    routingConfig?: Partial<RoutingConfig>;
+    onReady?: (port: number) => void;
+    onError?: (error: Error) => void;
+    onPayment?: (info: {
+        model: string;
+        amount: string;
+        network: string;
+    }) => void;
+    onRouted?: (decision: RoutingDecision) => void;
+};
+type ProxyHandle = {
+    port: number;
+    baseUrl: string;
+    close: () => Promise<void>;
+};
+/**
+ * Start the local x402 proxy server.
+ *
+ * Returns a handle with the assigned port, base URL, and a close function.
+ */
+declare function startProxy(options: ProxyOptions): Promise<ProxyHandle>;
+
+/**
+ * BlockRun ProviderPlugin for OpenClaw
+ *
+ * Registers BlockRun as an LLM provider in OpenClaw.
+ * Uses a local x402 proxy to handle micropayments transparently —
+ * pi-ai sees a standard OpenAI-compatible API at localhost.
+ */
+
+/**
+ * BlockRun provider plugin definition.
+ */
+declare const blockrunProvider: ProviderPlugin;
+
+/**
+ * BlockRun Model Definitions for OpenClaw
+ *
+ * Maps BlockRun's 30+ AI models to OpenClaw's ModelDefinitionConfig format.
+ * All models use the "openai-completions" API since BlockRun is OpenAI-compatible.
+ *
+ * Pricing is in USD per 1M tokens. Operators pay these rates via x402;
+ * they set their own markup when reselling to end users (Phase 2).
+ */
+
+type BlockRunModel = {
+    id: string;
+    name: string;
+    inputPrice: number;
+    outputPrice: number;
+    contextWindow: number;
+    maxOutput: number;
+    reasoning?: boolean;
+    vision?: boolean;
+};
+declare const BLOCKRUN_MODELS: BlockRunModel[];
+/**
+ * All BlockRun models in OpenClaw format.
+ */
+declare const OPENCLAW_MODELS: ModelDefinitionConfig[];
+/**
+ * Build a ModelProviderConfig for BlockRun.
+ *
+ * @param baseUrl - The proxy's local base URL (e.g., "http://127.0.0.1:12345")
+ */
+declare function buildProviderModels(baseUrl: string): ModelProviderConfig;
+
+/**
+ * Usage Logger
+ *
+ * Logs every LLM request as a JSON line to a daily log file.
+ * Files: ~/.openclaw/blockrun/logs/usage-YYYY-MM-DD.jsonl
+ *
+ * MVP: append-only JSON lines. No rotation, no cleanup.
+ * Logging never breaks the request flow — all errors are swallowed.
+ */
+type UsageEntry = {
+    timestamp: string;
+    model: string;
+    cost: number;
+    latencyMs: number;
+};
+/**
+ * Log a usage entry as a JSON line.
+ */
+declare function logUsage(entry: UsageEntry): Promise<void>;
+
+/**
+ * @blockrun/openclaw-provider
+ *
+ * OpenClaw plugin that adds BlockRun as an LLM provider with 30+ AI models.
+ * Payments are handled automatically via x402 USDC micropayments on Base.
+ * Smart routing picks the cheapest capable model for each request.
+ *
+ * Usage:
+ *   # Install the plugin
+ *   openclaw plugin install @blockrun/openclaw-provider
+ *
+ *   # Set wallet key
+ *   export BLOCKRUN_WALLET_KEY=0x...
+ *
+ *   # Or configure via wizard
+ *   openclaw provider add blockrun
+ *
+ *   # Use smart routing (auto-picks cheapest model)
+ *   openclaw config set model blockrun/auto
+ *
+ *   # Or use any specific BlockRun model
+ *   openclaw config set model openai/gpt-5.2
+ */
+
+declare const plugin: OpenClawPluginDefinition;
+
+export { BLOCKRUN_MODELS, DEFAULT_ROUTING_CONFIG, OPENCLAW_MODELS, type RoutingConfig, type RoutingDecision, type Tier, type UsageEntry, blockrunProvider, buildProviderModels, plugin as default, logUsage, route, startProxy };