@frontera-sdk/cli 1.53.9 → 1.53.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.53.9",
+  "version": "1.53.11",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -40,16 +40,16 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
     "@faker-js/faker": "10.6.0",
-    "@frontera-sdk/core": "1.53.9",
-    "@frontera-sdk/functions": "1.53.9",
-    "ai": "^6.0.116",
+    "@frontera-sdk/core": "1.53.11",
+    "@frontera-sdk/functions": "1.53.11",
+    "ai": "^6.0.319",
     "axe-core": "4.12.1",
     "gray-matter": "^4.0.3",
     "playwright-core": "1.63.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.53.9",
+    "@frontera-sdk/forge-contracts": "1.53.11",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/platform-api.ts

@@ -965,6 +965,49 @@ export class PlatformApi {
     )
   }
 
+  // ── Voice phone numbers ───────────────────────────────────────────────────
+
+  /** The numbers an Agent answers, and whether the deployment has a phone system. Served by the Voice application. */
+  voiceNumbers(agentId: string) {
+    return this.get<{ numbers: unknown[]; available: boolean }>(`/v1/voice-calls/agents/${encodeURIComponent(agentId)}/numbers`)
+  }
+
+  addVoiceNumber(agentId: string, body: { number?: string; source: 'whatsapp'; channelId?: string | null; callHours?: unknown }) {
+    return this.client.request<{ number: unknown }>(`/v1/voice-calls/agents/${encodeURIComponent(agentId)}/numbers`, { method: 'POST', body })
+  }
+
+  applyVoiceNumber(numberId: string) {
+    return this.client.request<{ number: unknown }>(`/v1/voice-calls/numbers/${encodeURIComponent(numberId)}/apply`, { method: 'POST' })
+  }
+
+  setVoiceNumberEnabled(numberId: string, enabled: boolean) {
+    return this.client.request<{ number: unknown }>(`/v1/voice-calls/numbers/${encodeURIComponent(numberId)}/enabled`, { method: 'PUT', body: { enabled } })
+  }
+
+  /** Changes a number's call hours (null: any time) and applies them again. */
+  setVoiceNumberHours(numberId: string, callHours: unknown) {
+    return this.client.request<{ number: unknown }>(`/v1/voice-calls/numbers/${encodeURIComponent(numberId)}/hours`, { method: 'PUT', body: { callHours } })
+  }
+
+  /** Starts a call from one of the Agent's numbers. A refusal is a 409 the caller reads. */
+  startVoiceCall(agentId: string, body: { numberId: string; to: string }) {
+    return this.client.request<{ callId: string; status: string }>(`/v1/voice-calls/agents/${encodeURIComponent(agentId)}/calls`, { method: 'POST', body })
+  }
+
+  voiceCallPermission(numberId: string, to: string) {
+    return this.get<{ permission: { status: string; expiresAt?: string; canCall: boolean; canRequest: boolean } }>(
+      `/v1/voice-calls/numbers/${encodeURIComponent(numberId)}/call-permission?to=${encodeURIComponent(to)}`,
+    )
+  }
+
+  requestVoiceCallPermission(numberId: string, body: { to: string; message?: string }) {
+    return this.client.request<{ requested: boolean }>(`/v1/voice-calls/numbers/${encodeURIComponent(numberId)}/call-permission-requests`, { method: 'POST', body })
+  }
+
+  removeVoiceNumber(numberId: string) {
+    return this.client.request<unknown>(`/v1/voice-calls/numbers/${encodeURIComponent(numberId)}`, { method: 'DELETE' })
+  }
+
   // ── Workspace secrets ─────────────────────────────────────────────────────
 
   /**

package/src/blueprint/compile.ts

@@ -72,6 +72,36 @@ export function readBacking(file: AuthoredFile): AuthoredBacking | undefined {
   }
 }
 
+/** A file's property that reads no column: only Actions write its values. */
+export function isEditOnly(property: unknown): boolean {
+  return (property as { editOnly?: unknown } | null)?.editOnly === true
+}
+
+/**
+ * The file shape of every edit-only property, refused before any write. It reads no
+ * column, so `backing.mapping` names none for it; and only an Action can give it a
+ * value, so a file that states `backing.editable` lists it there.
+ */
+export function assertEditOnlyShape(file: AuthoredFile): void {
+  const backing = readBacking(file)
+  const declared = Array.isArray(file.document.properties) ? file.document.properties as Array<Record<string, unknown>> : []
+  for (const property of declared.filter(isEditOnly)) {
+    const name = String(property.apiName)
+    if (backing?.mapping?.[name] !== undefined) {
+      throw new CliError(`${file.path}: property "${name}" is edit-only and reads no column, but backing.mapping names one for it.`, {
+        code: 'USAGE',
+        hint: `Remove "${name}" from backing.mapping, or drop \`editOnly: true\` to read that column.`,
+      })
+    }
+    if (backing?.editable && !backing.editable.includes(name)) {
+      throw new CliError(`${file.path}: property "${name}" is edit-only, so only an Action can give it a value, and backing.editable does not list it.`, {
+        code: 'USAGE',
+        hint: `Add "${name}" to backing.editable.`,
+      })
+    }
+  }
+}
+
 /**
  * `sharedField: accountCode` → the uuid the wire takes. THREE-VALUED, because the
  * authored key has three states and the wire has the same three:
@@ -211,10 +241,13 @@ export async function objectTypeCreateBody(
     })
   }
 
+  assertEditOnlyShape(file)
   const { revisionId } = await resolveDataset(backing.dataset)
   // A calculated field (a location from latitude and longitude) reads no column, and the
-  // create route has no channel for it: it is added after the type, by `add_field`.
-  const properties = (Array.isArray(document.properties) ? document.properties : []).filter((entry) => !(entry as { calculation?: unknown }).calculation)
+  // create route has no channel for it: it is added after the type, by `add_field`. So
+  // is an edit-only one, which reads no column either.
+  const properties = (Array.isArray(document.properties) ? document.properties : [])
+    .filter((entry) => !(entry as { calculation?: unknown }).calculation && !isEditOnly(entry))
 
   return {
     apiName: requireString(document, 'apiName', file.path),

package/src/blueprint/dataset-revision.ts

@@ -48,15 +48,16 @@ export interface ColumnMapping {
  * Shared by `bind` and by `apply`'s rebind, which send the same draft command.
  */
 export function columnMappingsFrom(
-  properties: ReadonlyArray<{ id?: string; apiName?: string; calculation?: unknown }>,
+  properties: ReadonlyArray<{ id?: string; apiName?: string; calculation?: unknown; editOnly?: unknown }>,
   mapping: Readonly<Record<string, MappingEntry | null | undefined>>,
 ): { columnMappings: ColumnMapping[]; unmapped: string[] } {
   const columnMappings: ColumnMapping[] = []
   const unmapped: string[] = []
   for (const property of properties) {
     const name = property.apiName
-    // A calculated field (a location from latitude and longitude) reads no column.
-    if (!name || property.calculation) continue
+    // A calculated field (a location from latitude and longitude) reads no column, nor
+    // does an edit-only one: its values are the ones Actions write.
+    if (!name || property.calculation || property.editOnly) continue
     const entry = mapping[name]
     if (entry === undefined || entry === null) {
       unmapped.push(name)

package/src/blueprint/diff.ts

@@ -282,12 +282,15 @@ function describeUpdate(local: Record<string, unknown>, live: Record<string, unk
   const replacements = (intents?.replacements ?? []).filter((entry) => entry.objectApiName === objectApiName)
   const added = after.filter((name) => !before.has(name) && !replacements.some((entry) => entry.added === name))
   const removed = [...before].filter((name) => !after.includes(name) && !replacements.some((entry) => entry.removed === name))
+  // An edit-only field is named as one: it reads no column, so its values start empty.
+  const editOnly = new Set((Array.isArray(local.properties) ? local.properties as Array<Record<string, unknown>> : [])
+    .filter((property) => property.editOnly === true).map((property) => String(property.apiName)))
   const parts: string[] = [
     ...(intents?.renames ?? []).filter((entry) => entry.objectApiName === objectApiName)
       .map((entry) => `rename ${entry.from} → ${entry.to} (its values, edits and references stay)`),
     ...replacements.map((entry) => `replace ${entry.removed} with ${entry.added} (${entry.removed}'s values are not carried over)`),
   ]
-  if (added.length) parts.push(`+${added.length} propert${added.length === 1 ? 'y' : 'ies'} (${added.join(', ')})`)
+  if (added.length) parts.push(`+${added.length} propert${added.length === 1 ? 'y' : 'ies'} (${added.map((name) => editOnly.has(name) ? `${name}: edit-only, no column` : name).join(', ')})`)
   if (removed.length) parts.push(`-${removed.length} propert${removed.length === 1 ? 'y' : 'ies'} (${removed.join(', ')})`)
   return parts.length ? parts.join(', ') : 'fields changed'
 }

package/src/commands/blueprint/declarative.ts

@@ -3,6 +3,8 @@ import { join, resolve } from 'node:path'
 
 import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
 import {
+  assertEditOnlyShape,
+  isEditOnly,
   linkTypeCreateBody,
   linkTypeStructure,
   objectTypeCreateBody,
@@ -619,7 +621,8 @@ export async function applyOperation(
         await objectTypeCreateBody(file, revision, resolveDataset, ids),
         revision,
       )
-      return applyCalculatedFields(client, operation.apiName, file, nextRevision(created, revision))
+      const withCalculated = await applyCalculatedFields(client, operation.apiName, file, nextRevision(created, revision))
+      return applyEditOnlyFields(client, operation.apiName, file, withCalculated, ids)
     }
     // Refused BEFORE the first write, not after some of them. Everything this
     // executor can express is enumerated below; a difference outside that set has no
@@ -780,6 +783,7 @@ export function assertApplicable(
   live: Record<string, unknown> | undefined,
 ): void {
   if (!live) return
+  if (kind === 'object-type') assertEditOnlyKept(file, live)
   const applicable = APPLICABLE_FIELDS[kind]
   // The SAME predicate the plan used to decide this artifact changed. An equality
   // comparison here would disagree with it about key order and about the fields a file
@@ -915,6 +919,98 @@ async function applyCalculatedFields(client: BlueprintAuthoringApi, apiName: str
   return current
 }
 
+/**
+ * A field is edit-only from the moment it is added, or never: the values Actions
+ * wrote and the values a column holds are not the same values, and no command moves
+ * one into the other. A file and a draft that disagree about it are refused by name.
+ */
+function assertEditOnlyKept(file: AuthoredFile, live: Record<string, unknown>): void {
+  const declared = Array.isArray(file.document.properties) ? file.document.properties as Array<Record<string, unknown>> : []
+  const liveByName = new Map((Array.isArray(live.properties) ? live.properties as Array<Record<string, unknown>> : [])
+    .map((property) => [String(property.apiName), property]))
+  for (const property of declared) {
+    const counterpart = liveByName.get(String(property.apiName))
+    if (!counterpart || isEditOnly(property) === isEditOnly(counterpart)) continue
+    throw new CliError(
+      `${file.path}: property "${String(property.apiName)}" ${isEditOnly(property) ? 'is edit-only in the file but reads a column on the draft' : 'is edit-only on the draft but not in the file'}.`,
+      {
+        code: 'USAGE',
+        hint: 'A field is edit-only from when it is added, or never. Add a new field with the other choice, '
+          + 'and remove this one once nothing needs its values.',
+      },
+    )
+  }
+}
+
+/**
+ * The `add_field` a file's property is added with: its column, or none for an
+ * edit-only one, which the service makes editable in the same command.
+ */
+function addFieldCommand(
+  objectId: string,
+  file: AuthoredFile,
+  property: Record<string, unknown>,
+  mapped: string | { column: string; field?: string | null } | undefined,
+  ids: AuthoringIds,
+): Record<string, unknown> {
+  const name = String(property.apiName)
+  const column = mapped === undefined ? '' : typeof mapped === 'string' ? mapped : mapped.column
+  const sourceField = mapped === undefined || typeof mapped === 'string' ? undefined : mapped.field
+  // Resolved here rather than at plan time: a shared field created earlier in
+  // this same run only entered the map when its create answered.
+  const sharedPropertyId = resolveSharedProperty(file, name, property.sharedField, ids.sharedPropertyIdByApiName)
+  const semanticTypeId = resolveSemanticType(file, `field "${name}"`, property.semanticType, ids.semanticTypeIdByApiName)
+  return {
+    kind: 'add_field',
+    objectId,
+    field: {
+      // The one identifier the CLI generates, and it never reaches a file: the
+      // command addresses a field that does not exist yet, so there is nothing on
+      // the draft to resolve a name against. It lives for one request.
+      id: crypto.randomUUID(),
+      apiName: name,
+      displayName: String(property.displayName ?? name),
+      propertyType: declaredPropertyType(property, ids.sharedPropertyTypeByApiName),
+      valueType: String(property.valueType ?? 'string'),
+      sourceColumn: column,
+      ...(sourceField === undefined || sourceField === null ? {} : { sourceField }),
+      ...(isEditOnly(property) ? { editOnly: true } : {}),
+      required: Boolean(property.required ?? false),
+      unique: Boolean(property.unique ?? false),
+      status: 'active',
+      visibility: 'normal',
+      // A field being ADDED has no reference to detach, so an authored `null`
+      // is simply "no shared field" — `add_field`'s uuid is not nullable, and a
+      // detach command on a field that is being created makes no sense anyway.
+      ...(typeof sharedPropertyId === 'string' ? { sharedPropertyId } : {}),
+      // Same collapse: `add_field`'s uuid is not nullable, and a field being
+      // created has no meaning to detach from.
+      ...(typeof semanticTypeId === 'string' ? { semanticTypeId } : {}),
+      // Its own classification, when the file gives one other than the object type's.
+      ...fieldSensitivityOf(property, objectTypeSensitivity(file.document)),
+    },
+  }
+}
+
+/**
+ * A created type's edit-only fields: the create route takes only fields that read a
+ * column, so each is added after it, as a calculated one is.
+ */
+async function applyEditOnlyFields(client: BlueprintAuthoringApi, apiName: string, file: AuthoredFile, revision: number, ids: AuthoringIds): Promise<number> {
+  const declared = Array.isArray(file.document.properties) ? (file.document.properties as Array<Record<string, unknown>>).filter(isEditOnly) : []
+  if (!declared.length) return revision
+  const detail = await client.getObjectTypeDetail(apiName)
+  if (!detail?.id) return revision
+  const present = new Set(detail.properties.map((property) => String(property.apiName)))
+  let current = revision
+  for (const property of declared) {
+    if (present.has(String(property.apiName))) continue
+    current = (await client.draftCommand(addFieldCommand(detail.id, file, property, undefined, ids), current)
+      .catch((err) => { throw stewardRefusal(err, file, String(property.apiName), fieldSensitivityOf(property, objectTypeSensitivity(file.document)).sensitivity !== undefined) })).revision
+  }
+  return current
+}
+
 /**
  * `primaryKey` and `title` — the two references a file states by property apiName.
  *
@@ -1204,16 +1300,19 @@ async function applyPropertyPlan(
     : []
   const plan = planProperties(file, liveProperties, backing, idByApiName, objectTypeSensitivity(liveDocument ?? {}))
 
+  assertEditOnlyShape(file)
   // Every add needs a column, and the service offers no name-match fallback. Checked
-  // for ALL of them before the first write, so a partial run cannot start.
+  // for ALL of them before the first write, so a partial run cannot start. An
+  // edit-only field reads none.
   for (const property of plan.adds) {
     const name = String(property.apiName)
-    if (backing?.mapping?.[name] === undefined) {
+    if (!isEditOnly(property) && backing?.mapping?.[name] === undefined) {
       throw new CliError(
         `${file.path}: new property "${name}" has no column in \`backing.mapping\`.`,
         {
           code: 'USAGE',
-          hint: 'A property reads a column, and there is no name-match fallback. Add it to backing.mapping.',
+          hint: 'A property reads a column, and there is no name-match fallback. Add it to backing.mapping, '
+            + 'or, for a field only Actions write, add `editOnly: true` to it.',
         },
       )
     }
@@ -1222,46 +1321,9 @@ async function applyPropertyPlan(
   let current = revision
   for (const property of plan.adds) {
     const name = String(property.apiName)
-    const mapped = backing!.mapping[name]!
-    const column = typeof mapped === 'string' ? mapped : mapped.column
-    const sourceField = typeof mapped === 'string' ? undefined : mapped.field
-    // Resolved here rather than at plan time: a shared field created earlier in
-    // this same run only entered the map when its create answered.
-    const sharedPropertyId = resolveSharedProperty(
-      file, name, property.sharedField, ids.sharedPropertyIdByApiName,
-    )
-    const semanticTypeId = resolveSemanticType(
-      file, `field "${name}"`, property.semanticType, ids.semanticTypeIdByApiName,
-    )
-    const result = await client.draftCommand({
-      kind: 'add_field',
-      objectId: detail.id,
-      field: {
-        // The one identifier the CLI generates, and it never reaches a file: the
-        // command addresses a field that does not exist yet, so there is nothing on
-        // the draft to resolve a name against. It lives for one request.
-        id: crypto.randomUUID(),
-        apiName: name,
-        displayName: String(property.displayName ?? name),
-        propertyType: declaredPropertyType(property, ids.sharedPropertyTypeByApiName),
-        valueType: String(property.valueType ?? 'string'),
-        sourceColumn: column,
-        ...(sourceField === undefined || sourceField === null ? {} : { sourceField }),
-        required: Boolean(property.required ?? false),
-        unique: Boolean(property.unique ?? false),
-        status: 'active',
-        visibility: 'normal',
-        // A field being ADDED has no reference to detach, so an authored `null`
-        // is simply "no shared field" — `add_field`'s uuid is not nullable, and a
-        // detach command on a field that is being created makes no sense anyway.
-        ...(typeof sharedPropertyId === 'string' ? { sharedPropertyId } : {}),
-        // Same collapse: `add_field`'s uuid is not nullable, and a field being
-        // created has no meaning to detach from.
-        ...(typeof semanticTypeId === 'string' ? { semanticTypeId } : {}),
-        // Its own classification, when the file gives one other than the object type's.
-        ...fieldSensitivityOf(property, objectTypeSensitivity(file.document)),
-      },
-    }, current).catch((err) => { throw stewardRefusal(err, file, name, fieldSensitivityOf(property, objectTypeSensitivity(file.document)).sensitivity !== undefined) })
+    const mapped = isEditOnly(property) ? undefined : backing!.mapping[name]!
+    const result = await client.draftCommand(addFieldCommand(detail.id, file, property, mapped, ids), current)
+      .catch((err) => { throw stewardRefusal(err, file, name, fieldSensitivityOf(property, objectTypeSensitivity(file.document)).sensitivity !== undefined) })
     current = result.revision
   }
   for (const change of plan.schemaChanges) {

package/src/commands/local/steps.ts

@@ -1,6 +1,6 @@
 import { UsageError } from '../../errors'
 import { FRONTERA_READ_ONLY_COMMANDS } from '../../forge/permission-rules'
-import { addPersonStep, clearSettledSteps, CREDENTIAL_WORDS, CREDENTIALS, currentTarget, deliveryGroups, readPersonSteps, runStepChecks, settlePersonStep, staleProblem, type PersonStep, type StepTarget } from '../../local/local-person-steps'
+import { addPersonStep, clearSettledSteps, CREDENTIAL_WORDS, CREDENTIALS, deliveryGroups, readPersonSteps, runStepChecks, settlePersonStep, staleProblem, stepTargets, type PersonStep, type StepTarget } from '../../local/local-person-steps'
 import { runSelf } from '../../mcp/mcp-cli'
 import { localProject } from '../../local/local-project'
 import { flagBool, flagString, type Command } from '../types'
@@ -15,9 +15,9 @@ import { flagBool, flagString, type Command } from '../types'
 
 const ACTIONS = ['list', 'add', 'done', 'dismiss', 'reopen', 'check', 'clear'] as const
 
-function stepLines(steps: PersonStep[], current: StepTarget | null): string[] {
+function stepLines(steps: PersonStep[], targets: StepTarget[]): string[] {
   return steps.flatMap((s, n) => {
-    const stale = staleProblem(s, current)
+    const stale = staleProblem(s, targets)
     return [
       `  ${n + 1}. ${s.command ?? `${s.changes} (in the product)`}${s.check ? ' · checks itself' : ''}`,
       `     ${s.why} Changes: ${s.changes} Needs ${CREDENTIAL_WORDS[s.credential] ?? s.credential}. (${s.id})`,
@@ -101,7 +101,7 @@ export const localSteps: Command = {
     const groups = deliveryGroups(steps)
     const settled = steps.filter((s) => s.status !== 'pending')
     const lines = groups.length
-      ? groups.flatMap((g) => [g.delivery ? `${g.delivery}:` : 'Other steps:', ...stepLines(g.steps, currentTarget(project.root)), ''])
+      ? groups.flatMap((g) => [g.delivery ? `${g.delivery}:` : 'Other steps:', ...stepLines(g.steps, stepTargets(project.root)), ''])
       : ['No steps wait on the person.', '']
     if (flagBool(ctx, 'all') && settled.length) lines.push('Settled:', ...settled.map((s) => `  ${s.status === 'done' ? '✓' : '–'} ${s.command ?? s.changes} (${s.id})`))
     return { data: { pending: groups, ...(flagBool(ctx, 'all') ? { settled } : {}) }, text: lines.join('\n').trimEnd() }