opena2a-cli 0.1.0 → 0.1.2

package/dist/shield/llm-backend.js

@@ -0,0 +1,145 @@
+"use strict";
+// Shield LLM Backend Abstraction
+//
+// Two backends:
+//   1. Claude Code CLI (primary, zero-config): detects `claude` binary and
+//      uses `claude --print` for completions. No API key required.
+//   2. Anthropic API (secondary): uses ANTHROPIC_API_KEY for direct API calls.
+//
+// Nesting prevention: if $CLAUDECODE is set, we're already inside a Claude
+// Code session and spawning `claude --print` would nest. Fall back to API.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isClaudeCodeAvailable = isClaudeCodeAvailable;
+exports.detectBackend = detectBackend;
+exports.callClaudeCode = callClaudeCode;
+exports.callLlm = callLlm;
+const node_child_process_1 = require("node:child_process");
+const CLAUDE_CODE_TIMEOUT_MS = 30_000;
+// Approximate tokens from text length (used when Claude Code doesn't report exact counts)
+function estimateTokens(text) {
+    // ~4 chars per token is a reasonable approximation
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Check if the Claude Code CLI binary is available and safe to call.
+ *
+ * Returns false if:
+ *   - `which claude` fails (not installed)
+ *   - $CLAUDECODE is set (nesting prevention)
+ */
+function isClaudeCodeAvailable() {
+    // Nesting prevention: if CLAUDECODE env var is set, we're already
+    // inside a Claude Code session. Don't spawn another.
+    if (process.env.CLAUDECODE) {
+        return false;
+    }
+    try {
+        const result = (0, node_child_process_1.execSync)('which claude', {
+            encoding: 'utf-8',
+            timeout: 5_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return result.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detect which LLM backend is available.
+ *
+ * Priority:
+ *   1. Claude Code CLI (zero-config, no API key needed)
+ *   2. Anthropic API (requires ANTHROPIC_API_KEY + consent)
+ *   3. None
+ */
+async function detectBackend() {
+    // 1. Try Claude Code CLI
+    if (isClaudeCodeAvailable()) {
+        return { backend: 'claude-code' };
+    }
+    // 2. Try Anthropic API
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (apiKey) {
+        // Check consent via @opena2a/shared
+        try {
+            const shared = await import('@opena2a/shared');
+            const mod = 'default' in shared ? shared.default : shared;
+            if (!mod.isLlmEnabled()) {
+                return { backend: 'none' };
+            }
+        }
+        catch {
+            // shared not available -- allow (backward compat)
+        }
+        return { backend: 'api', apiKey };
+    }
+    return { backend: 'none' };
+}
+/**
+ * Call the Claude Code CLI as an LLM backend.
+ *
+ * Uses `claude --print` with JSON output format and Haiku model
+ * for cost-efficient, fast completions.
+ */
+function callClaudeCode(systemPrompt, userPrompt, _maxTokens) {
+    try {
+        const result = (0, node_child_process_1.execFileSync)('claude', [
+            '--print',
+            '--output-format', 'json',
+            '--model', 'haiku',
+            '--max-turns', '1',
+            '--no-session-persistence',
+            '--system-prompt', systemPrompt,
+            userPrompt,
+        ], {
+            encoding: 'utf-8',
+            timeout: CLAUDE_CODE_TIMEOUT_MS,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env },
+        });
+        // Parse JSON output from claude --print --output-format json
+        const parsed = JSON.parse(result);
+        const text = parsed.result ?? '';
+        if (!text)
+            return null;
+        return {
+            text,
+            inputTokens: estimateTokens(systemPrompt + userPrompt),
+            outputTokens: estimateTokens(text),
+            backend: 'claude-code',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Unified LLM call interface.
+ *
+ * Routes to Claude Code CLI or Anthropic API based on detected backend.
+ * Returns null if no backend is available or the call fails.
+ */
+async function callLlm(systemPrompt, userPrompt, maxTokens) {
+    const { backend, apiKey } = await detectBackend();
+    if (backend === 'none')
+        return null;
+    if (backend === 'claude-code') {
+        return callClaudeCode(systemPrompt, userPrompt, maxTokens);
+    }
+    // API backend -- use callHaiku (imported lazily to avoid circular deps)
+    if (backend === 'api' && apiKey) {
+        const { callHaiku } = await import('./llm.js');
+        const result = await callHaiku(systemPrompt, userPrompt, maxTokens, apiKey);
+        if (!result)
+            return null;
+        return {
+            text: result.text,
+            inputTokens: result.inputTokens,
+            outputTokens: result.outputTokens,
+            backend: 'api',
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=llm-backend.js.map

package/dist/shield/llm-backend.js.map

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

package/dist/shield/llm.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Shield LLM Intelligence Layer
+ *
+ * Uses Claude Haiku for lightweight, cost-efficient security analysis:
+ *   1. Policy suggestions from observed agent behavior
+ *   2. Anomaly explanations for unusual actions
+ *   3. Weekly report narrative generation
+ *   4. Incident triage and severity classification
+ *
+ * Design principles:
+ *   - Batch processing: aggregate events, analyze in bulk (not per-event)
+ *   - Aggressive caching: file-based cache with TTLs per analysis type
+ *   - Graceful degradation: returns null if no API key or no consent
+ *   - Cost target: <$1/month at typical usage (~$0.40/month estimated)
+ *   - Zero network by default: only calls API when LLM is explicitly enabled
+ */
+import type { AnomalyExplanation, IncidentTriage, LlmAnalysisType, LlmBackend, LlmCache, LlmCacheEntry, PolicySuggestion, ReportNarrative, ShieldEvent, WeeklyReport } from './types.js';
+/** Load the LLM response cache from disk. Verifies signature integrity first. */
+export declare function loadCache(): LlmCache;
+/** Save the cache to disk, pruning expired entries. Re-signs the cache file. */
+export declare function saveCache(cache: LlmCache): void;
+/** Compute a cache key from input data. */
+export declare function cacheKey(analysisType: LlmAnalysisType, input: string): string;
+/** Look up a cached result. Returns null if not found or expired. */
+export declare function getCached(cache: LlmCache, key: string): LlmCacheEntry | null;
+/**
+ * Make a single API call to Claude Haiku.
+ * Returns the text response and token usage, or null on failure.
+ */
+export declare function callHaiku(systemPrompt: string, userPrompt: string, maxTokens: number, apiKey: string): Promise<{
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+} | null>;
+/**
+ * Check if LLM intelligence is available.
+ *
+ * Priority:
+ *   1. Claude Code CLI (zero-config, no API key needed)
+ *   2. Anthropic API (requires ANTHROPIC_API_KEY + consent)
+ *   3. None
+ *
+ * Returns the detected backend and optional API key.
+ */
+export declare function checkLlmAvailable(): Promise<{
+    backend: LlmBackend;
+    apiKey?: string;
+}>;
+/**
+ * Analyze observed agent behavior and suggest a security policy.
+ *
+ * Input: summarized event data (not raw events -- pre-aggregated to save tokens).
+ */
+export declare function suggestPolicy(agent: string, behaviorSummary: {
+    totalActions: number;
+    totalSessions: number;
+    topProcesses: {
+        name: string;
+        count: number;
+    }[];
+    topCredentials: {
+        name: string;
+        count: number;
+    }[];
+    topFilePaths: {
+        path: string;
+        count: number;
+    }[];
+    topNetworkHosts: {
+        host: string;
+        count: number;
+    }[];
+}): Promise<PolicySuggestion | null>;
+/**
+ * Explain why a specific event or action is anomalous.
+ *
+ * Designed for batch use: call with a few flagged events, not every event.
+ */
+export declare function explainAnomaly(event: ShieldEvent, context: {
+    agentName: string;
+    normalActions: string[];
+    isFirstOccurrence: boolean;
+}): Promise<AnomalyExplanation | null>;
+/**
+ * Generate a human-readable narrative for a weekly report.
+ *
+ * Input: pre-computed report metrics (not raw events).
+ */
+export declare function generateNarrative(report: WeeklyReport): Promise<ReportNarrative | null>;
+/**
+ * Triage a batch of related events as a potential incident.
+ *
+ * Input: a small batch of related high-severity events.
+ */
+export declare function triageIncident(events: ShieldEvent[], context: {
+    policyMode: string;
+    agentName: string;
+    recentBaseline: string[];
+}): Promise<IncidentTriage | null>;
+export interface LlmCacheStats {
+    totalEntries: number;
+    validEntries: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    estimatedCostUsd: number;
+    byType: Record<LlmAnalysisType, number>;
+}
+/**
+ * Compute cache statistics for diagnostics.
+ *
+ * Estimated cost uses Haiku pricing:
+ *   Input: $0.80 per million tokens
+ *   Output: $4.00 per million tokens
+ */
+export declare function getCacheStats(): LlmCacheStats;
+//# sourceMappingURL=llm.d.ts.map

package/dist/shield/llm.d.ts.map

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