agentic-qe 3.8.13 → 3.9.0

package/dist/plugins/resolver.js

@@ -0,0 +1,80 @@
+/**
+ * Agentic QE v3 - Plugin Dependency Resolver (IMP-09)
+ *
+ * DFS dependency resolution with cycle detection.
+ * Given a set of plugin manifests, produces a topologically-sorted
+ * load order where dependencies are loaded before dependents.
+ */
+// ============================================================================
+// PluginResolver
+// ============================================================================
+export class PluginResolver {
+    /**
+     * Resolve plugin load order via DFS topological sort.
+     *
+     * @param manifests - All available plugin manifests
+     * @returns Ordered list of plugins safe to load sequentially
+     * @throws Error if a dependency cycle is detected
+     */
+    resolve(manifests) {
+        const byName = new Map();
+        for (const m of manifests) {
+            byName.set(m.name, m);
+        }
+        const ordered = [];
+        const visited = new Set();
+        const visiting = new Set(); // cycle detection (gray nodes)
+        const missing = new Map();
+        const visit = (name, path) => {
+            if (visited.has(name))
+                return;
+            if (visiting.has(name)) {
+                const cycle = [...path.slice(path.indexOf(name)), name];
+                throw new Error(`Dependency cycle detected: ${cycle.join(' -> ')}`);
+            }
+            const manifest = byName.get(name);
+            if (!manifest) {
+                // Missing dependency — record it but don't fail the entire resolution
+                return;
+            }
+            visiting.add(name);
+            // Visit dependencies first
+            const deps = Object.keys(manifest.dependencies ?? {});
+            const missingDeps = [];
+            for (const dep of deps) {
+                if (!byName.has(dep)) {
+                    missingDeps.push(dep);
+                }
+                else {
+                    visit(dep, [...path, name]);
+                }
+            }
+            if (missingDeps.length > 0) {
+                missing.set(name, missingDeps);
+            }
+            visiting.delete(name);
+            visited.add(name);
+            ordered.push(manifest);
+        };
+        // Visit all plugins
+        for (const m of manifests) {
+            visit(m.name, []);
+        }
+        return {
+            ordered: ordered.map((manifest, index) => ({ manifest, order: index })),
+            missing,
+        };
+    }
+    /**
+     * Check if a specific plugin can be loaded given the currently loaded set.
+     */
+    canLoad(manifest, loaded) {
+        const deps = Object.keys(manifest.dependencies ?? {});
+        const missingDeps = deps.filter(d => !loaded.has(d));
+        return {
+            canLoad: missingDeps.length === 0,
+            missingDeps,
+        };
+    }
+}
+//# sourceMappingURL=resolver.js.map

package/dist/plugins/security.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Agentic QE v3 - Plugin Security (IMP-09)
+ *
+ * Security validation for plugins:
+ * - Name impersonation prevention (reserved namespaces)
+ * - Path traversal prevention in entry points and hook handlers
+ * - Non-ASCII name blocking
+ * - Hook policy integration (leverages IMP-07 hook security)
+ */
+import type { QEPluginManifest } from './manifest';
+export interface SecurityCheckResult {
+    safe: boolean;
+    violations: string[];
+}
+/**
+ * Run all security checks on a plugin manifest.
+ */
+export declare function checkPluginSecurity(manifest: QEPluginManifest): SecurityCheckResult;
+/**
+ * Validate that a plugin name is safe to use.
+ */
+export declare function isNameSafe(name: string): boolean;
+//# sourceMappingURL=security.d.ts.map

package/dist/plugins/security.js

@@ -0,0 +1,125 @@
+/**
+ * Agentic QE v3 - Plugin Security (IMP-09)
+ *
+ * Security validation for plugins:
+ * - Name impersonation prevention (reserved namespaces)
+ * - Path traversal prevention in entry points and hook handlers
+ * - Non-ASCII name blocking
+ * - Hook policy integration (leverages IMP-07 hook security)
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/** Prefixes reserved for first-party plugins */
+const RESERVED_PREFIXES = [
+    'aqe-core-',
+    'agentic-qe-core-',
+    'agentic-qe-internal-',
+];
+/** Names that cannot be used (exact match) */
+const RESERVED_NAMES = new Set([
+    'aqe',
+    'agentic-qe',
+    'ruflo',
+    'claude-flow',
+]);
+/** Dangerous path patterns */
+const DANGEROUS_PATH_PATTERNS = [
+    '..', // directory traversal
+    '~', // home directory expansion
+    '/etc/', // system config
+    '/proc/', // process info
+    '/dev/', // devices
+    'node_modules/', // dependency injection
+];
+// ============================================================================
+// Plugin Security Checks
+// ============================================================================
+/**
+ * Run all security checks on a plugin manifest.
+ */
+export function checkPluginSecurity(manifest) {
+    const violations = [];
+    checkName(manifest.name, violations);
+    checkEntryPoint(manifest.entryPoint, violations);
+    checkHookPaths(manifest.hooks, violations);
+    checkPermissions(manifest.permissions, violations);
+    return {
+        safe: violations.length === 0,
+        violations,
+    };
+}
+/**
+ * Validate that a plugin name is safe to use.
+ */
+export function isNameSafe(name) {
+    const violations = [];
+    checkName(name, violations);
+    return violations.length === 0;
+}
+// ============================================================================
+// Internal Checks
+// ============================================================================
+function checkName(name, violations) {
+    // Non-ASCII check
+    // eslint-disable-next-line no-control-regex
+    if (/[^\x20-\x7E]/.test(name)) {
+        violations.push(`Plugin name "${name}" contains non-ASCII characters`);
+    }
+    // Reserved exact names
+    if (RESERVED_NAMES.has(name.toLowerCase())) {
+        violations.push(`Plugin name "${name}" is a reserved name`);
+    }
+    // Reserved prefixes
+    for (const prefix of RESERVED_PREFIXES) {
+        if (name.toLowerCase().startsWith(prefix)) {
+            violations.push(`Plugin name "${name}" uses reserved prefix "${prefix}"`);
+        }
+    }
+    // Homoglyph detection: block names that look like reserved names
+    // (simplified — checks for common substitutions)
+    const normalized = name
+        .toLowerCase()
+        .replace(/[0o]/g, 'o')
+        .replace(/[1il]/g, 'l')
+        .replace(/[-_]/g, '');
+    if (RESERVED_NAMES.has(normalized)) {
+        violations.push(`Plugin name "${name}" is visually similar to a reserved name`);
+    }
+}
+function checkEntryPoint(entryPoint, violations) {
+    checkPath(entryPoint, 'entryPoint', violations);
+    // Must be relative
+    if (entryPoint.startsWith('/') || entryPoint.startsWith('\\')) {
+        violations.push('entryPoint must be a relative path, not absolute');
+    }
+}
+function checkHookPaths(hooks, violations) {
+    if (!hooks)
+        return;
+    for (const [event, handlerPath] of Object.entries(hooks)) {
+        checkPath(handlerPath, `hook[${event}]`, violations);
+    }
+}
+function checkPath(p, label, violations) {
+    for (const pattern of DANGEROUS_PATH_PATTERNS) {
+        if (p.includes(pattern)) {
+            violations.push(`${label} contains dangerous path pattern "${pattern}"`);
+        }
+    }
+    // Check for null bytes (path injection)
+    if (p.includes('\0')) {
+        violations.push(`${label} contains null byte (path injection attempt)`);
+    }
+}
+function checkPermissions(permissions, violations) {
+    if (!permissions)
+        return;
+    const dangerous = ['fs:write-root', 'net:arbitrary', 'exec:shell'];
+    for (const perm of permissions) {
+        if (dangerous.includes(perm)) {
+            violations.push(`Plugin requests dangerous permission: ${perm}`);
+        }
+    }
+}
+//# sourceMappingURL=security.js.map

package/dist/plugins/sources/github.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Agentic QE v3 - GitHub Plugin Source (IMP-09)
+ *
+ * Discovers and fetches plugins from GitHub repositories.
+ * Uses git clone over HTTPS (public repos only).
+ */
+import { type QEPluginManifest } from '../manifest';
+import type { PluginSource } from './local';
+export declare class GitHubPluginSource implements PluginSource {
+    readonly type = "github";
+    private readonly cacheDir;
+    constructor(cacheDir?: string);
+    resolve(location: string): Promise<QEPluginManifest>;
+    getPluginPath(location: string): Promise<string>;
+    private parseLocation;
+}
+//# sourceMappingURL=github.d.ts.map

package/dist/plugins/sources/github.js

@@ -0,0 +1,77 @@
+/**
+ * Agentic QE v3 - GitHub Plugin Source (IMP-09)
+ *
+ * Discovers and fetches plugins from GitHub repositories.
+ * Uses git clone over HTTPS (public repos only).
+ */
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import { parseManifest } from '../manifest';
+// ============================================================================
+// Input Validation
+// ============================================================================
+/** Only allow safe characters in repo owner/name and tag */
+const SAFE_REPO_REGEX = /^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/;
+const SAFE_TAG_REGEX = /^[a-zA-Z0-9._\-/]+$/;
+function validateRepoRef(repo, tag) {
+    if (!SAFE_REPO_REGEX.test(repo)) {
+        throw new Error(`Invalid GitHub repo "${repo}": must be owner/repo with alphanumeric, dots, hyphens, underscores only`);
+    }
+    if (tag && !SAFE_TAG_REGEX.test(tag)) {
+        throw new Error(`Invalid tag "${tag}": must be alphanumeric with dots, hyphens, underscores, slashes only`);
+    }
+}
+// ============================================================================
+// GitHubPluginSource
+// ============================================================================
+export class GitHubPluginSource {
+    type = 'github';
+    cacheDir;
+    constructor(cacheDir) {
+        this.cacheDir = cacheDir ?? path.join(process.cwd(), '.agentic-qe', 'plugins-cache');
+    }
+    async resolve(location) {
+        const pluginPath = await this.getPluginPath(location);
+        const manifestPath = path.join(pluginPath, 'qe-plugin.json');
+        const fs = await import('fs');
+        if (!fs.existsSync(manifestPath)) {
+            throw new Error(`No qe-plugin.json found in ${location}`);
+        }
+        const raw = fs.readFileSync(manifestPath, 'utf-8');
+        return parseManifest(raw);
+    }
+    async getPluginPath(location) {
+        const { repo, tag } = this.parseLocation(location);
+        // Validate inputs before using in any command
+        validateRepoRef(repo, tag);
+        const targetDir = path.join(this.cacheDir, repo.replace('/', '__'), tag || 'latest');
+        const fs = await import('fs');
+        if (fs.existsSync(targetDir)) {
+            return targetDir;
+        }
+        fs.mkdirSync(targetDir, { recursive: true });
+        try {
+            const cloneUrl = `https://github.com/${repo}.git`;
+            // Use execFileSync with array args — no shell, no injection
+            const args = ['clone', '--depth', '1'];
+            if (tag) {
+                args.push('--branch', tag);
+            }
+            args.push(cloneUrl, targetDir);
+            execFileSync('git', args, { stdio: 'pipe', timeout: 60_000 });
+        }
+        catch (err) {
+            fs.rmSync(targetDir, { recursive: true, force: true });
+            throw new Error(`Failed to clone ${repo}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return targetDir;
+    }
+    parseLocation(location) {
+        const [repo, tag] = location.split('@');
+        if (!repo || !repo.includes('/')) {
+            throw new Error(`Invalid GitHub location "${location}". Expected "owner/repo" or "owner/repo@tag"`);
+        }
+        return { repo, tag };
+    }
+}
+//# sourceMappingURL=github.js.map

package/dist/plugins/sources/local.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Agentic QE v3 - Local Plugin Source (IMP-09)
+ *
+ * Discovers and loads plugins from local filesystem directories.
+ * Expects a `qe-plugin.json` manifest file in the plugin root.
+ */
+import { type QEPluginManifest } from '../manifest';
+export interface PluginSource {
+    type: string;
+    /** Resolve the plugin manifest from this source. */
+    resolve(location: string): Promise<QEPluginManifest>;
+    /** Get the absolute path to the plugin directory. */
+    getPluginPath(location: string): Promise<string>;
+}
+export declare class LocalPluginSource implements PluginSource {
+    readonly type = "local";
+    resolve(location: string): Promise<QEPluginManifest>;
+    getPluginPath(location: string): Promise<string>;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/plugins/sources/local.js

@@ -0,0 +1,32 @@
+/**
+ * Agentic QE v3 - Local Plugin Source (IMP-09)
+ *
+ * Discovers and loads plugins from local filesystem directories.
+ * Expects a `qe-plugin.json` manifest file in the plugin root.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseManifest } from '../manifest';
+// ============================================================================
+// LocalPluginSource
+// ============================================================================
+export class LocalPluginSource {
+    type = 'local';
+    async resolve(location) {
+        const absPath = path.resolve(location);
+        const manifestPath = path.join(absPath, 'qe-plugin.json');
+        if (!fs.existsSync(manifestPath)) {
+            throw new Error(`No qe-plugin.json found at ${manifestPath}`);
+        }
+        const raw = fs.readFileSync(manifestPath, 'utf-8');
+        return parseManifest(raw);
+    }
+    async getPluginPath(location) {
+        const absPath = path.resolve(location);
+        if (!fs.existsSync(absPath)) {
+            throw new Error(`Plugin directory does not exist: ${absPath}`);
+        }
+        return absPath;
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/plugins/sources/npm.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Agentic QE v3 - npm Plugin Source (IMP-09)
+ *
+ * Discovers and installs plugins from the npm registry.
+ * Uses `npm pack` + extract to get the plugin without polluting
+ * the project's node_modules.
+ */
+import { type QEPluginManifest } from '../manifest';
+import type { PluginSource } from './local';
+export declare class NpmPluginSource implements PluginSource {
+    readonly type = "npm";
+    private readonly cacheDir;
+    constructor(cacheDir?: string);
+    resolve(location: string): Promise<QEPluginManifest>;
+    getPluginPath(location: string): Promise<string>;
+    private parseLocation;
+}
+//# sourceMappingURL=npm.d.ts.map

package/dist/plugins/sources/npm.js

@@ -0,0 +1,82 @@
+/**
+ * Agentic QE v3 - npm Plugin Source (IMP-09)
+ *
+ * Discovers and installs plugins from the npm registry.
+ * Uses `npm pack` + extract to get the plugin without polluting
+ * the project's node_modules.
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { execFileSync } from 'child_process';
+import { parseManifest } from '../manifest';
+// ============================================================================
+// Input Validation
+// ============================================================================
+/** Only allow safe npm package name characters: alphanumeric, @, /, -, ., _ */
+const SAFE_NPM_NAME_REGEX = /^(@[a-zA-Z0-9._-]+\/)?[a-zA-Z0-9._-]+$/;
+const SAFE_VERSION_REGEX = /^[a-zA-Z0-9._\-+]+$/;
+function validateNpmSpec(name, version) {
+    if (!SAFE_NPM_NAME_REGEX.test(name)) {
+        throw new Error(`Invalid npm package name "${name}": contains unsafe characters`);
+    }
+    if (version && !SAFE_VERSION_REGEX.test(version)) {
+        throw new Error(`Invalid version "${version}": contains unsafe characters`);
+    }
+}
+// ============================================================================
+// NpmPluginSource
+// ============================================================================
+export class NpmPluginSource {
+    type = 'npm';
+    cacheDir;
+    constructor(cacheDir) {
+        this.cacheDir = cacheDir ?? path.join(process.cwd(), '.agentic-qe', 'plugins-cache', 'npm');
+    }
+    async resolve(location) {
+        const pluginPath = await this.getPluginPath(location);
+        const manifestPath = path.join(pluginPath, 'qe-plugin.json');
+        if (!fs.existsSync(manifestPath)) {
+            throw new Error(`No qe-plugin.json found in npm package ${location}`);
+        }
+        const raw = fs.readFileSync(manifestPath, 'utf-8');
+        return parseManifest(raw);
+    }
+    async getPluginPath(location) {
+        const { name, version } = this.parseLocation(location);
+        // Validate inputs before using in any command
+        validateNpmSpec(name, version);
+        const safeName = name.replace(/\//g, '__');
+        const targetDir = path.join(this.cacheDir, `${safeName}@${version || 'latest'}`);
+        if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+            return targetDir;
+        }
+        fs.mkdirSync(targetDir, { recursive: true });
+        try {
+            const spec = version ? `${name}@${version}` : name;
+            // Use execFileSync with array args — no shell, no injection
+            const tarball = execFileSync('npm', ['pack', spec, '--pack-destination', targetDir], { stdio: 'pipe', timeout: 60_000 }).toString().trim();
+            const tarPath = path.join(targetDir, tarball);
+            execFileSync('tar', ['-xzf', tarPath, '-C', targetDir, '--strip-components=1'], { stdio: 'pipe' });
+            if (fs.existsSync(tarPath)) {
+                fs.unlinkSync(tarPath);
+            }
+        }
+        catch (err) {
+            fs.rmSync(targetDir, { recursive: true, force: true });
+            throw new Error(`Failed to fetch npm package ${location}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return targetDir;
+    }
+    parseLocation(location) {
+        // Handle scoped packages: @scope/name@version
+        const atIndex = location.lastIndexOf('@');
+        if (atIndex > 0) {
+            return {
+                name: location.slice(0, atIndex),
+                version: location.slice(atIndex + 1) || undefined,
+            };
+        }
+        return { name: location };
+    }
+}
+//# sourceMappingURL=npm.js.map

package/dist/shared/llm/retry.d.ts

@@ -1,10 +1,13 @@
 /**
  * Shared retry utilities for LLM providers.
- * Extracts the common exponential backoff pattern used across all providers.
+ * IMP-03: Now delegates to the unified retry engine.
+ * Preserves the original backoffDelay() signature for backwards compatibility.
  */
 /**
  * Compute exponential backoff delay: min(base * 2^attempt, max).
- * Used by all LLM provider retry loops.
+ * @deprecated Use `computeBackoff` from `../retry-engine` directly.
  */
 export declare function backoffDelay(attempt: number, baseMs?: number, maxMs?: number): number;
+export { computeBackoff, withRetry, isRetryableError } from '../retry-engine.js';
+export type { RetryOptions, RetryResult } from '../retry-engine.js';
 //# sourceMappingURL=retry.d.ts.map

package/dist/shared/llm/retry.js

@@ -1,16 +1,20 @@
 /**
  * Shared retry utilities for LLM providers.
- * Extracts the common exponential backoff pattern used across all providers.
+ * IMP-03: Now delegates to the unified retry engine.
+ * Preserves the original backoffDelay() signature for backwards compatibility.
  */
+import { computeBackoff } from '../retry-engine.js';
 /** Default base delay (1 second) */
 const DEFAULT_BASE_MS = 1000;
 /** Default maximum delay cap (30 seconds) */
 const DEFAULT_MAX_MS = 30000;
 /**
  * Compute exponential backoff delay: min(base * 2^attempt, max).
- * Used by all LLM provider retry loops.
+ * @deprecated Use `computeBackoff` from `../retry-engine` directly.
  */
 export function backoffDelay(attempt, baseMs = DEFAULT_BASE_MS, maxMs = DEFAULT_MAX_MS) {
-    return Math.min(baseMs * Math.pow(2, attempt), maxMs);
+    return computeBackoff(attempt, baseMs, maxMs, 0);
 }
+// IMP-03: Re-export unified retry engine for incremental migration
+export { computeBackoff, withRetry, isRetryableError } from '../retry-engine.js';
 //# sourceMappingURL=retry.js.map

package/dist/shared/prompt-cache-latch.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Latch field manager for API header/prompt stabilization.
+ * Values are locked after first set — subsequent set() calls are no-ops
+ * unless explicitly reset(). This prevents cache-busting from
+ * incidental parameter changes between API calls.
+ */
+export declare class PromptCacheLatch {
+    private latched;
+    private readonly disabled;
+    /**
+     * Latch a value. If already latched, this is a no-op (original preserved).
+     * Returns true if the value was newly latched, false if already locked.
+     * When disabled via AQE_PROMPT_CACHE_LATCH=false, always stores the new value.
+     */
+    latch(key: string, value: unknown): boolean;
+    /**
+     * Get a latched value.
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Check if a key is latched.
+     */
+    has(key: string): boolean;
+    /**
+     * Explicitly unlock and remove a latched value.
+     */
+    reset(key: string): void;
+    /**
+     * Reset all latched values (e.g., on session boundary).
+     */
+    resetAll(): void;
+    /**
+     * Get snapshot of all latched key-value pairs.
+     */
+    getSnapshot(): Record<string, unknown>;
+    /**
+     * Number of latched values.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=prompt-cache-latch.d.ts.map

package/dist/shared/prompt-cache-latch.js

@@ -0,0 +1,63 @@
+/**
+ * Latch field manager for API header/prompt stabilization.
+ * Values are locked after first set — subsequent set() calls are no-ops
+ * unless explicitly reset(). This prevents cache-busting from
+ * incidental parameter changes between API calls.
+ */
+export class PromptCacheLatch {
+    latched = new Map();
+    disabled = process.env.AQE_PROMPT_CACHE_LATCH === 'false';
+    /**
+     * Latch a value. If already latched, this is a no-op (original preserved).
+     * Returns true if the value was newly latched, false if already locked.
+     * When disabled via AQE_PROMPT_CACHE_LATCH=false, always stores the new value.
+     */
+    latch(key, value) {
+        if (this.disabled) {
+            this.latched.set(key, value);
+            return true;
+        }
+        if (this.latched.has(key)) {
+            return false;
+        }
+        this.latched.set(key, value);
+        return true;
+    }
+    /**
+     * Get a latched value.
+     */
+    get(key) {
+        return this.latched.get(key);
+    }
+    /**
+     * Check if a key is latched.
+     */
+    has(key) {
+        return this.latched.has(key);
+    }
+    /**
+     * Explicitly unlock and remove a latched value.
+     */
+    reset(key) {
+        this.latched.delete(key);
+    }
+    /**
+     * Reset all latched values (e.g., on session boundary).
+     */
+    resetAll() {
+        this.latched.clear();
+    }
+    /**
+     * Get snapshot of all latched key-value pairs.
+     */
+    getSnapshot() {
+        return Object.fromEntries(this.latched);
+    }
+    /**
+     * Number of latched values.
+     */
+    get size() {
+        return this.latched.size;
+    }
+}
+//# sourceMappingURL=prompt-cache-latch.js.map