@prbe.ai/electron-sdk 0.1.4 → 0.1.6

package/dist/index.d.mts

@@ -0,0 +1,332 @@
+import { P as PRBEToolDeclaration, a as PRBEToolParameter, b as PRBEInteractionRequester, F as FlaggedFileIn, c as PRBEAgentState, d as PRBEAgentConfig, I as InvestigationSource, e as InteractionPayload, f as InteractionResponse, g as PollResponse, T as TicketInfoOut } from './types-DHT-JxMT.mjs';
+export { A as API_URL, h as AskQuestionPayload, i as AskQuestionResponse, C as ContextRequestOut, D as DEFAULT_PRBE_STATE, j as InteractionType, k as InvestigationResult, M as MIDDLEWARE_URL, l as PRBEAgentConfigKey, m as PRBEAgentError, n as PRBEAgentErrorType, o as PRBEAgentStatus, p as PRBEAgentStatusType, q as PRBECRInvestigation, r as PRBECompletedInvestigation, s as PRBEInteractionHandler, t as PRBESerializedCR, u as PRBESerializedCompletedInvestigation, v as PRBESerializedState, w as PRBESerializedTicket, x as PRBEStateEvent, y as PRBEStatusEvent, z as PollRequest, R as RequestPathAccessPayload, B as RequestPathAccessResponse, E as RequestPermissionPayload, G as RequestPermissionResponse, H as ResolvedInteraction, J as TicketInfoRequest, K as TicketInfoResponse, L as TicketStatusOut, N as ToolName, O as ToolParamType, W as WSMessage, Q as WSMessageType, S as redactPII, U as serializePRBEState } from './types-DHT-JxMT.mjs';
+import 'events';
+
+/**
+ * tools/index.ts — Tool interface, registry, and closure tool
+ *
+ * Mirrors PRBEAgentTools.swift tool protocol + registry pattern.
+ */
+
+interface PRBETool {
+    readonly declaration: PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+declare class PRBEToolRegistry {
+    private tools;
+    register(tool: PRBETool): void;
+    allDeclarations(): PRBEToolDeclaration[];
+    execute(name: string, args: Record<string, unknown>): Promise<string>;
+}
+declare class PRBEClosureTool implements PRBETool {
+    readonly declaration: PRBEToolDeclaration;
+    private readonly handler;
+    constructor(name: string, description: string, parameters: PRBEToolParameter[], handler: (args: Record<string, unknown>) => Promise<string>);
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+/**
+ * Resolve a path string and validate it against auto-approved directories.
+ * Returns the resolved absolute path or null if outside auto-approved directories.
+ */
+declare function resolveAndValidate(pathStr: string, autoApprovedDirs: string[]): string | null;
+/** Result of resolveWithAccessRequest — resolved path, null (silently denied), or error string for the agent */
+type PathResolution = {
+    path: string;
+} | {
+    error: string;
+} | null;
+/**
+ * Resolve a path, requesting user access if outside auto-approved directories.
+ * When a requester is available and the path fails validation, prompts
+ * the user for permission and caches the grant in `grantedPaths`.
+ *
+ * Returns { path } on success, { error } with a message for the agent, or null.
+ */
+declare function resolveWithAccessRequest(pathStr: string, autoApprovedDirs: string[], grantedPaths: Set<string>, requester?: PRBEInteractionRequester): Promise<PathResolution>;
+/**
+ * Format byte sizes for human-readable output.
+ */
+declare function humanReadableSize(bytes: number): string;
+
+/**
+ * tools/logs.ts — Log capture + built-in log tools
+ *
+ * Implements: client_read_app_logs, client_search_app_logs,
+ *             client_clear_app_logs, client_flag_app_logs
+ *
+ * Mirrors PRBELogCapture.swift + log tool implementations from PRBEAgentTools.swift.
+ * Log capture works by monkey-patching console.log/warn/error in the Electron main process.
+ */
+
+interface LogEntry {
+    timestamp: Date;
+    level: string;
+    category: string;
+    message: string;
+}
+declare class PRBELogCapture {
+    private entries;
+    private readonly maxEntries;
+    private isCapturing;
+    private originalLog?;
+    private originalWarn?;
+    private originalError?;
+    private originalDebug?;
+    private originalInfo?;
+    constructor(maxEntries?: number);
+    log(message: string, level?: string, category?: string): void;
+    get count(): number;
+    getEntries(options?: {
+        offset?: number;
+        limit?: number;
+        level?: string;
+        from?: Date;
+        to?: Date;
+    }): LogEntry[];
+    search(pattern: string, contextLines?: number, maxResults?: number): Array<{
+        index: number;
+        entry: LogEntry;
+    }>;
+    clearLogs(): number;
+    startCapturing(): void;
+    stopCapturing(): void;
+    getAllEntries(): LogEntry[];
+    private append;
+}
+declare class ReadAppLogsTool implements PRBETool {
+    private readonly logCapture;
+    constructor(logCapture: PRBELogCapture);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+declare class SearchAppLogsTool implements PRBETool {
+    private readonly logCapture;
+    constructor(logCapture: PRBELogCapture);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+declare class ClearAppLogsTool implements PRBETool {
+    private readonly logCapture;
+    constructor(logCapture: PRBELogCapture);
+    get declaration(): PRBEToolDeclaration;
+    execute(_args: Record<string, unknown>): Promise<string>;
+}
+declare class FlagAppLogsTool implements PRBETool {
+    private readonly logCapture;
+    private readonly onFlag;
+    constructor(logCapture: PRBELogCapture, onFlag: (file: FlaggedFileIn) => void);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+
+/**
+ * agent.ts — PRBEAgent class
+ *
+ * Main entry point for the PRBE debug agent SDK.
+ * Handles WebSocket connection to middleware, investigation lifecycle,
+ * background polling for context requests, file uploads, and persistence.
+ *
+ * Mirrors PRBEAgent.swift behavior.
+ */
+
+declare class PRBEAgent implements PRBEInteractionRequester {
+    readonly state: PRBEAgentState;
+    readonly logCapture: PRBELogCapture;
+    private readonly config;
+    private readonly appDataPath?;
+    private readonly interactionHandler?;
+    private readonly registry;
+    private readonly grantedPaths;
+    private userCancelled;
+    private activeWS;
+    private pollingTimer;
+    private persistedData;
+    private fetchAbortController;
+    private currentInvestigationSource;
+    private currentCRId;
+    /** Files flagged during the current tool call — uploaded immediately after the tool returns. */
+    private pendingFlaggedFiles;
+    private get agentID();
+    private get trackedTicketIDs();
+    private set trackedTicketIDs(value);
+    private get respondedCRIDs();
+    private set respondedCRIDs(value);
+    private syncPolling;
+    private addTrackedTicket;
+    constructor(config: PRBEAgentConfig);
+    private hookElectronLog;
+    private hookRendererLogs;
+    private static mapElectronLogLevel;
+    get investigationSource(): InvestigationSource;
+    requestUserInteraction(payload: InteractionPayload): Promise<InteractionResponse>;
+    /**
+     * Add an additional root directory to the runtime allowed roots.
+     */
+    addAutoApprovedDir(rootPath: string): void;
+    /**
+     * Register a custom tool that the middleware can invoke during investigations.
+     */
+    registerTool(name: string, description: string, parameters: PRBEToolParameter[], handler: (args: Record<string, unknown>) => Promise<string>): void;
+    /**
+     * User-initiated investigation. Updates `state` events/report directly.
+     */
+    investigate(query: string, contextRequestID?: string): Promise<void>;
+    /**
+     * Cancel user-initiated investigation only (does not cancel background CRs).
+     */
+    cancelInvestigation(): void;
+    /**
+     * Cancel everything — user investigation and polling.
+     */
+    cancel(): void;
+    /**
+     * Poll the backend for context requests on tracked tickets.
+     */
+    poll(): Promise<PollResponse | null>;
+    /**
+     * Fetch ticket display info for all tracked tickets.
+     */
+    fetchTicketInfo(): Promise<TicketInfoOut[]>;
+    stopPolling(): void;
+    resumePolling(): void;
+    /**
+     * Destroy the agent — stops polling, stops console capture, closes WS.
+     */
+    destroy(): void;
+    /**
+     * Reset all persisted data (agent ID, tracked tickets, responded CRs).
+     * Also clears in-memory state.
+     */
+    resetPersistedData(): void;
+    /**
+     * Delete the persisted data file. Can be called without an agent instance.
+     */
+    static clearPersistedData(): void;
+    private investigateForCR;
+    private connectToProxy;
+    private sendCancel;
+    private extractArgs;
+    private extractUploadPrefix;
+    private static backgroundUpload;
+    private startPolling;
+    /**
+     * Abort all in-flight fetch requests to prevent orphaned DNS lookups
+     * that can crash the c-ares resolver during process shutdown.
+     */
+    private abortInFlightRequests;
+    /**
+     * Get an AbortSignal for fetch requests. Creates a new controller if needed.
+     */
+    private getFetchSignal;
+    private post;
+}
+
+/**
+ * tools/filesystem.ts — Built-in filesystem tools
+ *
+ * Implements: client_list_directory, client_read_file, client_search_content,
+ *             client_find_files, client_flag_file
+ *
+ * Mirrors PRBEAgentTools.swift filesystem tool implementations.
+ */
+
+declare class ListDirectoryTool implements PRBETool {
+    private readonly autoApprovedDirs;
+    private readonly requester?;
+    private readonly grantedPaths?;
+    constructor(autoApprovedDirs: string[], requester?: PRBEInteractionRequester, grantedPaths?: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+    private static readonly MAX_ENTRIES;
+    private listDir;
+}
+declare class ReadFileTool implements PRBETool {
+    private readonly autoApprovedDirs;
+    private readonly requester?;
+    private readonly grantedPaths?;
+    constructor(autoApprovedDirs: string[], requester?: PRBEInteractionRequester, grantedPaths?: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+declare class SearchContentTool implements PRBETool {
+    private readonly autoApprovedDirs;
+    private readonly requester?;
+    private readonly grantedPaths?;
+    constructor(autoApprovedDirs: string[], requester?: PRBEInteractionRequester, grantedPaths?: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+    private collectFiles;
+}
+declare class FindFilesTool implements PRBETool {
+    private readonly autoApprovedDirs;
+    private readonly requester?;
+    private readonly grantedPaths?;
+    constructor(autoApprovedDirs: string[], requester?: PRBEInteractionRequester, grantedPaths?: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+    private walkAndMatch;
+    /**
+     * Simple glob matching: supports *, ?, and character classes [...].
+     * Converts glob to regex and tests against the filename.
+     */
+    private globMatch;
+}
+declare class FlagFileTool implements PRBETool {
+    private readonly autoApprovedDirs;
+    private readonly onFlag;
+    private readonly requester?;
+    private readonly grantedPaths?;
+    private static readonly MAX_BINARY_SIZE;
+    constructor(autoApprovedDirs: string[], onFlag: (file: FlaggedFileIn) => void, requester?: PRBEInteractionRequester, grantedPaths?: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+
+/**
+ * tools/interactive.ts — AskUserTool
+ *
+ * Allows the agent to ask the user a question during an investigation.
+ */
+
+declare class AskUserTool implements PRBETool {
+    private readonly requester;
+    constructor(requester: PRBEInteractionRequester);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+
+/**
+ * tools/bash.ts — BashExecuteTool
+ *
+ * Allows the agent to execute shell commands during investigations.
+ * Uses a whitelist-only safety model: commands on the whitelist run without
+ * permission; everything else requires user approval.
+ *
+ * Platform-aware: uses separate whitelists for Unix and Windows, and
+ * runs commands via PowerShell on Windows for consistent behavior.
+ */
+
+declare class BashExecuteTool implements PRBETool {
+    private readonly requester;
+    private readonly autoApprovedDirs;
+    private readonly grantedPaths;
+    constructor(requester: PRBEInteractionRequester, autoApprovedDirs: string[], grantedPaths: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+    /**
+     * Check if a command is on the safe whitelist.
+     */
+    private isCommandSafe;
+    /**
+     * For piped commands, check that every segment uses a safe command.
+     */
+    private areAllPipeSegmentsSafe;
+}
+
+/**
+ * Probe brand mark SVG (transparent background, dark mark).
+ * Exported as a string so host apps can use it inline without bundler plugins.
+ */
+declare const PROBE_MARK_SVG = "<svg width=\"256\" height=\"256\" viewBox=\"0 0 256 256\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n  <path d=\"M50 112 L114 148 L50 184 Z\" fill=\"#111111\" opacity=\"0.07\"/>\n  <path d=\"M70 86 L148 134 L70 182 Z\" fill=\"#111111\" opacity=\"0.18\"/>\n  <path d=\"M92 56 L192 118 L92 180 Z\" fill=\"#111111\"/>\n</svg>";
+
+export { AskUserTool, BashExecuteTool, ClearAppLogsTool, FindFilesTool, FlagAppLogsTool, FlagFileTool, FlaggedFileIn, InteractionPayload, InteractionResponse, InvestigationSource, ListDirectoryTool, type LogEntry, PRBEAgent, PRBEAgentConfig, PRBEAgentState, PRBEClosureTool, PRBEInteractionRequester, PRBELogCapture, type PRBETool, PRBEToolDeclaration, PRBEToolParameter, PRBEToolRegistry, PROBE_MARK_SVG, PollResponse, ReadAppLogsTool, ReadFileTool, SearchAppLogsTool, SearchContentTool, TicketInfoOut, humanReadableSize, resolveAndValidate, resolveWithAccessRequest };

package/dist/index.d.ts

@@ -1,16 +1,332 @@
+import { P as PRBEToolDeclaration, a as PRBEToolParameter, b as PRBEInteractionRequester, F as FlaggedFileIn, c as PRBEAgentState, d as PRBEAgentConfig, I as InvestigationSource, e as InteractionPayload, f as InteractionResponse, g as PollResponse, T as TicketInfoOut } from './types-DHT-JxMT.js';
+export { A as API_URL, h as AskQuestionPayload, i as AskQuestionResponse, C as ContextRequestOut, D as DEFAULT_PRBE_STATE, j as InteractionType, k as InvestigationResult, M as MIDDLEWARE_URL, l as PRBEAgentConfigKey, m as PRBEAgentError, n as PRBEAgentErrorType, o as PRBEAgentStatus, p as PRBEAgentStatusType, q as PRBECRInvestigation, r as PRBECompletedInvestigation, s as PRBEInteractionHandler, t as PRBESerializedCR, u as PRBESerializedCompletedInvestigation, v as PRBESerializedState, w as PRBESerializedTicket, x as PRBEStateEvent, y as PRBEStatusEvent, z as PollRequest, R as RequestPathAccessPayload, B as RequestPathAccessResponse, E as RequestPermissionPayload, G as RequestPermissionResponse, H as ResolvedInteraction, J as TicketInfoRequest, K as TicketInfoResponse, L as TicketStatusOut, N as ToolName, O as ToolParamType, W as WSMessage, Q as WSMessageType, S as redactPII, U as serializePRBEState } from './types-DHT-JxMT.js';
+import 'events';
+
 /**
- * index.ts — Public API exports for @prbe/electron-sdk
- */
-export { PRBEAgent } from "./agent";
-export { PRBEAgentState, PRBEStateEvent } from "./state";
-export { WSMessageType, WSMessage, ToolParamType, ToolName, PRBEToolParameter, PRBEToolDeclaration, PRBEAgentConfigKey, PRBEAgentConfig, PRBEAgentStatus, PRBEAgentStatusType, PRBEAgentError, PRBEAgentErrorType, PRBEStatusEvent, PRBECRInvestigation, PRBECompletedInvestigation, FlaggedFileIn, InvestigationResult, PollRequest, PollResponse, ContextRequestOut, TicketStatusOut, TicketInfoRequest, TicketInfoOut, TicketInfoResponse, redactPII, API_URL, MIDDLEWARE_URL, } from "./models";
-export { InteractionType, InvestigationSource, AskQuestionPayload, RequestPermissionPayload, RequestPathAccessPayload, InteractionPayload, AskQuestionResponse, RequestPermissionResponse, RequestPathAccessResponse, InteractionResponse, ResolvedInteraction, PRBEInteractionRequester, PRBEInteractionHandler, } from "./interactions";
-export { PRBESerializedCR, PRBESerializedTicket, PRBESerializedCompletedInvestigation, PRBESerializedState, DEFAULT_PRBE_STATE, serializePRBEState, } from "./serialization";
-export { PRBETool, PRBEToolRegistry, PRBEClosureTool } from "./tools/index";
-export { resolveAndValidate, resolveWithAccessRequest, humanReadableSize } from "./tools/index";
-export { ListDirectoryTool, ReadFileTool, SearchContentTool, FindFilesTool, FlagFileTool, } from "./tools/filesystem";
-export { PRBELogCapture, LogEntry, ReadAppLogsTool, SearchAppLogsTool, ClearAppLogsTool, FlagAppLogsTool, } from "./tools/logs";
-export { AskUserTool } from "./tools/interactive";
-export { BashExecuteTool } from "./tools/bash";
-export { PROBE_MARK_SVG } from "./assets/index";
-//# sourceMappingURL=index.d.ts.map
+ * tools/index.ts — Tool interface, registry, and closure tool
+ *
+ * Mirrors PRBEAgentTools.swift tool protocol + registry pattern.
+ */
+
+interface PRBETool {
+    readonly declaration: PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+declare class PRBEToolRegistry {
+    private tools;
+    register(tool: PRBETool): void;
+    allDeclarations(): PRBEToolDeclaration[];
+    execute(name: string, args: Record<string, unknown>): Promise<string>;
+}
+declare class PRBEClosureTool implements PRBETool {
+    readonly declaration: PRBEToolDeclaration;
+    private readonly handler;
+    constructor(name: string, description: string, parameters: PRBEToolParameter[], handler: (args: Record<string, unknown>) => Promise<string>);
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+/**
+ * Resolve a path string and validate it against auto-approved directories.
+ * Returns the resolved absolute path or null if outside auto-approved directories.
+ */
+declare function resolveAndValidate(pathStr: string, autoApprovedDirs: string[]): string | null;
+/** Result of resolveWithAccessRequest — resolved path, null (silently denied), or error string for the agent */
+type PathResolution = {
+    path: string;
+} | {
+    error: string;
+} | null;
+/**
+ * Resolve a path, requesting user access if outside auto-approved directories.
+ * When a requester is available and the path fails validation, prompts
+ * the user for permission and caches the grant in `grantedPaths`.
+ *
+ * Returns { path } on success, { error } with a message for the agent, or null.
+ */
+declare function resolveWithAccessRequest(pathStr: string, autoApprovedDirs: string[], grantedPaths: Set<string>, requester?: PRBEInteractionRequester): Promise<PathResolution>;
+/**
+ * Format byte sizes for human-readable output.
+ */
+declare function humanReadableSize(bytes: number): string;
+
+/**
+ * tools/logs.ts — Log capture + built-in log tools
+ *
+ * Implements: client_read_app_logs, client_search_app_logs,
+ *             client_clear_app_logs, client_flag_app_logs
+ *
+ * Mirrors PRBELogCapture.swift + log tool implementations from PRBEAgentTools.swift.
+ * Log capture works by monkey-patching console.log/warn/error in the Electron main process.
+ */
+
+interface LogEntry {
+    timestamp: Date;
+    level: string;
+    category: string;
+    message: string;
+}
+declare class PRBELogCapture {
+    private entries;
+    private readonly maxEntries;
+    private isCapturing;
+    private originalLog?;
+    private originalWarn?;
+    private originalError?;
+    private originalDebug?;
+    private originalInfo?;
+    constructor(maxEntries?: number);
+    log(message: string, level?: string, category?: string): void;
+    get count(): number;
+    getEntries(options?: {
+        offset?: number;
+        limit?: number;
+        level?: string;
+        from?: Date;
+        to?: Date;
+    }): LogEntry[];
+    search(pattern: string, contextLines?: number, maxResults?: number): Array<{
+        index: number;
+        entry: LogEntry;
+    }>;
+    clearLogs(): number;
+    startCapturing(): void;
+    stopCapturing(): void;
+    getAllEntries(): LogEntry[];
+    private append;
+}
+declare class ReadAppLogsTool implements PRBETool {
+    private readonly logCapture;
+    constructor(logCapture: PRBELogCapture);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+declare class SearchAppLogsTool implements PRBETool {
+    private readonly logCapture;
+    constructor(logCapture: PRBELogCapture);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+declare class ClearAppLogsTool implements PRBETool {
+    private readonly logCapture;
+    constructor(logCapture: PRBELogCapture);
+    get declaration(): PRBEToolDeclaration;
+    execute(_args: Record<string, unknown>): Promise<string>;
+}
+declare class FlagAppLogsTool implements PRBETool {
+    private readonly logCapture;
+    private readonly onFlag;
+    constructor(logCapture: PRBELogCapture, onFlag: (file: FlaggedFileIn) => void);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+
+/**
+ * agent.ts — PRBEAgent class
+ *
+ * Main entry point for the PRBE debug agent SDK.
+ * Handles WebSocket connection to middleware, investigation lifecycle,
+ * background polling for context requests, file uploads, and persistence.
+ *
+ * Mirrors PRBEAgent.swift behavior.
+ */
+
+declare class PRBEAgent implements PRBEInteractionRequester {
+    readonly state: PRBEAgentState;
+    readonly logCapture: PRBELogCapture;
+    private readonly config;
+    private readonly appDataPath?;
+    private readonly interactionHandler?;
+    private readonly registry;
+    private readonly grantedPaths;
+    private userCancelled;
+    private activeWS;
+    private pollingTimer;
+    private persistedData;
+    private fetchAbortController;
+    private currentInvestigationSource;
+    private currentCRId;
+    /** Files flagged during the current tool call — uploaded immediately after the tool returns. */
+    private pendingFlaggedFiles;
+    private get agentID();
+    private get trackedTicketIDs();
+    private set trackedTicketIDs(value);
+    private get respondedCRIDs();
+    private set respondedCRIDs(value);
+    private syncPolling;
+    private addTrackedTicket;
+    constructor(config: PRBEAgentConfig);
+    private hookElectronLog;
+    private hookRendererLogs;
+    private static mapElectronLogLevel;
+    get investigationSource(): InvestigationSource;
+    requestUserInteraction(payload: InteractionPayload): Promise<InteractionResponse>;
+    /**
+     * Add an additional root directory to the runtime allowed roots.
+     */
+    addAutoApprovedDir(rootPath: string): void;
+    /**
+     * Register a custom tool that the middleware can invoke during investigations.
+     */
+    registerTool(name: string, description: string, parameters: PRBEToolParameter[], handler: (args: Record<string, unknown>) => Promise<string>): void;
+    /**
+     * User-initiated investigation. Updates `state` events/report directly.
+     */
+    investigate(query: string, contextRequestID?: string): Promise<void>;
+    /**
+     * Cancel user-initiated investigation only (does not cancel background CRs).
+     */
+    cancelInvestigation(): void;
+    /**
+     * Cancel everything — user investigation and polling.
+     */
+    cancel(): void;
+    /**
+     * Poll the backend for context requests on tracked tickets.
+     */
+    poll(): Promise<PollResponse | null>;
+    /**
+     * Fetch ticket display info for all tracked tickets.
+     */
+    fetchTicketInfo(): Promise<TicketInfoOut[]>;
+    stopPolling(): void;
+    resumePolling(): void;
+    /**
+     * Destroy the agent — stops polling, stops console capture, closes WS.
+     */
+    destroy(): void;
+    /**
+     * Reset all persisted data (agent ID, tracked tickets, responded CRs).
+     * Also clears in-memory state.
+     */
+    resetPersistedData(): void;
+    /**
+     * Delete the persisted data file. Can be called without an agent instance.
+     */
+    static clearPersistedData(): void;
+    private investigateForCR;
+    private connectToProxy;
+    private sendCancel;
+    private extractArgs;
+    private extractUploadPrefix;
+    private static backgroundUpload;
+    private startPolling;
+    /**
+     * Abort all in-flight fetch requests to prevent orphaned DNS lookups
+     * that can crash the c-ares resolver during process shutdown.
+     */
+    private abortInFlightRequests;
+    /**
+     * Get an AbortSignal for fetch requests. Creates a new controller if needed.
+     */
+    private getFetchSignal;
+    private post;
+}
+
+/**
+ * tools/filesystem.ts — Built-in filesystem tools
+ *
+ * Implements: client_list_directory, client_read_file, client_search_content,
+ *             client_find_files, client_flag_file
+ *
+ * Mirrors PRBEAgentTools.swift filesystem tool implementations.
+ */
+
+declare class ListDirectoryTool implements PRBETool {
+    private readonly autoApprovedDirs;
+    private readonly requester?;
+    private readonly grantedPaths?;
+    constructor(autoApprovedDirs: string[], requester?: PRBEInteractionRequester, grantedPaths?: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+    private static readonly MAX_ENTRIES;
+    private listDir;
+}
+declare class ReadFileTool implements PRBETool {
+    private readonly autoApprovedDirs;
+    private readonly requester?;
+    private readonly grantedPaths?;
+    constructor(autoApprovedDirs: string[], requester?: PRBEInteractionRequester, grantedPaths?: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+declare class SearchContentTool implements PRBETool {
+    private readonly autoApprovedDirs;
+    private readonly requester?;
+    private readonly grantedPaths?;
+    constructor(autoApprovedDirs: string[], requester?: PRBEInteractionRequester, grantedPaths?: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+    private collectFiles;
+}
+declare class FindFilesTool implements PRBETool {
+    private readonly autoApprovedDirs;
+    private readonly requester?;
+    private readonly grantedPaths?;
+    constructor(autoApprovedDirs: string[], requester?: PRBEInteractionRequester, grantedPaths?: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+    private walkAndMatch;
+    /**
+     * Simple glob matching: supports *, ?, and character classes [...].
+     * Converts glob to regex and tests against the filename.
+     */
+    private globMatch;
+}
+declare class FlagFileTool implements PRBETool {
+    private readonly autoApprovedDirs;
+    private readonly onFlag;
+    private readonly requester?;
+    private readonly grantedPaths?;
+    private static readonly MAX_BINARY_SIZE;
+    constructor(autoApprovedDirs: string[], onFlag: (file: FlaggedFileIn) => void, requester?: PRBEInteractionRequester, grantedPaths?: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+
+/**
+ * tools/interactive.ts — AskUserTool
+ *
+ * Allows the agent to ask the user a question during an investigation.
+ */
+
+declare class AskUserTool implements PRBETool {
+    private readonly requester;
+    constructor(requester: PRBEInteractionRequester);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+
+/**
+ * tools/bash.ts — BashExecuteTool
+ *
+ * Allows the agent to execute shell commands during investigations.
+ * Uses a whitelist-only safety model: commands on the whitelist run without
+ * permission; everything else requires user approval.
+ *
+ * Platform-aware: uses separate whitelists for Unix and Windows, and
+ * runs commands via PowerShell on Windows for consistent behavior.
+ */
+
+declare class BashExecuteTool implements PRBETool {
+    private readonly requester;
+    private readonly autoApprovedDirs;
+    private readonly grantedPaths;
+    constructor(requester: PRBEInteractionRequester, autoApprovedDirs: string[], grantedPaths: Set<string>);
+    get declaration(): PRBEToolDeclaration;
+    execute(args: Record<string, unknown>): Promise<string>;
+    /**
+     * Check if a command is on the safe whitelist.
+     */
+    private isCommandSafe;
+    /**
+     * For piped commands, check that every segment uses a safe command.
+     */
+    private areAllPipeSegmentsSafe;
+}
+
+/**
+ * Probe brand mark SVG (transparent background, dark mark).
+ * Exported as a string so host apps can use it inline without bundler plugins.
+ */
+declare const PROBE_MARK_SVG = "<svg width=\"256\" height=\"256\" viewBox=\"0 0 256 256\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n  <path d=\"M50 112 L114 148 L50 184 Z\" fill=\"#111111\" opacity=\"0.07\"/>\n  <path d=\"M70 86 L148 134 L70 182 Z\" fill=\"#111111\" opacity=\"0.18\"/>\n  <path d=\"M92 56 L192 118 L92 180 Z\" fill=\"#111111\"/>\n</svg>";
+
+export { AskUserTool, BashExecuteTool, ClearAppLogsTool, FindFilesTool, FlagAppLogsTool, FlagFileTool, FlaggedFileIn, InteractionPayload, InteractionResponse, InvestigationSource, ListDirectoryTool, type LogEntry, PRBEAgent, PRBEAgentConfig, PRBEAgentState, PRBEClosureTool, PRBEInteractionRequester, PRBELogCapture, type PRBETool, PRBEToolDeclaration, PRBEToolParameter, PRBEToolRegistry, PROBE_MARK_SVG, PollResponse, ReadAppLogsTool, ReadFileTool, SearchAppLogsTool, SearchContentTool, TicketInfoOut, humanReadableSize, resolveAndValidate, resolveWithAccessRequest };