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

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

@@ -0,0 +1,233 @@
+import type { StreamTextResult, TextStreamPart, ToolSet } from "ai";
+import { AgentEventBus } from "../../eventBus";
+import { type SessionInfo } from "../../session";
+import { PlaywrightMcpSession } from "./tools";
+import type { CreateAgentInput, OffensiveSecurityAgentInput } from "./types";
+export declare function filterWorkspaceToolsForRun(activeTools: string[], prompt: string, hasInteractiveApprovalGate: boolean): string[];
+/**
+ * General-purpose offensive security agent harness.
+ *
+ * The agent **owns tool creation** — all available tools are built from
+ * the session context, and specific agents select which ones to activate
+ * via the `activeTools` array (passed through to the AI SDK).
+ *
+ * The stream is created lazily on first consumption (see {@link streamReady}
+ * and {@link streamResult}) — after backend-probed runtime facts settle —
+ * so the AI SDK telemetry nests under this agent's span — no separate `.run()`.
+ *
+ * @typeParam TResult - The type returned by {@link consume}. When the input
+ *   includes a `resolveResult` function, `consume()` awaits it after the
+ *   stream finishes and returns the value. Defaults to `void`.
+ *
+ * ## Consumption (pick one — stream is single-read)
+ *
+ * **1. Emit to EventBus via `.consume()` → `TResult`**
+ * ```ts
+ * const bus = new AgentEventBus();
+ * bus.on("text-delta", (e) => process.stdout.write(e.text));
+ * bus.on("tool-call-complete", (e) => console.log(`→ ${e.toolName}`));
+ * const agent = new OffensiveSecurityAgent({ ..., eventBus: bus });
+ * const result = await agent.consume();
+ * ```
+ *
+ * **2. `for await` directly on the agent**
+ * ```ts
+ * for await (const chunk of agent) { ... }
+ * ```
+ *
+ * **3. Raw stream access**
+ * ```ts
+ * for await (const chunk of agent.fullStream) { ... }
+ * ```
+ */
+export declare class OffensiveSecurityAgent<TResult = void> {
+    /** The real SDK stream result — created exactly once, with backend-probed facts via {@link streamReady} or settled-or-unknown facts via the sync escape hatch. */
+    private _streamResult;
+    /** Composes the final system prompt, writes the trace init record, and calls `streamResponse`. Invoked at most once; both creation paths guard on `_streamResult`. */
+    private readonly createStream;
+    /** Lazy runtime probe, then `createStream`; memoized by {@link streamInit}. */
+    private readonly initializeStreamOnce;
+    /** Memoized {@link streamReady} promise; initialization runs at most once. */
+    private streamInit;
+    /** True when this agent's tool selection can use backend-probed execution facts. */
+    private readonly probesRuntime;
+    /** The tool context whose runtime scope keys fact discovery and the sync fallback. */
+    private readonly toolCtx;
+    /** The event bus for this agent's streaming output. */
+    readonly eventBus: AgentEventBus;
+    private readonly resolveResult?;
+    /** The structured result captured by the `response` tool, or `null` until it fires. */
+    private _capturedResponse;
+    /** Set synchronously when `response` fires, ahead of any async `resolveResult`, to distinguish a clean finish from an abort. */
+    private _responseToolFired;
+    /** Raw structured result submitted to the response tool, retained for root-span output. */
+    private _responseToolResult;
+    /** Resolves the instant `response` captures the result, so {@link consume} can return early and drain in the background. */
+    private _resolveResponseCaptured;
+    private _rejectResponseCaptured;
+    readonly responseCaptured: Promise<TResult>;
+    /** Rejects when the background drain errors, so a custom resolver racing `streamResult.response` isn't blocked by a wedged stream. */
+    private _drainRejection;
+    /** Settles when the background drain (including its synthetic-close finally) has fully finished. */
+    drained: Promise<void>;
+    /** Identifier for this agent when it is running as a subagent. */
+    private readonly subagentId?;
+    /** Display label for span name / `gen_ai.agent.name`; the id stays the join key. */
+    private readonly subagentName?;
+    /** Operating mode (tools surface); used for run-span attribution. */
+    private readonly agentMode;
+    /** The current open assistant message id (`msg_…`); minted on `start-step` in {@link consume}, `null` between steps. */
+    private currentMessageId;
+    /** Per-run stream counters for deterministic id derivation via {@link streamIdFactory}. */
+    private streamStepIndex;
+    private streamTextPartIndex;
+    /** Per-command executor for local-mode command execution; disposed on consume() completion. */
+    private readonly commandShell?;
+    /**
+     * This agent's Playwright MCP browser session. Either constructed fresh
+     * by this agent (when no `browserSession` was passed in) or supplied by
+     * the caller (e.g. `spawn_pentest_agent` constructs a fresh, isolated
+     * session for each worker, seeds it with a snapshot of the orchestrator's
+     * cookies + localStorage, and hands the seeded session in here so this
+     * agent's browser tools operate against an authenticated-but-isolated
+     * Chromium).
+     *
+     * Exposed publicly so spawn tools can read this agent's session (e.g.
+     * the pentest orchestrator's `browserSession` is what `spawn_pentest_agent`
+     * snapshots when it builds the worker's seeded clone). The session
+     * object is NOT shared between agents at runtime — each agent gets its
+     * own isolated Chromium so a sub-agent can't clobber its parent's DOM,
+     * cookies, or navigation state.
+     *
+     * Only populated for non-sandbox (local MCP) mode. In sandbox mode,
+     * browser state is already shared via the sandbox's per-sandbox
+     * Playwright user-data directory, so no host-side session object is
+     * needed.
+     */
+    readonly browserSession?: PlaywrightMcpSession;
+    /**
+     * True when this agent constructed its own {@link browserSession} (no
+     * `browserSession` was passed in). Only the owner disconnects it on
+     * `consume()` completion — an inherited session is torn down by whoever
+     * created it (e.g. `spawn_pentest_agent` for worker clones), so we must
+     * never disconnect a session we don't own.
+     */
+    private readonly ownsBrowserSession;
+    /** Guards against double force-kill across the drain-finally and result-capture paths. */
+    private browserDisconnected;
+    private shellDisposed;
+    /** Listeners started by this agent's callback helper tools; drained on finalization. */
+    private readonly callbackListeners;
+    private shellDisposeBarrier;
+    private readonly abortSignal?;
+    private readonly streamIdFactory?;
+    /** Recorded-run durable context authority; flushed (and failing) in finalizeRun. */
+    private readonly contextRecorder?;
+    /** The user-facing prompt passed to the model. */
+    readonly userPrompt: string;
+    /** The session this agent is operating within. */
+    private readonly _session;
+    /** Agent-local message persistence (debounce + serialized writes). */
+    private readonly writer;
+    /** Closes an interrupted step: synthetic results, reconstruction, write. */
+    private readonly finalizeInterruptedStep;
+    private messagesPath;
+    /** Serializes agent-owned messages.json writes in enqueue order. */
+    /**
+     * Async factory that creates a session when one is not provided,
+     * then constructs the agent. Use this instead of `new` when you
+     * want the agent to own session lifecycle.
+     *
+     * Pass an existing `session` to reuse one (console integration,
+     * subagent spawning, etc.).
+     */
+    static create<TResult = void>(input: CreateAgentInput<TResult>): Promise<OffensiveSecurityAgent<TResult>>;
+    /** The session this agent is operating within. */
+    get session(): SessionInfo;
+    /** This agent's identity on the event bus (subagent's session id, or the root session's id). */
+    private get busSessionId();
+    constructor(input: OffensiveSecurityAgentInput<TResult>);
+    /**
+     * Asynchronous initialization seam: probe runtime facts through this
+     * agent's command backend (only when its selected tools can use them), then
+     * create the stream. Idempotent; every consumption entry point awaits it,
+     * so the AI layer's prompt budgeting and recovery see the actual final
+     * system text.
+     */
+    streamReady(): Promise<void>;
+    /**
+     * The underlying Vercel AI SDK stream result — synchronous escape hatch.
+     * Always a real SDK result. Cold access creates it immediately with facts
+     * already settled for this runtime scope, else explicit unknown facts —
+     * never host facts; callers needing freshly probed facts await
+     * {@link streamReady}, `consume()`, or `fullStream` iteration instead.
+     * Guarded so a cold access racing an in-flight probe never creates a
+     * second model stream.
+     */
+    get streamResult(): StreamTextResult<ToolSet, never>;
+    /**
+     * The raw async-iterable stream of chunks.
+     * Equivalent to `streamResult.fullStream`; before initialization it
+     * settles {@link streamReady} on first iteration, then delegates to the
+     * real stream.
+     */
+    get fullStream(): AsyncIterable<TextStreamPart<ToolSet>>;
+    /**
+     * Makes the agent instance itself async-iterable so callers can write:
+     * ```ts
+     * for await (const chunk of agent) { ... }
+     * ```
+     *
+     * **Note:** The underlying stream can only be consumed once.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<TextStreamPart<ToolSet>>;
+    /**
+     * Consume the stream, emitting each chunk on the {@link eventBus}, then
+     * resolve the final result.
+     *
+     * Each AI SDK stream part is forwarded to the bus via
+     * {@link AgentEventBus.emitStreamPart}, tagged with this agent's
+     * `subagentId` when present.
+     *
+     * @returns The value produced by `resolveResult`, or `void` if none was provided.
+     */
+    consume(): Promise<TResult>;
+    /**
+     * Apply one stream part: part-id bookkeeping, lifecycle-tracker updates,
+     * and the finish-step close-out emissions. Pure projection of the part
+     * onto run state; forwarding to the bus is the caller's job.
+     */
+    private applyStreamPart;
+    /**
+     * Finalize a finished (or failed) run: stop diagnostics, dispose the owned
+     * shell, surface deferred tool errors, close the interrupted step, and
+     * disconnect the owned browser on every path. Returns the first
+     * finalization error (or null) — the caller keeps the stream error
+     * primary.
+     */
+    private finalizeRun;
+    /**
+     * Disposes the owned per-command executor exactly once; safe to call from
+     * multiple teardown paths. Returns the same cached barrier on repeat
+     * calls; the barrier resolves once a killed invocation's bounded
+     * termination protocol has settled, so closeout never races an active
+     * command.
+     */
+    disposeOwnedShell(): Promise<void>;
+    /** Force-kills the owned Chromium child process exactly once; safe to call from multiple teardown paths. */
+    private disconnectOwnedBrowser;
+    /**
+     * Idempotent teardown for hosts that abort before `consume()` settles
+     * (Console `settleOnAbort` on timeout/pause). Force-disconnects the owned
+     * browser, awaits the shell's bounded kill barrier, then awaits the drain
+     * so owned work settles before the host starts closeout.
+     */
+    abortAndDrain(): Promise<void>;
+    /**
+     * Promise that resolves to the final response metadata once the stream
+     * has been fully consumed. Await this *after* iterating the stream.
+     */
+    get response(): Promise<import("ai").LanguageModelResponseMetadata & {
+        messages: Array<import("ai").AssistantModelMessage | import("ai").ToolModelMessage>;
+    }>;
+}

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

@@ -0,0 +1,35 @@
+interface SessionPaths {
+    rootPath: string;
+    findingsPath: string;
+    pocsPath: string;
+    scratchpadPath: string;
+    logsPath: string;
+    config?: {
+        codebasePath?: string;
+    };
+}
+/**
+ * Inspect the session's `provided_files/` directory and return a prompt
+ * section enumerating the files made available to the agent. When no
+ * provided files exist the function returns an empty string so the
+ * section is omitted entirely.
+ *
+ * The directory is populated by the console (see
+ * `packages/agents/utils.ts` → `populateProvidedFiles`) from files
+ * uploaded at the project level, and may contain a generated
+ * `README.md` manifest.
+ */
+export declare function buildProvidedFilesSection(sessionRootPath: string, fileWorkspaceRoot?: string): string;
+export declare function buildSessionWorkspaceSection(session: SessionPaths, agentCwd: string, activeTools?: readonly string[], fileWorkspaceRoot?: string): string;
+/** Options for building the base system prompt. */
+export interface BaseSystemPromptOptions {
+    /** When true, include the "Stay in the session folder" instruction. Defaults to true. */
+    sandboxMode?: boolean;
+}
+export declare function buildBaseSystemPrompt(options?: BaseSystemPromptOptions): string;
+/**
+ * Default base system prompt (sandbox mode — includes "Stay in session folder").
+ * Use {@link buildBaseSystemPrompt} when you need to control sandbox vs CWD mode.
+ */
+export declare const BASE_SYSTEM_PROMPT: string;
+export {};

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

@@ -0,0 +1,11 @@
+import { type ToolSet } from "ai";
+import type { ToolExecutionRecorder } from "../../runtime/runToolStore";
+/**
+ * Journal recorded-run tool calls. Intent is committed before any effect,
+ * the exact model-visible conversion is normalized once to the JSON
+ * transport shape and settled before the SDK can expose the result, and
+ * that settled shape is cached by toolCallId so repeated SDK conversions
+ * never re-run a spill-writing converter. Callers that pass no recorder
+ * are never wrapped.
+ */
+export declare function wrapRecordedTools(tools: ToolSet, recorder: ToolExecutionRecorder): ToolSet;

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

@@ -0,0 +1,43 @@
+import type { ToolContext } from "./tools/types";
+/**
+ * Runtime execution facts, probed through the agent's actual command backend
+ * with the configured execution env — never the host process. A failed,
+ * timed-out, or truncated probe yields {@link UNKNOWN_FACTS}: unknown, not
+ * absent, and not retained.
+ */
+export interface RuntimeExecutionFacts {
+    /** False when the probe failed, timed out, was aborted, or came back truncated. */
+    probed: boolean;
+    /** `uname -sr` from the execution environment. */
+    os?: string;
+    available: string[];
+    missing: string[];
+}
+export declare const UNKNOWN_FACTS: RuntimeExecutionFacts;
+/** Tools whose presence changes technique choice. */
+export declare const PROBE_TOOL_NAMES: readonly ["bash", "sh", "python3", "python", "node", "ffuf", "nmap", "gobuster", "sqlmap", "nikto", "hydra", "john", "hashcat", "tcpdump", "tshark", "nc", "socat", "curl", "wget", "git"];
+export declare const MAX_CACHE_ENTRIES = 32;
+export declare function probeRuntimeFacts(ctx: ToolContext): Promise<RuntimeExecutionFacts>;
+/** Facts already discovered for this runtime scope, or null before a probe settles. */
+export declare function peekSettledRuntimeFacts(ctx: ToolContext): RuntimeExecutionFacts | null;
+/** Test seam: drop cached probes so a suite can exercise fresh probe paths. */
+export declare function resetRuntimeFactsCache(): void;
+/** The command interpreter the agent's resolved backend will use. */
+export declare function resolveCommandPlatform(ctx: ToolContext): "posix" | "windows";
+export interface RuntimeContextSectionOptions {
+    platform: "posix" | "windows";
+}
+/**
+ * Compact, persona-neutral execution facts appended to every system prompt
+ * the harness assembles. Emits no environment variable names or values and
+ * no session paths — this text is embedded in the trace init record's base
+ * prompt, whose hash must stay stable across workspaces; cwd and
+ * file-workspace context live in the workspace section.
+ */
+export declare function buildRuntimeContextSection(facts: RuntimeExecutionFacts, opts: RuntimeContextSectionOptions): string;
+/**
+ * Authoritative inventory of CLI-bundled wordlist assets. The paths are
+ * host-local: a sandbox or remote backend cannot resolve them without
+ * staging, so callers advertise this only for local execution.
+ */
+export declare function buildBundledAssetsSection(): string | null;

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

@@ -0,0 +1,67 @@
+/** Byte size of a streamed tool input, for the response-debug tracer. */
+export declare function responseArgBytes(input: unknown): number;
+/** Structural chunk view the diagnostics read. */
+export interface DiagnosticsChunk {
+    type: string;
+    id?: string;
+    toolCallId?: string;
+    toolName?: string;
+    delta?: string;
+    input?: unknown;
+    args?: unknown;
+    error?: unknown;
+    invalid?: boolean;
+    finishReason?: string;
+}
+export interface StreamDiagnosticsOptions {
+    sessionId: string;
+    subagentId?: string;
+    /** Live in-flight tool view (owned by the lifecycle tracker). */
+    inFlightTools: () => ReadonlyMap<string, string>;
+    /** Whether the `response` tool has fired (owned by the agent). */
+    responseToolFired: () => boolean;
+    /** Tool name treated as the structured-response tool. */
+    responseToolName: string;
+    /** Stall watchdog + gap tracking; defaults to STREAM_STALL_DEBUG. */
+    stallEnabled?: boolean;
+    /** Response-tool lifecycle tracing; defaults to RESPONSE_DEBUG. */
+    responseDebugEnabled?: boolean;
+    /** Warn sink; defaults to the scoped response-debug logger. */
+    warn?: (message: string) => void;
+}
+export declare class StreamDiagnostics {
+    private readonly opts;
+    private readonly stallEnabled;
+    private readonly responseDebugEnabled;
+    private readonly warn;
+    private readonly responseArgChars;
+    private readonly responseSawTerminal;
+    private lastChunkAt;
+    private lastChunkType;
+    private stallStepIndex;
+    private stallTimer;
+    constructor(options: StreamDiagnosticsOptions);
+    /** Start the stall watchdog interval (no-op when disabled). */
+    start(): void;
+    /** Observe one stream chunk: gap tracking plus response-debug tracing. */
+    observeChunk(chunk: DiagnosticsChunk): void;
+    /** Response-debug: a deferred tool-error surfaced at finish-step. */
+    logSurfacedToolError(info: {
+        toolCallId: string;
+        toolName: string;
+        message: string;
+        streamedArgChars: number;
+        finishReason?: string;
+        truncated: boolean;
+    }): void;
+    /** Response-debug: an in-flight call closed at finish-step. */
+    logClosingInFlightTool(info: {
+        toolCallId: string;
+        toolName: string;
+        finishReason?: string;
+        truncated: boolean;
+    }): void;
+    /** Stop the stall watchdog so it never leaks past stream end / throw. */
+    stop(): void;
+    private traceResponseTool;
+}

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

@@ -0,0 +1,223 @@
+import type { LanguageModelMiddleware, StopCondition, StreamTextOnStepFinishCallback, ToolSet } from "ai";
+import type { z } from "zod";
+import type { AIAuthConfig, AIModel, CacheMetrics, OpenAIReasoningEffort, ThinkingEffort, UsageRecorder } from "../../ai";
+import type { CredentialManager } from "../../credentials";
+import { AgentEventBus } from "../../eventBus";
+import type { AttackSurfaceRegistry } from "../../findings/attackSurfaceRegistry";
+import type { FindingsRegistry } from "../../findings/registry";
+import type { SessionInfo } from "../../session";
+import type { ToolBackends } from "../../tools/backends/types";
+import { type BrowserSessionProvider, type SessionIdFactory, type WorkflowSeams } from "../../workflows/seams";
+import type { GrpcPentestContext } from "../specialized/attackSurface/grpcSchema";
+import type { AuthenticationAgentInput } from "../specialized/authenticationAgent/agent";
+import type { FindingJudgeInput } from "../specialized/findingJudge";
+import type { PentestResult, TargetedPentestAgent } from "../specialized/pentest/agent";
+import type { PlaywrightMcpSession, UnifiedSandbox } from "./tools";
+import type { AgentHooks, StreamIdFactory, SystemPentestScope } from "./types";
+/** Registry key selecting which child agent {@link SubagentSpawner.spawn} builds. */
+export type SubagentType = "pentest" | "code" | "whitebox-attack-surface" | "blackbox-attack-surface" | "authentication" | "finding-judge";
+/** Type-specific construction fields; the `type` also selects the registry entry. */
+export type SubagentSpec = {
+    type: "pentest";
+    target: string;
+    objectives: string[];
+    context?: string;
+    grpc?: GrpcPentestContext;
+    systemScope?: SystemPentestScope;
+    role?: "worker";
+    findingsRegistry?: FindingsRegistry;
+    browserSession?: PlaywrightMcpSession;
+} | {
+    type: "code";
+    codebasePath: string;
+    objective: string;
+    system?: string;
+    responseSchema?: z.ZodSchema;
+    stopWhen?: StopCondition<ToolSet>;
+    excludeTools?: string[];
+    projectThreatModel?: string;
+    attackSurfaceRegistry?: AttackSurfaceRegistry;
+} | {
+    type: "whitebox-attack-surface";
+    codebasePath: string;
+    attackSurfaceRegistry?: AttackSurfaceRegistry;
+} | {
+    type: "blackbox-attack-surface";
+    target: string;
+    attackSurfaceRegistry?: AttackSurfaceRegistry;
+} | {
+    type: "authentication";
+    target: string;
+    authHints?: AuthenticationAgentInput["authHints"];
+} | {
+    type: "finding-judge";
+    judgeInput: FindingJudgeInput;
+    target?: string;
+};
+/**
+ * Harness the parent runtime injects into every child. The durable hooks and
+ * `sandbox` are inherited from the parent so a spawned child is subject to the
+ * same middleware / usage recording / id minting / execution sandbox.
+ * @public Consumed by Console's durable subagent runtime.
+ */
+export interface SpawnRuntime {
+    session: SessionInfo;
+    model: AIModel;
+    authConfig?: AIAuthConfig;
+    abortSignal?: AbortSignal;
+    sandbox?: UnifiedSandbox;
+    backends?: ToolBackends;
+    credentialManager?: CredentialManager;
+    display?: string;
+    enableThinking?: boolean;
+    thinkingEffort?: ThinkingEffort | null;
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+    environmentVariables?: Record<string, string>;
+    secretValues?: string[];
+    languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
+    usageRecorder?: UsageRecorder;
+    streamIdFactory?: StreamIdFactory;
+    /**
+     * Step-usage + cache-metric callbacks forwarded to spawned workers. The inline
+     * spawner path uses these for usage accounting; the durable runtime attributes
+     * usage via {@link usageRecorder} instead and leaves them unset.
+     */
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+    onCacheMetrics?: (metrics: CacheMetrics) => void;
+}
+/** @public Consumed by Console's durable subagent runtime. */
+export interface SpawnOptions<TResult = unknown> {
+    /** Type-specific construction fields + the registry discriminator. */
+    spec: SubagentSpec;
+    /** Harness inherited from the parent runtime. */
+    runtime: SpawnRuntime;
+    /** Parent bus the child's events bubble to via {@link AgentEventBus.attachChild}. */
+    parentBus?: AgentEventBus;
+    /** Explicit child id. When omitted, minted via the spawner's id factory. */
+    subagentId?: string;
+    /** UI label — `subagent-spawn.name` and the child's `subagentName`. */
+    subagentName?: string;
+    /** Payload for the `subagent-spawn` `input` field. */
+    lifecycleInput?: unknown;
+    /** Owning agent id → lifecycle `parentSubagentId`. */
+    parentSubagentId?: string;
+    /** Owning agent session id → lifecycle `parentSessionId`. */
+    parentSessionId?: string;
+    /** AI SDK tool call that authoritatively launched this child. */
+    parentToolCallId?: string;
+    /** Stamp the child's own id as `sessionId` on lifecycle events. */
+    stampChildSessionId?: boolean;
+    /** When set, await the child's background drain (bounded) before `subagent-complete`. */
+    drainGraceMs?: number;
+    /** Derive the completion status from the result (default: resolve → completed). */
+    resolveStatus?: (result: TResult) => "completed" | "failed";
+    /** Called with the freshly minted (or overridden) child id. */
+    onSpawned?: (childId: string) => void;
+    /** Attach listeners to the child bus before consumption (e.g. text capture). */
+    beforeConsume?: (childBus: AgentEventBus) => void;
+    /** Runs after a successful consume, before the drain wait and completion emit. */
+    onConsumed?: (result: TResult) => void | Promise<void>;
+    /** Runs after a failed consume, before the drain wait and completion emit. */
+    onError?: (error: unknown) => void | Promise<void>;
+}
+/**
+ * The one seam through which every sub-agent is spawned. The in-process
+ * default preserves today's behavior; a durable implementation can swap in
+ * deterministic ids, a recording sandbox, and child-workflow scheduling
+ * without touching any spawn call site.
+ */
+export interface SubagentSpawner {
+    /**
+     * Spawn one child: mint its id, wire a child bus onto the parent, emit the
+     * `subagent-spawn` / `subagent-complete` lifecycle, construct the agent by
+     * `spec.type`, and return its consumed result.
+     */
+    spawn<TResult = unknown>(opts: SpawnOptions<TResult>): Promise<TResult>;
+    /**
+     * Run a fan-out with bounded concurrency. Unifies the `pLimit` /
+     * `runWithBoundedConcurrency` / sequential mechanisms behind one `concurrency`
+     * arg. Failed workers yield `null`, matching the fan-out helpers it replaces.
+     */
+    spawnMany<TItem, TResult>(items: readonly TItem[], worker: (item: TItem, index: number) => Promise<TResult>, opts: {
+        concurrency: number;
+        abortSignal?: AbortSignal;
+    }): Promise<(TResult | null)[]>;
+}
+/**
+ * The serializable subset of a pentest {@link SubagentSpec} — everything a
+ * durable caller can carry across a child-workflow boundary. `findingsRegistry`
+ * and `browserSession` are live objects, not serializable, so they live on
+ * {@link SpawnedPentestWorkerInput} instead.
+ */
+export type SpawnedPentestWorkerSpec = Omit<Extract<SubagentSpec, {
+    type: "pentest";
+}>, "type" | "findingsRegistry" | "browserSession">;
+/**
+ * Explicit, serializable-by-the-caller input for {@link runSpawnedPentestWorker}
+ * — everything the `spawn_pentest_agent` worker path reads today, with no
+ * reads of the spawner's own enclosing scope. A durable caller rebuilds
+ * `hooks` and `seams` on its own side and runs the worker as a child workflow.
+ */
+export interface SpawnedPentestWorkerInput {
+    model: AIModel;
+    session: SessionInfo;
+    authConfig?: AIAuthConfig;
+    abortSignal?: AbortSignal;
+    eventBus?: AgentEventBus;
+    subagentId?: string;
+    subagentName?: string;
+    findingsRegistry?: FindingsRegistry;
+    browserSession?: PlaywrightMcpSession;
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+    onCacheMetrics?: (metrics: CacheMetrics) => void;
+    environmentVariables?: Record<string, string>;
+    secretValues?: string[];
+    enableThinking?: boolean;
+    thinkingEffort?: ThinkingEffort | null;
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+    display?: string;
+    /** The caller's own {@link AgentHooks} — `backends` is the caller's object. */
+    hooks: AgentHooks;
+    /** Fan-out / hook seams (`../../workflows/seams.ts`); only `hooksForItem` is consulted here. */
+    seams: WorkflowSeams;
+    /** Lets the in-process spawner observe its drain promise; unused by a standalone/durable caller. */
+    onAgentConstructed?: (agent: TargetedPentestAgent) => void;
+}
+/**
+ * Construct one {@link TargetedPentestAgent} from a spawn spec and consume it —
+ * the exact mapping `spawn_pentest_agent`'s in-process worker path uses today,
+ * pulled out so a durable caller can run a spawned pentest worker as its own
+ * child workflow instead of hand-rolling the construction.
+ */
+export declare function runSpawnedPentestWorker(spec: SpawnedPentestWorkerSpec, input: SpawnedPentestWorkerInput): Promise<PentestResult>;
+/**
+ * Default spawner: constructs the real agent and consumes it in-process — a
+ * faithful extraction of the hand-rolled `newSessionId → new AgentEventBus →
+ * attachChild → new Agent → consume` pattern the tools used before.
+ *
+ * Optionally takes the `ids` / `browser` {@link WorkflowSeams} (`../../workflows/seams.ts`)
+ * so a durable host can mint deterministic child ids and reattach a browser
+ * session by scope instead of the in-process defaults (random ULID, no
+ * session). Unconfigured, behavior is unchanged from before these seams existed.
+ */
+declare class InProcessSubagentSpawner implements SubagentSpawner {
+    private readonly ids;
+    private readonly browser?;
+    private ordinal;
+    constructor(ids?: SessionIdFactory, browser?: BrowserSessionProvider | undefined);
+    private mintChildId;
+    spawn<TResult = unknown>(opts: SpawnOptions<TResult>): Promise<TResult>;
+    spawnMany<TItem, TResult>(items: readonly TItem[], worker: (item: TItem, index: number) => Promise<TResult>, opts: {
+        concurrency: number;
+        abortSignal?: AbortSignal;
+    }): Promise<(TResult | null)[]>;
+}
+/** Shared default used by every spawn call site when none is injected. */
+export declare const inProcessSubagentSpawner: InProcessSubagentSpawner;
+/**
+ * Build an in-process spawner wired to the `ids` / `browser` seams of a
+ * {@link WorkflowSeams} (`../../workflows/seams.ts`), e.g.
+ * `createInProcessSubagentSpawner(inProcessSeams({ ids: myFactory }))`.
+ */
+export declare function createInProcessSubagentSpawner(seams?: Partial<Pick<WorkflowSeams, "ids" | "browser">>): SubagentSpawner;
+export {};

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

@@ -0,0 +1,19 @@
+import {
+  runSpawnedPentestWorker2,
+  inProcessSubagentSpawner2,
+  createInProcessSubagentSpawner2
+} from "../../../chunk-f04pr76h.js";
+import"../../../chunk-517rf135.js";
+import"../../../chunk-7gjdygcx.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 {
+  createInProcessSubagentSpawner2 as createInProcessSubagentSpawner,
+  inProcessSubagentSpawner2 as inProcessSubagentSpawner,
+  runSpawnedPentestWorker2 as runSpawnedPentestWorker
+};