@frontera-sdk/cli 1.52.28 → 1.52.30

package/src/local/local-library.ts

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { RemoteItem } from './local-sync-plan'
+import { invert, type Directory } from './local-sync-refs'
+
+/**
+ * What the workspace installed from the library: each installation's entry
+ * (`frontera/returns-desk`), the release it is at, and what it made there
+ * (the Agent, the skills it created or reused), by name. A pull records it
+ * as `library.json`, so the project keeps where its Agents and skills came
+ * from; the Agents and skills themselves come as the project's own items.
+ *
+ * `local dev` checks the local runtime's library for each entry and
+ * release and says whether it is there. It does not install them again:
+ * an installation makes its own Agent and managed skills, which would stand
+ * beside the project's copies, and a managed skill cannot take the
+ * project's edits. Never proposed back: installing is the library's own
+ * flow on the platform.
+ */
+
+/** An installation as `/v1/sync/library` lists it. */
+export interface LibraryRow {
+  id: string
+  entry: { namespace: string; slug: string; kind: 'agent' | 'skill'; name: string; source?: string }
+  release: { number: number; version: string; digest?: string }
+  installType?: 'agent' | 'skill'
+  state?: string
+  agentId?: string | null
+  resources?: Array<{ type: 'agent' | 'skill'; id: string | null; ownership?: string }>
+}
+
+export interface LibraryInstallation {
+  entry: string
+  kind: 'agent' | 'skill'
+  name: string
+  release: { number: number; version: string }
+  state?: string
+  agent?: string
+  skills?: string[]
+}
+
+export interface LibraryFile {
+  installations: LibraryInstallation[]
+}
+
+export const LIBRARY_PATH = 'library.json'
+
+/** The workspace's installations as one project item (`library`). */
+export function readLibrary(rows: LibraryRow[], directory: Directory): RemoteItem[] {
+  if (!rows.length) return []
+  const ids = invert(directory)
+  const nameOf = (id: string | null | undefined, kind: 'agent' | 'skill') => {
+    const hit = id ? ids.get(id) : undefined
+    return hit && hit.kind === kind ? hit.name : undefined
+  }
+  const installations: LibraryInstallation[] = rows.map((r) => {
+    const agent = nameOf(r.agentId, 'agent')
+    const made = (r.resources ?? []).flatMap((x) => (x.type === 'skill' && nameOf(x.id, 'skill') ? [`skill/${nameOf(x.id, 'skill')}`] : []))
+    return {
+      entry: `${r.entry.namespace}/${r.entry.slug}`,
+      kind: r.entry.kind,
+      name: r.entry.name,
+      release: { number: r.release.number, version: r.release.version },
+      ...(r.state && r.state !== 'installed' ? { state: r.state } : {}),
+      ...(agent ? { agent: `agent/${agent}` } : {}),
+      ...(made.length ? { skills: [...new Set(made)].sort() } : {}),
+    }
+  })
+  const doc: LibraryFile = { installations }
+  const n = installations.length
+  return [{
+    ref: 'library',
+    kind: 'library',
+    name: 'library',
+    title: 'Library installations',
+    files: { [LIBRARY_PATH]: `${JSON.stringify(doc, null, 2)}\n` },
+    unresolved: [],
+    notes: [`Where ${n === 1 ? 'one Agent or skill' : `${n} Agents and skills`} came from in the library, recorded here; the items themselves are the project’s own`],
+    requires: [],
+  }]
+}
+
+type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
+
+const dataOf = (body: unknown) => ((body as { data?: unknown } | null)?.data ?? body) as Record<string, unknown> | null
+
+/** Why an installation is not installed again here, as the build says it. */
+export const LIBRARY_NOT_REINSTALLED = 'The Agents and skills it installed are the project’s own copies here; installing them again would add a second copy'
+
+/**
+ * Check the local runtime's library for each installation the project
+ * records: the same entry at the same release, a different release, or none.
+ * Nothing is installed (see above); the build says what it found.
+ */
+export async function applyLibrary(root: string, call: Call): Promise<{ ok: boolean; output: string }> {
+  const path = join(root, LIBRARY_PATH)
+  if (!existsSync(path)) return { ok: false, output: `error [LIBRARY]: ${LIBRARY_PATH} is missing` }
+  let doc: LibraryFile
+  try {
+    doc = JSON.parse(readFileSync(path, 'utf8')) as LibraryFile
+  } catch (err) {
+    return { ok: false, output: `error [USAGE]: ${LIBRARY_PATH} is not valid JSON: ${(err as Error).message}` }
+  }
+  const installations = Array.isArray(doc.installations) ? doc.installations : []
+  const offered = new Map<string, { number: number; version: string } | null>()
+  for (let offset = 0; offset < 2000; offset += 50) {
+    const listed = await call('GET', `/v1/library/entries?limit=50&offset=${offset}`)
+    if (listed.status >= 400) return { ok: true, output: `  ${installations.length} library installation${installations.length === 1 ? '' : 's'} recorded; this runtime’s library could not be read (${listed.status})` }
+    const page = (dataOf(listed.body)?.data ?? dataOf(listed.body)) as { entries?: Array<{ key: string; offeredRelease?: { releaseNumber: number; contentVersion: string } | null }>; hasMore?: boolean } | null
+    for (const e of page?.entries ?? []) offered.set(e.key, e.offeredRelease ? { number: e.offeredRelease.releaseNumber, version: e.offeredRelease.contentVersion } : null)
+    if (!page?.hasMore) break
+  }
+  const lines = installations.map((i) => {
+    const here = offered.get(i.entry)
+    const what = i.agent ?? i.skills?.join(', ') ?? i.entry
+    if (here === undefined) return `  ${i.name} (${what}): not in this runtime’s library; the project’s copy is used`
+    if (here && here.number === i.release.number) return `  ${i.name} (${what}): in this runtime’s library at the same release (${i.release.version})`
+    return `  ${i.name} (${what}): this runtime’s library offers ${here ? `release ${here.version}` : 'no release'}, the workspace has ${i.release.version}`
+  })
+  lines.unshift(`  ${installations.length} library installation${installations.length === 1 ? '' : 's'} recorded`)
+  if (installations.length) lines.push(`  warning: ${LIBRARY_NOT_REINSTALLED}`)
+  return { ok: true, output: lines.join('\n') }
+}

package/src/local/local-media-sets.ts

@@ -0,0 +1,31 @@
+/**
+ * The stand-in for a media-backed object type (design §8, Stubbed): a
+ * Media Set holds the platform's files, which never come down, so an object
+ * type over a set's catalog (`media_<set>`) is held locally over an empty
+ * Media Set of the same name, made on the runtime before the Blueprint
+ * applies. The type keeps its fields, links, metrics and Actions; it has no
+ * rows until files are uploaded to the local set. A type over a set's
+ * extracted text or passages is still left off (`local-portability.ts`).
+ */
+
+type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
+
+const dataOf = (body: unknown) => ((body as { data?: unknown } | null)?.data ?? body) as unknown
+
+/**
+ * Make each Media Set the runtime lacks, by API name, as the runtime's owner.
+ * Returns why one could not be made, or null.
+ */
+export async function ensureMediaSets(sets: Record<string, string>, call: Call): Promise<string | null> {
+  const names = Object.keys(sets)
+  if (!names.length) return null
+  const listed = await call('GET', '/v1/media/sets')
+  if (listed.status >= 400) return `the runtime’s Media Sets couldn’t be read (${listed.status})`
+  const here = new Set(((dataOf(listed.body) as { mediaSets?: Array<{ apiName?: string }> } | null)?.mediaSets ?? []).map((s) => s.apiName))
+  for (const apiName of names) {
+    if (here.has(apiName)) continue
+    const made = await call('POST', '/v1/media/sets', { apiName, displayName: sets[apiName], description: 'An empty stand-in for the platform’s Media Set: its files stay on the platform.' })
+    if (made.status >= 400) return `the Media Set ${apiName} couldn’t be made (${made.status} ${JSON.stringify(made.body).slice(0, 160)})`
+  }
+  return null
+}

package/src/local/local-object-sets.ts

@@ -0,0 +1,181 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { isIgnoredName } from './local-dev-sync'
+import type { LocalCredentials } from './local-state'
+import { objectSetNames, rows, type ObjectSetRow } from './local-sync-remote'
+import { parseRef, referencesIn, toIds } from './local-sync-refs'
+
+/**
+ * Saved object sets on the local runtime, from `blueprint/object-sets/`.
+ *
+ * A pull writes each of the workspace's saved sets there (`objectSetItems`):
+ * its name, the object type it returns, and its definition, or the keys of
+ * the records a static set lists. `blueprint apply` reads only the model's
+ * own folders, so `local dev` saves the sets itself once the Blueprint is
+ * published and granted here: a new one is created, a changed one updated,
+ * in the order their `reference`s to each other need. A static set whose
+ * records changed is created again (the platform keeps a static set's keys
+ * as they were made), so what names it is applied again.
+ */
+
+export interface ObjectSetFile {
+  /** The file's name, which is the set's name in a reference (`objectSet/open-cases`). */
+  ref: string
+  file: string
+  doc: { name?: unknown; description?: unknown; objectType?: unknown; kind?: unknown; definition?: unknown; records?: unknown }
+}
+
+export function readObjectSetFiles(root: string): ObjectSetFile[] {
+  const dir = join(root, 'blueprint', 'object-sets')
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).sort().flatMap((name) => {
+    if (isIgnoredName(name) || !/\.(ya?ml|json)$/.test(name)) return []
+    const file = join('blueprint', 'object-sets', name)
+    try {
+      const doc = parseYaml(readFileSync(join(root, file), 'utf8')) as ObjectSetFile['doc'] | null
+      return doc && typeof doc === 'object' ? [{ ref: name.replace(/\.(ya?ml|json)$/, ''), file, doc }] : []
+    } catch {
+      return []
+    }
+  })
+}
+
+type Fetcher = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
+
+export function objectSetCalls(serviceUrl: string, creds: LocalCredentials, fetcher: typeof fetch = fetch): Fetcher {
+  return async (method, path, body) => {
+    const res = await fetcher(new URL(path, serviceUrl), {
+      method,
+      headers: {
+        authorization: `Bearer ${creds.session}`,
+        'x-org-id': creds.organizationId,
+        'x-workspace-id': creds.workspaceId,
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+    const text = await res.text()
+    let parsed: unknown = text
+    try {
+      parsed = text ? JSON.parse(text) : null
+    } catch {
+      // Keep the text.
+    }
+    return { status: res.status, body: parsed }
+  }
+}
+
+const errorOf = (answer: { status: number; body: unknown }): string => {
+  const b = answer.body as { message?: unknown } | null
+  return `${answer.status} ${String(typeof b?.message === 'string' ? b.message : JSON.stringify(b)).replace(/\s+/g, ' ').slice(0, 200)}`
+}
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null)
+
+export interface ObjectSetsApplied {
+  /** One line per set saved, for the apply's output. */
+  lines: string[]
+  /** One `warning:` line per set that could not be saved here: an adaptation of the Blueprint build. */
+  warnings: string[]
+  /** Sets created again under a new id: what names them is applied again. */
+  recreated: string[]
+}
+
+/**
+ * Save the project's object sets on the runtime. `leftOff` names the object
+ * types the runtime's Blueprint leaves off (media-backed): a set on one is
+ * left off too, with why.
+ */
+export async function applyObjectSets(root: string, call: Fetcher, leftOff: ReadonlySet<string> = new Set()): Promise<ObjectSetsApplied> {
+  const out: ObjectSetsApplied = { lines: [], warnings: [], recreated: [] }
+  const files = readObjectSetFiles(root)
+  if (!files.length) return out
+  const listed = await call('GET', '/v1/sync/object-sets')
+  if (listed.status === 404) {
+    out.warnings.push('  warning: saved object sets: this runtime cannot list them, so they were not saved here')
+    return out
+  }
+  if (listed.status >= 400) {
+    out.warnings.push(`  warning: saved object sets: ${errorOf(listed)}`)
+    return out
+  }
+  const existing = rows<ObjectSetRow>(listed.body)
+  const names = objectSetNames(existing)
+  const byRef = new Map(existing.map((s) => [names.get(s.id)!, s]))
+  const ids = new Map([...byRef].map(([ref, s]) => [ref, s.id]))
+
+  let pending = files
+  while (pending.length) {
+    const next: ObjectSetFile[] = []
+    for (const f of pending) {
+      const doc = f.doc
+      const name = typeof doc.name === 'string' && doc.name ? doc.name : f.ref
+      const objectType = typeof doc.objectType === 'string' ? doc.objectType : ''
+      const kind = doc.kind === 'static' ? 'static' : 'dynamic'
+      if (!objectType) {
+        out.warnings.push(`  warning: saved object set ${f.ref} names no objectType, so it was not saved here`)
+        continue
+      }
+      if (leftOff.has(objectType)) {
+        out.warnings.push(`  warning: saved object set ${f.ref} is left off here: its object type ${objectType} is left off on this runtime`)
+        continue
+      }
+      // A set naming another waits for that one.
+      const waits = referencesIn(doc.definition).filter((r) => r.kind === 'objectSet' && !ids.has(r.name))
+      if (waits.length) {
+        next.push(f)
+        continue
+      }
+      const { doc: definition } = toIds(doc.definition, { objectSet: ids })
+      const description = typeof doc.description === 'string' ? doc.description : undefined
+      const records = Array.isArray(doc.records) ? (doc.records as Array<string | number>) : []
+      const have = byRef.get(f.ref)
+      let saved: { status: number; body: unknown }
+      if (have && kind === 'dynamic' && have.kind === 'dynamic') {
+        if (have.name === name && (have.description ?? undefined) === description && same(have.definition, definition)) continue
+        saved = await call('PUT', `/v1/blueprint/object-sets/${encodeURIComponent(have.id)}`, { name, description: description ?? null, definition })
+      } else {
+        if (have) {
+          if (have.kind === 'static' && kind === 'static' && have.name === name && (have.description ?? undefined) === description && same(have.staticPks, records) && have.objectType === objectType) continue
+          // A static set's keys, or a set's kind, cannot be edited in place: it is made again.
+          await call('DELETE', `/v1/blueprint/object-sets/${encodeURIComponent(have.id)}`)
+          out.recreated.push(f.ref)
+        }
+        if (kind === 'static' && !records.length) {
+          out.warnings.push(`  warning: saved object set ${f.ref} lists no records, so it was not saved here`)
+          continue
+        }
+        saved = await call('POST', '/v1/blueprint/object-sets', {
+          name,
+          ...(description ? { description } : {}),
+          kind,
+          ...(kind === 'static' ? { objectType, staticPks: records } : { definition }),
+        })
+      }
+      if (saved.status >= 400) {
+        out.warnings.push(`  warning: saved object set ${f.ref} could not be saved here: ${errorOf(saved)}`)
+        continue
+      }
+      const row = ((saved.body as { data?: unknown })?.data ?? saved.body) as { id?: string }
+      if (row?.id) ids.set(f.ref, row.id)
+      out.lines.push(`  saved object set ${f.ref}`)
+    }
+    if (next.length === pending.length) {
+      for (const f of next) {
+        const missing = referencesIn(f.doc.definition).filter((r) => r.kind === 'objectSet' && !ids.has(r.name)).map((r) => `objectSet/${r.name}`)
+        out.warnings.push(`  warning: saved object set ${f.ref} was not saved here: it names ${missing.join(', ')}, which isn't in the project`)
+      }
+      break
+    }
+    pending = next
+  }
+  return out
+}
+
+/** Whether a file's text names one of these sets, so it is applied again with its new id. */
+export function namesObjectSet(text: string, refs: string[]): boolean {
+  return refs.some((ref) => text.includes(`objectSet/${ref}`) && parseRef(`objectSet/${ref}`) !== null)
+}

package/src/local/local-objects.ts

@@ -0,0 +1,159 @@
+import { isUuid, parseRef, type Directory } from './local-sync-refs'
+
+/**
+ * An Agent's object tools (`objectBindings` in `agent.json`): each row binds
+ * it to an object definition of the workspace, whose records the Agent reads
+ * and writes through its object tools. The definition is the workspace's,
+ * not the Agent's, but nothing else in a project holds it, so a pull writes
+ * it into the row it belongs to (`definition`: name, description, icon and
+ * fields), and names the row's definition by slug (`object/<slug>`). The
+ * records stay on the platform (sync v2 design §8).
+ *
+ * `local dev` makes each definition on the runtime from the row (or brings
+ * the runtime's copy up to its fields), then binds the Agent to it. A row the
+ * pull could not name (an older platform) or a definition the runtime refuses
+ * leaves the Agent without those tools, said as an adaptation.
+ */
+
+export interface ObjectDefinitionDoc {
+  name: string
+  description?: string
+  icon?: string
+  fields: Array<Record<string, unknown>>
+}
+
+/** A definition as `GET /v1/sync/object-definitions` lists it. */
+export interface ObjectDefinitionRow {
+  id: string
+  slug: string
+  name: string
+  description?: string | null
+  icon?: string | null
+  fields?: unknown
+  shared?: boolean
+}
+
+/** What a row carries of its definition: everything but its id and timestamps. */
+export function definitionDoc(row: ObjectDefinitionRow): ObjectDefinitionDoc {
+  return {
+    name: row.name,
+    ...(row.description ? { description: row.description } : {}),
+    ...(row.icon ? { icon: row.icon } : {}),
+    fields: (Array.isArray(row.fields) ? row.fields : []) as Array<Record<string, unknown>>,
+  }
+}
+
+/**
+ * The pull's side: each binding row gets its definition, by the platform's id,
+ * before ids become names. Returns the notes for rows it could not complete.
+ */
+export function attachDefinitions(agent: Record<string, unknown>, definitions: ObjectDefinitionRow[] | null): string[] {
+  const rows = Array.isArray(agent.objectBindings) ? (agent.objectBindings as Array<Record<string, unknown>>) : []
+  if (!rows.length) return []
+  if (!definitions) return [`Its object tools (${rows.length}) couldn’t be read: this platform doesn’t list object definitions to this key, so locally it goes without them`]
+  const byId = new Map(definitions.map((d) => [d.id, d]))
+  let missing = 0
+  for (const row of rows) {
+    const found = typeof row.objectDefinitionId === 'string' ? byId.get(row.objectDefinitionId) : undefined
+    if (found) row.definition = definitionDoc(found)
+    else missing += 1
+  }
+  return missing ? [`${missing} of its object tools name${missing === 1 ? 's' : ''} an object definition this workspace doesn’t list, so locally it goes without ${missing === 1 ? 'it' : 'them'}`] : []
+}
+
+/** Rows whose definition the pull could not name: they stay platform ids. */
+export function unnamedObjectBindings(agent: unknown): number {
+  const rows = (agent as { objectBindings?: unknown } | null)?.objectBindings
+  if (!Array.isArray(rows)) return 0
+  return rows.filter((r) => {
+    const id = (r as { objectDefinitionId?: unknown } | null)?.objectDefinitionId
+    return typeof id !== 'string' || !parseRef(id) || !(r as { definition?: unknown }).definition
+  }).length
+}
+
+type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
+
+const dataOf = (body: unknown) => ((body as { data?: unknown } | null)?.data ?? body) as unknown
+
+const errorOf = (a: { status: number; body: unknown }) => {
+  const b = a.body as { message?: unknown } | null
+  return `${a.status} ${String(typeof b?.message === 'string' ? b.message : JSON.stringify(b)).replace(/\s+/g, ' ').slice(0, 160)}`
+}
+
+/** The fields as the definition route takes them: each with its sort order. */
+function fieldsBody(fields: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
+  return fields.map((f, i) => ({ ...f, sortOrder: typeof f.sortOrder === 'number' ? f.sortOrder : i }))
+}
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null)
+
+/**
+ * The runtime's side: make or update each definition the Agent's rows carry,
+ * put its id in the directory, and drop the `definition` the runtime does not
+ * take. A row naming nothing the runtime can hold is left off, with why.
+ * Changes `agent` and `dir`; returns the warnings.
+ */
+export async function ensureObjectDefinitions(agent: Record<string, unknown>, dir: Directory, call: Call | null, label: string): Promise<string[]> {
+  const rows = Array.isArray(agent.objectBindings) ? (agent.objectBindings as Array<Record<string, unknown>>) : []
+  if (!rows.length) return []
+  const warnings: string[] = []
+  const leaveOff = (row: Record<string, unknown>, why: string) => {
+    warnings.push(`  warning: Its object tools for ${String((row.definition as ObjectDefinitionDoc | undefined)?.name ?? row.objectDefinitionId)} are left out here: ${why}`)
+    return false
+  }
+  let local: ObjectDefinitionRow[] | null = null
+  const listLocal = async () => {
+    if (local || !call) return local ?? []
+    const listed = await call('GET', '/v1/objects/definitions')
+    local = listed.status < 400 ? ((dataOf(listed.body) as ObjectDefinitionRow[] | null) ?? []) : []
+    return local
+  }
+  dir.object ??= new Map()
+  const kept: Array<Record<string, unknown>> = []
+  for (const row of rows) {
+    const id = typeof row.objectDefinitionId === 'string' ? row.objectDefinitionId : ''
+    const ref = parseRef(id)
+    const definition = row.definition as ObjectDefinitionDoc | undefined
+    const { definition: _definition, ...bare } = row
+    if (!ref || ref.kind !== 'object') {
+      if (isUuid(id)) leaveOff(row, 'the pull couldn’t name its object definition on the platform; pull again from a newer platform')
+      else leaveOff(row, `${id || 'it'} doesn’t name an object definition`)
+      continue
+    }
+    if (!definition || !Array.isArray(definition.fields)) {
+      if (dir.object.has(ref.name)) kept.push(bare)
+      else leaveOff(row, `the object ${ref.name} isn’t on this runtime, and the file doesn’t carry its fields`)
+      continue
+    }
+    if (!call) {
+      leaveOff(row, 'the runtime has no owner session; restart it')
+      continue
+    }
+    const here = (await listLocal()).find((d) => d.slug === ref.name)
+    if (!here) {
+      const made = await call('POST', '/v1/objects/definitions', { slug: ref.name, name: definition.name, ...(definition.description ? { description: definition.description } : {}), ...(definition.icon ? { icon: definition.icon } : {}), fields: fieldsBody(definition.fields) })
+      const madeId = (dataOf(made.body) as { id?: unknown } | null)?.id
+      if (made.status >= 400 || typeof madeId !== 'string') {
+        leaveOff(row, `the runtime refused its object definition (${errorOf(made)})`)
+        continue
+      }
+      dir.object.set(ref.name, madeId)
+      ;(local as ObjectDefinitionRow[] | null)?.push({ id: madeId, slug: ref.name, name: definition.name })
+    } else {
+      dir.object.set(ref.name, here.id)
+      const differs = here.name !== definition.name || !same(here.description || undefined, definition.description) || !same(here.icon || undefined, definition.icon) || !same(fieldsBody((here.fields as Array<Record<string, unknown>>) ?? []).map(comparable), fieldsBody(definition.fields).map(comparable))
+      if (differs) {
+        const put = await call('PUT', `/v1/objects/definitions/${encodeURIComponent(here.id)}`, { name: definition.name, ...(definition.description ? { description: definition.description } : {}), ...(definition.icon ? { icon: definition.icon } : {}), fields: fieldsBody(definition.fields) })
+        if (put.status >= 400) warnings.push(`  warning: ${label}: the object ${ref.name}’s fields couldn’t be brought up to the file’s (${errorOf(put)}); its tools use the runtime’s`)
+      }
+    }
+    kept.push(bare)
+  }
+  agent.objectBindings = kept
+  return warnings
+}
+
+/** A field as both sides compare it: the keys a definition route keeps. */
+function comparable(f: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(f).filter(([, v]) => v !== undefined && v !== null).sort(([a], [b]) => a.localeCompare(b)))
+}

package/src/local/local-operating.ts

@@ -36,12 +36,16 @@ export async function applyOperatingConfig(args: {
   creds: LocalCredentials
   slug: string
   file: string
+  /** The document with names resolved to this runtime's ids; the file is read when absent. */
+  document?: unknown
 }): Promise<Result> {
-  let operatingConfig: unknown
-  try {
-    operatingConfig = JSON.parse(readFileSync(args.file, 'utf8'))
-  } catch (err) {
-    return { ok: false, output: `error [USAGE]: ${args.file} is not valid JSON: ${(err as Error).message}` }
+  let operatingConfig: unknown = args.document
+  if (operatingConfig === undefined) {
+    try {
+      operatingConfig = JSON.parse(readFileSync(args.file, 'utf8'))
+    } catch (err) {
+      return { ok: false, output: `error [USAGE]: ${args.file} is not valid JSON: ${(err as Error).message}` }
+    }
   }
   if (!args.creds.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime has no owner session; restart it' }
   const headers = {

package/src/local/local-org-settings.ts

@@ -0,0 +1,118 @@
+import type { LocalCredentials } from './local-state'
+import type { SyncClient } from './local-sync-client'
+
+/**
+ * The organization settings that change how Agents behave, as
+ * `/v1/sync/settings` returns them: the timezone, the AI settings and the
+ * feature flags. A fetch records the workspace's in the snapshot; `local dev`
+ * reads the local runtime's the same way, takes the workspace's timezone,
+ * and records every other difference in the build, in words, so the build
+ * summary says where the runtime behaves differently.
+ */
+export interface OrgSettings {
+  timezone?: string
+  computerMode?: boolean
+  memoryTree?: boolean
+  embedding?: { provider: string | null; model: string | null }
+  memoryEmbedding?: { provider: string | null; model: string | null }
+  webSearch?: string | null
+  imageModel?: { provider: string | null; model: string | null }
+  voiceSpeed?: number | null
+  featureFlags?: Record<string, boolean>
+}
+
+/** The settings, or null on a platform without the route (or that could not answer). */
+export async function readOrgSettings(client: SyncClient): Promise<OrgSettings | null> {
+  try {
+    const found = await client.find<unknown>('/v1/sync/settings')
+    if (!found || typeof found !== 'object') return null
+    const body = found as { data?: unknown }
+    const value = (body.data && typeof body.data === 'object' ? body.data : found) as OrgSettings
+    return value && typeof value === 'object' ? value : null
+  } catch {
+    return null
+  }
+}
+
+const DEFAULT = 'the deployment’s default'
+
+const pair = (p?: { provider: string | null; model: string | null }) => (p?.provider || p?.model ? [p.provider, p.model].filter(Boolean).join(' / ') : DEFAULT)
+
+const onOff = (v?: boolean) => (v ? 'on' : 'off')
+
+/**
+ * Where the runtime's settings differ from the workspace's, one line each,
+ * the timezone left out (`local dev` sets it). A flag or setting only one
+ * side reports (an older runtime) is left out too: nothing to compare.
+ */
+export function settingsDifferences(workspace: OrgSettings, local: OrgSettings): string[] {
+  const out: string[] = []
+  const differs = (a: unknown, b: unknown) => JSON.stringify(a ?? null) !== JSON.stringify(b ?? null)
+  const both = (k: keyof OrgSettings) => k in workspace && k in local
+  if (both('computerMode') && differs(workspace.computerMode, local.computerMode)) out.push(`Computer mode is ${onOff(workspace.computerMode)} in the workspace and ${onOff(local.computerMode)} here`)
+  if (both('memoryTree') && differs(workspace.memoryTree, local.memoryTree)) out.push(`The memory tree is ${onOff(workspace.memoryTree)} in the workspace and ${onOff(local.memoryTree)} here`)
+  if (both('embedding') && differs(workspace.embedding, local.embedding)) out.push(`Embeddings use ${pair(workspace.embedding)} in the workspace and ${pair(local.embedding)} here, so knowledge search ranks differently`)
+  if (both('memoryEmbedding') && differs(workspace.memoryEmbedding, local.memoryEmbedding)) out.push(`Memory embeddings use ${pair(workspace.memoryEmbedding)} in the workspace and ${pair(local.memoryEmbedding)} here`)
+  if (both('webSearch') && differs(workspace.webSearch, local.webSearch)) out.push(`Web search is ${workspace.webSearch ?? DEFAULT} in the workspace and ${local.webSearch ?? DEFAULT} here`)
+  if (both('imageModel') && differs(workspace.imageModel, local.imageModel)) out.push(`Images are made with ${pair(workspace.imageModel)} in the workspace and ${pair(local.imageModel)} here`)
+  if (both('voiceSpeed') && differs(workspace.voiceSpeed, local.voiceSpeed)) out.push(`Voice speed is ${workspace.voiceSpeed ?? DEFAULT} in the workspace and ${local.voiceSpeed ?? DEFAULT} here`)
+  const ws = workspace.featureFlags ?? {}
+  const here = local.featureFlags ?? {}
+  for (const key of Object.keys(ws).sort()) {
+    if (key in here && ws[key] !== here[key]) out.push(`Feature ${key} is ${onOff(ws[key])} in the workspace and ${onOff(here[key])} here`)
+  }
+  return out
+}
+
+type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
+
+export function settingsCalls(serviceUrl: string, creds: LocalCredentials, fetcher: typeof fetch = fetch): Call {
+  return async (method, path, body) => {
+    const res = await fetcher(new URL(path, serviceUrl), {
+      method,
+      headers: {
+        authorization: `Bearer ${creds.session}`,
+        'x-org-id': creds.organizationId,
+        'x-workspace-id': creds.workspaceId,
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+    const text = await res.text()
+    let parsed: unknown = text
+    try {
+      parsed = text ? JSON.parse(text) : null
+    } catch {
+      // Keep the text.
+    }
+    return { status: res.status, body: parsed }
+  }
+}
+
+export interface SettingsMirror {
+  /** What was done, for `local dev`'s output: the timezone set. */
+  lines: string[]
+  /** Where the runtime still behaves differently, in words. */
+  differences: string[]
+}
+
+/**
+ * Make the runtime's organization settings match the workspace's where that
+ * is safe, and say where they still differ. Only the timezone is taken (the
+ * owner sets it, as Settings → Usage does): it decides how dates resolve in
+ * Blueprint queries and usage windows. The rest stays the runtime's: a
+ * provider or model there needs this computer's own credentials.
+ */
+export async function mirrorOrgSettings(workspace: OrgSettings, call: Call): Promise<SettingsMirror> {
+  const out: SettingsMirror = { lines: [], differences: [] }
+  const read = await call('GET', '/v1/sync/settings')
+  if (read.status >= 400) return out
+  const local = ((read.body as { data?: unknown })?.data ?? read.body) as OrgSettings
+  if (workspace.timezone && local.timezone && workspace.timezone !== local.timezone) {
+    const set = await call('PUT', '/v1/usage-limits/windows', { timezone: workspace.timezone })
+    if (set.status < 400) out.lines.push(`  timezone set to ${workspace.timezone}, as in the workspace`)
+    else out.differences.push(`The timezone is ${workspace.timezone} in the workspace and ${local.timezone} here; it could not be set (${set.status})`)
+  }
+  out.differences.push(...settingsDifferences(workspace, local))
+  return out
+}