network-ai 5.13.4 → 5.15.0

package/dist/lib/claude-hooks.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * Claude Code Hooks Bridge — AuthGuardian-gated tool calls for coding agents.
+ *
+ * Claude Code (and other hook-capable agent CLIs) can call an external
+ * command on every tool use (PreToolUse / PostToolUse hooks). This module
+ * turns Network-AI into that command: every tool call an agent makes is
+ * audited — and optionally permission-gated — through the same
+ * `AuthGuardian` weighted scoring used for swarm agents (justification 40%,
+ * trust 30%, risk 30%).
+ *
+ * Two modes:
+ * - `'observe'` (default) — every tool call is audit-logged, nothing is
+ *   blocked. Zero-risk visibility into what the agent is doing.
+ * - `'enforce'` — tool calls are mapped to Network-AI resource types
+ *   (Bash → SHELL_EXEC, Write/Edit → FILE_SYSTEM, WebFetch →
+ *   EXTERNAL_SERVICE, …) and must pass `AuthGuardian.requestPermission()`.
+ *   Denied calls return `'ask'` (escalate to the human) or `'deny'`.
+ *
+ * Wire-up (Claude Code `settings.json`):
+ * ```json
+ * {
+ *   "hooks": {
+ *     "PreToolUse": [{
+ *       "matcher": "Bash|Write|Edit|WebFetch",
+ *       "hooks": [{ "type": "command",
+ *                   "command": "npx -y -p network-ai network-ai hook pre-tool-use --mode enforce" }]
+ *     }]
+ *   }
+ * }
+ * ```
+ * See `examples/claude-code-hooks.json` for a complete config.
+ *
+ * @module ClaudeHooks
+ * @version 1.0.0
+ */
+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.ClaudeHookBridge = exports.DEFAULT_TOOL_RESOURCE_MAP = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const auth_guardian_1 = require("./auth-guardian");
+// ============================================================================
+// DEFAULTS
+// ============================================================================
+/**
+ * Default mapping from Claude Code tool names to Network-AI resource types.
+ * MCP tools (`mcp__*`) and unknown tools map to EXTERNAL_SERVICE.
+ */
+exports.DEFAULT_TOOL_RESOURCE_MAP = {
+    Bash: 'SHELL_EXEC',
+    BashOutput: 'SHELL_EXEC',
+    KillShell: 'SHELL_EXEC',
+    Write: 'FILE_SYSTEM',
+    Edit: 'FILE_SYSTEM',
+    MultiEdit: 'FILE_SYSTEM',
+    NotebookEdit: 'FILE_SYSTEM',
+    Read: 'FILE_SYSTEM',
+    Glob: 'FILE_SYSTEM',
+    Grep: 'FILE_SYSTEM',
+    WebFetch: 'EXTERNAL_SERVICE',
+    WebSearch: 'EXTERNAL_SERVICE',
+    Task: 'EXTERNAL_SERVICE',
+};
+/** Justification templates per resource type — phrased to carry the
+ *  resource-relevant context AuthGuardian's scorer checks for. */
+const JUSTIFICATION_TEMPLATES = {
+    SHELL_EXEC: (tool, target) => `Execute shell command via ${tool} in order to complete the current coding task: ${target}`,
+    FILE_SYSTEM: (tool, target) => `Access workspace file via ${tool} in order to complete the current coding task: ${target}`,
+    GIT: (tool, target) => `Perform git repository operation via ${tool} in order to complete the current coding task: ${target}`,
+    EXTERNAL_SERVICE: (tool, target) => `Fetch external api endpoint via ${tool} in order to complete the current coding task: ${target}`,
+};
+// ============================================================================
+// HELPERS
+// ============================================================================
+/** Extract the most meaningful target string from a tool input */
+function extractTarget(toolName, toolInput) {
+    if (!toolInput)
+        return toolName;
+    const candidates = ['command', 'file_path', 'filePath', 'path', 'url', 'query', 'pattern', 'prompt'];
+    for (const key of candidates) {
+        const v = toolInput[key];
+        if (typeof v === 'string' && v.length > 0)
+            return v.slice(0, 500);
+    }
+    try {
+        return JSON.stringify(toolInput).slice(0, 300);
+    }
+    catch {
+        return toolName;
+    }
+}
+/** Test a tool name / target against a pattern list */
+function matchesAny(patterns, toolName, target) {
+    if (!patterns || patterns.length === 0)
+        return false;
+    for (const p of patterns) {
+        const re = typeof p === 'string' ? new RegExp(p, 'i') : p;
+        if (re.test(toolName) || re.test(target))
+            return true;
+    }
+    return false;
+}
+// ============================================================================
+// CLAUDE HOOK BRIDGE
+// ============================================================================
+/**
+ * Bridges coding-agent hook events (Claude Code PreToolUse / PostToolUse)
+ * into Network-AI's AuthGuardian permission system and audit trail.
+ */
+class ClaudeHookBridge {
+    guardian;
+    agentId;
+    mode;
+    denyPatterns;
+    allowPatterns;
+    toolResourceMap;
+    blockedDecision;
+    auditLogPath;
+    onAudit;
+    constructor(options = {}) {
+        this.agentId = options.agentId ?? 'claude-code';
+        this.mode = options.mode ?? 'observe';
+        this.denyPatterns = options.denyPatterns ?? [];
+        this.allowPatterns = options.allowPatterns ?? [];
+        this.toolResourceMap = { ...exports.DEFAULT_TOOL_RESOURCE_MAP, ...(options.toolResourceMap ?? {}) };
+        this.blockedDecision = options.blockedDecision ?? 'ask';
+        this.auditLogPath = options.auditLogPath ? path.resolve(options.auditLogPath) : null;
+        this.onAudit = options.onAudit ?? null;
+        if (options.guardian) {
+            this.guardian = options.guardian;
+        }
+        else if (this.mode === 'enforce') {
+            // Auto-create a guardian with a trust identity for this agent.
+            this.guardian = new auth_guardian_1.AuthGuardian({
+                trustLevels: [{
+                        agentId: this.agentId,
+                        trustLevel: options.trustLevel ?? 0.7,
+                        allowedNamespaces: ['*'],
+                        allowedResources: ['*'],
+                    }],
+                ...(options.guardianAuditLogPath ? { auditLogPath: options.guardianAuditLogPath } : {}),
+                ...(options.trustConfigPath ? { trustConfigPath: options.trustConfigPath } : {}),
+            });
+        }
+        else {
+            this.guardian = null;
+        }
+    }
+    /**
+     * Parse a raw hook stdin payload. Tolerates a leading UTF-8 BOM (some
+     * shells prepend one when piping). Throws on malformed JSON or a payload
+     * that is not an object.
+     */
+    static parseInput(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.replace(/^\uFEFF/, '').trim());
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new Error(`ClaudeHookBridge: invalid hook input JSON — ${detail}`);
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('ClaudeHookBridge: hook input must be a JSON object');
+        }
+        const obj = parsed;
+        if (typeof obj['hook_event_name'] !== 'string') {
+            throw new Error('ClaudeHookBridge: hook input missing hook_event_name');
+        }
+        return obj;
+    }
+    /**
+     * Handle a PreToolUse event: decide allow / deny / ask.
+     *
+     * Decision order: denyPatterns → allowPatterns → observe-mode allow →
+     * AuthGuardian permission request (enforce mode).
+     */
+    async handlePreToolUse(input) {
+        const toolName = input.tool_name ?? 'unknown';
+        const target = extractTarget(toolName, input.tool_input);
+        // 1. Hard deny list
+        if (matchesAny(this.denyPatterns, toolName, target)) {
+            return this.decide(input, toolName, target, 'deny', `Blocked by Network-AI deny pattern (tool: ${toolName})`);
+        }
+        // 2. Explicit allow list
+        if (matchesAny(this.allowPatterns, toolName, target)) {
+            return this.decide(input, toolName, target, 'allow', `Allowed by Network-AI allow pattern (tool: ${toolName})`);
+        }
+        // 3. Observe mode: audit, never block
+        if (this.mode === 'observe' || !this.guardian) {
+            return this.decide(input, toolName, target, 'allow', 'Network-AI observe mode — call audited, not gated');
+        }
+        // 4. Enforce mode: AuthGuardian weighted permission scoring
+        const resourceType = this.toolResourceMap[toolName]
+            ?? (toolName.startsWith('mcp__') ? 'EXTERNAL_SERVICE' : 'EXTERNAL_SERVICE');
+        const template = JUSTIFICATION_TEMPLATES[resourceType] ?? JUSTIFICATION_TEMPLATES['EXTERNAL_SERVICE'];
+        const justification = template(toolName, target);
+        const grant = await this.guardian.requestPermission(this.agentId, resourceType, justification, toolName);
+        if (grant.granted) {
+            return this.decide(input, toolName, target, 'allow', `AuthGuardian granted ${resourceType} (restrictions: ${grant.restrictions.join(', ') || 'none'})`);
+        }
+        return this.decide(input, toolName, target, this.blockedDecision, `AuthGuardian denied ${resourceType}: ${grant.reason ?? 'permission not granted'}`);
+    }
+    /**
+     * Handle a PostToolUse event: audit the completed call. Never blocks.
+     * Returns an empty object (the hook-protocol no-op).
+     */
+    async handlePostToolUse(input) {
+        const toolName = input.tool_name ?? 'unknown';
+        const target = extractTarget(toolName, input.tool_input);
+        this.audit({
+            timestamp: new Date().toISOString(),
+            event: 'PostToolUse',
+            toolName,
+            target,
+            sessionId: input.session_id,
+            agentId: this.agentId,
+            mode: this.mode,
+        });
+        return {};
+    }
+    /**
+     * Dispatch a hook input by its `hook_event_name`.
+     */
+    async handle(input) {
+        if (input.hook_event_name === 'PreToolUse')
+            return this.handlePreToolUse(input);
+        if (input.hook_event_name === 'PostToolUse')
+            return this.handlePostToolUse(input);
+        throw new Error(`ClaudeHookBridge: unsupported hook event "${input.hook_event_name}"`);
+    }
+    // --------------------------------------------------------------------------
+    // Internals
+    // --------------------------------------------------------------------------
+    decide(input, toolName, target, decision, reason) {
+        this.audit({
+            timestamp: new Date().toISOString(),
+            event: 'PreToolUse',
+            toolName,
+            target,
+            decision,
+            reason,
+            sessionId: input.session_id,
+            agentId: this.agentId,
+            mode: this.mode,
+        });
+        return {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: decision,
+                permissionDecisionReason: reason,
+            },
+        };
+    }
+    audit(entry) {
+        try {
+            this.onAudit?.(entry);
+        }
+        catch {
+            /* observer errors must never break the hook */
+        }
+        if (this.auditLogPath) {
+            try {
+                fs.mkdirSync(path.dirname(this.auditLogPath), { recursive: true });
+                fs.appendFileSync(this.auditLogPath, JSON.stringify(entry) + '\n', 'utf8');
+            }
+            catch {
+                /* audit-write failures must never break the hook */
+            }
+        }
+    }
+}
+exports.ClaudeHookBridge = ClaudeHookBridge;
+//# sourceMappingURL=claude-hooks.js.map

package/dist/lib/claude-hooks.js.map

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

package/dist/lib/context-composer.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Context Composer — token-budgeted, relevance-ranked context assembly.
+ *
+ * Agents have large context windows but a much smaller *effective reasoning*
+ * window: irrelevant, stale, or noisy context degrades output quality long
+ * before the hard token limit ("context rot"). This module assembles the
+ * context block for an LLM call from candidate sources (blackboard entries,
+ * project context, memory recall) under a **hard token budget**, ranked by:
+ *
+ *   score = w.relevance × relevance + w.recency × recency + w.affinity × affinity
+ *
+ * - **relevance** — semantic similarity to the task via a pluggable
+ *   {@link SemanticRanker} (BYOE — e.g. wrap `SemanticMemory`), with a
+ *   deterministic lexical-overlap fallback when no ranker is supplied;
+ * - **recency**  — exponential half-life decay on the entry timestamp
+ *   (the same math `EpisodicMemory` uses);
+ * - **affinity** — scope-tag match on the key (same substring semantics as
+ *   `ContextThrottler`).
+ *
+ * Pinned sources (task-critical instructions, Layer-3 project context) are
+ * always included first. Assembly is position-aware by default: the
+ * strongest items are placed at the start *and end* of the block, weakest in
+ * the middle — mitigating "lost in the middle" attention decay.
+ *
+ * The result carries full observability metadata: what was included,
+ * what was excluded and why, token usage, and budget utilization.
+ *
+ * @example
+ * ```ts
+ * const composer = new ContextComposer();
+ * const sources = ContextComposer.fromSnapshot(blackboard.getScopedSnapshot('analyst'));
+ * const pack = await composer.compose(sources, {
+ *   task: 'Summarize Q3 revenue anomalies',
+ *   budgetTokens: 2000,
+ *   scopeTags: ['analytics', 'task'],
+ * });
+ * llmPrompt = `${instructions}\n\n${pack.text}`;
+ * ```
+ *
+ * @module ContextComposer
+ * @version 1.0.0
+ */
+/**
+ * Estimate the token count of a text without a tokenizer dependency.
+ *
+ * Uses the ~4-characters-per-token heuristic blended with a word count
+ * (English prose averages ~0.75 tokens/word; code and JSON run denser).
+ * Accurate to roughly ±15% across prose/code/JSON — sufficient for budget
+ * enforcement, not for billing.
+ */
+export declare function estimateTokens(text: string): number;
+/** One candidate context item offered to the composer. */
+export interface ContextSource {
+    /** Unique identifier (blackboard key, memory id, …) */
+    key: string;
+    /** Rendered text content of this item */
+    text: string;
+    /** Agent that produced the item, when known */
+    sourceAgent?: string;
+    /** ISO timestamp of the item, when known (drives recency decay) */
+    timestamp?: string;
+    /** TTL in seconds (`null`/`undefined` = no expiry) — expired items are dropped */
+    ttl?: number | null;
+    /** Pinned items bypass ranking and are always included first (budget permitting) */
+    pinned?: boolean;
+}
+/** A source annotated with its ranking scores. */
+export interface RankedContextItem extends ContextSource {
+    /** Semantic (or lexical-fallback) relevance to the task, 0–1 */
+    relevance: number;
+    /** Recency after half-life decay, 0–1 */
+    recency: number;
+    /** Scope-tag affinity, 0–1 */
+    affinity: number;
+    /** Weighted total score, 0–1 */
+    score: number;
+    /** Estimated token cost of this item's rendered block */
+    tokens: number;
+}
+/** Why an item was left out of the composed pack. */
+export type ExclusionReason = 'budget' | 'score' | 'stale' | 'empty';
+/** An excluded item and the reason it was dropped. */
+export interface ExcludedItem {
+    key: string;
+    reason: ExclusionReason;
+    score?: number;
+}
+/**
+ * Pluggable semantic ranker: given the task text and candidate items,
+ * return a map of key → similarity score (0–1). Missing keys fall back to
+ * lexical scoring. BYOE — bring your own embeddings.
+ */
+export type SemanticRanker = (query: string, items: ReadonlyArray<{
+    key: string;
+    text: string;
+}>) => Promise<Map<string, number>>;
+/** Scoring weights (normalized internally; defaults: 0.5 / 0.3 / 0.2). */
+export interface ScoreWeights {
+    relevance?: number;
+    recency?: number;
+    affinity?: number;
+}
+/** Options for a single {@link ContextComposer.compose} call. */
+export interface ComposeOptions {
+    /** The task/query driving relevance ranking (required) */
+    task: string;
+    /** Hard token budget for the entire composed block (required, > 0) */
+    budgetTokens: number;
+    /** Scope tags for affinity scoring (ContextThrottler semantics: substring match on key) */
+    scopeTags?: string[];
+    /** Score weights — merged over the composer defaults */
+    weights?: ScoreWeights;
+    /** Recency half-life in ms (default: composer default, 30 min) */
+    halfLifeMs?: number;
+    /** Items scoring below this are excluded outright (default 0.05) */
+    minScore?: number;
+    /** Hard cap on the number of included items (0 = unlimited) */
+    maxItems?: number;
+    /** Override the composer-level semantic ranker for this call */
+    ranker?: SemanticRanker;
+    /**
+     * Position-aware assembly (default true): strongest items at the start
+     * AND end of the block, weakest in the middle.
+     */
+    positionAware?: boolean;
+}
+/** The assembled, budget-enforced context pack. */
+export interface ComposedContext {
+    /** Final assembled context block, ready to inject into a prompt */
+    text: string;
+    /** Items included, in ranked order (not layout order) */
+    included: RankedContextItem[];
+    /** Items excluded, with reasons */
+    excluded: ExcludedItem[];
+    /** The budget that was enforced */
+    budgetTokens: number;
+    /** Estimated tokens used by `text` */
+    usedTokens: number;
+    /** usedTokens / budgetTokens (0–1) */
+    utilization: number;
+}
+/** Constructor options for {@link ContextComposer}. */
+export interface ContextComposerOptions {
+    /** Default half-life for recency decay in ms (default: 1_800_000 = 30 min) */
+    halfLifeMs?: number;
+    /** Default scoring weights */
+    weights?: ScoreWeights;
+    /** Default semantic ranker (BYOE) */
+    ranker?: SemanticRanker;
+}
+/** Minimal `SemanticMemory`-compatible search surface. */
+export interface SemanticSearchLike {
+    search(query: string, topK?: number, threshold?: number): Promise<Array<{
+        key: string;
+        score: number;
+    }>>;
+}
+/**
+ * Adapt a `SemanticMemory` instance (or anything with a compatible
+ * `search()`) into a {@link SemanticRanker}. Items the memory does not know
+ * about simply fall back to lexical scoring.
+ */
+export declare function createSemanticMemoryRanker(memory: SemanticSearchLike): SemanticRanker;
+/**
+ * Assembles token-budgeted, relevance-ranked context packs from candidate
+ * sources. See the module docs for the ranking model.
+ */
+export declare class ContextComposer {
+    private readonly halfLifeMs;
+    private readonly weights;
+    private readonly ranker;
+    constructor(options?: ContextComposerOptions);
+    /**
+     * Convert a blackboard snapshot (`getSnapshot()` / `getScopedSnapshot()`
+     * shape) into {@link ContextSource} candidates. Values are rendered as
+     * strings (JSON for objects) and truncated to `maxValueChars`.
+     */
+    static fromSnapshot(snapshot: Record<string, unknown>, options?: {
+        maxValueChars?: number;
+    }): ContextSource[];
+    /**
+     * Rank the candidate sources against the task and assemble the largest
+     * high-signal context block that fits the token budget.
+     */
+    compose(sources: ContextSource[], options: ComposeOptions): Promise<ComposedContext>;
+}
+//# sourceMappingURL=context-composer.d.ts.map

package/dist/lib/context-composer.d.ts.map

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