@frontera-sdk/cli 1.53.4 → 1.53.6

package/src/local/local-docker.ts

@@ -1,5 +1,7 @@
 import { spawn, spawnSync } from 'node:child_process'
 import { openSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 
 /**
  * The container runtime, through its CLI.
@@ -67,6 +69,80 @@ export function imagePresent(image: string): boolean {
   return docker(['image', 'inspect', image, '--format', '{{.Id}}']).ok
 }
 
+/** The registry an image comes from: its first part when that names a host, else Docker Hub. */
+export function registryHost(image: string): string {
+  const first = image.split('/')[0]!
+  return image.includes('/') && /[.:]|^localhost$/.test(first) ? first : 'docker.io'
+}
+
+/** Docker Hub answers to three names, and its sign-in is kept under `https://index.docker.io/v1/`. */
+const DOCKER_HUB = new Set(['docker.io', 'index.docker.io', 'registry-1.docker.io'])
+const sameRegistry = (host: string) => (DOCKER_HUB.has(host) ? 'docker.io' : host)
+
+/**
+ * Whether Docker holds a sign-in for a registry host, read as Docker reads it:
+ * `config.json` in `$DOCKER_CONFIG` (else `~/.docker`), then the host's
+ * credential helper or the default store, asked for its `list` (addresses and
+ * user names, never a secret), else the file's own `auths`. False when none
+ * is found or it can't be read; nothing here prompts.
+ */
+export function dockerSignedIn(host: string): boolean {
+  let config: { auths?: Record<string, { auth?: string; identitytoken?: string } | null>; credHelpers?: Record<string, string>; credsStore?: string }
+  try {
+    config = JSON.parse(readFileSync(join(process.env.DOCKER_CONFIG || join(homedir(), '.docker'), 'config.json'), 'utf8'))
+  } catch {
+    return false
+  }
+  const isHost = (address: string) => sameRegistry(address.replace(/^https?:\/\//, '').split('/')[0]!) === sameRegistry(host)
+  const helper = Object.entries(config.credHelpers ?? {}).find(([address]) => isHost(address))?.[1] ?? config.credsStore
+  if (!helper) return Object.entries(config.auths ?? {}).some(([address, entry]) => isHost(address) && !!(entry?.auth || entry?.identitytoken))
+  // A name with a slash would run a program by path (`../evil` from the folder), not a helper on PATH.
+  if (!/^[A-Za-z0-9._-]+$/.test(helper)) return false
+  const listed = spawnSync(`docker-credential-${helper}`, ['list'], { input: 'unused', encoding: 'utf8', timeout: 5_000 })
+  if (listed.status !== 0) return false
+  try {
+    return Object.keys(JSON.parse(listed.stdout) as Record<string, string>).some(isHost)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Why a pull failed, decided once from its output and Docker's sign-in for
+ * the registry. `signed-out`: refused, with no sign-in Docker shows, so
+ * signing in is the fix. `no-access`: refused although Docker is signed in,
+ * so only someone who grants access can clear it. `missing`: the image or
+ * tag is not there. `other`: anything else, in the log.
+ */
+export type PullFailure = 'signed-out' | 'no-access' | 'missing' | 'other'
+
+export class PullError extends DockerError {
+  constructor(
+    readonly failure: PullFailure,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+function pullFailureMessage(failure: PullFailure, image: string, code: number | null, logFile: string): string {
+  const host = registryHost(image)
+  switch (failure) {
+    case 'signed-out':
+      return host === 'ghcr.io'
+        ? `the registry refused access to ${image}: run \`gh auth refresh -s read:packages\`, then \`gh auth token | docker login ghcr.io -u <github-user> --password-stdin\`, or run from a platform checkout without --image`
+        : `the registry refused access to ${image}: sign in with \`docker login ${host}\`, or run from a platform checkout without --image`
+    case 'no-access':
+      return host === 'ghcr.io'
+        ? `the registry refused ${image}, though Docker is signed in to ghcr.io. The GitHub account it signed in with has no read access to the organization's packages, or its sign-in no longer works. Ask an organization owner to grant that account read access, or run from a platform checkout without --image`
+        : `the registry refused ${image}, though Docker is signed in to ${host}. The account it signed in with may not pull it, or its sign-in no longer works. Ask an owner of ${host} to grant that account pull access, or run from a platform checkout without --image`
+    case 'missing':
+      return `${image} is not in the registry: check --registry and --version, or push that release there first`
+    case 'other':
+      return `docker pull ${image} failed (exit ${code}); see ${logFile}`
+  }
+}
+
 /** Pull an image, writing progress to a log file instead of the terminal. */
 export function pullImage(image: string, logFile: string): Promise<void> {
   return new Promise((resolvePromise, reject) => {
@@ -75,23 +151,21 @@ export function pullImage(image: string, logFile: string): Promise<void> {
     child.on('error', reject)
     child.on('exit', (code) => {
       if (code === 0) return resolvePromise()
-      // The private release images are the usual failure: say what grants access.
       let tail = ''
       try {
         tail = readFileSync(logFile, 'utf8').slice(-2000)
       } catch {
         // The log is a convenience; the exit code is the fact.
       }
-      const denied = /unauthorized|denied|authentication required/i.test(tail)
-      const host = image.split('/')[0]
-      const reason = denied
-        ? image.startsWith('ghcr.io/')
-          ? `the registry refused access to ${image}: run \`gh auth refresh -s read:packages\`, then \`gh auth token | docker login ghcr.io -u <github-user> --password-stdin\`, or run from a platform checkout without --image`
-          : `the registry refused access to ${image}: sign in with \`docker login ${host}\`, or run from a platform checkout without --image`
+      // The words don't tell no sign-in from a sign-in without access (ghcr.io answers `denied` to a token that no longer works); Docker's own sign-in does.
+      const failure: PullFailure = /unauthorized|denied|authentication required/i.test(tail)
+        ? dockerSignedIn(registryHost(image))
+          ? 'no-access'
+          : 'signed-out'
         : /manifest unknown|not found/i.test(tail)
-          ? `${image} is not in the registry: check --registry and --version, or push that release there first`
-          : `docker pull ${image} failed (exit ${code}); see ${logFile}`
-      reject(new DockerError(reason))
+          ? 'missing'
+          : 'other'
+      reject(new PullError(failure, pullFailureMessage(failure, image, code, logFile)))
     })
   })
 }

package/src/local/local-mcp-servers.ts

@@ -2,7 +2,11 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { parse as parseYaml } from 'yaml'
 
+import { CliError } from '../errors'
 import { errorOf } from './local-chat-apps'
+import { allTargets } from './local-dev-sync'
+import { localProjectAt } from './local-project'
+import { getSyncKey, readLink, type SyncLink } from './local-sync-link'
 
 /**
  * A workspace's own MCP servers: `mcp-servers/<slug>.yaml` (or .yml, .json),
@@ -12,6 +16,11 @@ import { errorOf } from './local-chat-apps'
  * types the workspace is granted, its Functions, workflows and governed
  * Actions. A server whose file is deleted is archived on the runtime.
  *
+ * A change request carries no MCP servers: `frontera mcp-server save` sends
+ * the same file with the same request to the workspace the project is linked
+ * to (`local sync connect`), with its workspace key, as `local sync push`
+ * reaches it; to the profile's workspace in a project with no link.
+ *
  * Its format is the service's (`frontera local schema mcp-server`).
  */
 
@@ -24,45 +33,101 @@ export interface McpServerApplied {
   output: string
 }
 
-interface SavedServer {
+export interface SavedServer {
   server?: { slug?: string; name?: string; url?: string; signIn?: boolean; tools?: unknown[] }
   created?: boolean
   warnings?: Array<{ name?: string; reason?: string }>
 }
 
 /** The file as the service takes it: YAML or JSON, a mapping at the top. */
-export function readMcpServerFile(root: string, file: string): { ok: true; doc: Record<string, unknown> } | { ok: false; output: string } {
+export function readMcpServerFile(root: string, file: string): { ok: true; doc: Record<string, unknown> } | { ok: false; problem: string } {
   const path = join(root, file)
-  if (!existsSync(path)) return { ok: false, output: `error [MCP_SERVER]: ${file} is missing` }
+  if (!existsSync(path)) return { ok: false, problem: `${file} is missing` }
   let doc: unknown
   try {
     const text = readFileSync(path, 'utf8')
     doc = file.endsWith('.json') ? JSON.parse(text) : parseYaml(text)
   } catch (err) {
-    return { ok: false, output: `error [MCP_SERVER]: ${file} can't be read: ${(err as Error).message.split('\n')[0]}` }
+    return { ok: false, problem: `${file} can't be read: ${(err as Error).message.split('\n')[0]}` }
   }
   if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
-    return { ok: false, output: `error [MCP_SERVER]: ${file} must be a mapping with name, instructions and tools (\`frontera local schema mcp-server\`)` }
+    return { ok: false, problem: `${file} must be a mapping with name, instructions and tools (\`frontera local schema mcp-server\`)` }
   }
   return { ok: true, doc: doc as Record<string, unknown> }
 }
 
+/** Where a client connects to a saved server, and each tool offered to nobody for now. */
+export function savedLines(slug: string, saved: SavedServer | null, updated = 'applied'): string[] {
+  const tools = saved?.server?.tools?.length ?? 0
+  const url = saved?.server?.url
+  // A local runtime offers no sign-in: a client there sends the runtime's workspace key.
+  const how = saved?.server?.signIn === false ? " with the runtime's workspace key" : ''
+  const lines = [`  ${saved?.created ? 'created' : updated} MCP server ${slug} (${tools} tool${tools === 1 ? '' : 's'})${url ? ` — connect at ${url}${how}` : ''}`]
+  for (const warning of saved?.warnings ?? []) {
+    lines.push(`  warning: MCP server ${slug}: tool ${warning.name ?? '?'} is offered to nobody for now: ${warning.reason ?? 'unavailable'}`)
+  }
+  return lines
+}
+
 /** Save one server on the runtime; the line says where a client connects, or what the service refused. */
 export async function applyMcpServer(root: string, slug: string, file: string, call: Call): Promise<McpServerApplied> {
   const read = readMcpServerFile(root, file)
-  if (!read.ok) return read
+  if (!read.ok) return { ok: false, output: `error [MCP_SERVER]: ${read.problem}` }
   const res = await call('PUT', `/v1/mcp-servers/${encodeURIComponent(slug)}`, read.doc)
   if (res.status !== 200 && res.status !== 201) {
     return { ok: false, output: `error [MCP_SERVER]: MCP server ${slug} was refused: ${errorOf(res)}` }
   }
   const saved = ((res.body as { data?: unknown } | null)?.data ?? res.body) as SavedServer | null
-  const tools = saved?.server?.tools?.length ?? 0
-  const url = saved?.server?.url
-  // A local runtime offers no sign-in: a client there sends the runtime's workspace key.
-  const how = saved?.server?.signIn === false ? " with the runtime's workspace key" : ''
-  const lines = [`  ${saved?.created ? 'created' : 'applied'} MCP server ${slug} (${tools} tool${tools === 1 ? '' : 's'})${url ? ` — connect at ${url}${how}` : ''}`]
-  for (const warning of saved?.warnings ?? []) {
-    lines.push(`  warning: MCP server ${slug}: tool ${warning.name ?? '?'} is offered to nobody for now: ${warning.reason ?? 'unavailable'}`)
+  return { ok: true, output: savedLines(slug, saved).join('\n') }
+}
+
+/** The project's MCP server files, as `local dev` finds them. */
+export function projectMcpServers(root: string): Array<{ slug: string; file: string }> {
+  return allTargets(root).flatMap((t) => (t.kind === 'mcp-server' ? [{ slug: t.name, file: t.file }] : []))
+}
+
+/** "Orders (ws_1) on acme.frontera.example": the linked workspace in a sentence. */
+function linkedWorkspaceWords(link: SyncLink): string {
+  return `${link.workspaceName ?? link.workspace}${link.workspaceName ? ` (${link.workspace})` : ''} on ${new URL(link.platform).host}`
+}
+
+/**
+ * Where `frontera mcp-server save` sends a linked project's servers: the
+ * linked workspace, with the project's workspace key, which is what `local
+ * sync push` reaches and what its line names. The directory's profile in a
+ * project with a local runtime is the runtime's (`local start` binds it), and
+ * `local dev` already saves the files there. A workspace key acts for its
+ * creator, so the service lets it save a server as it lets `local dev`'s.
+ * Null when the project has no link. With a link and no key on this computer,
+ * refused rather than sent to the profile.
+ */
+export function linkedSaveTarget(root: string): { platform: string; key: string; where: string } | null {
+  const link = readLink(root)
+  if (!link) return null
+  const workspace = linkedWorkspaceWords(link)
+  const key = getSyncKey(localProjectAt(root), 'workspace')
+  if (!key) {
+    throw new CliError(`this project is linked to ${workspace}, and this computer holds no workspace key for it`, {
+      code: 'SYNC_NO_KEY',
+      hint: '`frontera local sync connect` stores one (keys are kept per computer); `--profile <name>` saves to that profile’s workspace instead',
+    })
   }
-  return { ok: true, output: lines.join('\n') }
+  return { platform: link.platform, key, where: `${workspace}, the workspace this project is linked to` }
+}
+
+/**
+ * What a push or `sync status` says of the project's MCP server files, which
+ * no change request carries, with the command that saves them. Null when the
+ * project has none.
+ */
+export function mcpServersNotCarried(root: string): { files: string[]; command: string; line: string } | null {
+  const files = projectMcpServers(root).map((s) => s.file)
+  if (!files.length) return null
+  const command = files.length === 1 ? `frontera mcp-server save ${files[0]}` : 'frontera mcp-server save'
+  const link = readLink(root)
+  const where = link
+    ? `${linkedWorkspaceWords(link)}, the workspace this project is linked to, with its workspace key (\`--profile <name>\` saves to a profile’s workspace instead)`
+    : 'the workspace your profile signs in to (`--profile <name>` picks another)'
+  const line = `A change request does not carry MCP servers (${files.join(', ')}): \`${command}\` saves ${files.length === 1 ? 'it' : 'every one'} to ${where}.`
+  return { files, command, line }
 }

package/src/local/local-person-steps.ts

@@ -25,7 +25,7 @@ import { writeFileAtomic } from '../fs-atomic'
 export const PERSON_STEPS_FILE = join('.frontera', 'sync', 'person-steps.json')
 
 /** Who or what the step needs. */
-export const CREDENTIALS = ['workspace-key', 'organization-key', 'steward', 'admin', 'second-person', 'person'] as const
+export const CREDENTIALS = ['workspace-key', 'organization-key', 'steward', 'admin', 'second-person', 'person', 'registry-owner'] as const
 export type Credential = (typeof CREDENTIALS)[number]
 
 /** Each credential in the person's words, as the card and the list say it. */
@@ -36,6 +36,7 @@ export const CREDENTIAL_WORDS: Record<Credential, string> = {
   admin: 'a workspace admin',
   'second-person': 'a second person (not whoever made the change)',
   person: 'you, signed in (`frontera auth login --browser`)',
+  'registry-owner': 'an owner of the organization that publishes the runtime images',
 }
 
 /**
@@ -67,9 +68,9 @@ export interface PersonStep {
   doneAt?: string
   /** Who saw it done: the person's mark, or its check. */
   doneBy?: 'person' | 'check'
-  /** Where it came from: the coding agent, or what a change request left after Apply. */
-  source?: 'agent' | 'change-request'
-  /** A change request's own key for it (`action-deploy:qualifyLead`), so applying again updates it. */
+  /** Where it came from: the coding agent, what a change request left after Apply, or the local runtime at a refusal only a person clears. */
+  source?: 'agent' | 'change-request' | 'runtime'
+  /** A change request's own key for it (`action-deploy:qualifyLead`), or the runtime's (`image-access:<repository>`), so recording it again updates it. */
   key?: string
   check?: StepCheck
   lastCheckedAt?: string
@@ -133,19 +134,23 @@ function writeSteps(root: string, steps: PersonStep[]): void {
 }
 
 export interface NewPersonStep {
-  command: string
+  /** null for a step done outside the CLI, which only the CLI itself records. */
+  command: string | null
   why: string
   changes: string
   credential: string
   delivery?: string | null
   /** The read that proves it done, already checked (`checkProblem`). */
   check?: StepCheck
+  /** The CLI's own step, under a stable key: recording it again updates that step, and reopens it if it was settled. */
+  key?: string
+  source?: 'agent' | 'runtime'
 }
 
 /** Each problem with a step as given; empty when it can be recorded. */
 export function stepProblems(input: NewPersonStep): string[] {
   const problems: string[] = []
-  const command = commandProblem(input.command)
+  const command = input.command === null ? null : commandProblem(input.command)
   if (command) problems.push(command)
   if (!input.why?.trim()) problems.push('say why the step is needed (`why`)')
   if (!input.changes?.trim()) problems.push('say what the step changes (`changes`)')
@@ -160,17 +165,20 @@ export function stepProblems(input: NewPersonStep): string[] {
 /**
  * Record a step. The same command pending in the same delivery is the same
  * step, updated rather than listed twice, so an agent restating its plan
- * after a compaction doesn't double the card.
+ * after a compaction doesn't double the card. A keyed step is one step
+ * whatever its state: a refusal seen again is pending again.
  */
 export function addPersonStep(root: string, input: NewPersonStep, now = new Date()): { step: PersonStep; updated: boolean } {
   const problems = stepProblems(input)
   if (problems.length) throw new Error(problems.join('; '))
   const steps = readPersonSteps(root)
-  const command = input.command.trim().replace(/\s+/g, ' ')
+  const command = input.command === null ? null : input.command.trim().replace(/\s+/g, ' ')
   const delivery = input.delivery?.trim() || null
-  const same = steps.find((s) => s.status === 'pending' && s.command === command && s.delivery === delivery)
+  const same = input.key ? steps.find((s) => s.key === input.key) : steps.find((s) => s.status === 'pending' && s.command === command && s.delivery === delivery)
   if (same) {
-    Object.assign(same, { why: input.why.trim(), changes: input.changes.trim(), credential: input.credential as Credential, ...(input.check ? { check: input.check } : {}) })
+    Object.assign(same, { why: input.why.trim(), changes: input.changes.trim(), credential: input.credential as Credential, status: 'pending', ...(input.check ? { check: input.check } : {}) })
+    delete same.doneAt
+    delete same.doneBy
     writeSteps(root, steps)
     return { step: same, updated: true }
   }
@@ -184,7 +192,8 @@ export function addPersonStep(root: string, input: NewPersonStep, now = new Date
     delivery,
     status: 'pending',
     createdAt: now.toISOString(),
-    source: 'agent',
+    source: input.source ?? 'agent',
+    ...(input.key ? { key: input.key } : {}),
     ...(input.check ? { check: input.check } : {}),
   }
   writeSteps(root, [...steps, step])
@@ -208,6 +217,15 @@ export function settlePersonStep(root: string, id: string, status: 'done' | 'dis
   return step
 }
 
+/** Mark the pending step recorded under `key` done, seen by the CLI itself (the pull it waited for now works). */
+export function markKeyedStepDone(root: string, key: string, now = new Date()): void {
+  const steps = readPersonSteps(root)
+  const step = steps.find((s) => s.key === key && s.status === 'pending')
+  if (!step) return
+  Object.assign(step, { status: 'done', doneAt: now.toISOString(), doneBy: 'check' })
+  writeSteps(root, steps)
+}
+
 /** Take settled steps off the list; pending ones stay. */
 export function clearSettledSteps(root: string): number {
   const steps = readPersonSteps(root)

package/src/local/local-project.ts

@@ -48,7 +48,11 @@ export function slugify(name: string): string {
 }
 
 export function localProject(cwd: string): LocalProject {
-  const root = findSolutionRoot(cwd)
+  return localProjectAt(findSolutionRoot(cwd))
+}
+
+/** The local project rooted at `root` itself, with no walk up. */
+export function localProjectAt(root: string): LocalProject {
   const hash = createHash('sha256').update(root).digest('hex').slice(0, 8)
   return {
     root,

package/src/local/local-supervisor.ts

@@ -9,7 +9,9 @@ import {
   execInContainer,
   followLogs,
   imagePresent,
+  PullError,
   pullImage,
+  registryHost,
   removeContainer,
   runContainer,
   startContainer,
@@ -33,6 +35,7 @@ import {
   type LocalSecrets,
 } from './local-env'
 import { runtimeKeyCustodianProblem } from './local-key-custodian'
+import { addPersonStep, markKeyedStepDone } from './local-person-steps'
 import { localEmbeddingsReachable, providerEnv } from './local-keys'
 import { applyProviderSetup, readProviderSetup, rememberSlugs, writeProviderSetup } from './local-providers'
 import type { PortBlock } from './local-ports'
@@ -325,9 +328,44 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
 
 type SetFn = (name: ComponentName, patch: Partial<ComponentState>) => void
 
-async function ensureImage(image: string, project: LocalProject, component: ComponentName): Promise<void> {
-  if (imagePresent(image)) return
-  await pullImage(image, logPath(project, component))
+/**
+ * Every image the runtime runs comes through here. A pull refused for want of
+ * access is the person's step, recorded without the agent choosing to:
+ * one per image repository, so a retry finds the same step, and done once an
+ * image from that repository is on the machine.
+ */
+export async function ensureImage(image: string, project: LocalProject, component: ComponentName): Promise<void> {
+  const repository = image.replace(/:[^/:]*$/, '')
+  const key = `image-access:${repository}`
+  if (!imagePresent(image)) {
+    try {
+      await pullImage(image, logPath(project, component))
+    } catch (err) {
+      if (!(err instanceof PullError) || err.failure !== 'no-access') throw err
+      const host = registryHost(image)
+      const ghcr = host === 'ghcr.io'
+      try {
+        addPersonStep(project.root, {
+          key,
+          source: 'runtime',
+          command: null,
+          credential: 'registry-owner',
+          changes: ghcr ? `Read access for your GitHub account to the organization's package ${repository}` : `Pull access for your account on ${host} to ${repository}`,
+          why: [
+            `Docker is signed in to ${host}, and the registry still refused ${image}, so the local runtime can't start from it.`,
+            ghcr ? "Ask an organization owner to grant the GitHub account Docker signed in with read access to the organization's packages." : `Ask an owner of ${host} to grant the account Docker signed in with pull access.`,
+            `If the account already has access, its sign-in no longer works: sign Docker in to ${host} again.`,
+            'The next `frontera local start --image` that pulls the image marks this step done. Without access, run from a platform checkout without --image.',
+          ].join(' '),
+        })
+      } catch {
+        // Not recorded (200 steps already pending): the refusal still says what to do.
+        throw err
+      }
+      throw new PullError('no-access', `${err.message}. This is the person's step; \`frontera local steps\` lists it`)
+    }
+  }
+  markKeyedStepDone(project.root, key)
 }
 
 /**

package/src/local/local-sync-remote.ts

@@ -578,6 +578,22 @@ export async function agentOperatingConfig(
   return { config, notes }
 }
 
+/**
+ * The Knowledge app's bases an Agent searches are platform settings, not part
+ * of its files: a local runtime has no Knowledge app, and a base belongs to
+ * one installation. Said, so what the Agent answers locally is not taken for
+ * what it answers on the platform. Nothing to say where the platform has no
+ * Knowledge app, the Agent searches none, or the route is not there.
+ */
+export async function knowledgeBasesNote(source: SyncSource, agentId: string): Promise<string | null> {
+  const answer = await source.workspace.get(`/v1/config/agents/${encodeURIComponent(agentId)}/knowledge-bases`).catch(() => null)
+  const bases = answer ? one<{ bases?: Array<{ name?: unknown; searched?: unknown }> } | null>(answer)?.bases ?? [] : []
+  const names = bases.filter((base) => base.searched === true && typeof base.name === 'string').map((base) => `“${base.name as string}”`)
+  if (!names.length) return null
+  const which = names.length === 1 ? `the knowledge base ${names[0]}` : `${names.length} knowledge bases (${names.join(', ')})`
+  return `Searches ${which} from the Knowledge app on the platform. A local runtime has no Knowledge app, so here it answers without them: test this Agent’s Knowledge on the platform`
+}
+
 /** An Agent's record (`/v1/config/agents/:id`): its published version, and its behavior settings, scrubbed. */
 interface AgentDetail { currentVersion?: { versionNumber?: number } | null; operatingConfig?: unknown }
 
@@ -632,6 +648,8 @@ async function readAgents(source: SyncSource, lists: Lists, directory: Directory
       it.notes.push(`Its Context and data couldn’t be read on the platform: ${context.unread}. Until it can be read, local dev gives it read access to the object types the project holds, as an adaptation, so locally it may read more than on the platform`)
     }
     if (bound.functions.length || bound.workflows.length || bound.blueprint?.length || bound.blueprintUnread) docs.push({ path: `agents/${row.agentId}/bindings.json`, doc: bound, format: 'json' })
+    const knowledgeBases = await knowledgeBasesNote(source, row.id)
+    if (knowledgeBases) it.notes.push(knowledgeBases)
     await nameUnknownAgents(source, directory, docs)
     out.push(finish(it, directory, docs))
   }

package/src/main.ts

@@ -9,6 +9,7 @@ import { EXIT, sessionLaneFailure, sessionLaneRefusal, type ExitCode } from './e
 import { actAsLocalPersona, listPersonas, localPersonaHint, redact } from './local/local-personas'
 import { localRuntimeAt } from './local/local-runtime-target'
 import { acquireLock, lockRefusal, locksRuntime, projectStateDir, recordWrite, writeCommand } from './local/local-writers'
+import { tokenFromStdin } from './mcp/mcp-apps'
 import { resolveOrganization, setSelectedOrganization } from './organization'
 import { canPrompt, promptConfirm } from './prompt'
 import { remoteFromLocalProject, remoteWords } from './remote-guard'
@@ -228,6 +229,10 @@ async function main(): Promise<number> {
     // project are always read from one place. Two directories would mean
     // `--dir ../other-customer` could edit one customer's app with another
     // customer's key.
+    //
+    // The `frontera app dev` that `--detach` starts takes its caller's key on stdin, used as FRONTERA_TOKEN
+    // would be, so it is never in the environment the App's own server inherits.
+    const piped = await tokenFromStdin()
     let credential = command.meta.offline
       ? { apiUrl: typeof flags['api-url'] === 'string' ? flags['api-url'] : (process.env.FRONTERA_API_URL ?? ''), token: '' }
       : await resolveCredential(
@@ -237,7 +242,7 @@ async function main(): Promise<number> {
             // In a local project, an organization command takes the runtime's organization key.
             organization: commandScope(command.meta) === 'organization' && command.meta.noun !== 'auth' && command.meta.noun !== 'kit',
           },
-          { cwd },
+          { cwd, ...(piped ? { env: { ...process.env, FRONTERA_TOKEN: piped } } : {}) },
         )
     // A command that acts as a person takes the browser sign-in (`auth login --browser`) over the
     // profile's key, which it would refuse; nothing else does. A raw FRONTERA_TOKEN still wins.