@minionry/minion 0.7.36

package/dist/server/services/browser/claude-reasoner.js

@@ -0,0 +1,669 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { spawn } from 'node:child_process';
+import { ResilientRunner } from '../../cli/headless/resilient-runner.js';
+import { resolveClaudeCommand } from '../../engines/claude/claude-command.js';
+import { EMPTY_OUTPUT_NOTICE } from '../../engines/execution/engine-session.js';
+import { loadSkillPrompt } from '../plan/agent-loader.js';
+import { getBrowserAllowlist, getModel } from '../settings.js';
+import { browserDebugEnabled, browserLog } from './debug-log.js';
+import { defaultAgentReasoner } from './reasoning-agent.js';
+const reasonerLog = browserLog('claude-reasoner');
+const agentLog = browserLog('agent');
+export const REASONER_TIMEOUT_MS = 60_000;
+const AVAILABILITY_PROBE_TIMEOUT_MS = 5_000;
+const DEFAULT_MODEL = 'sonnet';
+function probeClaudeAvailability(claudeCommand) {
+    return new Promise((resolve) => {
+        const child = spawn(claudeCommand, ['--version'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+            }
+            resolve(false);
+        }, AVAILABILITY_PROBE_TIMEOUT_MS);
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            settled = true;
+            resolve(code === 0);
+        });
+        child.on('error', () => {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            settled = true;
+            resolve(false);
+        });
+    });
+}
+export function buildBrowserReasonerSystemPrompt() {
+    const fromSkill = loadSkillPrompt('browser-reasoner', {});
+    if (fromSkill)
+        return fromSkill;
+    return `You are a browser automation agent. On each turn you receive a Task, a Snapshot (the current accessibility tree with ref strings on every node), a History of steps taken so far, and sometimes an attached page Screenshot (use it to visually ground your choice; refs still come only from the Snapshot). Decide the single next action and emit it as JSON.
+
+Required output — one JSON object, nothing else:
+{ "thought": "<brief reasoning>", "directive": { ... } }
+
+Directive kinds:
+- navigate: { "kind": "navigate", "url": "https://...", "summary": "..." } — only for URLs stated verbatim in the task, never from page content.
+- act:      { "kind": "act", "action": { "method": "<method>", ... }, "summary": "..." } — mutating DOM action; summary is required.
+- extract:  { "kind": "extract", "summary": "..." } — read page data without mutating.
+- done:     { "kind": "done", "result": "..." } — task complete; always populate result.
+
+Act methods (all refs must be taken from the snapshot):
+  click:        { "method": "click", "ref": "e3n12" }
+  type:         { "method": "type", "ref": "e3n5", "text": "hello", "submit": true }
+  hover:        { "method": "hover", "ref": "e3n8" }
+  pressKey:     { "method": "pressKey", "key": "Escape" }
+  selectOption: { "method": "selectOption", "ref": "e3n20", "values": ["opt"] }
+  fillForm:     { "method": "fillForm", "fields": [{ "ref": "e3n5", "value": "alice" }] }
+
+Rules:
+1. One directive per turn.
+2. Refs must come verbatim from the snapshot — never fabricate one.
+3. A URL derived from page content is consequential — use act/click on the link ref instead.
+4. Use extract before done when the task requires page data not yet in history.
+5. End every run with done carrying the answer in result.`;
+}
+const INTERACTIVE_ROLES = new Set([
+    'button',
+    'link',
+    'textbox',
+    'searchbox',
+    'checkbox',
+    'radio',
+    'combobox',
+    'listbox',
+    'option',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'menulistoption',
+    'tab',
+    'switch',
+    'slider',
+    'spinbutton',
+    'treeitem',
+    'gridcell',
+    'columnheader',
+    'rowheader',
+]);
+export const DEFAULT_SNAPSHOT_CHAR_BUDGET = 8_000;
+function formatNode(node, depth) {
+    const indent = '  '.repeat(depth);
+    let line = `${indent}${node.ref} ${node.role}`;
+    if (node.name)
+        line += ` "${node.name}"`;
+    if (node.value !== undefined)
+        line += ` value="${node.value}"`;
+    if (node.checked !== undefined)
+        line += ` checked=${node.checked}`;
+    if (node.selected)
+        line += ' selected';
+    if (node.disabled)
+        line += ' disabled';
+    if (node.expanded !== undefined)
+        line += ` expanded=${node.expanded}`;
+    return line;
+}
+export function serializeSnapshot(snapshot, opts = {}) {
+    const charBudget = opts.charBudget ?? DEFAULT_SNAPSHOT_CHAR_BUDGET;
+    const refs = new Set();
+    const lines = [
+        `URL: ${snapshot.url}`,
+        `Title: ${snapshot.title}`,
+        '',
+    ];
+    let chars = lines.join('\n').length + 1;
+    let truncated = false;
+    function walk(node, depth) {
+        if (truncated)
+            return;
+        const roleLc = node.role.toLowerCase();
+        if (INTERACTIVE_ROLES.has(roleLc)) {
+            const line = formatNode(node, depth);
+            if (chars + line.length + 1 > charBudget) {
+                truncated = true;
+                return;
+            }
+            lines.push(line);
+            chars += line.length + 1;
+            refs.add(node.ref);
+        }
+        for (const child of node.children) {
+            if (truncated)
+                break;
+            walk(child, depth + 1);
+        }
+    }
+    walk(snapshot.root, 0);
+    if (truncated) {
+        lines.push('... [snapshot truncated: char budget exceeded]');
+    }
+    return { text: lines.join('\n'), refs };
+}
+export function buildUserMessage(input) {
+    const { task, snapshot, history, currentGoal, screenshot } = input;
+    const { text: snapshotText } = serializeSnapshot(snapshot);
+    const historyText = history.length === 0
+        ? '(none)'
+        : history
+            .map((h, i) => `${i + 1}. [${h.phase}] ${h.detail}`)
+            .join('\n');
+    return [
+        '## Task',
+        task,
+        ...(currentGoal !== undefined
+            ? [
+                '',
+                '## Current sub-goal',
+                currentGoal,
+                'Work only on this sub-goal. Emit a plain `done` (with a one-line result) the moment it is complete — even if the overall Task has later sub-goals.',
+            ]
+            : []),
+        '',
+        '## Current page',
+        snapshotText,
+        ...(screenshot
+            ? [
+                '',
+                '## Screenshot',
+                'A screenshot of the current page is attached. Use it to visually locate the right element or understand content the accessibility snapshot misses (canvas, images, layout). Every ref you emit must still come verbatim from the snapshot above.',
+            ]
+            : []),
+        '',
+        '## History',
+        historyText,
+        '',
+        'Emit the next directive as JSON now.',
+    ].join('\n');
+}
+function extractJsonObject(raw) {
+    const jsonFenced = raw.match(/```json\s*([\s\S]*?)```/);
+    if (jsonFenced)
+        return jsonFenced[1].trim();
+    const anyFenced = raw.match(/```[^\n]*\n([\s\S]*?)```/);
+    if (anyFenced)
+        return anyFenced[1].trim();
+    const braceMatch = raw.match(/\{[\s\S]*\}/);
+    if (braceMatch)
+        return braceMatch[0].trim();
+    return raw.trim();
+}
+const ACTION_VALIDATORS = {
+    click: (a) => {
+        if (typeof a.ref !== 'string' || !a.ref)
+            throw new Error('click requires ref');
+        return { method: 'click', ref: a.ref };
+    },
+    type: (a) => {
+        if (typeof a.ref !== 'string' || !a.ref)
+            throw new Error('type requires ref');
+        if (typeof a.text !== 'string')
+            throw new Error('type requires text');
+        return { method: 'type', ref: a.ref, text: a.text, ...(a.submit !== undefined ? { submit: Boolean(a.submit) } : {}) };
+    },
+    hover: (a) => {
+        if (typeof a.ref !== 'string' || !a.ref)
+            throw new Error('hover requires ref');
+        return { method: 'hover', ref: a.ref };
+    },
+    pressKey: (a) => {
+        if (typeof a.key !== 'string' || !a.key)
+            throw new Error('pressKey requires key');
+        return { method: 'pressKey', key: a.key };
+    },
+    selectOption: (a) => {
+        if (typeof a.ref !== 'string' || !a.ref)
+            throw new Error('selectOption requires ref');
+        if (!Array.isArray(a.values) || !a.values.every((v) => typeof v === 'string'))
+            throw new Error('selectOption requires values: string[]');
+        return { method: 'selectOption', ref: a.ref, values: a.values };
+    },
+    fillForm: (a) => {
+        if (!Array.isArray(a.fields))
+            throw new Error('fillForm requires fields array');
+        const fields = a.fields.map((f) => {
+            if (!f || typeof f !== 'object')
+                throw new Error('fillForm field must be an object');
+            const ff = f;
+            if (typeof ff.ref !== 'string' || !ff.ref)
+                throw new Error('fillForm field requires ref');
+            if (typeof ff.value !== 'string')
+                throw new Error('fillForm field requires value');
+            return { ref: ff.ref, value: ff.value };
+        });
+        return { method: 'fillForm', fields };
+    },
+};
+function validateAction(raw) {
+    if (!raw || typeof raw !== 'object')
+        throw new Error('action must be an object');
+    const a = raw;
+    const method = a.method;
+    const validator = ACTION_VALIDATORS[method];
+    if (!validator)
+        throw new Error(`unknown act method "${method}"`);
+    return validator(a);
+}
+function validateDirectiveObject(raw) {
+    const kind = raw.kind;
+    switch (kind) {
+        case 'navigate': {
+            if (typeof raw.url !== 'string' || !raw.url)
+                throw new Error('navigate requires url');
+            return { kind: 'navigate', url: raw.url, ...(typeof raw.summary === 'string' ? { summary: raw.summary } : {}) };
+        }
+        case 'act': {
+            const action = validateAction(raw.action);
+            const summary = typeof raw.summary === 'string' ? raw.summary : '';
+            return { kind: 'act', action, summary };
+        }
+        case 'extract':
+            return { kind: 'extract', ...(typeof raw.summary === 'string' ? { summary: raw.summary } : {}) };
+        case 'done':
+            return { kind: 'done', ...(raw.result !== undefined ? { result: String(raw.result) } : {}) };
+        default:
+            throw new Error(`unknown directive kind "${kind}"`);
+    }
+}
+function getDirectiveRefs(directive) {
+    if (directive.kind !== 'act')
+        return [];
+    const action = directive.action;
+    switch (action.method) {
+        case 'click': return [action.ref];
+        case 'type': return [action.ref];
+        case 'hover': return [action.ref];
+        case 'pressKey': return [];
+        case 'selectOption': return [action.ref];
+        case 'fillForm': return action.fields.map((f) => f.ref);
+    }
+}
+function firstInvalidRef(directive, validRefs) {
+    if (validRefs.size === 0)
+        return null;
+    for (const ref of getDirectiveRefs(directive)) {
+        if (!validRefs.has(ref))
+            return ref;
+    }
+    return null;
+}
+function isEmptyModelOutput(rawText) {
+    const trimmed = rawText?.trim();
+    return !trimmed || trimmed === EMPTY_OUTPUT_NOTICE;
+}
+export function parseDirective(rawText, validRefs) {
+    try {
+        if (isEmptyModelOutput(rawText)) {
+            return { kind: 'done', result: 'browser-reasoner: empty response from model' };
+        }
+        const jsonStr = extractJsonObject(rawText);
+        let parsed;
+        try {
+            parsed = JSON.parse(jsonStr);
+        }
+        catch {
+            return { kind: 'done', result: `browser-reasoner: failed to parse JSON from model response` };
+        }
+        if (!parsed || typeof parsed !== 'object') {
+            return { kind: 'done', result: 'browser-reasoner: parsed value is not an object' };
+        }
+        const rawDirective = parsed.directive;
+        if (!rawDirective || typeof rawDirective !== 'object' || Array.isArray(rawDirective)) {
+            return { kind: 'done', result: 'browser-reasoner: response missing "directive" field' };
+        }
+        const directive = validateDirectiveObject(rawDirective);
+        const invalidRef = firstInvalidRef(directive, validRefs);
+        if (invalidRef !== null) {
+            return { kind: 'done', result: `browser-reasoner: ref "${invalidRef}" is not present in the current snapshot` };
+        }
+        return directive;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { kind: 'done', result: `browser-reasoner: ${msg}` };
+    }
+}
+export function parseReasonerResponse(raw) {
+    return parseDirective(raw, new Set());
+}
+async function _runResilient(prompt, opts) {
+    const { model, engineId, effortLevel, timeoutMs, workingDir, imageAttachments } = opts;
+    const runner = new ResilientRunner({
+        workingDir,
+        prompt,
+        policy: 'NONE',
+        inferenceOnly: true,
+        effortLevel: effortLevel ?? 'auto',
+        ...(imageAttachments && imageAttachments.length > 0 ? { imageAttachments } : {}),
+        ...(model ? { model } : {}),
+        ...(engineId ? { engineId } : {}),
+        stallWarningMs: Math.max(1_000, Math.floor(timeoutMs / 2)),
+        stallKillMs: timeoutMs,
+        stallHardCapMs: timeoutMs,
+        verbose: false,
+        logLabel: 'browser-reasoner',
+        outputCallback: () => { },
+    });
+    const result = await runner.run();
+    return result.assistantResponse ?? '';
+}
+function navIsUserDerived(url, task) {
+    const taskLc = task.toLowerCase();
+    if (taskLc.includes(url.toLowerCase()))
+        return true;
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        return host.length > 0 && taskLc.includes(host);
+    }
+    catch {
+        return false;
+    }
+}
+const SECOND_LEVEL_REGISTRY_LABELS = new Set(['co', 'com', 'net', 'org', 'ac', 'gov', 'edu']);
+function navIsSiteNamed(url, task) {
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        const taskLc = task.toLowerCase();
+        return registrableLabels(host).some((label) => taskNamesLabel(taskLc, label));
+    }
+    catch {
+        return false;
+    }
+}
+function registrableLabels(host) {
+    const labels = host.split('.').filter((l) => l.length > 0);
+    if (labels[0] === 'www')
+        labels.shift();
+    if (labels.length < 2)
+        return [];
+    const secondLevel = labels[labels.length - 2];
+    const site = SECOND_LEVEL_REGISTRY_LABELS.has(secondLevel) && labels.length >= 3
+        ? labels[labels.length - 3]
+        : secondLevel;
+    return site.length >= 3 ? [site] : [];
+}
+function taskNamesLabel(taskLc, label) {
+    const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`).test(taskLc);
+}
+function hostOf(value) {
+    try {
+        const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `https://${value}`;
+        return new URL(withScheme).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+function originIsAllowlisted(url, allowlist) {
+    const host = hostOf(url);
+    if (!host)
+        return false;
+    if (host === 'localhost' || host === '127.0.0.1' || host.endsWith('.localhost'))
+        return true;
+    for (const entry of allowlist) {
+        const entryHost = hostOf(entry);
+        if (!entryHost)
+            continue;
+        if (host === entryHost || host.endsWith(`.${entryHost}`))
+            return true;
+    }
+    return false;
+}
+function classifyNavigate(url, task, allowlist) {
+    if (navIsUserDerived(url, task))
+        return 'trusted';
+    if (navIsSiteNamed(url, task))
+        return 'allowlisted';
+    if (originIsAllowlisted(url, allowlist))
+        return 'allowlisted';
+    return 'blocked';
+}
+function directiveRejection(directive, validRefs, task, allowlist) {
+    if (directive.kind === 'act' && validRefs.size > 0) {
+        for (const ref of getDirectiveRefs(directive)) {
+            if (!validRefs.has(ref)) {
+                return `ref "${ref}" is not present in the current snapshot — choose a ref from the page above or use extract`;
+            }
+        }
+        return null;
+    }
+    if (directive.kind === 'navigate' && classifyNavigate(directive.url, task, allowlist) === 'blocked') {
+        return `navigation to "${directive.url}" is derived from page content and is outside the origin allowlist — click the link's ref instead of navigating`;
+    }
+    return null;
+}
+function annotateNavigate(directive, task, allowlist) {
+    if (directive.kind !== 'navigate')
+        return directive;
+    if (classifyNavigate(directive.url, task, allowlist) !== 'allowlisted')
+        return directive;
+    const tag = '[content-derived: allowlisted, treat as consequential]';
+    const summary = directive.summary ? `${directive.summary} ${tag}` : tag;
+    return { ...directive, summary };
+}
+function logPrompt(fullPrompt) {
+    if (!browserDebugEnabled)
+        return;
+    const promptChars = fullPrompt.length;
+    const promptTokens = Math.ceil(promptChars / 4);
+    agentLog('prompt', `chars=${promptChars} tokens~${promptTokens}`);
+}
+function logResponse(raw) {
+    if (!browserDebugEnabled)
+        return;
+    const responseChars = raw.length;
+    const truncated = responseChars > 500 ? `${raw.slice(0, 500)}... [truncated ${responseChars - 500} chars]` : raw;
+    agentLog('response', truncated);
+}
+function screenshotAttachments(screenshot) {
+    if (!screenshot)
+        return undefined;
+    return [
+        {
+            fileName: `page-screenshot.${screenshot.format}`,
+            filePath: '',
+            content: screenshot.data,
+            isImage: true,
+            mimeType: screenshot.format === 'jpeg' ? 'image/jpeg' : 'image/png',
+        },
+    ];
+}
+async function inferWithEmptyRetry(inferOnce, baseSuffix) {
+    const first = await inferOnce(baseSuffix);
+    if (!isEmptyModelOutput(first.raw))
+        return first;
+    reasonerLog('empty-turn', 'model produced no visible output — re-prompting once');
+    return inferOnce(`${baseSuffix}\n\n## Correction\nYour previous turn produced no visible output. Respond now with ONLY the required JSON object ({ "thought": ..., "directive": ... }) — no other text, no hidden reasoning.`);
+}
+async function inferTurn(config, suffix, imageAttachments) {
+    const { staticPrefix, infer, model, engineId, effortLevel, claudeCommand, timeoutMs, workingDir } = config;
+    const fullPrompt = `${staticPrefix}\n${suffix}`;
+    logPrompt(fullPrompt);
+    const raw = await infer(fullPrompt, {
+        ...(model !== undefined ? { model } : {}),
+        ...(engineId ? { engineId } : {}),
+        ...(effortLevel ? { effortLevel } : {}),
+        claudeCommand,
+        timeoutMs,
+        workingDir,
+        ...(imageAttachments && imageAttachments.length > 0 ? { imageAttachments } : {}),
+    });
+    logResponse(raw);
+    const directive = parseDirective(raw, new Set());
+    if (browserDebugEnabled) {
+        agentLog('directive', JSON.stringify(directive));
+    }
+    return { raw, directive };
+}
+export function createClaudeReasoner(opts = {}) {
+    const claudeCommand = opts.claudeCommand ?? resolveClaudeCommand();
+    const timeoutMs = opts.timeoutMs ?? REASONER_TIMEOUT_MS;
+    const workingDir = opts.workingDir ?? process.cwd();
+    const engineId = opts.engine;
+    const effortLevel = opts.effortLevel;
+    const isClaudeEngine = (engineId ?? 'claude-code') === 'claude-code';
+    const model = opts.model ?? (isClaudeEngine ? (opts.useSettingsModel ? getModel() : DEFAULT_MODEL) : undefined);
+    const infer = opts.infer ?? _runResilient;
+    const fallback = opts.fallback ?? defaultAgentReasoner;
+    const probe = opts.probe ??
+        (isClaudeEngine ? () => probeClaudeAvailability(claudeCommand) : () => Promise.resolve(true));
+    const getAllowlist = opts.getAllowlist ?? getBrowserAllowlist;
+    const staticPrefix = `${buildBrowserReasonerSystemPrompt()}\n\n---\n`;
+    let probePromise = null;
+    return async (input) => {
+        try {
+            if (probePromise === null) {
+                probePromise = probe();
+            }
+            const available = await probePromise;
+            if (!available) {
+                reasonerLog('fallback', `claude binary unavailable (cmd=${claudeCommand}) — using fallback reasoner`);
+                return fallback(input);
+            }
+            const { refs } = serializeSnapshot(input.snapshot);
+            const allowlist = getAllowlist();
+            const baseSuffix = buildUserMessage(input);
+            const turnAttachments = screenshotAttachments(input.screenshot);
+            const inferOnce = (suffix) => inferTurn({
+                staticPrefix,
+                infer,
+                model,
+                ...(engineId ? { engineId } : {}),
+                ...(effortLevel ? { effortLevel } : {}),
+                claudeCommand,
+                timeoutMs,
+                workingDir,
+            }, suffix, turnAttachments);
+            let directive = (await inferWithEmptyRetry(inferOnce, baseSuffix)).directive;
+            let rejection = directiveRejection(directive, refs, input.task, allowlist);
+            if (rejection) {
+                reasonerLog('reprompt', rejection);
+                const corrected = `${baseSuffix}\n\n## Correction\nYour previous directive was rejected: ${rejection}\nEmit a corrected directive as JSON now. Use only refs present in the snapshot above; for any destination not named in the Task, click the link's ref instead of navigating.`;
+                directive = (await inferOnce(corrected)).directive;
+                rejection = directiveRejection(directive, refs, input.task, allowlist);
+                if (rejection) {
+                    return { kind: 'done', result: `browser-reasoner: ${rejection}` };
+                }
+            }
+            return annotateNavigate(directive, input.task, allowlist);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            reasonerLog('error', msg);
+            return { kind: 'done', result: `browser-reasoner: ${msg}` };
+        }
+    };
+}
+export const PLANNER_MAX_GOALS = 8;
+export function buildBrowserPlannerSystemPrompt() {
+    const fromSkill = loadSkillPrompt('browser-planner', {});
+    if (fromSkill)
+        return fromSkill;
+    return `You are the PLANNER for a browser automation agent. Decompose the user's Task into an ordered list of high-level sub-goals that an executor will carry out one at a time.
+
+Required output — one JSON object, nothing else:
+{ "thought": "<brief reasoning>", "plan": ["<sub-goal 1>", "<sub-goal 2>", ...] }
+
+Rules:
+1. Each sub-goal is ONE short, page-independent instruction (e.g. "navigate to google.com", "type 'cat' in the search box and submit", "report the top results"). 2 to ${PLANNER_MAX_GOALS} sub-goals.
+2. Do NOT reference element ids/refs or invent selectors — the executor sees the live page and picks those.
+3. Do NOT invent URLs or hostnames that are not stated in the Task. Only include a "navigate to <url>" sub-goal when that URL/host appears in the Task itself.
+4. The final sub-goal should report or confirm the outcome the Task asked for.
+5. Keep it minimal — no steps unrelated to the Task.`;
+}
+function buildPlannerUserMessage(input) {
+    const lines = ['## Task', input.task];
+    if (input.snapshot) {
+        const { text } = serializeSnapshot(input.snapshot);
+        lines.push('', '## Current page', text);
+    }
+    lines.push('', 'Emit the plan as JSON now.');
+    return lines.join('\n');
+}
+export function parsePlan(raw, max = PLANNER_MAX_GOALS) {
+    try {
+        if (!raw?.trim())
+            return [];
+        const parsed = JSON.parse(extractJsonObject(raw));
+        const arr = parsed?.plan;
+        if (!Array.isArray(arr))
+            return [];
+        const goals = [];
+        for (const item of arr) {
+            if (typeof item !== 'string')
+                continue;
+            const g = item.trim();
+            if (g && !goals.includes(g))
+                goals.push(g);
+            if (goals.length >= max)
+                break;
+        }
+        return goals;
+    }
+    catch {
+        return [];
+    }
+}
+export function createClaudePlanner(opts = {}) {
+    const claudeCommand = opts.claudeCommand ?? resolveClaudeCommand();
+    const timeoutMs = opts.timeoutMs ?? REASONER_TIMEOUT_MS;
+    const workingDir = opts.workingDir ?? process.cwd();
+    const engineId = opts.engine;
+    const isClaudeEngine = (engineId ?? 'claude-code') === 'claude-code';
+    const model = opts.model ?? (isClaudeEngine ? (opts.useSettingsModel ? getModel() : DEFAULT_MODEL) : undefined);
+    const infer = opts.infer ?? _runResilient;
+    const probe = opts.probe ??
+        (isClaudeEngine ? () => probeClaudeAvailability(claudeCommand) : () => Promise.resolve(true));
+    const maxGoals = opts.maxGoals ?? PLANNER_MAX_GOALS;
+    const fallback = opts.fallback ?? ((input) => [input.task]);
+    const staticPrefix = `${buildBrowserPlannerSystemPrompt()}\n\n---\n`;
+    const inferOpts = inferenceOptions({ model, engineId, effortLevel: opts.effortLevel }, { claudeCommand, timeoutMs, workingDir });
+    let probePromise = null;
+    return async (input) => {
+        try {
+            if (probePromise === null)
+                probePromise = probe();
+            if (!(await probePromise)) {
+                reasonerLog('planner.fallback', `claude unavailable (cmd=${claudeCommand}) — single-goal plan`);
+                return fallback(input);
+            }
+            const fullPrompt = `${staticPrefix}\n${buildPlannerUserMessage(input)}`;
+            const raw = await infer(fullPrompt, inferOpts);
+            const goals = parsePlan(raw, maxGoals);
+            logPlannerDebug(raw, goals);
+            return goals.length > 0 ? goals : fallback(input);
+        }
+        catch (err) {
+            reasonerLog('planner.error', err instanceof Error ? err.message : String(err));
+            return fallback(input);
+        }
+    };
+}
+function inferenceOptions(target, base) {
+    return {
+        ...(target.model !== undefined ? { model: target.model } : {}),
+        ...(target.engineId ? { engineId: target.engineId } : {}),
+        ...(target.effortLevel ? { effortLevel: target.effortLevel } : {}),
+        ...base,
+    };
+}
+function logPlannerDebug(raw, goals) {
+    if (!browserDebugEnabled)
+        return;
+    agentLog('planner.response', raw.length > 500 ? `${raw.slice(0, 500)}...` : raw);
+    agentLog('planner.plan', JSON.stringify(goals));
+}

package/dist/server/services/browser/debug-log.js

@@ -0,0 +1,3 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+export { debugEnabled as browserDebugEnabled, debugLog as browserLog, } from '../websocket/debug-log.js';