Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -364,3 +364,11 @@ explicit secrets.
Built on [Vercel](https://vercel.com) · [Kernel](https://kernel.sh) · [Linq](https://linqapp.com) · [Neon](https://neon.tech)

</div>

## 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.
31 changes: 31 additions & 0 deletions agent/subagents/browser-agent/hooks/browser-lifecycle.ts
Original file line number Diff line number Diff line change
@@ -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."
);
},
},
});
68 changes: 68 additions & 0 deletions agent/subagents/browser-agent/lib/lifecycle/retire.ts
Original file line number Diff line number Diff line change
@@ -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<typeof harvestBrowserTraceDomains>[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<void>,
signal?: AbortSignal
) {
const deadline = AbortSignal.timeout(auxiliaryBudgetMs);
const stepSignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
let timer: ReturnType<typeof setTimeout> | undefined;
try {
await Promise.race([
operation(stepSignal),
new Promise<never>((_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);
}
}
35 changes: 21 additions & 14 deletions agent/subagents/browser-agent/tools/manage_browsers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand All @@ -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,
Expand All @@ -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 } },
Expand Down Expand Up @@ -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";
}
}
Expand Down
55 changes: 55 additions & 0 deletions docs/browser-runtime-lessons.md
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
139 changes: 139 additions & 0 deletions scripts/check-browser-lifecycle.ts
Original file line number Diff line number Diff line change
@@ -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<string>();
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."
);
Loading
Loading