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

package/build/lib/core/session/persistence.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Session Persistence — Subagent I/O
+ *
+ * Single source of truth for writing AND reading subagent data.
+ * Both saveSubagentData (write) and loadSubagents (read) share the
+ * same path constants and filename conventions so they can never drift.
+ *
+ * Directory key: subagents live under `{rootPath}/subagents/{key}/`, where
+ * `key` is a session id (`ses_…`) for `spawn_pentest_agent` workers, or a
+ * stable slot id (`pentest-agent-N`) for the swarm.
+ */
+import { type SessionInfo } from "./index";
+export type { SessionInfo };
+import type { ModelMessage } from "ai";
+import type { GrpcPentestContext } from "../agents/specialized/attackSurface/grpcSchema";
+import { type SessionID } from "../id/id";
+import type { AuthenticationInfo } from "./types";
+/**
+ * UI-compatible message format
+ */
+export interface UIMessage {
+    role: "user" | "assistant" | "tool";
+    content: string;
+    createdAt: Date;
+    toolCallId?: string;
+    toolName?: string;
+    args?: Record<string, unknown>;
+    result?: unknown;
+    status?: "pending" | "completed" | "error";
+}
+/**
+ * Information needed to resume a paused agent
+ */
+interface ResumeInfo {
+    target: string;
+    objective: string;
+    vulnerabilityClass: string;
+    authenticationInfo?: AuthenticationInfo;
+}
+/**
+ * UI-compatible subagent format
+ */
+export interface UISubagent {
+    id: string;
+    name: string;
+    type: "attack-surface" | "pentest";
+    target: string;
+    messages: UIMessage[];
+    createdAt: Date;
+    status: "pending" | "completed" | "failed" | "paused" | "canceled";
+    resumeInfo?: ResumeInfo;
+}
+export interface SubagentSaveInput {
+    agentName: string;
+    target: string;
+    objective?: string;
+    vulnerabilityClass?: string;
+    status: string;
+    error?: string;
+    findingsCount?: number;
+    /** Raw AI SDK messages from onStepFinish (e.response.messages) */
+    messages: ModelMessage[];
+    /** System prompt used for this agent (for training data export) */
+    systemPrompt?: string;
+    /** Initial user prompt / task assignment (for training data export) */
+    userPrompt?: string;
+}
+/** Read a subagent's persisted messages by directory key (session id or slot id). */
+export declare function loadSubagentMessages(session: SessionInfo, key: string): ModelMessage[];
+/** Writes to `{session.rootPath}/{SUBAGENTS_DIR}/{name}.json`. */
+export declare function saveSubagentData(session: SessionInfo, data: SubagentSaveInput): void;
+export interface AgentManifestEntry {
+    /** Directory key / identity for this subagent — session id or slot id. */
+    id: string;
+    /** The subagent's session id (`ses_…`) when it has one; mirrors {@link id} for session-keyed subagents. */
+    sessionId?: string;
+    name: string;
+    target: string;
+    vulnerabilityClass: string;
+    objective: string;
+    authInfo?: Record<string, unknown>;
+    status: "running" | "completed" | "failed";
+    spawnedAt: string;
+    completedAt?: string;
+}
+/**
+ * Write the agent manifest file.
+ * The manifest tracks which agents are running/completed so the loader
+ * can detect interrupted (paused) agents on resume.
+ */
+export declare function writeAgentManifest(session: SessionInfo, entries: AgentManifestEntry[]): void;
+/**
+ * Read the current agent manifest, or return empty array if none exists.
+ */
+export declare function readAgentManifest(session: SessionInfo): AgentManifestEntry[];
+/** A normalized target for the pentest swarm */
+export interface SwarmTarget {
+    name?: string;
+    target: string;
+    objectives: string[];
+    /**
+     * gRPC method context for gRPC/Connect targets. When set, the spawned
+     * pentest agent runs the gRPC test battery instead of treating the wire
+     * path as an ordinary HTTP route.
+     */
+    grpc?: GrpcPentestContext;
+}
+/**
+ * Build initial manifest entries for a swarm of pentest agents.
+ * All entries start with status "running".
+ *
+ * @param mintId Session id factory, `(name, ordinal) => id`. Defaults to a
+ * fresh random `ses_` id (ignoring both args) — see
+ * `WorkflowSeams.ids` in `../workflows/seams.ts`.
+ */
+export declare function buildManifestEntries(targets: SwarmTarget[], mintId?: (name: string, ordinal: number) => string): AgentManifestEntry[];
+/**
+ * Reconcile a fresh manifest against the persisted one on resume so each
+ * worker's stable `ses_` id survives. Matches by position (targets re-supplied
+ * in the same order) and reuses the persisted id only when the target lines up;
+ * an in-progress worker resets to "running" for a retry.
+ */
+export declare function reconcileManifestOnResume(existing: AgentManifestEntry[], fresh: AgentManifestEntry[]): AgentManifestEntry[];
+/**
+ * Rewrite the agent manifest with final statuses.
+ * Uses index-based matching (not target-based) to correctly handle
+ * duplicate targets.
+ */
+export declare function finalizeManifest(session: SessionInfo, entries: AgentManifestEntry[], results: (unknown | null)[]): void;
+/**
+ * Atomically update a single agent's status in the manifest.
+ * Safe under Node.js concurrency — readFileSync + writeFileSync
+ * runs synchronously without event loop interleaving.
+ */
+export declare function updateManifestEntryStatus(session: SessionInfo, agentId: string, status: "completed" | "failed"): void;
+export declare function getCompletedAgentIds(session: SessionInfo): Set<string>;
+export declare function convertModelMessagesToUI(messages: ModelMessage[]): UIMessage[];
+/**
+ * Load all subagent data from disk and merge with the agent manifest.
+ *
+ * This is the single reader for subagent state. It:
+ *  1. Reads all .json files from {rootPath}/{SUBAGENTS_DIR}/
+ *  2. Discovers subdirectories with messages.json (no snapshot .json)
+ *  3. Reads the agent manifest from {rootPath}/{MANIFEST_FILE}
+ *  4. Matches manifest entries to loaded files by agentName === entry.id
+ *  5. Marks matched "running" manifest entries as "paused"
+ *  6. Creates paused stubs for unmatched "running" manifest entries
+ */
+export declare function loadSubagents(rootPath: string): UISubagent[];
+/** A persisted agent message row (Console `agent_messages`). */
+interface ConsoleMessageRow {
+    id: string;
+    sessionId: string;
+    role: "user" | "assistant" | "system";
+    sequence: number;
+    stepSeq: number | null;
+    data: unknown;
+    createdAt: string | Date;
+}
+/** A persisted agent part row (Console `agent_parts`). */
+export interface ConsolePartRow {
+    id: string;
+    messageId: string;
+    sessionId: string;
+    index: number;
+    type: "text" | "tool" | "file" | "subagent_ref";
+    toolCallId: string | null;
+    s3Key: string | null;
+    data: unknown;
+    createdAt: string | Date;
+}
+/** One session node (root or descendant) of a Console session tree. */
+export interface ConsoleSessionNode {
+    session: {
+        id: string;
+        agentType: string;
+        parentSessionId: string | null;
+        status: string;
+        metadata?: unknown;
+    };
+    messages: ConsoleMessageRow[];
+    parts: ConsolePartRow[];
+}
+/**
+ * The full session tree returned by `agentApi.execution.getSessionTree`.
+ * Mirrors the Console shape without importing it.
+ */
+export interface ConsoleSessionTree extends ConsoleSessionNode {
+    descendants: ConsoleSessionNode[];
+}
+/** Result of rehydration: the on-disk root plus in-memory model messages. */
+export interface RehydrateResult {
+    rootPath: string;
+    /** Root-session model messages, ready for the agent constructor. */
+    messages: ModelMessage[];
+    /** childSessionId → that subagent's model messages. */
+    subagentMessages: Map<string, ModelMessage[]>;
+}
+/**
+ * Repair orphan tool-calls left by a mid-step crash by synthesizing a
+ * "process terminated" tool-result for each. Only mutates the in-memory
+ * message list handed to the agent constructor — DB rows are untouched.
+ */
+export declare function repairOrphanToolCalls(messages: ModelMessage[]): ModelMessage[];
+/**
+ * Rebuild a session's on-disk state (session.json, messages.json, and each
+ * descendant's subagents/{childSessionId}/messages.json) from an
+ * already-fetched Console session tree, and return the same messages
+ * in-memory for the agent constructor. Prefer over {@link rehydrateFromConsole}
+ * when the caller already holds the tree.
+ *
+ * @knipignore Console imports this from `@pensar/apex/src/core/session/persistence`;
+ * nothing in this repo calls it, so knip would otherwise report it as dead.
+ */
+export declare function rehydrateFromConsoleTree(sessionId: SessionID, tree: ConsoleSessionTree): RehydrateResult;

package/build/lib/core/session/persistence.js

@@ -0,0 +1,35 @@
+import {
+  loadSubagentMessages2,
+  saveSubagentData2,
+  writeAgentManifest2,
+  readAgentManifest2,
+  buildManifestEntries2,
+  reconcileManifestOnResume2,
+  finalizeManifest2,
+  updateManifestEntryStatus2,
+  getCompletedAgentIds2,
+  convertModelMessagesToUI2,
+  loadSubagents2,
+  repairOrphanToolCalls2,
+  rehydrateFromConsoleTree2
+} from "../../chunk-48zms2q1.js";
+import"../../chunk-3502z798.js";
+import"../../chunk-8vhr65w3.js";
+import"../../chunk-2njv7wz3.js";
+import"../../chunk-jdjagvgr.js";
+import"../../chunk-3w05jmk6.js";
+export {
+  buildManifestEntries2 as buildManifestEntries,
+  convertModelMessagesToUI2 as convertModelMessagesToUI,
+  finalizeManifest2 as finalizeManifest,
+  getCompletedAgentIds2 as getCompletedAgentIds,
+  loadSubagentMessages2 as loadSubagentMessages,
+  loadSubagents2 as loadSubagents,
+  readAgentManifest2 as readAgentManifest,
+  reconcileManifestOnResume2 as reconcileManifestOnResume,
+  rehydrateFromConsoleTree2 as rehydrateFromConsoleTree,
+  repairOrphanToolCalls2 as repairOrphanToolCalls,
+  saveSubagentData2 as saveSubagentData,
+  updateManifestEntryStatus2 as updateManifestEntryStatus,
+  writeAgentManifest2 as writeAgentManifest
+};

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

@@ -0,0 +1,59 @@
+import { z } from "zod";
+/**
+ * Supported vulnerability classes for testing
+ */
+export type VulnerabilityClass = "sqli" | "idor" | "xss" | "command-injection" | "lfi" | "ssrf" | "crypto" | "cve" | "generic";
+/**
+ * Authentication information for testing
+ */
+export interface AuthenticationInfo {
+    method: string;
+    details: string;
+    credentials?: string;
+    cookies?: string;
+    headers?: string;
+}
+/**
+ * Zod schema for document_vulnerability tool input
+ */
+export declare const DocumentFindingSchema: 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>;
+    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>]>>>;
+    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>>>;
+}, z.core.$strip>;

package/build/lib/core/session/usage.d.ts

@@ -0,0 +1,37 @@
+/** Cumulative token usage for one session across all runs and agents. */
+export interface SessionTokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /** Cache-read tokens (Anthropic prompt caching). Already included in inputTokens. */
+    cacheReadTokens: number;
+    /** Cache-write tokens (Anthropic prompt caching). */
+    cacheWriteTokens: number;
+}
+export declare const EMPTY_SESSION_TOKEN_USAGE: SessionTokenUsage;
+/**
+ * The latest root-call context sample. Subagent calls never replace this —
+ * they run in their own short-lived contexts that say nothing about the
+ * operator's conversation size.
+ */
+export interface ContextUsage {
+    usedTokens: number;
+    contextLimit: number;
+    /** The model the root call actually ran on (the denominator's source). */
+    modelId: string;
+}
+/**
+ * Add one step's usage to a session's cumulative totals. Cache-read tokens
+ * are already part of the provider's inputTokens, so they accumulate into
+ * their own counters and are never added into inputTokens.
+ */
+export declare function accumulateSessionTokens(current: SessionTokenUsage, step: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}): SessionTokenUsage;
+/**
+ * Percentage of the context window in use, clamped to [0, 100]. Returns null
+ * when there is no sample or no usable limit (zero limits never divide).
+ */
+export declare function contextPercentage(context: ContextUsage | null): number | null;

package/build/lib/core/skills/builtins/index.d.ts

@@ -0,0 +1,13 @@
+import type { BuiltInSkill } from "../types";
+export { buildPentestPrompt } from "./pentest";
+export { promptInjectionSkill } from "./promptInjection";
+export { buildThreatModelPrompt } from "./threatModel";
+/**
+ * Code-defined skills bundled with the application.
+ *
+ * Built-in skills are loaded into the SkillsRegistry before filesystem skills,
+ * so they take precedence on slug collision (first-write-wins).
+ *
+ * To add a built-in skill, push a BuiltInSkill object into this array.
+ */
+export declare const BUILTIN_SKILLS: BuiltInSkill[];

package/build/lib/core/skills/builtins/pentest.d.ts

@@ -0,0 +1,19 @@
+import type { BuiltInSkill } from "../types";
+/**
+ * Build the full prompt sent to the agent for automated pentest execution.
+ * Injects runtime context (target, auth, scope) into the skill instructions.
+ */
+export declare function buildPentestPrompt(opts: {
+    target: string;
+    cwd?: string;
+    authUrl?: string;
+    authUser?: string;
+    authPass?: string;
+    authInstructions?: string;
+    hosts?: string[];
+    ports?: string[];
+    strict?: boolean;
+    prompt?: string;
+    skillContent: string;
+}): string;
+export declare const pentestSkill: BuiltInSkill;

package/build/lib/core/skills/builtins/promptInjection.d.ts

@@ -0,0 +1,2 @@
+import type { BuiltInSkill } from "../types";
+export declare const promptInjectionSkill: BuiltInSkill;

package/build/lib/core/skills/builtins/threatModel.d.ts

@@ -0,0 +1,11 @@
+import type { BuiltInSkill } from "../types";
+/**
+ * Build the full prompt sent to the agent for threat model generation.
+ * Used by the workflow, CLI, and TUI to ensure identical prompts.
+ */
+export declare function buildThreatModelPrompt(opts: {
+    outputPath: string;
+    codebasePath: string;
+    skillContent: string;
+}): string;
+export declare const threatModelSkill: BuiltInSkill;

package/build/lib/core/skills/index.d.ts

@@ -0,0 +1,5 @@
+import { SkillsRegistry } from "./registry";
+export { SkillsRegistry } from "./registry";
+export type { BuiltInSkill, SkillEntry, SkillManifest, SkillScript, SkillSource, } from "./types";
+/** Create a new SkillsRegistry instance. */
+export declare function createSkillsRegistry(): SkillsRegistry;

package/build/lib/core/skills/parser.d.ts

@@ -0,0 +1,11 @@
+import type { SkillManifest } from "./types";
+/**
+ * Parse a skills.sh-compatible SKILL.md file.
+ *
+ * Expects YAML frontmatter delimited by `---`, followed by markdown body.
+ * Uses the `yaml` package for robust parsing (arrays, nested objects).
+ */
+export declare function parseSkillMd(raw: string): {
+    manifest: SkillManifest;
+    instructions: string;
+};

package/build/lib/core/skills/registry.d.ts

@@ -0,0 +1,30 @@
+import type { SkillEntry } from "./types";
+/**
+ * Central registry for all discovered skills.
+ *
+ * Provides catalog generation for system prompts and on-demand
+ * content loading via `readSkillContent()`.
+ */
+export declare class SkillsRegistry {
+    private skills;
+    private projectRoot?;
+    load(opts?: {
+        projectRoot?: string;
+    }): Promise<void>;
+    refresh(): Promise<void>;
+    list(): SkillEntry[];
+    get(slug: string): SkillEntry | undefined;
+    /**
+     * Read a skill's full instructions from disk on demand.
+     * Used by the `read_skill` tool at runtime.
+     */
+    readSkillContent(slug: string): Promise<{
+        name: string;
+        content: string;
+    }>;
+    /**
+     * Build a compact catalog string suitable for inclusion in the system prompt.
+     * Shows name, tags, and description for progressive disclosure.
+     */
+    buildCatalog(): string;
+}

package/build/lib/core/skills/scanner.d.ts

@@ -0,0 +1,12 @@
+import type { SkillEntry } from "./types";
+/**
+ * Scan all skill roots and return a deduplicated list of SkillEntry objects.
+ *
+ * Scan order (first-write-wins dedup — project skills take priority):
+ *   1. Project: .skills/, .claude/skills/, skills/ → source: "project"
+ *   2. User: ~/.agents/skills/ → source: "user"
+ *   3. User: ~/.pensar/skills/ → source: "user" (directory-based only)
+ */
+export declare function scanSkillRoots(opts?: {
+    projectRoot?: string;
+}): Promise<SkillEntry[]>;

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

@@ -0,0 +1,44 @@
+/** Where a skill was discovered from */
+export type SkillSource = "project" | "user" | "builtin";
+/** Parsed SKILL.md frontmatter */
+export interface SkillManifest {
+    name: string;
+    description: string;
+    version?: string;
+    tags?: string[];
+    triggers?: string[];
+    inputs?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    outputs?: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
+/** A script discovered in the skill's `scripts/` subdirectory */
+export interface SkillScript {
+    name: string;
+    path: string;
+    description?: string;
+}
+/** Unified skill entry used by the registry */
+export interface SkillEntry {
+    slug: string;
+    source: SkillSource;
+    /** Path to SKILL.md */
+    filePath: string;
+    /** Parent directory for directory-based skills */
+    dirPath?: string;
+    manifest: SkillManifest;
+    /** Scripts from the `scripts/` subdirectory */
+    scripts: SkillScript[];
+    lastModified?: number;
+}
+/** A code-defined skill bundled with the application */
+export interface BuiltInSkill {
+    slug: string;
+    manifest: SkillManifest;
+    instructions: string;
+}

package/build/lib/core/skills/utils.d.ts

@@ -0,0 +1,6 @@
+/** Global skills directory: ~/.pensar/skills/ */
+export declare const SKILLS_DIR: string;
+/** skills.sh CLI global install directory: ~/.agents/skills/ */
+export declare const AGENTS_SKILLS_DIR: string;
+/** Convert a display name to a filename-safe slug. */
+export declare function slugify(name: string): string;