@sayknow-cli/coding-agent 0.4.2 → 0.4.3

package/dist/types/tools/bash.d.ts

@@ -0,0 +1,160 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@sayknow-cli/agent-core";
+import type { Component } from "@sayknow-cli/tui";
+import * as z from "zod/v4";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { type Theme } from "../modes/theme/theme";
+import type { ToolSession } from ".";
+import { type OutputMeta } from "./output-meta";
+export declare const BASH_DEFAULT_PREVIEW_LINES = 10;
+export declare function saveBashOriginalArtifactForTests(session: ToolSession, originalText: string): Promise<string | undefined>;
+declare const bashSchemaBase: z.ZodObject<{
+    command: z.ZodString;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    pty: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const bashSchemaWithAsync: z.ZodObject<{
+    command: z.ZodString;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    pty: z.ZodOptional<z.ZodBoolean>;
+    async: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type BashToolSchema = typeof bashSchemaBase | typeof bashSchemaWithAsync;
+export interface BashToolInput {
+    command: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    cwd?: string;
+    async?: boolean;
+    pty?: boolean;
+}
+export interface BashToolDetails {
+    meta?: OutputMeta;
+    timeoutSeconds?: number;
+    requestedTimeoutSeconds?: number;
+    terminalId?: string;
+    async?: {
+        state: "running" | "completed" | "failed";
+        jobId: string;
+        type: "bash";
+    };
+}
+/** Project only a bare executable name; commands and their output are never notification-safe. */
+export declare function summarizeBashToolActivity(kind: "args" | "result", value: unknown): string | undefined;
+export interface BashToolOptions {
+}
+/**
+ * Bash tool implementation.
+ *
+ * Executes bash commands with optional timeout and working directory.
+ */
+export declare class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "bash";
+    readonly label = "Bash";
+    readonly loadMode = "essential";
+    readonly description: string;
+    readonly parameters: BashToolSchema;
+    readonly concurrency = "exclusive";
+    readonly strict = true;
+    readonly safeSummary: typeof summarizeBashToolActivity;
+    constructor(session: ToolSession);
+    /**
+     * Start a background bash job for the Monitor tool. Reuses the full Bash
+     * pipeline (interceptors, internal-URL expansion, env, cwd, timeout); the
+     * public `monitor` tool itself is ACP-gated by `AgentSession` before this
+     * helper is called. The caller-supplied `onRawLine` callback is invoked once
+     * per newline-terminated stdout chunk, between turns, so the upstream Claude
+     * Code "Each stdout line is a task-notification event" semantics are preserved
+     * through the agent's existing background-task delivery path.
+     */
+    startMonitorJob(input: {
+        command: string;
+        cwd?: string;
+        timeout?: number;
+        env?: Record<string, string>;
+    }, opts?: {
+        ownerId?: string;
+        label?: string;
+        ctx?: AgentToolContext;
+        onRawLine?: (line: string, jobId: string) => void;
+        shouldAcceptRawLine?: (jobId: string) => boolean;
+        lifecycle?: import("../async").AsyncJobLifecycleCleanup;
+    }): Promise<{
+        jobId: string;
+        label: string;
+        commandCwd: string;
+    }>;
+    execute(_toolCallId: string, { command: rawCommand, env: rawEnv, timeout: rawTimeout, cwd, async: asyncRequested, pty, }: BashToolInput, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<BashToolDetails>, ctx?: AgentToolContext): Promise<AgentToolResult<BashToolDetails>>;
+}
+export interface BashRenderArgs {
+    command?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    cwd?: string;
+    __partialJson?: string;
+    [key: string]: unknown;
+}
+export interface BashRenderContext {
+    /** Raw output text */
+    output?: string;
+    /** Whether output came from artifact storage */
+    isFullOutput?: boolean;
+    /** Whether output is expanded */
+    expanded?: boolean;
+    /** Number of preview lines when collapsed */
+    previewLines?: number;
+    /** Timeout in seconds */
+    timeout?: number;
+}
+export interface ShellRendererConfig<TArgs> {
+    resolveTitle: (args: TArgs | undefined, options: RenderResultOptions) => string;
+    resolveCommand?: (args: TArgs | undefined) => string | undefined;
+    resolveCwd?: (args: TArgs | undefined) => string | undefined;
+    resolveEnv?: (args: TArgs | undefined) => Record<string, string> | undefined;
+}
+export declare function getBashEnvForDisplay(args: BashRenderArgs): Record<string, string> | undefined;
+export declare function formatBashCommand(args: BashRenderArgs): string;
+/**
+ * Returns the bash command formatted for the result body: the dim `$ cd … &&`
+ * prefix joined with syntax-highlighted command lines. The prefix is applied
+ * only to the first line so multi-line commands display cleanly — terminals
+ * reset SGR state at line boundaries, which made the previous single-string
+ * `theme.fg("dim", ...)` form render only the first line as dim.
+ */
+export declare function formatBashCommandLines(args: BashRenderArgs, uiTheme: Theme): string[];
+export declare function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>): {
+    renderCall(args: TArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: BashToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions & {
+        renderContext?: BashRenderContext;
+    }, uiTheme: Theme, args?: TArgs): Component;
+    mergeCallAndResult: boolean;
+    inline: boolean;
+};
+export declare const bashToolRenderer: {
+    renderCall(args: BashRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: {
+            type: string;
+            text?: string;
+        }[];
+        details?: BashToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions & {
+        renderContext?: BashRenderContext;
+    }, uiTheme: Theme, args?: BashRenderArgs | undefined): Component;
+    mergeCallAndResult: boolean;
+    inline: boolean;
+};
+export {};

package/dist/types/tools/bisect.d.ts

@@ -0,0 +1,81 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@sayknow-cli/agent-core";
+import * as z from "zod/v4";
+import type { ToolSession } from ".";
+import type { OutputMeta } from "./output-meta";
+declare const bisectSchema: z.ZodObject<{
+    good: z.ZodString;
+    bad: z.ZodDefault<z.ZodString>;
+    run: z.ZodString;
+    invert: z.ZodDefault<z.ZodBoolean>;
+    maxSteps: z.ZodDefault<z.ZodNumber>;
+    stepTimeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type BisectParams = z.infer<typeof bisectSchema>;
+export type BisectVerdict = "good" | "bad" | "skip";
+export interface BisectStep {
+    rev: string;
+    verdict: BisectVerdict;
+}
+export interface BisectMarkResult {
+    exitCode: number;
+    output: string;
+}
+export interface BisectControllerDeps {
+    maxSteps: number;
+    /** SHA of the revision git currently has checked out. */
+    currentRev: () => Promise<string>;
+    /** Evaluate the predicate at the checked-out revision. */
+    evaluate: (rev: string) => Promise<BisectVerdict>;
+    /** Apply the verdict via `git bisect good|bad|skip` and return the raw result. */
+    mark: (verdict: BisectVerdict) => Promise<BisectMarkResult>;
+}
+export interface BisectOutcome {
+    culprit: string | null;
+    steps: BisectStep[];
+    concluded: boolean;
+    reason?: string;
+}
+export interface BisectToolDetails {
+    meta?: OutputMeta;
+    culprit: string | null;
+    invert: boolean;
+    concluded: boolean;
+    steps: BisectStep[];
+    author?: string;
+    date?: string;
+    subject?: string;
+    reason?: string;
+}
+/** Parse the culprit SHA from `git bisect good|bad` output, or null when not yet converged. */
+export declare function parseFirstBadCommit(output: string): string | null;
+/**
+ * Map a predicate exit code to a bisect verdict. `invert` swaps the good/bad
+ * mapping (to hunt for a fixing commit) but never reinterprets a skip.
+ */
+export declare function classifyExit(exitCode: number, invert: boolean): BisectVerdict;
+/**
+ * Drive the bisect loop. Pure orchestration — every git/predicate effect is
+ * injected — so it can be exercised deterministically without a real repo.
+ */
+export declare function runBisectController(deps: BisectControllerDeps, signal?: AbortSignal): Promise<BisectOutcome>;
+export declare class BisectTool implements AgentTool<typeof bisectSchema, BisectToolDetails> {
+    private readonly session;
+    readonly name = "bisect";
+    readonly label = "Bisect";
+    readonly summary = "Find the commit that introduced a regression by driving git bisect with a shell predicate";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        good: z.ZodString;
+        bad: z.ZodDefault<z.ZodString>;
+        run: z.ZodString;
+        invert: z.ZodDefault<z.ZodBoolean>;
+        maxSteps: z.ZodDefault<z.ZodNumber>;
+        stepTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly loadMode = "discoverable";
+    readonly intent: (args: Partial<BisectParams>) => string;
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: BisectParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<BisectToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<BisectToolDetails>>;
+}
+export {};

package/dist/types/tools/browser/actions.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Structured browser action space.
+ *
+ * Adapts the SOTA computer-use / browser-use pattern: instead of authoring raw
+ * JavaScript for every interaction, the model emits a list of structured verbs
+ * (navigate / click / type / …) that reference elements by the numeric `id`
+ * returned from {@link Observation}. Each verb is compiled onto the existing
+ * in-tab `tab.*` helpers and executed through the same worker `run` path, so the
+ * worker protocol is unchanged and the raw-JS `run` escape hatch still works.
+ */
+export type BrowserActionVerb = "navigate" | "click" | "type" | "fill" | "select" | "press" | "scroll" | "back" | "wait" | "observe" | "extract" | "screenshot";
+export interface BrowserActionStep {
+    verb: BrowserActionVerb;
+    /** Element id from a prior `observe` (preferred for click/type). */
+    id?: number;
+    /** CSS / puppeteer selector when not addressing by `id`. */
+    selector?: string;
+    /** Text to type. */
+    text?: string;
+    /** Value for `fill`. */
+    value?: string;
+    /** Option value(s) for `select`. */
+    values?: string[];
+    /** URL for `navigate`. */
+    url?: string;
+    /** Key for `press` (e.g. "Enter"). */
+    key?: string;
+    /** Horizontal scroll delta. */
+    dx?: number;
+    /** Vertical scroll delta. */
+    dy?: number;
+    /** Sleep duration for `wait` when no selector is given. */
+    ms?: number;
+    /** Extract format. */
+    format?: "markdown" | "text" | "html";
+    /** Navigation wait condition for `navigate`. */
+    wait_until?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+    /** Only return interactive/viewport elements for `observe`. */
+    viewport_only?: boolean;
+    include_all?: boolean;
+}
+/**
+ * Validate a single step's required fields. Returns an error string, or
+ * `undefined` when the step is well-formed.
+ */
+export declare function validateActionStep(step: BrowserActionStep, index: number): string | undefined;
+/** Validate the full step list. Throws on the first invalid step. */
+export declare function validateActionSteps(steps: readonly BrowserActionStep[]): void;
+/**
+ * Compile structured steps into a JS program for the in-tab `run` worker. Steps
+ * are embedded as parsed JSON (no string interpolation, so values cannot inject
+ * code) and dispatched by a fixed interpreter against the `tab` / `page` helpers.
+ */
+export declare function compileActionSteps(steps: readonly BrowserActionStep[]): string;

package/dist/types/tools/browser/attach.d.ts

@@ -0,0 +1,50 @@
+import type { Browser, Page } from "puppeteer-core";
+/**
+ * Allocate an unused TCP port on 127.0.0.1 by binding to port 0 and reading
+ * back the kernel-assigned port. There's a small race between close and the
+ * subsequent bind in the launched app, but Chromium's listener will retry.
+ */
+export declare function findFreeCdpPort(): Promise<number>;
+/** Poll `${cdpUrl}/json/version` until it responds with 200, with abort + timeout support. */
+export declare function waitForCdp(cdpUrl: string, timeoutMs: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Pull a `--remote-debugging-port=<n>` value out of an argv array (Chromium
+ * accepts both `--flag=value` and `--flag value`). Returns null if absent or
+ * malformed.
+ */
+export declare function findCdpPortInArgsForTest(args: string[]): number | null;
+export declare function findCdpAddressInArgsForTest(args: readonly string[]): string | null;
+export declare function isSafeCdpAddressForTest(address: string | null): boolean;
+export declare function argsMatchChromeProfileForTest(args: readonly string[], profile: {
+    userDataDir: string;
+    profileDirectory: string;
+}): boolean;
+export declare function findReusableCdp(exe: string, signal?: AbortSignal): Promise<{
+    cdpUrl: string;
+    pid: number;
+} | null>;
+export interface RunningChromeProfile {
+    pid: number;
+    cdpUrl: string | null;
+    unsafeCdpReason?: string;
+}
+export declare function findRunningChromeProfile(exe: string, profile: {
+    userDataDir: string;
+    profileDirectory: string;
+}, signal?: AbortSignal): Promise<RunningChromeProfile | null>;
+/**
+ * Pick the best page target on an attached browser. Without a matcher, prefer
+ * a page that doesn't look like a helper window (devtools, request handler,
+ * background pages); with a matcher, return the first url+title substring hit.
+ */
+export declare function pickElectronTarget(browser: Browser, matcher?: string): Promise<Page>;
+/**
+ * SIGTERM the process tree, wait briefly, then SIGKILL anything still alive.
+ * Single-process variant for our own spawned children.
+ */
+export declare function gracefulKillTreeOnce(pid: number, gracePeriodMs?: number): Promise<void>;
+/**
+ * Multi-process variant for attach: find every PID running `executablePath`
+ * (single-instance apps may keep an orphan around) and tear them all down.
+ */
+export declare function killExistingByPath(executablePath: string, signal?: AbortSignal): Promise<number>;

package/dist/types/tools/browser/benchmark/detector-report.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Offline stealth-detector benchmark model.
+ *
+ * Pure, deterministic logic for the anti-detection benchmark suite: it converts
+ * a browser-collected fingerprint probe into a normalized per-detector verdict,
+ * implements the falsifiable CI gate (see plan Phase 1 / R-T3), and renders a
+ * before/after report. No browser or network access lives here so it can be
+ * unit-tested deterministically; the harness that drives the real browser tool
+ * against vendored detector fixtures feeds its output into these functions.
+ */
+export type SignalStatus = "pass" | "fail";
+/** A single boolean fingerprint signal, e.g. "navigator.webdriver is undefined". */
+export interface DetectorSignal {
+    /** Stable identifier, used to diff across runs. */
+    id: string;
+    /** Human-readable label for the report. */
+    label: string;
+    /** `pass` means the signal looks human; `fail` means it leaks automation. */
+    status: SignalStatus;
+    /** Optional observed value for debugging. */
+    detail?: string;
+}
+export type AutomatedVerdict = "human" | "bot" | "unknown";
+/** Normalized result for one detector (e.g. bot.sannysoft, CreepJS). */
+export interface DetectorResult {
+    detector: string;
+    signals: DetectorSignal[];
+    /** Overall automated/not classification when the detector exposes one. */
+    automatedVerdict: AutomatedVerdict;
+    /** Absolute trust score (observability-only, never a hard gate). */
+    trustScore: number | null;
+}
+/** Shape emitted by the offline probe fixture on `window.__stealthProbe`. */
+export interface RawProbe {
+    detector: string;
+    signals: Array<{
+        id: string;
+        label: string;
+        pass: boolean;
+        detail?: string;
+    }>;
+    automatedVerdict?: AutomatedVerdict;
+    trustScore?: number | null;
+}
+/** Convert a raw browser-collected probe into a normalized {@link DetectorResult}. */
+export declare function parseProbe(raw: RawProbe): DetectorResult;
+export interface GateOutcome {
+    pass: boolean;
+    reasons: string[];
+}
+/**
+ * Falsifiable CI gate (plan Phase 1 / R-T3, R-C1, R-C2):
+ *   (a) zero failing signals in the current run, AND
+ *       current pass-count >= baseline pass-count (no silent regression), AND
+ *   (b) either at least one signal that failed at baseline now passes,
+ *       OR the baseline was already all-green (empty-gap regression lock).
+ * The absolute `trustScore` is never consulted here; it is observability-only.
+ */
+export declare function evaluateGate(baseline: DetectorResult, current: DetectorResult): GateOutcome;
+/** Aggregate gate across every detector; passes only when all detectors pass. */
+export declare function evaluateSuiteGate(baseline: readonly DetectorResult[], current: readonly DetectorResult[]): GateOutcome;
+/** Render a deterministic before/after markdown report for one run. */
+export declare function renderReport(baseline: readonly DetectorResult[], current: readonly DetectorResult[]): string;

package/dist/types/tools/browser/benchmark/run-suite.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Offline stealth benchmark harness (plan Phase 1).
+ *
+ * Drives a puppeteer Page (already stealth-patched by the browser tool) against
+ * self-contained offline detector fixtures and collects normalized results. The
+ * navigation/evaluation is injected so this stays unit-testable without a real
+ * browser; the integration test wires a live puppeteer Page.
+ */
+import type { Page } from "puppeteer-core";
+import type { DetectorResult } from "./detector-report";
+/** Minimal surface of a puppeteer Page that the harness needs. */
+export type SuitePage = Pick<Page, "goto" | "evaluate">;
+export interface SuiteFixture {
+    /** file:// (or http://) URL of the offline detector fixture. */
+    url: string;
+}
+/** Navigate to each fixture and collect a normalized DetectorResult per fixture. */
+export declare function runOfflineSuite(page: SuitePage, fixtures: readonly SuiteFixture[]): Promise<DetectorResult[]>;

package/dist/types/tools/browser/dead-tab-recovery.d.ts

@@ -0,0 +1,24 @@
+export type DeadTabRecoveryConsumeStatus = "consumed" | "expired_or_missing" | "owner_mismatch";
+export interface DeadTabRecoveryConsumeResult<T> {
+    status: DeadTabRecoveryConsumeStatus;
+    descriptor?: T;
+}
+interface DeadTabRecoveryDeps {
+    now(): number;
+    onPeek(): void;
+}
+/** Store a short-lived immutable recovery descriptor for a dead tab worker. */
+export declare function registerDeadTabRecovery<T extends object>(name: string, ownerId: string | undefined, descriptor: T, ttlMs?: number): void;
+/**
+ * Check whether a recovery descriptor may be consumed by this owner. The test hook is
+ * intentionally synchronous: recovery must not yield between this check and consume.
+ */
+export declare function peekDeadTabRecovery<T>(name: string, ownerId: string | undefined): DeadTabRecoveryConsumeResult<T>;
+/** Consume only a live descriptor belonging to the expected owner. */
+export declare function consumeDeadTabRecovery<T>(name: string, ownerId: string | undefined): DeadTabRecoveryConsumeResult<T>;
+export declare function discardDeadTabRecovery(name: string): void;
+/** Whether an unconsumed descriptor remains live at the supplied policy clock. */
+export declare function isDeadTabRecoveryLive(name: string, now: number): boolean;
+export declare function __setDeadTabRecoveryDepsForTest(overrides: Partial<DeadTabRecoveryDeps>): void;
+export declare function __resetDeadTabRecoveryForTest(): void;
+export {};

package/dist/types/tools/browser/launch.d.ts

@@ -0,0 +1,84 @@
+import type { Browser, CDPSession, Page, default as Puppeteer, Target } from "puppeteer-core";
+export declare const DEFAULT_VIEWPORT: {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+};
+/**
+ * Per-CDP-message timeout applied to every puppeteer launch/connect. Set above
+ * `TOOL_TIMEOUTS.browser.max` (30s) so the agent-side wall-clock is the canonical
+ * limit; this constant only catches genuinely stuck CDP sockets (renderer wedged,
+ * connection dropped, etc.).
+ */
+export declare const BROWSER_PROTOCOL_TIMEOUT_MS = 60000;
+export declare function loadPuppeteer(): Promise<typeof Puppeteer>;
+export declare function loadPuppeteerInWorker(safeDir: string): Promise<typeof Puppeteer>;
+export interface LaunchHeadlessOptions {
+    headless: boolean;
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+    };
+    /**
+     * Optional isolated warm-up profile directory (see profile-reuse.ts). When
+     * set, the headless browser launches against this isolated copy of the user's
+     * real Chrome profile so sessions inherit real cookies/storage/cache for
+     * stronger stealth. Callers resolve this via resolveProfileReuse and MUST
+     * pass an isolated copy, never a live profile dir.
+     */
+    profileWarmupDir?: string;
+    /**
+     * Optional opt-in geo alignment (see settings browser.geo.*). When set, the
+     * browser is launched with a matching timezone (TZ env) and/or UI language
+     * (--lang) at the source. Default unset = strict no-op: the real environment
+     * timezone/locale are preserved (never half-spoof). Only align these to a
+     * coherent value (e.g. one matching a configured proxy egress).
+     */
+    geo?: {
+        timezone?: string;
+        locale?: string;
+    };
+}
+export declare function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<Browser>;
+export declare function applyViewport(page: Page, viewport?: {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+}): Promise<void>;
+export interface UserAgentOverride {
+    userAgent: string;
+    platform: string;
+    acceptLanguage: string;
+    userAgentMetadata: {
+        brands: Array<{
+            brand: string;
+            version: string;
+        }>;
+        fullVersion: string;
+        platform: string;
+        platformVersion: string;
+        architecture: string;
+        model: string;
+        mobile: boolean;
+    };
+}
+export interface UserAgentSession {
+    override: UserAgentOverride;
+    browserSession: CDPSession | null;
+}
+/** Builds the browser-page stealth bootstrap source for regression tests. */
+export declare function buildStealthInjectionScriptForTest(scripts?: readonly string[]): string;
+/** Apply stealth patches + UA override to a headless page. Idempotent within a tab. */
+export declare function applyStealthPatches(browser: Browser, page: Page, state: {
+    browserSession: CDPSession | null;
+    override: UserAgentOverride | null;
+}, geo?: {
+    readonly timezone?: string;
+    readonly locale?: string;
+}): Promise<void>;
+export declare function targetSupportsUserAgentOverrideForTest(target: Target): boolean;
+export declare function configureUserAgentTargetsForTest(browser: Browser, state: {
+    browserSession: CDPSession | null;
+    override: UserAgentOverride;
+}, targetTimeoutMs?: number): Promise<void>;

package/dist/types/tools/browser/profile-discovery.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Default Chrome profile discovery (plan Phase 2 wiring).
+ *
+ * Locates the user's real Chrome "Default" profile directory per OS so the
+ * default headless launch path can warm up synthetic sessions from an isolated
+ * copy of it (see profile-warmup.ts + profile-posture.ts). Pure path logic with
+ * an injectable existence check, so it is unit-testable without touching the
+ * real filesystem.
+ */
+export interface DiscoveryEnv {
+    platform: NodeJS.Platform;
+    home: string;
+    /** Injectable for tests; defaults to fs.existsSync at call sites. */
+    exists: (p: string) => boolean;
+    /** Windows LOCALAPPDATA override (tests / non-default installs). */
+    localAppData?: string;
+}
+/** Candidate Chrome user-data roots for the platform (most common first). */
+export declare function chromeUserDataRoots(env: DiscoveryEnv): string[];
+export interface DiscoveredProfile {
+    userDataDir: string;
+    profileDirectory: string;
+    profileDir: string;
+}
+/**
+ * Discover the default Chrome profile, or null when none is present.
+ * Only returns a profile whose directory actually exists.
+ */
+export declare function discoverDefaultChromeProfile(env: DiscoveryEnv, profileDirectory?: string): DiscoveredProfile | null;
+/** Convenience wrapper using the live OS environment + fs. */
+export declare function defaultDiscoveryEnv(exists: (p: string) => boolean): DiscoveryEnv;

package/dist/types/tools/browser/profile-posture.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Auto-default profile-reuse posture decision (plan Phase 2, Intent Reconciliation).
+ *
+ * User-confirmed policy: when a usable real Chrome profile is available, the
+ * browser tool uses it automatically (AUTO), emits a warning, and falls back to
+ * synthetic stealth when unavailable. The posture is overridable via a setting.
+ * This is pure decision logic (no browser, no filesystem side effects) so the
+ * launch/attach layer can call it and it can be unit-tested deterministically.
+ */
+/** Configured posture: `auto` (default) prefers the real profile; `opt-in` stays synthetic unless explicitly asked. */
+export type ProfileReusePosture = "auto" | "opt-in";
+export declare const DEFAULT_PROFILE_REUSE_POSTURE: ProfileReusePosture;
+export interface PostureInputs {
+    /** Configured posture; defaults to `auto` when unset. */
+    posture?: ProfileReusePosture;
+    /** A usable real Chrome profile was detected and is attachable/safe to copy. */
+    realProfileAvailable: boolean;
+    /** Caller explicitly requested real-profile reuse for this run (e.g. app.browser === "chrome"). */
+    explicitlyRequested?: boolean;
+}
+export interface PostureDecision {
+    /** `real` = use the (isolated copy of the) real profile; `synthetic` = synthetic stealth session. */
+    mode: "real" | "synthetic";
+    /** User-facing warning to emit when real credentials/state are about to be used. */
+    warning: string | null;
+    /** Machine-readable reason for logs/audit. */
+    reason: "auto-real" | "explicit-real" | "synthetic-fallback" | "synthetic-opt-in";
+}
+/**
+ * Decide whether to reuse the real profile or run synthetic.
+ *
+ * - `auto` + available            -> real (with warning)
+ * - `opt-in` + explicitly asked   -> real (with warning)
+ * - `opt-in` (no explicit ask)    -> synthetic
+ * - not available                 -> synthetic (fallback), even under `auto`
+ */
+export declare function decideProfilePosture(inputs: PostureInputs): PostureDecision;

package/dist/types/tools/browser/profile-reuse.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Profile-reuse orchestration (plan Phase 2 wiring).
+ *
+ * Single entry point the launch path calls to decide, for a default headless
+ * session, whether to warm up from an isolated copy of the user's real Chrome
+ * profile. Ties together discovery + posture + isolated warm-up. Filesystem
+ * effects (the copy) are performed only when the posture resolves to `real`.
+ * The heavy pieces are injectable so this is unit-testable without a browser.
+ */
+import { type DiscoveredProfile, type DiscoveryEnv } from "./profile-discovery";
+import { type ProfileReusePosture } from "./profile-posture";
+import { type WarmupManifest } from "./profile-warmup";
+export interface ResolveProfileReuseInputs {
+    posture?: ProfileReusePosture;
+    /** Caller explicitly requested real-profile reuse (e.g. app.browser === "chrome"). */
+    explicitlyRequested?: boolean;
+    discoveryEnv: DiscoveryEnv;
+    /** Destination for the isolated warm-up copy; defaults to an ephemeral temp dir. */
+    destDir?: string;
+    /** Injectable copier (defaults to collectWarmupArtifacts). */
+    copy?: (sourceProfileDir: string, destDir: string) => WarmupManifest;
+    /** Injectable temp-dir factory (defaults to fs.mkdtemp under os.tmpdir()). */
+    makeTempDir?: () => string;
+}
+export interface ProfileReuseResult {
+    mode: "real" | "synthetic";
+    reason: string;
+    warning: string | null;
+    discovered: DiscoveredProfile | null;
+    /** Isolated copy directory when mode === "real", else null. */
+    warmupDir: string | null;
+    manifest: WarmupManifest | null;
+}
+/**
+ * Resolve profile reuse for a default session. When the posture resolves to
+ * `real`, copies an allowlisted, lock-free subset of the discovered profile
+ * into an isolated dir and returns that dir for the launcher to use.
+ */
+export declare function resolveProfileReuse(inputs: ResolveProfileReuseInputs): ProfileReuseResult;