@lexmanh/shed-agent 0.2.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,279 @@
+import { CleanableItem } from '@lexmanh/shed-core';
+
+/**
+ * AIProvider — unified interface for AI backends.
+ *
+ * Implementations: anthropic, openai, ollama.
+ */
+interface AIMessage {
+    readonly role: 'user' | 'assistant' | 'system';
+    readonly content: string;
+}
+interface AITool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+}
+interface AIToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+}
+interface AIResponse {
+    readonly text: string;
+    readonly toolCalls: readonly AIToolCall[];
+    readonly stopReason: 'end' | 'tool_use' | 'max_tokens';
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+}
+interface AIProvider {
+    readonly name: string;
+    readonly isLocal: boolean;
+    /**
+     * Send a conversation to the AI and get a response.
+     * Supports function calling via tools parameter.
+     */
+    chat(args: {
+        messages: readonly AIMessage[];
+        tools?: readonly AITool[];
+        maxTokens?: number;
+        signal?: AbortSignal;
+    }): Promise<AIResponse>;
+}
+/**
+ * Privacy preview — what will be sent to the AI provider.
+ * Shown to the user BEFORE the request leaves the machine (unless provider is local).
+ */
+interface PrivacyPreview {
+    readonly providerName: string;
+    readonly isLocal: boolean;
+    readonly dataIncluded: readonly string[];
+    readonly dataExcluded: readonly string[];
+    readonly estimatedTokens: number;
+}
+
+declare class AnthropicProvider implements AIProvider {
+    readonly name = "anthropic";
+    readonly isLocal = false;
+    private readonly client;
+    private readonly model;
+    constructor(apiKey: string, model?: string);
+    chat(args: {
+        messages: readonly AIMessage[];
+        tools?: readonly AITool[];
+        maxTokens?: number;
+        signal?: AbortSignal;
+    }): Promise<AIResponse>;
+}
+
+declare class GeminiProvider implements AIProvider {
+    readonly name = "gemini";
+    readonly isLocal = false;
+    private readonly client;
+    private readonly model;
+    constructor(apiKey: string, model?: string);
+    chat(args: {
+        messages: readonly AIMessage[];
+        tools?: readonly AITool[];
+        maxTokens?: number;
+        signal?: AbortSignal;
+    }): Promise<AIResponse>;
+}
+
+/**
+ * Base provider for OpenAI-compatible APIs.
+ * Used by OpenAI, Groq, Mistral, Ollama, OpenRouter — all share the same
+ * chat completions API shape, differing only in baseURL and available models.
+ */
+
+interface OpenAICompatibleOptions {
+    readonly apiKey: string;
+    readonly model: string;
+    readonly baseURL?: string;
+    readonly providerName: string;
+    readonly isLocal?: boolean;
+}
+declare class OpenAICompatibleProvider implements AIProvider {
+    readonly name: string;
+    readonly isLocal: boolean;
+    private readonly client;
+    private readonly model;
+    constructor(options: OpenAICompatibleOptions);
+    chat(args: {
+        messages: readonly AIMessage[];
+        tools?: readonly AITool[];
+        maxTokens?: number;
+        signal?: AbortSignal;
+    }): Promise<AIResponse>;
+}
+
+declare class GroqProvider extends OpenAICompatibleProvider {
+    constructor(apiKey: string, model?: string);
+}
+
+declare class MistralProvider extends OpenAICompatibleProvider {
+    constructor(apiKey: string, model?: string);
+}
+
+declare class OllamaProvider extends OpenAICompatibleProvider {
+    constructor(model?: string, endpoint?: string);
+}
+
+declare class OpenAIProvider extends OpenAICompatibleProvider {
+    constructor(apiKey: string, model?: string);
+}
+
+/**
+ * OpenRouter — aggregates 200+ models behind a single API key.
+ * Default model: google/gemini-2.5-pro (strong, cost-effective).
+ * Users can set any model slug from openrouter.ai/models.
+ */
+declare class OpenRouterProvider extends OpenAICompatibleProvider {
+    constructor(apiKey: string, model?: string);
+}
+
+/**
+ * Tool schemas used by both the built-in AI (agent package) and MCP server.
+ * These are READ-ONLY tools — AI cannot execute cleanup directly.
+ * Cleanup requires explicit user confirmation in the CLI.
+ */
+
+declare const TOOLS: {
+    readonly listProjects: {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                root: {
+                    type: string;
+                    description: string;
+                };
+                maxDepth: {
+                    type: string;
+                    description: string;
+                    default: number;
+                };
+            };
+            required: string[];
+        };
+    };
+    readonly analyzeProject: {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                path: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    readonly estimateCleanup: {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                itemIds: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                };
+                includeRed: {
+                    type: string;
+                    default: boolean;
+                };
+            };
+            required: string[];
+        };
+    };
+    readonly getDiskUsage: {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                path: {
+                    type: string;
+                    description: string;
+                };
+            };
+        };
+    };
+};
+declare const ALL_TOOLS: readonly AITool[];
+
+/**
+ * ToolExecutor — bridges AI tool calls to shed-core Scanner.
+ * All operations are READ-ONLY. AI cannot trigger cleanup.
+ */
+
+type ToolResult = Record<string, unknown>;
+declare function executeToolCall(name: string, input: Record<string, unknown>, allScannedItems?: readonly CleanableItem[]): Promise<ToolResult>;
+
+/**
+ * ExplainSession — orchestrates a single AI analysis session.
+ *
+ * Flow:
+ * 1. Build privacy preview (what data will be sent)
+ * 2. Show preview and ask user consent (unless provider is local)
+ * 3. Run agentic loop: AI calls tools → executor resolves → AI responds
+ * 4. Return final explanation text
+ *
+ * Token budget: warn at 40k, hard stop at 100k (CLAUDE.md rule 8.4).
+ */
+
+interface ExplainSessionOptions {
+    readonly provider: AIProvider;
+    readonly scanRoot: string;
+    readonly scannedItems?: readonly CleanableItem[];
+    /** Called to show privacy preview and get user consent. Return false to abort. */
+    readonly onPrivacyPrompt: (preview: PrivacyPreview) => Promise<boolean>;
+    /** Called when token warning threshold is reached. */
+    readonly onTokenWarning?: (used: number) => void;
+    /** System prompt override. */
+    readonly systemPrompt?: string;
+}
+interface ExplainResult {
+    readonly text: string;
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly aborted: boolean;
+}
+declare class ExplainSession {
+    private readonly options;
+    constructor(options: ExplainSessionOptions);
+    run(userQuestion: string): Promise<ExplainResult>;
+}
+
+/**
+ * Factory to instantiate the correct AIProvider from shed config.
+ * API keys are stored in the OS keychain via keytar.
+ *
+ * Supported providers: anthropic, openai, gemini, groq, mistral, openrouter, ollama
+ */
+
+type ProviderName = 'anthropic' | 'openai' | 'gemini' | 'groq' | 'mistral' | 'openrouter' | 'ollama';
+declare const PROVIDER_NAMES: ProviderName[];
+declare const DEFAULT_MODELS: Record<ProviderName, string>;
+declare function getStoredApiKey(provider: ProviderName): Promise<string | null>;
+declare function setStoredApiKey(provider: ProviderName, key: string): Promise<void>;
+declare function deleteStoredApiKey(provider: ProviderName): Promise<void>;
+interface CreateProviderOptions {
+    readonly provider: ProviderName;
+    readonly model?: string;
+    /** For ollama: base URL override */
+    readonly ollamaEndpoint?: string;
+    /** API key override (skips keychain lookup) */
+    readonly apiKey?: string;
+}
+declare function createProvider(options: CreateProviderOptions): Promise<AIProvider>;
+
+export { type AIMessage, type AIProvider, type AIResponse, type AITool, type AIToolCall, ALL_TOOLS, AnthropicProvider, type CreateProviderOptions, DEFAULT_MODELS, type ExplainResult, ExplainSession, type ExplainSessionOptions, GeminiProvider, GroqProvider, MistralProvider, OllamaProvider, type OpenAICompatibleOptions, OpenAICompatibleProvider, OpenAIProvider, OpenRouterProvider, PROVIDER_NAMES, type PrivacyPreview, type ProviderName, TOOLS, type ToolResult, createProvider, deleteStoredApiKey, executeToolCall, getStoredApiKey, setStoredApiKey };

package/dist/index.js

@@ -0,0 +1,588 @@
+// src/providers/anthropic.ts
+import Anthropic from "@anthropic-ai/sdk";
+var AnthropicProvider = class {
+  name = "anthropic";
+  isLocal = false;
+  client;
+  model;
+  constructor(apiKey, model = "claude-opus-4-7") {
+    this.client = new Anthropic({ apiKey });
+    this.model = model;
+  }
+  async chat(args) {
+    const sdkMessages = args.messages.filter((m) => m.role !== "system").map((m) => ({ role: m.role, content: m.content }));
+    const systemMsg = args.messages.find((m) => m.role === "system")?.content;
+    const sdkTools = args.tools?.map((t) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.inputSchema
+    }));
+    const response = await this.client.messages.create(
+      {
+        model: this.model,
+        max_tokens: args.maxTokens ?? 1024,
+        ...systemMsg ? { system: systemMsg } : {},
+        messages: sdkMessages,
+        ...sdkTools?.length ? { tools: sdkTools } : {}
+      },
+      { signal: args.signal }
+    );
+    const text = response.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+    const toolCalls = response.content.filter((b) => b.type === "tool_use").map((b) => ({ id: b.id, name: b.name, input: b.input }));
+    const stopReason = response.stop_reason === "tool_use" ? "tool_use" : response.stop_reason === "max_tokens" ? "max_tokens" : "end";
+    return {
+      text,
+      toolCalls,
+      stopReason,
+      usage: {
+        inputTokens: response.usage.input_tokens,
+        outputTokens: response.usage.output_tokens
+      }
+    };
+  }
+};
+
+// src/providers/gemini.ts
+import { GoogleGenAI } from "@google/genai";
+var GeminiProvider = class {
+  name = "gemini";
+  isLocal = false;
+  client;
+  model;
+  constructor(apiKey, model = "gemini-2.5-pro") {
+    this.client = new GoogleGenAI({ apiKey });
+    this.model = model;
+  }
+  async chat(args) {
+    const systemMsg = args.messages.find((m) => m.role === "system")?.content;
+    const history = args.messages.filter((m) => m.role !== "system").slice(0, -1).map((m) => ({
+      role: m.role === "assistant" ? "model" : "user",
+      parts: [{ text: m.content }]
+    }));
+    const lastMsg = args.messages.filter((m) => m.role !== "system").at(-1);
+    const sdkTools = args.tools?.length ? [
+      {
+        functionDeclarations: args.tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          parameters: t.inputSchema
+        }))
+      }
+    ] : void 0;
+    const chat = this.client.chats.create({
+      model: this.model,
+      ...systemMsg ? { systemInstruction: systemMsg } : {},
+      history,
+      config: {
+        maxOutputTokens: args.maxTokens ?? 1024,
+        ...sdkTools ? { tools: sdkTools } : {}
+      }
+    });
+    const response = await chat.sendMessage({ message: lastMsg?.content ?? "" });
+    const text = response.text ?? "";
+    const toolCalls = (response.functionCalls ?? []).map((fc, i) => ({
+      id: `gemini-tc-${i}`,
+      name: fc.name ?? "",
+      input: fc.args ?? {}
+    }));
+    const stopReason = toolCalls.length > 0 ? "tool_use" : response.candidates?.[0]?.finishReason === "MAX_TOKENS" ? "max_tokens" : "end";
+    const usage = response.usageMetadata;
+    return {
+      text,
+      toolCalls,
+      stopReason,
+      usage: {
+        inputTokens: usage?.promptTokenCount ?? 0,
+        outputTokens: usage?.candidatesTokenCount ?? 0
+      }
+    };
+  }
+};
+
+// src/providers/openai-compatible.ts
+import OpenAI from "openai";
+var OpenAICompatibleProvider = class {
+  name;
+  isLocal;
+  client;
+  model;
+  constructor(options) {
+    this.name = options.providerName;
+    this.isLocal = options.isLocal ?? false;
+    this.model = options.model;
+    this.client = new OpenAI({
+      apiKey: options.apiKey,
+      ...options.baseURL ? { baseURL: options.baseURL } : {}
+    });
+  }
+  async chat(args) {
+    const sdkMessages = args.messages.map((m) => ({
+      role: m.role,
+      content: m.content
+    }));
+    const sdkTools = args.tools?.map((t) => ({
+      type: "function",
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.inputSchema
+      }
+    }));
+    const response = await this.client.chat.completions.create(
+      {
+        model: this.model,
+        max_tokens: args.maxTokens ?? 1024,
+        messages: sdkMessages,
+        ...sdkTools?.length ? { tools: sdkTools } : {}
+      },
+      { signal: args.signal }
+    );
+    const choice = response.choices[0];
+    const message = choice?.message;
+    const text = message?.content ?? "";
+    const toolCalls = (message?.tool_calls ?? []).map((tc) => ({
+      id: tc.id,
+      name: tc.function.name,
+      input: JSON.parse(tc.function.arguments)
+    }));
+    const stopReason = choice?.finish_reason === "tool_calls" ? "tool_use" : choice?.finish_reason === "length" ? "max_tokens" : "end";
+    return {
+      text,
+      toolCalls,
+      stopReason,
+      usage: {
+        inputTokens: response.usage?.prompt_tokens ?? 0,
+        outputTokens: response.usage?.completion_tokens ?? 0
+      }
+    };
+  }
+};
+
+// src/providers/groq.ts
+var GroqProvider = class extends OpenAICompatibleProvider {
+  constructor(apiKey, model = "llama-3.3-70b-versatile") {
+    super({
+      apiKey,
+      model,
+      baseURL: "https://api.groq.com/openai/v1",
+      providerName: "groq"
+    });
+  }
+};
+
+// src/providers/mistral.ts
+var MistralProvider = class extends OpenAICompatibleProvider {
+  constructor(apiKey, model = "mistral-large-latest") {
+    super({
+      apiKey,
+      model,
+      baseURL: "https://api.mistral.ai/v1",
+      providerName: "mistral"
+    });
+  }
+};
+
+// src/providers/ollama.ts
+var OllamaProvider = class extends OpenAICompatibleProvider {
+  constructor(model = "llama3.2", endpoint = "http://localhost:11434") {
+    super({
+      apiKey: "ollama",
+      // Ollama doesn't require a real key
+      model,
+      baseURL: `${endpoint}/v1`,
+      providerName: "ollama",
+      isLocal: true
+    });
+  }
+};
+
+// src/providers/openai.ts
+var OpenAIProvider = class extends OpenAICompatibleProvider {
+  constructor(apiKey, model = "gpt-4o") {
+    super({ apiKey, model, providerName: "openai" });
+  }
+};
+
+// src/providers/openrouter.ts
+var OpenRouterProvider = class extends OpenAICompatibleProvider {
+  constructor(apiKey, model = "google/gemini-2.5-pro") {
+    super({
+      apiKey,
+      model,
+      baseURL: "https://openrouter.ai/api/v1",
+      providerName: "openrouter"
+    });
+  }
+};
+
+// src/tools.ts
+var TOOLS = {
+  listProjects: {
+    name: "list_projects",
+    description: "List all detected projects under a given path. Returns project type, path, last-modified date, and total cleanable size. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        root: { type: "string", description: "Absolute path to scan from" },
+        maxDepth: { type: "number", description: "Max directory depth", default: 5 }
+      },
+      required: ["root"]
+    }
+  },
+  analyzeProject: {
+    name: "analyze_project",
+    description: "Get detailed analysis of a single project: all cleanable items, risk tiers, git status, last activity. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute path to the project root" }
+      },
+      required: ["path"]
+    }
+  },
+  estimateCleanup: {
+    name: "estimate_cleanup",
+    description: "Estimate space that would be freed by cleaning a set of items. Runs safety checks and returns what would be allowed vs skipped. Read-only, never deletes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        itemIds: { type: "array", items: { type: "string" } },
+        includeRed: { type: "boolean", default: false }
+      },
+      required: ["itemIds"]
+    }
+  },
+  getDiskUsage: {
+    name: "get_disk_usage",
+    description: "Get current disk usage on the user machine (free / used / total).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to check (defaults to home)" }
+      }
+    }
+  }
+};
+var ALL_TOOLS = Object.values(TOOLS);
+
+// src/tool-executor.ts
+import {
+  AndroidDetector,
+  CocoaPodsDetector,
+  DockerDetector,
+  FlutterDetector,
+  IdeDetector,
+  NodeDetector,
+  PythonDetector,
+  RustDetector,
+  SafetyChecker,
+  Scanner,
+  XcodeDetector
+} from "@lexmanh/shed-core";
+import { execa } from "execa";
+function makeScanner() {
+  return new Scanner([
+    new NodeDetector(),
+    new PythonDetector(),
+    new RustDetector(),
+    new DockerDetector(),
+    new XcodeDetector(),
+    new FlutterDetector(),
+    new AndroidDetector(),
+    new CocoaPodsDetector(),
+    new IdeDetector()
+  ]);
+}
+async function executeToolCall(name, input, allScannedItems) {
+  switch (name) {
+    case "list_projects": {
+      const root = input.root ?? process.env.HOME ?? "/";
+      const maxDepth = input.maxDepth ?? 5;
+      const scanner = makeScanner();
+      const ctx = { scanRoot: root, maxDepth };
+      const [projects, globalItems] = await Promise.all([
+        scanner.scan(root),
+        scanner.scanGlobal(ctx)
+      ]);
+      return {
+        root,
+        projectCount: projects.length,
+        projects: projects.map((p) => ({
+          root: p.root,
+          type: p.type,
+          name: p.name,
+          lastModified: p.lastModified,
+          cleanableItems: p.items.length,
+          totalBytes: p.items.reduce((s, i) => s + i.sizeBytes, 0)
+        })),
+        globalItemCount: globalItems.length,
+        globalTotalBytes: globalItems.reduce((s, i) => s + i.sizeBytes, 0)
+      };
+    }
+    case "analyze_project": {
+      const path = input.path;
+      const scanner = makeScanner();
+      const ctx = { scanRoot: path, maxDepth: 3 };
+      const projects = await scanner.scan(path);
+      const project = projects.find((p) => p.root === path) ?? projects[0];
+      if (!project) return { error: `No project detected at ${path}` };
+      const checker = new SafetyChecker();
+      const checkResults = await Promise.all(project.items.map((i) => checker.check(i)));
+      return {
+        root: project.root,
+        type: project.type,
+        name: project.name,
+        hasGit: project.hasGit,
+        lastModified: project.lastModified,
+        items: project.items.map((item, idx) => ({
+          id: item.id,
+          path: item.path,
+          risk: item.risk,
+          sizeBytes: item.sizeBytes,
+          description: item.description,
+          safetyAllowed: checkResults[idx]?.allowed ?? false,
+          safetyReasons: checkResults[idx]?.reasons ?? []
+        })),
+        // scanGlobal not relevant per-project
+        ctx
+      };
+    }
+    case "estimate_cleanup": {
+      const itemIds = input.itemIds ?? [];
+      if (!allScannedItems) {
+        return { error: "No scan context available. Run list_projects first." };
+      }
+      const targets = allScannedItems.filter((i) => itemIds.includes(i.id));
+      const checker = new SafetyChecker();
+      const results = await Promise.all(targets.map((i) => checker.check(i)));
+      const allowed = targets.filter((_, idx) => results[idx]?.allowed);
+      const blocked = targets.filter((_, idx) => !results[idx]?.allowed);
+      return {
+        totalRequested: targets.length,
+        allowedCount: allowed.length,
+        blockedCount: blocked.length,
+        estimatedBytesFreed: allowed.reduce((s, i) => s + i.sizeBytes, 0),
+        blocked: blocked.map((i) => ({
+          id: i.id,
+          path: i.path,
+          reason: results[targets.indexOf(i)]?.reasons.find((r) => r.severity === "block")?.message
+        }))
+      };
+    }
+    case "get_disk_usage": {
+      const checkPath = input.path ?? process.env.HOME ?? "/";
+      try {
+        const { stdout } = await execa("df", ["-k", checkPath]);
+        const lines = stdout.trim().split("\n");
+        const parts = lines[1]?.split(/\s+/) ?? [];
+        const totalKb = Number.parseInt(parts[1] ?? "0", 10);
+        const usedKb = Number.parseInt(parts[2] ?? "0", 10);
+        const availKb = Number.parseInt(parts[3] ?? "0", 10);
+        return {
+          path: checkPath,
+          totalBytes: totalKb * 1024,
+          usedBytes: usedKb * 1024,
+          freeBytes: availKb * 1024,
+          usedPercent: totalKb > 0 ? Math.round(usedKb / totalKb * 100) : 0
+        };
+      } catch {
+        return { error: "Could not read disk usage" };
+      }
+    }
+    default:
+      return { error: `Unknown tool: ${name}` };
+  }
+}
+
+// src/explain-session.ts
+var TOKEN_WARN = 4e4;
+var TOKEN_HARD_STOP = 1e5;
+var DEFAULT_SYSTEM = `You are Shed, an AI assistant helping developers reclaim disk space safely.
+You have access to tools to scan projects and analyze disk usage. Use them to give accurate,
+specific recommendations. Always explain WHY something is safe to delete and how to regenerate it.
+Be concise. Format sizes in human-readable form (MB/GB). Never suggest deleting anything without
+explaining the risk tier and how to recover.`;
+var ExplainSession = class {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  async run(userQuestion) {
+    const { provider, scanRoot, scannedItems, onPrivacyPrompt, onTokenWarning } = this.options;
+    if (!provider.isLocal) {
+      const preview = buildPrivacyPreview(provider.name, scanRoot, scannedItems);
+      const consented = await onPrivacyPrompt(preview);
+      if (!consented) {
+        return { text: "", totalInputTokens: 0, totalOutputTokens: 0, aborted: true };
+      }
+    }
+    const messages = [
+      {
+        role: "system",
+        content: this.options.systemPrompt ?? DEFAULT_SYSTEM
+      },
+      { role: "user", content: userQuestion }
+    ];
+    let totalInput = 0;
+    let totalOutput = 0;
+    for (let i = 0; i < 10; i++) {
+      const response = await provider.chat({
+        messages,
+        tools: ALL_TOOLS,
+        maxTokens: 2048
+      });
+      totalInput += response.usage.inputTokens;
+      totalOutput += response.usage.outputTokens;
+      const totalUsed = totalInput + totalOutput;
+      if (totalUsed >= TOKEN_HARD_STOP) {
+        return {
+          text: response.text || "[Session stopped: token budget exceeded]",
+          totalInputTokens: totalInput,
+          totalOutputTokens: totalOutput,
+          aborted: true
+        };
+      }
+      if (totalUsed >= TOKEN_WARN) {
+        onTokenWarning?.(totalUsed);
+      }
+      if (response.stopReason !== "tool_use" || response.toolCalls.length === 0) {
+        return {
+          text: response.text,
+          totalInputTokens: totalInput,
+          totalOutputTokens: totalOutput,
+          aborted: false
+        };
+      }
+      messages.push({ role: "assistant", content: response.text || "[tool use]" });
+      for (const tc of response.toolCalls) {
+        const result = await executeToolCall(tc.name, tc.input, scannedItems);
+        messages.push({
+          role: "user",
+          content: `Tool result for ${tc.name} (id: ${tc.id}):
+${JSON.stringify(result, null, 2)}`
+        });
+      }
+    }
+    return {
+      text: "[Session ended: max iterations reached]",
+      totalInputTokens: totalInput,
+      totalOutputTokens: totalOutput,
+      aborted: true
+    };
+  }
+};
+function buildPrivacyPreview(providerName, scanRoot, items) {
+  const itemCount = items?.length ?? 0;
+  return {
+    providerName,
+    isLocal: false,
+    dataIncluded: [
+      `Scan root path: ${scanRoot}`,
+      ...itemCount > 0 ? [`${itemCount} cleanable item paths (names only, no file contents)`] : [],
+      "Project types detected (node, python, rust, etc.)",
+      "Item sizes and risk tiers"
+    ],
+    dataExcluded: [
+      "File contents",
+      "Source code",
+      "Environment variables",
+      "API keys or secrets",
+      "Git history"
+    ],
+    estimatedTokens: 500 + itemCount * 30
+  };
+}
+
+// src/provider-factory.ts
+var PROVIDER_NAMES = [
+  "anthropic",
+  "openai",
+  "gemini",
+  "groq",
+  "mistral",
+  "openrouter",
+  "ollama"
+];
+var DEFAULT_MODELS = {
+  anthropic: "claude-opus-4-7",
+  openai: "gpt-4o",
+  gemini: "gemini-2.5-pro",
+  groq: "llama-3.3-70b-versatile",
+  mistral: "mistral-large-latest",
+  openrouter: "google/gemini-2.5-pro",
+  ollama: "llama3.2"
+};
+var KEYTAR_SERVICE = "shed-ai";
+async function getStoredApiKey(provider) {
+  try {
+    const { default: keytar } = await import("keytar");
+    return await keytar.getPassword(KEYTAR_SERVICE, provider);
+  } catch {
+    return process.env[`SHED_${provider.toUpperCase()}_API_KEY`] ?? null;
+  }
+}
+async function setStoredApiKey(provider, key) {
+  try {
+    const { default: keytar } = await import("keytar");
+    await keytar.setPassword(KEYTAR_SERVICE, provider, key);
+  } catch {
+    throw new Error(
+      `Could not store API key in keychain. Set SHED_${provider.toUpperCase()}_API_KEY env var instead.`
+    );
+  }
+}
+async function deleteStoredApiKey(provider) {
+  try {
+    const { default: keytar } = await import("keytar");
+    await keytar.deletePassword(KEYTAR_SERVICE, provider);
+  } catch {
+  }
+}
+async function createProvider(options) {
+  const { provider, model } = options;
+  if (provider === "ollama") {
+    return new OllamaProvider(model ?? DEFAULT_MODELS.ollama, options.ollamaEndpoint);
+  }
+  const apiKey = options.apiKey ?? await getStoredApiKey(provider) ?? process.env[`SHED_${provider.toUpperCase()}_API_KEY`];
+  if (!apiKey) {
+    throw new Error(
+      `No API key found for provider "${provider}". Run: shed config set-key ${provider}
+Or set env var: SHED_${provider.toUpperCase()}_API_KEY`
+    );
+  }
+  const m = model ?? DEFAULT_MODELS[provider];
+  switch (provider) {
+    case "anthropic":
+      return new AnthropicProvider(apiKey, m);
+    case "openai":
+      return new OpenAIProvider(apiKey, m);
+    case "gemini":
+      return new GeminiProvider(apiKey, m);
+    case "groq":
+      return new GroqProvider(apiKey, m);
+    case "mistral":
+      return new MistralProvider(apiKey, m);
+    case "openrouter":
+      return new OpenRouterProvider(apiKey, m);
+  }
+}
+export {
+  ALL_TOOLS,
+  AnthropicProvider,
+  DEFAULT_MODELS,
+  ExplainSession,
+  GeminiProvider,
+  GroqProvider,
+  MistralProvider,
+  OllamaProvider,
+  OpenAICompatibleProvider,
+  OpenAIProvider,
+  OpenRouterProvider,
+  PROVIDER_NAMES,
+  TOOLS,
+  createProvider,
+  deleteStoredApiKey,
+  executeToolCall,
+  getStoredApiKey,
+  setStoredApiKey
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@lexmanh/shed-agent",
+  "version": "0.2.0-beta.1",
+  "description": "AI provider abstraction for Shed — supports Anthropic, OpenAI, Gemini, Groq, Mistral, OpenRouter, and Ollama",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.32.0",
+    "@google/genai": "^1.50.1",
+    "execa": "^9.5.0",
+    "keytar": "^7.9.0",
+    "openai": "^4.77.0",
+    "@lexmanh/shed-core": "0.2.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}