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

package/build/lib/core/whitebox/types.d.ts

@@ -0,0 +1,108 @@
+export declare const WHITEBOX_ARTIFACT_TYPES: readonly ["repo-profile", "static-scan", "code-query", "source-trace", "candidate", "job-log", "fuzz-harness", "fuzz-crash", "build-log", "raw-output"];
+export type WhiteboxArtifactType = (typeof WHITEBOX_ARTIFACT_TYPES)[number];
+export type WhiteboxArtifactRef = {
+    path: string;
+    type: WhiteboxArtifactType;
+    description: string;
+};
+export declare const WHITEBOX_CANDIDATE_STATES: readonly ["hypothesis", "investigating", "repro_attempted", "confirmed", "rejected", "deferred"];
+export type WhiteboxCandidateState = (typeof WHITEBOX_CANDIDATE_STATES)[number];
+export type SourceLocation = {
+    file: string;
+    line?: number;
+    symbol?: string;
+};
+export type SourceTrace = {
+    source?: SourceLocation;
+    sink?: SourceLocation;
+    path?: SourceLocation[];
+    notes?: string;
+};
+export type WhiteboxCandidate = {
+    id: string;
+    title: string;
+    vulnerabilityClass: string;
+    state: WhiteboxCandidateState;
+    confidence: "low" | "medium" | "high";
+    summary: string;
+    sourceTrace?: SourceTrace;
+    artifacts: WhiteboxArtifactRef[];
+    verification?: {
+        strategy: string;
+        status: "not_started" | "running" | "failed" | "succeeded";
+        notes?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+};
+export type LanguageId = "typescript" | "javascript" | "python" | "go" | "rust" | "java" | "kotlin" | "ruby" | "php" | "c" | "cpp" | "csharp" | "unknown";
+export type PackageManagerId = "bun" | "npm" | "yarn" | "pnpm" | "pip" | "poetry" | "cargo" | "go" | "maven" | "gradle" | "bundler" | "composer" | "dotnet";
+export type ToolAvailability = {
+    name: string;
+    available: boolean;
+    path?: string;
+};
+export type RepoProfile = {
+    rootPath: string;
+    currentCommit?: string;
+    languages: LanguageId[];
+    packageManagers: PackageManagerId[];
+    manifestFiles: string[];
+    lockfiles: string[];
+    buildCommands: string[];
+    testCommands: string[];
+    runCommands: string[];
+    entryPointHints: string[];
+    iacFiles: string[];
+    ciFiles: string[];
+    nativeCode: boolean;
+    submodules: string[];
+    excludedDirs: string[];
+    toolAvailability: ToolAvailability[];
+};
+export type CatalogRecordKind = "entry-point" | "trust-boundary" | "sink" | "scanner" | "fuzzer" | "review-pass" | "verification";
+export type CatalogRecord = {
+    id: string;
+    kind: CatalogRecordKind;
+    title: string;
+    languages?: LanguageId[];
+    tags: string[];
+    patterns?: string[];
+    tools?: string[];
+    guidance: string;
+};
+export type CatalogSelection = {
+    records: CatalogRecord[];
+    recommendedPasses: CatalogRecord[];
+};
+export type ScanKind = "static" | "secrets" | "dependencies" | "iac" | "repo-intelligence" | "fuzzing";
+export type ScanFindingSummary = {
+    tool: string;
+    severity?: string;
+    title: string;
+    location?: SourceLocation;
+    description?: string;
+};
+export type ScanRunResult = {
+    scanner: string;
+    command: string[];
+    exitCode: number | null;
+    findings: ScanFindingSummary[];
+    artifact: WhiteboxArtifactRef;
+    /** True when stdout/stderr capture hit the byte cap before the process ended. */
+    outputTruncated?: boolean;
+    /** True when the scanner hit the wall-clock timeout (exit code 124). */
+    timedOut?: boolean;
+};
+export type WhiteboxJobStatus = "running" | "completed" | "failed" | "timed_out" | "stopped";
+export type WhiteboxJobRecord = {
+    id: string;
+    command: string;
+    cwd: string;
+    logPath: string;
+    startedAt: string;
+    updatedAt: string;
+    timeoutSeconds: number;
+    status: WhiteboxJobStatus;
+    exitCode?: number | null;
+};

package/build/lib/core/workflows/fastStrike.d.ts

@@ -0,0 +1,4 @@
+import type { PentestWorkflowInput, PentestWorkflowResult } from "./pentest";
+export declare const FAST_STRIKE_SYSTEM_PROMPT = "You are an elite offensive security operator running a fast strike against a single target. You work ALONE and finish the job yourself \u2014 there is no team to hand off to, no swarm to spawn, no plan to file. Your edge is discipline and observation, not volume.\n\nRun this loop, tightly:\n\n1. OBSERVE \u2014 Read every response for signal before you act. Note the stack, headers, cookies, tokens, form fields, error messages, redirects, disabled controls, ID patterns. State what you just learned in one line before the next move.\n2. HYPOTHESIZE \u2014 From that signal and your deep knowledge of web/app vulnerability classes, name the single most likely vulnerability and why the evidence points to it. Rank leads by signal strength and go for the strongest first. A disabled form field, an ID in a URL or JWT, advertised demo creds, an exposed schema \u2014 these are tells; read them.\n3. ACT \u2014 Test that one hypothesis with the strongest available technique. Use direct tools for quick probes, but treat the shell as a working environment rather than merely a way to issue one-off commands. When the work becomes stateful, repetitive, concurrent, protocol-heavy, or multi-stage, externalize it into an editable script in the session scratchpad directory identified in the workspace instructions. Never create a scratchpad/ directory inside the target repository. Run the script, inspect the results, modify it, and rerun it as the attack develops. For blind/out-of-band testing (SSRF, blind RCE, XSS callbacks), start_callback_listener gives you a nonce-correlated listener that survives intervening commands: embed the returned callback URL (only an address you know the target can reach \u2014 never a guessed one) in the payload, then poll_callback_listener for hits. Listener readiness and the tool's own self-test never count as target evidence; stop_callback_listener when done.\n4. PRUNE \u2014 If the evidence disproves a lead, drop it and move to the next-strongest. Do NOT re-run a disproven approach or grind a dead end. Do NOT enumerate, brute-force, or run wordlists unless a specific signal demands it \u2014 choose techniques from evidence, not from a checklist.\n5. EXPLOIT \u2014 When a vulnerability is confirmed, exploit it: capture the flag, extract the sensitive data, and pivot through it if the objective requires more. Preserve viable primitives and build on them. Prefer extending a working script into an end-to-end exploit over rebuilding the chain with repeated one-off tool calls or stopping at the next network or protocol boundary.\n6. DOCUMENT & FINISH \u2014 Record each confirmed vulnerability with the document_vulnerability tool as you go. Before concluding that every credible lead is exhausted, account for each viable primitive and pursue any concrete path that could still close the objective. After this check, whether the objective was met or every credible lead was genuinely exhausted, call the response tool with the correct solved value and a concise summary.\n\nRules:\n- You are one operator. Plan in your head and in short text notes \u2014 never via planning tools, task lists, or sub-agents.\n- Recon and exploitation are the same loop. Do just enough recon to form the first hypothesis, then start testing. Do not map the entire surface before acting.\n- Spend your reasoning on choosing techniques and interpreting evidence; use scripts for deterministic mechanics, iteration, and chain execution.\n- Bias toward the shortest path that proves impact. Speed comes from picking the right lead, not from skipping verification \u2014 always confirm a finding before you claim it.\n- Stay in scope. Only touch the target you were given and hosts it legitimately depends on.";
+/** Single-operator pentest: skips attack-surface/swarm, returns {@link PentestWorkflowResult}. */
+export declare function runFastStrike(input: PentestWorkflowInput): Promise<PentestWorkflowResult>;

package/build/lib/core/workflows/pentest.d.ts

@@ -0,0 +1,167 @@
+import type { LanguageModelMiddleware, StreamTextOnStepFinishCallback, ToolSet } from "ai";
+import type { AgentHooks, Finding } from "../agents/offSecAgent";
+import { type SubagentSpawner } from "../agents/offSecAgent/subagentSpawner";
+import type { StreamIdFactory } from "../agents/offSecAgent/types";
+import type { PentestResult } from "../agents/specialized/pentest/agent";
+import type { AIAuthConfig, AIModel, CacheMetrics, OpenAIReasoningEffort, ThinkingEffort, UsageRecorder } from "../ai";
+import type { AgentEventBus } from "../eventBus";
+import { FindingsRegistry } from "../findings/registry";
+import type { SessionInfo } from "../session";
+import { type AgentManifestEntry, type SwarmTarget } from "../session/persistence";
+import { type WorkflowSeams } from "./seams";
+export declare const DEFAULT_CONCURRENCY = 10;
+export interface PentestWorkflowInput {
+    /** Live target URL — always required */
+    target: string;
+    /** Local codebase path — when provided, enables whitebox attack surface */
+    cwd?: string;
+    model: AIModel;
+    session: SessionInfo;
+    authConfig?: AIAuthConfig;
+    abortSignal?: AbortSignal;
+    eventBus?: AgentEventBus;
+    /** Callback fired after each agent step completes */
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+    /** Called when Anthropic cache metrics are present in a step's providerMetadata */
+    onCacheMetrics?: (metrics: CacheMetrics) => void;
+    /** Enable extended thinking 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;
+    /** Optional guidance prompt injected into discovery agent system prompts */
+    prompt?: string;
+    /** Optional raw threat model content — wrapped with standard preamble and
+     *  injected into discovery agent system prompts alongside `prompt` */
+    threatModel?: string;
+    /**
+     * Whitebox-only: when false, the attack surface workflow skips the
+     * `@pensar/surface` deterministic-enumeration path and uses the legacy
+     * pages+apiEndpoints discovery agents for every service app. Defaults
+     * to `true`. Has no effect on blackbox runs.
+     */
+    surfaceIntegrationEnabled?: boolean;
+    /** Skip attack-surface/swarm; run single fast-strike operator. See {@link ./fastStrike}. */
+    fastStrike?: boolean;
+    /** Spawner routed into the swarm fan-out. Defaults to the in-process spawner. */
+    subagentSpawner?: SubagentSpawner;
+    /** Durable AI hooks forwarded to swarm workers; unset outside the durable runtime. */
+    languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
+    usageRecorder?: UsageRecorder;
+    streamIdFactory?: StreamIdFactory;
+    /**
+     * The caller's full {@link AgentHooks} (backends, middleware, usage
+     * recorder, stream ids, inbox transports, extra tools, sandbox), forwarded
+     * to every agent this workflow constructs. Takes precedence over the
+     * individual hook fields above when both are set. Unset → those individual
+     * fields (or their in-process defaults) apply, matching today's behavior.
+     */
+    hooks?: AgentHooks;
+    /**
+     * Fan-out / registry / id / browser / hook seams (`./seams.ts`). Defaults
+     * to {@link inProcessSeams}, matching today's in-process behavior.
+     */
+    seams?: WorkflowSeams;
+}
+export interface PentestWorkflowResult {
+    findings: Finding[];
+    findingsPath: string;
+    pocsPath: string;
+    reportPath: string | null;
+}
+export type { SwarmTarget } from "../session/persistence";
+export interface PentestSwarmInput {
+    targets: SwarmTarget[];
+    model: AIModel;
+    session: SessionInfo;
+    authConfig?: AIAuthConfig;
+    abortSignal?: AbortSignal;
+    findingsRegistry: FindingsRegistry;
+    eventBus?: AgentEventBus;
+    onError?: (e: unknown) => void;
+    concurrency?: number;
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+    onCacheMetrics?: (metrics: CacheMetrics) => void;
+    enableThinking?: boolean;
+    thinkingEffort?: ThinkingEffort | null;
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+    /**
+     * X display (e.g. `":11"`) for every swarm sub-agent's browser, so a swarm
+     * launched by an orchestrator on a per-endpoint virtual desktop keeps its
+     * workers on that same display instead of the process-wide `DISPLAY`.
+     */
+    display?: string;
+    /** Fan-out spawner. Defaults to the in-process spawner. */
+    subagentSpawner?: SubagentSpawner;
+    /** Durable AI hooks forwarded to swarm workers; unset outside the durable runtime. */
+    languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
+    usageRecorder?: UsageRecorder;
+    streamIdFactory?: StreamIdFactory;
+    /**
+     * The caller's full {@link AgentHooks}, forwarded to every worker this
+     * swarm constructs (see {@link PentestWorkflowInput.hooks}). A per-target
+     * override can come from `seams.hooksForItem` (`./seams.ts`).
+     */
+    hooks?: AgentHooks;
+    /**
+     * Fan-out / id / hook seams (`./seams.ts`). Defaults to {@link inProcessSeams},
+     * matching today's in-process behavior.
+     */
+    seams?: WorkflowSeams;
+}
+/**
+ * Explicit, serializable-by-the-caller input for {@link runPentestSwarmTarget}
+ * — everything one swarm target's worker reads, with no reads of
+ * `runPentestSwarm`'s own local scope. A durable caller rebuilds `hooks` and
+ * `seams` on its own side (they carry backends/functions, same as
+ * {@link PentestSwarmInput}) and runs the target as a separate child workflow.
+ */
+export interface PentestSwarmTargetInput {
+    model: AIModel;
+    session: SessionInfo;
+    authConfig?: AIAuthConfig;
+    abortSignal?: AbortSignal;
+    findingsRegistry: FindingsRegistry;
+    eventBus?: AgentEventBus;
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+    onCacheMetrics?: (metrics: CacheMetrics) => void;
+    enableThinking?: boolean;
+    thinkingEffort?: ThinkingEffort | null;
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+    display?: string;
+    onError?: (e: unknown) => void;
+    /** The swarm's shared {@link AgentHooks}; merged with `seams.hooksForItem` for this target. */
+    hooks: AgentHooks;
+    seams: WorkflowSeams;
+    /** Manifest entries built by the swarm before fan-out — `manifestEntries[index]` is this target's entry. */
+    manifestEntries: AgentManifestEntry[];
+    /** Subagent ids already completed on resume — a completed target is skipped. */
+    completedIds: Set<string>;
+}
+/**
+ * One pentest swarm target: the optional plan phase, then the
+ * {@link TargetedPentestAgent}, with message capture, spawn/complete events,
+ * and persistence on success or failure. Closure-free extraction of
+ * `runPentestSwarm`'s worker body so a durable caller can run it as a
+ * separate child workflow.
+ */
+export declare function runPentestSwarmTarget(target: SwarmTarget, index: number, input: PentestSwarmTargetInput): Promise<PentestResult | null>;
+/**
+ * Run a pentest swarm: build manifest, run agents with bounded concurrency
+ * and automatic persistence, then finalize the manifest.
+ *
+ * Each agent gets message capture, callback wrapping, spawn/complete events,
+ * and persistence on success or failure — all handled internally.
+ *
+ * Returns `(PentestResult | null)[]` in the same order as targets.
+ */
+export declare function runPentestSwarm(input: PentestSwarmInput): Promise<(PentestResult | null)[]>;
+/**
+ * Deterministic pentest workflow.
+ *
+ * Phase 1: Run attack surface discovery (whitebox workflow or blackbox agent).
+ * Phase 2: Flatten results into pentest targets.
+ * Phase 3: Spawn a swarm of {@link TargetedPentestAgent} instances in parallel.
+ */
+export declare function runPentestWorkflow(input: PentestWorkflowInput): Promise<PentestWorkflowResult>;

package/build/lib/core/workflows/pentest.js

@@ -0,0 +1,42 @@
+import {
+  DEFAULT_CONCURRENCY2,
+  runPentestSwarmTarget2,
+  runPentestSwarm2,
+  runPentestWorkflow2
+} from "../../chunk-4ydrmwd9.js";
+import"../../chunk-2t65f749.js";
+import"../../chunk-48zms2q1.js";
+import"../../chunk-k5m5rasy.js";
+import"../../chunk-xpfg2fbk.js";
+import"../../chunk-jah67hkt.js";
+import"../../chunk-2j49k090.js";
+import"../../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 {
+  DEFAULT_CONCURRENCY2 as DEFAULT_CONCURRENCY,
+  runPentestSwarm2 as runPentestSwarm,
+  runPentestSwarmTarget2 as runPentestSwarmTarget,
+  runPentestWorkflow2 as runPentestWorkflow
+};

package/build/lib/core/workflows/seams.d.ts

@@ -0,0 +1,102 @@
+import type { AgentHooks, Finding } from "../agents/offSecAgent";
+import type { PlaywrightMcpSession } from "../agents/offSecAgent/tools";
+import { type AttackSurfaceRegistryOps } from "../findings/attackSurfaceRegistry";
+import { type FindingsRegistryOps } from "../findings/registry";
+/**
+ * Bounded-concurrency fan-out. Same contract as
+ * {@link SubagentSpawner.spawnMany} (`subagentSpawner.ts`) — pulled out here
+ * so a workflow can fan out without depending on subagent-spawning specifics.
+ */
+export interface ConcurrencyRunner {
+    spawnMany<TItem, TResult>(items: readonly TItem[], worker: (item: TItem, index: number) => Promise<TResult>, opts: {
+        concurrency: number;
+        abortSignal?: AbortSignal;
+    }): Promise<(TResult | null)[]>;
+}
+/** In-process default: the same `runWithBoundedConcurrency` pool every workflow already runs on. */
+export declare const inProcessConcurrencyRunner: ConcurrencyRunner;
+export interface RegistryProvider {
+    findings(): FindingsRegistryOps;
+    attackSurface(): AttackSurfaceRegistryOps;
+}
+/** In-process default: fresh in-memory registries, same classes workflows construct today. */
+export declare const inMemoryRegistryProvider: RegistryProvider;
+export interface SessionIdFactory {
+    newSessionId(name: string, ordinal: number): string;
+}
+/** In-process default: today's random time-descending ULID, name/ordinal ignored. */
+export declare const randomSessionIdFactory: SessionIdFactory;
+export interface BrowserSessionScope {
+    subagentId: string;
+    subagentName?: string;
+}
+export interface BrowserSessionProvider {
+    forChild(scope: BrowserSessionScope): PlaywrightMcpSession | undefined;
+}
+/** Wraps a single live session so every child gets the same by-reference session — today's behavior. */
+export declare function sharedBrowserSessionProvider(session?: PlaywrightMcpSession): BrowserSessionProvider;
+/** In-process default: no session held, matching sandbox-mode agents that never had one. */
+export declare const noBrowserSessionProvider: BrowserSessionProvider;
+export interface EndpointScope {
+    subagentId: string;
+    subagentName?: string;
+    target: string;
+}
+export interface OrchestrationHooks {
+    onEndpointStart?(scope: EndpointScope): void | Promise<void>;
+    onEndpointDone?(scope: EndpointScope, result: unknown): void | Promise<void>;
+    onEndpointFailed?(scope: EndpointScope, error: unknown): void | Promise<void>;
+    onFindingPersisted?(finding: Finding): void | Promise<void>;
+}
+/** In-process default: no-op — nothing observes endpoint/finding lifecycle today. */
+export declare const noopOrchestrationHooks: OrchestrationHooks;
+/**
+ * Wraps a {@link FindingsRegistryOps} so a successful (non-duplicate) `register`
+ * also invokes `hooks.onFindingPersisted`. Returns `registry` unchanged when no
+ * hook is set, so this is a no-op under the in-process default.
+ */
+export declare function withFindingPersistedHook(registry: FindingsRegistryOps, onFindingPersisted?: OrchestrationHooks["onFindingPersisted"]): FindingsRegistryOps;
+export interface WorkflowLimits {
+    maxDepth: number;
+    maxConcurrentChildren: number;
+}
+/** pentest is root -> endpoint -> worker -> judge = 3 edges. */
+export declare const DEFAULT_MAX_DEPTH = 3;
+/**
+ * Matches `DEFAULT_CONCURRENCY` in `./pentest.ts`. Duplicated rather than
+ * imported so `seams.ts`
+ * never depends back on a workflow module.
+ */
+export declare const DEFAULT_MAX_CONCURRENT_CHILDREN = 10;
+export declare class WorkflowLimitExceededError extends Error {
+    constructor(message: string);
+}
+/** Throws {@link WorkflowLimitExceededError} when `depth` exceeds `limits.maxDepth`. */
+export declare function assertDepth(depth: number, limits: WorkflowLimits): void;
+/**
+ * The four seams (plus ids + limits) apex's workflow layer runs on. Every
+ * member has an in-process default that is exactly today's behavior — see
+ * {@link inProcessSeams}. Console (or any durable host) overrides members to
+ * swap in DBOS-backed child workflows, DB-backed registries, deterministic
+ * ids, browser reattach-by-lease, and persistence hooks, without the
+ * workflows (`pentest.ts` / `whiteboxAttackSurface.ts` / `fastStrike.ts`)
+ * changing.
+ */
+export interface WorkflowSeams {
+    fanOut: ConcurrencyRunner;
+    registries: RegistryProvider;
+    ids: SessionIdFactory;
+    browser: BrowserSessionProvider;
+    hooks: OrchestrationHooks;
+    limits: WorkflowLimits;
+    /**
+     * Per-item {@link AgentHooks} override for one item in a workflow's fan-out
+     * (e.g. an endpoint's dedicated lease/backends, its own politeness budget).
+     * Recorders are agent-scoped: provide them here rather than sharing a parent journal.
+     */
+    hooksForItem?<TItem = unknown>(item: TItem, index: number): Partial<AgentHooks>;
+}
+/** Builds a `WorkflowSeams` from in-process defaults, overridable per-member. */
+export declare function inProcessSeams(overrides?: Partial<WorkflowSeams>): WorkflowSeams;
+/** Inherits shared hooks while requiring an explicit recorder for each child. */
+export declare function resolveItemHooks<TItem>(hooks: AgentHooks | undefined, seams: WorkflowSeams, item: TItem, index: number): AgentHooks;

package/build/lib/core/workflows/seams.js

@@ -0,0 +1,37 @@
+import {
+  inProcessConcurrencyRunner2,
+  inMemoryRegistryProvider2,
+  randomSessionIdFactory2,
+  sharedBrowserSessionProvider2,
+  noBrowserSessionProvider2,
+  noopOrchestrationHooks2,
+  withFindingPersistedHook2,
+  DEFAULT_MAX_DEPTH2,
+  DEFAULT_MAX_CONCURRENT_CHILDREN2,
+  WorkflowLimitExceededError2,
+  assertDepth2,
+  inProcessSeams2,
+  resolveItemHooks2
+} from "../../chunk-517rf135.js";
+import"../../chunk-b8eq85d2.js";
+import"../../chunk-02awpt3c.js";
+import"../../chunk-3502z798.js";
+import"../../chunk-8vhr65w3.js";
+import"../../chunk-2njv7wz3.js";
+import"../../chunk-jdjagvgr.js";
+import"../../chunk-3w05jmk6.js";
+export {
+  DEFAULT_MAX_CONCURRENT_CHILDREN2 as DEFAULT_MAX_CONCURRENT_CHILDREN,
+  DEFAULT_MAX_DEPTH2 as DEFAULT_MAX_DEPTH,
+  WorkflowLimitExceededError2 as WorkflowLimitExceededError,
+  assertDepth2 as assertDepth,
+  inMemoryRegistryProvider2 as inMemoryRegistryProvider,
+  inProcessConcurrencyRunner2 as inProcessConcurrencyRunner,
+  inProcessSeams2 as inProcessSeams,
+  noBrowserSessionProvider2 as noBrowserSessionProvider,
+  noopOrchestrationHooks2 as noopOrchestrationHooks,
+  randomSessionIdFactory2 as randomSessionIdFactory,
+  resolveItemHooks2 as resolveItemHooks,
+  sharedBrowserSessionProvider2 as sharedBrowserSessionProvider,
+  withFindingPersistedHook2 as withFindingPersistedHook
+};

package/build/lib/core/workflows/threatModel.d.ts

@@ -0,0 +1,26 @@
+import type { AIAuthConfig, AIModel } from "../ai";
+import type { AgentEventBus } from "../eventBus";
+import type { SessionInfo } from "../session";
+export interface ThreatModelWorkflowInput {
+    /** Path to the codebase to analyze */
+    codebasePath: string;
+    /** Where to write the threat model markdown file */
+    outputPath: string;
+    /** AI model (defaults to claude-sonnet-4-5) */
+    model?: AIModel;
+    /** Optional existing session to reuse — auto-created if omitted */
+    session?: SessionInfo;
+    /** Per-provider API key overrides */
+    authConfig?: AIAuthConfig;
+    /** AbortSignal to cancel the workflow */
+    abortSignal?: AbortSignal;
+    /** Optional event bus for streaming agent output */
+    eventBus?: AgentEventBus;
+}
+export interface ThreatModelWorkflowResult {
+    /** The session used (whether provided or auto-created) */
+    session: SessionInfo;
+    /** Absolute path where the threat model was written */
+    outputPath: string;
+}
+export declare function runThreatModelWorkflow(input: ThreatModelWorkflowInput): Promise<ThreatModelWorkflowResult>;

package/build/lib/core/workflows/whiteboxAttackSurface.d.ts

@@ -0,0 +1,142 @@
+import type { StreamTextOnStepFinishCallback, ToolSet } from "ai";
+import type { AgentHooks } from "../agents/offSecAgent";
+import { type SubagentSpawner } from "../agents/offSecAgent/subagentSpawner";
+import { type AppInfo, type WhiteboxAttackSurfaceResult } from "../agents/specialized/whiteboxAttackSurface";
+import { type AgentConcurrencyLimiter } from "../agents/specialized/whiteboxAttackSurface/endpointDocumentationAgent";
+import type { AIAuthConfig, AIModel, CacheMetrics, OpenAIReasoningEffort, ThinkingEffort } from "../ai";
+import type { AgentEventBus } from "../eventBus";
+import type { SessionInfo } from "../session";
+import { type WorkflowSeams } from "./seams";
+export interface WhiteboxAttackSurfaceWorkflowInput {
+    /** Preloaded owned-backend artifacts; absent preserves full discovery. */
+    incremental?: {
+        diffPath: string;
+        assetsPath: string;
+        existingResult: WhiteboxAttackSurfaceResult;
+    };
+    codebasePath: string;
+    model: AIModel;
+    session: SessionInfo;
+    authConfig?: AIAuthConfig;
+    abortSignal?: AbortSignal;
+    eventBus?: AgentEventBus;
+    attackSurfaceRegistry?: import("../findings/attackSurfaceRegistry").AttackSurfaceRegistry;
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+    onCacheMetrics?: (metrics: CacheMetrics) => void;
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+    /** Enable extended thinking for supported models (Anthropic Claude 3.7+). */
+    enableThinking?: boolean;
+    /** Adaptive-thinking effort hint (Anthropic Opus/Sonnet 4.6+); ignored elsewhere. */
+    thinkingEffort?: ThinkingEffort | null;
+    /** Known domains associated with the project — agents can map discovered apps to these. */
+    domains?: string[];
+    /** Project-level threat model content (e.g. from .pensar/threat_model.md), if found */
+    projectThreatModel?: string;
+    /** Deployment environment names (e.g. ["production", "staging"]) from project settings. */
+    environments?: string[];
+    /**
+     * When false, Phase 2 skips the deterministic `@pensar/surface` path and
+     * always runs the legacy pages + apiEndpoints discovery agent pair for
+     * service apps. Defaults to `true`.
+     */
+    surfaceIntegrationEnabled?: boolean;
+    /**
+     * Hard ceiling on CodeAgents running concurrently across all apps/endpoints.
+     * Defaults to {@link MAX_CONCURRENT_AGENTS}. Bounds total agent fan-out so it
+     * doesn't scale with the number of apps in the repo.
+     */
+    maxConcurrentAgents?: number;
+    /** Fan-out spawner. Defaults to the in-process spawner. */
+    subagentSpawner?: SubagentSpawner;
+    /**
+     * The caller's full {@link AgentHooks}, forwarded to every CodeAgent this
+     * workflow constructs (Phase 1 apps discovery, Phase 2 per-app/per-endpoint
+     * documentation). A per-app override can come from `seams.hooksForItem`
+     * (`./seams.ts`).
+     */
+    hooks?: AgentHooks;
+    /**
+     * Fan-out / id / hook seams (`./seams.ts`). Defaults to
+     * {@link inProcessSeams}, matching today's in-process behavior.
+     */
+    seams?: WorkflowSeams;
+}
+interface IncrementalWhiteboxInput extends WhiteboxAttackSurfaceWorkflowInput {
+    previousCommitSha: string;
+    currentCommitSha: string;
+    existingResult: WhiteboxAttackSurfaceResult;
+}
+/**
+ * Explicit, serializable-by-the-caller input for {@link runWhiteboxAttackSurfaceApp}
+ * — everything one app's Phase-2 worker reads, with no reads of
+ * `runWhiteboxAttackSurfaceWorkflow`'s own local scope. A durable caller
+ * rebuilds `hooks`, `seams`, `mintChildId` and `agentLimiter` on its own side
+ * and runs the app as a separate child workflow.
+ */
+export interface WhiteboxAttackSurfaceAppInput {
+    codebasePath: string;
+    model: AIModel;
+    session: SessionInfo;
+    authConfig?: AIAuthConfig;
+    abortSignal?: AbortSignal;
+    eventBus?: AgentEventBus;
+    attackSurfaceRegistry?: import("../findings/attackSurfaceRegistry").AttackSurfaceRegistry;
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+    onCacheMetrics?: (metrics: CacheMetrics) => void;
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+    enableThinking?: boolean;
+    thinkingEffort?: ThinkingEffort | null;
+    projectThreatModel?: string;
+    environments?: string[];
+    surfaceIntegrationEnabled: boolean;
+    /** `serviceApps.length === 1` at the time Phase 2 started — forwarded to `mapAppWithSurface`. */
+    isSingleAppRepo: boolean;
+    /** Parent id for this app's own subagent-complete event — the Phase-1 umbrella node. */
+    umbrellaId: string;
+    /** Mints IDs for discovery and per-endpoint documentation children. */
+    mintChildId: (name: string) => string;
+    /** Bounds total concurrent CodeAgents across the whole workflow (Phase 1 + every app). */
+    agentLimiter: AgentConcurrencyLimiter;
+    /** Fan-out spawner forwarded to `runAppEndpointDocumentation`'s own per-endpoint fan-out. */
+    subagentSpawner?: SubagentSpawner;
+    hooks: AgentHooks;
+    seams: WorkflowSeams;
+}
+/**
+ * One Phase-2 app: pages/API-endpoints discovery (surface-driven or legacy
+ * fallback) or cloud-resource documentation, then this app's own
+ * subagent-complete event. Closure-free extraction of
+ * `runWhiteboxAttackSurfaceWorkflow`'s per-app worker so a durable caller can
+ * run it as a separate child workflow. Returns whether the app failed.
+ */
+export declare function runWhiteboxAttackSurfaceApp(app: AppInfo, appIndex: number, input: WhiteboxAttackSurfaceAppInput): Promise<boolean>;
+/**
+ * Deterministic whitebox attack surface workflow.
+ *
+ * Phase 1: Spawn a single CodeAgent to identify all apps in the repo.
+ * Phase 1.5: Create app folders with app.json metadata.
+ * Phase 2: Per-app dispatch. When `surfaceIntegrationEnabled` (default), service
+ *           apps run `mapAppWithSurface`; on `surface` mode a per-endpoint
+ *           endpoint-documentation CodeAgent documents the deterministic list,
+ *           on `fallback` the legacy pages+apiEndpoints agent pair runs. When
+ *           `surfaceIntegrationEnabled` is false, every service app uses the
+ *           legacy pair directly. Cloud resources always use the specialized
+ *           cloud-resource agent. Threat models and risk scores are generated
+ *           inline by document_endpoint.
+ * Phase 3: Read the assets directory to build endpoint data.
+ * Phase 4: Final assembly.
+ */
+export declare function runWhiteboxAttackSurfaceWorkflow(input: WhiteboxAttackSurfaceWorkflowInput): Promise<WhiteboxAttackSurfaceResult>;
+/**
+ * Incremental whitebox attack surface workflow for commit-triggered recon.
+ *
+ * Instead of scanning the entire codebase:
+ * 1. Run `git diff` between the two commits and write the output to a file.
+ * 2. Serialize existing assets into the session's assets directory (app folder structure).
+ * 3. Spawn a CodeAgent to analyze the diff and update assets in-place.
+ *    New endpoints get risk scores inline via document_endpoint.
+ * 4. Read the final assets directory and reconstruct the result.
+ * 5. Carry forward existing risk scores for unchanged endpoints.
+ */
+export declare function runIncrementalWhiteboxAttackSurfaceWorkflow(input: IncrementalWhiteboxInput): Promise<WhiteboxAttackSurfaceResult>;
+export {};