@frontera-sdk/cli 1.52.22 → 1.52.24

package/src/local/local-schemas.ts

@@ -0,0 +1,301 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+import type { LocalProject } from './local-project'
+import { isAlive, readState } from './local-state'
+
+/**
+ * The formats of a project's files, as JSON Schema, for the coding agents and
+ * editors working in it (`frontera local schema <kind>`).
+ *
+ * The service checks three of them, so their schemas come from the service
+ * the runtime runs (`GET /v1/config/file-schemas/<kind>`), made from the same
+ * zod schemas that check the files. The other two only this CLI reads, so it
+ * describes them itself, beside the code that reads them. `local start` writes
+ * all five into `.frontera/local/schemas/` once the service is up, so they can
+ * be read while the runtime is stopped and always describe the release it ran.
+ */
+
+export const SCHEMA_KINDS = ['operating', 'agent', 'workflow', 'evals', 'dataset'] as const
+export type SchemaKind = (typeof SCHEMA_KINDS)[number]
+
+/** Where each kind of file lives in a project. */
+export const SCHEMA_FILES: Record<SchemaKind, string> = {
+  operating: 'agents/<slug>/operating.json',
+  agent: 'agents/<slug>/agent.json',
+  workflow: 'workflows/<slug>.yaml',
+  evals: 'agents/<slug>/evals/*.yaml',
+  dataset: 'datasets/<apiName>.json',
+}
+
+export function isSchemaKind(value: string): value is SchemaKind {
+  return (SCHEMA_KINDS as readonly string[]).includes(value)
+}
+
+const DRAFT = 'https://json-schema.org/draft/2020-12/schema'
+
+type JsonSchema = Record<string, unknown>
+
+/** `agents/<slug>/evals/*.yaml`, as `local test` and Studio read it (`local-test-runner.ts`). */
+const EVALS_SCHEMA: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Agent test cases (agents/<slug>/evals/*.yaml)',
+  description:
+    "`frontera local test` and Studio's Evaluations run each case on the Agent's draft (`--live`: its live version): a new conversation, the user turns sent in order, then the last reply checked.",
+  type: 'object',
+  properties: {
+    cases: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', minLength: 1, description: 'Names the case in results.' },
+          conversation: {
+            type: 'array',
+            minItems: 1,
+            description: 'One turn per item. Only the user turns are sent; an assistant turn is kept for whoever reads the case.',
+            items: {
+              type: 'object',
+              properties: { user: { type: 'string' }, assistant: { type: 'string' } },
+              minProperties: 1,
+              maxProperties: 1,
+              additionalProperties: false,
+            },
+          },
+          expected: { type: 'string', description: 'The last reply, word for word; differences in whitespace are ignored.' },
+          expectedContains: {
+            type: 'array',
+            minItems: 1,
+            items: { type: 'string', minLength: 1 },
+            description: 'Phrases the last reply must contain, ignoring case. When present, expected is not checked.',
+          },
+          savedFrom: { type: 'string', description: 'Where the case was saved from; Studio writes it.' },
+        },
+        required: ['name', 'conversation'],
+        anyOf: [{ required: ['expected'] }, { required: ['expectedContains'] }],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['cases'],
+  additionalProperties: false,
+}
+
+/** The column types `dataset create` accepts (`commands/dataset/index-commands.ts`). */
+const COLUMN_TYPES = ['text', 'numeric', 'boolean', 'date', 'timestamptz']
+
+const COLUMN_NAMES = {
+  type: 'array',
+  minItems: 1,
+  maxItems: 256,
+  items: { type: 'string', minLength: 1 },
+  description: 'The columns to load, by name.',
+}
+
+/** Every kind of dataset definition reads these. */
+const DATASET_COMMON = {
+  apiName: {
+    type: 'string',
+    minLength: 1,
+    maxLength: 100,
+    description: "How an object type's backing.dataset and `frontera blueprint bind` name the dataset.",
+  },
+  displayName: { type: 'string', minLength: 1, maxLength: 200, description: 'Defaults to apiName.' },
+  description: { type: 'string', maxLength: 4000 },
+  keyColumns: {
+    anyOf: [{ type: 'array', minItems: 1, maxItems: 16, items: { type: 'string', minLength: 1 } }, { type: 'null' }],
+    description: 'The columns that identify a row, or null when none does.',
+  },
+  deterministicKeyConfirmed: {
+    type: 'boolean',
+    description: 'Confirms that keyColumns identify every row uniquely. Ignored without keyColumns.',
+  },
+}
+
+/** `datasets/<apiName>.json`, as `dataset create` reads it (`commands/dataset/index-commands.ts`). */
+const DATASET_SCHEMA: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Dataset definition (datasets/<apiName>.json)',
+  description:
+    'Data the Blueprint reads. kind says where the columns come from: blank declares them, file reads a CSV, source pulls a relation from a connected Source. A key another kind reads is refused.',
+  type: 'object',
+  oneOf: [
+    {
+      title: 'blank',
+      type: 'object',
+      properties: {
+        ...DATASET_COMMON,
+        kind: { const: 'blank', description: 'The default: columns only, no rows.' },
+        columns: {
+          type: 'array',
+          minItems: 1,
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', pattern: '^[a-z_][a-z0-9_]*$' },
+              databaseType: { type: 'string', enum: COLUMN_TYPES },
+              nullable: {
+                type: 'boolean',
+                description: 'Whether the column may hold nulls. A required Blueprint property may not read a nullable column that holds them.',
+              },
+            },
+            required: ['name', 'databaseType', 'nullable'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['apiName', 'columns'],
+      additionalProperties: false,
+    },
+    {
+      title: 'file',
+      type: 'object',
+      properties: {
+        ...DATASET_COMMON,
+        kind: { const: 'file' },
+        path: { type: 'string', minLength: 1, description: 'The CSV, relative to this file.' },
+        includedColumns: COLUMN_NAMES,
+      },
+      required: ['apiName', 'kind', 'path', 'includedColumns'],
+      additionalProperties: false,
+    },
+    {
+      title: 'source',
+      type: 'object',
+      properties: {
+        ...DATASET_COMMON,
+        kind: { const: 'source' },
+        source: { type: 'string', minLength: 1, description: 'The connected Source, by its display name.' },
+        schema: { type: 'string', minLength: 1 },
+        relation: { type: 'string', minLength: 1 },
+        includedColumns: COLUMN_NAMES,
+      },
+      required: ['apiName', 'kind', 'source', 'schema', 'relation', 'includedColumns'],
+      additionalProperties: false,
+    },
+  ],
+}
+
+/** The schema this CLI owns for a kind, or null when the service owns it. */
+export function cliSchema(kind: SchemaKind): JsonSchema | null {
+  if (kind === 'evals') return EVALS_SCHEMA
+  if (kind === 'dataset') return DATASET_SCHEMA
+  return null
+}
+
+export function schemasDir(project: LocalProject): string {
+  return join(project.stateDir, 'schemas')
+}
+
+export function schemaPath(project: LocalProject, kind: SchemaKind): string {
+  return join(schemasDir(project), `${kind}.schema.json`)
+}
+
+/** How to reach the running runtime's service: its URL and a credential it accepts. */
+export interface SchemaSource {
+  serviceUrl: string
+  token: string
+}
+
+/** The running runtime, or null when it is stopped, still starting, or not seeded. */
+export function runtimeSource(project: LocalProject): SchemaSource | null {
+  const state = readState(project)
+  if (!state || state.phase !== 'ready' || !state.supervisorPid || !isAlive(state.supervisorPid)) return null
+  const token = state.credentials?.workspaceKey ?? state.credentials?.session
+  return token ? { serviceUrl: `http://127.0.0.1:${state.ports.service}`, token } : null
+}
+
+type Fetched = { ok: true; schema: JsonSchema } | { ok: false; status: number; reason: string }
+
+/** One kind's schema from the runtime's service. */
+export async function fetchServiceSchema(source: SchemaSource, kind: SchemaKind): Promise<Fetched> {
+  try {
+    const res = await fetch(new URL(`/v1/config/file-schemas/${kind}`, source.serviceUrl), {
+      headers: { authorization: `Bearer ${source.token}` },
+      signal: AbortSignal.timeout(10_000),
+    })
+    const text = await res.text()
+    let body: { data?: { schema?: unknown }; message?: string } | null = null
+    try {
+      body = text ? JSON.parse(text) : null
+    } catch {
+      // Not JSON: reported by status below.
+    }
+    const schema = body?.data?.schema
+    if (res.ok && schema && typeof schema === 'object') return { ok: true, schema: schema as JsonSchema }
+    if (res.status === 404) return { ok: false, status: 404, reason: "the runtime's service does not describe its files (it predates file formats)" }
+    return { ok: false, status: res.status, reason: `the service answered ${res.status}${body?.message ? `: ${body.message}` : ''}` }
+  } catch (err) {
+    return { ok: false, status: 0, reason: `the service did not answer: ${(err as Error).message}` }
+  }
+}
+
+/** A schema `local start` kept, or null. */
+export function readKeptSchema(project: LocalProject, kind: SchemaKind): JsonSchema | null {
+  const path = schemaPath(project, kind)
+  if (!existsSync(path)) return null
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8')) as unknown
+    return value && typeof value === 'object' && !Array.isArray(value) ? (value as JsonSchema) : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Write every kind's schema into the project's state, for the release the
+ * runtime runs. Returns what could not be written; never throws, so it cannot
+ * fail a start. A kind the service did not answer for is removed rather than
+ * kept, so a file never describes a release other than the one that ran.
+ */
+export async function keepSchemas(project: LocalProject, source: SchemaSource): Promise<string[]> {
+  const problems: string[] = []
+  for (const kind of SCHEMA_KINDS) {
+    try {
+      let schema = cliSchema(kind)
+      if (!schema) {
+        const fetched = await fetchServiceSchema(source, kind)
+        if (fetched.ok) schema = fetched.schema
+        else problems.push(`${kind}: ${fetched.reason}`)
+      }
+      if (schema) writeFileAtomic(schemaPath(project, kind), `${JSON.stringify(schema, null, 2)}\n`, 0o644)
+      else rmSync(schemaPath(project, kind), { force: true })
+    } catch (err) {
+      problems.push(`${kind}: ${(err as Error).message}`)
+    }
+  }
+  return problems
+}
+
+export type SchemaAnswer =
+  | { ok: true; schema: JsonSchema; from: 'cli' | 'runtime' | 'kept'; note?: string }
+  | { ok: false; reason: string; hint: string }
+
+/**
+ * The schema for a kind: the CLI's own, or the running runtime's, or, with the
+ * runtime stopped or not answering, the one its last start kept.
+ */
+export async function resolveSchema(project: LocalProject, kind: SchemaKind, source: SchemaSource | null): Promise<SchemaAnswer> {
+  const own = cliSchema(kind)
+  if (own) return { ok: true, schema: own, from: 'cli' }
+  const kept = readKeptSchema(project, kind)
+  if (!source) {
+    if (kept) return { ok: true, schema: kept, from: 'kept', note: 'The local runtime is not running: this is the format of the release it ran last.' }
+    return {
+      ok: false,
+      reason: `no ${kind} format here yet: the local runtime is not running, and no start has kept one`,
+      hint: 'run `frontera local start` once; it keeps the formats of the release it runs in .frontera/local/schemas/',
+    }
+  }
+  const fetched = await fetchServiceSchema(source, kind)
+  if (fetched.ok) return { ok: true, schema: fetched.schema, from: 'runtime' }
+  if (kept) return { ok: true, schema: kept, from: 'kept', note: `The local runtime did not answer (${fetched.reason}): this is the format its last start kept.` }
+  return {
+    ok: false,
+    reason: `the ${kind} format is not available: ${fetched.reason}`,
+    hint: fetched.status === 404
+      ? 'restart the runtime so it runs a service that does: `frontera local stop`, then `frontera local start`'
+      : 'see `frontera local logs service`, or `frontera local status`',
+  }
+}

package/src/local/local-seed.ts

@@ -0,0 +1,332 @@
+import { appendFileSync } from 'node:fs'
+
+import { findProvider, getKey, keylessEmbeddings, LOCAL_PROVIDERS } from './local-keys'
+import type { LocalCredentials } from './local-state'
+
+/**
+ * Seed a fresh local runtime over its own HTTP API.
+ *
+ * The same sequence a person goes through, so the organization gets its roles,
+ * its `General` workspace and its Blueprint Steward from the service's own
+ * bootstrap instead of rows written behind its back (which is why the
+ * database-level seed scripts are not used here):
+ *
+ *   sign up → sign in → create organization (bootstraps the workspace)
+ *   → workspace key (`sk-ws-`, `mcp` scope) → organization key (`sk-org-`)
+ *
+ * Model keys are applied on every start, not only at seed time, because an
+ * organization's model calls read only the organization's own stored
+ * credential — never the process environment — and an FDE may have added a
+ * key since the last start.
+ */
+
+export const OWNER_EMAIL = 'owner@frontera.local'
+
+interface SeedArgs {
+  serviceUrl: string
+  password: string
+  databaseUrl: string
+  logFile: string
+}
+
+class SeedError extends Error {}
+
+function log(file: string, line: string) {
+  try {
+    appendFileSync(file, `[local-seed] ${line}\n`)
+  } catch {
+    // Logging must never fail the seed.
+  }
+}
+
+export async function call<T>(serviceUrl: string, path: string, init: { method?: string; body?: unknown; token?: string; orgId?: string; workspaceId?: string } = {}): Promise<{ status: number; body: T; headers: Headers }> {
+  const headers: Record<string, string> = { 'content-type': 'application/json' }
+  if (init.token) headers.authorization = `Bearer ${init.token}`
+  if (init.orgId) headers['x-org-id'] = init.orgId
+  if (init.workspaceId) headers['x-workspace-id'] = init.workspaceId
+  const res = await fetch(new URL(path, serviceUrl), {
+    method: init.method ?? (init.body === undefined ? 'GET' : 'POST'),
+    headers,
+    body: init.body === undefined ? undefined : JSON.stringify(init.body),
+    signal: AbortSignal.timeout(60_000),
+  })
+  const text = await res.text()
+  let body: unknown = text
+  try {
+    body = text ? JSON.parse(text) : null
+  } catch {
+    // Not JSON; keep the text for the error message.
+  }
+  return { status: res.status, body: body as T, headers: res.headers }
+}
+
+function expect(ok: boolean, what: string, status: number, body: unknown): void {
+  if (!ok) throw new SeedError(`${what} failed (${status}): ${JSON.stringify(body).slice(0, 300)}`)
+}
+
+export async function signIn(serviceUrl: string, password: string): Promise<string> {
+  const res = await call<{ token?: string }>(serviceUrl, '/api/auth/sign-in/email', { body: { email: OWNER_EMAIL, password } })
+  const token = res.body?.token ?? res.headers.get('set-auth-token') ?? undefined
+  expect(res.status === 200 && !!token, 'sign-in', res.status, res.body)
+  return token!
+}
+
+/**
+ * The organization key for the local profile: every capability the owner may
+ * delegate, in the seeded workspace too. The runtime is one person's, on their
+ * machine, so the key is as capable as they are; the service still refuses
+ * what no key may hold.
+ */
+async function mintOrgKey(serviceUrl: string, token: string, organizationId: string, workspaceId: string): Promise<string> {
+  const caps = await call<{ data?: Array<{ resource: string; actions: Array<{ action: string; held: boolean }> }> }>(
+    serviceUrl,
+    '/v1/org/api-keys/capabilities',
+    { token, orgId: organizationId },
+  )
+  expect(Array.isArray(caps.body?.data), 'list the delegable capabilities', caps.status, caps.body)
+  const permissions: Record<string, string[]> = {}
+  for (const group of caps.body.data!) {
+    const held = group.actions.filter((a) => a.held).map((a) => a.action)
+    if (held.length) permissions[group.resource] = held
+  }
+  const expiresAt = new Date(Date.now() + 360 * 24 * 3600 * 1000).toISOString()
+  const mint = () =>
+    call<{ data?: { key?: string }; message?: string }>(serviceUrl, '/v1/org/api-keys', {
+      token,
+      orgId: organizationId,
+      body: { name: 'Local runtime', permissions, workspaceIds: [workspaceId], expiresAt },
+    })
+  let res = await mint()
+  // `held` is the owner's organization ceiling; inside the workspace the
+  // owner's workspace role is the ceiling, and the refusal names what it lacks.
+  const missing = res.status === 403 ? /Missing: (.+)$/.exec(res.body?.message ?? '')?.[1] : undefined
+  if (missing) {
+    for (const pair of missing.split(',').map((p) => p.trim())) {
+      const [resource, action] = pair.split(':')
+      if (!resource || !action || !permissions[resource]) continue
+      permissions[resource] = permissions[resource]!.filter((a) => a !== action)
+      if (!permissions[resource]!.length) delete permissions[resource]
+    }
+    res = await mint()
+  }
+  expect(!!res.body?.data?.key, 'create the organization key', res.status, res.body)
+  return res.body.data!.key!
+}
+
+/** A runtime seeded with the earlier, narrower organization key gets a full one. */
+export async function ensureOrgKey(serviceUrl: string, session: string, credentials: LocalCredentials, logFile: string): Promise<LocalCredentials> {
+  if (credentials.orgKeyGrant === 'owner') return credentials
+  const orgKey = await mintOrgKey(serviceUrl, session, credentials.organizationId, credentials.workspaceId)
+  log(logFile, 'replaced the organization key with one carrying the owner\'s delegable capabilities')
+  return { ...credentials, orgKey, orgKeyGrant: 'owner' }
+}
+
+export async function seedLocalRuntime(args: SeedArgs): Promise<LocalCredentials> {
+  const { serviceUrl, password } = args
+
+  const signUp = await call(serviceUrl, '/api/auth/sign-up/email', { body: { email: OWNER_EMAIL, password, name: 'Local owner' } })
+  // 422/400 "user already exists" after a partial earlier seed is fine: sign in next.
+  if (signUp.status !== 200) log(args.logFile, `sign-up answered ${signUp.status}; signing in`)
+  const token = await signIn(serviceUrl, password)
+
+  const org = await call<{ id?: string }>(serviceUrl, '/api/auth/organization/create', {
+    token,
+    body: { name: 'Local', slug: `local-${Date.now().toString(36)}` },
+  })
+  expect(org.status === 200 && !!org.body?.id, 'create organization', org.status, org.body)
+  const organizationId = org.body.id!
+
+  const workspaces = await call<{ data?: Array<{ id: string; orgId: string; slug?: string; name?: string }> }>(serviceUrl, '/v1/workspaces', {
+    token,
+    orgId: organizationId,
+  })
+  const workspace = workspaces.body?.data?.find((w) => w.orgId === organizationId)
+  expect(!!workspace, 'find the bootstrapped workspace', workspaces.status, workspaces.body)
+
+  const wsKey = await call<{ data?: { rawKey?: string } }>(serviceUrl, `/v1/workspaces/${workspace!.id}/api-keys`, {
+    token,
+    orgId: organizationId,
+    workspaceId: workspace!.id,
+    body: { name: 'Local runtime', scope: 'mcp' },
+  })
+  expect(!!wsKey.body?.data?.rawKey, 'create the workspace key', wsKey.status, wsKey.body)
+
+  const orgKey = await mintOrgKey(serviceUrl, token, organizationId, workspace!.id)
+
+  log(args.logFile, `seeded ${OWNER_EMAIL}, organization ${organizationId}, workspace ${workspace!.id}`)
+  return {
+    email: OWNER_EMAIL,
+    organizationId,
+    workspaceId: workspace!.id,
+    workspaceSlug: workspace!.slug,
+    orgKey,
+    orgKeyGrant: 'owner',
+    workspaceKey: wsKey.body.data!.rawKey!,
+  }
+}
+
+/** Provider ids the service stores as organization credentials, each with an `apiKey` field. */
+const CREDENTIAL_PROVIDERS = new Set(['anthropic', 'openai', 'openrouter', 'google'])
+
+/** Embedding defaults by provider, in preference order; the service requires 1536-wide vectors. */
+const EMBEDDING: Array<{ provider: string; model: string }> = [
+  { provider: 'openai', model: 'text-embedding-3-small' },
+  { provider: 'openrouter', model: 'openai/text-embedding-3-small' },
+]
+
+/**
+ * Copy the FDE's stored keys into the local organization's credentials, and
+ * pick an embedding model when one is possible. Returns what was applied, for
+ * the status line; failures are logged, never fatal — a runtime without a model
+ * key still starts, and says so.
+ */
+export async function applyModelKeys(args: { serviceUrl: string; password: string; organizationId: string; logFile: string }): Promise<string[]> {
+  const applied: string[] = []
+  let token: string
+  try {
+    token = await signIn(args.serviceUrl, args.password)
+  } catch (err) {
+    log(args.logFile, `could not sign in to apply model keys: ${(err as Error).message}`)
+    return applied
+  }
+  for (const p of LOCAL_PROVIDERS) {
+    if (!CREDENTIAL_PROVIDERS.has(p.id)) continue
+    const key = getKey(p.id)
+    if (!key) continue
+    const res = await call(args.serviceUrl, `/v1/admin/provider-credentials/${p.id}`, {
+      method: 'PUT',
+      token,
+      orgId: args.organizationId,
+      body: { fields: { apiKey: key } },
+    })
+    if (res.status >= 200 && res.status < 300) applied.push(p.id)
+    else log(args.logFile, `storing the ${findProvider(p.id)?.label} key answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
+  }
+  let embedding = EMBEDDING.find((e) => applied.includes(e.provider))
+  if (!embedding && keylessEmbeddings()) {
+    // A placeholder OpenAI credential: the service's OpenAI client is pointed
+    // at the local embeddings (see serviceEnv), which embed without a key.
+    const res = await call(args.serviceUrl, '/v1/admin/provider-credentials/openai', {
+      method: 'PUT',
+      token,
+      orgId: args.organizationId,
+      body: { fields: { apiKey: 'local-embeddings' } },
+    })
+    if (res.status >= 200 && res.status < 300) {
+      embedding = EMBEDDING[0]
+      applied.push('local-embeddings')
+    } else log(args.logFile, `storing the local embeddings credential answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
+  }
+  if (embedding) {
+    const res = await call(args.serviceUrl, '/v1/config/embedding', {
+      method: 'PUT',
+      token,
+      orgId: args.organizationId,
+      body: embedding,
+    })
+    if (res.status >= 300) log(args.logFile, `setting the embedding model answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
+  }
+  return applied
+}
+
+/**
+ * Runtimes started before the echo model was removed still list it: the
+ * `local` custom provider, its `local-model` catalog entry, and that model as
+ * the workspace's judge. Take all three away, so no Agent or test can pick a
+ * model that says nothing about behaviour. Idempotent and never fatal.
+ */
+export async function retireLocalModel(args: { serviceUrl: string; password: string; organizationId: string; workspaceId: string; logFile: string }): Promise<void> {
+  let token: string
+  try {
+    token = await signIn(args.serviceUrl, args.password)
+  } catch {
+    return
+  }
+  const scope = { token, orgId: args.organizationId, workspaceId: args.workspaceId }
+  // An empty PATCH answers with the current judge settings and changes nothing.
+  const judge = await call<{ data?: { judgeModelSlug?: string | null } }>(args.serviceUrl, '/v1/eval/settings', { ...scope, method: 'PATCH', body: {} })
+  if (judge.body?.data?.judgeModelSlug === 'local-model') {
+    const cleared = await call(args.serviceUrl, '/v1/eval/settings', { ...scope, method: 'PATCH', body: { judgeModelSlug: null } })
+    if (cleared.status >= 300) log(args.logFile, `clearing the echo model as judge answered ${cleared.status}`)
+  }
+  const catalog = await call<{ data?: Array<{ slug: string }> }>(args.serviceUrl, '/v1/config/models/catalog', { token, orgId: args.organizationId })
+  if (catalog.body?.data?.some((m) => m.slug === 'local-model')) {
+    const removed = await call(args.serviceUrl, '/v1/config/models/catalog?slug=local-model', { method: 'DELETE', token, orgId: args.organizationId })
+    if (removed.status >= 300) log(args.logFile, `removing the echo model from the catalog answered ${removed.status}`)
+  }
+  const providers = await call<{ data?: Array<{ slug: string }> }>(args.serviceUrl, '/v1/admin/custom-providers', { token, orgId: args.organizationId })
+  if (providers.body?.data?.some((p) => p.slug === 'local')) {
+    const removed = await call(args.serviceUrl, '/v1/admin/custom-providers/local', { method: 'DELETE', token, orgId: args.organizationId })
+    if (removed.status >= 300) log(args.logFile, `removing the echo model's provider answered ${removed.status}`)
+  }
+}
+
+/**
+ * Chat models a stored provider key unlocks in the local catalog, so an Agent
+ * can name a real model in its `agent.json`. Kept short and current: the
+ * catalog slug is what `modelSlug` takes, the model id is the provider's own.
+ */
+export const PROVIDER_MODELS: Record<string, Array<{ slug: string; modelId: string; name: string }>> = {
+  openrouter: [
+    { slug: 'claude-sonnet-5-5', modelId: 'anthropic/claude-sonnet-5.5', name: 'Claude Sonnet 5.5' },
+    { slug: 'claude-haiku-5-5', modelId: 'anthropic/claude-haiku-5.5', name: 'Claude Haiku 5.5' },
+    { slug: 'gemini-3-8-flash', modelId: 'google/gemini-3.8-flash', name: 'Gemini 3.8 Flash' },
+    { slug: 'gpt-5-6-terra', modelId: 'openai/gpt-5.6-terra', name: 'GPT-5.6 Terra' },
+  ],
+}
+
+/**
+ * Add the chat models each applied provider unlocks to the local catalog.
+ * Idempotent and never fatal: a model already there is left alone, and a
+ * refusal is logged.
+ */
+export async function ensureProviderModels(args: { serviceUrl: string; password: string; organizationId: string; providers: string[]; logFile: string }): Promise<string[]> {
+  const wanted = args.providers.flatMap((provider) => (PROVIDER_MODELS[provider] ?? []).map((m) => ({ ...m, provider })))
+  if (!wanted.length) return []
+  let token: string
+  try {
+    token = await signIn(args.serviceUrl, args.password)
+  } catch {
+    return []
+  }
+  const catalog = await call<{ data?: Array<{ provider: string; modelId: string }> }>(args.serviceUrl, '/v1/config/models/catalog', { token, orgId: args.organizationId })
+  const added: string[] = []
+  for (const model of wanted) {
+    if (catalog.body?.data?.some((m) => m.provider === model.provider && m.modelId === model.modelId)) continue
+    const res = await call(args.serviceUrl, '/v1/config/models/catalog', {
+      token,
+      orgId: args.organizationId,
+      body: { slug: model.slug, provider: model.provider, modelId: model.modelId, name: model.name, kind: 'text' },
+    })
+    if (res.status < 300) added.push(model.slug)
+    else log(args.logFile, `adding ${model.name} to the catalog answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
+  }
+  return added
+}
+
+/**
+ * Make Blueprint usable in a fresh local organization: authoring on (it is
+ * off by default for an organization) and the lifecycle adopted, so the
+ * Blueprint CLI loop (`pull`, `plan`, `apply`) and Studio's Blueprint section
+ * work from the first start. The seeded owner is already the Steward.
+ */
+export async function ensureBlueprint(args: { serviceUrl: string; password: string; organizationId: string; logFile: string }): Promise<void> {
+  let token: string
+  try {
+    token = await signIn(args.serviceUrl, args.password)
+  } catch {
+    return
+  }
+  const flag = await call(args.serviceUrl, '/v1/config/feature-flags', {
+    method: 'PUT',
+    token,
+    orgId: args.organizationId,
+    body: { key: 'blueprint.authoring', value: true },
+  })
+  if (flag.status >= 300) log(args.logFile, `turning on Blueprint authoring answered ${flag.status}`)
+  const lifecycle = await call(args.serviceUrl, '/v1/blueprint/lifecycle', { token, orgId: args.organizationId })
+  if (lifecycle.status === 404) {
+    const adopted = await call(args.serviceUrl, '/v1/blueprint/lifecycle/adopt', { token, orgId: args.organizationId, body: {} })
+    if (adopted.status >= 300) log(args.logFile, `adopting the Blueprint lifecycle answered ${adopted.status}: ${JSON.stringify(adopted.body).slice(0, 200)}`)
+  }
+}