@pensar/apex 2.5.0 → 2.6.1-canary.0cc77dcc

package/build/lib/core/agents/offSecAgent/types.d.ts

@@ -0,0 +1,543 @@
+import type { LanguageModelMiddleware, ModelMessage, StopCondition, StreamTextOnFinishCallback, StreamTextOnStepFinishCallback, StreamTextResult, ToolChoice, ToolSet } from "ai";
+import { z } from "zod";
+import type { AIAuthConfig, AIModel, CacheMetrics, InferenceRecorder, OpenAIReasoningEffort, ThinkingEffort, UsageRecorder } from "../../ai";
+import type { CredentialManager } from "../../credentials";
+import type { AgentEventBus } from "../../eventBus";
+import type { AttackSurfaceRegistry } from "../../findings/attackSurfaceRegistry";
+import type { FindingsRegistry } from "../../findings/registry";
+import type { ApprovalGate } from "../../operator";
+import type { PromptInjectionLibrary } from "../../prompt-injections";
+import type { RunContextRecorder } from "../../runtime/runContext";
+import type { ToolExecutionRecorder } from "../../runtime/runToolStore";
+import type { SessionConfig, SessionInfo } from "../../session";
+import type { SkillsRegistry } from "../../skills/registry";
+import type { ToolBackends } from "../../tools/backends/types";
+import type { GrpcPentestContext } from "../specialized/attackSurface/grpcSchema";
+import type { SubagentSpawner } from "./subagentSpawner";
+import type { BrowserEngine, PlaywrightMcpSession, ToolName, UnifiedSandbox } from "./tools";
+import type { EmailAdapterResolver } from "./tools/email/adapters";
+import type { SmsInbox } from "./tools/smsInbox";
+export declare const ApexFindingObject: z.ZodObject<{
+    title: z.ZodString;
+    severity: z.ZodPreprocess<z.ZodEnum<{
+        CRITICAL: "CRITICAL";
+        HIGH: "HIGH";
+        MEDIUM: "MEDIUM";
+        LOW: "LOW";
+    }>>;
+    description: z.ZodString;
+    impact: z.ZodString;
+    evidence: z.ZodString;
+    endpoint: z.ZodString;
+    pocPath: z.ZodString;
+    remediation: z.ZodString;
+    references: z.ZodOptional<z.ZodString>;
+    toolCallDescription: z.ZodOptional<z.ZodString>;
+    cwes: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        id: z.ZodString;
+        reasoning: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        reasoning: z.ZodString;
+    }, z.core.$strip>]>>>;
+    rootCauseGroup: z.ZodOptional<z.ZodString>;
+    relatedFindings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    rootCauseLead: z.ZodOptional<z.ZodBoolean>;
+    evidenceFiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        type: z.ZodEnum<{
+            "http-response": "http-response";
+            screenshot: "screenshot";
+            "poc-output": "poc-output";
+            "raw-evidence": "raw-evidence";
+        }>;
+        description: z.ZodString;
+    }, z.core.$strip>>>;
+    attackPath: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        applicationId: z.ZodOptional<z.ZodString>;
+        applicationName: z.ZodOptional<z.ZodString>;
+        host: z.ZodOptional<z.ZodString>;
+        relationshipType: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    credentialIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type Finding = Omit<z.infer<typeof ApexFindingObject>, "credentialIds"> & {
+    credentialIds?: string[];
+};
+/**
+ * Input for the general-purpose OffensiveSecurityAgent harness.
+ *
+ * The base agent owns tool creation — specific agents just declare
+ * which tools they need via `activeTools`.
+ *
+ * @typeParam TResult - The type returned by `consume()`. Defaults to `void`.
+ */
+/** Agent operating mode that controls which tools are available. */
+export type AgentMode = "default" | "plan" | "fast-strike";
+/** Structured authorization envelope for a multi-application System pentest. */
+export type SystemPentestScope = {
+    systemId: string;
+    memberHosts: string[];
+};
+/** Identifies which streamed event a {@link StreamIdFactory} is minting an id for. */
+export type StreamIdFactoryContext = {
+    kind: "message";
+    stepIndex: number;
+} | {
+    kind: "text-part";
+    stepIndex: number;
+    textPartIndex: number;
+} | {
+    kind: "tool-part";
+    toolCallId: string;
+};
+/**
+ * Mints message/part ids for streamed events. Defaults to random ULIDs
+ * ({@link newMessageId}/{@link newPartId}) when unset; a durable runtime injects
+ * a factory that derives deterministic, replay-stable ids from the context.
+ */
+export type StreamIdFactory = (context: StreamIdFactoryContext) => string;
+/**
+ * The hooks a host injects to control agent execution: tool
+ * backends, the sub-agent fan-out seam, model-call middleware/telemetry, the
+ * inbound-message transports, and the abort/extra-tools/sandbox escape
+ * hatches. Every specialized agent input extends this ONE type instead of
+ * re-declaring the fields, so a specialized agent can no longer drop a hook
+ * by forgetting to list it in a hand-written constructor.
+ */
+export interface AgentHooks {
+    /** Opt-in shared backend directory for incremental recon endpoint artifacts. */
+    attackSurfaceArtifactsPath?: string;
+    /** Execution backends for fs / command / http / browser / inbox. Unset means local execution. */
+    backends?: ToolBackends;
+    /** Seam through which orchestration tools spawn sub-agents. Unset → the in-process spawner. */
+    subagentSpawner?: SubagentSpawner;
+    /** Provider middleware applied only to this agent's model calls. Unset → raw model. */
+    languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
+    /** Records physical model attempts for this agent; never inherited by spawned agents. */
+    inferenceRecorder?: InferenceRecorder;
+    /** Recorded-run durable context authority. Unset → no canonical persistence. */
+    contextRecorder?: RunContextRecorder;
+    /** Recorded-run tool journal. Unset → tool executes are never wrapped. */
+    toolExecutionRecorder?: ToolExecutionRecorder;
+    /** Per-run usage recorder. Unset → the process-global usage callback fires as today. */
+    usageRecorder?: UsageRecorder;
+    /** Factory for streamed message/part ids. Unset → random ULIDs, unchanged. */
+    streamIdFactory?: StreamIdFactory;
+    /** Transport for inbound SMS reads. Unset → the Console agent API over HTTP. */
+    smsInbox?: SmsInbox;
+    /** Supplies an adapter for a `pensar-managed` inbox. Unset → the config-driven factory. */
+    emailAdapterFor?: EmailAdapterResolver;
+    /** AbortSignal to cancel the agent mid-run. */
+    abortSignal?: AbortSignal;
+    /** Additional tools merged on top of the built-in toolset. */
+    extraTools?: ToolSet;
+    /** When set, tools route execution through this sandbox instead of running locally. */
+    sandbox?: UnifiedSandbox;
+}
+export type OffensiveSecurityAgentInput<TResult = void> = AgentHooks & {
+    attackSurfaceArtifactsPath?: string;
+    /** System prompt defining agent persona and behavior. Defaults to BASE_SYSTEM_PROMPT when omitted. */
+    system?: string;
+    /** Initial user prompt that kicks off the agent */
+    prompt: string;
+    /** AI model identifier */
+    model: AIModel;
+    /**
+     * Operating mode that controls which tools are available.
+     *
+     * - `"default"` — all tools in `activeTools` are available (default)
+     * - `"plan"` — only read-only / non-mutating tools are available
+     * - `"fast-strike"` — live registry minus {@link FAST_STRIKE_EXCLUDED_TOOL_NAMES}; ignores `activeTools`
+     *
+     * When set to `"plan"`, the agent's `activeTools` are intersected with
+     * {@link PLAN_MODE_TOOL_NAMES} so that mutation tools (create_file,
+     * update_file, document_vulnerability, document_app,
+     * document_endpoint) are excluded.
+     *
+     * @default "default"
+     */
+    mode?: AgentMode;
+    /** Session providing paths for findings, POCs, logs, etc. */
+    session: SessionInfo;
+    /**
+     * Explicit working directory for this agent instance. Overrides
+     * `session.config.agentCwd`; defaults to `session.rootPath`. Drives command
+     * cwd and relative-path resolution for tools that have no
+     * {@link OffensiveSecurityAgentInput.fileWorkspaceRoot}.
+     */
+    agentCwd?: string;
+    /**
+     * Root that scopes this agent's native file tools when resolving relative
+     * paths and enforcing confinement. File-tool scoping only — command cwd and
+     * shell/OS permissions are not restricted by this value.
+     */
+    fileWorkspaceRoot?: string;
+    /** The target URL / host — passed to browser tools for context */
+    target?: string;
+    /**
+     * gRPC context when the target is a gRPC method rather than an HTTP
+     * endpoint. Forwarded into the {@link ToolContext} so `spawn_pentest_agent`
+     * can hand it down to spawned workers.
+     */
+    grpc?: GrpcPentestContext;
+    /** Structured multi-application scope forwarded to pentest workers. */
+    systemScope?: SystemPentestScope;
+    /**
+     * Which tools the agent is allowed to use.
+     *
+     * Accepts both built-in tool names and custom tool names (from `extraTools`).
+     * This array controls which tools the model can see and invoke
+     * (maps to the AI SDK `activeTools`).
+     */
+    activeTools: (ToolName | (string & {}))[];
+    /**
+     * Additional tools to merge into the toolset.
+     *
+     * Use this to inject agent-specific tools (e.g. a structured response
+     * tool) without modifying the shared tool registry. These are merged
+     * on top of the built-in tools created by `createAllTools`.
+     */
+    extraTools?: ToolSet;
+    /** Existing conversation history (for resumption / multi-turn) */
+    messages?: Array<ModelMessage>;
+    /** Condition(s) under which the agent should stop */
+    stopWhen?: StopCondition<NoInfer<ToolSet>> | StopCondition<NoInfer<ToolSet>>[];
+    /** Strategy for selecting which tool to call */
+    toolChoice?: ToolChoice<ToolSet>;
+    /** Callback fired after each agent step completes */
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+    /** Provider middleware applied only to this agent's model calls. Unset → raw model. */
+    languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
+    /** Per-run usage recorder. Unset → the process-global usage callback fires as today. */
+    usageRecorder?: UsageRecorder;
+    /** Factory for streamed message/part ids. Unset → random ULIDs, unchanged. */
+    streamIdFactory?: StreamIdFactory;
+    /** Callback fired when the entire stream finishes */
+    onFinish?: StreamTextOnFinishCallback<ToolSet>;
+    /** Called when Anthropic cache metrics are present in a step's providerMetadata */
+    onCacheMetrics?: (metrics: CacheMetrics) => void;
+    /**
+     * Forward usage callbacks through tools that spawn agents. Enable only when
+     * the caller does not already account for subagents from trace events.
+     */
+    forwardUsageCallbacksToSpawnedAgents?: boolean;
+    /** AbortSignal to cancel the agent mid-run */
+    abortSignal?: AbortSignal;
+    /** Per-provider API key overrides */
+    authConfig?: AIAuthConfig;
+    /**
+     * When set, tools like execute_command / http_request / document_vulnerability
+     * route execution through this sandbox instead of running locally.
+     */
+    sandbox?: UnifiedSandbox;
+    /**
+     * Execution backends for fs / command / http / browser / inbox, forwarded into the
+     * {@link ToolContext}. Unset means local execution; a durable runtime injects
+     * sandbox-backed implementations.
+     */
+    backends?: ToolBackends;
+    /**
+     * Seam through which orchestration tools spawn sub-agents. Forwarded into the
+     * {@link ToolContext}; unset → tools use the in-process spawner.
+     */
+    subagentSpawner?: SubagentSpawner;
+    /**
+     * Transport for inbound SMS reads. Forwarded into the {@link ToolContext};
+     * unset → the Console agent API over HTTP, which needs sandbox dispatch.
+     */
+    smsInbox?: SmsInbox;
+    /**
+     * Supplies an adapter for a `pensar-managed` inbox, forwarded into the
+     * ToolContext. Unset → the config-driven factory, which rejects that provider.
+     */
+    emailAdapterFor?: EmailAdapterResolver;
+    /**
+     * Shared findings registry for cross-agent dedup.
+     * When present, `document_vulnerability` checks for duplicates before writing.
+     */
+    findingsRegistry?: FindingsRegistry;
+    /**
+     * Shared attack surface registry for cross-agent asset dedup.
+     * When present, `document_endpoint` checks for duplicates before writing.
+     */
+    attackSurfaceRegistry?: AttackSurfaceRegistry;
+    /**
+     * In-memory credential store. When present, tools resolve credential
+     * IDs to secrets at execution time and prompt builders emit only
+     * safe {@link CredentialReference} metadata — the agent never sees
+     * raw passwords, tokens, or API keys.
+     */
+    credentialManager?: CredentialManager;
+    /**
+     * Called after the stream is fully consumed to produce a typed result.
+     *
+     * Receives the completed `StreamTextResult` — at this point all lazy
+     * properties (`.steps`, `.text`, `.response`, etc.) are resolved.
+     *
+     * If omitted, `consume()` returns `void`.
+     */
+    resolveResult?: (streamResult: StreamTextResult<ToolSet, never>) => TResult | Promise<TResult>;
+    /** The subagent ID if this agent is a subagent */
+    subagentId?: string;
+    /** Display label for the OTel span name / `gen_ai.agent.name`. */
+    subagentName?: string;
+    /**
+     * Override the auto-computed task directory. When set, takes precedence
+     * over the directory derived from `subagentId`. Use this when a plan
+     * agent needs to write tasks to the execution agent's task directory.
+     */
+    tasksDir?: string;
+    /**
+     * Override for plan file scoping. When set, write_plan uses this ID
+     * instead of `subagentId` to derive the plan file path, allowing
+     * plan agents to write plans scoped to their corresponding execution agent.
+     */
+    planSubagentId?: string;
+    /**
+     * Event bus for streaming agent output.
+     *
+     * When provided, the agent emits all streaming events (text deltas,
+     * tool calls, tool results, errors) on this bus. Multiple consumers
+     * can subscribe independently — TUI, DB persistence, metrics, etc.
+     *
+     * The bus is also passed through to tools so orchestration tools
+     * (run_attack_surface, spawn_pentest_swarm) can emit subagent events
+     * on the same bus.
+     *
+     * When omitted, a fresh bus is created internally — callers can access
+     * it via `agent.eventBus` after construction.
+     */
+    eventBus?: AgentEventBus;
+    /**
+     * Zod schema for structured output via the `response` tool.
+     *
+     * When provided, the base class automatically:
+     * 1. Creates and injects a `response` tool with this schema
+     * 2. Merges `hasToolCall("response")` into the stop conditions
+     * 3. Defaults `resolveResult` to return the captured structured data
+     *
+     * Specialized agents just set this and include `"response"` in
+     * `activeTools` to get typed structured output from `consume()`.
+     */
+    responseSchema?: z.ZodSchema;
+    /**
+     * Skills registry for on-demand skill loading.
+     * When provided, read_skill is available.
+     */
+    skillsRegistry?: SkillsRegistry;
+    /**
+     * Runtime-only prompt-injection library. Raw payloads are resolved inside
+     * trusted tool execution paths, not in prompts or model-visible messages.
+     */
+    promptInjectionLibrary?: PromptInjectionLibrary;
+    /**
+     * Local filesystem path for a prompt-injection payload library. Falls back
+     * to PENSAR_PROMPT_INJECTION_LIBRARY / APEX_PROMPT_INJECTION_LIBRARY.
+     */
+    promptInjectionLibrarySource?: string;
+    /**
+     * When provided, each tool call is gated through the approval gate.
+     * The gate will pause execution until the operator approves or denies
+     * the call (when `requireApproval` is enabled on the gate).
+     */
+    approvalGate?: ApprovalGate;
+    /**
+     * Directory where `messages.json` is persisted after each step.
+     * Defaults to `session.rootPath`.
+     */
+    messagesDir?: string;
+    /**
+     * Mutable handle the agent populates so the caller can cancel the
+     * currently running shell command without killing the agent.
+     */
+    commandCancelHandle?: CommandCancelHandle;
+    /**
+     * Environment variables to inject into the agent's per-command executor.
+     * Each key-value pair is set in every invocation's process environment,
+     * so they're available to every `execute_command` call. Scoped to this
+     * agent instance — other agents on the same machine never see them.
+     */
+    environmentVariables?: Record<string, string>;
+    /** Secret values to scrub from execute_command output. Forwarded into the {@link ToolContext}. */
+    secretValues?: string[];
+    /** Enable extended thinking (reasoning) for supported models. */
+    enableThinking?: boolean;
+    /** Adaptive-thinking effort hint (Anthropic Opus/Sonnet 4.6+); ignored elsewhere. */
+    thinkingEffort?: ThinkingEffort | null;
+    /** OpenAI reasoning effort for GPT/o-series reasoning models. */
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+    /**
+     * Whitebox attack surface flag forwarded into the {@link ToolContext} for
+     * orchestrator-driven pentests. Defaults to `true` when undefined.
+     */
+    surfaceIntegrationEnabled?: boolean;
+    /**
+     * Project-level threat model content (e.g. from `.pensar/threat_model.md`).
+     * Forwarded into the {@link ToolContext} so tools that spawn dedicated
+     * per-endpoint threat-model sub-agents can include this as additional
+     * grounding context.
+     */
+    projectThreatModel?: string;
+    /**
+     * Pre-constructed Playwright MCP browser session to use for this agent
+     * instead of constructing a fresh one. Used by `spawn_pentest_agent` to
+     * hand a worker a freshly-cloned-and-seeded session — fresh Chromium,
+     * own MCP child-process, but pre-loaded with a snapshot of the
+     * orchestrator's cookies + per-origin localStorage so the worker is
+     * already authenticated for the same origins the orchestrator was.
+     *
+     * The agent does NOT share this session with any other agent at runtime
+     * — each agent owns its own isolated Chromium and a sub-agent's
+     * browser-side mutations (navigations, `localStorage.setItem`,
+     * `browser_evaluate` calls, alerts, etc.) never leak back into the
+     * caller's browser. Lifecycle of an externally-supplied session belongs
+     * to whoever supplied it (e.g. `spawn_pentest_agent` disconnects the
+     * worker session on completion).
+     */
+    browserSession?: PlaywrightMcpSession;
+    /**
+     * X display (e.g. `":11"`) for this agent's browser. Overrides
+     * `process.env.DISPLAY` for the session this agent constructs, so several
+     * headed agents in one process (concurrent per-endpoint pentests) each run
+     * on their own virtual desktop. Ignored when `browserSession` is supplied
+     * (that session already owns its display). Omit to fall back to the
+     * process-wide `DISPLAY`.
+     */
+    display?: string;
+    /**
+     * Browser engine for the session this agent constructs. Chrome is required
+     * for Sign in with Google; Camoufox is the default. Ignored when
+     * `browserSession` is supplied.
+     */
+    browserEngine?: BrowserEngine;
+};
+/**
+ * Mutable handle for cancelling the running shell command.
+ * The agent populates `cancel` at construction time; the caller invokes it.
+ */
+export type CommandCancelHandle = {
+    cancel: () => boolean;
+};
+/**
+ * Shared input fields for all specialized agents.
+ *
+ * Specialized agent input interfaces should extend this to inherit
+ * the common harness fields, then add only their agent-specific ones.
+ *
+ * Extends {@link AgentHooks} rather than re-declaring `backends` /
+ * `subagentSpawner` / `languageModelMiddleware` / `usageRecorder` /
+ * `streamIdFactory` / `smsInbox` / `emailAdapterFor` / `abortSignal` /
+ * `extraTools` / `sandbox` — that was the drop bug: a
+ * hand-rolled copy of this list silently omitted a field, and every hook
+ * lived past the constructor that forgot to forward it.
+ */
+export interface SpecializedAgentInput extends AgentHooks {
+    /** AI model to drive the agent */
+    model: AIModel;
+    /** Session providing paths for findings, POCs, logs, etc. */
+    session: SessionInfo;
+    /** Optional per-provider API key overrides */
+    authConfig?: AIAuthConfig;
+    /** Existing conversation history for resumption */
+    messages?: Array<ModelMessage>;
+    /** Callback fired after each agent step */
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+    /** Called when Anthropic cache metrics are present in a step's providerMetadata */
+    onCacheMetrics?: (metrics: CacheMetrics) => void;
+    /** Event bus for streaming agent output */
+    eventBus?: AgentEventBus;
+    /**
+     * When set, stream chunks emitted during {@link OffensiveSecurityAgent.consume}
+     * are tagged with this id on the event bus (for multi-agent UIs).
+     */
+    subagentId?: string;
+    /** Display label forwarded to {@link OffensiveSecurityAgentInput} for span names. */
+    subagentName?: string;
+    /** Shared findings registry for cross-agent dedup */
+    findingsRegistry?: FindingsRegistry;
+    /** Shared attack surface registry for cross-agent asset dedup */
+    attackSurfaceRegistry?: AttackSurfaceRegistry;
+    /** In-memory credential store for secret-free agent prompts */
+    credentialManager?: CredentialManager;
+    /** Override the default stop condition */
+    stopWhen?: StopCondition<ToolSet>;
+    /**
+     * Environment variables to inject into the agent's per-command executor.
+     * Forwarded to the underlying {@link OffensiveSecurityAgentInput}.
+     */
+    environmentVariables?: Record<string, string>;
+    /** Secret values to scrub from execute_command output. Forwarded into the {@link ToolContext}. */
+    secretValues?: string[];
+    /** Enable extended thinking (reasoning) for supported models. */
+    enableThinking?: boolean;
+    /** Adaptive-thinking effort hint (Anthropic Opus/Sonnet 4.6+); ignored elsewhere. */
+    thinkingEffort?: ThinkingEffort | null;
+    /** OpenAI reasoning effort for GPT/o-series reasoning models. */
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+    /**
+     * Whitebox attack surface flag forwarded into the {@link ToolContext} for
+     * orchestrator-driven pentests. Defaults to `true` when undefined.
+     */
+    surfaceIntegrationEnabled?: boolean;
+    /**
+     * Project-level threat model content. Forwarded into {@link ToolContext}
+     * so per-endpoint threat-model sub-agents can incorporate it as grounding.
+     */
+    projectThreatModel?: string;
+    /**
+     * Pre-constructed Playwright MCP browser session for this sub-agent —
+     * typically a freshly-cloned-and-seeded session built by
+     * `spawn_pentest_agent` so the worker inherits the orchestrator's
+     * cookies + localStorage but operates against its OWN isolated Chromium
+     * (so its browser mutations don't leak back to the orchestrator or to
+     * sibling workers). Forwarded to the underlying
+     * {@link OffensiveSecurityAgentInput}.
+     */
+    browserSession?: PlaywrightMcpSession;
+    /**
+     * X display (e.g. `":11"`) for this agent's browser, forwarded to the
+     * underlying {@link OffensiveSecurityAgentInput} so concurrent per-endpoint
+     * pentests can each run headed on their own virtual desktop.
+     */
+    display?: string;
+    /**
+     * Browser engine forwarded to {@link OffensiveSecurityAgentInput}. Chrome
+     * when any session credential is Sign in with Google; Camoufox otherwise.
+     */
+    browserEngine?: BrowserEngine;
+    /** Target URL/host forwarded to {@link OffensiveSecurityAgentInput}. */
+    target?: string;
+    /** gRPC context forwarded to {@link OffensiveSecurityAgentInput}. */
+    grpc?: GrpcPentestContext;
+    /** Explicit working directory forwarded to {@link OffensiveSecurityAgentInput}. */
+    agentCwd?: string;
+    /** File-tool workspace root forwarded to {@link OffensiveSecurityAgentInput}. */
+    fileWorkspaceRoot?: string;
+    /** Structured multi-application scope forwarded to {@link OffensiveSecurityAgentInput}. */
+    systemScope?: SystemPentestScope;
+    /** Harness operating mode forwarded to {@link OffensiveSecurityAgentInput}. */
+    mode?: AgentMode;
+}
+/**
+ * Input for the `OffensiveSecurityAgent.create()` async factory.
+ *
+ * Identical to {@link OffensiveSecurityAgentInput} except `session` is
+ * optional. When omitted, the factory creates a new session automatically
+ * using the remaining fields.
+ *
+ * Pass an existing `session` to reuse one (e.g. from the console API or
+ * when spawning subagents).
+ */
+export type CreateAgentInput<TResult = void> = Omit<OffensiveSecurityAgentInput<TResult>, "session" | "system"> & {
+    /** Existing session to reuse. When omitted a new one is created. */
+    session?: SessionInfo;
+    /** Session config used when auto-creating a session (ignored when `session` is provided). */
+    sessionConfig?: SessionConfig;
+    /** System prompt override. When omitted, BASE_SYSTEM_PROMPT is used. The session workspace section is always appended. */
+    system?: string;
+    /** Called when the async AI name generation resolves with a name. */
+    onNameGenerated?: (name: string) => void;
+};

package/build/lib/core/agents/offSecAgent/types.js

@@ -0,0 +1,7 @@
+import {
+  ApexFindingObject2
+} from "../../../chunk-q5e23acz.js";
+import"../../../chunk-bx94rwt5.js";
+export {
+  ApexFindingObject2 as ApexFindingObject
+};

package/build/lib/core/agents/specialized/attackSurface/blackboxAgent.d.ts

@@ -0,0 +1,66 @@
+import type { SessionInfo } from "../../../session";
+import { AgentRuntime } from "../../agentRuntime";
+import type { SpecializedAgentInput } from "../../offSecAgent";
+import type { AttackSurfaceAnalysisResults, PentestTarget } from "./types";
+/** At least one of `target` or `cwd` must be provided. */
+export type AttackSurfaceAgentInput = SpecializedAgentInput & ({
+    /** The target to analyze (domain, IP, URL, network range, or org name) */
+    target: string;
+    cwd?: string;
+} | {
+    target?: string;
+    /** Working directory for source-code based analysis */
+    cwd: string;
+}) & {
+    /**
+     * Whitebox-only: when false, the workflow skips the `@pensar/surface`
+     * deterministic-enumeration path and uses the legacy pages+apiEndpoints
+     * discovery agents. Defaults to `true`. Has no effect on blackbox runs.
+     */
+    surfaceIntegrationEnabled?: boolean;
+};
+/** The typed result returned by `AttackSurfaceAgent.consume()`. */
+export interface AttackSurfaceResult {
+    /** The full analysis results (targets, assets, key findings) */
+    results: AttackSurfaceAnalysisResults | null;
+    /** All targets identified for deep penetration testing */
+    targets: PentestTarget[];
+    /** Absolute path to the attack-surface-results.json file */
+    resultsPath: string;
+    /** Absolute path to the session's assets directory */
+    assetsPath: string;
+}
+interface BlackboxState {
+    target: string;
+    subagentFolder: string;
+}
+export declare const blackboxAttackSurfaceDefinition: import("../../defineAgent").AgentDefinition<AttackSurfaceAgentInput, AttackSurfaceResult, BlackboxState>;
+/**
+ * A recon-focused specialisation of {@link OffensiveSecurityAgent}.
+ *
+ * Maps the entire attack surface of a target — discovers assets, endpoints,
+ * authentication flows, and produces a list of targets for deep testing.
+ *
+ * `consume()` returns an {@link AttackSurfaceResult} with the full analysis.
+ *
+ * @example
+ * ```ts
+ * const agent = new AttackSurfaceAgent({
+ *   target: "https://example.com",
+ *   model: "claude-sonnet-4-20250514",
+ *   session,
+ * });
+ *
+ * const { targets, results } = await agent.consume({
+ *   onTextDelta: (d) => process.stdout.write(d.text),
+ *   onToolCall:  (d) => console.log(`→ ${d.toolName}`),
+ * });
+ *
+ * console.log(`Identified ${targets.length} targets for deep testing`);
+ * ```
+ */
+export declare class BlackboxAttackSurfaceAgent extends AgentRuntime<AttackSurfaceAgentInput, AttackSurfaceResult, BlackboxState> {
+    constructor(opts: AttackSurfaceAgentInput);
+}
+export declare function buildBlackboxPrompt(target: string, session: SessionInfo): string;
+export {};

package/build/lib/core/agents/specialized/attackSurface/blackboxAgent.js

@@ -0,0 +1,33 @@
+import {
+  blackboxAttackSurfaceDefinition2,
+  BlackboxAttackSurfaceAgent2,
+  buildBlackboxPrompt2
+} from "../../../../chunk-mp1czx2y.js";
+import"../../../../chunk-vt9spgd1.js";
+import"../../../../chunk-g8d2x00m.js";
+import"../../../../chunk-f04pr76h.js";
+import"../../../../chunk-517rf135.js";
+import"../../../../chunk-7gjdygcx.js";
+import"../../../../chunk-b8eq85d2.js";
+import"../../../../chunk-wr6ke041.js";
+import"../../../../chunk-ja7j565c.js";
+import"../../../../chunk-3q89v4xv.js";
+import"../../../../chunk-fy3bbbqy.js";
+import"../../../../chunk-02awpt3c.js";
+import"../../../../chunk-t5bt5vn1.js";
+import"../../../../chunk-eb4h4k1f.js";
+import"../../../../chunk-vx228eeq.js";
+import"../../../../chunk-3502z798.js";
+import"../../../../chunk-8vhr65w3.js";
+import"../../../../chunk-2njv7wz3.js";
+import"../../../../chunk-jdjagvgr.js";
+import"../../../../chunk-3w05jmk6.js";
+import"../../../../chunk-zrbqn62x.js";
+import"../../../../chunk-mv74mq5n.js";
+import"../../../../chunk-q5e23acz.js";
+import"../../../../chunk-bx94rwt5.js";
+export {
+  BlackboxAttackSurfaceAgent2 as BlackboxAttackSurfaceAgent,
+  blackboxAttackSurfaceDefinition2 as blackboxAttackSurfaceDefinition,
+  buildBlackboxPrompt2 as buildBlackboxPrompt
+};

package/build/lib/core/agents/specialized/attackSurface/blackboxRiskScoring.d.ts

@@ -0,0 +1,30 @@
+import type { RiskScore } from "../whiteboxAttackSurface";
+import type { RiskLevel } from "./schemas";
+interface EndpointDetails {
+    url?: string;
+    method?: string | string[];
+    authentication?: string;
+    authRequired?: boolean;
+    handler?: string;
+    file?: string;
+    line?: number;
+    services?: string[];
+    technology?: string[];
+    status?: string | number;
+    [key: string]: unknown;
+}
+/**
+ * Compute a heuristic {@link RiskScore} for a blackbox-discovered asset.
+ *
+ * Since there is no source code to read, we derive the four breakdown
+ * dimensions from the agent-assigned `riskLevel`, the `assetType`, and
+ * observable metadata (authentication, services, technology stack).
+ *
+ * The breakdown dimensions match the whitebox model:
+ *   - **exposure** (0-3): How reachable is the asset from the outside?
+ *   - **dataSensitivity** (0-3): How sensitive is the data it likely handles?
+ *   - **functionCriticality** (0-2): How critical is the business function?
+ *   - **securityIndicators** (0-2): Are there observable security concerns?
+ */
+export declare function computeBlackboxRiskScore(riskLevel: RiskLevel, assetType: string, details?: EndpointDetails, notes?: string): RiskScore;
+export {};