docorbit 0.1.0 → 0.1.2

package/dist/packages/retrieval/src/recipe-engine.js

@@ -0,0 +1,265 @@
+import { createHash } from 'node:crypto';
+import { RetrievalEngine } from "./engine.js";
+import { resolveProjectContext } from "../../workspace/src/index.js";
+export class RecipeEngine {
+    repository;
+    retrievalEngine;
+    constructor(repository, retrievalEngine) {
+        this.repository = repository;
+        this.retrievalEngine = retrievalEngine || new RetrievalEngine(repository);
+    }
+    /**
+     * Deterministically compiles an implementation recipe grounded strictly in indexed evidence.
+     * Distinguishes documented facts, inferred relationships, and missing information.
+     * Never invents APIs, steps, prerequisites, or validation steps.
+     */
+    async assembleRecipe(goal, options = {}) {
+        const cleanGoal = goal.trim();
+        let effectiveDocVersion = options.docVersion;
+        // Resolve project and version context if projectDir is provided
+        if (options.projectDir) {
+            const projContext = resolveProjectContext(options.projectDir, cleanGoal, this.repository);
+            if (projContext.matchedDependency && !effectiveDocVersion) {
+                effectiveDocVersion = projContext.matchedDependency.targetDocVersion;
+            }
+        }
+        // 1. Query candidate API endpoints, examples, pitfalls, and search chunks
+        const endpoints = this.repository.searchApiEndpoints(cleanGoal, {
+            docVersion: effectiveDocVersion,
+            limit: 10,
+        });
+        const examples = this.repository.searchIndexedExamples(cleanGoal, {
+            docVersion: effectiveDocVersion,
+            limit: 10,
+        });
+        const pitfalls = this.repository.searchPitfalls(cleanGoal, {
+            docVersion: effectiveDocVersion,
+            limit: 10,
+        });
+        const searchResults = await this.retrievalEngine.search(cleanGoal, {
+            docVersion: effectiveDocVersion,
+            limit: 10,
+        });
+        // 2. Collect unique source URLs
+        const sourcesSet = new Set();
+        for (const ep of endpoints) {
+            if (ep.provenance?.sourceUrl)
+                sourcesSet.add(ep.provenance.sourceUrl);
+        }
+        for (const ex of examples) {
+            if (ex.sourceUrl)
+                sourcesSet.add(ex.sourceUrl);
+        }
+        for (const pf of pitfalls) {
+            if (pf.provenance?.sourceUrl)
+                sourcesSet.add(pf.provenance.sourceUrl);
+        }
+        for (const sr of searchResults) {
+            if (sr.chunk.provenance?.sourceUrl)
+                sourcesSet.add(sr.chunk.provenance.sourceUrl);
+        }
+        const sources = Array.from(sourcesSet);
+        // 3. Assemble Prerequisites strictly from documented requirements
+        const prerequisites = [];
+        // Check required_config or permission pitfalls
+        for (const pf of pitfalls) {
+            if (pf.kind === 'required_config' || pf.kind === 'permission') {
+                prerequisites.push({
+                    text: `${pf.title}: ${pf.content}`,
+                    evidenceLevel: 'documented_fact',
+                    sourceUrl: pf.provenance?.sourceUrl,
+                });
+            }
+        }
+        // Check chunks with prerequisite/setup headings (only relevant chunks with score >= 5.0)
+        for (const sr of searchResults.filter(s => s.score >= 5.0)) {
+            const headingText = (sr.chunk.title || sr.chunk.sectionPath.join(' ')).toLowerCase();
+            if (headingText.includes('prerequisite') || headingText.includes('before you begin') || headingText.includes('requirements')) {
+                const textSnippet = sr.chunk.content.split('\n')[0].trim();
+                if (textSnippet && !prerequisites.some(p => p.text === textSnippet)) {
+                    prerequisites.push({
+                        text: textSnippet,
+                        evidenceLevel: 'documented_fact',
+                        sourceUrl: sr.chunk.provenance?.sourceUrl,
+                    });
+                }
+            }
+        }
+        // 4. Assemble Ordered Steps
+        const orderedSteps = [];
+        const usedApis = new Set();
+        const usedExamples = new Set();
+        const usedPitfalls = new Set();
+        let stepNumber = 1;
+        // A. Setup / Client Initialization Step (if documented in examples)
+        const initExample = examples.find(ex => /(?:new\s+\w+|initialize|config(?:ure)?|createClient|express\(\)|FastAPI\()/i.test(ex.code));
+        if (initExample) {
+            orderedSteps.push({
+                step: stepNumber++,
+                title: `Initialize Client / Service (${initExample.framework || initExample.language})`,
+                description: `Configure and initialize client instance as documented in ${initExample.task}`,
+                evidenceLevel: 'documented_fact',
+                exampleCode: initExample.code,
+                sourceUrl: initExample.sourceUrl,
+                sourceChunkIds: initExample.chunkId ? [initExample.chunkId] : undefined,
+            });
+            usedExamples.add(initExample.id);
+        }
+        // B. Primary API Actions (Documented Fact)
+        for (const ep of endpoints) {
+            const apiStr = `${ep.method.toUpperCase()} ${ep.path}`;
+            if (usedApis.has(apiStr))
+                continue;
+            usedApis.add(apiStr);
+            // Find matching code example for this API
+            const matchingEx = examples.find(ex => !usedExamples.has(ex.id) &&
+                (ex.relatedApi === apiStr || ex.code.includes(ep.path) || (ep.operationId && ex.code.includes(ep.operationId))));
+            if (matchingEx)
+                usedExamples.add(matchingEx.id);
+            // Find matching pitfalls for this API
+            const matchingPfs = pitfalls.filter(pf => pf.relatedApi === apiStr ||
+                (ep.deprecated && pf.kind === 'deprecated') ||
+                (pf.kind === 'rate_limit') ||
+                (pf.kind === 'breaking_change'));
+            const stepPitfalls = [];
+            for (const p of matchingPfs) {
+                const pfStr = `[${p.kind}] ${p.title}: ${p.content}`;
+                stepPitfalls.push(pfStr);
+                usedPitfalls.add(pfStr);
+            }
+            // If the endpoint is deprecated, explicitly highlight it in step title/description
+            const depWarning = ep.deprecated ? ' [DEPRECATED]' : '';
+            orderedSteps.push({
+                step: stepNumber++,
+                title: `${apiStr}${depWarning}${ep.summary ? ` - ${ep.summary}` : ''}`,
+                description: ep.description || ep.summary || `Execute documented ${apiStr} request with parameters: ${ep.parameters.map(p => `${p.name}${p.required ? ' (required)' : ''}`).join(', ')}`,
+                evidenceLevel: 'documented_fact',
+                apiEndpoint: apiStr,
+                exampleCode: matchingEx?.code,
+                pitfalls: stepPitfalls.length > 0 ? stepPitfalls : undefined,
+                sourceUrl: ep.provenance?.sourceUrl || matchingEx?.sourceUrl,
+                sourceChunkIds: matchingEx?.chunkId ? [matchingEx.chunkId] : undefined,
+            });
+        }
+        // C. Remaining Code Examples as implementation steps
+        for (const ex of examples) {
+            if (usedExamples.has(ex.id))
+                continue;
+            usedExamples.add(ex.id);
+            const matchingPfs = pitfalls.filter(pf => (ex.relatedApi && pf.relatedApi === ex.relatedApi) ||
+                (ex.relatedSymbol && pf.relatedSymbol === ex.relatedSymbol));
+            const stepPitfalls = matchingPfs.map(p => `[${p.kind}] ${p.title}: ${p.content}`);
+            stepPitfalls.forEach(p => usedPitfalls.add(p));
+            orderedSteps.push({
+                step: stepNumber++,
+                title: ex.task,
+                description: `Implement documented code example for ${ex.task} (${ex.language}${ex.framework ? ` / ${ex.framework}` : ''})`,
+                evidenceLevel: 'documented_fact',
+                apiEndpoint: ex.relatedApi,
+                exampleCode: ex.code,
+                pitfalls: stepPitfalls.length > 0 ? stepPitfalls : undefined,
+                sourceUrl: ex.sourceUrl,
+                sourceChunkIds: ex.chunkId ? [ex.chunkId] : undefined,
+            });
+            if (ex.relatedApi)
+                usedApis.add(ex.relatedApi);
+        }
+        // D. If neither endpoints nor examples existed, check procedural chunks with strong relevance
+        if (orderedSteps.length === 0) {
+            for (const sr of searchResults.filter(s => s.score >= 5.0).slice(0, 3)) {
+                orderedSteps.push({
+                    step: stepNumber++,
+                    title: sr.chunk.title || sr.chunk.sectionPath.join(' > ') || 'Documented Procedure',
+                    description: sr.chunk.content.substring(0, 300),
+                    evidenceLevel: 'inferred_relationship',
+                    sourceUrl: sr.chunk.provenance?.sourceUrl,
+                    sourceChunkIds: [sr.chunk.id],
+                });
+            }
+        }
+        // E. If documentation contains no relevant implementation steps, mark missing_information
+        if (orderedSteps.length === 0) {
+            orderedSteps.push({
+                step: stepNumber++,
+                title: 'Missing Implementation Knowledge',
+                description: `The indexed documentation does not contain documented API endpoints, code examples, or procedures for: "${cleanGoal}".`,
+                evidenceLevel: 'missing_information',
+            });
+        }
+        // 5. Assemble Evidence-Based Validation Steps
+        const validationSteps = [];
+        let valStepNumber = 1;
+        // Validation from API response schemas
+        for (const ep of endpoints) {
+            const okResponse = ep.responseSchema?.['200'] || ep.responseSchema?.['201'];
+            if (okResponse && okResponse.schema) {
+                const props = okResponse.schema.properties ? Object.keys(okResponse.schema.properties) : [];
+                const propsDesc = props.length > 0 ? ` Expected properties: [${props.slice(0, 6).join(', ')}]` : '';
+                const exampleStr = okResponse.example ? JSON.stringify(okResponse.example, null, 2) : undefined;
+                validationSteps.push({
+                    step: valStepNumber++,
+                    description: `Verify ${ep.method.toUpperCase()} ${ep.path} returns HTTP ${okResponse.statusCode}.${propsDesc}`,
+                    evidenceLevel: 'documented_fact',
+                    expectedResponse: exampleStr || (props.length > 0 ? JSON.stringify(props) : undefined),
+                    sourceUrl: ep.provenance?.sourceUrl,
+                });
+            }
+        }
+        // Validation from code examples containing verification/assertion patterns
+        for (const ex of examples) {
+            if (/(?:constructEvent|verifySignature|assert|expect|validate|signature)/i.test(ex.code)) {
+                validationSteps.push({
+                    step: valStepNumber++,
+                    description: `Validate event/data integrity using documented pattern from ${ex.task}`,
+                    evidenceLevel: 'documented_fact',
+                    testPattern: ex.code,
+                    sourceUrl: ex.sourceUrl,
+                });
+            }
+        }
+        // If no validation steps can be derived from evidence, do NOT invent any!
+        if (validationSteps.length === 0) {
+            validationSteps.push({
+                step: 1,
+                description: 'No response schemas, test instructions, or verification assertions are documented for this task.',
+                evidenceLevel: 'missing_information',
+            });
+        }
+        // Collect all pitfalls
+        for (const pf of pitfalls) {
+            const pfStr = `[${pf.kind}] ${pf.title}: ${pf.content}`;
+            usedPitfalls.add(pfStr);
+        }
+        // Calculate confidence score strictly based on evidence
+        let confidence = 0.0;
+        const factSteps = orderedSteps.filter(s => s.evidenceLevel === 'documented_fact').length;
+        const totalSteps = orderedSteps.length;
+        if (totalSteps > 0 && factSteps > 0) {
+            confidence += 0.4 * (factSteps / totalSteps);
+            if (endpoints.length > 0)
+                confidence += 0.3;
+            if (examples.length > 0)
+                confidence += 0.2;
+            if (validationSteps.some(v => v.evidenceLevel === 'documented_fact'))
+                confidence += 0.1;
+        }
+        confidence = Math.min(1.0, Math.round(confidence * 100) / 100);
+        const recipeId = createHash('sha256')
+            .update(`${cleanGoal}:${effectiveDocVersion || 'default'}:${orderedSteps.length}`)
+            .digest('hex')
+            .substring(0, 16);
+        return {
+            id: recipeId,
+            goal: cleanGoal,
+            prerequisites,
+            orderedSteps,
+            requiredApis: Array.from(usedApis),
+            examples: Array.from(usedExamples),
+            pitfalls: Array.from(usedPitfalls),
+            validationSteps,
+            sources,
+            docVersion: effectiveDocVersion,
+            confidence,
+        };
+    }
+}

package/dist/packages/retrieval/src/scorer.d.ts

@@ -0,0 +1,13 @@
+import type { DocumentChunk, SymbolReference, ChunkCode, ScoringWeights, QueryIntent, SourceAuthority, SearchResult } from '../../shared/src/index.ts';
+export interface ScoreCandidateInput {
+    chunk: DocumentChunk;
+    ftsRank: number;
+    symbols: SymbolReference[];
+    codeSnippets: ChunkCode[];
+    query: string;
+    intent: QueryIntent;
+    authority?: SourceAuthority;
+    targetDocVersion?: string;
+    weights: ScoringWeights;
+}
+export declare function scoreChunkCandidate(input: ScoreCandidateInput): SearchResult;

package/dist/packages/retrieval/src/scorer.js

@@ -0,0 +1,110 @@
+export function scoreChunkCandidate(input) {
+    const { chunk, ftsRank, symbols, codeSnippets, query, intent, authority = 'official', targetDocVersion, weights } = input;
+    const matchReasons = [];
+    const queryLower = query.toLowerCase().trim();
+    const queryTokens = queryLower
+        .replace(/[^\w\s-]/g, ' ')
+        .split(/\s+/)
+        .filter(t => t.length > 2);
+    // 1. Base BM25 score from FTS5 (FTS5 rank is negative where smaller = more relevant)
+    const normalizedBm25 = Math.max(0.1, -ftsRank);
+    let totalScore = normalizedBm25 * weights.bm25Weight;
+    matchReasons.push(`BM25 base (${normalizedBm25.toFixed(2)})`);
+    // 2. Exact phrase match in content
+    if (chunk.content.toLowerCase().includes(queryLower)) {
+        totalScore += weights.exactPhraseBonus;
+        matchReasons.push(`Exact phrase match (+${weights.exactPhraseBonus})`);
+    }
+    // 3. Title match
+    const titleLower = (chunk.title || '').toLowerCase();
+    const titleMatches = queryTokens.filter(t => titleLower.includes(t));
+    if (titleMatches.length > 0) {
+        const boost = weights.titleBonus * (titleMatches.length / queryTokens.length);
+        totalScore += boost;
+        matchReasons.push(`Title match [${titleMatches.join(', ')}] (+${boost.toFixed(1)})`);
+    }
+    // 4. Section path match
+    const pathString = chunk.sectionPath.join(' ').toLowerCase();
+    const pathMatches = queryTokens.filter(t => pathString.includes(t));
+    if (pathMatches.length > 0) {
+        const boost = weights.sectionPathBonus * (pathMatches.length / queryTokens.length);
+        totalScore += boost;
+        matchReasons.push(`Section breadcrumbs match [${pathMatches.join(', ')}] (+${boost.toFixed(1)})`);
+    }
+    // 5. Symbol match (shallow deterministic regex symbols)
+    const matchedSymbols = symbols.filter(s => {
+        const symLower = s.name.toLowerCase();
+        return queryLower.includes(symLower) || symLower.includes(queryLower);
+    });
+    if (matchedSymbols.length > 0) {
+        totalScore += weights.symbolMatchBonus;
+        matchReasons.push(`Symbol match [${matchedSymbols.map(s => s.name).join(', ')}] (+${weights.symbolMatchBonus})`);
+    }
+    // 6. Query intent alignment
+    let intentBoost = 0;
+    if (intent === 'api' && chunk.chunkType === 'api') {
+        intentBoost = weights.intentTypeBonus;
+    }
+    else if (intent === 'examples' && (chunk.chunkType === 'example' || chunk.chunkType === 'code')) {
+        intentBoost = weights.intentTypeBonus;
+    }
+    else if (intent === 'troubleshooting' && (chunk.chunkType === 'warning' || /error|exception|fail|status|code/i.test(chunk.content))) {
+        intentBoost = weights.intentTypeBonus;
+    }
+    else if (intent === 'implementation' && (chunk.chunkType === 'mixed' || chunk.chunkType === 'example')) {
+        intentBoost = weights.intentTypeBonus;
+    }
+    else if (intent === 'conceptual' && chunk.chunkType === 'prose') {
+        intentBoost = weights.intentTypeBonus;
+    }
+    else if (intent === 'configuration' && (symbols.some(s => s.kind === 'config') || chunk.chunkType === 'prose')) {
+        intentBoost = weights.intentTypeBonus;
+    }
+    if (intentBoost > 0) {
+        totalScore += intentBoost;
+        matchReasons.push(`Intent alignment '${intent}' for chunkType '${chunk.chunkType}' (+${intentBoost})`);
+    }
+    // 7. Documentation version boosting & nuance
+    if (targetDocVersion && chunk.docVersion) {
+        const chunkVerClean = chunk.docVersion.replace(/^[v=]/, '');
+        const targetVerClean = targetDocVersion.replace(/^[v=]/, '');
+        const chunkMajor = chunkVerClean.split('.')[0];
+        const targetMajor = targetVerClean.split('.')[0];
+        if (chunkVerClean === targetVerClean || chunk.docVersion === targetDocVersion) {
+            // Exact version match
+            totalScore += weights.versionBonus;
+            matchReasons.push(`Target doc version exact match [${chunk.docVersion}] (+${weights.versionBonus})`);
+        }
+        else if (chunkMajor === targetMajor) {
+            // Same major version (e.g. target 14.2.3, chunk v14 or 14.1)
+            const majorBoost = weights.versionBonus * 0.85;
+            totalScore += majorBoost;
+            matchReasons.push(`Target doc major match [${chunk.docVersion}] (+${majorBoost.toFixed(1)})`);
+        }
+        else if (chunk.docVersion === 'latest' ||
+            chunk.docVersion === 'stable' ||
+            chunk.docVersion === 'current') {
+            // Unversioned / latest documentation: neutral supplemental context
+            matchReasons.push(`Supplemental unversioned/latest documentation [${chunk.docVersion}]`);
+        }
+        else {
+            // Evidence of major version incompatibility (e.g. target v14 vs chunk v16)
+            const penalty = weights.versionBonus * 0.5;
+            totalScore -= penalty;
+            matchReasons.push(`Version major discrepancy [chunk ${chunk.docVersion} vs target ${targetDocVersion}] (-${penalty.toFixed(1)})`);
+        }
+    }
+    // 8. Authority weighting
+    const authMultiplier = weights.authorityWeights[authority] ?? 1.0;
+    totalScore *= authMultiplier;
+    if (authMultiplier !== 1.0) {
+        matchReasons.push(`Authority weighting: x${authMultiplier}`);
+    }
+    return {
+        chunk,
+        score: parseFloat(totalScore.toFixed(3)),
+        matchReasons,
+        symbols,
+        codeSnippets,
+    };
+}

package/dist/packages/retrieval/src/weights.d.ts

@@ -0,0 +1,3 @@
+import type { ScoringWeights } from '../../shared/src/index.ts';
+export declare const DEFAULT_SCORING_WEIGHTS_V1: ScoringWeights;
+export declare function resolveScoringWeights(overrides?: Partial<ScoringWeights>): ScoringWeights;

package/dist/packages/retrieval/src/weights.js

@@ -0,0 +1,28 @@
+export const DEFAULT_SCORING_WEIGHTS_V1 = {
+    version: '1.0.0',
+    bm25Weight: 1.0,
+    exactPhraseBonus: 5.0,
+    titleBonus: 8.0,
+    sectionPathBonus: 4.0,
+    symbolMatchBonus: 10.0,
+    intentTypeBonus: 6.0,
+    versionBonus: 12.0,
+    authorityWeights: {
+        official: 1.0,
+        community: 0.8,
+        third_party: 0.6,
+    },
+};
+export function resolveScoringWeights(overrides) {
+    if (!overrides) {
+        return { ...DEFAULT_SCORING_WEIGHTS_V1 };
+    }
+    return {
+        ...DEFAULT_SCORING_WEIGHTS_V1,
+        ...overrides,
+        authorityWeights: {
+            ...DEFAULT_SCORING_WEIGHTS_V1.authorityWeights,
+            ...(overrides.authorityWeights || {}),
+        },
+    };
+}

package/dist/packages/security/src/annotations.d.ts

@@ -0,0 +1,10 @@
+import type { SecurityAnnotation } from '../../shared/src/index.ts';
+/**
+ * Scans documentation content for security hazards (prompt injection,
+ * malicious execution snippets, unsafe links, credential harvesting) and returns
+ * non-destructive annotations.
+ *
+ * Principle: External documentation is treated as untrusted data and structurally
+ * separated from agent instructions. Original documentation text is never altered.
+ */
+export declare function detectSecurityAnnotations(content: string): SecurityAnnotation[];

package/dist/packages/security/src/annotations.js

@@ -0,0 +1,100 @@
+const MULTILINE_INJECTION_PATTERNS = [
+    { pattern: /<system\b[^>]*>([\s\S]*?)<\/system>/gi, severity: 'high', label: '<system> block' },
+    { pattern: /\[SYSTEM(?:\s+INSTRUCTION)?\]([\s\S]*?)\[\/SYSTEM(?:\s+INSTRUCTION)?\]/gi, severity: 'high', label: '[SYSTEM] block' },
+    { pattern: /<\|im_start\|>system([\s\S]*?)<\|im_end\|>/gi, severity: 'high', label: 'ChatML system block' },
+    { pattern: /<!--\s*AI\s+INSTRUCTION:([\s\S]*?)-->/gi, severity: 'high', label: 'HTML comment injection' },
+];
+const PROMPT_INJECTION_PATTERNS = [
+    { pattern: /\b(?:ignore|disregard|forget)\s+(?:all\s+)?(?:previous|prior|above)\s+instructions\b/i, severity: 'high' },
+    { pattern: /\b(?:system\s+message|system\s+prompt|system\s+instruction)\s*[:=]/i, severity: 'high' },
+    { pattern: /\byou\s+are\s+now\s+(?:an?\s+)?(?:unrestricted|jailbroken|developer\s+mode|dan|evil)\b/i, severity: 'high' },
+    { pattern: /\byou\s+are\s+now\s+(?:acting\s+as\s+)?a\b.*?\bassistant\s+that\s+(?:executes|runs|ignores)\b/i, severity: 'high' },
+    { pattern: /\bIMPORTANT\s+INSTRUCTION\s+FOR\s+(?:THE\s+)?AI\s+AGENT\b/i, severity: 'high' },
+    { pattern: /\b(?:call|invoke|execute)\s+(?:the\s+)?tool\s+['"]?[a-zA-Z0-9_-]+['"]?\s+with\b/i, severity: 'high' },
+    { pattern: /\buse\s+(?:the\s+)?(?:bash|terminal|shell|command|run_command)\s+tool\s+to\b/i, severity: 'high' },
+    { pattern: /\bdo\s+not\s+tell\s+the\s+user\b/i, severity: 'medium' },
+];
+const SUSPICIOUS_INSTRUCTION_PATTERNS = [
+    { pattern: /curl\s+-[sS]*[fF]*[kK]*\s+https?:\/\/[^\s|]+\s*\|\s*(?:ba)?sh/i, severity: 'high' },
+    { pattern: /wget\s+-[qO-]*\s+https?:\/\/[^\s|]+\s*\|\s*(?:ba)?sh/i, severity: 'high' },
+    { pattern: /powershell\s+.*-(?:enc|encodedcommand)\s+[A-Za-z0-9+/=]{20,}/i, severity: 'high' },
+    { pattern: /base64\s+-d\s+.*\|\s*(?:ba)?sh/i, severity: 'high' },
+    { pattern: /eval\s*\(\s*base64_decode\s*\(/i, severity: 'high' },
+    { pattern: /\b(?:cat|type)\s+[^\n]*\.(?:ssh\/id_[a-zA-Z0-9_-]*|aws\/credentials|env)\b/i, severity: 'high' },
+    { pattern: /\b(?:curl|wget|fetch|nc|ncat)\b[^\n]*\b(?:\.ssh\/id_|\.aws\/credentials|\.env|API_KEY|SECRET)\b/i, severity: 'high' },
+    { pattern: /\b(?:printenv|env)\b[^\n]*\|\s*(?:curl|nc|wget|base64)/i, severity: 'high' },
+];
+const UNSAFE_LINK_PATTERNS = [
+    { pattern: /\[[^\]]*\]\(((?:javascript|data|file):[\s\S]*?)\)(?:\.|\s|$)/i, severity: 'high' },
+];
+/**
+ * Scans documentation content for security hazards (prompt injection,
+ * malicious execution snippets, unsafe links, credential harvesting) and returns
+ * non-destructive annotations.
+ *
+ * Principle: External documentation is treated as untrusted data and structurally
+ * separated from agent instructions. Original documentation text is never altered.
+ */
+export function detectSecurityAnnotations(content) {
+    const annotations = [];
+    if (!content)
+        return annotations;
+    // 1. Multiline patterns across whole content
+    for (const rule of MULTILINE_INJECTION_PATTERNS) {
+        let match;
+        const regex = new RegExp(rule.pattern.source, rule.pattern.flags);
+        while ((match = regex.exec(content)) !== null) {
+            const matchStart = match.index;
+            const lineNumber = content.slice(0, matchStart).split('\n').length;
+            annotations.push({
+                type: 'prompt_injection_suspected',
+                location: `Line ${lineNumber} (${rule.label})`,
+                evidence: match[0].slice(0, 150).trim(),
+                severity: rule.severity,
+            });
+        }
+    }
+    // 2. Line-by-line checks
+    const lines = content.split('\n');
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+        const line = lines[lineIdx];
+        const loc = `Line ${lineIdx + 1}`;
+        // Prompt injection checks
+        for (const rule of PROMPT_INJECTION_PATTERNS) {
+            const match = line.match(rule.pattern);
+            if (match) {
+                annotations.push({
+                    type: 'prompt_injection_suspected',
+                    location: loc,
+                    evidence: match[0].trim(),
+                    severity: rule.severity,
+                });
+            }
+        }
+        // Suspicious shell execution / credential theft checks
+        for (const rule of SUSPICIOUS_INSTRUCTION_PATTERNS) {
+            const match = line.match(rule.pattern);
+            if (match) {
+                annotations.push({
+                    type: 'suspicious_instruction',
+                    location: loc,
+                    evidence: match[0].trim(),
+                    severity: rule.severity,
+                });
+            }
+        }
+        // Unsafe link protocols check
+        for (const rule of UNSAFE_LINK_PATTERNS) {
+            const match = line.match(rule.pattern);
+            if (match) {
+                annotations.push({
+                    type: 'unsafe_link',
+                    location: loc,
+                    evidence: match[1] || match[0],
+                    severity: rule.severity,
+                });
+            }
+        }
+    }
+    return annotations;
+}

package/dist/packages/security/src/index.js

@@ -0,0 +1,2 @@
+export * from "./ssrf.js";
+export * from "./annotations.js";

package/dist/packages/security/src/ssrf.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Checks whether an IPv4 or IPv6 address is in a private, link-local, loopback,
+ * or cloud provider metadata range.
+ */
+export declare function isPrivateOrBlockedIp(ip: string): boolean;
+export interface SsrfValidationOptions {
+    allowLocalhostForTesting?: boolean;
+}
+/**
+ * Validates a target URL against SSRF threats:
+ * - Ensures valid HTTP/HTTPS protocol
+ * - Validates hostname does not resolve to private or loopback IP
+ */
+export declare function validateTargetUrl(urlStr: string, options?: SsrfValidationOptions): Promise<{
+    url: URL;
+    resolvedIp: string;
+}>;