ptbk 0.119.0-16 → 0.119.0-21

package/dist/browser/browser.d.ts

@@ -1,8 +1,11 @@
 import { type EffectiveSettings } from '../project/config.js';
 import type { Project } from '../project/workspace.js';
 import type { BridgeTool } from '../engine/bridge.js';
-import type { RequestStore, UserRequest } from '../engine/requests.js';
+import type { TaskChats } from '../chats/task-chats.js';
 import type { TaskTrace } from '../engine/task-trace.js';
+import type { BrowserDetailView } from '../engine/snapshot.js';
+import type { ControlOutcome } from '../service/actions.js';
+import { promptbookAppData } from '../common/app-data.js';
 import { BrowserRecorder } from './recording.js';
 /**
  * Locates a Chrome-compatible browser (configuration, `CHROME_PATH`, standard locations, PATH).
@@ -11,17 +14,67 @@ import { BrowserRecorder } from './recording.js';
  */
 export declare function findBrowserExecutable(settings: EffectiveSettings, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
 /**
- * Resolves the profile directory: the isolated project profile in `.ptbk/` or an explicitly selected path.
+ * Where the project's browser profile comes from (saved in ptbk.json as a portable kind, never a machine path for
+ * the managed global profile).
  *
  * @private project browser
  */
-export declare function browserProfileDirectory(project: Project, settings: EffectiveSettings): string;
+export type BrowserProfileSource = 'global' | 'isolated' | 'user' | 'custom';
+/**
+ * Classifies a `browser.profile` value: `global`, `isolated`, `user`, or a custom profile path.
+ *
+ * @private project browser
+ */
+export declare function browserProfileSource(value: string): BrowserProfileSource;
+export { promptbookAppData };
+/**
+ * The dedicated Promptbook-managed browser profile shared by this user's projects (not the user's own Chrome profile).
+ *
+ * @private project browser
+ */
+export declare function globalBrowserProfile(env?: NodeJS.ProcessEnv): string;
+/**
+ * The user's ordinary Chrome user-data directory on this platform.
+ *
+ * @private project browser
+ */
+export declare function userChromeProfile(env?: NodeJS.ProcessEnv): string;
+/**
+ * Resolves the profile directory of the selected source: the managed global profile, the isolated project profile in
+ * `.ptbk/`, the user's Chrome profile, or a custom path (relative paths resolve against the project).
+ *
+ * @private project browser
+ */
+export declare function browserProfileDirectory(project: Project, settings: EffectiveSettings, env?: NodeJS.ProcessEnv): string;
+/**
+ * Human description of a `browser.profile` value.
+ *
+ * @private project browser
+ */
+export declare function describeBrowserProfile(value: string): string;
 /**
  * Checks whether another browser process currently owns a profile (Chrome's singleton lock).
  *
  * @private project browser
  */
 export declare function profileOwner(profileDirectory: string): Promise<number | undefined>;
+/**
+ * Observed health of the project browser (engine-owned diagnosis and recovery; never inferred from configuration).
+ *
+ * @private project browser
+ */
+export type BrowserHealth = {
+    state: BrowserDetailView['state'];
+    checkedAt?: string;
+    pid?: number;
+    profilePath?: string;
+    actualMode?: 'headless' | 'headful';
+    executable?: string;
+    ownership: BrowserDetailView['ownership'];
+    lastFailure?: BrowserDetailView['lastFailure'];
+    recovery: NonNullable<BrowserDetailView['recovery']>;
+    lastAction?: BrowserDetailView['lastAction'];
+};
 /**
  * The project's single shared browser instance (one profile, one automation owner at a time).
  *
@@ -31,21 +84,73 @@ export declare class ProjectBrowser {
     private readonly project;
     private readonly settings;
     private readonly env;
+    /** Publishes health changes to every view. */
+    private readonly onChange;
     private child?;
+    /** Release of the cross-project claim of a shared profile. */
+    private releaseClaim?;
     private connection?;
     private sessionId?;
     private note?;
-    /** Task-linked recording of browser activity (`traces/<task-id>/video/`). */
+    /** A launch in progress (concurrent automatic/manual starts share it: never two owners). */
+    private launching?;
+    /** The current task used the browser (a restart waits for the task boundary). */
+    private usedByTask;
+    /** A manual restart waits for the current task to release the browser. */
+    private pendingRestart;
+    /** Observed health, diagnostics and recovery. */
+    private health;
+    /** Task-linked recording of browser activity (`traces/<task-file-basename>/video/`). */
     readonly recorder: BrowserRecorder;
-    constructor(project: Project, settings: () => EffectiveSettings, env: NodeJS.ProcessEnv);
+    constructor(project: Project, settings: () => EffectiveSettings, env: NodeJS.ProcessEnv, 
+    /** Publishes health changes to every view. */
+    onChange?: () => void);
+    /** Updates the observed health and notifies the views. */
+    private setHealth;
+    /** Records a real launch/connection failure with redacted evidence. */
+    private recordFailure;
+    /**
+     * The browser as the engine sees it: effective profile source and resolved path, requested/actual mode, health,
+     * ownership, last failure and recovery. A profile path is diagnostic data, never permission to read its contents.
+     */
+    inspect(): BrowserDetailView;
+    /** Records the outcome of a manual browser action. */
+    private acted;
+    /**
+     * Diagnostic recheck (no launch, no change): browser executable, profile existence and ownership, and the live
+     * connection when the browser runs.
+     */
+    recheck(): Promise<ControlOutcome>;
+    /** Retries browser startup now (sharing any launch already in progress); a shared profile is released again when idle. */
+    retry(): Promise<ControlOutcome>;
+    /**
+     * Restarts only this project's own browser process, preserving the selected profile and its sessions. While a task
+     * uses the browser the restart waits for that task's boundary instead of breaking its work.
+     */
+    restart(): Promise<ControlOutcome>;
+    /** Performs a restart at a safe boundary. */
+    private restartNow;
+    /** After a task: performs a deferred restart and releases a shared profile. */
+    taskFinished(): Promise<void>;
+    /** Handles a lost connection: stops only this project's browser process; the next use relaunches it. */
+    private connectionLost;
     /** Associates subsequent browser use with a task attempt for recording. */
     useFor(trace: TaskTrace, attempt: string): Promise<void>;
     /** Unsubscribes the page-transition listener of the current connection. */
     private navigationListener?;
     /** Ensures the browser runs and recording of the attached task has begun. */
     private active;
-    /** Launches (or reuses) the browser and attaches to one page. */
+    /**
+     * Launches (or reuses) the browser and attaches to one page. A technical launch failure is retried automatically
+     * within a bound; concurrent callers share one launch, so automatic and manual recovery never start two owners.
+     */
     private ensure;
+    /** Bounded automatic launch recovery with recorded attempts, causes and next retry. */
+    private launchWithRecovery;
+    /** One launch attempt of the configured browser and profile. */
+    private launchOnce;
+    /** Starts the browser process and attaches to one page. */
+    private launch;
     /** Evaluates JavaScript in the page and returns its value. */
     private evaluate;
     /** Text and interactive elements of the current page (elements get stable `ref` numbers). */
@@ -64,15 +169,20 @@ export declare class ProjectBrowser {
     bringToFront(): Promise<string | undefined>;
     /** Stops only the browser process this service launched (never the user's browsers or the profile). */
     close(): void;
+    /** Releases this project's claim of a shared profile. */
+    private releaseProfile;
+    /**
+     * After a task: a browser on a shared profile (global, user or custom) is closed so other projects can use the
+     * profile; the isolated project profile stays open for the next task.
+     */
+    releaseShared(): void;
 }
 /**
  * Browser tools exposed to agents through the ptbk MCP bridge.
  *
  * @private project browser
  */
-export declare function browserTools(browser: ProjectBrowser, requests: RequestStore, task: {
-    ref: string;
-    id?: string;
-    title: string;
-    agent?: string;
-}, onUserRequest: (request: UserRequest) => void): BridgeTool[];
+export declare function browserTools(browser: ProjectBrowser, chats: TaskChats | undefined, agent: string, onUserChat: (chat: {
+    chat: string;
+    awaited: number;
+}) => void): BridgeTool[];