@trusty-squire/mcp 1.1.13 → 1.1.14-rc.10

package/dist/bot/session/lifecycle.d.ts

@@ -4,7 +4,7 @@ import type { OAuthProviderId } from "../oauth-providers.js";
 import type { Session } from "./model.js";
 import type { CompactV2StartMetadata, Observation } from "../provision-session.js";
 export interface SessionStartPorts {
-    observeSession: (session: Session, detail: "compact" | "full", startMetadata?: CompactV2StartMetadata) => Promise<Observation>;
+    observeSession: (session: Session, format: "compact" | "full", startMetadata?: CompactV2StartMetadata) => Promise<Observation>;
     compactV2StartMetadata: (registryHint: string | undefined, loginHint: string, userEmail: string | null) => CompactV2StartMetadata;
 }
 export declare function audit(sessionId: string, event: string, detail?: Record<string, unknown>): void;
@@ -15,6 +15,8 @@ export declare function withPaymentSessionCall<T>(sessionId: string | undefined,
 export declare function observeSnapshotDir(sessionId: string): string;
 export interface StartOptions {
     serviceUrl: string;
+    /** Observation shape returned by this start. Compact is the public default. */
+    format?: "compact" | "full";
     profileDir?: string;
     proxyUrl?: string;
     extraAllowedHosts?: readonly string[];
@@ -24,7 +26,7 @@ export interface StartOptions {
 }
 export interface HarnessStartOptions extends Omit<StartOptions, "profileDir" | "proxyUrl"> {
     browser: BrowserController;
-    observationFormat?: "v1" | "compact-v2";
+    observationFormat?: "v1" | "browser-use-dom";
 }
 export interface NeedsUserLogin {
     wall: "google_session";
@@ -51,6 +53,7 @@ export interface PreparedFinishResult<T> {
 }
 export declare function finishProvisionSessionWithPreparation<T>(sessionId: string, prepare: () => Promise<T>, successfulOutcome?: () => boolean): Promise<PreparedFinishResult<T>>;
 export declare function finishProvisionSession(sessionId: string): Promise<FinishResult>;
+export declare function forceFinishProvisionSession(sessionId: string): Promise<boolean>;
 export declare function closeAllProvisionSessions(): Promise<void>;
 export declare function activeSessionCount(): number;
 //# sourceMappingURL=lifecycle.d.ts.map

package/dist/bot/session/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/bot/session/lifecycle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/bot/session/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/bot/session/lifecycle.js

@@ -1,3 +1,5 @@
+import { reserveBrokerAdmission } from "../broker/admission-context.js";
+import { brokerBrowserCustody } from "../broker/custody.js";
 // Phase 2 of the operator session-management restructure: the session
 // lifecycle, moved out of provision-session.ts as ONE transaction.
 //
@@ -30,6 +32,8 @@ import { compactV2AuditValue } from "../compact-observation-v2.js";
 import { acquireProfileOperationGuard, CHROME_PROFILE_DIR, ProfileBusyError, waitForProfileFree, } from "../profile.js";
 import { loginSessionGuidance } from "../skill-hint.js";
 import { OperatorBrowserWatchdog, } from "../operator-browser-watchdog.js";
+import { IdentityRuntime, IncompatibleIdentityRuntimeSettingsError, } from "../identity-runtime.js";
+import { experimentalMultiSessionEnabled } from "./multisession-flag.js";
 import { createSession } from "./model.js";
 import { hostStrings, merchantSiblingSeedHosts, registrableHost, requestScopeHostStrings, } from "./hosts.js";
 const sessions = new Map();
@@ -37,6 +41,9 @@ const sessions = new Map();
 // but it never creates a browser session. Its terminal acknowledgement is a
 // no-op rather than an "unknown session" error.
 const refusedStartSessionIds = new Set();
+// At most one live group per process today (one shared operator profile).
+let sharedIdentityGroup = null;
+const operatorIdentityRuntime = new IdentityRuntime();
 const leasedBrowsers = new Map();
 const startingBrowsers = new Set();
 let shutdownGeneration = 0;
@@ -109,16 +116,120 @@ function assertProvisionStartAdmitted(generation) {
         throw new Error("operate_start cancelled: operator server is shutting down");
     }
 }
+// Experimental (TRUSTY_SQUIRE_EXPERIMENTAL_MULTISESSION) — a second (or Nth)
+// operate_start joining an identity that is already live or mid-launch IN
+// THIS PROCESS. Returns null when there is nothing of ours to join (the busy
+// signal is from an unrelated process, or a genuinely different profile), so
+// the caller re-throws the original ProfileBusyError instead of silently
+// swallowing a real cross-process busy condition.
+//
+// Deliberately does NOT re-acquire the profile-operation guard: that lease is
+// the group's, held once by whichever session became primary (see
+// acquireWarmBrowser) and released only when the group empties (see
+// releaseWarmBrowserPage). Joining here only ever reuses operatorIdentityRuntime's
+// already-live handle — its own single-flight is what makes this race-free
+// against a primary launch still in flight.
+async function tryAcquireSatelliteBrowser(opts, profileDir, generation, sessionId) {
+    if (!operatorIdentityRuntime.isLive() && !operatorIdentityRuntime.isLaunching())
+        return null;
+    const identitySettings = {
+        profileDir,
+        ...(opts.proxyUrl !== undefined ? { proxyUrl: opts.proxyUrl } : {}),
+    };
+    let acquired;
+    try {
+        acquired = await operatorIdentityRuntime.acquire(identitySettings, async () => {
+            throw new Error("operate_start (TRUSTY_SQUIRE_EXPERIMENTAL_MULTISESSION): expected to join an already-live " +
+                "identity but the runtime attempted a fresh launch instead — this should be unreachable");
+        });
+    }
+    catch (err) {
+        if (err instanceof IncompatibleIdentityRuntimeSettingsError)
+            return null;
+        throw err;
+    }
+    const joinable = (group) => group !== null && group.profileDir === profileDir && group.refCount > 0;
+    if (!acquired.reused || !joinable(sharedIdentityGroup)) {
+        acquired.releaseTabs();
+        return null;
+    }
+    const group = sharedIdentityGroup;
+    try {
+        assertProvisionStartAdmitted(generation);
+    }
+    catch (err) {
+        acquired.releaseTabs();
+        throw err;
+    }
+    let satellite;
+    try {
+        satellite = await BrowserController.attachSatellite(group.primary, {
+            profileDir,
+            ...(opts.proxyUrl !== undefined ? { proxyUrl: opts.proxyUrl } : {}),
+        });
+    }
+    catch (err) {
+        acquired.releaseTabs();
+        throw err;
+    }
+    // The last live session's teardown may have emptied the group while the
+    // attach was in flight; a satellite must never be committed onto it.
+    if (sharedIdentityGroup !== group || !joinable(group)) {
+        await satellite.closeOwnPagesOnly().catch(() => undefined);
+        acquired.releaseTabs();
+        return null;
+    }
+    group.refCount += 1;
+    audit(sessionId, "multisession_satellite_attach", { profile_dir: profileDir });
+    leasedBrowsers.set(satellite, {
+        controller: satellite,
+        profileDir,
+        lease: group.lease,
+        shutdownGeneration: generation,
+        identityLease: acquired.releaseTabs,
+        identityGroup: group,
+        ...(opts.proxyUrl === undefined ? {} : { proxyUrl: opts.proxyUrl }),
+    });
+    return { controller: satellite, profileDir, shutdownGeneration: generation };
+}
 async function acquireWarmBrowser(opts, sessionId) {
     const generation = provisionStartGeneration();
+    const custody = brokerBrowserCustody();
+    if (custody !== undefined) {
+        const acquired = await custody.acquire(opts);
+        try {
+            assertProvisionStartAdmitted(generation);
+        }
+        catch (error) {
+            await custody.release(acquired.browser);
+            throw error;
+        }
+        return {
+            controller: acquired.browser,
+            profileDir: acquired.profileDir,
+            shutdownGeneration: generation,
+        };
+    }
     if ((process.env.BOT_CDP_ENDPOINT ?? "").trim().length > 0) {
         throw new Error("operate_start does not support remote CDP with the local Chrome profile");
     }
     const profileDir = opts.profileDir ?? CHROME_PROFILE_DIR;
+    const multiSession = experimentalMultiSessionEnabled();
     // This lease is held for the complete operate session. Its on-disk owner
     // records host + pid + process birth time, so a crashed holder is reclaimed
     // while a live or indeterminate holder is never stolen.
-    const lease = acquireProfileOperationGuard(profileDir);
+    let lease;
+    try {
+        lease = acquireProfileOperationGuard(profileDir);
+    }
+    catch (err) {
+        if (multiSession && err instanceof ProfileBusyError) {
+            const satellite = await tryAcquireSatelliteBrowser(opts, profileDir, generation, sessionId);
+            if (satellite !== null)
+                return satellite;
+        }
+        throw err;
+    }
     if (!(await waitForProfileFree(profileDir, { deadlineMs: 0 }))) {
         lease.release();
         throw new ProfileBusyError("another Trusty Squire session is already using the browser — close it first");
@@ -134,42 +245,70 @@ async function acquireWarmBrowser(opts, sessionId) {
     };
     startingBrowsers.add(pending);
     let controller = null;
+    let identityLease = null;
     try {
         if (pending.cancelRequested) {
             throw new Error("operate_start cancelled: operator server is shutting down");
         }
-        controller = new BrowserController({
+        const identitySettings = {
             profileDir,
             ...(opts.proxyUrl !== undefined ? { proxyUrl: opts.proxyUrl } : {}),
+        };
+        // Single-flighted through operatorIdentityRuntime rather than constructed
+        // inline: today it always launches fresh (production still forgets this
+        // identity at every session finish, below), but the acquisition itself
+        // now goes through the one place that will later decide whether to reuse
+        // a still-live Chrome instead of relaunching it.
+        const acquired = await operatorIdentityRuntime.acquire(identitySettings, async (settings) => {
+            const launched = new BrowserController({
+                profileDir: settings.profileDir,
+                ...(settings.proxyUrl !== undefined ? { proxyUrl: settings.proxyUrl } : {}),
+            });
+            pending.controller = launched;
+            pending.launch = startBrowserBounded(launched, sessionId, async () => {
+                await cancelStartingBrowser(pending);
+            });
+            await pending.launch;
+            return launched;
         });
-        pending.controller = controller;
-        pending.launch = startBrowserBounded(controller, sessionId, async () => {
-            await cancelStartingBrowser(pending);
-        });
-        await pending.launch;
+        controller = acquired.handle;
+        identityLease = acquired.releaseTabs;
         if (pending.cancelRequested) {
             throw new Error("operate_start cancelled: operator server is shutting down");
         }
         assertProvisionStartAdmitted(generation);
     }
     catch (err) {
-        if (controller !== null)
-            await controller.close().catch(() => undefined);
+        const constructed = controller ?? pending.controller;
+        if (constructed !== null) {
+            identityLease?.();
+            await constructed.close().catch(() => undefined);
+            operatorIdentityRuntime.forgetAfterShutdown();
+        }
         lease.release();
         throw err;
     }
     finally {
         startingBrowsers.delete(pending);
     }
-    if (controller === null) {
+    if (controller === null || identityLease === null) {
         throw new Error("operate_start cancelled before browser initialization");
     }
+    // This session became primary: form the shared group so a subsequent
+    // busy-guard failure (above) knows there is something of ours to join, and
+    // so releaseWarmBrowserPage/forceReleaseWarmBrowserPage know who actually
+    // owns the profile-operation lease and the real teardown.
+    const identityGroup = multiSession
+        ? (sharedIdentityGroup = { primary: controller, profileDir, lease, refCount: 1 })
+        : undefined;
     leasedBrowsers.set(controller, {
         controller,
         profileDir,
         lease,
         shutdownGeneration: generation,
+        identityLease,
         ...(opts.proxyUrl === undefined ? {} : { proxyUrl: opts.proxyUrl }),
+        ...(identityGroup !== undefined ? { identityGroup } : {}),
     });
     return {
         controller,
@@ -178,25 +317,118 @@ async function acquireWarmBrowser(opts, sessionId) {
     };
 }
 async function releaseWarmBrowserPage(browser, _persistState, owner) {
+    const custody = brokerBrowserCustody();
+    if (custody !== undefined) {
+        await custody.release(browser);
+        return;
+    }
     const leased = leasedBrowsers.get(browser);
+    const group = leased?.identityGroup;
+    // A forced teardown of a GROUPED session belongs wholly to
+    // forceReleaseWarmBrowserPage, which the forcing path runs next on this same
+    // session: it performs the group's one decrement and, when last, the
+    // primary close. Touching the refcount, the lease, or the leasedBrowsers
+    // entry here first would discard the group before anything closed the
+    // shared Chrome. The ungrouped (flag-off) path is unchanged.
+    if (group !== undefined && owner?.forced) {
+        throw new Error("operator browser terminal teardown was forced");
+    }
+    if (group !== undefined)
+        group.refCount -= 1;
+    const emptiedGroup = group !== undefined && group.refCount <= 0;
     try {
         if (owner?.forced)
             throw new Error("operator browser terminal teardown was forced");
-        await browser.close();
+        if (group === undefined) {
+            // Production still tears the identity's Chrome down at every session
+            // finish (flag off, or no multisession group formed).
+            await browser.close();
+        }
+        else if (!emptiedGroup) {
+            await browser.closeOwnPagesOnly();
+        }
+        else {
+            if (browser !== group.primary)
+                await browser.closeOwnPagesOnly().catch(() => undefined);
+            await group.primary.close();
+        }
     }
     finally {
         leasedBrowsers.delete(browser);
-        leased?.lease.release();
+        if (leased !== undefined) {
+            if (group === undefined) {
+                leased.lease.release();
+                leased.identityLease();
+                operatorIdentityRuntime.forgetAfterShutdown();
+            }
+            else {
+                leased.identityLease();
+                if (emptiedGroup) {
+                    group.lease.release();
+                    operatorIdentityRuntime.forgetAfterShutdown();
+                    if (sharedIdentityGroup === group)
+                        sharedIdentityGroup = null;
+                }
+            }
+        }
     }
 }
 async function forceReleaseWarmBrowserPage(browser, owner) {
+    const custody = brokerBrowserCustody();
+    if (custody !== undefined) {
+        await custody.release(browser);
+        return;
+    }
     const leased = leasedBrowsers.get(browser);
-    await closeBrowserUntilProven(browser, false, "operator browser force-close timed out", () => owner?.requireProvenBrowserClose === true);
+    const group = leased?.identityGroup;
+    // The group's one decrement for a forced session happens here, never in a
+    // preempted releaseWarmBrowserPage (see there), so whichever session's
+    // teardown empties the group — primary or satellite, graceful or forced —
+    // is the one that closes the shared Chrome.
+    if (group !== undefined)
+        group.refCount -= 1;
+    const emptiedGroup = group !== undefined && group.refCount <= 0;
+    try {
+        if (group === undefined) {
+            await closeBrowserUntilProven(browser, false, "operator browser force-close timed out", () => owner?.requireProvenBrowserClose === true);
+        }
+        else if (!emptiedGroup) {
+            await closeOwnPagesBounded(browser);
+        }
+        else {
+            if (browser !== group.primary)
+                await closeOwnPagesBounded(browser);
+            await closeBrowserUntilProven(group.primary, false, "operator browser force-close timed out", () => owner?.requireProvenBrowserClose === true);
+        }
+    }
+    finally {
+        if (leased !== undefined) {
+            leased.identityLease();
+            if (group === undefined) {
+                operatorIdentityRuntime.forgetAfterShutdown();
+            }
+            else if (emptiedGroup) {
+                operatorIdentityRuntime.forgetAfterShutdown();
+                if (sharedIdentityGroup === group)
+                    sharedIdentityGroup = null;
+            }
+        }
+    }
     if (leased === undefined)
         return;
-    leased.lease.release();
+    if (group === undefined)
+        leased.lease.release();
+    else if (emptiedGroup)
+        group.lease.release();
     leasedBrowsers.delete(browser);
 }
+// The forced-teardown counterpart of closeOwnPagesOnly: page.close() can hang
+// indefinitely on a wedged Chrome, so the grouped forced path keeps the same
+// bounded contract closeBrowserBounded gives the ungrouped one.
+async function closeOwnPagesBounded(browser) {
+    const timeoutMs = positiveTimeout("TRUSTY_SQUIRE_OPERATOR_FORCE_CLOSE_TIMEOUT_MS", DEFAULT_OPERATOR_FORCE_CLOSE_TIMEOUT_MS);
+    await withTerminalTimeout(browser.closeOwnPagesOnly(), timeoutMs, "operator browser own-page force-close timed out").catch(() => undefined);
+}
 async function closeBrowserBounded(browser, cancelStart, timeoutMessage, maximumTimeoutMs) {
     const forceClose = browser.forceCloseOwnedProcessTree;
     const ordinaryClose = browser
@@ -410,7 +642,10 @@ function startSessionWatchdog(session) {
     const watchdog = new OperatorBrowserWatchdog({
         startedAt: session.startedAt,
         lastActivityAt: () => session.lastActivityAt,
-        hasActiveCall: () => session.initializing || session.callCount > 0 || session.paymentCallCount > 0,
+        hasActiveCall: () => brokerBrowserCustody() !== undefined ||
+            session.initializing ||
+            session.callCount > 0 ||
+            session.paymentCallCount > 0,
         processMarker: () => session.browser.operatorBrowserMarker?.() ?? null,
         onTerminate: async (reason) => await terminateExpiredProvisionSession(session, reason),
     });
@@ -578,15 +813,28 @@ async function ensureProvisionPrimaryProviderSession(browser) {
     });
 }
 export async function startProvisionSession(opts, ports) {
-    const id = randomUUID();
+    const id = reserveBrokerAdmission([opts.serviceUrl, ...(opts.extraAllowedHosts ?? [])]) ?? randomUUID();
     const compactV2Mode = configuredCompactV2Mode();
+    const requestedFormat = opts.format ?? (compactV2Mode === "on" ? "full" : "compact");
     let browser;
     let liveProviders;
     let workerEmail = null;
     const acquired = await acquireWarmBrowser(opts, id);
     browser = acquired.controller;
     try {
-        liveProviders = await ensureProvisionPrimaryProviderSession(browser);
+        const probe = async () => {
+            const providers = await ensureProvisionPrimaryProviderSession(browser);
+            workerEmail =
+                typeof browser.detectGoogleAccountEmail === "function"
+                    ? await browser.detectGoogleAccountEmail().catch(() => null)
+                    : null;
+            return providers;
+        };
+        const custody = brokerBrowserCustody();
+        liveProviders =
+            custody === undefined
+                ? await ensureProvisionPrimaryProviderSession(browser)
+                : await custody.identity(probe);
         assertProvisionStartAdmitted(acquired.shutdownGeneration);
         const gate = googleSessionGate(liveProviders);
         if (!gate.ok) {
@@ -594,20 +842,29 @@ export async function startProvisionSession(opts, ports) {
             await releaseWarmBrowserPage(browser, false);
             refusedStartSessionIds.add(id);
             return compactV2Mode === "on"
-                ? {
-                    session_id: id,
-                    format: "compact-v2",
-                    stage: "auth",
-                    url: "",
-                    text: "",
-                    needs_user: gate.needs_user,
-                }
+                ? requestedFormat === "full"
+                    ? {
+                        session_id: id,
+                        format: "browser-use-dom",
+                        stage: "auth",
+                        url: "",
+                        needs_user: gate.needs_user,
+                    }
+                    : {
+                        session_id: id,
+                        format: "browser-use-control-query",
+                        stage: "auth",
+                        url: "",
+                        safe_table: [],
+                        needs_user: gate.needs_user,
+                    }
                 : { session_id: id, url: "", text: "", elements: [], needs_user: gate.needs_user };
         }
-        workerEmail =
-            typeof browser.detectGoogleAccountEmail === "function"
-                ? await browser.detectGoogleAccountEmail().catch(() => null)
-                : null;
+        if (custody === undefined)
+            workerEmail =
+                typeof browser.detectGoogleAccountEmail === "function"
+                    ? await browser.detectGoogleAccountEmail().catch(() => null)
+                    : null;
     }
     catch (error) {
         await releaseWarmBrowserPage(browser, false);
@@ -669,10 +926,11 @@ export async function startProvisionSession(opts, ports) {
         // doesn't have to guess. Composed with the skill route hint (if any).
         const loginHint = loginSessionGuidance(liveProviders);
         const hintParts = [loginHint, ...(opts.hint !== undefined ? [opts.hint] : [])];
-        const observation = await ports.observeSession(session, "compact", ports.compactV2StartMetadata(opts.hint, loginHint, session.userEmail));
+        const observation = await ports.observeSession(session, requestedFormat, ports.compactV2StartMetadata(opts.hint, loginHint, session.userEmail));
         session.initializing = false;
         session.lastActivityAt = Date.now();
-        if (observation.format === "compact-v2")
+        if (observation.format === "browser-use-dom" ||
+            observation.format === "browser-use-control-query")
             return observation;
         return {
             ...observation,
@@ -690,6 +948,7 @@ export async function startProvisionSession(opts, ports) {
 /** Start a normal guarded session on a caller-owned harness page. */
 export async function startHarnessProvisionSession(opts, ports) {
     const id = randomUUID();
+    const requestedFormat = opts.format ?? (opts.observationFormat === "browser-use-dom" ? "full" : "compact");
     const targetHost = registrableHost(opts.serviceUrl);
     const allowedHosts = [
         ...(targetHost === null ? [] : [targetHost]),
@@ -704,7 +963,7 @@ export async function startHarnessProvisionSession(opts, ports) {
         id,
         browser: opts.browser,
         allowedHosts,
-        compactV2Mode: opts.observationFormat === "compact-v2" ? "on" : "off",
+        compactV2Mode: opts.observationFormat === "browser-use-dom" ? "on" : "off",
         startUrl: opts.serviceUrl,
         hintServed: opts.hint !== undefined,
         consentInboxRead: opts.consentInboxRead !== false,
@@ -719,10 +978,11 @@ export async function startHarnessProvisionSession(opts, ports) {
             allowed_hosts: hostStrings(session),
         });
         await opts.browser.goto(opts.serviceUrl);
-        const observation = await ports.observeSession(session, "compact", ports.compactV2StartMetadata(opts.hint, "", null));
+        const observation = await ports.observeSession(session, requestedFormat, ports.compactV2StartMetadata(opts.hint, "", null));
         session.initializing = false;
         session.lastActivityAt = Date.now();
-        if (observation.format === "compact-v2")
+        if (observation.format === "browser-use-dom" ||
+            observation.format === "browser-use-control-query")
             return observation;
         return { ...observation, hint: opts.hint ?? "" };
     }
@@ -922,6 +1182,15 @@ export async function finishProvisionSession(sessionId) {
     }
     return (await finishProvisionSessionWithPreparation(sessionId, async () => undefined)).finish;
 }
+export async function forceFinishProvisionSession(sessionId) {
+    const session = sessionForCall(sessionId);
+    if (session === undefined)
+        return true;
+    const terminalError = await forceTerminateProvisionSession(session, "broker_detached_expiry", {
+        reason: "stuck_dispatched_operation",
+    });
+    return terminalError === undefined && sessionForCall(sessionId) === undefined;
+}
 // Test/teardown helper — close every live session (used by the dev shim on exit).
 export async function closeAllProvisionSessions() {
     shutdownGeneration += 1;