@mind-harness/mh-browser 0.2.4 → 0.2.6

package/lib/types/service/service.d.ts

@@ -1,15 +1,20 @@
 import { Context } from '@deepseek-ai/cordis';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { BrowserConfig } from '../config.ts';
+import type { BrowserLocation } from '../location.ts';
 import type { HeldPage, PresenceReceipt, PresenceRecord, PresenceSource } from '../presence/record.ts';
 import type { PendingOp } from '../presence/fold.ts';
-import type { Download, FetchResponseBody, InvokeCall, InvokeSent, PageError, PageOp, PageView, TabInfo, WaitFor } from '../types.ts';
+import type { BrowserName, Download, FetchResponseBody, InvokeCall, InvokeSent, PageError, PageOp, PageView, TabInfo, WaitFor } from '../types.ts';
 import { type Taken } from './control.ts';
 import { testHooks, type TestHooks } from './test-hooks.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         mhBrowser: MhBrowserService;
     }
+    interface Events {
+        /** Volatile config was committed on this plugin fiber. Paths are key arrays. */
+        'loader/volatile-update'(paths: readonly (readonly string[])[]): void;
+    }
 }
 export type WriteTarget = {
     root: string;
@@ -30,13 +35,23 @@ export interface HandBack extends Taken {
  * also has an Agent View.
  */
 export declare class MhBrowserService extends TypertRemoteService {
-    static Config: import("@deepseek-ai/schemastery").default<BrowserConfig>;
     private readonly windows;
-    private readonly launchOptions;
+    private readonly headless;
+    private readonly profileDir;
+    private readonly browserName;
+    private readonly executablePath;
+    /** Tests replace the machine lookup. Unset uses this machine. */
+    private locator;
     private context;
     private readonly pids;
     private ready;
     private closing;
+    /** A browser restart was requested and has not run yet. */
+    private relaunchWanted;
+    /** Counts browser and path changes. A start that sampled the latest one clears the restart. */
+    private configEpoch;
+    /** The running browser is being closed so the new configuration can start. */
+    private replacing;
     /** The browser is not running. The next call that needs a page starts it. */
     private exited;
     private readonly exits;
@@ -112,6 +127,11 @@ export declare class MhBrowserService extends TypertRemoteService {
     /** The person asked for the browser: start it if it exited, past the exit limit. */
     startForPerson(): Promise<void>;
     [testHooks](): TestHooks;
+    /**
+     * Where `browser` would be launched from when no path is configured.
+     * The configured path is not consulted: the answer is what an empty path uses.
+     */
+    locateFor(browser: BrowserName, signal?: AbortSignal): Promise<BrowserLocation>;
     act(owner: string, tab: string, op: PageOp, signal?: AbortSignal): Promise<PageView>;
     holdHandover(owner: string, tab: string): void;
     releaseHandover(owner: string): void;
@@ -152,6 +172,7 @@ export declare class MhBrowserService extends TypertRemoteService {
     /**
      * The person took over between turns. The next message they send is the
      * hand-back. A handover that is still waiting on its card is not.
+     * The addresses are read before a waiting restart closes the pages.
      */
     takePersonHandback(owner: string): HandBack | undefined;
     /**
@@ -243,5 +264,15 @@ export declare class MhBrowserService extends TypertRemoteService {
     private presenceUrls;
     private snapshotNamed;
     private exclusive;
+    private launchChoice;
+    private locateEnv;
+    private idle;
+    /**
+     * Close and start again when a configuration change is waiting and nothing
+     * is using the browser. A browser that is not running keeps the new values
+     * for the next start. The close is not counted as a crash.
+     */
+    private relaunchIfIdle;
+    private replaceBrowser;
 }
 //# sourceMappingURL=service.d.ts.map

package/lib/types/service/test-hooks.d.ts

@@ -1,3 +1,4 @@
+import type { LocateEnv } from './locate.ts';
 /** Key of the hooks tests use to crash the browser and reach a live page. Not exported by the package. */
 export declare const testHooks: unique symbol;
 export interface TestHooks {
@@ -9,5 +10,7 @@ export interface TestHooks {
     pages(): unknown[];
     /** The main browser process id recorded at start. */
     pid(): number | undefined;
+    /** Use this lookup instead of the machine's. `undefined` restores the machine. */
+    useLocator(env: LocateEnv | undefined): void;
 }
 //# sourceMappingURL=test-hooks.d.ts.map

package/lib/types/service/windows.d.ts

@@ -114,7 +114,7 @@ export declare class Windows {
     /** The tab touched most recently, for raising the window the person asked to see. */
     latest(owner: OwnerId): LiveTab | undefined;
     /** Make this tab the current one in its window. Does not raise the browser. */
-    activate(tab: LiveTab): Promise<void>;
+    activate(tab: LiveTab, signal?: AbortSignal): Promise<void>;
     /** Group title for the person. Empty until a title is known. */
     setTitle(owner: OwnerId, title: string): void;
     /** A handover in progress prefixes the group title and recolors it. */
@@ -126,15 +126,17 @@ export declare class Windows {
      * use the extension. Without a window, later pages use `window.open` from
      * an isolated world so they stay in that window.
      */
-    openBlank(owner: OwnerId): Promise<LiveTab>;
+    openBlank(owner: OwnerId, signal?: AbortSignal): Promise<LiveTab>;
     private createTab;
     private keep;
+    /** The page from a create, or close it when this wait is abandoned. */
+    private claimedPage;
     /**
      * Close one tab. `note` is listed in the next `<tabs>` block. A tab the
      * model was never shown (an Agent View discovered on a new tab) omits it.
      */
     closeTab(tab: LiveTab, note?: string): Promise<void>;
-    closeOwner(owner: OwnerId): Promise<void>;
+    closeOwner(owner: OwnerId, signal?: AbortSignal): Promise<void>;
     private closePage;
     /** A tab leaves the registry. The window closes with its last tab. */
     private forget;
@@ -176,5 +178,10 @@ export declare class Windows {
     private dropSession;
     private targetIdOf;
     private windowIdOf;
+    private pageSession;
+    private cdp;
+    /** Close a page that may no longer answer. A stall ends at `CLOSE_MS`. */
+    private shutdown;
+    private shutdownSession;
 }
 //# sourceMappingURL=windows.d.ts.map

package/lib/types/settings-form.d.ts

@@ -0,0 +1,142 @@
+import { type ReactElement, type ReactNode } from 'react';
+/**
+ * A staged settings form drawn by this plugin. It follows the host's settings
+ * form: edits stay local until Save, leaving the page drops them, and a field
+ * is overridden while the user layer carries it. Styles use host theme tokens
+ * only, so the page matches the host without loading its components.
+ */
+/** What `ctx.configForms.get()` serves for one Host entry. */
+export interface SettingsFormScopeSnapshot<T> {
+    status: 'loading' | 'ready' | 'unavailable';
+    value: T | undefined;
+    /** The layer a cleared field falls back to. */
+    base: unknown;
+    /** The user layer as stored. A field present here is overridden. */
+    user: unknown;
+    writable: boolean;
+    revision: number | undefined;
+}
+export type SettingsFormPathOp = {
+    op: 'set';
+    path: readonly string[];
+    value: unknown;
+} | {
+    op: 'unset';
+    path: readonly string[];
+};
+export interface SettingsFormScope<T> {
+    getSnapshot(): SettingsFormScopeSnapshot<T>;
+    subscribe(listener: () => void): () => void;
+    /** One revision-fenced write. Resolves to whether the Host accepted it. */
+    mutate(ops: readonly SettingsFormPathOp[], expectedRevision?: number): Promise<boolean>;
+}
+export type FieldWrite = {
+    kind: 'set';
+    value: unknown;
+} | {
+    kind: 'clear';
+};
+export interface FieldSpec {
+    field: string;
+    /** Stored value as draft text. */
+    format: (value: unknown) => string;
+    /** The write a draft stages. Undefined blocks the save. */
+    parse: (text: string) => FieldWrite | undefined;
+}
+export interface FieldState {
+    text: string;
+    /** Saving would leave this field in the user layer. */
+    overridden: boolean;
+    invalid: boolean;
+}
+export interface FormShell {
+    available: boolean;
+    writable: boolean;
+    dirty: boolean;
+    invalid: boolean;
+    saving: boolean;
+    /** The last save did not land. Cleared by the next edit or save. */
+    failed: boolean;
+}
+export interface FormLabels {
+    unavailable: string;
+    readOnly: string;
+    saveFailed: string;
+    discard: string;
+    save: string;
+    saving: string;
+}
+export interface Store<S> {
+    getSnapshot(): S;
+    subscribe(listener: () => void): () => void;
+}
+/** Drafts over one entry's fields, written together on save. */
+export declare class StagedForm<T> {
+    private readonly scope;
+    private readonly specs;
+    private readonly staged;
+    private readonly listeners;
+    private baseline;
+    private saving;
+    private failed;
+    private readonly unsubscribe;
+    constructor(scope: SettingsFormScope<T>, specs: readonly FieldSpec[]);
+    /** A store over `project`, rebuilt whenever the entry or a draft changes. */
+    bind<S>(project: () => S): Store<S>;
+    shell(): FormShell;
+    field(field: string): FieldState;
+    edit(field: string, text: string): void;
+    /** Stage removing the field from the user layer. The draft shows what it falls back to. */
+    reset(field: string): void;
+    discard(): void;
+    /**
+     * Write every staged edit. A save the Host refuses keeps the drafts, and the
+     * next save is fenced on what the Host holds now, so trying again can land.
+     */
+    save(): Promise<void>;
+    dispose(): void;
+    private plan;
+    private stage;
+    private spec;
+    private read;
+    private stored;
+    private publish;
+}
+/** Free text. An empty draft clears the field. */
+export declare function textField(field: string): FieldSpec;
+/** The page frame: read-only notice, the fields, and Save. Unmounting drops every draft. */
+export declare function SettingsFrame(props: {
+    labels: FormLabels;
+    state: FormShell;
+    onSave: () => void;
+    onDiscard: () => void;
+    children?: ReactNode;
+}): ReactElement;
+export interface FieldProps extends FieldState {
+    id: string;
+    label: string;
+    hint?: string;
+    overriddenLabel: string;
+    resetLabel: string;
+    /** Shown instead of the hint while the draft is invalid. A field that cannot be invalid omits it. */
+    invalidLabel?: string;
+    disabled: boolean;
+    /** Text behind the information button beside the label. */
+    help?: {
+        label: string;
+        content: ReactNode;
+    };
+    onReset: () => void;
+}
+export declare function TextField(props: FieldProps & {
+    placeholder?: string;
+    onEdit: (text: string) => void;
+}): ReactElement;
+export declare function ChoiceField(props: FieldProps & {
+    options: readonly {
+        value: string;
+        label: string;
+    }[];
+    onEdit: (value: string) => void;
+}): ReactElement;
+//# sourceMappingURL=settings-form.d.ts.map

package/lib/types/settings.d.ts

@@ -0,0 +1,121 @@
+import { type ReactElement } from 'react';
+import { type Translate } from './locales.ts';
+import { type FieldState, type FieldWrite, type FormShell, type SettingsFormScope } from './settings-form.ts';
+/** Loader row id, and the settings namespace for that row. */
+export declare const ENTRY_ID = "mh-browser";
+/** `plugins.row.config` key: the bundle package, then the row id. */
+export declare const ROW_KEY = "@mind-harness/mh-bundle#mh-browser";
+export declare const BROWSER_CHOICES: readonly ["chrome", "msedge", "chromium"];
+export type BrowserChoice = (typeof BROWSER_CHOICES)[number];
+/** Matches the host's `BrowserLocation`. The client bundle cannot import the host file. */
+export type BrowserLocation = {
+    found: string;
+} | {
+    missing: {
+        path: string;
+        reason: string;
+    }[];
+};
+export type LocateResult = {
+    ok: true;
+    value: BrowserLocation;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export type LocateFor = (browser: BrowserChoice, signal?: AbortSignal) => Promise<LocateResult>;
+export type LookupView = {
+    status: 'loading';
+} | {
+    status: 'found';
+    path: string;
+} | {
+    status: 'missing';
+    tried: {
+        path: string;
+        reason: string;
+    }[];
+} | {
+    status: 'failed';
+};
+/** The host entry's config. Only these two fields are edited here. */
+export interface BrowserSettingsConfig {
+    browser?: string;
+    executablePath?: string;
+}
+interface BrowserState extends FormShell {
+    browser: FieldState;
+    executablePath: FieldState;
+}
+interface ConfigForms {
+    get<T>(entryId: string): SettingsFormScope<T>;
+}
+export interface SettingsHost {
+    slots: {
+        inject(name: string, register: () => unknown): unknown;
+        register(options: {
+            name: string;
+            key: string;
+            locale: string;
+        }, component: (props: {
+            t: Translate;
+            view?: 'summary' | 'page';
+        }) => ReactElement | null): () => void;
+    };
+    configForms: ConfigForms;
+    remote: {
+        mhBrowser: {
+            locateFor: LocateFor;
+        };
+    };
+    effect(execute: () => () => void): unknown;
+}
+/** Empty text clears the field. Anything else must be absolute, or start with `~`. */
+export declare function parseExecutable(text: string): FieldWrite | undefined;
+/** Placeholder for an empty path field: the path an empty value would use. */
+export declare function pathPlaceholder(lookup: LookupView, browser: BrowserChoice, t: Translate): string | undefined;
+/** The full path, or every place that was tried. Absent while looking or after a failed lookup. */
+export declare function pathHelpText(lookup: LookupView, t: Translate): string | undefined;
+/**
+ * One browser name's lookup, kept until the settings page unmounts.
+ * A newer lookup cancels the one still running.
+ */
+export declare class ExecutableLookup {
+    private readonly locate;
+    private readonly cache;
+    private inflight;
+    private controller;
+    private readonly listeners;
+    constructor(locate: LocateFor);
+    subscribe: (listener: () => void) => (() => void);
+    /** Cached answer for `browser`, or loading when that answer is not in yet. */
+    view(browser: BrowserChoice): LookupView;
+    watch(browser: BrowserChoice): void;
+    dispose(): void;
+    private publish;
+}
+/** Staged browser choice and path. A save the host accepts restarts the browser when it is idle. */
+export declare class BrowserForm {
+    private readonly form;
+    readonly lookup: ExecutableLookup;
+    readonly state: {
+        getSnapshot(): BrowserState;
+        subscribe(listener: () => void): () => void;
+    };
+    constructor(scope: SettingsFormScope<BrowserSettingsConfig>, locate: LocateFor);
+    edit(field: 'browser' | 'executablePath', text: string): void;
+    reset(field: 'browser' | 'executablePath'): void;
+    save(): void;
+    discard(): void;
+    dispose(): void;
+}
+export declare function registerSettings(ctx: SettingsHost): void;
+export declare function BrowserSettings(props: {
+    t: Translate;
+    form: BrowserForm;
+}): ReactElement;
+export {};
+//# sourceMappingURL=settings.d.ts.map

package/lib/types/tools/given.d.ts

@@ -0,0 +1,5 @@
+/** A string the caller gave. Blank is the same as omitting it; the text itself is kept. */
+export declare function givenString(value: unknown): string | undefined;
+/** Seconds to wait. Zero is the same as omitting it; any other number is kept. */
+export declare function givenTime(value: unknown): number | undefined;
+//# sourceMappingURL=given.d.ts.map

package/lib/types/typeprobe.d.ts

@@ -0,0 +1,49 @@
+import type { Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+interface Full {
+    presence: {
+        maxBytes: number;
+    };
+    browser: Volatile<'chrome' | 'msedge' | 'chromium'>;
+    executablePath: Volatile<string | undefined>;
+    profileDir?: string;
+    headless: boolean;
+}
+export declare const full: z<Full>;
+declare const oldShape: z<Schemastery.ObjectS<NoInfer<{
+    browser: z<"chrome" | "msedge" | "chromium", "chrome" | "msedge" | "chromium", "defined">;
+    profileDir: z<string, string, "plain">;
+    headless: z<boolean, boolean, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    browser: z<"chrome" | "msedge" | "chromium", "chrome" | "msedge" | "chromium", "defined">;
+    profileDir: z<string, string, "plain">;
+    headless: z<boolean, boolean, "defined">;
+}>>, "plain">;
+declare const newShape: z<Schemastery.ObjectS<NoInfer<{
+    browser: z<"chrome" | "msedge" | "chromium", "chrome" | "msedge" | "chromium", "volatile-defined">;
+    executablePath: z<string, string, "volatile">;
+    profileDir: z<string, string, "plain">;
+    headless: z<boolean, boolean, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    browser: z<"chrome" | "msedge" | "chromium", "chrome" | "msedge" | "chromium", "volatile-defined">;
+    executablePath: z<string, string, "volatile">;
+    profileDir: z<string, string, "plain">;
+    headless: z<boolean, boolean, "defined">;
+}>>, "plain">;
+type Old = ReturnType<typeof oldShape>;
+type New = ReturnType<typeof newShape>;
+export type Probe = {
+    oldProfile: Old['profileDir'];
+    oldBrowser: Old['browser'];
+    newProfile: New['profileDir'];
+    newBrowser: New['browser'];
+    newPath: New['executablePath'];
+    oldKeys: keyof Old;
+    newKeys: keyof New;
+};
+export declare const showOldProfile: Old['profileDir'];
+export declare const showNewProfile: New['profileDir'];
+export declare const showNewPath: New['executablePath'];
+export declare const showNewBrowser: New['browser'];
+export {};
+//# sourceMappingURL=typeprobe.d.ts.map

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@mind-harness/mh-browser",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Opens pages in a real browser for the agent, keeps chosen Agent Views in context, and hands the browser to you when a person is needed.",
   "license": "SEE LICENSE IN LICENSE",
   "files": [
     "lib/index.js",
     "lib/types/representation/agent-view.js",
+    "lib/types/location.js",
     "lib/types/**/*.d.ts",
     "lib/typert.host.js",
     "lib/typert.host.d.ts",
@@ -29,6 +30,10 @@
       "types": "./lib/types/representation/agent-view.d.ts",
       "default": "./lib/types/representation/agent-view.js"
     },
+    "./location": {
+      "types": "./lib/types/location.d.ts",
+      "default": "./lib/types/location.js"
+    },
     "./typert": {
       "types": "./lib/typert.host.d.ts",
       "default": "./lib/typert.host.js"
@@ -60,6 +65,7 @@
     "@deepseek-ai/dsh-agent-loop-testkit": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-attachment": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-browser-use": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-home-paths": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-llm": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-llm-mock-server": "^0.2.2-rc.1",
@@ -77,6 +83,7 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.1.0",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.2.2-rc.1 <0.2.3-0",
     "@deepseek-ai/dsh-home-paths": ">=0.2.2-rc.1 <0.2.3-0",
     "@deepseek-ai/dsh-llm": ">=0.2.2-rc.1 <0.2.3-0",
     "@deepseek-ai/dsh-tools": ">=0.2.2-rc.1 <0.2.3-0",
@@ -94,7 +101,8 @@
       "platform": "web",
       "inject": [
         "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-client-ui-conversation"
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-settings"
       ]
     }
   },