@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/mcp/tools/app-tools.ts

@@ -0,0 +1,241 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { RELEASE_LABEL, suggestedLabel } from '../../commands/app/deploy'
+import { appSdkDrift, sdkDriftLines } from '../../local/local-app-sdk'
+import type { LocalProject } from '../../local/local-project'
+import { forgeSession, observeInForge, readForgeLink } from '../forge-link'
+import { AXE_RUN, axeSource, summarizeA11y } from '../a11y-scan'
+import { observeHeadless } from '../headless'
+import { ensureDevServer, findAppProjects, listDevServers, localAppEnv, resolveAppProject, stopDevServerAndSay } from '../mcp-apps'
+import { runSelf } from '../mcp-cli'
+import { errorResult, intArg, stringArg, type McpTool, type ToolResult } from '../mcp-protocol'
+import { redactSecret, requireRuntime, runtimeLink, signedStudioUrl } from '../mcp-runtime'
+import { platformCalls, renderTargetOf, writeRenderEvidence, type PageObservation, type RenderTarget } from '../page-observation'
+
+/**
+ * Custom Apps: run one against the local runtime, look at it the way a
+ * person would, and ship a preview. `app_render` is the local twin of the
+ * cloud copilot's `render_app`: it writes the render evidence a deploy
+ * carries, so a version deployed from here no longer says nobody looked
+ * at it. There is no tool to promote: that stays with a person.
+ */
+
+const appProperty = { type: 'string', description: 'The App\'s slug. Optional when the project has one App.' }
+
+function joinPath(base: string, path: string): string {
+  if (!path || path === '/') return base
+  const url = new URL(base)
+  // The Vite host page carries the App's path in its hash.
+  if (url.pathname.endsWith('/dev-host.html')) {
+    url.hash = path.startsWith('/') ? path : `/${path}`
+    return url.toString()
+  }
+  return new URL(path.startsWith('/') ? path : `/${path}`, url.origin).toString()
+}
+
+/** The App's `package.json` version, for a label suggestion. */
+function appPackageVersion(root: string): string | null {
+  try {
+    const v = (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { version?: unknown }).version
+    return typeof v === 'string' ? v : null
+  } catch {
+    return null
+  }
+}
+
+/** The text and picture of an observation, for the agent. */
+export function observationResult(summary: Record<string, unknown>, observation: PageObservation): ToolResult {
+  return {
+    content: [
+      { type: 'text', text: JSON.stringify(summary, null, 2) },
+      { type: 'image', data: observation.screenshot, mimeType: 'image/png' },
+    ],
+  }
+}
+
+export function appTools(project: LocalProject): McpTool[] {
+  return [
+    {
+      name: 'app_dev',
+      description:
+        "Start the App's dev server against the local runtime (its records are the project's datasets, never the workspace's; a governed Action the App submits changes them when it runs here, and one that would reach another system is switched off), or reuse the one already running, and return its URL. A server this session starts stops when the session ends; `frontera local stop` also stops it. Pass stop to stop it now. The App's files git tracks (or the pull recorded) that the dev server rewrites, such as next-env.d.ts, are put back once it is ready and again when it stops; trackedFiles says which, and an edit of yours is never put back. With no App in the call and several in the project, lists them.",
+      inputSchema: {
+        type: 'object',
+        properties: { app: appProperty, stop: { type: 'boolean', description: 'Stop the App\'s dev server instead.' } },
+        additionalProperties: false,
+      },
+      annotations: { title: 'Run an App locally', readOnlyHint: false, openWorldHint: false },
+      async run(input) {
+        const slug = stringArg(input, 'app')
+        const apps = findAppProjects(project.root)
+        if (!slug && apps.length > 1) {
+          const running = listDevServers(project)
+          return {
+            content: [{ type: 'text', text: JSON.stringify({ apps: apps.map((a) => ({ app: a.slug, path: a.path, framework: a.framework, running: running.find((s) => s.slug === a.slug)?.url ?? null })), next: 'Call app_dev with app set to one of these.' }, null, 2) }],
+          }
+        }
+        const app = resolveAppProject(project.root, slug)
+        if (input.stop === true) {
+          // Stopped, then what it put back as it stopped: the tracked files the dev server rewrote.
+          const { stopped, trackedFiles } = await stopDevServerAndSay(project, app.slug)
+          return { content: [{ type: 'text', text: stopped ? [`Stopped ${app.slug}'s dev server.`, ...trackedFiles.map((l) => `${app.path}: ${l}.`)].join('\n') : `${app.slug} had no dev server running.` }] }
+        }
+        const link = requireRuntime(project)
+        const { server, reused, installed, trackedFiles } = await ensureDevServer(project, app, link)
+        // An installed SDK older than (or without what is in) the one the skills describe: said with the upgrade.
+        const sdkLines = sdkDriftLines(app.path, appSdkDrift(app.root))
+        const sdk = sdkLines.filter((l) => !/^note:/.test(l))
+        const sdkNotes = sdkLines.filter((l) => /^note:/.test(l))
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ app: app.slug, url: server.url, reused, ...(installed ? { installed } : {}), ...(trackedFiles?.length ? { trackedFiles: trackedFiles.map((l) => `${app.path}: ${l}`) } : {}), runtime: link.serviceUrl, log: server.log, ...(sdk.length ? { warnings: sdk } : {}), ...(sdkNotes.length ? { notes: sdkNotes } : {}), next: 'app_render shows the page with its console; browser_open opens it in Forge\'s Browser to click through.' }, null, 2),
+            },
+          ],
+        }
+      },
+    },
+    {
+      name: 'app_render',
+      description:
+        "Open the App (or one of its pages), wait for it to settle, and return a screenshot, the console's errors and warnings, failed requests, and the Blueprint reads and governed Action requests it made. Writes the render evidence a deploy carries. Starts the dev server when none runs. In Forge the page opens in the person's Browser.",
+      inputSchema: {
+        type: 'object',
+        properties: {
+          app: appProperty,
+          path: { type: 'string', description: 'The App\'s page to open, e.g. /tickets (default /).' },
+          url: { type: 'string', description: 'Render this address instead of the dev server, e.g. a preview deployment\'s link.' },
+          width: { type: 'integer', minimum: 320, maximum: 2560, description: 'Viewport width (default 1440; 768 tablet, 375 phone).' },
+          waitForText: { type: 'string', description: 'Wait until this text shows before the screenshot.' },
+          fullPage: { type: 'boolean', description: 'Capture the whole page, not only the viewport.' },
+        },
+        additionalProperties: false,
+      },
+      annotations: { title: 'Render an App', readOnlyHint: false, openWorldHint: false },
+      async run(input) {
+        const app = resolveAppProject(project.root, stringArg(input, 'app'))
+        const path = stringArg(input, 'path') ?? '/'
+        const explicit = stringArg(input, 'url')
+        const link = runtimeLink(project)
+        let url: string
+        let installed: string | undefined
+        // What the dev server rewrote among the App's tracked files, put back as it started (next-env.d.ts).
+        let trackedFiles: string[] | undefined
+        let target: RenderTarget
+        if (explicit) {
+          url = explicit
+          // A deploy attaches this render only when it is of this App: its dev server or one of its previews.
+          target = renderTargetOf(explicit, app.slug, listDevServers(project).find((s) => s.slug === app.slug)?.url ?? null)
+        } else {
+          if (typeof link === 'string') return errorResult(link)
+          const dev = await ensureDevServer(project, app, link)
+          installed = dev.installed
+          trackedFiles = dev.trackedFiles
+          url = joinPath(dev.server.url, path)
+          target = { of: 'dev-server', url, app: app.slug }
+        }
+        const width = intArg(input, 'width', 1440, 320, 2560)
+        // A preview on this project's Studio opens signed in, as `frontera local ui`'s link does; the token never reaches an answer.
+        const signed = signedStudioUrl(project, link, url)
+        const req = { url: signed.url, width, height: width < 800 ? 812 : 900, waitForText: stringArg(input, 'waitForText'), fullPage: input.fullPage === true, a11yScript: axeSource(), a11yRun: AXE_RUN }
+        const session = forgeSession()
+        const forge = readForgeLink(project.stateDir)
+        const raw = (forge ? await observeInForge(forge, req, { session, label: app.name }) : null) ?? (await observeHeadless(req))
+        // Forge answers with the scan's raw findings; they are kept in one shape.
+        const { screenshot: picture, ...seen } = { ...raw, a11y: raw.a11y && !Array.isArray(raw.a11y) ? raw.a11y : summarizeA11y(raw.a11y) }
+        const observation = { ...redactSecret(seen, signed.secret), screenshot: picture }
+        const { record, screenshot, evidence } = writeRenderEvidence({
+          appRoot: app.root,
+          solutionRoot: project.root,
+          session,
+          slug: app.slug,
+          path,
+          observation,
+          runtime: explicit || typeof link === 'string' ? { kind: 'url', url } : { kind: 'local', url: link.serviceUrl, version: link.state.platformVersion },
+          target,
+        })
+        const calls = platformCalls(observation.requests)
+        const problems = record.consoleErrors + record.failedRequests + (observation.navigationError ? 1 : 0)
+        return observationResult(
+          {
+            app: app.slug,
+            url: observation.url,
+            title: observation.title,
+            verdict: problems ? `${problems} problem${problems === 1 ? '' : 's'} to look at` : 'Rendered with no console errors or failed requests',
+            browser: observation.where === 'forge' ? 'Forge Browser (the person can see this tab)' : 'headless',
+            ...(installed ? { installed } : {}),
+            ...(trackedFiles?.length ? { trackedFiles: trackedFiles.map((l) => `${app.path}: ${l}`) } : {}),
+            ...(observation.navigationError ? { navigationError: observation.navigationError } : {}),
+            console: observation.console.slice(0, 25),
+            failedRequests: observation.failedRequests.slice(0, 15),
+            blueprintCalls: calls.blueprint.slice(0, 20),
+            actionRequests: calls.actions,
+            functionCalls: calls.functions.slice(0, 10),
+            ...(observation.a11y ? { accessibility: { serious: observation.a11y.violations, findings: observation.a11y.findings.slice(0, 10) } } : {}),
+            text: observation.text.slice(0, 1_500),
+            evidence: {
+              record: `${app.path === '.' ? '' : `${app.path}/`}.frontera/last-render.json`,
+              screenshot,
+              details: evidence,
+              // Said here, not only at deploy: a render of another address is not this App's evidence.
+              ...(target.of === 'elsewhere'
+                ? { attachesToDeploy: false, note: `${url} is not ${app.slug}'s dev server or one of its previews, so app_deploy will not attach this render. Render the App (no url), or its preview link.` }
+                : { attachesToDeploy: true, of: target.of }),
+            },
+          },
+          observation,
+        )
+      },
+    },
+    {
+      name: 'app_deploy',
+      description:
+        "Build the App (bun run build), check it (bun run check, and that the build is newer than the source) and upload it as a preview deployment: it gets its own link and moves this branch's and this session's preview links, and never changes what users see. Deploys to the local runtime unless target is workspace (the linked workspace, with the person's own sign-in). Render first: the deployment carries the render evidence, and evidence.ok says whether that render was clean. Promotion stays with a person.",
+      inputSchema: {
+        type: 'object',
+        properties: {
+          app: appProperty,
+          target: { type: 'string', enum: ['local', 'workspace'], description: 'Where the preview goes (default local).' },
+          label: { type: 'string', description: 'An optional release label: a version such as 1.4.0, or 1.4.0-e2e.1 with a suffix (not "e2e-1"); unique per App. Every deployment has its own id without one.' },
+          build: { type: 'boolean', description: 'Build before deploying (default true). false deploys the build output already on disk.' },
+        },
+        additionalProperties: false,
+      },
+      annotations: { title: 'Deploy an App preview', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      async run(input) {
+        const app = resolveAppProject(project.root, stringArg(input, 'app'))
+        const target = stringArg(input, 'target') === 'workspace' ? 'workspace' : 'local'
+        const env = target === 'local' ? localAppEnv(requireRuntime(project)) : {}
+        const label = stringArg(input, 'label')
+        if (label && !RELEASE_LABEL.test(label)) {
+          return errorResult(`label "${label}" is not a version: labels look like 1.4.0, or 1.4.0-e2e.1 with a suffix. Try "${suggestedLabel(label, appPackageVersion(app.root))}", or leave label out (every deployment has its own id).`)
+        }
+        const result = await runSelf(['app', 'deploy', '--preview', ...(input.build === false ? [] : ['--build']), ...(label ? ['--label', label] : [])], { cwd: app.root, env })
+        const deployment = (result.data && typeof result.data === 'object' ? result.data : null) as { evidence?: { ok: boolean; problems: string[] } } | null
+        const evidence = deployment?.evidence
+        return {
+          ...(result.ok ? {} : { isError: true as const }),
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(
+                {
+                  ok: result.ok,
+                  target,
+                  // First, because it is what the agent must carry into its report.
+                  ...(evidence ? { evidence: evidence.ok ? evidence : { ...evidence, next: 'Say so when you report this preview: app_render the pages again after fixing what it found, then deploy again.' } } : {}),
+                  deployment: result.data,
+                  log: result.log,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        }
+      },
+    },
+  ]
+}

package/src/mcp/tools/browser-tools.ts

@@ -0,0 +1,310 @@
+import { existsSync, statSync } from 'node:fs'
+import { isAbsolute } from 'node:path'
+
+import { localProject, type LocalProject } from '../../local/local-project'
+import { headlessSession, type HeadlessBrowserSession } from '../browser/headless-session'
+import { callForgeBrowser, forgeSession, readForgeLink } from '../forge-link'
+import { observeHeadless } from '../headless'
+import { findAppProjects, listDevServers } from '../mcp-apps'
+import { stringArg, type McpTool, type ToolResult } from '../mcp-protocol'
+import { redactSecret, runtimeLink, signedStudioUrl, type RuntimeLink } from '../mcp-runtime'
+import { saveScreenshot } from '../page-observation'
+
+/**
+ * A browser for the coding agent. With the project open in Forge, each tool
+ * runs in a tab of Forge's Browser, labelled with the session that drives
+ * it, where the person can take over or stop it. Without Forge (a plain
+ * Claude Code or Codex session, an IDE, CI) the same tools run in a headless
+ * Chromium this server owns, with the same contracts and answers. Every
+ * answer ends saying which: `browser: forge` or `browser: headless`. The
+ * shapes follow Playwright MCP's, so agents need no new habits: snapshot for
+ * the page's accessibility tree with element refs, then click and type by ref.
+ *
+ * Reading and navigating are free on any site. Acting outside the project
+ * (submitting a form on another website, or on the linked workspace, or
+ * running script there) asks the person first, in Forge; headless, nobody
+ * can be asked, so it is refused. An agent acts only in the tabs it opened;
+ * in Forge the person's tabs and other sessions' it may only read
+ * (snapshot, screenshot, console, network).
+ */
+
+const tabId = { type: 'string', description: 'The tab, from browser_open or browser_tabs; your session\'s current tab when left out. You act only in tabs you opened; the person\'s and other sessions\' tabs you may only read (browser_open the same address to work on it).' }
+const ref = { type: 'string', description: 'The element\'s ref from the latest browser_snapshot, e.g. e12.' }
+const element = { type: 'string', description: 'What the element is, in words ("Save button"), shown to the person while you act.' }
+const waitFields = {
+  text: { type: 'string', description: 'Wait until this text shows on the page.' },
+  textGone: { type: 'string', description: 'Wait until this text is gone.' },
+  selector: { type: 'string', description: 'Wait until an element matching this CSS selector shows (or, with state hidden, is gone).' },
+  state: { type: 'string', enum: ['visible', 'hidden'], description: 'For selector or ref: visible (default) or hidden.' },
+  networkIdle: { type: 'boolean', description: 'Wait until no request has run for half a second.' },
+  timeout: { type: 'number', description: 'Seconds to wait at most (default 10, at most 60).' },
+}
+const waitFor = {
+  type: 'object',
+  description: 'Before reading the page, wait (bounded) for content that appears a moment after it loads.',
+  properties: waitFields,
+  additionalProperties: false,
+}
+
+interface BrowserToolSpec {
+  name: string
+  title: string
+  description: string
+  properties: Record<string, unknown>
+  required?: string[]
+  readOnly: boolean
+}
+
+const SPECS: BrowserToolSpec[] = [
+  {
+    name: 'browser_open',
+    title: 'Open a page',
+    description: "Open an address in a new tab and return its accessibility snapshot: a dev server, Studio (opened signed in), the linked workspace or any website. In the Forge Browser when the project is open in Forge (the person watches), else in a headless browser; the answer ends with which.",
+    properties: { url: { type: 'string', description: 'The address, e.g. http://127.0.0.1:3100/tickets.' }, waitFor },
+    required: ['url'],
+    readOnly: true,
+  },
+  {
+    name: 'browser_navigate',
+    title: 'Navigate',
+    description: 'Go to an address in the tab, or back, forward or reload. Waits for the page to load and settle, then returns the new snapshot.',
+    properties: { url: { type: 'string', description: 'Where to go.' }, action: { type: 'string', enum: ['back', 'forward', 'reload'], description: 'Instead of an address.' }, waitFor, tabId },
+    readOnly: true,
+  },
+  {
+    name: 'browser_snapshot',
+    title: 'Read the page',
+    description: "The page's accessibility tree with a ref for each element you can act on. Embedded frames (an App previewed in Studio) are read in under their Iframe line, marked [frame=address]; their refs act inside the frame like any other. A ref keeps naming the same element until the page navigates to another document; take a new snapshot after that, and after the person has used the tab.",
+    properties: { waitFor: { ...waitFor, properties: { ...waitFields, ref: { type: 'string', description: 'For a ref from an earlier snapshot: wait until it shows (or, with state hidden, is gone).' } } }, tabId },
+    readOnly: true,
+  },
+  {
+    name: 'browser_click',
+    title: 'Click',
+    description: 'Click an element by its ref. The person sees the element outlined and the pointer move. Submitting a form outside the project asks the person first.',
+    properties: { ref, element, doubleClick: { type: 'boolean' }, button: { type: 'string', enum: ['left', 'right', 'middle'] }, tabId },
+    required: ['ref', 'element'],
+    readOnly: false,
+  },
+  {
+    name: 'browser_type',
+    title: 'Type',
+    description: 'Type text into an element by its ref, optionally pressing Enter after. Password fields are refused: ask the person to sign in.',
+    properties: { ref, element, text: { type: 'string' }, submit: { type: 'boolean', description: 'Press Enter after typing.' }, clear: { type: 'boolean', description: 'Clear the field first (default true).' }, tabId },
+    required: ['ref', 'element', 'text'],
+    readOnly: false,
+  },
+  {
+    name: 'browser_press_key',
+    title: 'Press a key',
+    description: 'Press a key or a combination (Enter, Escape, Tab, ArrowDown, a, Shift+Tab, Meta+a), in the element by ref (focused first) or wherever the page has focus. Enter or Space outside the project asks the person first.',
+    properties: { key: { type: 'string' }, ref: { type: 'string', description: 'Optional: the element to press it in.' }, element, tabId },
+    required: ['key'],
+    readOnly: false,
+  },
+  {
+    name: 'browser_select_option',
+    title: 'Choose an option',
+    description: 'Choose one or more options of a <select> by value or label. For a custom list box, click it open and click the option.',
+    properties: { ref, element, values: { type: 'array', items: { type: 'string' }, description: 'The options, by value or label.' }, tabId },
+    required: ['ref', 'element', 'values'],
+    readOnly: false,
+  },
+  {
+    name: 'browser_hover',
+    title: 'Hover',
+    description: 'Move the pointer over an element by ref, so what shows on hover (a menu, a tooltip) appears in the snapshot.',
+    properties: { ref, element, tabId },
+    required: ['ref', 'element'],
+    readOnly: false,
+  },
+  {
+    name: 'browser_wait_for',
+    title: 'Wait for the page',
+    description: 'Wait, bounded, until text shows or is gone, an element (selector or ref) shows or is gone, the network goes quiet, or for a number of seconds. Returns the snapshot; an error when it did not happen in time.',
+    properties: { ...waitFields, ref: { type: 'string', description: 'An element\'s ref: wait until it shows (or, with state hidden, is gone).' }, time: { type: 'number', description: 'Instead: just wait this many seconds (at most 60).' }, tabId },
+    readOnly: true,
+  },
+  {
+    name: 'browser_evaluate',
+    title: 'Run script in the page',
+    description: "Run a JavaScript expression in the page (its own world, where the App's state lives) and return the result as JSON, at most 20,000 characters. A function, such as () => document.title, is called; a promise is awaited (10 s at most). With a ref, it runs in the frame that element is in (an App embedded in Studio) and a function is called with the element. Outside the project it asks the person first. Prefer snapshot, click and type to check what a person sees.",
+    properties: {
+      expression: { type: 'string', description: 'An expression or a function, e.g. () => window.location.pathname, or (element) => element.value with a ref.' },
+      ref: { type: 'string', description: 'Optional: an element from the snapshot. The script runs in its frame and a function gets the element.' },
+      tabId,
+    },
+    required: ['expression'],
+    readOnly: false,
+  },
+  {
+    name: 'browser_set_viewport',
+    title: 'Set the page width',
+    description: "Lay the tab's page out at a device width (desktop, tablet 768, phone 375) or at a width (and height) in pixels, for responsive checks. desktop goes back to the window's own size.",
+    properties: { device: { type: 'string', enum: ['desktop', 'tablet', 'phone'] }, width: { type: 'integer', minimum: 240, maximum: 3840 }, height: { type: 'integer', minimum: 240, maximum: 4320 }, tabId },
+    readOnly: false,
+  },
+  {
+    name: 'browser_handle_dialog',
+    title: 'Answer a dialog',
+    description: "Answer the dialog the page opened (alert, confirm, prompt, or leaving the page): accept (OK) or not (Cancel), with text for a prompt. Actions say when one opened, and what it says; the page waits until it is answered. OK outside the project asks the person first.",
+    properties: { accept: { type: 'boolean', description: 'OK (default) or Cancel.' }, promptText: { type: 'string', description: 'For a prompt: the text to answer with.' }, tabId },
+    readOnly: false,
+  },
+  {
+    name: 'browser_screenshot',
+    title: 'Screenshot',
+    description: 'A screenshot of the tab once its page settled (a tab behind the person\'s is captured without bringing it to the front), saved in the evidence folder of the project the tab belongs to, named after the App when it shows one. Without Forge, url renders an address headless without opening a tab.',
+    properties: { tabId, fullPage: { type: 'boolean' }, url: { type: 'string', description: 'Without Forge only: an address to render once, instead of a tab.' } },
+    readOnly: true,
+  },
+  {
+    name: 'browser_console',
+    title: 'Console',
+    description: "The tab's console messages since it opened, newest last.",
+    properties: { tabId, onlyErrors: { type: 'boolean', description: 'Only errors and warnings.' } },
+    readOnly: true,
+  },
+  {
+    name: 'browser_network',
+    title: 'Network',
+    description: "The tab's requests since it opened: method, address, status and time, failed ones first. With onlyFailed, only the failed ones, then how many others were captured; with none failed it says how many were captured, so an empty answer never hides a capture.",
+    properties: { tabId, onlyFailed: { type: 'boolean', description: 'Only failed requests (refused, aborted, or 400 and above).' } },
+    readOnly: true,
+  },
+  {
+    name: 'browser_tabs',
+    title: 'Tabs',
+    description: 'List the Browser\'s tabs (owner says whose: you, the person, another session), make one your current tab, or close one of yours. You may read any of them; you act only in yours.',
+    properties: { action: { type: 'string', enum: ['list', 'select', 'close'], description: 'Default list.' }, tabId },
+    readOnly: false,
+  },
+]
+
+/** Where a screenshot's evidence goes: the folder of the project the tab belongs to (as Forge says), else this server's. */
+export function evidenceProject(project: LocalProject, tabRoot: unknown): LocalProject {
+  if (typeof tabRoot !== 'string' || !isAbsolute(tabRoot) || tabRoot === project.root) return project
+  try {
+    return existsSync(tabRoot) && statSync(tabRoot).isDirectory() ? localProject(tabRoot) : project
+  } catch {
+    return project
+  }
+}
+
+/** The project's App an address shows: its dev server's origin, or a platform or Studio page under `/apps/<slug>`. */
+export function appForUrl(project: LocalProject, url: string): string | null {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return null
+  }
+  const dev = listDevServers(project).find((s) => {
+    try {
+      return new URL(s.url).origin === parsed.origin
+    } catch {
+      return false
+    }
+  })
+  if (dev) return dev.slug
+  const slug = /^\/apps\/([^/?#]+)/.exec(parsed.pathname)?.[1]
+  if (!slug) return null
+  const name = decodeURIComponent(slug)
+  return findAppProjects(project.root).some((a) => a.slug === name) ? name : null
+}
+
+/** Keep a screenshot the Forge Browser returned in the evidence folder of the tab's project, named after its App, and say where. */
+function keepScreenshots(result: ToolResult & { meta?: { url?: string; root?: string } }, project: LocalProject, session: string | null): ToolResult {
+  const { meta, ...answer } = result
+  const owner = evidenceProject(project, meta?.root)
+  const url = typeof meta?.url === 'string' ? meta.url : ''
+  const app = url ? appForUrl(owner, url) : null
+  let host = ''
+  try {
+    host = url ? new URL(url).hostname : ''
+  } catch {
+    // Not an address.
+  }
+  const label = app ? `${app}-screenshot` : host ? `${host}-screenshot` : 'screenshot'
+  const saved: string[] = []
+  for (const c of answer.content) if (c.type === 'image') saved.push(saveScreenshot(owner.root, session, c.data, label))
+  if (!saved.length) return answer
+  const where = owner.root === project.root ? saved.join(', ') : saved.map((p) => `${p} in ${owner.root}`).join(', ')
+  return { ...answer, content: [...answer.content, { type: 'text', text: `Saved ${where}${app ? ` (App ${app})` : ''}` }] }
+}
+
+/**
+ * The agent's address, signed in when it is this project's Studio (an App
+ * preview at `/apps/<slug>?version=…` sits behind Studio's sign-in): Studio
+ * swaps the `?token=` for its cookie and redirects to the same address
+ * without it. Forge is told the token too, so the tab blanks it out of its
+ * requests, console and address; the answer is redacted here as well.
+ */
+export function signBrowserInput(project: LocalProject, link: RuntimeLink | string, tool: string, input: Record<string, unknown>): { input: Record<string, unknown>; secret: string | null } {
+  if (tool !== 'browser_open' && tool !== 'browser_navigate') return { input, secret: null }
+  const url = stringArg(input, 'url')
+  if (!url) return { input, secret: null }
+  const signed = signedStudioUrl(project, link, url)
+  return signed.secret ? { input: { ...input, url: signed.url, redact: signed.secret }, secret: signed.secret } : { input, secret: null }
+}
+
+/** The answer with the token blanked out of its words and the screenshot's address; pictures untouched. */
+export function redactAnswer<T extends ToolResult & { meta?: { url?: string } }>(answer: T, secret: string | null): T {
+  if (!secret) return answer
+  return {
+    ...answer,
+    content: answer.content.map((c) => (c.type === 'text' ? redactSecret(c, secret) : c)),
+    ...(answer.meta ? { meta: redactSecret(answer.meta, secret) } : {}),
+  }
+}
+
+/** Say which browser answered, last, so the agent knows whether the person saw it. */
+function tagged(answer: ToolResult, browser: 'forge' | 'headless'): ToolResult {
+  return { ...answer, content: [...answer.content, { type: 'text', text: `browser: ${browser}` }] }
+}
+
+export function browserTools(project: LocalProject, deps: { runtime?: () => RuntimeLink | string; headless?: () => HeadlessBrowserSession } = {}): McpTool[] {
+  const runtime = deps.runtime ?? (() => runtimeLink(project))
+  const headless = deps.headless ?? headlessSession
+  return SPECS.map((spec) => ({
+    name: spec.name,
+    description: spec.description,
+    inputSchema: { type: 'object', properties: spec.properties, ...(spec.required ? { required: spec.required } : {}), additionalProperties: false },
+    annotations: { title: spec.title, readOnlyHint: spec.readOnly, openWorldHint: true },
+    async run(input): Promise<ToolResult> {
+      const session = forgeSession()
+      const signed = signBrowserInput(project, runtime(), spec.name, input)
+      // Forge first: the person watches there. Not reachable, or no window to show a page in: headless.
+      const link = readForgeLink(project.stateDir)
+      const raw = link ? await callForgeBrowser(link, spec.name, signed.input, { session }) : null
+      if (raw) {
+        const answer = redactAnswer(raw, signed.secret)
+        return tagged(spec.name === 'browser_screenshot' ? keepScreenshots(answer, project, session) : answer, 'forge')
+      }
+      const url = stringArg(input, 'url')
+      if (spec.name === 'browser_screenshot' && url) {
+        const once = signedStudioUrl(project, runtime(), url)
+        const observation = redactSecret(await observeHeadless({ url: once.url, fullPage: input.fullPage === true }), once.secret)
+        const app = appForUrl(project, url)
+        let label = 'page'
+        try {
+          label = app ? `${app}-screenshot` : new URL(url).hostname
+        } catch {
+          // Not an address; the page's own name stands.
+        }
+        const path = saveScreenshot(project.root, session, observation.screenshot, label)
+        return tagged(
+          {
+            content: [
+              { type: 'text', text: JSON.stringify({ url: observation.url, title: observation.title, browser: 'headless', saved: path, ...(app ? { app } : {}), consoleErrors: observation.console.filter((c) => c.level === 'error').length }, null, 2) },
+              { type: 'image', data: observation.screenshot, mimeType: 'image/png' },
+            ],
+          },
+          'headless',
+        )
+      }
+      const answer = redactAnswer(await headless().run(spec.name, signed.input, project.root), signed.secret)
+      return tagged(spec.name === 'browser_screenshot' ? keepScreenshots(answer, project, session) : answer, 'headless')
+    },
+  }))
+}

package/src/mcp/tools/docs-tools.ts

@@ -0,0 +1,32 @@
+import { answerDocsMessage, docsCopyPath, type SchemaLookup } from '../../local/local-docs'
+import type { LocalProject } from '../../local/local-project'
+import type { McpTool, ToolResult } from '../mcp-protocol'
+
+/**
+ * The documentation tools, unchanged from the `frontera-docs` server they
+ * absorb: same names and inputs, answered from the copy `local start` keeps,
+ * so they work with the runtime stopped.
+ */
+
+const DOCS_TOOLS = [
+  { name: 'search_documentation', description: "Search Frontera's documentation for the release the local runtime runs. Returns guides with the best matching heading and a snippet; read one with read_documentation." },
+  { name: 'read_documentation', description: 'Read a guide by its slug from a search result, whole or one heading of it.' },
+  { name: 'list_documentation', description: 'List every guide: slug, title and description. Use it to browse an area, e.g. everything under "workflows/".' },
+  { name: 'read_file_schema', description: 'The exact format of a kind of project file (agent.json, operating.json, a workflow, the Blueprint), as JSON Schema, for the runtime\'s release. Read it before writing such a file.' },
+] as const
+
+export function docsTools(project: LocalProject, schemaFor: SchemaLookup): McpTool[] {
+  const docsPath = docsCopyPath(project)
+  // The schemas come from the docs server itself, so the two never drift.
+  const listed = answerDocsMessage({ jsonrpc: '2.0', id: 0, method: 'tools/list' }, docsPath, schemaFor) as { result: { tools: Array<{ name: string; inputSchema: Record<string, unknown> }> } }
+  return DOCS_TOOLS.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: listed.result.tools.find((t) => t.name === tool.name)?.inputSchema ?? { type: 'object' },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async run(input) {
+      const answer = answerDocsMessage({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: tool.name, arguments: input } }, docsPath, schemaFor) as { result: ToolResult }
+      return answer.result
+    },
+  }))
+}