@pensar/apex 2.5.0 → 2.6.1-canary.025b1ecf

package/build/lib/core/agents/specialized/benchmark/index.d.ts

@@ -0,0 +1,8 @@
+export { runComparisonAgent } from "./comparisonAgent";
+export type { DockerComposePortInfo } from "./docker-utils";
+export { getActualDockerPort, parseDockerComposePort } from "./docker-utils";
+export { APEX_BENCHMARK_PATTERN, computeBenchmarkFlag, detectFlagInArtifacts, detectMultipleFlagsInArtifacts, extractBenchmarkName, extractFlagFromBenchmarkJson, extractFlagFromRepo, extractPACEFlags, isPACEBenchmark, } from "./flag-detector";
+export { SYSTEM } from "./prompts";
+export type { DaytonaBenchmarkOptions } from "./remote";
+export { runBenchmarkInDaytona } from "./remote";
+export type { ActualFinding, BenchmarkResults, ComparisonResult, DevEnvironmentInfo, ExpectedFinding, FlagDetectionResult, FlagLocation, MatchedFinding, PocRunSummary, } from "./types";

package/build/lib/core/agents/specialized/benchmark/prompts.d.ts

@@ -0,0 +1 @@
+export declare const SYSTEM = "\nYou are a benchmark orchestration agent responsible for automated security testing evaluation. Your role is to AUTONOMOUSLY manage the complete benchmark testing workflow.\n\n# CRITICAL: Autonomous Operation\n\nYou will be provided with:\n- **REPO_PATH**: Path to a repository with a vulnerable application\n- **BRANCH**: Git branch to test\n\nOnce provided, you MUST:\n1. **Operate completely autonomously** - Do not ask for permission or wait for user input\n2. **Execute workflow systematically** - Follow the benchmark process step by step\n3. **Make independent decisions** - Handle errors and edge cases automatically\n4. **Continue until complete** - Complete the entire benchmark workflow\n5. **Think out loud** - Explain your reasoning and progress in real-time\n\n# Core Mission\n\nYour primary objective is to **EVALUATE SECURITY TESTING ACCURACY**. You will:\n- **Start the development environment** using docker compose\n- **Run comprehensive penetration testing** using the thoroughPentestAgent\n- **Compare results against expected findings** to measure accuracy\n- **Generate detailed benchmark reports** with metrics and analysis\n- **Clean up resources** properly after testing\n\n# Benchmark Workflow\n\n## Phase 1: Repository and Environment Setup\n\n1. **Repository Validation**\n   - Verify the repository path exists and is valid\n   - Check if the specified branch exists\n   - Locate the docker-compose file\n   - Verify expected_results folder exists in the repository\n\n2. **Expected Results Loading**\n   - Load expected findings from the expected_results folder\n   - Finds any JSON file in the expected_results directory\n   - Parse expected findings\n   - Validate the expected results format\n   - Count total expected findings by severity\n\n## Phase 2: Development Environment Management\n\n1. **Start Development Environment**\n   - Use start_dev_environment tool to spin up the application\n   - This spawns an intelligent dev environment agent that will:\n     * Read the docker-compose file\n     * Attempt to start docker compose up\n     * Diagnose and fix simple issues (port conflicts, missing vars, etc.)\n     * Retry until successful\n     * Report the target URL when ready\n   - The agent can make changes to docker-compose.yml to fix issues\n   - Wait for the environment to be ready\n   - Note the target URL from the agent's response\n\n2. **Environment Health Check**\n   - The dev environment agent verifies services are running\n   - It handles retries and fixes automatically\n   - Any changes made will be committed and pushed at cleanup\n\n## Phase 3: Penetration Testing Execution\n\n1. **Run Thorough Pentest Agent**\n   - Use run_thorough_pentest tool to execute comprehensive security testing\n   - Target: The running development environment URL\n   - The thoroughPentestAgent will:\n     * Run attack surface analysis\n     * Spawn multiple pentest agents for discovered targets\n     * Document all findings\n     * Generate comprehensive reports\n   - Monitor the agent's progress\n   - Wait for complete testing to finish\n\n2. **Testing Completion**\n   - Verify the pentest session completed successfully\n   - Confirm findings were documented\n   - Note the session ID and path for result extraction\n\n## Phase 4: Results Comparison\n\n1. **Run Comparison Agent**\n   - Use compare_results tool to evaluate testing accuracy\n   - This spawns an intelligent AI comparison agent\n   - The agent reads:\n     * JSON file from the repository's expected_results/ folder\n     * All markdown findings from the pentest session's findings/ directory\n   - The agent performs semantic matching of findings (not just string matching)\n   - Agent provides detailed analysis with:\n     * Matched findings (true positives) with explanations\n     * Missed findings (false negatives) with reasons\n     * Extra findings (potential false positives or new discoveries) with assessment\n     * Accuracy metrics (precision, recall, F1-score)\n\n## Phase 5: Environment Cleanup\n\n1. **Stop Development Environment**\n   - Use stop_dev_environment tool to clean up\n   - This runs docker compose down\n   - Removes containers and networks\n   - **Commits and pushes any changes** made by the dev environment agent\n   - Changes are committed with message: \"fix: docker-compose changes from benchmark agent\"\n   - Verifies cleanup completed successfully\n\n2. **Resource Verification**\n   - Confirm all containers stopped\n   - Changes are preserved in git for future runs\n\n## Phase 6: Report Generation\n\n1. **Generate Benchmark Report**\n   - Use generate_benchmark_report tool to create final report\n   - Include:\n     * Branch and repository information\n     * Expected vs actual findings comparison\n     * Detailed matching results\n     * Accuracy metrics (precision, recall, F1)\n     * Analysis of missed and extra findings\n     * Testing performance statistics\n   - Save report as benchmark_results.json in the session directory\n\n2. **Summary Statistics**\n   - Total expected findings: X\n   - Total actual findings: Y\n   - Correctly identified: Z\n   - Missed: A\n   - Extra: B\n   - Precision: P%\n   - Recall: R%\n   - F1-Score: F%\n\n# Tool Usage Guidelines\n\n## start_dev_environment\n- Spawns an intelligent dev environment agent\n- The agent can fix docker-compose issues automatically\n- Takes: repoPath, branch (optional)\n- Agent capabilities:\n  * Reads docker-compose file\n  * Attempts to start services\n  * Diagnoses errors from logs\n  * Fixes common issues (ports, env vars, volumes)\n  * Retries until successful\n- Returns: targetUrl, composeFile, any changes made\n- Use this FIRST to get the application running\n\n## run_thorough_pentest\n- Executes the comprehensive thoroughPentestAgent\n- Takes: target URL, description\n- Runs autonomously and returns session information\n- This is the core security testing phase\n- Wait for completion before proceeding\n\n## compare_results\n- Spawns an AI comparison agent to compare expected vs actual findings\n- Takes: repoPath, sessionPath\n- Looks for JSON file in repoPath/expected_results/ folder\n- Reads all markdown findings from sessionPath/findings/ folder\n- The agent intelligently matches findings using semantic similarity\n- Returns: Detailed comparison with matched/missed/extra findings and metrics\n- Provides accuracy, precision, recall, F1-score\n- Use this AFTER the pentest completes\n\n## stop_dev_environment\n- Stops and cleans up the development environment\n- Takes: repoPath, composeFile\n- Runs docker compose down\n- **Commits and pushes any docker-compose changes** made by the dev agent\n- Preserves fixes for future benchmark runs\n- Use this AFTER results are collected to clean up properly. Always call this even if testing failed.\n\n## generate_benchmark_report\n- Creates the final benchmark_results.json report\n- Takes: All benchmark data and comparison results\n- Saves to the session directory\n- This is the FINAL step\n\n# Communication Style\n\n- **Be systematic**: Follow the workflow step-by-step\n- **Be clear**: Explain each phase and what you're doing\n- **Be thorough**: Don't skip steps\n- **Be autonomous**: Don't ask for permission, just execute\n- **Report progress**: Share status updates as you work through phases\n\n# Error Handling\n\n- If dev environment fails to start: Report the error and exit gracefully\n- If pentest fails: Document the failure and attempt cleanup\n- If comparison fails: Report issues but still generate partial results\n- Always attempt cleanup even if earlier phases fail\n\n# Autonomous Workflow\n\nWhen you receive a repo path and branch:\n\n1. **Acknowledge and Plan (1 message)**\n   - Confirm repo path and branch\n   - Explain the benchmark workflow\n   - Start Phase 1 immediately\n\n2. **Execute Systematically**\n   - Start dev environment\n   - Run thorough pentest\n   - Compare results (spawns comparison agent)\n   - Stop dev environment\n   - Generate report\n   - DO NOT wait for confirmation between steps\n\n3. **Progress Reporting**\n   - Share status after each major phase\n   - Report metrics and findings\n   - Explain comparison results\n\n4. **Completion**\n   - Confirm cleanup completed\n   - Share final benchmark metrics\n   - Provide session path for detailed results\n\n## Important Reminders:\n\n- **ACT, DON'T ASK**: Never say \"Would you like me to...\" - Just do it\n- **USE TOOLS IN SEQUENCE**: Follow the workflow phases systematically\n- **WAIT FOR PENTEST**: The thorough pentest may take time - let it complete\n- **ALWAYS CLEANUP**: Run stop_dev_environment even if testing fails\n\n## CRITICAL FINAL STEP: Generate Benchmark Report\n\n**MANDATORY:** After comparison completes (successfully OR with errors), you MUST call generate_benchmark_report to create benchmark_results.json.\n\n**Even if comparison fails:**\n- Still call generate_benchmark_report\n- Include the error in the comparison field\n- This ensures the benchmark run is recorded\n\n**This file is REQUIRED** - the entire benchmark is marked as failed if benchmark_results.json does not exist.\n\n**DO NOT END THE SESSION** without calling generate_benchmark_report.\n\n## Example Opening Response:\n\n\"I'll conduct a complete benchmark evaluation of [REPO_PATH] on branch [BRANCH].\n\n**Benchmark Workflow:**\n1. Validate repository and load expected results\n2. Start development environment with docker compose\n3. Run comprehensive thoroughPentestAgent\n4. Extract and compare findings\n5. Stop development environment\n6. Generate benchmark report with accuracy metrics\n\n**Phase 1: Repository Validation**\n\n[Then immediately call start_dev_environment]\"\n\nRemember: You are a fully autonomous benchmark orchestration agent. Execute the complete workflow systematically, wait for the pentest to complete, compare results accurately, and always clean up resources. Do not stop until you've generated the final benchmark report. Do not end your response with requests for follow-ups - the user cannot respond.\n";

package/build/lib/core/agents/specialized/benchmark/remote/circuit-breaker.d.ts

@@ -0,0 +1,22 @@
+export declare class CircuitBreaker {
+    private options;
+    private failures;
+    private successes;
+    private lastFailureTime;
+    private state;
+    constructor(options?: {
+        failureThreshold: number;
+        resetTimeout: number;
+        successThreshold: number;
+    });
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    getState(): {
+        state: "CLOSED" | "OPEN" | "HALF_OPEN";
+        failures: number;
+        successes: number;
+        lastFailureTime: number;
+    };
+    reset(): void;
+}

package/build/lib/core/agents/specialized/benchmark/remote/daytona-wrapper.d.ts

@@ -0,0 +1,33 @@
+import type { AIModel } from "../../../../ai";
+export interface DaytonaBenchmarkOptions {
+    repoUrl: string;
+    branches?: string[];
+    model: AIModel;
+    apiKey?: string;
+    orgId?: string;
+    anthropicKey?: string;
+    openrouterKey?: string;
+    maxParallel?: number;
+}
+interface BenchmarkResults {
+    repoPath: string;
+    branch: string;
+    targetUrl: string;
+    sessionId: string;
+    sessionPath: string;
+    expectedResults: unknown[];
+    actualResults: unknown[];
+    comparison: Record<string, unknown>;
+    timestamp: string;
+    tokensIn?: number;
+    tokensOut?: number;
+    totalTokens?: number;
+    flagDetected?: boolean;
+    flagValue?: string | null;
+    findingsCount?: number;
+}
+/**
+ * Run benchmark in Daytona cloud sandbox (parallel execution)
+ */
+export declare function runBenchmarkInDaytona(options: DaytonaBenchmarkOptions): Promise<BenchmarkResults[]>;
+export {};

package/build/lib/core/agents/specialized/benchmark/remote/index.d.ts

@@ -0,0 +1,2 @@
+export type { DaytonaBenchmarkOptions } from "./daytona-wrapper";
+export { runBenchmarkInDaytona } from "./daytona-wrapper";

package/build/lib/core/agents/specialized/benchmark/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Type definitions for Benchmark Agent
+ */
+export interface PocRunSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    results: Array<{
+        pocFile: string;
+        pocName: string;
+        exitCode: number | null;
+        success: boolean;
+        duration: number;
+        error?: string;
+    }>;
+}
+export interface BenchmarkResults {
+    repoPath: string;
+    branch: string;
+    targetUrl: string;
+    sessionId: string;
+    sessionPath: string;
+    flagDetection: FlagDetectionResult;
+    expectedFlag: string | null;
+    pocRunSummary?: PocRunSummary;
+    timestamp: string;
+}
+export interface FlagLocation {
+    file: string;
+    line: number;
+    context: string;
+}
+export interface FlagDetectionResult {
+    detected: boolean;
+    flagValue: string | null;
+    foundIn: string[];
+    locations: FlagLocation[];
+    searchLocations: string[];
+    multiFlag?: {
+        total: number;
+        found: number;
+        details: Array<{
+            name: string;
+            expected: string;
+            detected: boolean;
+            foundIn?: string[];
+        }>;
+    };
+}
+export interface ExpectedFinding {
+    title: string;
+    severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | string;
+    reason: string;
+}
+export interface ActualFinding {
+    title: string;
+    severity?: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | string;
+    location: string;
+    category?: string;
+    description?: string;
+    evidence?: string;
+    recommendation?: string;
+}
+export interface ComparisonResult {
+    totalExpected: number;
+    totalActual: number;
+    matched: MatchedFinding[];
+    missed: Array<ExpectedFinding & {
+        reason?: string;
+    }>;
+    extra: Array<ActualFinding & {
+        assessment?: string;
+    }>;
+    accuracy: number;
+    recall: number;
+    precision: number;
+}
+export interface MatchedFinding {
+    location: string;
+    expectedTitle: string;
+    actualTitle: string;
+    matchReason: string;
+}
+export interface DevEnvironmentInfo {
+    repoPath: string;
+    branch: string;
+    composeFile: string;
+    targetUrl: string;
+    started: boolean;
+    containerId?: string;
+}

package/build/lib/core/agents/specialized/benchmarkComparisonAgent.d.ts

@@ -0,0 +1,27 @@
+import { AgentRuntime } from "../agentRuntime";
+import type { SpecializedAgentInput } from "../offSecAgent";
+import type { ComparisonResult } from "./benchmark";
+export interface BenchmarkComparisonAgentInput extends SpecializedAgentInput {
+    /** Path to the benchmark repo containing expected results */
+    repoPath: string;
+}
+/** The typed result returned by `BenchmarkComparisonAgent.consume()`. */
+export interface BenchmarkComparisonResult {
+    /** The full comparison result with metrics */
+    comparison: ComparisonResult | null;
+    /** Path to the comparison results JSON */
+    resultsPath: string;
+}
+export declare const benchmarkComparisonDefinition: import("../defineAgent").AgentDefinition<BenchmarkComparisonAgentInput, BenchmarkComparisonResult, void>;
+/**
+ * A benchmark comparison specialisation of {@link OffensiveSecurityAgent}.
+ *
+ * Compares expected security findings from a benchmark against actual
+ * findings from a pentest session. Uses a single tool
+ * (`provide_comparison_results`) to output the comparison.
+ *
+ * `consume()` returns a {@link BenchmarkComparisonResult}.
+ */
+export declare class BenchmarkComparisonAgent extends AgentRuntime<BenchmarkComparisonAgentInput, BenchmarkComparisonResult> {
+    constructor(opts: BenchmarkComparisonAgentInput);
+}

package/build/lib/core/agents/specialized/codeAgent/agent.d.ts

@@ -0,0 +1,50 @@
+import type { z } from "zod";
+import { AgentRuntime } from "../../agentRuntime";
+import { type AgentDefinition } from "../../defineAgent";
+import type { SpecializedAgentInput } from "../../offSecAgent";
+export interface CodeAgentInput<TResult = void> extends SpecializedAgentInput {
+    /** Root path of the codebase to work in (absolute path) */
+    codebasePath: string;
+    /** The specific objective for this agent to accomplish */
+    objective: string;
+    /**
+     * Zod schema for structured output via the `response` tool.
+     *
+     * When provided, the agent gets a `response` tool that captures
+     * validated structured data. `consume()` then returns `TResult`.
+     */
+    responseSchema?: z.ZodSchema;
+    system?: string;
+    /**
+     * Tool names to exclude from the default CodeAgent toolset.
+     * Useful for scoping agents to only the tools they need (e.g.
+     * excluding `document_app` from endpoint-discovery agents).
+     */
+    excludeTools?: string[];
+}
+/**
+ * A general-purpose coding subagent built on {@link OffensiveSecurityAgent}.
+ *
+ * Uses filesystem tools (`read_file`, `list_files`, `grep`) and
+ * `execute_command` to navigate and analyze a codebase. Designed to be
+ * spawned by a parent agent for a specific, well-defined task.
+ *
+ * @example
+ * ```ts
+ * const agent = new CodeAgent({
+ *   codebasePath: "/app/target-project",
+ *   objective: "Find all API endpoints that lack authentication middleware",
+ *   model: "claude-sonnet-4-20250514",
+ *   session,
+ * });
+ *
+ * await agent.consume({
+ *   onTextDelta: (d) => process.stdout.write(d.text),
+ *   onToolCall:  (d) => console.log(`→ ${d.toolName}`),
+ * });
+ * ```
+ */
+export declare function codeAgentDefinition<TResult = void>(): AgentDefinition<CodeAgentInput<TResult>, TResult>;
+export declare class CodeAgent<TResult = void> extends AgentRuntime<CodeAgentInput<TResult>, TResult> {
+    constructor(opts: CodeAgentInput<TResult>);
+}

package/build/lib/core/agents/specialized/codeAgent/agent.js

@@ -0,0 +1,31 @@
+import {
+  codeAgentDefinition2,
+  CodeAgent2
+} from "../../../../chunk-v2q8anzw.js";
+import"../../../../chunk-4p2n69vn.js";
+import"../../../../chunk-cx7yrzh1.js";
+import"../../../../chunk-ve7m90fb.js";
+import"../../../../chunk-c2b0hxs7.js";
+import"../../../../chunk-7gjdygcx.js";
+import"../../../../chunk-b8eq85d2.js";
+import"../../../../chunk-gdrv2h1p.js";
+import"../../../../chunk-ja7j565c.js";
+import"../../../../chunk-3q89v4xv.js";
+import"../../../../chunk-fy3bbbqy.js";
+import"../../../../chunk-8d8w07a9.js";
+import"../../../../chunk-t5bt5vn1.js";
+import"../../../../chunk-eb4h4k1f.js";
+import"../../../../chunk-vx228eeq.js";
+import"../../../../chunk-sgd2126b.js";
+import"../../../../chunk-8vhr65w3.js";
+import"../../../../chunk-2njv7wz3.js";
+import"../../../../chunk-jdjagvgr.js";
+import"../../../../chunk-kfvq4m1s.js";
+import"../../../../chunk-zrbqn62x.js";
+import"../../../../chunk-mv74mq5n.js";
+import"../../../../chunk-q5e23acz.js";
+import"../../../../chunk-bx94rwt5.js";
+export {
+  CodeAgent2 as CodeAgent,
+  codeAgentDefinition2 as codeAgentDefinition
+};

package/build/lib/core/agents/specialized/codeAgent/prompts.d.ts

@@ -0,0 +1 @@
+export declare const CODE_AGENT_SYSTEM_PROMPT = "You are an expert coding agent with direct filesystem access. You will be given a specific objective \u2014 focus exclusively on completing it.\n\n# Tool Usage Guide\n\nYou have the following tools. Use them strategically to accomplish your objective:\n\n## read_file\nRead the contents of any file. You can read the whole file or a specific line range.\n- When a file is large, read it in chunks using startLine / endLine to stay focused.\n- Follow imports and references \u2014 when you see an interesting function call, read its source.\n\n## list_files\nList files and directories. Use this to orient yourself in the codebase.\n- Start by listing the project root or relevant subdirectory to understand the structure.\n- Use recursive=true sparingly on targeted subdirectories to avoid flooding context.\n\n## grep\nSearch file contents by pattern. This is your most powerful navigation tool.\n- Use it to find function definitions, usages, imports, and references.\n- Use -i for case-insensitive searches.\n- Use --include=\"*.ext\" to narrow to relevant file types.\n- Use -C 3 or -C 5 to get context around matches.\n- Use -rn (default for directories) for recursive search with line numbers.\n- Use -l to get just file paths when you need a broad overview of where something appears.\n\n## execute_command\nRun shell commands when needed.\n- Use for any task that benefits from shell access: build tools, git operations, package managers, linters, etc.\n- Useful for running scripts, checking dependencies, inspecting git history, or any CLI tool.\n\n## Whitebox security tools (when investigating vulnerabilities)\n- **profile_codebase** \u2014 summarize languages, manifests, scanners, and repo shape; full JSON is written as a session artifact.\n- **query_whitebox_catalog** \u2014 pull focused methodology slices (sinks, scanners, review passes) instead of loading a whole playbook into context.\n- **run_code_query** \u2014 batched rg / ast-grep / comby searches with bounded output and artifact logs.\n- **run_whitebox_scan** \u2014 run installed scanners when available; triage results before treating them as confirmed issues.\n- **create_whitebox_candidate / update_whitebox_candidate / list_whitebox_candidates** \u2014 track hypotheses with explicit state and evidence.\n- **start_whitebox_job / poll_whitebox_job / stop_whitebox_job** \u2014 bounded long-running jobs (builds, fuzzers) with logs under the session.\n- **read_whitebox_artifact** \u2014 read `logs/whitebox/` or `scratchpad/whitebox/` artifact paths returned by other tools (or legacy job logs by id).\n\nPrefer catalog + code_query for sink-first work; use candidates to separate unverified ideas from `document_vulnerability`. Do not modify the target repo unless the operator asked you to \u2014 keep harnesses and scratch output in the session scratchpad.\n\n# Working Approach\n1. **Orient first** \u2014 list files and read key entry points to understand the structure before diving in.\n2. **Search, then read** \u2014 use grep to locate what you need, then read the relevant files.\n3. **Follow the trail** \u2014 trace through imports, function calls, and references to build full understanding.\n4. **Stay focused** \u2014 stick to your objective. Don't wander into unrelated areas of the codebase.\n5. **Be thorough** \u2014 don't stop at the first match. Make sure you've covered everything relevant to the objective.\n";

package/build/lib/core/agents/specialized/codeAgent/schemas.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+/**
+ * Structured result returned by a CodeAgent that analyzes git diffs
+ * to determine which endpoints need re-testing.
+ */
+export declare const EndpointSelectionResultSchema: z.ZodObject<{
+    runAll: z.ZodBoolean;
+    affectedEndpointIds: z.ZodArray<z.ZodString>;
+    reasoning: z.ZodString;
+}, z.core.$strip>;
+export type EndpointSelectionResult = z.infer<typeof EndpointSelectionResultSchema>;

package/build/lib/core/agents/specialized/codeAgent/schemas.js

@@ -0,0 +1,10 @@
+// src/core/agents/specialized/codeAgent/schemas.ts
+import { z } from "zod";
+var EndpointSelectionResultSchema = z.object({
+  runAll: z.boolean().describe("If true, all endpoints should be tested (e.g. global config change, too many indirect effects to determine scope)."),
+  affectedEndpointIds: z.array(z.string()).describe("IDs of endpoints affected by the diff. Empty when runAll is true."),
+  reasoning: z.string().describe("Brief explanation of how the affected endpoints were determined.")
+});
+export {
+  EndpointSelectionResultSchema
+};

package/build/lib/core/agents/specialized/cvssScorer/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * CVSS 4.0 Scorer Subagent
+ *
+ * A specialized agent that analyzes vulnerability findings and their discovery context
+ * to determine appropriate CVSS 4.0 metrics and calculate scores.
+ *
+ * This agent is spawned by the document_vulnerability tool to provide standardized
+ * severity scoring based on the CVSS 4.0 specification.
+ */
+import type { LanguageModelMiddleware } from "ai";
+import { type CVSS4Metrics } from "../../../../lib/cvss";
+import { type ValidatedCweEntry } from "../../../../lib/cwe/types";
+import { type AIAuthConfig, type AIModel, type UsageRecorder } from "../../../ai";
+export interface CVSSScorerInput {
+    /** The finding to score */
+    finding: {
+        title: string;
+        description: string;
+        impact: string;
+        evidence: string;
+        endpoint: string;
+        vulnerabilityClass?: string;
+        remediation?: string;
+    };
+    /** Messages from the meta testing agent's conversation (for context) */
+    agentMessages: Record<string, unknown>[];
+}
+export interface CVSSScorerResult {
+    /** Numeric score (0.0-10.0) */
+    score: number;
+    /** Qualitative severity (NONE, LOW, MEDIUM, HIGH, CRITICAL) */
+    severity: string;
+    /** Full vector string (CVSS:4.0/AV:N/...) */
+    vectorString: string;
+    /** Individual metric values */
+    metrics: CVSS4Metrics;
+    /** Score type (CVSS-B, CVSS-BT, etc.) */
+    scoreType: string;
+    /** AI's reasoning for metric choices */
+    reasoning: string;
+    /** CWE classifications assigned to this vulnerability (validated against MITRE database) */
+    cwes: ValidatedCweEntry[];
+}
+/** Per-run model-call hooks forwarded to the scorer's structured-output call. */
+export interface CVSSScorerHooks {
+    languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
+    usageRecorder?: UsageRecorder;
+}
+/**
+ * Score a vulnerability finding with CVSS 4.0
+ *
+ * @param input - The finding data and conversation context
+ * @param model - The AI model to use for scoring
+ * @returns The CVSS 4.0 score with reasoning
+ */
+export declare function scoreFindingWithCVSS(input: CVSSScorerInput, model: AIModel, authConfig?: AIAuthConfig, abortSignal?: AbortSignal, sessionId?: string, hooks?: CVSSScorerHooks): Promise<CVSSScorerResult>;

package/build/lib/core/agents/specialized/environment/agent.d.ts

@@ -0,0 +1,43 @@
+import { AgentRuntime } from "../../agentRuntime";
+import { type EnvironmentAgentInput, type EnvironmentResult } from "./types";
+export declare const environmentAgentDefinition: import("../../defineAgent").AgentDefinition<EnvironmentAgentInput, {
+    url: string;
+    status: "failed" | "ready";
+    stepsTaken: string;
+    authenticationDetails: string;
+}, void>;
+/**
+ * A dev-environment setup agent that starts and validates development
+ * environments inside a sandbox.
+ *
+ * Shares the same filesystem and execution tools as {@link PatchingAgent}
+ * (`read_file`, `list_files`, `grep`, `create_file`, `update_file`,
+ * `execute_command`, `response`) but uses prompts tailored for DevOps tasks
+ * — Docker Compose assessment, dependency installation, service startup,
+ * and authentication testing.
+ *
+ * When an optional `sandbox` is provided, tools automatically route
+ * operations through the sandbox instead of the local filesystem.
+ *
+ * Returns a structured {@link EnvironmentResult} with the application URL,
+ * status, steps taken, and authentication details.
+ *
+ * @example
+ * ```ts
+ * const agent = new EnvironmentAgent({
+ *   cwd: "/tmp/cloned-repo",
+ *   model: "claude-sonnet-4-20250514",
+ *   session,
+ *   sandbox, // optional — tools route through sandbox when provided
+ *   config: { startCommand: "npm run dev" },
+ * });
+ *
+ * const result = await agent.consume({
+ *   onTextDelta: (d) => process.stdout.write(d.text),
+ * });
+ * // result.url, result.status, result.stepsTaken, result.authenticationDetails
+ * ```
+ */
+export declare class EnvironmentAgent extends AgentRuntime<EnvironmentAgentInput, EnvironmentResult> {
+    constructor(opts: EnvironmentAgentInput);
+}

package/build/lib/core/agents/specialized/environment/index.d.ts

@@ -0,0 +1,4 @@
+export { EnvironmentAgent } from "./agent";
+export { buildEnvironmentPrompt, buildEnvironmentSystemPrompt, ENVIRONMENT_SYSTEM_PROMPT, } from "./prompts";
+export type { DevEnvironmentConfig, EnvironmentAgentInput, EnvironmentResult, EnvironmentVariable, } from "./types";
+export { EnvironmentResultSchema } from "./types";

package/build/lib/core/agents/specialized/environment/prompts.d.ts

@@ -0,0 +1,10 @@
+import type { DevEnvironmentConfig } from "./types";
+/**
+ * Build the environment agent system prompt.
+ */
+export declare function buildEnvironmentSystemPrompt(): string;
+export declare const ENVIRONMENT_SYSTEM_PROMPT: string;
+/**
+ * Build the environment agent user prompt.
+ */
+export declare function buildEnvironmentPrompt(cwd: string, config?: DevEnvironmentConfig): string;

package/build/lib/core/agents/specialized/environment/types.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import type { SpecializedAgentInput } from "../../offSecAgent";
+/**
+ * Structured result returned by the environment agent via the `response` tool.
+ */
+export declare const EnvironmentResultSchema: z.ZodObject<{
+    url: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        ready: "ready";
+    }>;
+    stepsTaken: z.ZodString;
+    authenticationDetails: z.ZodString;
+}, z.core.$strip>;
+export type EnvironmentResult = z.infer<typeof EnvironmentResultSchema>;
+export interface EnvironmentVariable {
+    name: string;
+    value: string;
+}
+/**
+ * Configuration for the dev environment setup.
+ */
+export interface DevEnvironmentConfig {
+    startCommand?: string | null;
+    installCommand?: string | null;
+    devEnvironmentInstructions?: string | null;
+    environmentVariables?: EnvironmentVariable[];
+}
+/**
+ * Input for the EnvironmentAgent constructor.
+ */
+export interface EnvironmentAgentInput extends SpecializedAgentInput {
+    /** Root path of the cloned repository */
+    cwd: string;
+    /** Optional dev environment configuration hints */
+    config?: DevEnvironmentConfig;
+}

package/build/lib/core/agents/specialized/findingJudge/agent.d.ts

@@ -0,0 +1,22 @@
+import { AgentRuntime } from "../../agentRuntime";
+import type { SpecializedAgentInput } from "../../offSecAgent";
+import { type FindingJudgeAgentOutput, type FindingJudgeInput } from "./types";
+export interface FindingJudgeAgentInput extends SpecializedAgentInput {
+    finding: FindingJudgeInput;
+    target?: string;
+}
+export declare const findingJudgeDefinition: import("../../defineAgent").AgentDefinition<FindingJudgeAgentInput, {
+    valid: boolean;
+    findingType: "informational" | "vulnerability" | "expected-behavior";
+    confidence: number;
+    reasoning: string;
+    concerns: string[];
+    verificationSteps: string[];
+    toolEvidence: string[];
+    reproducedPoc: boolean;
+    webResearchUsed: boolean;
+    limitations: string[];
+}, void>;
+export declare class FindingJudgeAgent extends AgentRuntime<FindingJudgeAgentInput, FindingJudgeAgentOutput> {
+    constructor(opts: FindingJudgeAgentInput);
+}