@frontera-sdk/cli 1.52.28 → 1.52.29

package/src/local/local-adapt.ts

@@ -0,0 +1,216 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { loadBuild, refOfTarget, refWords } from './local-applied'
+import { allTargets } from './local-dev-sync'
+import type { LocalProject } from './local-project'
+import { objectTypeFit } from './local-portability'
+import { parseRef, type Unresolved } from './local-sync-refs'
+
+/**
+ * What a file names that the local runtime will never have, applied around
+ * instead of refusing the whole file (design §8, "adapted").
+ *
+ * Two kinds of missing are told apart:
+ * - **Coming**: the project holds it (a Function file, a workflow, an object
+ *   type the runtime builds) and it is not applied yet. The file waits for it
+ *   (`blocked`), and the retry in `local dev` applies it once it is there.
+ * - **Absent**: nothing in the project provides it: a built-in connection
+ *   signed in on the platform, a knowledge base not pulled, an object type or
+ *   governed Action the runtime leaves off. Waiting would wait forever, so the
+ *   file is applied without the part that names it, and each omission is an
+ *   adaptation in the build, in words.
+ *
+ * What is left out is the smallest part that still makes sense: a link in
+ * guidance text stays as plain words, a procedure's tool or knowledge scope
+ * loses that one entry, a step is left out, an action is left out with the
+ * steps that run it. A procedure whose completion or verification needs the
+ * missing action is switched off rather than run half-built.
+ */
+
+/** Whether the project provides a reference the runtime does not have yet, so a file naming it should wait. */
+export function projectProvides(project: LocalProject, organizationId?: string | null): (ref: string) => boolean {
+  const refs = new Set(allTargets(project.root).map(refOfTarget))
+  const blueprint = join(project.root, 'blueprint')
+  const docsIn = (dir: string): Array<Record<string, unknown>> => {
+    const at = join(blueprint, dir)
+    if (!existsSync(at)) return []
+    return readdirSync(at).flatMap((name) => {
+      if (!/\.(ya?ml|json)$/.test(name) || name.startsWith('.')) return []
+      try {
+        const doc = parseYaml(readFileSync(join(at, name), 'utf8')) as Record<string, unknown> | null
+        return doc && typeof doc.apiName === 'string' ? [doc] : []
+      } catch {
+        return []
+      }
+    })
+  }
+  const objectTypes = new Set(docsIn('object-types').filter((d) => !objectTypeFit(d, () => true).leftOff).map((d) => String(d.apiName)))
+  const leftOff = organizationId ? loadBuild(project, organizationId).blueprint?.actions ?? {} : {}
+  const actions = new Set(docsIn('actions').map((d) => String(d.apiName)).filter((name) => leftOff[name]?.status !== 'left-off'))
+  // A saved object set is named by its file (`blueprint/object-sets/open-cases.yaml`).
+  const setsDir = join(blueprint, 'object-sets')
+  const objectSets = new Set(existsSync(setsDir) ? readdirSync(setsDir).flatMap((n) => (/\.(ya?ml|json)$/.test(n) && !n.startsWith('.') ? [n.replace(/\.(ya?ml|json)$/, '')] : [])) : [])
+  return (ref: string) => {
+    const parsed = parseRef(ref)
+    if (!parsed) return false
+    if (parsed.kind === 'objectType') return objectTypes.has(parsed.name)
+    if (parsed.kind === 'action') return actions.has(parsed.name)
+    if (parsed.kind === 'objectSet') return objectSets.has(parsed.name)
+    return refs.has(ref)
+  }
+}
+
+/** Why an absent reference is absent, in words: "isn’t connected here". */
+export function absentWhy(ref: string): string {
+  const kind = parseRef(ref)?.kind
+  if (kind === 'plugin') return 'isn’t connected here'
+  if (kind === 'objectType' || kind === 'action') return 'the local runtime leaves it off'
+  return 'isn’t on this runtime'
+}
+
+const LINK = /\[\[([A-Za-z]+):([^\]\s]+)\]\]/g
+
+type Json = Record<string, unknown>
+
+function at(doc: unknown, path: string[]): unknown {
+  let v = doc
+  for (const p of path) v = v && typeof v === 'object' ? (v as Json)[p] : undefined
+  return v
+}
+
+function setAt(doc: unknown, path: string[], value: unknown): void {
+  const parent = at(doc, path.slice(0, -1))
+  if (parent && typeof parent === 'object') (parent as Json)[path[path.length - 1]!] = value
+}
+
+/** A label for where a link sits: a procedure by name, an Agent's instructions, or the field. */
+function placeOf(doc: unknown, path: string[]): string {
+  if (path[0] === 'procedures' && /^\d+$/.test(path[1] ?? '')) return `procedure ‘${procedureName(at(doc, path.slice(0, 2)))}’`
+  if (path[0] === 'prompts') return 'its instructions'
+  return path.filter((p) => !/^\d+$/.test(p)).join('.') || 'the file'
+}
+
+function procedureName(proc: unknown): string {
+  const p = (proc ?? {}) as { name?: unknown; id?: unknown }
+  return String(p.name || p.id || 'unnamed')
+}
+
+/**
+ * Each link to an absent reference becomes its name as plain words
+ * (`[[plugin:google-sheets]]` → `google-sheets`), so the guidance still reads
+ * and no link points nowhere. Returns the warnings, one per link.
+ */
+export function plainLinks(doc: unknown, links: Unresolved[]): string[] {
+  const warnings: string[] = []
+  for (const u of links) {
+    const path = u.path.split('.')
+    const text = at(doc, path)
+    const ref = parseRef(u.value)
+    if (typeof text !== 'string' || !ref) continue
+    setAt(doc, path, text.replace(LINK, (whole, kind: string, name: string) => (kind === ref.kind && name === ref.name ? name : whole)))
+    warnings.push(`  warning: The link to ${refWords(u.value)} in ${placeOf(doc, path)} is plain text here: it ${absentWhy(u.value)}`)
+  }
+  return [...new Set(warnings)]
+}
+
+const REMOVE = Symbol('remove')
+
+/** Arrays whose elements are procedure steps. */
+const STEP_LISTS = new Set(['steps', 'onFailure', 'otherwise'])
+
+/**
+ * An Agent's behavior settings without what names an absent reference
+ * (`procedures.2.actions.0.functionId` = `function/x`). `doc` is changed in
+ * place. Returns one warning per omission, in words the build shows:
+ * "Procedure ‘Book a visit’ step 3 left out: uses Plugin google-sheets, which
+ * isn’t connected here".
+ */
+export function adaptOperating(doc: Json, absent: Unresolved[]): string[] {
+  const warnings: string[] = []
+  const removedActions = new Map<Json, Map<string, string>>()
+  const uses = (u: Unresolved) => `uses ${refWords(u.value)}, which ${absentWhy(u.value)}`
+  const remove = (path: string[]) => setAt(doc, path, REMOVE)
+  for (const u of absent) {
+    const path = u.path.split('.')
+    if (path[0] === 'procedures' && /^\d+$/.test(path[1] ?? '')) {
+      const proc = at(doc, path.slice(0, 2)) as Json | undefined
+      if (!proc || typeof proc !== 'object') continue
+      const name = procedureName(proc)
+      const rel = path.slice(2)
+      if ((rel[0] === 'tools' || rel[0] === 'knowledge') && rel[1] === 'ids' && /^\d+$/.test(rel[2] ?? '')) {
+        remove(path.slice(0, 5))
+        warnings.push(`  warning: Procedure ‘${name}’ goes without ${refWords(u.value)}: it ${absentWhy(u.value)}`)
+        continue
+      }
+      if (rel[0] === 'actions' && /^\d+$/.test(rel[1] ?? '')) {
+        const action = at(proc, rel.slice(0, 2)) as Json | undefined
+        if (action && typeof action.id === 'string') {
+          const byProc = removedActions.get(proc) ?? new Map<string, string>()
+          byProc.set(action.id, `Procedure ‘${name}’ action ‘${String(action.label || action.id)}’ ${uses(u)}`)
+          removedActions.set(proc, byProc)
+        }
+        remove(path.slice(0, 4))
+        continue
+      }
+      // The innermost step that holds it.
+      let step = -1
+      for (let i = rel.length - 2; i >= 0; i--) {
+        if (STEP_LISTS.has(rel[i]!) && /^\d+$/.test(rel[i + 1] ?? '')) {
+          step = i
+          break
+        }
+      }
+      if (step >= 0) {
+        remove([...path.slice(0, 2), ...rel.slice(0, step + 2)])
+        warnings.push(`  warning: Procedure ‘${name}’ step ${Number(rel[step + 1]) + 1} left out: ${uses(u)}`)
+        continue
+      }
+      proc.enabled = false
+      warnings.push(`  warning: Procedure ‘${name}’ is switched off: it ${uses(u)}`)
+      continue
+    }
+    // Outside the procedures: the innermost list entry that holds it, else the field.
+    const last = path.findLastIndex((p) => /^\d+$/.test(p))
+    const held = last >= 0 ? path.slice(0, last + 1) : path
+    remove(held)
+    const field = held.filter((p) => !/^\d+$/.test(p)).join('.') || 'a setting'
+    warnings.push(`  warning: ${last >= 0 ? `An entry of ${field}` : `The setting ${field}`} left out: ${uses(u)}`)
+  }
+  // An action left out takes the steps that run it, and the strict block before it, along.
+  for (const [proc, actions] of removedActions) {
+    const ids = new Set(actions.keys())
+    const needed = [(proc.verification as Json | undefined)?.actionId, (proc.completion as Json | undefined)?.actionId].some((id) => typeof id === 'string' && ids.has(id))
+    if (needed) {
+      proc.enabled = false
+      for (const why of actions.values()) warnings.push(`  warning: ${why}; the procedure is switched off, as it can’t finish without it`)
+      continue
+    }
+    const strip = (v: unknown): unknown => {
+      if (Array.isArray(v)) return v.filter((s) => !(s && typeof s === 'object' && (((s as Json).type === 'run' && ids.has(String((s as Json).actionId))) || ((s as Json).anchor === 'before-action' && ids.has(String((s as Json).actionId)))))).map(strip)
+      if (v && typeof v === 'object') return Object.fromEntries(Object.entries(v as Json).map(([k, x]) => [k, strip(x)]))
+      return v
+    }
+    for (const key of ['blocks', 'steps']) if (proc[key] !== undefined) proc[key] = strip(proc[key])
+    for (const why of actions.values()) warnings.push(`  warning: ${why}; it is left out, with the steps that run it`)
+  }
+  sweep(doc)
+  return [...new Set(warnings)]
+}
+
+/** Drop what was marked for removal, at any depth. */
+function sweep(v: unknown): void {
+  if (Array.isArray(v)) {
+    for (let i = v.length - 1; i >= 0; i--) if (v[i] === REMOVE) v.splice(i, 1)
+    for (const x of v) sweep(x)
+    return
+  }
+  if (v && typeof v === 'object') {
+    for (const [k, x] of Object.entries(v as Json)) {
+      if (x === REMOVE) delete (v as Json)[k]
+      else sweep(x)
+    }
+  }
+}

package/src/local/local-agent-files.ts

@@ -3,9 +3,11 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { contentHash, loadHashes, saveHashes } from './local-applied'
+import { localDirectory, resolveTarget } from './local-dev-references'
 import { localProfileName } from './local-control'
 import { targetFor } from './local-dev-sync'
 import type { LocalProject } from './local-project'
+import { readState } from './local-state'
 
 /**
  * Studio's editor, the counterpart of Mastra Studio's: a change made in the
@@ -94,6 +96,7 @@ export async function saveAgentEdit(
   organizationId: string,
   slug: string,
   edit: AgentFileEdit,
+  serviceUrl?: string,
 ): Promise<{ path: string; changed: boolean; applied: boolean; output: string }> {
   const path = agentFilePath(project.root, slug)
   const rel = join('agents', slug, 'agent.json')
@@ -109,9 +112,13 @@ export async function saveAgentEdit(
   }
   if (next === null) return { path: rel, changed: false, applied: true, output: '' }
   writeFileSync(path, next)
-  const result = await applyWithCli(project, slug, rel)
+  // Names in the file (`skill/acme-reply-style`) are applied as this runtime's ids, as `local dev` does.
+  const target = targetFor(project.root, path)
+  const creds = readState(project)?.credentials
+  const resolved = target && serviceUrl && creds ? await resolveTarget(project, target, () => localDirectory(serviceUrl, creds), creds.workspaceId) : { ok: true, output: '' }
+  if (!resolved.ok) return { path: rel, changed: true, applied: false, output: resolved.output.split('\n').slice(0, 6).join('\n') }
+  const result = await applyWithCli(project, slug, 'file' in resolved && resolved.file ? resolved.file : rel)
   if (result.ok) {
-    const target = targetFor(project.root, path)
     if (target) {
       const applied = loadHashes(project, organizationId)
       applied.set(target.key, contentHash(project, target))

package/src/local/local-agent-grants.ts

@@ -0,0 +1,125 @@
+import { parseRef } from './local-sync-refs'
+import type { LocalCredentials } from './local-state'
+
+/**
+ * An Agent's Context and data on the local runtime: the object types it may
+ * read through its Blueprint tools, from the `blueprint` list in its
+ * `agents/<slug>/bindings.json` (`{ "objectType": "objectType/Incident",
+ * "permissions": ["read"] }`). On the platform these are the Agent's
+ * Blueprint grants; without them it has no Blueprint tools at all.
+ *
+ * Granting is a Steward's call on the organization's Blueprint, so it is made
+ * with the runtime's organization key, after the Blueprint is applied and
+ * published (bindings apply after it). The runtime ends up with the file's
+ * grants: missing ones are granted, changed permissions replaced, and grants
+ * the file does not list revoked. An object type the runtime leaves off
+ * (media files) is skipped with a warning; one it does not hold yet waits
+ * for the Blueprint to build, so the Agent's tools read as blocked on it.
+ */
+
+export interface AgentGrant {
+  objectType: string
+  permissions?: string[]
+}
+
+export interface GrantOutcome {
+  /** One line each, `  objectType/X: why`, as the other bindings report a refusal. */
+  failures: string[]
+  /** `  warning: …` lines (adaptations) and plain lines for the log. */
+  notes: string[]
+}
+
+/** The build's word on object types it left off, by API name, with why. */
+export type LeftOff = (apiName: string) => string | null
+
+export async function applyAgentGrants(input: {
+  slug: string
+  grants: AgentGrant[]
+  serviceUrl: string
+  creds: LocalCredentials
+  /** Object types the last Blueprint build left off (`build.json`). */
+  leftOff: LeftOff
+  /** Whether the project's Blueprint has a file for this object type. */
+  inProject: (apiName: string) => boolean
+  fetch?: typeof fetch
+}): Promise<GrantOutcome> {
+  const { slug, creds } = input
+  const doFetch = input.fetch ?? fetch
+  const failures: string[] = []
+  const notes: string[] = []
+  const call = async (key: string | undefined, path: string, method = 'GET', body?: unknown): Promise<{ ok: boolean; status: number; data: unknown; text: string }> => {
+    const res = await doFetch(new URL(path, input.serviceUrl), {
+      method,
+      headers: { authorization: `Bearer ${key ?? ''}`, 'content-type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+    const text = await res.text()
+    let data: unknown = null
+    try {
+      data = JSON.parse(text)
+    } catch {
+      // Not JSON: the text is the message.
+    }
+    return { ok: res.ok, status: res.status, data, text }
+  }
+  const list = <T>(body: unknown): T[] => {
+    let v = body
+    for (let i = 0; i < 3 && v && !Array.isArray(v) && typeof v === 'object' && 'data' in (v as object); i++) v = (v as { data: unknown }).data
+    return Array.isArray(v) ? (v as T[]) : []
+  }
+  const brief = (r: { status: number; text: string }) => `${r.status} ${r.text.slice(0, 200)}`
+
+  // Wanted: by API name, the file's permissions (read when it names none).
+  const wanted = new Map<string, string[]>()
+  for (const g of input.grants) {
+    const ref = typeof g?.objectType === 'string' ? parseRef(g.objectType) : null
+    if (!ref || ref.kind !== 'objectType') {
+      failures.push(`  ${String(g?.objectType)}: not an object type reference (objectType/<apiName>)`)
+      continue
+    }
+    wanted.set(ref.name, [...(Array.isArray(g.permissions) && g.permissions.length ? g.permissions : ['read'])].sort())
+  }
+
+  // The workspace's own list, which holds Agents never published too; the organization's
+  // Blueprint list (`org-agents`) leaves those out, and a pulled draft is one of them.
+  const agents = await call(creds.workspaceKey, '/v1/sync/agents')
+  if (!agents.ok) return { failures: [...failures, `  agent/${slug}: the runtime’s Agents could not be read: ${brief(agents)}`], notes }
+  const agent = list<{ id: string; agentId?: string }>(agents.data).find((a) => a.agentId === slug)
+  if (!agent) return { failures: [...failures, `  agent/${slug}: not found on the runtime`], notes }
+
+  const held = await call(creds.workspaceKey, '/v1/blueprint/object-types')
+  const onRuntime = new Set(held.ok ? list<{ apiName?: string }>(held.data).flatMap((t) => (t.apiName ? [t.apiName] : [])) : [])
+  const current = await call(creds.orgKey, `/v1/blueprint/grants/agent/${encodeURIComponent(agent.id)}`)
+  if (!current.ok) return { failures: [...failures, `  agent/${slug}: its Blueprint access could not be read: ${brief(current)}`], notes }
+  const has = new Map(list<{ objectTypeApiName: string; permissions?: string[] }>(current.data).map((g) => [g.objectTypeApiName, [...(g.permissions ?? ['read'])].sort()]))
+
+  let granted = 0
+  for (const [apiName, permissions] of wanted) {
+    const why = input.leftOff(apiName)
+    if (why) {
+      notes.push(`  warning: Context and data: ${apiName} is left off here (${why}), so ${slug} can’t read it locally`)
+      continue
+    }
+    if (!onRuntime.has(apiName)) {
+      // The Blueprint does not hold it (yet): blocked until it builds, or named by nothing in the project.
+      failures.push(`  objectType/${apiName}: ${input.inProject(apiName) ? 'not on the runtime yet: the Blueprint isn’t built' : 'not found in the project’s Blueprint'}`)
+      continue
+    }
+    if (has.get(apiName)?.join(',') !== permissions.join(',')) {
+      const res = await call(creds.orgKey, '/v1/blueprint/grants/agent', 'POST', { agentId: agent.id, objectTypeApiName: apiName, permissions })
+      if (!res.ok) {
+        failures.push(`  objectType/${apiName}: ${brief(res)}`)
+        continue
+      }
+    }
+    granted += 1
+  }
+  // The file is what the Agent may read: a grant it does not list is withdrawn.
+  for (const apiName of has.keys()) {
+    if (wanted.has(apiName)) continue
+    const res = await call(creds.orgKey, `/v1/blueprint/grants/agent/${encodeURIComponent(agent.id)}/${encodeURIComponent(apiName)}`, 'DELETE')
+    if (!res.ok) failures.push(`  objectType/${apiName}: could not be revoked: ${brief(res)}`)
+  }
+  if (granted) notes.push(`  Context and data: ${granted} object type${granted === 1 ? '' : 's'}`)
+  return { failures, notes }
+}

package/src/local/local-agent-name.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { LocalCredentials } from './local-state'
+
+/**
+ * An Agent's name and description on the local runtime, as its file has them.
+ *
+ * The Agent's row carries the name the platform lists it by (Studio's lists,
+ * breadcrumbs and pickers). On the platform, publishing moves the draft's
+ * name onto the row; `local dev` keeps Agents as drafts (Studio runs the
+ * draft), so the row kept whatever it was created with: the slug, since
+ * `agent create` was called without one. A pulled "Telco Operations" read
+ * `telco-operations` everywhere.
+ *
+ * So `local dev` creates an Agent with its name, and after each apply of
+ * `agents/<slug>/agent.json` sets the row's name and description when they
+ * differ from the file's. Only the row changes: the draft already holds them.
+ */
+
+export interface AgentIdentity {
+  name?: string
+  description?: string
+}
+
+/** `config.name` and `config.description` from an Agent's file; empty when it has none or does not parse. */
+export function agentIdentity(root: string, file: string): AgentIdentity {
+  try {
+    const doc = JSON.parse(readFileSync(join(root, file), 'utf8')) as { config?: { name?: unknown; description?: unknown }; snapshot?: { config?: { name?: unknown; description?: unknown } } }
+    const config = doc.snapshot?.config ?? doc.config ?? {}
+    const text = (v: unknown) => (typeof v === 'string' && v.trim() ? v.trim() : undefined)
+    return { ...(text(config.name) ? { name: text(config.name) } : {}), ...(text(config.description) ? { description: text(config.description) } : {}) }
+  } catch {
+    return {}
+  }
+}
+
+/** The flags `agent create` takes for them. */
+export function createFlags(identity: AgentIdentity): string[] {
+  return [...(identity.name ? ['--name', identity.name] : []), ...(identity.description ? ['--description', identity.description] : [])]
+}
+
+/**
+ * Set the row's name and description to the file's where they differ.
+ * Returns a line for the log (a `warning:` one when it could not), or null
+ * when nothing changed. Never throws:
+ * a name that could not be set is a warning, not a failed apply.
+ */
+export async function syncAgentName(input: { slug: string; identity: AgentIdentity; serviceUrl: string; creds: LocalCredentials; fetch?: typeof fetch }): Promise<string | null> {
+  const { identity, creds } = input
+  if (!identity.name && !identity.description) return null
+  const doFetch = input.fetch ?? fetch
+  const headers = { authorization: `Bearer ${creds.workspaceKey ?? ''}`, 'content-type': 'application/json' }
+  try {
+    const listed = await doFetch(new URL('/v1/sync/agents', input.serviceUrl), { headers })
+    if (!listed.ok) return `  warning: ${input.slug}'s name could not be checked (${listed.status})`
+    const body = (await listed.json()) as { data?: Array<{ id: string; agentId: string; name?: string | null; description?: string | null }> }
+    const row = body.data?.find((a) => a.agentId === input.slug)
+    if (!row) return null
+    const patch: Record<string, string> = {}
+    if (identity.name && row.name !== identity.name) patch.name = identity.name
+    if (identity.description && (row.description ?? '') !== identity.description) patch.description = identity.description
+    if (!Object.keys(patch).length) return null
+    // `direct`: the row itself, as a publish would set it; the draft already has these.
+    const res = await doFetch(new URL(`/v1/config/agents/${encodeURIComponent(row.id)}?direct=1`, input.serviceUrl), { method: 'PATCH', headers, body: JSON.stringify(patch) })
+    if (!res.ok) return `  warning: ${input.slug}'s name could not be set (${res.status})`
+    return patch.name ? `  named ${input.slug} “${patch.name}”` : `  updated ${input.slug}’s description`
+  } catch (err) {
+    return `  warning: ${input.slug}'s name could not be set: ${(err as Error).message}`
+  }
+}