@jellyos/agent 0.1.3 → 0.1.5

package/dist/mcp/server.d.ts

@@ -0,0 +1,31 @@
+/**
+ * MCPServer — Model Context Protocol server over stdio. (#28)
+ *
+ * Exposes all JellyOS registered tools as MCP tools so they can be used
+ * by Claude Desktop, Cursor, Continue, and any MCP-compatible client.
+ *
+ * Protocol: JSON-RPC 2.0 over stdin/stdout (MCP stdio transport).
+ *
+ * Usage:
+ *   jellyos-mcp                        # exposes built-in tools
+ *   jellyos-mcp --extension ./my.ts    # includes extension tools
+ *
+ * Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
+ *   {
+ *     "mcpServers": {
+ *       "jellyos": {
+ *         "command": "jellyos-mcp",
+ *         "env": { "OPENROUTER_API_KEY": "sk-or-..." }
+ *       }
+ *     }
+ *   }
+ */
+import type { Registry } from "../api/Registry.js";
+export declare class MCPServer {
+    private registry;
+    constructor(registry: Registry);
+    run(): Promise<void>;
+    private respond;
+    private handle;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.js

@@ -0,0 +1,128 @@
+/**
+ * MCPServer — Model Context Protocol server over stdio. (#28)
+ *
+ * Exposes all JellyOS registered tools as MCP tools so they can be used
+ * by Claude Desktop, Cursor, Continue, and any MCP-compatible client.
+ *
+ * Protocol: JSON-RPC 2.0 over stdin/stdout (MCP stdio transport).
+ *
+ * Usage:
+ *   jellyos-mcp                        # exposes built-in tools
+ *   jellyos-mcp --extension ./my.ts    # includes extension tools
+ *
+ * Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
+ *   {
+ *     "mcpServers": {
+ *       "jellyos": {
+ *         "command": "jellyos-mcp",
+ *         "env": { "OPENROUTER_API_KEY": "sk-or-..." }
+ *       }
+ *     }
+ *   }
+ */
+import { createInterface } from "node:readline";
+export class MCPServer {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    async run() {
+        const rl = createInterface({ input: process.stdin, terminal: false });
+        // MCP uses newline-delimited JSON-RPC 2.0
+        rl.on("line", async (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return;
+            let req;
+            try {
+                req = JSON.parse(trimmed);
+            }
+            catch {
+                this.respond({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+                return;
+            }
+            const response = await this.handle(req);
+            this.respond(response);
+        });
+        rl.on("close", () => process.exit(0));
+        // MCP servers send an initialization notification on stderr
+        process.stderr.write("[JellyOS MCP] Server ready\n");
+    }
+    respond(res) {
+        process.stdout.write(JSON.stringify(res) + "\n");
+    }
+    async handle(req) {
+        try {
+            switch (req.method) {
+                case "initialize":
+                    return {
+                        jsonrpc: "2.0", id: req.id,
+                        result: {
+                            protocolVersion: "2024-11-05",
+                            capabilities: { tools: {} },
+                            serverInfo: { name: "jellyos", version: "0.1.5" },
+                        },
+                    };
+                case "notifications/initialized":
+                    // No response needed for notifications
+                    return { jsonrpc: "2.0", id: req.id, result: null };
+                case "tools/list":
+                    return {
+                        jsonrpc: "2.0", id: req.id,
+                        result: {
+                            tools: this.registry.listTools().map(t => ({
+                                name: t.name,
+                                description: t.description,
+                                inputSchema: {
+                                    ...t.parameters,
+                                    type: "object", // MCP requires explicit type
+                                },
+                            })),
+                        },
+                    };
+                case "tools/call": {
+                    const { name, arguments: args } = (req.params ?? {});
+                    if (!name) {
+                        return { jsonrpc: "2.0", id: req.id, error: { code: -32602, message: "Missing tool name" } };
+                    }
+                    const tool = this.registry.getTool(name);
+                    if (!tool) {
+                        return { jsonrpc: "2.0", id: req.id, error: { code: -32601, message: `Tool not found: ${name}` } };
+                    }
+                    try {
+                        const result = await tool.execute("mcp", (args ?? {}));
+                        return {
+                            jsonrpc: "2.0", id: req.id,
+                            result: {
+                                content: result.content.map(c => ({ type: "text", text: c.text })),
+                                isError: false,
+                            },
+                        };
+                    }
+                    catch (e) {
+                        const msg = e instanceof Error ? e.message : String(e);
+                        return {
+                            jsonrpc: "2.0", id: req.id,
+                            result: {
+                                content: [{ type: "text", text: `Tool error: ${msg}` }],
+                                isError: true,
+                            },
+                        };
+                    }
+                }
+                case "ping":
+                    return { jsonrpc: "2.0", id: req.id, result: {} };
+                default:
+                    return {
+                        jsonrpc: "2.0", id: req.id,
+                        error: { code: -32601, message: `Method not found: ${req.method}` },
+                    };
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return { jsonrpc: "2.0", id: req.id, error: { code: -32603, message: `Internal error: ${msg}` } };
+        }
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/models/CostTracker.d.ts

@@ -0,0 +1,66 @@
+/**
+ * CostTracker — tracks per-session and lifetime token usage and cost.
+ *
+ * Uses OpenRouter response headers (x-credit-used) when available,
+ * otherwise estimates from the model registry's pricing data.
+ * Emits budget warnings and provides cost reports via tool/command.
+ */
+import type { ModelRegistry } from "./ModelRegistry.js";
+export interface UsageEntry {
+    model: string;
+    timestamp: number;
+    promptTokens: number;
+    completionTokens: number;
+    /** Estimated cost in nano-dollars (billionths of a dollar) */
+    estimatedCost: number;
+    /** Duration in ms */
+    duration: number;
+}
+export interface SessionUsage {
+    promptTokens: number;
+    completionTokens: number;
+    estimatedCost: number;
+    calls: number;
+    errors: number;
+}
+export interface LifetimeUsage {
+    promptTokens: number;
+    completionTokens: number;
+    estimatedCost: number;
+    calls: number;
+    modelsUsed: Set<string>;
+}
+export declare class CostTracker {
+    private modelReg;
+    private session;
+    private lifetime;
+    private budgetSession;
+    private budgetLifetime;
+    private budgetWarned;
+    constructor(modelReg: ModelRegistry);
+    record(modelId: string, promptTokens: number, completionTokens: number, duration: number): void;
+    recordError(): void;
+    private maybeWarnBudget;
+    getBudgetStatus(): {
+        session: SessionUsage;
+        lifetime: LifetimeUsage;
+        warnings: string[];
+    };
+    /** True if the next call would exceed the session budget. */
+    wouldExceed(estimatedCallCost: number): boolean;
+    private loadLifetime;
+    saveLifetime(): void;
+    private formatNano;
+    statusLine(): string;
+    report(): string;
+    readonly costReportParams: import("@sinclair/typebox").TObject<{}>;
+    costReportTool(): Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        details: Record<string, unknown>;
+    }>;
+    resetSession(): void;
+}
+//# sourceMappingURL=CostTracker.d.ts.map

package/dist/models/CostTracker.js

@@ -0,0 +1,148 @@
+/**
+ * CostTracker — tracks per-session and lifetime token usage and cost.
+ *
+ * Uses OpenRouter response headers (x-credit-used) when available,
+ * otherwise estimates from the model registry's pricing data.
+ * Emits budget warnings and provides cost reports via tool/command.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { Type } from "@sinclair/typebox";
+const JELLY_HOME = process.env.JELLYOS_HOME ?? join(homedir(), ".jelly");
+const COST_FILE = join(JELLY_HOME, "usage.json");
+// ── CostTracker class ─────────────────────────────────────────────────────────
+const DEFAULT_BUDGET_PER_SESSION = 1_000_000_000_000; // $1.00 in nano-dollars
+const DEFAULT_BUDGET_LIFETIME = 25_000_000_000_000; // $25.00
+export class CostTracker {
+    modelReg;
+    session = { promptTokens: 0, completionTokens: 0, estimatedCost: 0, calls: 0, errors: 0 };
+    lifetime = { promptTokens: 0, completionTokens: 0, estimatedCost: 0, calls: 0, modelsUsed: new Set() };
+    budgetSession;
+    budgetLifetime;
+    budgetWarned = false;
+    constructor(modelReg) {
+        this.modelReg = modelReg;
+        this.budgetSession = parseInt(process.env.JELLY_BUDGET_SESSION ?? String(DEFAULT_BUDGET_PER_SESSION));
+        this.budgetLifetime = parseInt(process.env.JELLY_BUDGET_LIFETIME ?? String(DEFAULT_BUDGET_LIFETIME));
+        this.loadLifetime();
+    }
+    // ── Recording ─────────────────────────────────────────────────────────────
+    record(modelId, promptTokens, completionTokens, duration) {
+        const tm = this.modelReg["modelMap"]?.get(modelId);
+        const costPer1K = tm?.costPer1K ?? 50_000; // fallback: 50 nano-dollars/1K (=$0.00005/1K)
+        const estimatedCost = Math.round(costPer1K * (promptTokens + completionTokens) / 1000);
+        const entry = { model: modelId, timestamp: Date.now(), promptTokens, completionTokens, estimatedCost, duration };
+        // Session
+        this.session.promptTokens += promptTokens;
+        this.session.completionTokens += completionTokens;
+        this.session.estimatedCost += estimatedCost;
+        this.session.calls++;
+        // Lifetime
+        this.lifetime.promptTokens += promptTokens;
+        this.lifetime.completionTokens += completionTokens;
+        this.lifetime.estimatedCost += estimatedCost;
+        this.lifetime.calls++;
+        this.lifetime.modelsUsed.add(modelId);
+        this.maybeWarnBudget();
+    }
+    recordError() {
+        this.session.errors++;
+        this.lifetime.calls++;
+    }
+    // ── Budget ────────────────────────────────────────────────────────────────
+    maybeWarnBudget() {
+        if (this.session.estimatedCost > this.budgetSession * 0.8 && !this.budgetWarned) {
+            this.budgetWarned = true;
+            // Budget warning is surfaced via getBudgetStatus() — callers can check
+        }
+    }
+    getBudgetStatus() {
+        const warnings = [];
+        const pctSession = this.session.estimatedCost / this.budgetSession * 100;
+        const pctLifetime = this.lifetime.estimatedCost / this.budgetLifetime * 100;
+        if (pctSession >= 90)
+            warnings.push(`⚠ Session budget at ${pctSession.toFixed(0)}% — near limit`);
+        else if (pctSession >= 75)
+            warnings.push(`⚡ Session budget at ${pctSession.toFixed(0)}%`);
+        if (pctLifetime >= 90)
+            warnings.push(`⚠ Lifetime budget at ${pctLifetime.toFixed(0)}% — near limit`);
+        else if (pctLifetime >= 75)
+            warnings.push(`⚡ Lifetime budget at ${pctLifetime.toFixed(0)}%`);
+        return { session: { ...this.session }, lifetime: { ...this.lifetime, modelsUsed: new Set(this.lifetime.modelsUsed) }, warnings };
+    }
+    /** True if the next call would exceed the session budget. */
+    wouldExceed(estimatedCallCost) {
+        return this.session.estimatedCost + estimatedCallCost > this.budgetSession;
+    }
+    // ── Persistence ────────────────────────────────────────────────────────────
+    loadLifetime() {
+        try {
+            if (!existsSync(COST_FILE))
+                return;
+            const raw = JSON.parse(readFileSync(COST_FILE, "utf-8"));
+            this.lifetime.promptTokens = raw.promptTokens ?? 0;
+            this.lifetime.completionTokens = raw.completionTokens ?? 0;
+            this.lifetime.estimatedCost = raw.estimatedCost ?? 0;
+            this.lifetime.calls = raw.calls ?? 0;
+            this.lifetime.modelsUsed = new Set(raw.modelsUsed ?? []);
+        }
+        catch { /* best effort */ }
+    }
+    saveLifetime() {
+        try {
+            mkdirSync(JELLY_HOME, { recursive: true });
+            writeFileSync(COST_FILE, JSON.stringify({
+                promptTokens: this.lifetime.promptTokens,
+                completionTokens: this.lifetime.completionTokens,
+                estimatedCost: this.lifetime.estimatedCost,
+                calls: this.lifetime.calls,
+                modelsUsed: [...this.lifetime.modelsUsed],
+            }));
+        }
+        catch { /* best effort */ }
+    }
+    // ── Formatting ─────────────────────────────────────────────────────────────
+    formatNano(cost) {
+        return `$${(cost / 1_000_000_000).toFixed(4)}`;
+    }
+    statusLine() {
+        return `${this.formatNano(this.session.estimatedCost)} · ${this.session.calls}calls`;
+    }
+    report() {
+        const s = this.session;
+        return [
+            `Session: ${s.calls} calls · ${s.errors} errors · ${this.formatNano(s.estimatedCost)}`,
+            `  Prompt:      ${s.promptTokens.toLocaleString()} tokens`,
+            `  Completion:  ${s.completionTokens.toLocaleString()} tokens`,
+            `Lifetime: ${this.lifetime.calls} calls · ${this.formatNano(this.lifetime.estimatedCost)}`,
+            `  Models used: ${this.lifetime.modelsUsed.size}`,
+        ].join("\n");
+    }
+    // ── Tool: cost_report ──────────────────────────────────────────────────────
+    costReportParams = Type.Object({});
+    async costReportTool() {
+        const status = this.getBudgetStatus();
+        let text = this.report();
+        if (status.warnings.length > 0) {
+            text += "\n\n" + status.warnings.join("\n");
+        }
+        return {
+            content: [{ type: "text", text }],
+            details: {
+                session_cost_nano: status.session.estimatedCost,
+                lifetime_cost_nano: status.lifetime.estimatedCost,
+                session_calls: status.session.calls,
+                lifetime_calls: status.lifetime.calls,
+                models_used: status.lifetime.modelsUsed.size,
+                warnings: status.warnings,
+            },
+        };
+    }
+    // ── Reset ──────────────────────────────────────────────────────────────────
+    resetSession() {
+        this.session = { promptTokens: 0, completionTokens: 0, estimatedCost: 0, calls: 0, errors: 0 };
+        this.budgetWarned = false;
+    }
+}
+//# sourceMappingURL=CostTracker.js.map

package/dist/models/ModelRegistry.d.ts

@@ -0,0 +1,157 @@
+/**
+ * ModelRegistry — dynamic model discovery, tiering, and routing.
+ *
+ * Queries OpenRouter's /models endpoint at startup to build a local registry
+ * of all available models. Classifies them into tiers (orchestrator / analyst /
+ * worker / free), tracks performance, handles deprecation, and exposes
+ * model selection as both a tool and a REPL command.
+ *
+ * Also supports direct provider routing (Anthropic/OpenAI/Google keys) for
+ * models that can be reached cheaper outside OpenRouter.
+ */
+import type { ModelConfig } from "../runner/ModelClient.js";
+import { type Static } from "@sinclair/typebox";
+export interface OpenRouterModel {
+    id: string;
+    name: string;
+    created: number;
+    description: string;
+    context_length: number;
+    architecture: {
+        modality: string;
+        tokenizer: string;
+        instruct_type: string | null;
+    };
+    pricing: {
+        prompt: string;
+        completion: string;
+        image?: string;
+        request?: string;
+        input_cache_read?: string;
+        input_cache_write?: string;
+    };
+    top_provider: {
+        context_length: number;
+        max_completion_tokens: number | null;
+        is_moderated: boolean;
+    };
+    per_request_limits?: Record<string, string>;
+}
+export type ModelTier = "orchestrator" | "analyst" | "worker" | "free";
+export interface TieredModel {
+    tier: ModelTier;
+    model: OpenRouterModel;
+    /** Nano-dollars per 1K prompt tokens (for cost comparison) */
+    costPer1K: number;
+    /** Whether this model is currently available (not deprecated / rate-limited) */
+    available: boolean;
+    /** Consecutive failures — if >= 3, mark unavailable temporarily */
+    failures: number;
+    /** Timestamp of last failure (ms) */
+    lastFailure: number;
+    /** Average stream latency in ms */
+    avgLatency: number;
+    /** Number of times used */
+    uses: number;
+}
+export interface TieredPool {
+    orchestrator: TieredModel[];
+    analyst: TieredModel[];
+    worker: TieredModel[];
+    free: TieredModel[];
+}
+export declare function classifyModel(model: OpenRouterModel): ModelTier;
+export declare class ModelRegistry {
+    private allModels;
+    private tieredPool;
+    private modelMap;
+    private loaded;
+    private lastFetch;
+    /** Query OpenRouter /models and build the tiered pool. Called once at startup. */
+    initialise(apiKey?: string): Promise<void>;
+    /** Rebuild tier classifications (call after cache load or fetch). */
+    private rebuildTiers;
+    private saveCache;
+    private loadFromCache;
+    /** True if cache is stale and we should re-fetch on next opportunity. */
+    get cacheStale(): boolean;
+    /**
+     * Pick the best available model for a given tier.
+     * Favours lower cost among available models, excluding those with >= 3
+     * consecutive failures (which get a 5-minute cooldown).
+     */
+    pick(tier: ModelTier): OpenRouterModel | null;
+    /**
+     * Per-model and per-tier temperature profiles.
+     * Reasoning/thinking models REQUIRE temperature=1.0 (API enforces).
+     * Code/structured tasks want low temp; creative analysis wants higher.
+     */
+    private getTemperature;
+    /**
+     * Per-tier max token budgets.
+     * Orchestrators get generous budgets; free workers get minimal.
+     */
+    private getTokenBudget;
+    /**
+     * Build a full ModelConfig chain from the tiered pool.
+     * Uses user-configured models from env first, then fills with tiered picks.
+     */
+    buildModelChain(userModels: string[]): ModelConfig[];
+    /** Build a single ModelConfig, preferring direct provider when possible. */
+    buildConfig(modelId: string, maxTokens: number, temperature: number, tier?: ModelTier): ModelConfig | null;
+    recordFailure(modelId: string): void;
+    recordSuccess(modelId: string, latencyMs: number): void;
+    /** Mark a model as permanently deprecated (404, model removed). */
+    markDeprecated(modelId: string): void;
+    getTier(modelId: string): ModelTier;
+    get modelCount(): number;
+    /** Search / filter models by keyword (case-insensitive). */
+    search(query: string, maxResults?: number): TieredModel[];
+    /** Get all models for a tier. */
+    getPool(tier: ModelTier): TieredModel[];
+    /** Human-readable summary of the current pool. */
+    summary(): string;
+    /**
+     * Find the cheapest model meeting minimum requirements.
+     * @param tier       - Required tier (or "any")
+     * @param minContext - Minimum context length
+     * @param maxCost    - Maximum cost in nano-dollars per 1K prompt
+     */
+    findCheapest(tier: ModelTier | "any", minContext?: number, maxCost?: number): TieredModel | null;
+    readonly listModelsParams: import("@sinclair/typebox").TObject<{
+        query: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        tier: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        available_only: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    }>;
+    listModelsTool(_id: string, params: Static<typeof this.listModelsParams>): Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        details: Record<string, unknown>;
+    }>;
+    readonly pickModelParams: import("@sinclair/typebox").TObject<{
+        tier: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        min_context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        max_cost: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    }>;
+    pickModelTool(_id: string, params: Static<typeof this.pickModelParams>): Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        details: Record<string, unknown>;
+    }>;
+    readonly summaryParams: import("@sinclair/typebox").TObject<{}>;
+    summaryTool(): Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        details: Record<string, unknown>;
+    }>;
+}
+/** Singleton — initialised once at startup, used everywhere */
+export declare const modelRegistry: ModelRegistry;
+//# sourceMappingURL=ModelRegistry.d.ts.map