diff --git a/README.md b/README.md index 389e2515..196c6edf 100644 --- a/README.md +++ b/README.md @@ -364,3 +364,11 @@ explicit secrets. Built on [Vercel](https://vercel.com) · [Kernel](https://kernel.sh) · [Linq](https://linqapp.com) · [Neon](https://neon.tech) + +## Browser runtime checks + +See [browser runtime lessons from BELL](docs/browser-runtime-lessons.md) for the +provider-independent lifecycle improvements, retained architecture, and the +opt-in Kernel profile-persistence and retirement check. Run it with +`OPENINSTINCT_LIVE_BROWSER_CHECK=1 pnpm test:browser:live`; it uses a temporary +profile and verifies cleanup without touching saved user browser state. diff --git a/agent/subagents/browser-agent/hooks/browser-lifecycle.ts b/agent/subagents/browser-agent/hooks/browser-lifecycle.ts new file mode 100644 index 00000000..b1f5351a --- /dev/null +++ b/agent/subagents/browser-agent/hooks/browser-lifecycle.ts @@ -0,0 +1,31 @@ +import { defineHook } from "eve/hooks"; +import { listWorkerBrowserSessions } from "@db/services/browsers"; +import { scopeFromPrincipal } from "@agent/lib/principal-scope"; +import { retireBrowserSession } from "../lib/lifecycle/retire"; + +export default defineHook({ + events: { + async "session.ended"(_event, ctx) { + const caller = ctx.session.auth.initiator ?? ctx.session.auth.current; + if (!caller) return; + const scope = scopeFromPrincipal(caller); + const browsers = await listWorkerBrowserSessions(scope, ctx.session.id); + // The ended occurrence may already be aborted. Retirement owns fresh + // deadlines and keeps ownership records when provider release fails. + const retired = await Promise.allSettled( + browsers.map((browser) => + retireBrowserSession(scope, ctx.session.id, browser) + ) + ); + const failures: unknown[] = []; + for (const result of retired) { + if (result.status === "rejected") failures.push(result.reason); + } + if (failures.length > 0) + throw new AggregateError( + failures, + "Some worker browsers could not be retired." + ); + }, + }, +}); diff --git a/agent/subagents/browser-agent/lib/lifecycle/retire.ts b/agent/subagents/browser-agent/lib/lifecycle/retire.ts new file mode 100644 index 00000000..77736734 --- /dev/null +++ b/agent/subagents/browser-agent/lib/lifecycle/retire.ts @@ -0,0 +1,68 @@ +import { z } from "zod"; +import { deleteBrowserSession } from "@db/services/browsers"; +import type { AccessScope } from "@shared/identity/access-scope"; +import { kernel } from "../kernel"; +import { disposeBrowserLoopSession } from "../semantic-loop"; +import { harvestBrowserTraceDomains } from "../trace/domains"; + +const auxiliaryBudgetMs = 3_000; +const releaseBudgetMs = 20_000; + +/** Forget ownership only after Kernel confirms release or absence. */ +export async function retireBrowserSession( + scope: AccessScope, + workerSessionId: string, + browser: Parameters[2], + signal?: AbortSignal +) { + await retirementHousekeeping( + "telemetry", + (stepSignal) => + harvestBrowserTraceDomains(scope, workerSessionId, browser, stepSignal), + signal + ); + await retirementHousekeeping( + "reference cleanup", + () => disposeBrowserLoopSession(browser.sessionId), + signal + ); + // Optional housekeeping cannot consume the provider's release deadline. + const deadline = AbortSignal.timeout(releaseBudgetMs); + const releaseSignal = signal ? AbortSignal.any([signal, deadline]) : deadline; + try { + await kernel.browsers.deleteByID(browser.sessionId, { + signal: releaseSignal, + }); + } catch (error) { + if (!z.object({ status: z.literal(404) }).safeParse(error).success) + throw error; + } + await deleteBrowserSession(scope, browser.sessionId); +} + +async function retirementHousekeeping( + step: "telemetry" | "reference cleanup", + operation: (signal: AbortSignal) => Promise, + signal?: AbortSignal +) { + const deadline = AbortSignal.timeout(auxiliaryBudgetMs); + const stepSignal = signal ? AbortSignal.any([signal, deadline]) : deadline; + let timer: ReturnType | undefined; + try { + await Promise.race([ + operation(stepSignal), + new Promise((_resolve, reject) => { + timer = setTimeout(() => { + reject(new Error("Retirement housekeeping timed out.")); + }, auxiliaryBudgetMs); + }), + ]); + } catch { + // A cache or telemetry failure must not keep the hosted browser running. + console.warn("[browser-lifecycle] Optional retirement step failed", { + step, + }); + } finally { + clearTimeout(timer); + } +} diff --git a/agent/subagents/browser-agent/tools/manage_browsers.ts b/agent/subagents/browser-agent/tools/manage_browsers.ts index 64b6cbd1..51beff75 100644 --- a/agent/subagents/browser-agent/tools/manage_browsers.ts +++ b/agent/subagents/browser-agent/tools/manage_browsers.ts @@ -14,22 +14,32 @@ import { withBrowserProfileWriteLock, } from "@db/services/browsers"; import { recordBrowserTraceDomains } from "@db/services/browser-traces"; +import { retireBrowserSession } from "../lib/lifecycle/retire"; import { kernel } from "@agent/subagents/browser-agent/lib/kernel"; import { requireWorkerScope } from "@agent/subagents/browser-agent/lib/access"; import { disposeBrowserLoopSession } from "../lib/semantic-loop"; import { requireOwnedBrowserSession } from "@agent/subagents/browser-agent/lib/owned-browser"; -import { - domainFromUrl, - harvestBrowserTraceDomains, -} from "@agent/subagents/browser-agent/lib/trace/domains"; +import { domainFromUrl } from "@agent/subagents/browser-agent/lib/trace/domains"; const browserTimeoutFloorSeconds = 15 * 60; +const startUrlSchema = z.url().refine((value) => { + try { + const url = new URL(value); + return ( + ["http:", "https:"].includes(url.protocol) && + !url.username && + !url.password + ); + } catch { + return false; + } +}, "Use an HTTP(S) URL without embedded credentials."); const inputSchema = z.object({ action: z.enum(["create", "update", "list", "get", "delete"]), save_changes: z.boolean().optional(), session_id: z.string().optional(), - start_url: z.url().optional(), + start_url: startUrlSchema.optional(), timeout_seconds: z .number() .int() @@ -53,6 +63,10 @@ const manageBrowsers = defineTool({ switch (input.action) { case "create": { + const startUrl = + input.start_url === undefined + ? undefined + : startUrlSchema.parse(input.start_url); const create = async () => { const profile = await ensureWorkspaceProfile( scope.workspaceId, @@ -75,7 +89,7 @@ const manageBrowsers = defineTool({ id: profile.id, save_changes: input.save_changes ?? false, }, - start_url: input.start_url, + start_url: startUrl, stealth: true, telemetry: { browser: { page: { enabled: true } }, @@ -169,19 +183,12 @@ const manageBrowsers = defineTool({ case "delete": { const sessionId = requireSessionId(input.session_id); const record = await requireOwnedBrowserSession(scope, sessionId); - await harvestBrowserTraceDomains( + await retireBrowserSession( scope, record.workerSessionId ?? context.session.id, { createdAt: record.createdAt, sessionId: record.sessionId }, signal ); - await disposeBrowserLoopSession(sessionId); - await kernel.browsers - .deleteByID(sessionId, { signal }) - .catch((cause: unknown) => { - if (!isNotFoundError(cause)) throw cause; - }); - await deleteBrowserSession(scope, sessionId); return "Browser session deleted successfully"; } } diff --git a/docs/browser-runtime-lessons.md b/docs/browser-runtime-lessons.md new file mode 100644 index 00000000..a8b0ca81 --- /dev/null +++ b/docs/browser-runtime-lessons.md @@ -0,0 +1,55 @@ +# Browser runtime lessons from BELL + +Reviewed [BELL Stack](https://github.com/browserbase/bell-stack/tree/89954b6429ce65dbb0a15646f08a993427d732f4) +at commit `89954b6`. That snapshot uses Eve 0.79.1 and Browserbase/Stagehand. +OpenInstinct keeps Kernel, Eve 1.0, workspace-scoped browser ownership, and its +dedicated browser worker. + +## Adopted + +| BELL practice | OpenInstinct adaptation | +| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Release hosted browsers when a conversation ends, including from a fresh process. | A native `session.ended` worker hook looks up that worker's browser records and retires them. Ordinary turn completion and cancellation leave the worker available for continuation. | +| Keep provider identifiers when release fails. | Ownership records are removed only after Kernel confirms deletion or absence. A failed release is reported and remains discoverable for recovery. Cleanup uses a fresh timeout rather than the ended session's cancellation signal. | +| Reject unsafe navigation URLs before using the provider. | `manage_browsers` accepts only HTTP(S) launch URLs without embedded credentials. Both the tool schema and execution boundary enforce the rule. | +| Make live provider regressions opt-in and fail when cleanup fails. | A Kernel check writes a synthetic cookie into a temporary profile, retires the writer, restores it in a read-only browser, and verifies retirement and cleanup. | + +## Existing strengths retained + +BELL's Context metadata is scoped to one trusted operator and process. Our +workspace database and profile writer lock already support user isolation and +concurrent readers. The existing server-side vault fill and screenshot masking +remain in place. Kernel telemetry already leaves network, console, CDP, +interaction, and screenshot capture off by default; page navigation is enabled +for domain summaries. + +## Useful follow-ups + +BELL's expiring handoff links and post-payment browser quarantine are worth +adapting separately. A handoff should use our authenticated workspace boundary. +Payment quarantine needs a checkout operation that owns filling, submission, +and reconciliation together, so ordinary browser tools cannot inspect payment +fields afterward. Copying the quarantine in isolation would break the current +fill-then-submit flow. Link remains disabled until its integration supports our +Eve version. + +BELL's separate task-state reducer and local Context file are unnecessary here; +Eve's native projection and our database remain the owning sources of state. + +## Live Kernel check + +```sh +OPENINSTINCT_LIVE_BROWSER_CHECK=1 pnpm test:browser:live +``` + +This uses real Kernel resources and the ignored `.env.local` configuration. It +creates a uniquely named test profile and two short-lived browsers, touches no +saved user profile or vault, and makes no website purchase or account change. +The cookie belongs to a reserved `.invalid` origin; no external website is +needed. Without the explicit flag, the command skips before starting the Kernel client or making provider calls. + +Cleanup runs even when verification fails. If browser release fails, the check +retains the temporary profile for recovery, prints its unique name, and exits +with an error. A skipped check does not establish provider behavior. This checks +the provider's profile and retirement contract; the worker hook has separate +credential-free regression coverage. diff --git a/package.json b/package.json index 67276b52..315de375 100644 --- a/package.json +++ b/package.json @@ -121,7 +121,8 @@ "build:eve": "eve build", "dev:eve": "eve dev", "start:eve": "eve start", - "test:runtime": "node --experimental-strip-types scripts/run-runtime-smoke.ts" + "test:runtime": "node --experimental-strip-types scripts/run-runtime-smoke.ts", + "test:browser:live": "node --env-file-if-exists=.env.local --import tsx scripts/check-browser-lifecycle.ts" }, "version": "0.0.0", "type": "module" diff --git a/scripts/check-browser-lifecycle.ts b/scripts/check-browser-lifecycle.ts new file mode 100644 index 00000000..82d842cf --- /dev/null +++ b/scripts/check-browser-lifecycle.ts @@ -0,0 +1,139 @@ +import { randomUUID } from "node:crypto"; +import { NotFoundError } from "@onkernel/sdk"; + +// oxlint-disable-next-line eslint/no-restricted-properties, turbo/no-undeclared-env-vars -- A standalone provider check requires explicit opt-in before loading credentials. +if (process.env.OPENINSTINCT_LIVE_BROWSER_CHECK !== "1") { + console.log( + "Skipped live browser check. Set OPENINSTINCT_LIVE_BROWSER_CHECK=1 to use real Kernel resources." + ); + process.exit(0); +} + +const { kernel } = await import("../agent/subagents/browser-agent/lib/kernel"); +const profileName = `openinstinct-check-${randomUUID()}`; +const browsers = new Set(); +const failures: unknown[] = []; +const options = () => ({ signal: AbortSignal.timeout(30_000), maxRetries: 0 }); +const cookie = { + name: "openinstinct_lifecycle_check", + value: randomUUID(), + url: "https://browser-check.invalid", +}; +let profileId: string | undefined; + +async function release(sessionId: string) { + try { + await kernel.browsers.deleteByID(sessionId, options()); + } catch (error) { + if (!(error instanceof NotFoundError)) throw error; + } + try { + const state = await kernel.browsers.retrieve( + sessionId, + { include_deleted: true }, + options() + ); + if (!state.deleted_at) + throw new Error("Kernel still reports the retired browser as active."); + } catch (error) { + if (!(error instanceof NotFoundError)) throw error; + } + browsers.delete(sessionId); +} + +try { + const profile = await kernel.profiles.create( + { name: profileName }, + options() + ); + if (!profile.id) throw new Error("Kernel returned no profile ID."); + profileId = profile.id; + const writer = await kernel.browsers.create( + { + profile: { id: profile.id, save_changes: true }, + timeout_seconds: 120, + telemetry: { enabled: false }, + }, + options() + ); + browsers.add(writer.session_id); + const written = await kernel.browsers.playwright.execute( + writer.session_id, + { + code: `if (!context) throw new Error('No browser context'); await context.addCookies([${JSON.stringify(cookie)}]); return true;`, + timeout_sec: 20, + }, + options() + ); + if (!written.success) + throw new Error( + `Synthetic profile cookie could not be written: ${written.error ?? "unknown provider error"}` + ); + await release(writer.session_id); + + const reader = await kernel.browsers.create( + { + profile: { id: profile.id, save_changes: false }, + timeout_seconds: 120, + telemetry: { enabled: false }, + }, + options() + ); + browsers.add(reader.session_id); + const restored = await kernel.browsers.playwright.execute( + reader.session_id, + { + code: `if (!context) throw new Error('No browser context'); const restoredCookies = await context.cookies(${JSON.stringify(cookie.url)}); return restoredCookies.some(cookie => cookie.name === ${JSON.stringify(cookie.name)} && cookie.value === ${JSON.stringify(cookie.value)});`, + timeout_sec: 20, + }, + options() + ); + if (!restored.success || restored.result !== true) + throw new Error( + `The reader did not restore the synthetic profile cookie: ${restored.error ?? "cookie missing"}` + ); + await release(reader.session_id); + console.log( + "Passed: profile persisted across writer retirement and a fresh read-only browser; both browsers retired." + ); +} catch (error) { + failures.push(error); +} finally { + // A create request can succeed remotely before its response is lost. Recover + // only browsers attached to this check's uniquely named temporary profile. + if (profileId) { + try { + for await (const browser of kernel.browsers.list( + { query: profileId, status: "active" }, + options() + )) { + if (browser.profile?.id === profileId) browsers.add(browser.session_id); + } + } catch (error) { + failures.push(error); + } + } + const cleanup = await Promise.allSettled([...browsers].map(release)); + for (const result of cleanup) { + if (result.status === "rejected") failures.push(result.reason); + } + // Keep the profile when browser release failed, so the provider resources can + // still be located by their unique profile name. + if (browsers.size === 0) { + try { + await kernel.profiles.delete(profileId ?? profileName, options()); + } catch (error) { + if (!(error instanceof NotFoundError)) failures.push(error); + } + } +} +if (failures.length > 0) { + console.error(`Live check failed; temporary profile: ${profileName}`); + throw new AggregateError( + failures, + "Kernel lifecycle check or cleanup failed." + ); +} +console.log( + "Cleanup verified: the temporary profile and browsers were released." +); diff --git a/tests/agent/subagents/browser-agent/hooks/browser-lifecycle.test.ts b/tests/agent/subagents/browser-agent/hooks/browser-lifecycle.test.ts new file mode 100644 index 00000000..3b49ce35 --- /dev/null +++ b/tests/agent/subagents/browser-agent/hooks/browser-lifecycle.test.ts @@ -0,0 +1,181 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import type { + deleteBrowserSession, + listWorkerBrowserSessions, +} from "@db/services/browsers"; +import type { disposeBrowserLoopSession } from "@agent/subagents/browser-agent/lib/semantic-loop"; +import type { harvestBrowserTraceDomains } from "@agent/subagents/browser-agent/lib/trace/domains"; +import { kernel } from "@agent/subagents/browser-agent/lib/kernel"; +import lifecycle from "@agent/subagents/browser-agent/hooks/browser-lifecycle"; +import { hookContextFor } from "@tests/helpers/hook-context"; + +const mocks = vi.hoisted(() => ({ + list: vi.fn(), + forget: vi.fn(), + dispose: vi.fn(), + harvest: vi.fn(), +})); +vi.mock("@db/services/browsers", () => ({ + listWorkerBrowserSessions: mocks.list, + deleteBrowserSession: mocks.forget, +})); +vi.mock("@agent/subagents/browser-agent/lib/semantic-loop", () => ({ + disposeBrowserLoopSession: mocks.dispose, +})); +vi.mock("@agent/subagents/browser-agent/lib/trace/domains", () => ({ + harvestBrowserTraceDomains: mocks.harvest, +})); +const release = vi.spyOn(kernel.browsers, "deleteByID"); +const ended = lifecycle.events["session.ended"]; +if (!ended) + throw new Error("The worker must register terminal-session cleanup."); +const scope = { userId: "user-1", workspaceId: "workspace-1" }; +const ctx = hookContextFor({ + sessionId: "worker-1", + auth: { + current: null, + initiator: { + principalId: scope.userId, + principalType: "user", + attributes: { workspaceId: scope.workspaceId }, + authenticator: "authjs", + }, + }, +}); +const browser = { sessionId: "browser-1", createdAt: "2026-11-02T12:00:00Z" }; + +beforeEach(() => { + vi.resetAllMocks(); + mocks.list.mockResolvedValue([browser]); + mocks.forget.mockResolvedValue(true); + mocks.dispose.mockResolvedValue(); + mocks.harvest.mockResolvedValue(); + release.mockResolvedValue(); +}); + +describe("worker browser retirement", () => { + it.each(["completed", "failed"] as const)( + "releases only this worker's browsers when the session ends %s", + async (outcome) => { + await ended({ type: "session.ended", data: { outcome } }, ctx); + expect(mocks.list).toHaveBeenCalledExactlyOnceWith(scope, "worker-1"); + expect(mocks.harvest).toHaveBeenCalledWith( + scope, + "worker-1", + browser, + expect.any(AbortSignal) + ); + expect(release).toHaveBeenCalledOnce(); + expect(release.mock.calls[0]?.[0]).toBe("browser-1"); + expect(release.mock.calls[0]?.[1]?.signal).toBeInstanceOf(AbortSignal); + expect(mocks.forget).toHaveBeenCalledExactlyOnceWith(scope, "browser-1"); + expect(release.mock.invocationCallOrder[0]).toBeLessThan( + mocks.forget.mock.invocationCallOrder[0] ?? 0 + ); + } + ); + + it("preserves a failed release for recovery while still retiring the other browsers", async () => { + mocks.list.mockResolvedValue([ + browser, + { ...browser, sessionId: "browser-2" }, + ]); + release.mockRejectedValueOnce(new Error("Provider unavailable")); + await expect( + ended({ type: "session.ended", data: { outcome: "completed" } }, ctx) + ).rejects.toThrow("Some worker browsers could not be retired."); + expect(mocks.forget).not.toHaveBeenCalledWith(scope, "browser-1"); + expect(mocks.forget).toHaveBeenCalledWith(scope, "browser-2"); + }); + + it("forgets a browser that the provider confirms is already absent", async () => { + release.mockRejectedValue({ status: 404 }); + await ended({ type: "session.ended", data: { outcome: "completed" } }, ctx); + expect(mocks.forget).toHaveBeenCalledWith(scope, "browser-1"); + }); + + it("does no provider work when a repeated retirement has no remaining browsers", async () => { + mocks.list.mockResolvedValue([]); + await ended({ type: "session.ended", data: { outcome: "completed" } }, ctx); + expect(release).not.toHaveBeenCalled(); + }); + + it("can retire a worker whose authenticated caller is current-only", async () => { + await ended( + { type: "session.ended", data: { outcome: "completed" } }, + { + ...ctx, + session: { + ...ctx.session, + auth: { initiator: null, current: ctx.session.auth.initiator }, + }, + } + ); + expect(mocks.list).toHaveBeenCalledWith(scope, "worker-1"); + expect(mocks.forget).toHaveBeenCalledWith(scope, "browser-1"); + }); + + it.each(["telemetry", "local disposal"] as const)( + "reserves a live provider deadline when %s exhausts its budget", + async (step) => { + vi.useFakeTimers(); + const timeout = vi + .spyOn(AbortSignal, "timeout") + .mockImplementation((milliseconds) => { + const controller = new AbortController(); + setTimeout(() => { + controller.abort(); + }, milliseconds); + return controller.signal; + }); + try { + if (step === "telemetry") { + mocks.harvest.mockImplementation( + async (_scope, _worker, _browser, signal) => { + if (!signal) throw new Error("Expected a telemetry deadline."); + await new Promise((resolve) => { + signal.addEventListener( + "abort", + () => { + resolve(); + }, + { once: true } + ); + }); + } + ); + } else { + mocks.dispose.mockImplementation( + () => new Promise(() => undefined) + ); + } + const work = ended( + { type: "session.ended", data: { outcome: "completed" } }, + ctx + ); + await vi.advanceTimersByTimeAsync(3_000); + await work; + expect(release).toHaveBeenCalledOnce(); + expect(release.mock.calls[0]?.[1]?.signal?.aborted).toBe(false); + expect(mocks.forget).toHaveBeenCalledWith(scope, "browser-1"); + } finally { + timeout.mockRestore(); + vi.useRealTimers(); + } + } + ); + + it("uses a fresh cleanup signal after the runtime occurrence was aborted", async () => { + const controller = new AbortController(); + controller.abort(); + await ended( + { type: "session.ended", data: { outcome: "completed" } }, + { + ...ctx, + occurrence: { ...ctx.occurrence, abortSignal: controller.signal }, + } + ); + expect(release.mock.calls[0]?.[1]?.signal?.aborted).toBe(false); + expect(mocks.forget).toHaveBeenCalledWith(scope, "browser-1"); + }); +}); diff --git a/tests/agent/subagents/browser-agent/tools/kernel-browser-contract.test.ts b/tests/agent/subagents/browser-agent/tools/kernel-browser-contract.test.ts index d716e84a..5d9ea10d 100644 --- a/tests/agent/subagents/browser-agent/tools/kernel-browser-contract.test.ts +++ b/tests/agent/subagents/browser-agent/tools/kernel-browser-contract.test.ts @@ -148,6 +148,26 @@ describe("Kernel browser contract", () => { ).toBe(true); }); + it.each([ + "not-a-url", + "", + "file:///etc/passwd", + "javascript:alert(1)", + "data:text/html,test", + "ftp://example.com/file", + "https://user:password@example.com/", + "https://user%40example.com:secret@merchant.test/", + ])( + "rejects unsafe launch URLs before contacting Kernel: %s", + async (start_url) => { + await expect( + manageBrowsers.execute({ action: "create", start_url }, workerContext) + ).rejects.toThrow("HTTP(S) URL without embedded credentials"); + expect(mocks.createBrowser).not.toHaveBeenCalled(); + expect(mocks.retrieveProfile).not.toHaveBeenCalled(); + } + ); + it("starts a read-only persistent-profile browser at the target URL", async () => { const result = await manageBrowsers.execute( { action: "create", start_url: "https://example.com/checkout" },