@spectyra/sdk 0.1.0

package/README.md

@@ -0,0 +1,244 @@
+# Spectyra SDK
+
+**SDK-first agent runtime control: routing, budgets, tool gating, telemetry**
+
+Spectyra SDK provides agent runtime control for Claude Agent SDK and other agent frameworks. Control model selection, budgets, tool permissions, and telemetry—all without requiring a proxy.
+
+## Installation
+
+```bash
+npm install @spectyra/sdk
+# or
+pnpm add @spectyra/sdk
+# or
+yarn add @spectyra/sdk
+```
+
+## Two Integration Styles
+
+### A) Local SDK Mode (Default)
+
+**No proxy required.** SDK makes local decisions about agent options.
+
+```typescript
+import { createSpectyra } from '@spectyra/sdk';
+
+// Local mode - works offline, no API calls
+const spectyra = createSpectyra({ mode: "local" });
+
+// One line integration with Claude Agent SDK
+const options = spectyra.agentOptions(ctx, prompt);
+const result = await agent.query({ prompt, options });
+```
+
+### B) API Control Plane Mode (Enterprise)
+
+SDK calls Spectyra API to fetch agent options and stream events for telemetry.
+
+```typescript
+import { createSpectyra } from '@spectyra/sdk';
+
+const spectyra = createSpectyra({
+  mode: "api",
+  endpoint: "https://spectyra.up.railway.app/v1",
+  apiKey: process.env.SPECTYRA_API_KEY,
+});
+
+// Fetch options from remote API
+const response = await spectyra.agentOptionsRemote(ctx, promptMeta);
+const result = await agent.query({ prompt, options: response.options });
+
+// Stream events for telemetry
+for await (const event of agentStream) {
+  await spectyra.sendAgentEvent(ctx, event);
+}
+```
+
+## Quick Start: Local Mode
+
+```typescript
+import { createSpectyra } from '@spectyra/sdk';
+import { Agent } from '@anthropic-ai/sdk/agent';
+
+// Create Spectyra instance (local mode - default)
+const spectyra = createSpectyra({ mode: "local" });
+
+// Create context for this agent run
+const ctx = {
+  runId: crypto.randomUUID(),
+  budgetUsd: 2.5,
+  tags: { project: "my-app" },
+};
+
+// Get agent options (synchronous, local decision)
+const prompt = "Fix the bug in src/utils.ts";
+const options = spectyra.agentOptions(ctx, prompt);
+
+// Use with Claude Agent SDK
+const agent = new Agent({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  ...options, // Model, budget, tools, permissions
+});
+
+const result = await agent.query({ prompt });
+```
+
+## Quick Start: API Mode
+
+```typescript
+import { createSpectyra } from '@spectyra/sdk';
+
+const spectyra = createSpectyra({
+  mode: "api",
+  endpoint: "https://spectyra.up.railway.app/v1",
+  apiKey: process.env.SPECTYRA_API_KEY,
+});
+
+const ctx = {
+  runId: crypto.randomUUID(),
+  budgetUsd: 5.0,
+};
+
+// Fetch options from remote API
+const promptMeta = {
+  promptChars: prompt.length,
+  path: "code",
+  repoId: "my-repo",
+  language: "typescript",
+};
+
+const response = await spectyra.agentOptionsRemote(ctx, promptMeta);
+// response.run_id is set automatically
+
+// Use options with agent
+const agent = new Agent({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  ...response.options,
+});
+
+// Stream events for telemetry
+const stream = agent.queryStream({ prompt });
+await spectyra.observeAgentStream(ctx, stream);
+```
+
+## API Reference
+
+### `createSpectyra(config?: SpectyraConfig)`
+
+Create a Spectyra SDK instance.
+
+**Config:**
+- `mode?: "local" | "api"` - Default: `"local"`
+- `endpoint?: string` - Required for API mode
+- `apiKey?: string` - Required for API mode
+- `defaults?: { budgetUsd?: number; models?: { small?, medium?, large? } }`
+
+**Returns:** `SpectyraInstance`
+
+### `agentOptions(ctx: SpectyraCtx, prompt: string | PromptMeta): ClaudeAgentOptions`
+
+Get agent options locally (synchronous, offline).
+
+**Context:**
+- `runId?: string` - Run identifier
+- `budgetUsd?: number` - Budget for this run
+- `tags?: Record<string, string>` - Tags for analytics
+
+**Returns:** Claude Agent SDK-compatible options
+
+### `agentOptionsRemote(ctx: SpectyraCtx, promptMeta: PromptMeta): Promise<AgentOptionsResponse>`
+
+Fetch agent options from remote API (asynchronous).
+
+**PromptMeta:**
+- `promptChars: number` - Prompt character count
+- `path?: "code" | "talk"` - Path type
+- `repoId?: string` - Repository identifier
+- `language?: string` - Programming language
+- `filesChanged?: number` - Number of files changed
+
+**Returns:** Options with `run_id` and `reasons`
+
+### `sendAgentEvent(ctx: SpectyraCtx, event: any): Promise<void>`
+
+Send agent event for telemetry (best-effort, non-blocking).
+
+### `observeAgentStream(ctx: SpectyraCtx, stream: AsyncIterable<any>): Promise<void>`
+
+Observe agent stream and forward events automatically.
+
+## Agent Options
+
+The SDK returns Claude Agent SDK-compatible options:
+
+```typescript
+interface ClaudeAgentOptions {
+  model?: string;                    // e.g., "claude-3-5-sonnet-latest"
+  maxBudgetUsd?: number;             // Budget limit
+  allowedTools?: string[];           // e.g., ["Read", "Edit", "Bash"]
+  permissionMode?: "acceptEdits";    // Permission mode
+  canUseTool?: (tool, input) => boolean; // Tool gate function
+}
+```
+
+## Local Decision Logic
+
+In local mode, the SDK uses simple heuristics:
+
+- **Prompt length < 6k chars** → Small tier → `claude-3-5-haiku-latest`
+- **Prompt length < 20k chars** → Medium tier → `claude-3-5-sonnet-latest`
+- **Prompt length ≥ 20k chars** → Large tier → `claude-3-7-sonnet-latest`
+
+Default budget: $2.5 per run  
+Default tools: `["Read", "Edit", "Bash", "Glob"]`  
+Default permissions: `"acceptEdits"`
+
+## Tool Gating
+
+The SDK includes a default `canUseTool` gate that:
+- ✅ Allows: Read, Edit, Bash (safe commands), Glob
+- ❌ Denies: Bash commands containing `curl`, `wget`, `ssh`, `scp`, `nc`, `telnet`
+
+You can override this by providing your own `canUseTool` function in the options.
+
+## Remote Chat Optimization (Optional)
+
+For chat optimization (not agentic), use the legacy client:
+
+```typescript
+import { SpectyraClient } from '@spectyra/sdk';
+
+const client = new SpectyraClient({
+  apiUrl: 'https://spectyra.up.railway.app/v1',
+  spectyraKey: process.env.SPECTYRA_API_KEY,
+  provider: 'openai',
+  providerKey: process.env.OPENAI_API_KEY, // BYOK
+});
+
+const response = await client.chat({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Hello' }],
+  path: 'talk',
+  optimization_level: 3,
+});
+```
+
+**Note:** `SpectyraClient` is deprecated. For agentic use cases, use `createSpectyra()`.
+
+## Examples
+
+See `examples/` directory:
+- `claude-agent-local.ts` - Local mode with Claude Agent SDK
+- `claude-agent-remote.ts` - API mode with telemetry
+- `chat-remote.ts` - Chat optimization (legacy)
+
+## BYOK (Bring Your Own Key)
+
+- Provider API keys are **never stored** server-side
+- Keys are only used for the duration of the request
+- You maintain full control over provider billing
+- Agent options/events endpoints don't require provider keys
+
+## License
+
+MIT

package/dist/adapters/claudeAgent.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Claude Agent SDK Adapter
+ *
+ * Converts Spectyra decisions to Claude Agent SDK-compatible options
+ */
+import type { AgentDecision, ClaudeAgentOptions } from "../types.js";
+/**
+ * Convert agent decision to Claude Agent SDK options
+ */
+export declare function toClaudeAgentOptions(decision: AgentDecision): ClaudeAgentOptions;

package/dist/adapters/claudeAgent.js

@@ -0,0 +1,29 @@
+/**
+ * Claude Agent SDK Adapter
+ *
+ * Converts Spectyra decisions to Claude Agent SDK-compatible options
+ */
+/**
+ * Convert agent decision to Claude Agent SDK options
+ */
+export function toClaudeAgentOptions(decision) {
+    const options = {
+        ...decision.options,
+    };
+    // Add default canUseTool gate if not provided
+    if (!options.canUseTool) {
+        options.canUseTool = (toolName, toolInput) => {
+            // Deny potentially dangerous Bash commands
+            if (toolName === "Bash") {
+                const command = typeof toolInput === "string" ? toolInput : toolInput?.command || "";
+                const dangerous = ["curl", "wget", "ssh", "scp", "nc", "telnet"];
+                const hasDangerous = dangerous.some(cmd => command.toLowerCase().includes(cmd));
+                if (hasDangerous) {
+                    return false;
+                }
+            }
+            return true;
+        };
+    }
+    return options;
+}

package/dist/createSpectyra.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Create Spectyra SDK Instance
+ *
+ * Main entry point for SDK-first agentic integration
+ */
+import type { SpectyraConfig, SpectyraCtx, PromptMeta, ClaudeAgentOptions, AgentOptionsResponse, ChatOptions, ChatResponse } from "./types.js";
+export interface SpectyraInstance {
+    /**
+     * Get agent options locally (SDK mode - default)
+     * Synchronous, works offline, no API calls
+     */
+    agentOptions(ctx: SpectyraCtx, prompt: string | PromptMeta): ClaudeAgentOptions;
+    /**
+     * Get agent options from remote API (API mode)
+     * Asynchronous, requires endpoint and apiKey
+     */
+    agentOptionsRemote(ctx: SpectyraCtx, promptMeta: PromptMeta): Promise<AgentOptionsResponse>;
+    /**
+     * Send agent event to remote API
+     */
+    sendAgentEvent(ctx: SpectyraCtx, event: any): Promise<void>;
+    /**
+     * Observe agent stream and forward events
+     */
+    observeAgentStream(ctx: SpectyraCtx, stream: AsyncIterable<any>): Promise<void>;
+    /**
+     * Chat optimization (remote API mode)
+     * Optional wrapper for /v1/chat endpoint
+     */
+    chatRemote?(options: ChatOptions): Promise<ChatResponse>;
+}
+/**
+ * Create a Spectyra SDK instance
+ *
+ * @example
+ * ```ts
+ * // Local mode (default, no API required)
+ * const spectyra = createSpectyra({ mode: "local" });
+ * const options = spectyra.agentOptions(ctx, prompt);
+ *
+ * // API mode (enterprise control plane)
+ * const spectyra = createSpectyra({
+ *   mode: "api",
+ *   endpoint: "https://spectyra.up.railway.app/v1",
+ *   apiKey: process.env.SPECTYRA_API_KEY,
+ * });
+ * const response = await spectyra.agentOptionsRemote(ctx, promptMeta);
+ * ```
+ */
+export declare function createSpectyra(config?: SpectyraConfig): SpectyraInstance;

package/dist/createSpectyra.js

@@ -0,0 +1,103 @@
+/**
+ * Create Spectyra SDK Instance
+ *
+ * Main entry point for SDK-first agentic integration
+ */
+import { decideAgent } from "./local/decideAgent.js";
+import { toClaudeAgentOptions } from "./adapters/claudeAgent.js";
+import { fetchAgentOptions, sendAgentEvent } from "./remote/agentRemote.js";
+/**
+ * Create a Spectyra SDK instance
+ *
+ * @example
+ * ```ts
+ * // Local mode (default, no API required)
+ * const spectyra = createSpectyra({ mode: "local" });
+ * const options = spectyra.agentOptions(ctx, prompt);
+ *
+ * // API mode (enterprise control plane)
+ * const spectyra = createSpectyra({
+ *   mode: "api",
+ *   endpoint: "https://spectyra.up.railway.app/v1",
+ *   apiKey: process.env.SPECTYRA_API_KEY,
+ * });
+ * const response = await spectyra.agentOptionsRemote(ctx, promptMeta);
+ * ```
+ */
+export function createSpectyra(config = {}) {
+    const mode = config.mode || "local";
+    const endpoint = config.endpoint;
+    const apiKey = config.apiKey;
+    // Validate API mode requirements
+    if (mode === "api") {
+        if (!endpoint) {
+            throw new Error("endpoint is required for API mode");
+        }
+        if (!apiKey) {
+            throw new Error("apiKey is required for API mode");
+        }
+    }
+    return {
+        /**
+         * Local agent options (synchronous, offline)
+         */
+        agentOptions(ctx, prompt) {
+            const decision = decideAgent({ config, ctx, prompt });
+            return toClaudeAgentOptions(decision);
+        },
+        /**
+         * Remote agent options (asynchronous, requires API)
+         */
+        async agentOptionsRemote(ctx, promptMeta) {
+            if (mode !== "api" || !endpoint || !apiKey) {
+                throw new Error("agentOptionsRemote requires API mode with endpoint and apiKey");
+            }
+            const response = await fetchAgentOptions(endpoint, apiKey, ctx, promptMeta);
+            // Update ctx with run_id if returned
+            if (response.run_id && !ctx.runId) {
+                ctx.runId = response.run_id;
+            }
+            return response;
+        },
+        /**
+         * Send agent event
+         */
+        async sendAgentEvent(ctx, event) {
+            if (mode !== "api" || !endpoint || !apiKey) {
+                // In local mode, events are no-ops (best effort)
+                return;
+            }
+            try {
+                await sendAgentEvent(endpoint, apiKey, ctx, event);
+            }
+            catch (error) {
+                // Best-effort: don't throw, just log if possible
+                console.warn("Failed to send agent event:", error);
+            }
+        },
+        /**
+         * Observe agent stream and forward events
+         */
+        async observeAgentStream(ctx, stream) {
+            try {
+                for await (const event of stream) {
+                    await this.sendAgentEvent(ctx, event);
+                }
+            }
+            catch (error) {
+                // Best-effort: don't throw
+                console.warn("Error observing agent stream:", error);
+            }
+        },
+        /**
+         * Chat remote (optional, for backwards compatibility)
+         */
+        chatRemote: mode === "api" && endpoint && apiKey
+            ? async (options) => {
+                // This requires provider and providerKey which aren't in config
+                // So this is only available if user provides them separately
+                throw new Error("chatRemote requires provider and providerKey. Use legacy SpectyraClient for chat optimization.");
+            }
+            : undefined,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Spectyra SDK
+ *
+ * SDK-first agent runtime control: routing, budgets, tool gating, telemetry
+ *
+ * @example
+ * ```ts
+ * // Local mode (default, no API required)
+ * import { createSpectyra } from '@spectyra/sdk';
+ *
+ * const spectyra = createSpectyra({ mode: "local" });
+ *
+ * // Use with Claude Agent SDK
+ * const options = spectyra.agentOptions(ctx, prompt);
+ * const result = await agent.query({ prompt, options });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // API mode (enterprise control plane)
+ * const spectyra = createSpectyra({
+ *   mode: "api",
+ *   endpoint: "https://spectyra.up.railway.app/v1",
+ *   apiKey: process.env.SPECTYRA_API_KEY,
+ * });
+ *
+ * const response = await spectyra.agentOptionsRemote(ctx, promptMeta);
+ * ```
+ */
+export { createSpectyra } from "./createSpectyra.js";
+export type { SpectyraConfig, SpectyraMode, SpectyraCtx, PromptMeta, ClaudeAgentOptions, AgentDecision, AgentOptionsRequest, AgentOptionsResponse, AgentEventRequest, AgentEventResponse, } from "./types.js";
+export { SpectyraClient } from "./legacy/SpectyraClient.js";
+export type { SpectyraClientConfig, ChatOptions, ChatResponse, ChatMessage, Usage, Path, Mode, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * Spectyra SDK
+ *
+ * SDK-first agent runtime control: routing, budgets, tool gating, telemetry
+ *
+ * @example
+ * ```ts
+ * // Local mode (default, no API required)
+ * import { createSpectyra } from '@spectyra/sdk';
+ *
+ * const spectyra = createSpectyra({ mode: "local" });
+ *
+ * // Use with Claude Agent SDK
+ * const options = spectyra.agentOptions(ctx, prompt);
+ * const result = await agent.query({ prompt, options });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // API mode (enterprise control plane)
+ * const spectyra = createSpectyra({
+ *   mode: "api",
+ *   endpoint: "https://spectyra.up.railway.app/v1",
+ *   apiKey: process.env.SPECTYRA_API_KEY,
+ * });
+ *
+ * const response = await spectyra.agentOptionsRemote(ctx, promptMeta);
+ * ```
+ */
+// New SDK-first API
+export { createSpectyra } from "./createSpectyra.js";
+// Legacy API (deprecated but still supported)
+export { SpectyraClient } from "./legacy/SpectyraClient.js";

package/dist/legacy/SpectyraClient.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Legacy Spectyra Client
+ *
+ * @deprecated Use createSpectyra({mode:"api"}).chatRemote(...) or createSpectyra({mode:"local"})
+ *
+ * This class is maintained for backwards compatibility.
+ * It now uses the new remote chat client internally.
+ */
+import type { SpectyraClientConfig, ChatOptions, ChatResponse } from "../types.js";
+/**
+ * @deprecated Use createSpectyra({mode:"api"}) instead
+ *
+ * Legacy client for chat optimization via API.
+ * For agentic use cases, use createSpectyra() with agentOptions().
+ */
+export declare class SpectyraClient {
+    private config;
+    constructor(config: SpectyraClientConfig);
+    /**
+     * Send a chat request through Spectyra optimization.
+     *
+     * @deprecated Use createSpectyra({mode:"api"}).chatRemote() instead
+     *
+     * @param options Chat options
+     * @returns Optimized response with savings metrics
+     */
+    chat(options: ChatOptions): Promise<ChatResponse>;
+    /**
+     * Estimate savings for a conversation without making real LLM calls.
+     *
+     * @deprecated Use createSpectyra({mode:"api"}).chatRemote() with dry_run option
+     *
+     * @param options Chat options (dry_run will be set to true)
+     * @returns Estimated savings
+     */
+    estimateSavings(options: Omit<ChatOptions, "dry_run">): Promise<ChatResponse>;
+    /**
+     * Get the current configuration (without sensitive keys)
+     */
+    getConfig(): Omit<SpectyraClientConfig, "spectyraKey" | "providerKey">;
+}

package/dist/legacy/SpectyraClient.js

@@ -0,0 +1,85 @@
+/**
+ * Legacy Spectyra Client
+ *
+ * @deprecated Use createSpectyra({mode:"api"}).chatRemote(...) or createSpectyra({mode:"local"})
+ *
+ * This class is maintained for backwards compatibility.
+ * It now uses the new remote chat client internally.
+ */
+import { chatRemote } from "../remote/chatRemote.js";
+/**
+ * @deprecated Use createSpectyra({mode:"api"}) instead
+ *
+ * Legacy client for chat optimization via API.
+ * For agentic use cases, use createSpectyra() with agentOptions().
+ */
+export class SpectyraClient {
+    config;
+    constructor(config) {
+        this.config = config;
+        if (!config.apiUrl) {
+            throw new Error("apiUrl is required");
+        }
+        if (!config.spectyraKey) {
+            throw new Error("spectyraKey is required");
+        }
+        if (!config.provider) {
+            throw new Error("provider is required");
+        }
+        if (!config.providerKey) {
+            throw new Error("providerKey is required (BYOK)");
+        }
+    }
+    /**
+     * Send a chat request through Spectyra optimization.
+     *
+     * @deprecated Use createSpectyra({mode:"api"}).chatRemote() instead
+     *
+     * @param options Chat options
+     * @returns Optimized response with savings metrics
+     */
+    async chat(options) {
+        const { model, messages, path, optimization_level = 2, conversation_id, dry_run = false, } = options;
+        // Validate messages
+        if (!messages || messages.length === 0) {
+            throw new Error("messages array cannot be empty");
+        }
+        // Use new remote chat client
+        return chatRemote({
+            endpoint: this.config.apiUrl,
+            apiKey: this.config.spectyraKey,
+            provider: this.config.provider,
+            providerKey: this.config.providerKey,
+        }, {
+            model,
+            messages,
+            path,
+            optimization_level,
+            conversation_id,
+            dry_run,
+        });
+    }
+    /**
+     * Estimate savings for a conversation without making real LLM calls.
+     *
+     * @deprecated Use createSpectyra({mode:"api"}).chatRemote() with dry_run option
+     *
+     * @param options Chat options (dry_run will be set to true)
+     * @returns Estimated savings
+     */
+    async estimateSavings(options) {
+        return this.chat({
+            ...options,
+            dry_run: true,
+        });
+    }
+    /**
+     * Get the current configuration (without sensitive keys)
+     */
+    getConfig() {
+        return {
+            apiUrl: this.config.apiUrl,
+            provider: this.config.provider,
+        };
+    }
+}

package/dist/local/decideAgent.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Local Agent Decision Engine
+ *
+ * Makes local decisions about agent options without requiring API calls.
+ * This is the default "SDK mode" - works offline.
+ */
+import type { SpectyraConfig, SpectyraCtx, PromptMeta, AgentDecision } from "../types.js";
+export interface DecideAgentInput {
+    config: SpectyraConfig;
+    ctx: SpectyraCtx;
+    prompt: string | PromptMeta;
+}
+/**
+ * Determine agent options locally based on prompt characteristics
+ */
+export declare function decideAgent(input: DecideAgentInput): AgentDecision;

package/dist/local/decideAgent.js

@@ -0,0 +1,70 @@
+/**
+ * Local Agent Decision Engine
+ *
+ * Makes local decisions about agent options without requiring API calls.
+ * This is the default "SDK mode" - works offline.
+ */
+/**
+ * Determine agent options locally based on prompt characteristics
+ */
+export function decideAgent(input) {
+    const { config, ctx, prompt } = input;
+    const reasons = [];
+    // Determine prompt length
+    const promptLength = typeof prompt === "string" ? prompt.length : prompt.promptChars;
+    const path = typeof prompt === "string" ? undefined : prompt.path;
+    // Determine tier by prompt length
+    let tier;
+    if (promptLength < 6000) {
+        tier = "small";
+        reasons.push(`Prompt length ${promptLength} chars → small tier`);
+    }
+    else if (promptLength < 20000) {
+        tier = "medium";
+        reasons.push(`Prompt length ${promptLength} chars → medium tier`);
+    }
+    else {
+        tier = "large";
+        reasons.push(`Prompt length ${promptLength} chars → large tier`);
+    }
+    // Choose model from config or defaults
+    const modelDefaults = config.defaults?.models || {};
+    let model;
+    if (tier === "small") {
+        model = modelDefaults.small || "claude-3-5-haiku-latest";
+        reasons.push(`Small tier → ${model}`);
+    }
+    else if (tier === "medium") {
+        model = modelDefaults.medium || "claude-3-5-sonnet-latest";
+        reasons.push(`Medium tier → ${model}`);
+    }
+    else {
+        model = modelDefaults.large || "claude-3-7-sonnet-latest";
+        reasons.push(`Large tier → ${model}`);
+    }
+    // Set budget
+    const maxBudgetUsd = ctx.budgetUsd || config.defaults?.budgetUsd || 2.5;
+    reasons.push(`Budget: $${maxBudgetUsd} (from ctx or defaults)`);
+    // Default allowed tools (configurable)
+    const allowedTools = ["Read", "Edit", "Bash", "Glob"];
+    reasons.push(`Allowed tools: ${allowedTools.join(", ")}`);
+    // Permission mode
+    const permissionMode = "acceptEdits";
+    reasons.push(`Permission mode: ${permissionMode}`);
+    // Build options
+    const options = {
+        model,
+        maxBudgetUsd,
+        allowedTools,
+        permissionMode,
+        // canUseTool will be set by adapter if needed
+    };
+    // Add path-specific context if available
+    if (path) {
+        reasons.push(`Path: ${path}`);
+    }
+    return {
+        options,
+        reasons,
+    };
+}

package/dist/remote/agentRemote.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Remote Agent Client
+ *
+ * Handles agent-related API calls (options, events)
+ */
+import type { SpectyraCtx, PromptMeta, AgentOptionsResponse, AgentEventResponse } from "../types.js";
+/**
+ * Fetch agent options from remote API
+ */
+export declare function fetchAgentOptions(endpoint: string, apiKey: string, ctx: SpectyraCtx, promptMeta: PromptMeta): Promise<AgentOptionsResponse>;
+/**
+ * Send agent event to remote API
+ */
+export declare function sendAgentEvent(endpoint: string, apiKey: string, ctx: SpectyraCtx, event: any): Promise<AgentEventResponse>;

package/dist/remote/agentRemote.js

@@ -0,0 +1,47 @@
+/**
+ * Remote Agent Client
+ *
+ * Handles agent-related API calls (options, events)
+ */
+import { postJson } from "./http.js";
+/**
+ * Fetch agent options from remote API
+ */
+export async function fetchAgentOptions(endpoint, apiKey, ctx, promptMeta) {
+    const url = `${endpoint}/agent/options`;
+    const request = {
+        run_id: ctx.runId,
+        prompt_meta: promptMeta,
+        preferences: {
+            budgetUsd: ctx.budgetUsd,
+            // allowTools can be added if needed
+        },
+    };
+    return postJson(url, apiKey, request);
+}
+/**
+ * Send agent event to remote API
+ */
+export async function sendAgentEvent(endpoint, apiKey, ctx, event) {
+    if (!ctx.runId) {
+        throw new Error("runId is required to send agent events");
+    }
+    const url = `${endpoint}/agent/events`;
+    // Truncate large events (max 256KB JSON)
+    let eventToSend = event;
+    const eventJson = JSON.stringify(event);
+    if (eventJson.length > 256 * 1024) {
+        // Store only type + summary for large events
+        eventToSend = {
+            type: event.type || "unknown",
+            summary: "Event truncated (exceeds 256KB)",
+            originalSize: eventJson.length,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    const request = {
+        run_id: ctx.runId,
+        event: eventToSend,
+    };
+    return postJson(url, apiKey, request);
+}

package/dist/remote/chatRemote.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Remote Chat Client
+ *
+ * Handles chat optimization API calls (backwards compatibility)
+ */
+import type { ChatOptions, ChatResponse } from "../types.js";
+export interface ChatRemoteConfig {
+    endpoint: string;
+    apiKey: string;
+    provider: string;
+    providerKey: string;
+}
+/**
+ * Send chat request to Spectyra API for optimization
+ */
+export declare function chatRemote(config: ChatRemoteConfig, options: ChatOptions): Promise<ChatResponse>;

package/dist/remote/chatRemote.js

@@ -0,0 +1,36 @@
+/**
+ * Remote Chat Client
+ *
+ * Handles chat optimization API calls (backwards compatibility)
+ */
+/**
+ * Send chat request to Spectyra API for optimization
+ */
+export async function chatRemote(config, options) {
+    const url = `${config.endpoint}/chat`;
+    const body = {
+        path: options.path,
+        provider: config.provider,
+        model: options.model,
+        messages: options.messages,
+        mode: "optimized",
+        optimization_level: options.optimization_level ?? 2,
+        conversation_id: options.conversation_id,
+        dry_run: options.dry_run ?? false,
+    };
+    // Make request with both Spectyra key and provider key (BYOK)
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-SPECTYRA-API-KEY": config.apiKey,
+            "X-PROVIDER-KEY": config.providerKey, // BYOK - never stored server-side
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: "Unknown error" }));
+        throw new Error(`Spectyra API error: ${error.error || response.statusText}`);
+    }
+    return response.json();
+}

package/dist/remote/http.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Remote HTTP Client
+ *
+ * Handles HTTP requests to Spectyra API with proper error handling
+ */
+export interface ApiError {
+    error: string;
+    details?: string;
+}
+/**
+ * Make a POST request to Spectyra API
+ */
+export declare function postJson<T>(url: string, apiKey: string, body: any): Promise<T>;

package/dist/remote/http.js

@@ -0,0 +1,37 @@
+/**
+ * Remote HTTP Client
+ *
+ * Handles HTTP requests to Spectyra API with proper error handling
+ */
+/**
+ * Make a POST request to Spectyra API
+ */
+export async function postJson(url, apiKey, body) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-SPECTYRA-API-KEY": apiKey,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        let errorMessage = `API error: ${response.statusText}`;
+        try {
+            const errorData = await response.json();
+            errorMessage = errorData.error || errorMessage;
+            if (errorData.details) {
+                errorMessage += ` - ${errorData.details}`;
+            }
+        }
+        catch {
+            // If JSON parsing fails, use status text
+            const text = await response.text();
+            if (text) {
+                errorMessage = text.substring(0, 200);
+            }
+        }
+        throw new Error(errorMessage);
+    }
+    return response.json();
+}

package/dist/types.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Spectyra SDK Types
+ *
+ * Core types for SDK-first agentic integration
+ */
+export type SpectyraMode = "local" | "api";
+export interface SpectyraConfig {
+    /**
+     * SDK mode: "local" (default, no proxy) or "api" (remote control plane)
+     */
+    mode?: SpectyraMode;
+    /**
+     * Spectyra API endpoint (required for "api" mode, optional for "local")
+     * Example: "https://spectyra.up.railway.app/v1"
+     */
+    endpoint?: string;
+    /**
+     * Spectyra API key (required for "api" mode, optional for "local")
+     */
+    apiKey?: string;
+    /**
+     * Default settings
+     */
+    defaults?: {
+        /**
+         * Default budget in USD per agent run
+         */
+        budgetUsd?: number;
+        /**
+         * Model preferences by tier
+         */
+        models?: {
+            small?: string;
+            medium?: string;
+            large?: string;
+        };
+    };
+}
+export interface SpectyraCtx {
+    /**
+     * Organization ID (optional; in API mode server derives from API key)
+     */
+    orgId?: string;
+    /**
+     * Project ID (optional)
+     */
+    projectId?: string;
+    /**
+     * Run ID for tracking this agent session
+     */
+    runId?: string;
+    /**
+     * Budget in USD for this run
+     */
+    budgetUsd?: number;
+    /**
+     * Tags for filtering/analytics
+     */
+    tags?: Record<string, string>;
+}
+export interface PromptMeta {
+    /**
+     * Prompt character count (to avoid sending full prompt by default)
+     */
+    promptChars: number;
+    /**
+     * Path: "code" for coding, "talk" for chat/Q&A
+     */
+    path?: "code" | "talk";
+    /**
+     * Repository identifier (optional)
+     */
+    repoId?: string;
+    /**
+     * Programming language (optional)
+     */
+    language?: string;
+    /**
+     * Number of files changed (optional)
+     */
+    filesChanged?: number;
+    /**
+     * Test command (optional)
+     */
+    testCommand?: string;
+}
+export interface ClaudeAgentOptions {
+    /**
+     * Model name (e.g., "claude-3-5-sonnet-latest")
+     */
+    model?: string;
+    /**
+     * Maximum budget in USD for this run
+     */
+    maxBudgetUsd?: number;
+    /**
+     * Working directory
+     */
+    cwd?: string;
+    /**
+     * Allowed tool names
+     */
+    allowedTools?: string[];
+    /**
+     * Permission mode
+     */
+    permissionMode?: "default" | "acceptEdits" | "bypassPermissions";
+    /**
+     * Tool usage gate function
+     */
+    canUseTool?: (toolName: string, toolInput: any) => boolean | Promise<boolean>;
+}
+export interface AgentDecision {
+    /**
+     * Generated agent options
+     */
+    options: ClaudeAgentOptions;
+    /**
+     * Decision reasons (for debugging)
+     */
+    reasons: string[];
+}
+export interface AgentOptionsRequest {
+    run_id?: string;
+    prompt_meta: PromptMeta;
+    preferences?: {
+        budgetUsd?: number;
+        allowTools?: string[];
+    };
+}
+export interface AgentOptionsResponse {
+    run_id: string;
+    options: ClaudeAgentOptions;
+    reasons: string[];
+}
+export interface AgentEventRequest {
+    run_id: string;
+    event: any;
+}
+export interface AgentEventResponse {
+    ok: boolean;
+}
+export type Path = "talk" | "code";
+export type Mode = "baseline" | "optimized";
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export interface Usage {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    estimated?: boolean;
+}
+export interface ChatResponse {
+    id: string;
+    created_at: string;
+    mode: Mode;
+    path: Path;
+    optimization_level: number;
+    provider: string;
+    model: string;
+    response_text: string;
+    usage: Usage;
+    cost_usd: number;
+    savings?: {
+        savings_type: "verified" | "estimated" | "shadow_verified";
+        tokens_saved: number;
+        pct_saved: number;
+        cost_saved_usd: number;
+        confidence_band?: "high" | "medium" | "low";
+    };
+    quality?: {
+        pass: boolean;
+        failures: string[];
+    };
+}
+export interface SpectyraClientConfig {
+    /**
+     * Spectyra API base URL (e.g., "https://spectyra.up.railway.app/v1")
+     */
+    apiUrl: string;
+    /**
+     * Your Spectyra API key
+     */
+    spectyraKey: string;
+    /**
+     * LLM provider (e.g., "openai", "anthropic", "gemini", "grok")
+     */
+    provider: string;
+    /**
+     * Your provider API key (BYOK - Bring Your Own Key)
+     * This is sent to Spectyra but never stored server-side.
+     */
+    providerKey: string;
+}
+export interface ChatOptions {
+    /**
+     * Model name (e.g., "gpt-4o-mini", "claude-3-5-sonnet")
+     */
+    model: string;
+    /**
+     * Conversation messages
+     */
+    messages: ChatMessage[];
+    /**
+     * Path: "talk" for chat/Q&A, "code" for coding workflows
+     */
+    path: Path;
+    /**
+     * Optimization level (0-4)
+     * 0 = Minimal, 1 = Conservative, 2 = Balanced, 3 = Aggressive, 4 = Maximum
+     */
+    optimization_level?: number;
+    /**
+     * Conversation ID for state tracking (optional)
+     */
+    conversation_id?: string;
+    /**
+     * Dry-run mode: estimate savings without making real LLM calls
+     */
+    dry_run?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Spectyra SDK Types
+ *
+ * Core types for SDK-first agentic integration
+ */
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@spectyra/sdk",
+  "version": "0.1.0",
+  "description": "Spectyra SDK for real-time LLM optimization",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "llm",
+    "optimization",
+    "token-reduction",
+    "spectyra",
+    "claude",
+    "agent",
+    "sdk"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spectyra/spectyra.git",
+    "directory": "packages/sdk"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "~5.4.0"
+  }
+}