@myagentroam/node 0.9.152 → 0.9.154

package/dist/connector.js

@@ -72,7 +72,7 @@ import { SessionCatalogService } from './service/session-catalog-service.js';
 import { SessionCommandService } from './service/session-command-service.js';
 import { SessionPresentationService } from './service/session-presentation-service.js';
 import { isPlainRecord, isRunnerImageAttachment, parseRunnerImageAttachments } from './runner/codex/conversation-parser.js';
-import { readWebSearchError } from './service/web-search-error.js';
+import { WebToolService } from './service/web-tool-service.js';
 export { nodeConnectEndpoint, validatedCapabilities } from './runner/codex/conversation-parser.js';
 import { NodeControlChannel } from './service/node-control-channel.js';
 import { NodeControlMessageService } from './service/node-control-message-service.js';
@@ -168,6 +168,7 @@ export class NodeConnector {
         send: (envelope) => this.sendEnvelope(envelope)
     });
     marAgentRuntimeModels = new MarAgentRuntimeModelFactory(this.runtimeCredentials);
+    webToolService = new WebToolService(() => this.config);
     marAgentModelTransportTests = new MarAgentModelTransportTestService({
         modelFactory: this.marAgentRuntimeModels
     });
@@ -589,7 +590,8 @@ export class NodeConnector {
             setCommandState: (sessionId, state) => this.commandStates.set(sessionId, state),
             clearCommandState: (sessionId, commandId) => this.commandStates.clear(sessionId, commandId),
             commandStates: (sessionId) => this.commandStates.list(sessionId),
-            webSearch: (input, signal) => this.webSearch(input, signal),
+            webSearch: (input, signal) => this.webToolService.webSearch(input, signal),
+            webFetch: (input, signal) => this.webToolService.webFetch(input, signal),
             registerGeneratedImages: (runId, nativeSessionId, images) => {
                 const turn = this.runtime.conversationTurnForRun(runId);
                 const session = turn === undefined ? undefined : this.runtime.getAgentSession(turn.sessionId);
@@ -1536,7 +1538,8 @@ export class NodeConnector {
                     await templateService.recoverInterruptedPublications();
                     await store.rebuildConversationIndex();
                     runtime = new MarAgentHostedConversationRuntime({
-                        webSearch: (input, signal) => this.webSearch(input, signal),
+                        webSearch: (input, signal) => this.webToolService.webSearch(input, signal),
+                        webFetch: (input, signal) => this.webToolService.webFetch(input, signal, false),
                         modelFactory: this.marAgentRuntimeModels,
                         registerNativeImages: (runId, roots, images) => this.runAttachmentService.registerNativeImages(runId, roots, images, {
                             reuseCachedRunImages: false
@@ -2021,6 +2024,7 @@ export class NodeConnector {
         this.scheduledRunAuthorization.close();
         this.mailNotificationControl.close();
         const mailMcpDrain = this.mailNotificationMcpServer.close();
+        const webToolDrain = this.webToolService.close();
         this.directTransferService?.dispose();
         this.directTransferService = undefined;
         this.controlChannel.stop();
@@ -2033,7 +2037,8 @@ export class NodeConnector {
             uploadDrain,
             goalMcpDrain,
             scheduledMcpDrain,
-            mailMcpDrain
+            mailMcpDrain,
+            webToolDrain
         ]);
         this.stopping = (async () => {
             try {
@@ -2202,25 +2207,6 @@ export class NodeConnector {
         });
         return this.gitExecutionService;
     }
-    async webSearch(input, signal) {
-        const config = this.config;
-        if (config?.nodeId === undefined || config.credential === undefined)
-            throw new Error('NODE_UNAUTHENTICATED');
-        const response = await fetch(`${config.serverUrl.replace(/\/$/u, '')}/api/node-tools/web-search`, {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                'x-mar-node-id': config.nodeId,
-                authorization: `Bearer ${config.credential}`
-            },
-            body: JSON.stringify(input),
-            signal
-        });
-        if (!response.ok)
-            throw await readWebSearchError(response);
-        const result = await response.json();
-        return { content: JSON.stringify(result), data: result };
-    }
     publishGoalState(session, goal) {
         if (goal.status !== 'active') {
             this.commandStates.clear(session.id, 'goal');

package/dist/main.js

@@ -1,16 +1,20 @@
 #!/usr/bin/env node
 import { dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { NodeConnector } from './connector.js';
+import { spawnSync } from 'node:child_process';
 import { loadNodeConfig, nodeConfigPath, nodeDatabasePath, nodeDataDirectory } from './config.js';
 import { getNodeHealth } from './health.js';
-import { removeServiceDefinition, writeServiceDefinition } from './service.js';
+import { browserCachePath, removeServiceDefinition, writeServiceDefinition } from './service.js';
 import { superviseNode } from './supervisor.js';
 import { configureNodeLog } from './rotating-log.js';
 const [command = 'status', ...args] = process.argv.slice(2);
 const config = readOption(args, '--config') ?? nodeConfigPath();
 const output = readOption(args, '--output') ?? defaultServicePath();
+const browserPath = readOption(args, '--browser-cache');
+if (browserPath !== undefined)
+    process.env['PLAYWRIGHT_BROWSERS_PATH'] = browserPath;
 if (command === 'run') {
+    const { NodeConnector } = await import('./connector.js');
     configureNodeLog(nodeDataDirectory(await loadNodeConfig(config), config));
     const connector = new NodeConnector({ configPath: config });
     await connector.start();
@@ -54,5 +58,9 @@ function defaultServicePath() {
 }
 async function writeCurrentServiceDefinition(output, configPath) {
     const nodeConfig = await loadNodeConfig(configPath);
-    await writeServiceDefinition(output, process.execPath, configPath, process.platform, process.argv[1], [dirname(nodeDatabasePath(nodeConfig, configPath)), ...nodeConfig.allowedRoots]);
+    const cachePath = browserCachePath(nodeDataDirectory(nodeConfig, configPath));
+    const browser = spawnSync(process.execPath, [resolve(import.meta.dirname, '../scripts/install-web-browser.mjs')], { stdio: 'inherit', env: { ...process.env, PLAYWRIGHT_BROWSERS_PATH: cachePath } });
+    if (browser.error || browser.signal || browser.status !== 0)
+        throw new Error('NODE_WEB_BROWSER_INSTALL_FAILED');
+    await writeServiceDefinition(output, process.execPath, configPath, process.platform, process.argv[1], [dirname(nodeDatabasePath(nodeConfig, configPath)), ...nodeConfig.allowedRoots], cachePath);
 }

package/dist/runner/mar-agent/execution-extensions.js

@@ -0,0 +1,21 @@
+import { MarAgentError } from '@myagentroam/agent';
+/** Composes Node-owned tools without replacing another domain's execution handler. */
+export function combineExecutionExtensions(...sources) {
+    const tools = sources.flatMap((source) => source.tools ?? []);
+    if (new Set(tools.map((tool) => tool.name)).size !== tools.length)
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Host tool names conflict.');
+    return {
+        tools,
+        skills: sources.flatMap((source) => source.skills ?? []),
+        isToolAvailable: (name, context) => {
+            const source = sources.find((source) => source.tools?.some((tool) => tool.name === name));
+            return source !== undefined && source.isToolAvailable?.(name, context) !== false;
+        },
+        executeTool: async (call, context) => {
+            const source = sources.find((source) => source.tools?.some((tool) => tool.name === call.name));
+            if (!source?.executeTool)
+                throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Host tool is unavailable.');
+            return source.executeTool(call, context);
+        }
+    };
+}

package/dist/runner/mar-agent/hosted-conversation-runtime.js

@@ -6,6 +6,8 @@ import { hostedConversationGeneratedImagesDisplayDirectory, hostedConversationIm
 import { MarAgentMcpClientPool } from './mcp-client-pool.js';
 import { MarAgentRuntimeModelFactory, sdkModelConfigurations, closeImageCredentialProviders } from './runtime-model-factory.js';
 import { createImageGenerationExtensions } from './image-generation-extensions.js';
+import { createWebToolsExtensions } from './web-tools-extensions.js';
+import { combineExecutionExtensions } from './execution-extensions.js';
 /**
  * Opens one short-lived MAR Agent Host per hosted Run so template mounts cannot leak across Run
  * boundaries. Conversation-scoped tmp and Session history may remain available to later Runs.
@@ -18,6 +20,7 @@ export class MarAgentHostedConversationRuntime {
     #now;
     #onEvent;
     #webSearch;
+    #webFetch;
     #active = new Map();
     #modelFactory;
     #registerNativeImages;
@@ -29,6 +32,7 @@ export class MarAgentHostedConversationRuntime {
         this.#now = options.now ?? Date.now;
         this.#onEvent = options.onEvent;
         this.#webSearch = options.webSearch;
+        this.#webFetch = options.webFetch;
         this.#registerNativeImages = options.registerNativeImages;
         this.#modelFactory =
             options.modelFactory ??
@@ -275,7 +279,7 @@ export class MarAgentHostedConversationRuntime {
                 executionId: 'clientMessageId' in input ? input.clientMessageId : input.conversationId
             });
             const selectedModelId = 'defaultModelId' in input ? input.defaultModelId : input.modelId;
-            const extensions = createImageGenerationExtensions({
+            const imageExtensions = createImageGenerationExtensions({
                 configuration: models.find((model) => model.id === selectedModelId)?.imageGeneration,
                 homeDirectory: input.homeDirectory,
                 ...(generatedImageDisplayDirectory === undefined
@@ -283,6 +287,16 @@ export class MarAgentHostedConversationRuntime {
                     : { displayDirectory: generatedImageDisplayDirectory }),
                 host: () => host
             });
+            const webAccess = 'webAccess' in input && input.webAccess;
+            const extensions = combineExecutionExtensions(imageExtensions, createWebToolsExtensions({
+                enabled: webAccess,
+                hostedSearchModelIds: models
+                    .filter((model) => model.hostedWebSearch)
+                    .map((model) => model.id),
+                hostedWebSearch: models.find((model) => model.id === selectedModelId)?.hostedWebSearch ?? false,
+                ...(this.#webSearch === undefined ? {} : { webSearch: this.#webSearch }),
+                ...(this.#webFetch === undefined ? {} : { webFetch: this.#webFetch })
+            }));
             host = this.#createHost({
                 extensions,
                 mode: 'node',
@@ -294,17 +308,12 @@ export class MarAgentHostedConversationRuntime {
                 restrictPaths: true,
                 workspaceWritable: false,
                 pathMounts: hostedPathMounts(input),
-                webFetch: 'webAccess' in input && input.webAccess,
-                ...('webAccess' in input && input.webAccess && this.#webSearch !== undefined
-                    ? { webSearch: this.#webSearch }
-                    : {}),
                 ...(mcp === undefined
                     ? {}
                     : {
                         mcpCatalog: () => mcp.catalog(),
                         callMcp: (call, signal, context) => mcp.call(call.name, call.arguments, signal, context?.expectedTool)
-                    }),
-                allowUntrustedTls: false
+                    })
             });
         }
         catch (error) {

package/dist/runner/mar-agent/managed-run-controller.js

@@ -3,6 +3,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { access, constants } from 'node:fs/promises';
 import { nodeExecutionEnvironment } from '../../node-execution-environment.js';
+import { nodeLog } from '../../operational.js';
 import { BUNDLED_RIPGREP_VERSION, bundledRipgrepPath, prependBundledRipgrepToPath } from '../../ripgrep-binary.js';
 import { LocalAgentHost, createMarAgent, generateSessionTitle } from '@myagentroam/agent';
 import { marAgentReasoningEffortSchema, marAgentRuntimeModelConfigurationSchema } from '@myagentroam/protocol';
@@ -14,6 +15,8 @@ import { parseRunnerImageAttachments } from '../../util/node-operation-parsers.j
 import { runnerErrorProjection } from '../../util/runner-error.js';
 import { MarAgentRuntimeModelFactory, sdkModelConfigurations, closeImageCredentialProviders } from './runtime-model-factory.js';
 import { createImageGenerationExtensions } from './image-generation-extensions.js';
+import { createWebToolsExtensions } from './web-tools-extensions.js';
+import { combineExecutionExtensions } from './execution-extensions.js';
 export class MarAgentManagedRunController {
     runner;
     host;
@@ -61,7 +64,7 @@ export class MarAgentManagedRunController {
                 execution.cancelTitle();
                 execution.cancel();
             }
-            await Promise.all([...new Set(this.#sessionRuntimes.values())].map((runtime) => this.#releaseRuntime(runtime)));
+            await Promise.all([...new Set(this.#sessionRuntimes.values())].map((runtime) => this.#releaseRuntime(runtime, 'controller_disposed')));
             await this.#mcpClients.close();
             await this.#computerUse?.dispose();
         })();
@@ -83,7 +86,7 @@ export class MarAgentManagedRunController {
                 execution?.cancelTitle();
                 execution?.cancel();
             }
-            await this.#releaseRuntime(runtime);
+            await this.#releaseRuntime(runtime, 'session_released');
             await Promise.all([
                 this.#computerUse?.releaseSession(sessionId),
                 this.#computerUse?.releaseSession(runtime.session.id)
@@ -279,21 +282,26 @@ export class MarAgentManagedRunController {
             const acquisition = this.#acquireRuntime(input);
             for (const key of acquisitionKeys)
                 this.#runtimeAcquisitions.set(key, acquisition);
+            let acquired = false;
             try {
                 runtime = await acquisition;
+                acquired = true;
                 executionModels = runtime.models;
             }
             finally {
                 for (const key of acquisitionKeys)
                     if (this.#runtimeAcquisitions.get(key) === acquisition)
                         this.#runtimeAcquisitions.delete(key);
+                // A failed acquisition may have retained an idle Runtime before setup failed.
+                if (!acquired)
+                    this.#restoreRuntimeRelease(this.#sessionRuntimes.get(sessionKey));
             }
             controller.signal.throwIfAborted();
             if (this.#disposed ||
                 this.#sessionReleases.has(sessionKey) ||
                 this.#sessionReleases.has(input.sessionId) ||
                 this.#sessionReleases.has(runtime.session.id)) {
-                await this.#releaseRuntime(runtime);
+                await this.#releaseRuntime(runtime, 'admission_released');
                 throw new Error('MAR_AGENT_SESSION_RUNTIME_RELEASED');
             }
             if (runtime.activeRunId !== undefined)
@@ -341,12 +349,23 @@ export class MarAgentManagedRunController {
                 homeDirectory: homedir(),
                 host: () => runtime.host
             });
+            const extensions = combineExecutionExtensions(imageExtensions, createWebToolsExtensions({
+                enabled: true,
+                hostedSearchModelIds: executionModels
+                    .filter((model) => model.hostedWebSearch)
+                    .map((model) => model.id),
+                hostedWebSearch: executionModels.find((model) => model.id === input.model.id)?.hostedWebSearch ?? false,
+                webSearch: (request, signal) => this.host.webSearch(request, signal),
+                ...(this.host.webFetch === undefined
+                    ? {}
+                    : { webFetch: (request, signal) => this.host.webFetch(request, signal) })
+            }));
             executionMcpBinding = runtime.host.bindExecutionExtensions({
-                ...imageExtensions,
+                ...extensions,
                 environment: input.secretEnvironment?.['MAR_CTL_USER_TOKEN'] === undefined
                     ? {}
                     : { MAR_CTL_USER_TOKEN: input.secretEnvironment['MAR_CTL_USER_TOKEN'] },
-                skills: [...(imageExtensions.skills ?? []), computerUseHostSkill]
+                skills: [...(extensions.skills ?? []), computerUseHostSkill]
             }, {
                 tools: [...nodeTools, ...userTools],
                 catalog: () => {
@@ -488,16 +507,16 @@ export class MarAgentManagedRunController {
         }
     }
     #prepareRuntimeForTerminal(runId, runtime) {
-        if (runtime.activeRunId === runId) {
-            delete runtime.activeRunId;
-        }
+        if (runtime.activeRunId !== runId)
+            return;
+        delete runtime.activeRunId;
         this.#scheduleRuntimeRelease(runtime);
     }
     async #finishRuntimeExecution(runId, runtime) {
-        if (runtime.activeRunId === runId) {
-            delete runtime.activeRunId;
-        }
-        this.#scheduleRuntimeRelease(runtime);
+        if (runtime.activeRunId === runId)
+            this.#prepareRuntimeForTerminal(runId, runtime);
+        else
+            this.#restoreRuntimeRelease(runtime);
     }
     async #acquireRuntime(input) {
         if (this.#disposed)
@@ -553,9 +572,14 @@ export class MarAgentManagedRunController {
                         existing.personalInstructions = personalInstructions;
                     }
                     this.#retainRuntime(sessionKey);
+                    nodeLog('runner.mar-agent.runtime.reused', {
+                        runtimeId: existing.runtimeId,
+                        sessionId: existing.session.id,
+                        runId: input.runId
+                    });
                     return existing;
                 }
-                await this.#releaseRuntime(existing);
+                await this.#releaseRuntime(existing, 'host_configuration_changed');
             }
             const creation = this.#createRuntime(input, sessionKey, fingerprint, hostConfiguration);
             for (const key of creationKeys)
@@ -598,8 +622,6 @@ export class MarAgentManagedRunController {
                 },
                 mcpCatalog: () => mcp.catalog(),
                 callMcp: async (call, signal, context) => mcp.call(call.name, call.arguments, signal, context?.expectedTool),
-                webSearch: (request, signal) => this.host.webSearch(request, signal),
-                allowUntrustedTls: allowsUntrustedWebFetchTls(hostConfiguration.environment),
                 resourceIdleTtlMs: this.#resourceIdleTtlMs
             });
             models = this.#modelFactory.create(input.models, {
@@ -617,6 +639,7 @@ export class MarAgentManagedRunController {
                 ? await agent.openSession(input.externalSessionId)
                 : await agent.createSession({ workspace: input.cwd });
             runtime = {
+                runtimeId: randomUUID(),
                 fingerprint,
                 agent,
                 session,
@@ -631,6 +654,11 @@ export class MarAgentManagedRunController {
             };
             this.#sessionRuntimes.set(sessionKey, runtime);
             this.#sessionRuntimes.set(session.id, runtime);
+            nodeLog('runner.mar-agent.runtime.created', {
+                runtimeId: runtime.runtimeId,
+                sessionId: session.id,
+                runId: input.runId
+            });
             if (!input.externalSessionId)
                 this.host.promote(input.sessionId, session.id);
             return runtime;
@@ -642,16 +670,26 @@ export class MarAgentManagedRunController {
             throw error;
         }
     }
+    #runtimeInUse(runtime) {
+        return (runtime.activeRunId !== undefined ||
+            [...this.#runtimeAcquisitions.keys()].some((key) => this.#sessionRuntimes.get(key) === runtime));
+    }
     #scheduleRuntimeRelease(runtime) {
-        if (runtime.released || runtime.release !== undefined)
+        // Old finalizers must neither reclaim a continuation nor extend its idle lease.
+        if (runtime.released ||
+            runtime.release !== undefined ||
+            runtime.idleTimer !== undefined ||
+            this.#runtimeInUse(runtime))
             return;
-        if (runtime.idleTimer !== undefined)
-            clearTimeout(runtime.idleTimer);
-        runtime.idleTimer = setTimeout(() => {
+        const timer = setTimeout(() => {
+            if (runtime.idleTimer !== timer)
+                return;
             delete runtime.idleTimer;
-            void this.#releaseRuntime(runtime);
+            if (!this.#runtimeInUse(runtime))
+                void this.#releaseRuntime(runtime, 'idle_expired');
         }, this.#resourceIdleTtlMs);
-        runtime.idleTimer.unref();
+        runtime.idleTimer = timer;
+        timer.unref();
     }
     #retainRuntime(sessionKey) {
         const runtime = this.#sessionRuntimes.get(sessionKey);
@@ -670,11 +708,17 @@ export class MarAgentManagedRunController {
             return;
         this.#scheduleRuntimeRelease(runtime);
     }
-    #releaseRuntime(runtime) {
+    #releaseRuntime(runtime, reason) {
         if (runtime.release !== undefined)
             return runtime.release;
         runtime.release = (async () => {
             runtime.released = true;
+            nodeLog('runner.mar-agent.runtime.releasing', {
+                runtimeId: runtime.runtimeId,
+                sessionId: runtime.session.id,
+                reason,
+                ...(runtime.activeRunId === undefined ? {} : { runId: runtime.activeRunId })
+            });
             if (runtime.idleTimer !== undefined) {
                 clearTimeout(runtime.idleTimer);
                 delete runtime.idleTimer;
@@ -811,9 +855,6 @@ function sessionModelFingerprint(input) {
     }))
         .digest('hex');
 }
-export function allowsUntrustedWebFetchTls(environment) {
-    return environment['MAR_AGENT_WEB_FETCH_ALLOW_UNTRUSTED_TLS'] !== '0';
-}
 async function resolveMarAgentHostRuntimeConfiguration(secretEnvironment = {}) {
     const environment = nodeExecutionEnvironment({
         ...secretEnvironment,

package/dist/runner/mar-agent/web-tools-extensions.js

@@ -0,0 +1,72 @@
+import { MarAgentError } from '@myagentroam/agent';
+import { WEB_FETCH_MAX_URL_LENGTH, webFetchRequestSchema, webSearchRequestSchema } from '../../service/web-fetch-contracts.js';
+export const webSearchToolDefinition = {
+    name: 'web_search',
+    allowedCallers: ['direct', 'programmatic'],
+    parallelSafety: 'safe',
+    description: 'Search the web for current information using the Node search service. Use web_fetch to open a specific result.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', maxLength: 500 },
+            maxResults: { type: 'integer', minimum: 1, maximum: 10, default: 8 }
+        },
+        required: ['query'],
+        additionalProperties: false
+    }
+};
+export const webFetchToolDefinition = {
+    name: 'web_fetch',
+    allowedCallers: ['direct', 'programmatic'],
+    parallelSafety: 'safe',
+    description: 'Read an HTTP or HTTPS URL from the Node network, including intranet URLs. Choose http for raw text/HTML without JavaScript, or browser for rendered visible text using an isolated headless Chromium. Modes never switch automatically; explicitly retry in the other mode when needed. No user browser login or cookies are shared.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            url: { type: 'string', maxLength: WEB_FETCH_MAX_URL_LENGTH },
+            mode: { type: 'string', enum: ['http', 'browser'] }
+        },
+        required: ['url', 'mode'],
+        additionalProperties: false
+    }
+};
+export function createWebToolsExtensions(input) {
+    const tools = input.enabled
+        ? [
+            ...((input.hostedSearchModelIds !== undefined || !input.hostedWebSearch) && input.webSearch
+                ? [webSearchToolDefinition]
+                : []),
+            ...(input.webFetch ? [webFetchToolDefinition] : [])
+        ]
+        : [];
+    const isToolAvailable = (name, context) => tools.some((tool) => tool.name === name) &&
+        (name !== 'web_search' ||
+            !(context.modelId === undefined || input.hostedSearchModelIds === undefined
+                ? input.hostedWebSearch
+                : input.hostedSearchModelIds.includes(context.modelId)));
+    return {
+        tools,
+        isToolAvailable,
+        executeTool: async (call, context) => {
+            if (!isToolAvailable(call.name, context))
+                throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Node web tool is unavailable.');
+            context.signal.throwIfAborted();
+            const parsed = call.name === 'web_search'
+                ? webSearchRequestSchema.safeParse(call.arguments)
+                : webFetchRequestSchema.safeParse(call.arguments);
+            if (!parsed.success)
+                throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Node web tool input is invalid.');
+            try {
+                if (call.name === 'web_search')
+                    return await input.webSearch(webSearchRequestSchema.parse(parsed.data), context.signal);
+                const request = webFetchRequestSchema.parse(parsed.data);
+                return await input.webFetch({ ...request, url: new URL(request.url).href }, context.signal);
+            }
+            catch (error) {
+                if (context.signal.aborted || error instanceof MarAgentError)
+                    throw error;
+                throw new MarAgentError(call.name === 'web_search' ? 'MAR_AGENT_WEB_SEARCH_FAILED' : 'MAR_AGENT_WEB_FETCH_FAILED', call.name === 'web_search' ? 'Web search failed.' : 'Web fetch failed.', { cause: error });
+            }
+        }
+    };
+}

package/dist/service/web-fetch-contracts.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+export const WEB_FETCH_MAX_BYTES = 1_000_000;
+export const WEB_FETCH_MAX_URL_LENGTH = 8_192;
+const webUrlSchema = z
+    .string()
+    .max(WEB_FETCH_MAX_URL_LENGTH)
+    .refine((value) => {
+    try {
+        const url = new URL(value);
+        return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+});
+export const webFetchModeSchema = z.enum(['http', 'browser']);
+export const webFetchRequestSchema = z
+    .object({
+    url: webUrlSchema,
+    mode: webFetchModeSchema
+})
+    .strict();
+export const webSearchRequestSchema = z
+    .object({
+    query: z.string().trim().min(1).max(500),
+    maxResults: z.number().int().min(1).max(10).default(8)
+})
+    .strict();
+export const webFetchResultSchema = z
+    .object({
+    content: z
+        .string()
+        .max(WEB_FETCH_MAX_BYTES)
+        .refine((value) => new TextEncoder().encode(value).byteLength <= WEB_FETCH_MAX_BYTES),
+    data: z
+        .object({
+        url: webUrlSchema,
+        mode: webFetchModeSchema,
+        status: z.number().int().min(200).max(299),
+        contentType: z.string().max(256),
+        title: z.string().max(1_000).optional()
+    })
+        .strict(),
+    truncated: z.boolean()
+})
+    .strict();

package/dist/service/web-fetch-service.js

@@ -0,0 +1,345 @@
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { createBrotliDecompress, createGunzip, createInflate } from 'node:zlib';
+import { pipeline } from 'node:stream/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { MarAgentError } from '@myagentroam/agent';
+import { chromium, errors } from 'playwright';
+import { WEB_FETCH_MAX_BYTES, webFetchRequestSchema } from './web-fetch-contracts.js';
+const TIMEOUT_MS = 30_000;
+const MAX_REDIRECTS = 5;
+const MAX_BROWSER_REQUESTS = 2;
+export class WebFetchError extends MarAgentError {
+    code;
+    status;
+    publicMessage;
+    publicParameters;
+    constructor(code, status, publicMessage, publicParameters) {
+        super(code, publicMessage, { details: { status, ...(publicParameters ?? {}) } });
+        this.code = code;
+        this.status = status;
+        this.publicMessage = publicMessage;
+        this.publicParameters = publicParameters;
+    }
+}
+/** Owns Node-side network access and the lifetime of isolated browser reads. */
+export class WebFetchService {
+    #shutdown = new AbortController();
+    #active = new Set();
+    #allowUntrustedTls;
+    #launchBrowser;
+    #browserRequests = 0;
+    #closing;
+    constructor(options = {}) {
+        this.#allowUntrustedTls =
+            options.allowUntrustedTls ?? process.env['MAR_AGENT_WEB_FETCH_ALLOW_UNTRUSTED_TLS'] !== '0';
+        this.#launchBrowser = options.launchBrowser ?? chromium.launch.bind(chromium);
+    }
+    fetch(input, signal, policy = {}) {
+        const parsed = webFetchRequestSchema.safeParse(input);
+        if (!parsed.success)
+            return Promise.reject(new WebFetchError('MAR_AGENT_TOOL_INPUT_INVALID', 400, 'Web fetch input is invalid.'));
+        const timeout = AbortSignal.timeout(TIMEOUT_MS);
+        const combined = AbortSignal.any([signal, this.#shutdown.signal, timeout]);
+        const task = this.#execute(parsed.data, combined, policy.allowUntrustedTls ?? this.#allowUntrustedTls).catch((error) => {
+            if (timeout.aborted || error instanceof errors.TimeoutError)
+                throw new WebFetchError('MAR_AGENT_WEB_FETCH_TIMEOUT', 504, 'Web fetch timed out.');
+            if (combined.aborted)
+                throw new WebFetchError('MAR_AGENT_WEB_FETCH_CANCELLED', 503, 'Web fetch was cancelled.');
+            if (error instanceof WebFetchError)
+                throw error;
+            throw new WebFetchError('MAR_AGENT_WEB_FETCH_UPSTREAM_FAILED', 502, 'Web fetch upstream failed.');
+        });
+        this.#active.add(task);
+        void task.then(() => this.#active.delete(task), () => this.#active.delete(task));
+        return task;
+    }
+    close() {
+        return (this.#closing ??= this.#close());
+    }
+    async #close() {
+        this.#shutdown.abort();
+        await Promise.allSettled([...this.#active]);
+    }
+    async #execute(input, signal, allowUntrustedTls) {
+        signal.throwIfAborted();
+        return input.mode === 'http'
+            ? this.#fetchHttp(input, signal, allowUntrustedTls)
+            : this.#fetchBrowser(input, signal, allowUntrustedTls);
+    }
+    async #fetchHttp(input, signal, allowUntrustedTls) {
+        let url = new URL(input.url);
+        for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects++) {
+            const response = await requestHttp(url, signal, allowUntrustedTls);
+            const status = response.statusCode ?? 0;
+            const location = response.headers.location;
+            if ([301, 302, 303, 307, 308].includes(status) && location) {
+                response.destroy();
+                const next = new URL(location, url);
+                if (!webFetchRequestSchema.safeParse({ url: next.href, mode: 'http' }).success)
+                    throw new WebFetchError('MAR_AGENT_TOOL_INPUT_INVALID', 400, 'Redirect URL is not supported.');
+                url = next;
+                continue;
+            }
+            const contentType = (response.headers['content-type'] ?? 'text/plain').slice(0, 256);
+            if (status < 200 || status >= 300 || !readableContentType(contentType)) {
+                response.destroy();
+                validateResponse(status, contentType);
+            }
+            const encoding = response.headers['content-encoding']?.trim().toLowerCase() ?? 'identity';
+            const decompressor = encoding === 'gzip'
+                ? createGunzip()
+                : encoding === 'br'
+                    ? createBrotliDecompress()
+                    : encoding === 'deflate'
+                        ? createInflate()
+                        : undefined;
+            if (!decompressor && encoding !== 'identity' && encoding !== '') {
+                response.destroy();
+                throw new WebFetchError('MAR_AGENT_WEB_FETCH_UNSUPPORTED_CONTENT', 415, 'Response content encoding is not supported.');
+            }
+            const body = decompressor ?? response;
+            let transferError;
+            const transfer = decompressor
+                ? pipeline(response, decompressor, { signal }).catch((error) => {
+                    transferError = error;
+                })
+                : undefined;
+            const chunks = [];
+            let bytes = 0;
+            let truncated = false;
+            try {
+                for await (const chunk of body) {
+                    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                    const remaining = WEB_FETCH_MAX_BYTES - bytes;
+                    chunks.push(buffer.subarray(0, remaining));
+                    bytes += Math.min(remaining, buffer.byteLength);
+                    if (buffer.byteLength > remaining) {
+                        truncated = true;
+                        break;
+                    }
+                }
+            }
+            finally {
+                response.destroy();
+                decompressor?.destroy();
+                await transfer;
+            }
+            if (!truncated && transferError)
+                throw transferError;
+            signal.throwIfAborted();
+            const text = new TextDecoder().decode(Buffer.concat(chunks), { stream: truncated });
+            const output = Buffer.from(text);
+            truncated ||= output.byteLength > WEB_FETCH_MAX_BYTES;
+            const content = new TextDecoder().decode(output.subarray(0, WEB_FETCH_MAX_BYTES), {
+                stream: truncated
+            });
+            return { content, data: { url: url.href, mode: 'http', status, contentType }, truncated };
+        }
+        throw new WebFetchError('MAR_AGENT_WEB_FETCH_UPSTREAM_FAILED', 502, 'Too many web fetch redirects.');
+    }
+    async #fetchBrowser(input, signal, allowUntrustedTls) {
+        if (this.#browserRequests >= MAX_BROWSER_REQUESTS)
+            throw new WebFetchError('MAR_AGENT_WEB_FETCH_BUSY', 429, 'Node web fetch browser capacity is exhausted.');
+        this.#browserRequests++;
+        let browser;
+        let context;
+        let navigationFailure;
+        const cancel = () => {
+            void browser?.close().catch(() => undefined);
+        };
+        signal.addEventListener('abort', cancel, { once: true });
+        try {
+            try {
+                browser = await this.#launchBrowser({
+                    headless: true,
+                    channel: 'chromium',
+                    timeout: 15_000
+                });
+            }
+            catch {
+                throw new WebFetchError('MAR_AGENT_WEB_FETCH_BROWSER_UNAVAILABLE', 503, 'Node Chromium could not start. Prepare the matching runtime with the Node browser installation script under the service account. On Linux, check Chromium system libraries; an administrator may need to install them.');
+            }
+            signal.throwIfAborted();
+            context = await browser.newContext({
+                acceptDownloads: false,
+                ignoreHTTPSErrors: allowUntrustedTls,
+                serviceWorkers: 'block'
+            });
+            let blockedNavigation = false;
+            let resourceRequests = 0;
+            await context.route('**/*', async (route) => {
+                const request = route.request();
+                resourceRequests++;
+                const valid = webFetchRequestSchema.safeParse({
+                    url: request.url(),
+                    mode: 'browser'
+                }).success;
+                if (request.isNavigationRequest() && request.frame() === page.mainFrame() && !valid)
+                    blockedNavigation = true;
+                try {
+                    if (!valid ||
+                        blockedNavigation ||
+                        resourceRequests > 128 ||
+                        ['image', 'media', 'font'].includes(request.resourceType()))
+                        await route.abort();
+                    else
+                        await route.continue();
+                }
+                catch {
+                    // A cancelled or closed page may invalidate an outstanding route.
+                }
+            });
+            const page = await context.newPage();
+            // Playwright routes see only the first request in an HTTP redirect chain.
+            // Chromium interception validates every hop before any redirected request is sent.
+            const cdp = await context.newCDPSession(page);
+            const { frameTree } = await cdp.send('Page.getFrameTree');
+            const mainFrameId = frameTree.frame.id;
+            let navigationRequests = 0;
+            let interceptedRequests = 0;
+            cdp.on('Fetch.requestPaused', (event) => {
+                const valid = webFetchRequestSchema.safeParse({
+                    url: event.request.url,
+                    mode: 'browser'
+                }).success;
+                const mainNavigation = event.resourceType === 'Document' && event.frameId === mainFrameId;
+                if (mainNavigation) {
+                    navigationRequests++;
+                    if (!valid)
+                        navigationFailure = new WebFetchError('MAR_AGENT_TOOL_INPUT_INVALID', 400, 'Page navigation URL is not supported.');
+                    else if (navigationRequests > MAX_REDIRECTS + 1)
+                        navigationFailure = new WebFetchError('MAR_AGENT_WEB_FETCH_UPSTREAM_FAILED', 502, 'Too many web fetch redirects.');
+                }
+                const blocked = !valid || navigationFailure !== undefined || ++interceptedRequests > 128;
+                void cdp
+                    .send(blocked ? 'Fetch.failRequest' : 'Fetch.continueRequest', {
+                    requestId: event.requestId,
+                    ...(blocked ? { errorReason: 'BlockedByClient' } : {})
+                })
+                    .catch(() => {
+                    if (!signal.aborted && !page.isClosed()) {
+                        navigationFailure ??= new WebFetchError('MAR_AGENT_WEB_FETCH_UPSTREAM_FAILED', 502, 'Browser request interception failed.');
+                        cancel();
+                    }
+                });
+            });
+            await cdp.send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] });
+            let navigationResponse;
+            page.on('response', (response) => {
+                if (response.request().isNavigationRequest() &&
+                    response.request().frame() === page.mainFrame())
+                    navigationResponse = response;
+            });
+            context.on('page', (other) => {
+                if (other !== page)
+                    void other.close().catch(() => undefined);
+            });
+            page.on('dialog', (dialog) => {
+                void dialog.dismiss().catch(() => undefined);
+            });
+            const response = await page.goto(input.url, {
+                waitUntil: 'domcontentloaded',
+                timeout: 25_000
+            });
+            if (!response)
+                throw new WebFetchError('MAR_AGENT_WEB_FETCH_UPSTREAM_FAILED', 502, 'Page navigation returned no response.');
+            navigationResponse ??= response;
+            validateResponse(response.status(), (await response.allHeaders())['content-type'] ?? 'text/html');
+            // Wait for visible text to settle, not for long-lived network connections to become idle.
+            const start = Date.now();
+            let previous = '';
+            let changedAt = start;
+            let snapshot;
+            while (Date.now() - start < 5_000) {
+                signal.throwIfAborted();
+                try {
+                    const current = await page.evaluate((maxBytes) => {
+                        const text = document.body?.innerText.trim() ?? '';
+                        const bytes = new TextEncoder().encode(text);
+                        return {
+                            url: location.href,
+                            title: document.title.slice(0, 1_000),
+                            content: new TextDecoder().decode(bytes.subarray(0, maxBytes), {
+                                stream: bytes.length > maxBytes
+                            }),
+                            truncated: bytes.length > maxBytes
+                        };
+                    }, WEB_FETCH_MAX_BYTES);
+                    snapshot = current;
+                }
+                catch (error) {
+                    if (page.isClosed() || signal.aborted || navigationFailure)
+                        throw error;
+                    // A client-side navigation can replace the evaluation context between snapshots.
+                    snapshot = undefined;
+                }
+                const identity = snapshot ? `${snapshot.url}\n${snapshot.content}` : '';
+                if (identity !== previous) {
+                    previous = identity;
+                    changedAt = Date.now();
+                }
+                if (snapshot?.content && Date.now() - start >= 1_000 && Date.now() - changedAt >= 750)
+                    break;
+                await delay(100, undefined, { signal });
+            }
+            signal.throwIfAborted();
+            if (navigationFailure)
+                throw navigationFailure;
+            const finalUrl = page.url();
+            if (blockedNavigation ||
+                !webFetchRequestSchema.safeParse({ url: finalUrl, mode: 'browser' }).success)
+                throw new WebFetchError('MAR_AGENT_TOOL_INPUT_INVALID', 400, 'Page navigation URL is not supported.');
+            if (!snapshot?.content || snapshot.url !== finalUrl)
+                throw new WebFetchError('MAR_AGENT_WEB_FETCH_EMPTY_CONTENT', 422, 'The rendered page has no readable text.');
+            const contentType = ((await navigationResponse.allHeaders())['content-type'] ?? 'text/html').slice(0, 256);
+            validateResponse(navigationResponse.status(), contentType);
+            return {
+                content: snapshot.content,
+                data: {
+                    url: finalUrl,
+                    mode: 'browser',
+                    status: navigationResponse.status(),
+                    contentType,
+                    title: snapshot.title
+                },
+                truncated: snapshot.truncated
+            };
+        }
+        catch (error) {
+            if (navigationFailure)
+                throw navigationFailure;
+            throw error;
+        }
+        finally {
+            signal.removeEventListener('abort', cancel);
+            await context?.close().catch(() => undefined);
+            await browser?.close().catch(() => undefined);
+            this.#browserRequests--;
+        }
+    }
+}
+function readableContentType(contentType) {
+    return /^(?:text\/|application\/(?:[\w.+-]+\+)?(?:json|xml)(?:[;\s]|$))/iu.test(contentType);
+}
+function validateResponse(status, contentType) {
+    if (status < 200 || status >= 300)
+        throw new WebFetchError('MAR_AGENT_WEB_FETCH_UPSTREAM_FAILED', 502, 'Web fetch upstream returned an HTTP error.', { upstreamStatus: status });
+    if (!readableContentType(contentType))
+        throw new WebFetchError('MAR_AGENT_WEB_FETCH_UNSUPPORTED_CONTENT', 415, 'Response is not readable text.');
+}
+function requestHttp(url, signal, allowUntrustedTls) {
+    return new Promise((resolve, reject) => {
+        const request = (url.protocol === 'https:' ? httpsRequest : httpRequest)(url, {
+            signal,
+            headers: {
+                accept: 'text/html,application/json,text/plain;q=0.9,*/*;q=0.1',
+                'accept-encoding': 'identity',
+                'user-agent': 'MyAgentRoam/0.9'
+            },
+            ...(url.protocol === 'https:' ? { rejectUnauthorized: !allowUntrustedTls } : {})
+        }, resolve);
+        request.once('error', reject);
+        request.end();
+    });
+}

package/dist/service/web-tool-service.js

@@ -0,0 +1,72 @@
+import { MarAgentError } from '@myagentroam/agent';
+import { readWebSearchError } from './web-search-error.js';
+import { WebFetchService } from './web-fetch-service.js';
+import { webFetchResultSchema } from './web-fetch-contracts.js';
+/** Owns Node web reads and the authenticated Server search adapter. */
+export class WebToolService {
+    #config;
+    #request;
+    #fetcher;
+    constructor(config, request = fetch) {
+        this.#config = config;
+        this.#request = request;
+        this.#fetcher = new WebFetchService();
+    }
+    webSearch(input, signal) {
+        return this.#execute(input, signal);
+    }
+    webFetch = async (input, signal, allowUntrustedTls) => {
+        const result = await this.#fetcher.fetch(input, signal, {
+            ...(allowUntrustedTls === undefined ? {} : { allowUntrustedTls })
+        });
+        const parsed = webFetchResultSchema.safeParse(result);
+        if (!parsed.success)
+            throw new MarAgentError('MAR_AGENT_WEB_FETCH_FAILED', 'Web fetch returned an invalid result.');
+        return parsed.data;
+    };
+    close() {
+        return this.#fetcher.close();
+    }
+    async #execute(input, signal) {
+        const config = this.#config();
+        if (config?.nodeId === undefined || config.credential === undefined)
+            throw new Error('NODE_UNAUTHENTICATED');
+        try {
+            const response = await this.#request(`${config.serverUrl.replace(/\/$/u, '')}/api/node-tools/web-search`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-mar-node-id': config.nodeId,
+                    authorization: `Bearer ${config.credential}`
+                },
+                body: JSON.stringify(input),
+                signal
+            });
+            if (!response.ok)
+                throw await readWebSearchError(response);
+            let result;
+            try {
+                result = await response.json();
+            }
+            catch {
+                throw invalidResult();
+            }
+            if (result === null || typeof result !== 'object')
+                throw invalidResult();
+            const content = JSON.stringify(result);
+            if (content === undefined)
+                throw invalidResult();
+            return { content, data: result };
+        }
+        catch (error) {
+            if (error instanceof MarAgentError || signal.aborted)
+                throw error;
+            throw new MarAgentError('MAR_AGENT_WEB_SEARCH_FAILED', 'Web search failed.', {
+                cause: error
+            });
+        }
+    }
+}
+function invalidResult() {
+    return new MarAgentError('MAR_AGENT_WEB_SEARCH_FAILED', 'Web search returned an invalid result.');
+}

package/dist/service.js

@@ -1,23 +1,32 @@
 import { chmod, mkdir, rm, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
-export function systemdUnit(executable, configPath, entrypoint, writablePaths = []) {
+export function browserCachePath(dataDirectory) {
+    const configured = process.env['PLAYWRIGHT_BROWSERS_PATH'];
+    return configured === '0' ? '0' : resolve(configured ?? resolve(dataDirectory, 'web-browsers'));
+}
+export function systemdUnit(executable, configPath, entrypoint, writablePaths = [], browserPath) {
     const command = [
         escapeSystemd(executable),
         ...(entrypoint === undefined ? [] : [escapeSystemd(entrypoint)])
     ].join(' ');
-    const readWritePaths = writablePaths.map((path) => escapeSystemd(resolve(path))).join(' ');
-    return `[Unit]\nDescription=MyAgentRoam Node\nAfter=network-online.target\n\n[Service]\nType=simple\nUser=mar-node\nNoNewPrivileges=true\nPrivateTmp=true\nProtectSystem=strict\n${readWritePaths.length === 0 ? '' : `ReadWritePaths=${readWritePaths}\n`}ExecStart=${command} supervise --config ${escapeSystemd(configPath)}\nRestart=on-failure\n\n[Install]\nWantedBy=multi-user.target\n`;
+    const readWritePaths = [
+        ...writablePaths,
+        ...(browserPath === undefined || browserPath === '0' ? [] : [browserPath])
+    ]
+        .map((path) => escapeSystemd(resolve(path)))
+        .join(' ');
+    return `[Unit]\nDescription=MyAgentRoam Node\nAfter=network-online.target\n\n[Service]\nType=simple\nUser=mar-node\nNoNewPrivileges=true\nPrivateTmp=true\nProtectSystem=strict\n${readWritePaths.length === 0 ? '' : `ReadWritePaths=${readWritePaths}\n`}${browserPath === undefined ? '' : `Environment=${escapeSystemd(`PLAYWRIGHT_BROWSERS_PATH=${browserPath}`)}\n`}ExecStart=${command} supervise --config ${escapeSystemd(configPath)}\nRestart=on-failure\n\n[Install]\nWantedBy=multi-user.target\n`;
 }
-export function windowsServiceDefinition(executable, configPath, entrypoint) {
+export function windowsServiceDefinition(executable, configPath, entrypoint, browserPath) {
     return JSON.stringify({
         serviceName: 'MyAgentRoamNode',
         displayName: 'MyAgentRoam Node',
-        binaryPath: `"${executable}"${entrypoint === undefined ? '' : ` "${entrypoint}"`} supervise --config "${configPath}"`,
+        binaryPath: `"${executable}"${entrypoint === undefined ? '' : ` "${entrypoint}"`} supervise --config "${configPath}"${browserPath === undefined ? '' : ` --browser-cache "${browserPath}"`}`,
         startType: 'auto',
         account: 'LocalService'
     }, undefined, 2);
 }
-export function launchdServiceDefinition(executable, configPath, entrypoint) {
+export function launchdServiceDefinition(executable, configPath, entrypoint, browserPath) {
     const argumentsList = [
         executable,
         ...(entrypoint === undefined ? [] : [entrypoint]),
@@ -41,6 +50,7 @@ ${argumentsList}
   <dict>
     <key>PATH</key>
     <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+${browserPath === undefined ? '' : `    <key>PLAYWRIGHT_BROWSERS_PATH</key>\n    <string>${escapeXml(browserPath)}</string>`}
   </dict>
   <key>RunAtLoad</key>
   <true/>
@@ -50,13 +60,13 @@ ${argumentsList}
 </plist>
 `;
 }
-export async function writeServiceDefinition(outputPath, executable, configPath, platform = process.platform, entrypoint, writablePaths = []) {
+export async function writeServiceDefinition(outputPath, executable, configPath, platform = process.platform, entrypoint, writablePaths = [], browserPath) {
     const contents = platform === 'linux'
-        ? systemdUnit(executable, configPath, entrypoint, writablePaths)
+        ? systemdUnit(executable, configPath, entrypoint, writablePaths, browserPath)
         : platform === 'win32'
-            ? windowsServiceDefinition(executable, configPath, entrypoint)
+            ? windowsServiceDefinition(executable, configPath, entrypoint, browserPath)
             : platform === 'darwin'
-                ? launchdServiceDefinition(executable, configPath, entrypoint)
+                ? launchdServiceDefinition(executable, configPath, entrypoint, browserPath)
                 : (() => {
                     throw new Error('NODE_PLATFORM_UNSUPPORTED');
                 })();

package/dist/supervisor.js

@@ -60,6 +60,15 @@ export async function superviseNode(configPath, bootstrapEntrypoint) {
             }
             if (rebuildResult.code !== 0)
                 throw new Error('NODE_UPGRADE_NATIVE_REBUILD_FAILED');
+            const browserInstall = await runProcess(process.execPath, [
+                resolve(prefix, 'node_modules', '@myagentroam', 'node', 'scripts', 'install-web-browser.mjs')
+            ], true);
+            if (browserInstall.signalled) {
+                stopping = true;
+                throw new Error('NODE_UPGRADE_INSTALL_INTERRUPTED');
+            }
+            if (browserInstall.code !== 0)
+                throw new Error('NODE_UPGRADE_BROWSER_INSTALL_FAILED');
             const nextEntrypoint = resolve(prefix, 'node_modules', '@myagentroam', 'node', 'dist', 'main.js');
             await access(nextEntrypoint);
             await writeAtomic(activePath, `${nextEntrypoint}\n`);

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.9.152",
+  "version": "0.9.154",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
   "files": [
     "dist/**/*.js",
+    "scripts/install-web-browser.mjs",
     "vendor/ripgrep/**/*",
     "vendor/ctags/**/*",
     "LICENSE",
@@ -32,17 +33,19 @@
     "node-datachannel": "0.33.4",
     "node-pty": "1.1.0",
     "npm": "11.12.1",
+    "playwright": "1.62.1",
     "ws": "^8.21.3",
     "zod": "4.4.3",
+    "@myagentroam/agent": "0.9.154",
+    "@myagentroam/protocol": "0.9.154",
     "@myagentroam/marctl": "0.9.120",
-    "@myagentroam/protocol": "0.9.152",
-    "@myagentroam/code-navigation": "0.9.129",
-    "@myagentroam/agent": "0.9.152"
+    "@myagentroam/code-navigation": "0.9.129"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"
   },
   "scripts": {
+    "postinstall": "node scripts/install-web-browser.mjs",
     "build": "node ../scripts/clean-build-output.mjs dist && tsc -p tsconfig.json",
     "stage:computer-use-runtime": "node ../scripts/stage-computer-use-runtime.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.tests.json --noEmit",

package/scripts/install-web-browser.mjs

@@ -0,0 +1,62 @@
+import { access, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { chromium } from 'playwright';
+
+/** Download browser binaries only; operating-system package installation is never implicit. */
+export async function installWebBrowser(options = {}) {
+  const environment = options.environment ?? process.env;
+  if (['1', 'true'].includes(environment.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD)) return 'skipped';
+  const exists =
+    options.exists ??
+    (async (path) => {
+      if (!(await stat(path)).isFile()) throw new Error('Browser executable is not a regular file');
+      await access(path, constants.X_OK);
+    });
+  let cached = false;
+  try {
+    await exists(chromium.executablePath());
+    cached = true;
+  } catch {
+    // The exact browser revision is absent or unusable.
+  }
+  const require = createRequire(import.meta.url);
+  const cli = resolve(dirname(require.resolve('playwright/package.json')), 'cli.js');
+  const run =
+    options.run ??
+    ((command, args) =>
+      spawnSync(command, args, {
+        stdio: 'inherit',
+        env: environment,
+        timeout: 300_000
+      }));
+  const result = run(process.execPath, [cli, 'install', 'chromium', '--no-shell']);
+  if (result.error || result.signal || result.status !== 0)
+    throw new Error(
+      'NODE_WEB_BROWSER_INSTALL_FAILED: Chromium download failed. Check network access or preinstall the matching Playwright Chromium runtime.'
+    );
+  // Register this package with Playwright's cache GC even when binaries already exist.
+  try {
+    await exists(chromium.executablePath());
+  } catch {
+    throw new Error(
+      'NODE_WEB_BROWSER_INSTALL_FAILED: Chromium executable is unavailable or not executable after preparation.'
+    );
+  }
+  return cached ? 'cached' : 'installed';
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    const outcome = await installWebBrowser();
+    process.stdout.write(`Node Chromium preparation: ${outcome}.\n`);
+  } catch (error) {
+    process.stderr.write(
+      `${error instanceof Error ? error.message : 'NODE_WEB_BROWSER_INSTALL_FAILED'}\n`
+    );
+    process.exitCode = 1;
+  }
+}