@frontera-sdk/cli 1.52.27 → 1.52.29

package/src/local/local-stand-ins.ts

@@ -0,0 +1,442 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { answerDocsMessage } from './local-docs'
+import { HOST_FROM_CONTAINER } from './local-env'
+import type { LocalProject } from './local-project'
+import { readState } from './local-state'
+import type { SyncClient } from './local-sync-client'
+import type { RemoteItem } from './local-sync-plan'
+import { rows } from './local-sync-remote'
+
+/**
+ * Stand-ins for built-in connections (design §8, class Stubbed).
+ *
+ * A built-in connection (Google Sheets, BigQuery, GitHub…) is signed in on
+ * the platform with OAuth or a service account, so the local runtime cannot
+ * reach it. An Agent, a procedure, a workflow step or trigger that names one
+ * would otherwise be refused locally, or applied without it. Instead the
+ * pull declares a stand-in, `mcp/<name>.stand-in.json` (the connection's name
+ * and tools, as the platform lists them), and `local dev` installs it as a
+ * Plugin of that name, served by the runtime's own Studio server: it lists
+ * the connection's tools, and each answers "not connected" in words. So the
+ * Agent, the procedure and the workflow apply as written, and what they do
+ * with the connection fails visibly instead of silently.
+ *
+ * A stand-in is the project's declaration, never a Plugin of the workspace:
+ * a change request never proposes it (it is not a `.plugin.json`), and a
+ * real `mcp/<name>.plugin.json` takes its place.
+ *
+ * Two of the workspace's built-in Plugins are not connections to someone
+ * else's system, and are declared apart:
+ * - **Documentation** (Frontera's documentation for Agents): its stand-in
+ *   `serves: "documentation"`, answering the plugin's tools from the
+ *   documentation `local start` copied for the runtime's release (the same
+ *   copy `frontera local docs-mcp` serves the project's coding agents). The
+ *   Agent's documentation tools work here.
+ * - **Analytics**: the workspace's analytics tools read its analytics
+ *   project, which a local runtime does not have (design §8). The pull
+ *   declares it platform-only, `mcp/<name>.platform.json`. An Agent that
+ *   uses it runs here without those tools, said in the build as "Analytics
+ *   tools stay on the platform". So that a workflow step on it still
+ *   applies, `local dev` installs a Plugin of its name served by the Studio
+ *   server, as for a connection's stand-in, whose every tool answers in
+ *   words that the analytics tools stay on the platform.
+ */
+
+export const standInPath = (name: string) => `mcp/${name}.stand-in.json`
+
+export interface StandInFile {
+  standIn: true
+  /** The connection as people know it: "Google Sheets". */
+  connection: string
+  /** `documentation`: it serves the runtime's documentation instead of answering "not connected". */
+  serves?: 'documentation'
+  note: string
+  tools: Array<{ name: string; description?: string }>
+}
+
+const NOTE = 'A stand-in for a connection signed in on the platform. On the local runtime its tools answer “not connected”. Frontera writes this file from the workspace; a change request never proposes it.'
+const DOCS_NOTE = 'Frontera’s documentation for Agents. On the local runtime it serves the documentation of the runtime’s release. Frontera writes this file from the workspace; a change request never proposes it.'
+
+/** The Documentation plugin's tools, as the platform's documentation server lists them. */
+const DOCS_TOOLS: StandInFile['tools'] = [
+  { name: 'get_documentation_context', description: 'The documentation release this runtime serves' },
+  { name: 'read_documentation', description: 'Read a guide' },
+  { name: 'search_documentation', description: 'Search the documentation' },
+]
+
+/** The built-in Plugins these items need that get a stand-in (connections, the Documentation plugin), by install name. */
+export function connectionsNeeded(items: Array<Pick<RemoteItem, 'portability'>>): string[] {
+  return [...new Set(items.flatMap((i) => (i.portability?.needs ?? []).flatMap((n) => (n.kind === 'connection' || n.kind === 'documentation' ? [n.name] : []))))].sort()
+}
+
+/** Which of those are the Documentation plugin. */
+export function documentationNeeded(items: Array<Pick<RemoteItem, 'portability'>>): Set<string> {
+  return new Set(items.flatMap((i) => (i.portability?.needs ?? []).flatMap((n) => (n.kind === 'documentation' ? [n.name] : []))))
+}
+
+/** The workspace's analytics Plugins these items use: platform-only. */
+export function analyticsNeeded(items: Array<Pick<RemoteItem, 'portability'>>): string[] {
+  return [...new Set(items.flatMap((i) => (i.portability?.needs ?? []).flatMap((n) => (n.kind === 'analytics' ? [n.name] : []))))].sort()
+}
+
+// ── Platform-only Plugins ────────────────────────────────────────────────────
+
+export const platformOnlyPath = (name: string) => `mcp/${name}.platform.json`
+
+/** What an Agent that uses the workspace's analytics is told, in the build and the Pull dialog. */
+export const ANALYTICS_STAY = 'Analytics tools stay on the platform: a local runtime has no analytics'
+
+/** What each of the analytics Plugin's tools answers on the local runtime. */
+export function analyticsStay(tool: string): string {
+  return `Analytics tools stay on the platform: a local runtime has no analytics, so ${tool} didn’t run. Run this in the workspace.`
+}
+
+/** Whether the project declares this Plugin platform-only (`mcp/<name>.platform.json`). */
+export function isPlatformOnly(root: string, name: string): boolean {
+  return existsSync(join(root, platformOnlyPath(name)))
+}
+
+export interface PlatformOnlyFile {
+  platformOnly: 'analytics'
+  note: string
+}
+
+const ANALYTICS_NOTE = 'The workspace’s analytics tools. They stay on the platform: they read the workspace’s analytics, which a local runtime does not have. Frontera writes this file from the workspace; nothing is installed locally, and a change request never proposes it.'
+
+/** The Plugins the project declares platform-only, by install name. */
+export function platformOnlyNames(root: string): Set<string> {
+  try {
+    return new Set(readdirSync(join(root, 'mcp')).flatMap((f) => (f.endsWith('.platform.json') && f !== '.platform.json' ? [f.slice(0, -'.platform.json'.length)] : [])))
+  } catch {
+    return new Set()
+  }
+}
+
+/** Declare each analytics Plugin the project's items use as platform-only. Returns the paths written. */
+export function writePlatformOnly(root: string, names: string[]): string[] {
+  const out: string[] = []
+  const doc: PlatformOnlyFile = { platformOnly: 'analytics', note: ANALYTICS_NOTE }
+  const text = `${JSON.stringify(doc, null, 2)}\n`
+  for (const name of names) {
+    const path = join(root, platformOnlyPath(name))
+    if (existsSync(path) && readFileSync(path, 'utf8') === text) continue
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, text)
+    out.push(platformOnlyPath(name))
+  }
+  return out
+}
+
+/**
+ * An Agent's rows that name a platform-only Plugin (its install, its MCP
+ * server, its tool settings) are left off its local copy, said once.
+ * Changes `doc`; returns the warning.
+ */
+export function dropPlatformOnly(doc: Record<string, unknown>, names: ReadonlySet<string>): string[] {
+  if (!names.size) return []
+  const named = (v: unknown) => typeof v === 'string' && v.startsWith('plugin/') && names.has(v.slice('plugin/'.length))
+  let dropped = false
+  const keep = (key: string, test: (row: Record<string, unknown>) => boolean) => {
+    if (!Array.isArray(doc[key])) return
+    const rows = doc[key] as Array<Record<string, unknown>>
+    const kept = rows.filter((r) => !test(r ?? {}))
+    if (kept.length !== rows.length) dropped = true
+    doc[key] = kept
+  }
+  keep('appInstalls', (r) => named(r.installId))
+  keep('mcpServers', (r) => typeof r.name === 'string' && names.has(r.name))
+  keep('pluginTools', (r) => named(r.plugin))
+  return dropped ? [`  warning: ${ANALYTICS_STAY}`] : []
+}
+
+export function readStandIn(root: string, name: string): StandInFile | null {
+  try {
+    const doc = JSON.parse(readFileSync(join(root, standInPath(name)), 'utf8')) as StandInFile
+    return doc && doc.standIn === true ? doc : null
+  } catch {
+    return null
+  }
+}
+
+/** The stand-ins the project declares, by connection name. */
+export function standInNames(root: string): Set<string> {
+  try {
+    return new Set(readdirSync(join(root, 'mcp')).flatMap((f) => (f.endsWith('.stand-in.json') && f !== '.stand-in.json' ? [f.slice(0, -'.stand-in.json'.length)] : [])))
+  } catch {
+    return new Set()
+  }
+}
+
+interface AppRow {
+  install?: { id: string; installName: string }
+  catalog?: { kind?: string; name?: string; displayName?: string }
+}
+
+export interface StandInsWritten {
+  /** Declared now, or brought up to date with the workspace's tools. */
+  written: string[]
+  /** A real Plugin file of that name is in the project: it is used instead. */
+  replaced: string[]
+}
+
+/**
+ * Declare a stand-in for each connection the project's items need: its name
+ * and tools from the workspace, when the platform can be read; otherwise its
+ * name alone (the tools the project's files name still answer). An existing
+ * stand-in is rewritten only to follow the workspace.
+ */
+export async function writeStandIns(root: string, names: string[], ws?: SyncClient, documentation: ReadonlySet<string> = new Set()): Promise<StandInsWritten> {
+  const out: StandInsWritten = { written: [], replaced: [] }
+  if (!names.length) return out
+  const apps = ws ? await ws.get<unknown>('/v1/apps').then((b) => rows<AppRow>(b)).catch(() => [] as AppRow[]) : []
+  for (const name of names) {
+    if (existsSync(join(root, 'mcp', `${name}.plugin.json`))) {
+      out.replaced.push(name)
+      continue
+    }
+    const row = apps.find((a) => a.install?.installName === name)
+    let tools: StandInFile['tools'] | null = null
+    if (ws && row?.install) {
+      tools = await ws
+        .get<unknown>(`/v1/apps/${encodeURIComponent(row.install.id)}/capabilities`)
+        .then((b) => rows<{ name?: string; displayName?: string; description?: string | null }>(b).flatMap((t) => (t.name ? [{ name: t.name, ...(t.description || t.displayName ? { description: String(t.description || t.displayName) } : {}) }] : [])))
+        .catch(() => null)
+    }
+    const before = readStandIn(root, name)
+    const docs = documentation.has(name) || before?.serves === 'documentation'
+    const doc: StandInFile = {
+      standIn: true,
+      connection: row?.catalog?.displayName ?? before?.connection ?? name,
+      ...(docs ? { serves: 'documentation' as const } : {}),
+      note: docs ? DOCS_NOTE : NOTE,
+      tools: (tools?.length ? tools : before?.tools?.length ? before.tools : docs ? DOCS_TOOLS : []).sort((a, b) => a.name.localeCompare(b.name)),
+    }
+    const text = `${JSON.stringify(doc, null, 2)}\n`
+    const path = join(root, standInPath(name))
+    if (existsSync(path) && readFileSync(path, 'utf8') === text) continue
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, text)
+    out.written.push(name)
+  }
+  return out
+}
+
+/**
+ * The tools a stand-in lists: the connection's, as the workspace listed
+ * them, and every tool the project's Agents and workflows name on it (a
+ * workflow step's `capability`, an Agent's tool setting), so each resolves.
+ */
+export function standInTools(root: string, name: string): StandInFile['tools'] {
+  const declared = readStandIn(root, name)?.tools ?? []
+  const tools = new Map(declared.map((t) => [t.name, t]))
+  const ref = `plugin/${name}`
+  const visit = (v: unknown) => {
+    if (Array.isArray(v)) return v.forEach(visit)
+    if (!v || typeof v !== 'object') return
+    const o = v as Record<string, unknown>
+    const names = o.resourceId === ref || o.plugin === ref || o.installId === ref
+    if (names) {
+      const params = (o.params ?? {}) as Record<string, unknown>
+      for (const tool of [o.capability, o.tool, params.capability]) if (typeof tool === 'string' && tool && !tools.has(tool)) tools.set(tool, { name: tool })
+    }
+    for (const x of Object.values(o)) visit(x)
+  }
+  for (const top of ['agents', 'workflows']) {
+    const walk = (dir: string, depth: number) => {
+      if (depth > 3 || !existsSync(dir)) return
+      for (const f of readdirSync(dir, { withFileTypes: true })) {
+        if (f.name.startsWith('.')) continue
+        const path = join(dir, f.name)
+        if (f.isDirectory()) walk(path, depth + 1)
+        else if (/\.(json|ya?ml)$/.test(f.name)) {
+          try {
+            const text = readFileSync(path, 'utf8')
+            if (text.includes(ref)) visit(f.name.endsWith('.json') ? JSON.parse(text) : parseYaml(text))
+          } catch {
+            // A file that does not parse names nothing here.
+          }
+        }
+      }
+    }
+    walk(join(root, top), 0)
+  }
+  return [...tools.values()].sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/** Where the runtime reaches a stand-in: the Studio server, from wherever the service runs. */
+export function standInUrl(project: LocalProject, name: string): string | null {
+  const state = readState(project)
+  if (!state?.ports?.studio) return null
+  const host = state.mode === 'image' ? HOST_FROM_CONTAINER : '127.0.0.1'
+  return `http://${host}:${state.ports.studio}/__stand-in/${encodeURIComponent(name)}/mcp`
+}
+
+/** What every one of a stand-in's tools answers. */
+export function notConnected(connection: string, tool: string): string {
+  return `${connection} isn’t connected on this local runtime, so ${tool} didn’t run. ${connection} is signed in on the platform only: try this in the workspace, or use sample data here.`
+}
+
+/**
+ * A stand-in's MCP endpoint (streamable HTTP, JSON answers): it lists the
+ * connection's tools and answers every call with a "not connected" error. It holds
+ * nothing and reaches nothing, so it needs no session.
+ */
+export async function standInMcp(root: string, name: string, req: Request, docsPath?: string): Promise<Response> {
+  if (req.method !== 'POST') return new Response(null, { status: 405, headers: { allow: 'POST' } })
+  // The analytics Plugin, platform-only, is served the same way: each of its tools says it stays on the platform.
+  const platformOnly = isPlatformOnly(root, name) && !readStandIn(root, name)
+  const doc: StandInFile | null = platformOnly ? { standIn: true, connection: 'Analytics', note: '', tools: [] } : readStandIn(root, name)
+  if (!doc) return new Response('No such stand-in', { status: 404 })
+  let body: unknown
+  try {
+    body = await req.json()
+  } catch {
+    return Response.json({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }, { status: 400 })
+  }
+  const answer = (msg: { id?: unknown; method?: string; params?: Record<string, unknown> }) => {
+    if (msg.id === undefined || msg.id === null) return null
+    // The Documentation plugin: the runtime's documentation, with the tools the platform's has.
+    if (doc.serves === 'documentation') return answerDocsMessage(msg as Parameters<typeof answerDocsMessage>[0], docsPath ?? '', undefined, 'agent')
+    switch (msg.method) {
+      case 'initialize':
+        return { jsonrpc: '2.0', id: msg.id, result: { protocolVersion: typeof msg.params?.protocolVersion === 'string' ? msg.params.protocolVersion : '2025-03-26', capabilities: { tools: {} }, serverInfo: { name: `${name} (stand-in)`, version: '1' }, instructions: platformOnly ? ANALYTICS_STAY : notConnected(doc.connection, 'its tools') } }
+      case 'ping':
+        return { jsonrpc: '2.0', id: msg.id, result: {} }
+      case 'tools/list':
+        return {
+          jsonrpc: '2.0',
+          id: msg.id,
+          result: { tools: standInTools(root, name).map((t) => ({ name: t.name, description: `${t.description ? `${t.description} ` : ''}(${platformOnly ? 'Analytics tools stay on the platform: a local runtime has no analytics.' : `Not connected on the local runtime: ${doc.connection} runs on the platform only.`})`, inputSchema: { type: 'object', additionalProperties: true } })) },
+        }
+      case 'tools/call': {
+        // An error, not a result marked isError: a workflow step takes a result as its output and
+        // goes on; an error stops the step with the words, and an Agent's tool call reports them.
+        const tool = typeof msg.params?.name === 'string' ? msg.params.name : 'this tool'
+        return { jsonrpc: '2.0', id: msg.id, error: { code: -32000, message: platformOnly ? analyticsStay(tool) : notConnected(doc.connection, tool) } }
+      }
+      default:
+        return { jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: `Method not found: ${msg.method}` } }
+    }
+  }
+  const batch = Array.isArray(body)
+  const replies = (batch ? (body as unknown[]) : [body]).map((m) => answer((m ?? {}) as Parameters<typeof answer>[0])).filter(Boolean)
+  if (!replies.length) return new Response(null, { status: 202 })
+  return Response.json(batch ? replies : replies[0])
+}
+
+function parseJson<T>(output: string): T | null {
+  const start = output.search(/[[{]/)
+  if (start < 0) return null
+  try {
+    return JSON.parse(output.slice(start)) as T
+  } catch {
+    return null
+  }
+}
+
+/** Why an item using a stand-in runs as it does, as its build says it. */
+export function standInAdaptation(connection: string): string {
+  return `${connection} isn’t connected here: a stand-in answers its tools with “not connected”`
+}
+
+/**
+ * Install a stand-in on the runtime as a Plugin of the connection's name,
+ * pointed at its endpoint, every tool on: an Agent, procedure or workflow
+ * that names the connection then resolves, and each call says it is not
+ * connected.
+ */
+export async function applyStandIn(
+  project: LocalProject,
+  name: string,
+  workspaceProfile: string,
+  run: (args: string[]) => Promise<{ ok: boolean; output: string }>,
+): Promise<{ ok: boolean; output: string }> {
+  const platformOnly = isPlatformOnly(project.root, name) && !readStandIn(project.root, name)
+  const doc: StandInFile | null = platformOnly ? { standIn: true, connection: 'Analytics', note: '', tools: [] } : readStandIn(project.root, name)
+  if (!doc) return { ok: false, output: `error [USAGE]: ${standInPath(name)} is not a stand-in` }
+  const made = standInPluginFile(project, name)
+  if (!made) return { ok: false, output: 'error [LOCAL_NOT_RUNNING]: the runtime has no Studio port for the stand-in' }
+  const p = ['--profile', workspaceProfile]
+  const find = async () => {
+    const listed = await run(['plugin', 'list', '--json', ...p])
+    return (parseJson<Array<{ install?: { id: string; installName: string } }>>(listed.output) ?? []).find((r) => r.install?.installName === name)?.install
+  }
+  let id = (await find())?.id
+  const step = id ? await run(['plugin', 'configure', id, '--file', made.file, ...p]) : await run(['plugin', 'add', 'mcp', '--name', name, '--file', made.file, ...p])
+  if (!step.ok) return step
+  id ??= (await find())?.id
+  if (!id) return { ok: false, output: `error [NOT_FOUND]: the stand-in ${name} was added but is not listed` }
+  const open = await run(['plugin', 'policy', id, '--enable', '--actions', 'allow_all', '--new-capability', 'enabled', ...p])
+  const lines = platformOnly
+    ? [`  analytics Plugin ${name}: ${standInTools(project.root, name).length} tools, each answering that analytics tools stay on the platform`, `  warning: ${ANALYTICS_STAY}`]
+    : doc.serves === 'documentation'
+    ? [`  ${doc.connection}: ${standInTools(project.root, name).length} tools, serving the documentation of this runtime’s release`]
+    : [`  stand-in for ${doc.connection}: ${standInTools(project.root, name).length} tools, each answering “not connected”`, `  warning: ${standInAdaptation(doc.connection)}`]
+  if (!open.ok) lines.push(`  warning: The stand-in ${name}’s tools could not be switched on: ${open.output.trim().split('\n')[0]}`)
+  return { ok: true, output: lines.join('\n') }
+}
+
+/**
+ * A workflow's Plugin triggers on a connection the project has a stand-in
+ * for: a stand-in answers tools, not events, so the trigger is left out (the
+ * workflow still runs by hand, from an Agent, or from its other triggers).
+ * Changes `doc`; returns each as a warning.
+ */
+export function dropStandInTriggers(root: string, doc: unknown, names: ReadonlySet<string>): string[] {
+  const d = (doc ?? {}) as Record<string, unknown>
+  if (!names.size || !Array.isArray(d.trigger)) return []
+  const out: string[] = []
+  d.trigger = (d.trigger as Array<Record<string, unknown>>).filter((t) => {
+    const name = t?.kind === 'plugin' && typeof t.resourceId === 'string' && t.resourceId.startsWith('plugin/') ? t.resourceId.slice('plugin/'.length) : null
+    if (!name || !names.has(name)) return true
+    const event = typeof t.event === 'string' ? t.event : ''
+    if (isPlatformOnly(root, name) && !readStandIn(root, name)) {
+      out.push(`  warning: Its Plugin trigger ${event} is left out here: ${ANALYTICS_STAY}`.replace('trigger  is', 'trigger is'))
+      return false
+    }
+    const connection = readStandIn(root, name)?.connection ?? name
+    out.push(`  warning: Its Plugin trigger ${event} is left out here: ${connection} isn’t connected here, and its stand-in answers tools, not events`.replace('trigger  is', 'trigger is'))
+    return false
+  })
+  return out
+}
+
+/**
+ * A local Agent is a draft, and a draft runs the MCP servers its own list
+ * names (`mcpServers`), not its Plugin installs: each connection it uses
+ * that has a stand-in gets the stand-in's server in that list. Changes `doc`.
+ */
+export function addStandInServers(project: LocalProject, doc: Record<string, unknown>, names: ReadonlySet<string>): void {
+  if (!names.size || !Array.isArray(doc.appInstalls)) return
+  const servers = Array.isArray(doc.mcpServers) ? (doc.mcpServers as Array<Record<string, unknown>>) : []
+  for (const row of doc.appInstalls as Array<Record<string, unknown>>) {
+    const name = typeof row?.installId === 'string' && row.installId.startsWith('plugin/') ? row.installId.slice('plugin/'.length) : null
+    if (!name || !names.has(name)) continue
+    const url = standInUrl(project, name)
+    if (!url) continue
+    // The workspace's own server for it (the Documentation plugin's, at the platform's address) points here instead.
+    const listed = servers.find((s) => s?.name === name)
+    if (listed) {
+      listed.transportType = 'http'
+      listed.url = url
+      delete listed.headers
+      continue
+    }
+    servers.push({ name, transportType: 'http', url, enabled: row.enabled !== false, autoStage: false, toonCompression: false })
+  }
+  if (servers.length) doc.mcpServers = servers
+}
+
+/** The Plugin file a stand-in is installed from: the runtime's own address for it, nothing secret. */
+export function standInPluginFile(project: LocalProject, name: string): { file: string; url: string } | null {
+  const url = standInUrl(project, name)
+  if (!url) return null
+  const file = join('.frontera', 'local', 'resolved', 'mcp', `${name}.plugin.json`)
+  mkdirSync(join(project.root, dirname(file)), { recursive: true })
+  writeFileSync(join(project.root, file), `${JSON.stringify({ transport: 'http', url }, null, 2)}\n`)
+  return { file, url }
+}

package/src/local/local-studio-server.ts

@@ -5,10 +5,14 @@ import { extname, join, normalize } from 'node:path'
 import type { LocalProject } from './local-project'
 import { AgentFileError, saveAgentEdit, type AgentFileEdit } from './local-agent-files'
 import { solutionStatus } from './local-applied'
+import { projectBlueprintOutline } from './local-blueprint-outline'
+import { itemBuild } from './local-build-summary'
 import { logPath, readApplied, readState, type ComponentName } from './local-state'
 import { appendTestCase, renderTestCase } from './local-test-cases'
 import { findCaseFiles } from './local-test-runner'
 import { createTestRuns } from './local-test-runs'
+import { docsCopyPath } from './local-docs'
+import { standInMcp } from './local-stand-ins'
 
 /**
  * Frontera Studio's server: the static app, the API, and the runtime's own
@@ -18,7 +22,9 @@ import { createTestRuns } from './local-test-runs'
  * Three rules shape it:
  * - It binds to 127.0.0.1 only, and every request needs the session cookie
  *   that the printed `?token=` link sets. "No auth configured means public" is
- *   the pattern we are deliberately not copying.
+ *   the pattern we are deliberately not copying. The one exception is a
+ *   built-in connection's stand-in (`/__stand-in/<name>/mcp`), which the
+ *   service calls: it lists tool names and answers "not connected", nothing else.
  * - The browser never sees a credential. `/api/*` is proxied to the local
  *   service with the seeded owner's session added here, so the API explorer
  *   and every Studio view call the real API exactly as the platform does.
@@ -113,6 +119,16 @@ export function startStudioServer(opts: StudioServerOptions) {
     if (url.pathname === '/__local/solution') {
       return json({ items: solutionStatus(project, readState(project)?.credentials?.organizationId ?? null) })
     }
+    // How the last `local dev` built one item (`?ref=agent/desk`), with each adaptation in words: the Agent page says it.
+    if (url.pathname === '/__local/build') {
+      const ref = url.searchParams.get('ref') ?? ''
+      if (!/^[a-z-]+\/[A-Za-z0-9][\w./-]{0,200}$/.test(ref)) return json({ error: 'name an item, as agent/<slug>' }, 400)
+      return json({ build: itemBuild(project.root, ref, project.id) })
+    }
+    // The Blueprint's definitions as the files state them, so they show before anything is applied.
+    if (url.pathname === '/__local/blueprint') {
+      return json({ objectTypes: projectBlueprintOutline(project.root) })
+    }
     // The solution's saved cases (`agents/<slug>/evals/*.yaml`), read fresh each time.
     if (url.pathname === '/__local/test-cases') {
       try {
@@ -265,6 +281,11 @@ export function startStudioServer(opts: StudioServerOptions) {
       }
 
       if (url.pathname === '/__local/health') return json({ ok: true })
+      // A built-in connection's stand-in (`local-stand-ins.ts`), which the runtime's service calls as an MCP
+      // server: it holds and reaches nothing, and answers every tool with "not connected", so it takes no session.
+      // The Documentation plugin's serves the release's customer documentation, which is public to every reader.
+      const standIn = /^\/__stand-in\/([A-Za-z0-9._-]+)\/mcp$/.exec(url.pathname)
+      if (standIn) return standInMcp(project.root, standIn[1]!, req, docsCopyPath(project))
 
       const cookie = cookieToken(req)
       if (!cookie || !sameToken(cookie, opts.sessionToken)) {
@@ -284,7 +305,7 @@ export function startStudioServer(opts: StudioServerOptions) {
         const edit = (await req.json().catch(() => null)) as AgentFileEdit | null
         if (!edit || typeof edit !== 'object') return json({ error: 'the edit must be a JSON object' }, 400)
         try {
-          return json(await saveAgentEdit(project, organizationId, decodeURIComponent(editMatch[1]!), edit))
+          return json(await saveAgentEdit(project, organizationId, decodeURIComponent(editMatch[1]!), edit, opts.serviceUrl))
         } catch (err) {
           if (err instanceof AgentFileError) return json({ error: err.message }, err.status)
           return json({ error: (err as Error).message }, 500)