mozart-router 0.1.0

package/dist/types/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_POLICY = void 0;
+exports.DEFAULT_POLICY = {
+    mode: 'local_first',
+    profile: 'startup-budget',
+    privacy: {
+        mode: 'balanced',
+        secrets: 'local_only',
+        envFiles: 'block_cloud',
+        customerData: 'trusted_only',
+    },
+    budget: {
+        mode: 'balanced',
+        dailyLimitUsd: 5,
+        warnAtPercent: 80,
+    },
+    routing: {
+        explain: true,
+        fallback: true,
+        cheapFirst: true,
+        premiumForCritical: true,
+        maxRetries: 2,
+        preferLocalForSimpleTasks: true,
+        allowCloudForCode: true,
+        allowCloudForSensitiveFiles: false,
+    },
+    logs: {
+        enabled: true,
+        redactSecrets: true,
+        retentionDays: 30,
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;;AAmKa,QAAA,cAAc,GAAiB;IAC1C,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,gBAAgB;IACzB,OAAO,EAAE;QACP,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,YAAY;QACrB,QAAQ,EAAE,aAAa;QACvB,YAAY,EAAE,cAAc;KAC7B;IACD,MAAM,EAAE;QACN,IAAI,EAAE,UAAU;QAChB,aAAa,EAAE,CAAC;QAChB,aAAa,EAAE,EAAE;KAClB;IACD,OAAO,EAAE;QACP,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,IAAI;QACd,UAAU,EAAE,IAAI;QAChB,kBAAkB,EAAE,IAAI;QACxB,UAAU,EAAE,CAAC;QACb,yBAAyB,EAAE,IAAI;QAC/B,iBAAiB,EAAE,IAAI;QACvB,2BAA2B,EAAE,KAAK;KACnC;IACD,IAAI,EAAE;QACJ,OAAO,EAAE,IAAI;QACb,aAAa,EAAE,IAAI;QACnB,aAAa,EAAE,EAAE;KAClB;CACF,CAAC"}

package/dist/utils/canrunit.d.ts

@@ -0,0 +1,26 @@
+export interface LocalCapability {
+    os: string;
+    arch: string;
+    platform: string;
+    cpu: {
+        model: string;
+        cores: number;
+    };
+    ram: {
+        totalGB: number;
+        freeGB: number;
+    };
+    gpu?: {
+        model: string;
+        vramGB?: number;
+    };
+    ollamaAvailable: boolean;
+    localModelCount: number;
+}
+export declare function scanLocalCapability(): LocalCapability;
+export declare function estimateLocalModelCapacity(capability: LocalCapability): Array<{
+    modelSize: string;
+    vramRequired: number;
+    canRun: boolean;
+}>;
+//# sourceMappingURL=canrunit.d.ts.map

package/dist/utils/canrunit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canrunit.d.ts","sourceRoot":"","sources":["../../src/utils/canrunit.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,GAAG,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,mBAAmB,IAAI,eAAe,CAsBrD;AAED,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,eAAe,GAAG,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CAS3I"}

package/dist/utils/canrunit.js

@@ -0,0 +1,69 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanLocalCapability = scanLocalCapability;
+exports.estimateLocalModelCapacity = estimateLocalModelCapacity;
+const os = __importStar(require("os"));
+function scanLocalCapability() {
+    const totalRAM = Math.round((os.totalmem() / (1024 * 1024 * 1024)) * 10) / 10;
+    const freeRAM = Math.round((os.freemem() / (1024 * 1024 * 1024)) * 10) / 10;
+    const result = {
+        os: os.type(),
+        arch: os.arch(),
+        platform: os.platform(),
+        cpu: {
+            model: os.cpus()[0]?.model ?? 'unknown',
+            cores: os.cpus().length,
+        },
+        ram: {
+            totalGB: totalRAM,
+            freeGB: freeRAM,
+        },
+        ollamaAvailable: false,
+        localModelCount: 0,
+    };
+    // GPU detection placeholder (requires native modules)
+    return result;
+}
+function estimateLocalModelCapacity(capability) {
+    const vramGB = capability.gpu?.vramGB ?? 0;
+    return [
+        { modelSize: '7B (Q4)', vramRequired: 5, canRun: vramGB >= 5 || capability.ram.totalGB >= 8 },
+        { modelSize: '13B (Q4)', vramRequired: 8, canRun: vramGB >= 8 || capability.ram.totalGB >= 16 },
+        { modelSize: '34B (Q4)', vramRequired: 20, canRun: vramGB >= 20 },
+        { modelSize: '70B (Q4)', vramRequired: 40, canRun: vramGB >= 40 },
+    ];
+}
+//# sourceMappingURL=canrunit.js.map

package/dist/utils/canrunit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canrunit.js","sourceRoot":"","sources":["../../src/utils/canrunit.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAaA,kDAsBC;AAED,gEASC;AA9CD,uCAAyB;AAazB,SAAgB,mBAAmB;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC;IAC9E,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC;IAE5E,MAAM,MAAM,GAAoB;QAC9B,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE;QACb,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE;QACf,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE;QACvB,GAAG,EAAE;YACH,KAAK,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,SAAS;YACvC,KAAK,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM;SACxB;QACD,GAAG,EAAE;YACH,OAAO,EAAE,QAAQ;YACjB,MAAM,EAAE,OAAO;SAChB;QACD,eAAe,EAAE,KAAK;QACtB,eAAe,EAAE,CAAC;KACnB,CAAC;IAEF,sDAAsD;IACtD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAgB,0BAA0B,CAAC,UAA2B;IACpE,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC,CAAC;IAE3C,OAAO;QACL,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,EAAE;QAC7F,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,EAAE;QAC/F,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE;QACjE,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE;KAClE,CAAC;AACJ,CAAC"}

package/dist/utils/dealsforge.d.ts

@@ -0,0 +1,6 @@
+import { InventoryRegistry } from '../core/inventory';
+export declare function syncDealsForgeData(registry: InventoryRegistry): {
+    modelsAdded: number;
+    providersAdded: number;
+};
+//# sourceMappingURL=dealsforge.d.ts.map

package/dist/utils/dealsforge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dealsforge.d.ts","sourceRoot":"","sources":["../../src/utils/dealsforge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAkEtD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,iBAAiB,GAC1B;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CA0CjD"}

package/dist/utils/dealsforge.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncDealsForgeData = syncDealsForgeData;
+const DEALSFORGE_MODELS = [
+    {
+        providerId: 'openrouter',
+        id: 'openai/gpt-4o',
+        displayName: 'GPT-4o',
+        family: 'gpt-4',
+        contextWindow: 128000,
+        inputPrice: 2.5,
+        outputPrice: 10.0,
+        latencyClass: 'medium',
+        qualityClass: 'premium',
+        modality: ['text', 'vision', 'multimodal'],
+        strengths: ['general', 'coding', 'vision', 'tools'],
+        supportsTools: true,
+        supportsJsonMode: true,
+        privacyLevel: 'cloud',
+    },
+    {
+        providerId: 'openrouter',
+        id: 'openai/gpt-4.1-nano',
+        displayName: 'GPT-4.1 Nano',
+        family: 'gpt-4',
+        contextWindow: 1000000,
+        inputPrice: 0.1,
+        outputPrice: 0.4,
+        latencyClass: 'fast',
+        qualityClass: 'medium',
+        modality: ['text'],
+        strengths: ['cheap', 'long_context'],
+        privacyLevel: 'cloud',
+    },
+    {
+        providerId: 'openrouter',
+        id: 'anthropic/claude-haiku-3.5',
+        displayName: 'Claude Haiku 3.5',
+        family: 'claude',
+        contextWindow: 200000,
+        inputPrice: 0.8,
+        outputPrice: 4.0,
+        latencyClass: 'fast',
+        qualityClass: 'high',
+        modality: ['text', 'vision'],
+        strengths: ['coding', 'fast', 'tools'],
+        supportsTools: true,
+        privacyLevel: 'cloud',
+    },
+    {
+        providerId: 'openrouter',
+        id: 'deepseek/deepseek-r1',
+        displayName: 'DeepSeek R1',
+        family: 'deepseek',
+        contextWindow: 65536,
+        inputPrice: 0.55,
+        outputPrice: 2.19,
+        latencyClass: 'medium',
+        qualityClass: 'high',
+        modality: ['text'],
+        strengths: ['reasoning', 'coding', 'math'],
+        supportsTools: true,
+        privacyLevel: 'cloud',
+    },
+];
+function syncDealsForgeData(registry) {
+    let modelsAdded = 0;
+    let providersAdded = 0;
+    for (const entry of DEALSFORGE_MODELS) {
+        const model = {
+            ...entry,
+            id: entry.id,
+            displayName: entry.displayName,
+            modality: entry.modality ?? ['text'],
+            latencyClass: entry.latencyClass ?? 'unknown',
+            qualityClass: entry.qualityClass ?? 'unknown',
+            strengths: entry.strengths ?? [],
+            weaknesses: [],
+            privacyLevel: entry.privacyLevel ?? 'cloud',
+            availability: 'available',
+            sourceConfidence: 'high',
+            lastCheckedAt: new Date().toISOString(),
+        };
+        const existing = registry.getModel(entry.providerId, entry.id);
+        if (!existing) {
+            registry.addModel(model);
+            modelsAdded++;
+        }
+    }
+    // Add a DealsForge provider
+    const existing = registry.getProvider('dealsforge');
+    if (!existing) {
+        registry.addProvider({
+            id: 'dealsforge',
+            name: 'DealsForge Intelligence',
+            source: 'dealsforge',
+            privacyLevel: 'cloud',
+            status: 'available',
+            lastCheckedAt: new Date().toISOString(),
+        });
+        providersAdded++;
+    }
+    return { modelsAdded, providersAdded };
+}
+//# sourceMappingURL=dealsforge.js.map

package/dist/utils/dealsforge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dealsforge.js","sourceRoot":"","sources":["../../src/utils/dealsforge.ts"],"names":[],"mappings":"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"}

package/docs/ADAPTERS.md

@@ -0,0 +1,129 @@
+# Adapters
+
+## Overview
+
+Mozart adapters connect to existing gateways and tools. Each adapter implements the `GatewayAdapter` interface:
+
+```typescript
+interface GatewayAdapter {
+  id: string;
+  name: string;
+  detect(): Promise<DetectionResult>;
+  readConfig?(): Promise<GatewayConfigSummary>;
+  listProviders(): Promise<Provider[]>;
+  listModels(): Promise<Model[]>;
+  listCapabilities?(): Promise<CapabilitySummary>;
+  getExecutionTarget?(decision: RouteDecision): Promise<ExecutionTarget>;
+  testConnection?(): Promise<ConnectionStatus>;
+  execute?(request: ExecutionRequest): Promise<ExecutionResult>;
+}
+```
+
+## Real adapters
+
+### OllamaAdapter
+- **ID:** `ollama`
+- **Detection:** Checks for `ollama` in PATH, runs `ollama --version` and `ollama list`
+- **Provider:** Local Ollama instance
+- **Execution:** Direct HTTP to `http://localhost:11434`
+- **Privacy:** Local-only, no API key needed
+
+### LiteLLMAdapter
+- **ID:** `litellm`
+- **Detection:** Scans for `litellm_config.yaml` in common locations (cwd, ~/.litellm/)
+- **Provider:** Parsed from config
+- **Execution:** Delegates to LiteLLM proxy (does not execute directly)
+- **Note:** Never reads or stores raw API keys from config
+
+### OpenRouterAdapter
+- **ID:** `openrouter`
+- **Detection:** Checks for `OPENROUTER_API_KEY` in environment
+- **Provider:** OpenRouter gateway
+- **Execution:** Recommends models, delegates execution
+- **Inventory:** Curated list of popular models with pricing
+
+### OpenCodeAdapter
+- **ID:** `opencode`
+- **Status:** Real detection
+- **Detection:** Checks for OpenCode installation via environment variables (OPENCODE_CLIENT, OPENCODE_SERVER_USERNAME) and data directory
+- **Integration path:** `examples/opencode/mozart-skill.json`
+
+### OpenClawAdapter
+- **ID:** `openclaw`
+- **Status:** Real detection — reads openclaw.json
+- **Detection:** Parses `~/.openclaw/openclaw.json`, extracts all providers, models, gateway settings
+- **Integration path:** `examples/openclaw/mozart-skill.yaml`
+
+### LMStudioAdapter
+- **ID:** `lmstudio`
+- **Status:** Real — HTTP detection
+- **Detection:** Queries `http://localhost:1234/v1/models`
+- **Execution:** Direct HTTP to LM Studio's OpenAI-compatible endpoint
+
+### VllmAdapter
+- **ID:** `vllm`
+- **Status:** Real — HTTP detection
+- **Detection:** Queries `http://localhost:8000/v1/models`
+- **Execution:** Direct HTTP to vLLM's OpenAI-compatible endpoint
+
+### NvidiaNimAdapter
+- **ID:** `nim`
+- **Status:** Real — HTTP + env detection
+- **Detection:** Queries local NIM endpoint + checks NVIDIA_API_KEY
+- **Inventory:** Curated list of NIM-available models (Llama, Mixtral)
+
+### GenericOpenAIAdapter
+- **ID:** configurable
+- **Status:** Universal plug-and-play
+- **Detection:** Queries any OpenAI-compatible `/v1/models` endpoint
+- **Auto-discovery:** Scans 11 common endpoints (Ollama, LM Studio, vLLM, LiteLLM, OpenRouter, OpenAI, Groq, Together, DeepSeek, Fireworks, Mistral)
+- **Custom:** Accepts any base URL — no code changes needed for new gateways
+
+## Stub adapters
+
+These adapters have full typed interfaces ready but require the target environment for real detection:
+
+### HermesAdapter
+- **ID:** `hermes`
+- **Status:** Stub with manifest
+- **Integration path:** `examples/hermes/mozart-tool.json`
+- **Next steps:** Connect to Hermes tool system
+
+### CursorAdapter
+- **ID:** `cursor`
+- **Status:** Stub with documentation
+- **Next steps:** Expose as local endpoint or use via SDK
+
+## Creating a custom adapter
+
+```typescript
+import { GatewayAdapter, DetectionResult, Provider, Model } from 'mozart-router';
+
+export class MyCustomAdapter implements GatewayAdapter {
+  id = 'my-custom';
+  name = 'My Custom Gateway';
+
+  async detect(): Promise<DetectionResult> {
+    // Check if your gateway is available
+    return {
+      detected: true,
+      gatewayId: this.id,
+      gatewayName: this.name,
+      status: 'active',
+      providersCount: 1,
+      modelsCount: 3,
+      details: ['Custom gateway detected'],
+    };
+  }
+
+  async listProviders(): Promise<Provider[]> {
+    // Return your providers
+    return [];
+  }
+
+  async listModels(): Promise<Model[]> {
+    // Return your models
+    return [];
+  }
+}
+```

package/docs/ARCHITECTURE.md

@@ -0,0 +1,113 @@
+# Architecture
+
+## High-level design
+
+Mozart is designed as a **gateway-first orchestration layer**. It does not replace gateways — it sits between agents and gateways adding decision intelligence.
+
+```
+┌──────────────────────────────────────────────────┐
+│                  Agent / IDE / User               │
+├──────────────────────────────────────────────────┤
+│              Mozart Interface Layer               │
+│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
+│  │   SDK    │ │   CLI    │ │  Skill/Tool API   │  │
+│  └──────────┘ └──────────┘ └──────────────────┘  │
+├──────────────────────────────────────────────────┤
+│         Gateway Introspection Layer               │
+│  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐  │
+│  │Ollama  │ │LiteLLM │ │OpenRt │ │Agent De-  │  │
+│  │Adapter │ │Adapter │ │Adapter│ │tectors    │  │
+│  └────────┘ └────────┘ └────────┘ └──────────┘  │
+├──────────────────────────────────────────────────┤
+│           Mozart Core Engine                      │
+│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
+│  │Inventory │ │  Policy  │ │  Privacy Guard   │  │
+│  │Registry  │ │  Engine  │ │                  │  │
+│  └──────────┘ └──────────┘ └──────────────────┘  │
+│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
+│  │ Task     │ │ Routing  │ │   Context        │  │
+│  │Classifier│ │ Engine   │ │   Optimizer      │  │
+│  └──────────┘ └──────────┘ └──────────────────┘  │
+│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
+│  │  Cost    │ │Explain-  │ │   Logger +       │  │
+│  │Estimator │ │ability   │ │   Redactor       │  │
+│  └──────────┘ └──────────┘ └──────────────────┘  │
+├──────────────────────────────────────────────────┤
+│          Execution Delegation Layer               │
+│  ┌──────────────────────────────────────────────┐ │
+│  │  Delegates to: LiteLLM / OpenRouter /        │ │
+│  │  Ollama / Direct Provider / Agent Tool       │ │
+│  └──────────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────┘
+```
+
+## Design principles
+
+### 1. Gateway-first
+Mozart never rebuilds what a gateway already does. It detects, understands, and orchestrates existing infrastructure.
+
+### 2. Agent-first
+Mozart integrates as a skill, tool, or adapter within existing agent frameworks — never as a separate application.
+
+### 3. Integration-first
+Every module is designed to be importable as a TypeScript SDK, not locked behind a UI or service boundary.
+
+### 4. Local-first
+All processing (classification, privacy scanning, routing, logging) happens locally. No cloud dependency for core functionality.
+
+### 5. Privacy by default
+Secrets are never logged. Privacy guard scans all content before routing. Local-only mode available.
+
+### 6. Modular
+Every component is independently usable. You can use just the Privacy Guard, just the Router, or the full orchestrator.
+
+## Module dependencies
+
+```
+types/ (zero dependencies)
+  |
+  ├─ core/
+  │   ├─ inventory.ts (types)
+  │   ├─ session.ts (types)
+  │   └─ mozart.ts (all modules)
+  |
+  ├─ adapters/ (types, core/inventory)
+  │   ├─ ollama.ts
+  │   ├─ litellm.ts
+  │   ├─ openrouter.ts
+  │   ├─ opencode.ts
+  │   ├─ openclaw.ts
+  │   ├─ hermes.ts
+  │   └─ cursor.ts
+  |
+  ├─ routing/
+  │   ├─ classifier.ts (types)
+  │   ├─ scorer.ts (types)
+  │   └─ router.ts (types, core/inventory, policy, cost)
+  |
+  ├─ policy/engine.ts (types)
+  ├─ privacy/guard.ts (types, logs)
+  ├─ context/optimizer.ts (types)
+  ├─ cost/estimator.ts (types)
+  ├─ explain/engine.ts (types)
+  |
+  ├─ logs/
+  │   ├─ logger.ts (types)
+  │   └─ redactor.ts
+  |
+  ├─ skills/definitions.ts (types)
+  └─ cli/main.ts (all modules)
+```
+
+## Data flow
+
+```
+User Input → Task Classifier → Task Profile
+           → Privacy Guard → Privacy Decision
+           → Policy Engine → Policy Evaluation
+           → Context Optimizer → Context Strategy
+           → Routing Engine → Route Decision
+           → Execution Delegation → Gateway Call
+           → Explainability → Explanation
+           → Logger → Local Logs
+```

package/docs/DELEGATED_EXECUTION.md

@@ -0,0 +1,62 @@
+# Delegated Execution — Mozart
+
+Mozart delegates execution to existing gateways. It does not become a gateway itself.
+
+## Architecture
+
+```
+Agent → Mozart → Gateway → Provider
+        (decide)  (execute)
+```
+
+Mozart sits in the decision position. The gateway sits in the execution position. This separation is intentional and permanent.
+
+## Execution targets
+
+When Mozart selects a route, it produces an `ExecutionTarget`:
+
+```typescript
+interface ExecutionTarget {
+  adapter: string;        // Which adapter handles this
+  gateway?: string;       // Which gateway
+  provider: string;       // Which provider
+  model: string;          // Which model
+  baseUrl?: string;       // Where to send the request
+  requiresApiKey?: boolean;
+  apiKeyManagedBy: 'gateway' | 'env' | 'manual' | 'none';
+  method: 'gateway_call' | 'tool_call' | 'direct_http' | 'local_exec';
+}
+```
+
+Key field: `apiKeyManagedBy` — Mozart never stores the key, only records who manages it.
+
+## Execution flow
+
+1. Mozart routes the task → produces `RouteDecision`
+2. Mozart delegates to the adapter → adapter provides `ExecutionTarget`
+3. Mozart calls `adapter.execute()` → adapter handles the HTTP call
+4. Mozart returns the result → gateway never exposed
+
+## Adapter responsibility
+
+Adapters are responsible for:
+- Detecting the gateway
+- Reading its config (without raw keys)
+- Providing execution targets
+- Executing calls when possible
+
+Mozart is responsible for:
+- Classifying tasks
+- Scoring models
+- Selecting the best route
+- Delegating to the right adapter
+
+## When execution is not available
+
+If an adapter doesn't support execution (or the gateway isn't accessible):
+
+- Mozart returns a recommendation (recommend-only)
+- The user/agent sends the call themselves using their existing gateway
+- Mozart's recommendation includes the exact model, provider, and rationale
+
+This is the preferred mode. Execution is optional.