spidersan 0.6.0 → 0.10.0

package/dist/lib/ai/event-handler.js

@@ -0,0 +1,98 @@
+/**
+ * Spidersan AI Core — Event Handler
+ *
+ * Processes git/colony events → deterministic conflict check → optional LLM escalation.
+ * Pure functions — no CLI or server concerns.
+ */
+import { reason } from './reasoner.js';
+import { buildContext } from './context-builder.js';
+import { classifyTier } from '../conflict-tier.js';
+// ─── Deterministic Conflict Check ───────────────────────────
+function checkDeterministicConflicts(event, context) {
+    if (!event.files || event.files.length === 0)
+        return null;
+    // Find overlapping files with registered branches
+    const overlaps = [];
+    // Pre-compute event files as Set for O(1) lookups
+    const eventFilesSet = new Set(event.files);
+    for (const branch of context.registry.branches) {
+        if (branch.name === event.branch)
+            continue;
+        if (branch.status !== 'active')
+            continue;
+        for (const file of branch.files) {
+            if (eventFilesSet.has(file)) {
+                overlaps.push({ branch: branch.name, file, tier: classifyTier(file) });
+            }
+        }
+    }
+    if (overlaps.length === 0)
+        return null;
+    const maxTier = Math.max(...overlaps.map(o => o.tier));
+    const tierActions = {
+        3: { action: 'block', label: 'BLOCK' },
+        2: { action: 'pause', label: 'PAUSE' },
+        1: { action: 'warn', label: 'WARN' },
+    };
+    const { action, label } = tierActions[maxTier];
+    const affectedBranches = [...new Set(overlaps.map(o => o.branch))];
+    const affectedFiles = [...new Set(overlaps.map(o => o.file))];
+    const commands = ['spidersan conflicts --json'];
+    if (maxTier >= 2)
+        commands.push('spidersan conflicts --wake');
+    if (maxTier >= 3)
+        commands.push('spidersan conflicts --strict');
+    return {
+        tier: maxTier,
+        action,
+        message: `🕷️ TIER ${maxTier} ${label}: ${event.branch ?? 'unknown'} overlaps with ${affectedBranches.join(', ')} on ${affectedFiles.join(', ')}`,
+        commands,
+        escalateToLLM: maxTier >= 2,
+    };
+}
+// ─── Main Event Handler ────────────────────────────────────
+/**
+ * Handle an event (push, PR, colony signal, branch register).
+ * First runs deterministic conflict check (fast, no LLM).
+ * Only escalates to LLM for TIER 2+ or complex scenarios.
+ *
+ * @param opts.repoRoot - Local repo path for context building. Defaults to process.cwd().
+ * @param opts.localOnly - If true, LLM escalation uses local providers only (never hosted/copilot).
+ *                         Use this for daemon/webhook paths to avoid consuming remote API credits.
+ */
+export async function handleEvent(event, opts = {}) {
+    const context = await buildContext({ includeActivity: true, repoRoot: opts.repoRoot });
+    // Fast path: deterministic conflict check
+    const deterministicAdvice = checkDeterministicConflicts(event, context);
+    if (deterministicAdvice && !deterministicAdvice.escalateToLLM) {
+        return deterministicAdvice;
+    }
+    // Slow path: LLM reasoning for TIER 2+ or ambiguous situations
+    if (deterministicAdvice?.escalateToLLM) {
+        try {
+            const result = await reason({
+                mode: 'ask',
+                question: `Event: ${event.type} on branch ${event.branch ?? 'unknown'} touching files [${(event.files ?? []).join(', ')}]. ${deterministicAdvice.message}. What should the agents do?`,
+                context,
+            }, { allowRemoteFallback: opts.localOnly ? false : undefined });
+            return {
+                ...deterministicAdvice,
+                message: result.advice,
+                commands: result.commands.length > 0 ? result.commands : deterministicAdvice.commands,
+            };
+        }
+        catch {
+            // LLM failed — return deterministic advice as fallback
+            return deterministicAdvice;
+        }
+    }
+    // No conflicts detected
+    return {
+        tier: 0,
+        action: 'info',
+        message: `✅ ${event.type} on ${event.branch ?? 'unknown'}: no conflicts detected.`,
+        commands: [],
+        escalateToLLM: false,
+    };
+}
+//# sourceMappingURL=event-handler.js.map

package/dist/lib/ai/event-handler.js.map

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

package/dist/lib/ai/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Spidersan AI Core — Public API
+ *
+ * Shared library for CLI (ask/advise/explain), MCP tools, webhook, and agent mode.
+ */
+export { buildContext } from './context-builder.js';
+export type { BuildContextOptions } from './context-builder.js';
+export { chat, ping, resolveConfig } from './llm-client.js';
+export { reason } from './reasoner.js';
+export { handleEvent } from './event-handler.js';
+export type { Advice, AIConfig, ActivityEntry, BranchSummary, ConflictSummary, DailyEntry, EventPayload, EventType, LLMConfig, LLMMessage, LLMProvider, LLMResponse, ReasoningMode, ReasoningRequest, ReasoningResult, SpiderContext, WorkSignal, } from './types.js';
+export { DEFAULT_LLM_CONFIGS } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/ai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/ai/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,YAAY,EACV,MAAM,EACN,QAAQ,EACR,aAAa,EACb,aAAa,EACb,eAAe,EACf,UAAU,EACV,YAAY,EACZ,SAAS,EACT,SAAS,EACT,UAAU,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/lib/ai/index.js

@@ -0,0 +1,11 @@
+/**
+ * Spidersan AI Core — Public API
+ *
+ * Shared library for CLI (ask/advise/explain), MCP tools, webhook, and agent mode.
+ */
+export { buildContext } from './context-builder.js';
+export { chat, ping, resolveConfig } from './llm-client.js';
+export { reason } from './reasoner.js';
+export { handleEvent } from './event-handler.js';
+export { DEFAULT_LLM_CONFIGS } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/lib/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/ai/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGpD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAsBjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/lib/ai/llm-client.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Spidersan AI Core — LLM Client
+ *
+ * Unified interface for LLM providers with automatic fallback chain:
+ * LM Studio (Gemma 4) → Ollama → Hosted API (api.spidersan.net) → GitHub Copilot
+ *
+ * Tier routing (auto, no explicit provider):
+ *   Tier 1: localhost:1234 / :8082 (lmstudio)
+ *   Tier 2: localhost:11434 (ollama)
+ *   Tier 3: api.spidersan.net (hosted) — requires API key
+ *   Remote: copilot — only with allowRemoteFallback or explicit config
+ */
+import type { LLMConfig, LLMMessage, LLMProvider, LLMResponse } from './types.js';
+export declare function resolveConfig(overrides?: Partial<LLMConfig>): LLMConfig;
+/**
+ * Send a chat completion request with automatic fallback.
+ *
+ * Priority order (auto-routing when no explicit provider set):
+ *   1. lmstudio (local)
+ *   2. ollama (local)
+ *   3. hosted (api.spidersan.net) — only if API key available
+ *   4. copilot — only if allowRemoteFallback or explicitly configured
+ */
+export declare function chat(messages: LLMMessage[], configOverrides?: Partial<LLMConfig> & {
+    allowRemoteFallback?: boolean;
+}): Promise<LLMResponse>;
+/**
+ * Quick health check — can we reach the configured provider?
+ */
+export declare function ping(configOverrides?: Partial<LLMConfig>): Promise<{
+    ok: boolean;
+    provider: LLMProvider;
+    model: string;
+    latencyMs: number;
+    error?: string;
+}>;
+//# sourceMappingURL=llm-client.d.ts.map

package/dist/lib/ai/llm-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-client.d.ts","sourceRoot":"","sources":["../../../src/lib/ai/llm-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAMlF,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAYvE;AAyHD;;;;;;;;GAQG;AACH,wBAAsB,IAAI,CACxB,QAAQ,EAAE,UAAU,EAAE,EACtB,eAAe,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG;IAAE,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAE,GACvE,OAAO,CAAC,WAAW,CAAC,CAgEtB;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC;IACxE,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAwBD"}

package/dist/lib/ai/llm-client.js

@@ -0,0 +1,225 @@
+/**
+ * Spidersan AI Core — LLM Client
+ *
+ * Unified interface for LLM providers with automatic fallback chain:
+ * LM Studio (Gemma 4) → Ollama → Hosted API (api.spidersan.net) → GitHub Copilot
+ *
+ * Tier routing (auto, no explicit provider):
+ *   Tier 1: localhost:1234 / :8082 (lmstudio)
+ *   Tier 2: localhost:11434 (ollama)
+ *   Tier 3: api.spidersan.net (hosted) — requires API key
+ *   Remote: copilot — only with allowRemoteFallback or explicit config
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { DEFAULT_LLM_CONFIGS } from './types.js';
+import { loadAiConfig } from './setup.js';
+const execFileAsync = promisify(execFile);
+export function resolveConfig(overrides) {
+    const providerEnv = process.env['SPIDERSAN_LLM'];
+    const provider = overrides?.provider ?? providerEnv ?? 'lmstudio';
+    const base = DEFAULT_LLM_CONFIGS[provider] ?? DEFAULT_LLM_CONFIGS.lmstudio;
+    return {
+        ...base,
+        ...overrides,
+        provider,
+        model: overrides?.model ?? process.env['SPIDERSAN_LLM_MODEL'] ?? base.model,
+        baseUrl: overrides?.baseUrl ?? process.env['SPIDERSAN_LLM_URL'] ?? base.baseUrl,
+    };
+}
+async function getGitHubToken() {
+    try {
+        const { stdout } = await execFileAsync('gh', ['auth', 'token'], { timeout: 5000 });
+        return stdout.trim();
+    }
+    catch {
+        throw new Error('GitHub CLI not authenticated. Run `gh auth login` first.');
+    }
+}
+async function chatOpenAICompatible(config, messages, apiKey) {
+    // Normalize: strip trailing /v1 so we always build the full path ourselves.
+    // Handles both http://host:port (env var form) and http://host:port/v1 (default form).
+    const base = config.baseUrl.replace(/\/v1\/?$/, '');
+    const url = `${base}/v1/chat/completions`;
+    const headers = { 'Content-Type': 'application/json' };
+    if (apiKey)
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    const resp = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+            model: config.model,
+            messages,
+            temperature: config.temperature,
+            max_tokens: config.maxTokens,
+        }),
+        signal: AbortSignal.timeout(60_000),
+    });
+    if (!resp.ok) {
+        const body = await resp.text().catch(() => '');
+        throw new Error(`LLM ${config.provider} returned ${resp.status}: ${body.slice(0, 200)}`);
+    }
+    const data = await resp.json();
+    return {
+        content: data.choices[0]?.message?.content ?? '',
+        model: data.model ?? config.model,
+        provider: config.provider,
+        promptTokens: data.usage?.prompt_tokens ?? 0,
+        completionTokens: data.usage?.completion_tokens ?? 0,
+    };
+}
+async function chatOllama(config, messages) {
+    const url = `${config.baseUrl}/api/chat`;
+    const resp = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            model: config.model,
+            messages,
+            stream: false,
+            options: { temperature: config.temperature, num_predict: config.maxTokens },
+        }),
+        signal: AbortSignal.timeout(120_000),
+    });
+    if (!resp.ok) {
+        throw new Error(`Ollama returned ${resp.status}`);
+    }
+    const data = await resp.json();
+    return {
+        content: data.message?.content ?? '',
+        model: data.model ?? config.model,
+        provider: 'ollama',
+        promptTokens: data.prompt_eval_count ?? 0,
+        completionTokens: data.eval_count ?? 0,
+    };
+}
+async function chatWithProvider(config, messages, apiKey) {
+    switch (config.provider) {
+        case 'lmstudio':
+            return chatOpenAICompatible(config, messages);
+        case 'copilot': {
+            const token = await getGitHubToken();
+            return chatOpenAICompatible(config, messages, token);
+        }
+        case 'ollama':
+            return chatOllama(config, messages);
+        case 'hosted': {
+            const key = apiKey ?? config.apiKey;
+            if (!key)
+                throw new Error('No API key for hosted tier. Run: spidersan ai-setup');
+            return chatOpenAICompatible(config, messages, key);
+        }
+        default:
+            throw new Error(`Unknown LLM provider: ${config.provider}`);
+    }
+}
+// Local-first fallback: never send repo context to remote without opt-in
+const LOCAL_FALLBACK = ['lmstudio', 'ollama'];
+const REMOTE_PROVIDERS = ['hosted', 'copilot'];
+/** Resolve the hosted API key from env var or persisted config. */
+async function resolveHostedApiKey() {
+    const envKey = process.env['SPIDERSAN_API_KEY'];
+    if (envKey)
+        return envKey;
+    const config = await loadAiConfig();
+    return config?.apiKey ?? undefined;
+}
+/**
+ * Send a chat completion request with automatic fallback.
+ *
+ * Priority order (auto-routing when no explicit provider set):
+ *   1. lmstudio (local)
+ *   2. ollama (local)
+ *   3. hosted (api.spidersan.net) — only if API key available
+ *   4. copilot — only if allowRemoteFallback or explicitly configured
+ */
+export async function chat(messages, configOverrides) {
+    const { allowRemoteFallback, ...llmOverrides } = configOverrides ?? {};
+    const config = resolveConfig(llmOverrides);
+    const isRemote = REMOTE_PROVIDERS.includes(config.provider);
+    const errors = [];
+    // Resolve hosted API key once (avoid repeated config reads in fallback loop)
+    const hostedApiKey = await resolveHostedApiKey();
+    // Try configured provider first
+    try {
+        return await chatWithProvider(config, messages, config.provider === 'hosted' ? hostedApiKey : undefined);
+    }
+    catch (err) {
+        errors.push({ provider: config.provider, error: err.message });
+    }
+    // Local fallback chain
+    for (const fallback of LOCAL_FALLBACK) {
+        if (fallback === config.provider)
+            continue;
+        try {
+            const result = await chatWithProvider(DEFAULT_LLM_CONFIGS[fallback], messages);
+            result.provider = fallback;
+            return result;
+        }
+        catch (err) {
+            errors.push({ provider: fallback, error: err.message });
+        }
+    }
+    // Remote fallback: hosted (if key available + tier allows), then copilot (if opted in)
+    //
+    // Tier routing: if the user configured free/contributor tier via ai-setup, hosted is
+    // always a valid fallback when local is unavailable — no explicit allowRemoteFallback needed.
+    const savedConfig = await loadAiConfig();
+    const tierAllowsHosted = savedConfig?.tier === 'free' || savedConfig?.tier === 'contributor';
+    if (allowRemoteFallback || isRemote || tierAllowsHosted) {
+        // hosted — only if we have a key
+        if (config.provider !== 'hosted' && hostedApiKey) {
+            try {
+                const result = await chatWithProvider(DEFAULT_LLM_CONFIGS.hosted, messages, hostedApiKey);
+                result.provider = 'hosted';
+                return result;
+            }
+            catch (err) {
+                errors.push({ provider: 'hosted', error: err.message });
+            }
+        }
+        // copilot — only with explicit allowRemoteFallback (never auto-routed)
+        if (allowRemoteFallback || isRemote) {
+            for (const fallback of ['copilot']) {
+                if (fallback === config.provider)
+                    continue;
+                try {
+                    const result = await chatWithProvider(DEFAULT_LLM_CONFIGS[fallback], messages);
+                    result.provider = fallback;
+                    return result;
+                }
+                catch (err) {
+                    errors.push({ provider: fallback, error: err.message });
+                }
+            }
+        }
+    }
+    const summary = errors.map(e => `  ${e.provider}: ${e.error}`).join('\n');
+    throw new Error(`All LLM providers failed:\n${summary}`);
+}
+/**
+ * Quick health check — can we reach the configured provider?
+ */
+export async function ping(configOverrides) {
+    const config = resolveConfig(configOverrides);
+    const start = Date.now();
+    try {
+        const result = await chat([{ role: 'user', content: 'Reply with just "ok".' }], { ...config, maxTokens: 10 });
+        return {
+            ok: true,
+            provider: result.provider,
+            model: result.model,
+            latencyMs: Date.now() - start,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            provider: config.provider,
+            model: config.model,
+            latencyMs: Date.now() - start,
+            error: err.message,
+        };
+    }
+}
+//# sourceMappingURL=llm-client.js.map

package/dist/lib/ai/llm-client.js.map

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

package/dist/lib/ai/reasoner.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Spidersan AI Core — Reasoner
+ *
+ * Sends SpiderContext + user question to LLM with spidersan-aware system prompt.
+ * The scenario playbook is embedded as a TS constant (no file I/O at runtime).
+ */
+import type { LLMConfig, ReasoningRequest, ReasoningResult } from './types.js';
+export declare function reason(request: ReasoningRequest, llmOverrides?: Partial<LLMConfig> & {
+    allowRemoteFallback?: boolean;
+}): Promise<ReasoningResult>;
+//# sourceMappingURL=reasoner.d.ts.map

package/dist/lib/ai/reasoner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoner.d.ts","sourceRoot":"","sources":["../../../src/lib/ai/reasoner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,SAAS,EAGT,gBAAgB,EAChB,eAAe,EAEhB,MAAM,YAAY,CAAC;AAqMpB,wBAAsB,MAAM,CAC1B,OAAO,EAAE,gBAAgB,EACzB,YAAY,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG;IAAE,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE,OAAO,CAAC,eAAe,CAAC,CAkE1B"}