@frontera-sdk/cli 1.52.38 → 1.52.40

package/README.md

@@ -112,6 +112,10 @@ project) and `frontera app init` (scaffold a new app) are different commands.
 
 `0` success · `1` transient · `2` usage · `3` conflict · `4` auth. Branch on
 them rather than on message text.
+Governed Action conflicts (a stale record version or approval, a record that
+already has an open request of the Action, a moved approval step) exit `3`,
+by code or by the refusal's `reason`; an idempotency key reused for another
+request exits `2` (`exit.ts`).
 
 ## Project configuration
 
@@ -137,6 +141,11 @@ gitignored `.frontera/state.json`. Existing projects that already use
 Next Apps consume the published `@frontera-sdk/core` and
 `@frontera-sdk/blueprint` packages. Existing Vite Apps retain vendored SDK
 source; `frontera app sdk sync` refreshes only that generated tree.
+On a local runtime started from a platform checkout (source mode),
+`frontera app sdk use-local` packs the checkout's `@frontera-sdk/*` packages
+into the App's `vendor/frontera-sdk/` and points `package.json` at them; commit
+that folder, and `--npm` switches back. It is a local development command and
+is kept out of the customer CLI reference.
 
 ## What `app init` does
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.52.38",
+  "version": "1.52.40",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -40,14 +40,16 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
     "@faker-js/faker": "10.6.0",
-    "@frontera-sdk/core": "1.52.38",
-    "@frontera-sdk/functions": "1.52.38",
+    "@frontera-sdk/core": "1.52.40",
+    "@frontera-sdk/functions": "1.52.40",
     "ai": "^6.0.116",
+    "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.52.38",
+    "@frontera-sdk/forge-contracts": "1.52.40",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/adopt.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 
 import { UsageError } from './errors'
 import { nextSkillFiles } from './templates/next-skills'
+import { SDK_RANGE } from './templates/next-app-files'
 
 /**
  * Turn an existing Next.js project into a Frontera App.
@@ -167,8 +168,8 @@ export interface AdoptionPlan {
  * project rather than by reading this list.
  */
 const REQUIRED_DEPENDENCIES: Record<string, string> = {
-  '@frontera-sdk/blueprint': '^1.43.10',
-  '@frontera-sdk/core': '^1.43.10',
+  '@frontera-sdk/blueprint': SDK_RANGE,
+  '@frontera-sdk/core': SDK_RANGE,
   '@tanstack/react-query': '^5.90.21',
   'class-variance-authority': '^0.7.1',
   clsx: '^2.1.1',
@@ -193,6 +194,8 @@ const NEXT_CONFIG_KEYS = [
   ['trailingSlash', 'true'],
   ['images', '{ unoptimized: true }'],
   ['transpilePackages', "['@frontera-sdk/core', '@frontera-sdk/blueprint', '@frontera-sdk/agents']"],
+  // Without it `next dev` rewrites AGENTS.md on every run, and a deploy refuses the build as stale.
+  ['agentRules', 'false'],
 ] as const
 
 export function planAdoption(target: AdoptionTarget): AdoptionPlan {
@@ -322,6 +325,7 @@ const nextConfig: NextConfig = {
   trailingSlash: true,
   images: { unoptimized: true },
   transpilePackages: ['@frontera-sdk/core', '@frontera-sdk/blueprint', '@frontera-sdk/agents'],
+  agentRules: false,
 }
 
 export default nextConfig

package/src/api/apps-api.ts

@@ -27,6 +27,49 @@ export interface AppVersionSummary {
   } | null
 }
 
+export interface DeploymentCheck {
+  id: 'build' | 'render' | 'contract' | 'a11y'
+  label: string
+  status: 'passed' | 'failed' | 'missing'
+  detail: string
+  required: boolean
+}
+
+export interface DeploymentRow {
+  id: string
+  label: string | null
+  producer: { kind: 'person' | 'workspace-key' | 'agent-key'; id: string; name: string | null }
+  session: { id: string; harness: string | null } | null
+  branch: string | null
+  commit: string | null
+  dirty: boolean
+  commitAuthor: string | null
+  changeRequestId: string | null
+  createdAt: string
+  productionAt: string | null
+  staged: boolean
+  pruned: { at: string; restorable: boolean } | null
+  /** `production`, `branch:<name>`, `session:<id>`. */
+  serves: string[]
+  renderEvidence: Record<string, unknown>
+  fileCount: number
+  totalBytes: number
+  url: string | null
+}
+
+export interface DeploymentLedger {
+  app: { id: string; slug: string; displayName: string }
+  production: {
+    deployment: string | null
+    label: string | null
+    pinned: { at: string; by: string | null; byName: string | null; reason: string | null; undoTo: string | null } | null
+  }
+  previews: Array<{ kind: 'branch' | 'session'; name: string; deployment: string | null; label: string | null; updatedAt: string; url: string | null }>
+  policy: { protectedApps: boolean; keysMayPromote: boolean; requiredChecks: string[] }
+  canPromote: boolean
+  deployments: DeploymentRow[]
+}
+
 export interface AppTokenResponse {
   token: string
   expiresAt: number
@@ -129,12 +172,16 @@ export class AppsApi {
   }
 
   publish(appId: string, args: {
-    version: string
+    /** An optional release label, unique per App. The deployment gets its own id. */
+    label?: string | null
+    /** Go live once the required checks pass (`--prod`); otherwise a preview. */
+    prod?: boolean
+    /** With `prod`: a staged production deployment, served by nothing until promoted. */
+    stage?: boolean
     parentVersion?: string | null
     dist: Uint8Array
     source: Uint8Array
     manifest?: unknown
-    promote: boolean
     /** §4.4 — whether this tree had been rendered since its last source change. */
     renderEvidence?: unknown
     /** Recorded build/package metadata; never trusted for authorization. */
@@ -143,20 +190,30 @@ export class AppsApi {
     thumbnail?: Uint8Array | null
   }) {
     const form = new FormData()
-    form.set('version', args.version)
+    if (args.label) form.set('label', args.label)
+    form.set('prod', args.prod ? 'true' : 'false')
+    if (args.prod && args.stage) form.set('stage', 'true')
     if (args.parentVersion) form.set('parentVersion', args.parentVersion)
     form.set('dist', new Blob([args.dist], { type: 'application/gzip' }), 'dist.tgz')
     form.set('source', new Blob([args.source], { type: 'application/gzip' }), 'src.tgz')
     if (args.manifest) form.set('manifest', JSON.stringify(args.manifest))
-    form.set('promote', args.promote ? 'true' : 'false')
     if (args.renderEvidence) form.set('renderEvidence', JSON.stringify(args.renderEvidence))
     if (args.provenance) form.set('provenance', JSON.stringify(args.provenance))
     if (args.thumbnail && args.thumbnail.byteLength > 0) {
       form.set('thumbnail', new Blob([args.thumbnail], { type: 'image/png' }), 'thumbnail.png')
     }
     return this.multipart<{
+      /** The deployment's id (`dpl_…`); `version` is the same, for older services. */
+      deployment?: string
       version: string
+      label?: string | null
       promoted: boolean
+      staged?: boolean
+      /** Asked for production and refused: the permission, the pin, or a required check. */
+      promoteRefused?: { message: string; code: string | null; checks?: DeploymentCheck[] }
+      branch?: string
+      branchUrl?: string
+      sessionUrl?: string
       fileCount: number
       totalBytes: number
       /** Where a person opens this exact build — composed by the service,
@@ -208,6 +265,31 @@ export class AppsApi {
     )
   }
 
+  /** The deployment ledger: production and its pin, the preview links, every deployment and what serves it. */
+  deployments(appId: string): Promise<DeploymentLedger> {
+    return this.client.request<DeploymentLedger>(`/v1/platform-apps/${appId}/deployments`)
+  }
+
+  checks(appId: string, deployment: string): Promise<{ deployment: string; checks: DeploymentCheck[] }> {
+    return this.client.request(`/v1/platform-apps/${appId}/deployments/${encodeURIComponent(deployment)}/checks`)
+  }
+
+  promote(appId: string, body: { deployment: string; force?: boolean; reason?: string }) {
+    return this.client.request<{ promoted: string; label: string | null; checks: DeploymentCheck[]; forced: string[]; liveUrl?: string }>(`/v1/platform-apps/${appId}/promote`, { method: 'POST', body })
+  }
+
+  rollback(appId: string, body: { deployment?: string; reason: string }) {
+    return this.client.request<{ from: string | null; fromLabel?: string | null; to: string; label: string | null; pinned: true }>(`/v1/platform-apps/${appId}/rollback`, { method: 'POST', body })
+  }
+
+  undoRollback(appId: string) {
+    return this.client.request<{ restored: string | null; label: string | null; pinned: false }>(`/v1/platform-apps/${appId}/rollback/undo`, { method: 'POST', body: {} })
+  }
+
+  unpin(appId: string, reason: string) {
+    return this.client.request<{ pinned: false; production: string | null; productionLabel?: string | null }>(`/v1/platform-apps/${appId}/unpin`, { method: 'POST', body: { reason } })
+  }
+
   deploy(appId: string, version: string) {
     return this.client.request<{ deployedVersion: string }>(`/v1/platform-apps/${appId}/deploy`, {
       method: 'POST',

package/src/api/blueprint-authoring-api.ts

@@ -96,6 +96,8 @@ export class BlueprintAuthoringApi {
       throw new CliError(payload?.message ?? `${res.status} ${text.slice(0, 200)}`, {
         code: (payload?.code as string) ?? 'FAILURE',
         hint: detail ?? 'frontera blueprint status',
+        // Kept whole: `plan` reads a refusal's reason from it (`withServiceActionChecks`).
+        ...(payload?.details !== undefined ? { details: payload.details } : {}),
       })
     }
 
@@ -456,14 +458,29 @@ export class BlueprintAuthoringApi {
     return this.call('/v1/blueprint/actions?view=draft')
   }
 
-  createAction(action: Record<string, unknown>, expectedRevision: number) {
-    return this.call('/v1/blueprint/actions', { method: 'POST', body: { expectedRevision, action } })
+  /**
+   * `inherited`: the Action is as the workspace it was pulled from holds it, so
+   * a semantic-type conflict it has is the workspace's. The local runtime then
+   * takes it as the workspace runs it; any other service ignores it.
+   */
+  createAction(action: Record<string, unknown>, expectedRevision: number, inherited = false) {
+    return this.call('/v1/blueprint/actions', { method: 'POST', body: { expectedRevision, action, ...(inherited ? { inherited } : {}) } })
+  }
+
+  /**
+   * The checks a create or update of this Action runs, against the current
+   * draft, with nothing written (`POST /v1/blueprint/actions/check`). Create
+   * or update is the service's call, by the action's apiName. A refusal
+   * throws as the write would.
+   */
+  checkAction(action: Record<string, unknown>, inherited = false): Promise<{ operation: 'create' | 'update' }> {
+    return this.call('/v1/blueprint/actions/check', { method: 'POST', body: { action, ...(inherited ? { inherited } : {}) } })
   }
 
-  updateAction(apiName: string, action: Record<string, unknown>, expectedRevision: number) {
+  updateAction(apiName: string, action: Record<string, unknown>, expectedRevision: number, inherited = false) {
     return this.call(`/v1/blueprint/actions/${encodeURIComponent(apiName)}`, {
       method: 'PUT',
-      body: { expectedRevision, action },
+      body: { expectedRevision, action, ...(inherited ? { inherited } : {}) },
     })
   }
 
@@ -498,22 +515,24 @@ export class BlueprintAuthoringApi {
     return this.call('/v1/blueprint/org-workspaces')
   }
 
-  orgAgents(): Promise<Array<{ id?: string; name?: string }>> {
+  /** The organization's Agents, unpublished ones too (`published`), each with its slug (`agentId`). */
+  orgAgents(): Promise<Array<{ id?: string; name?: string; agentId?: string; slug?: string; published?: boolean }>> {
     return this.call('/v1/blueprint/org-agents')
   }
 
-  workspaceGrants(workspaceId: string): Promise<Array<{ objectTypeApiName?: string }>> {
+  workspaceGrants(workspaceId: string): Promise<Array<{ objectTypeApiName?: string; permissions?: string[] }>> {
     return this.call(`/v1/blueprint/grants/workspace/${encodeURIComponent(workspaceId)}`)
   }
 
-  agentGrants(agentId: string): Promise<Array<{ objectTypeApiName?: string }>> {
+  agentGrants(agentId: string): Promise<Array<{ objectTypeApiName?: string; permissions?: string[] }>> {
     return this.call(`/v1/blueprint/grants/agent/${encodeURIComponent(agentId)}`)
   }
 
-  grantWorkspace(workspaceId: string, objectTypeApiName: string) {
+  /** `permissions` sets the grant's whole list (`read`, `read_sensitive`); left out, it is `read`. */
+  grantWorkspace(workspaceId: string, objectTypeApiName: string, permissions?: string[]) {
     return this.call('/v1/blueprint/grants/workspace', {
       method: 'POST',
-      body: { workspaceId, objectTypeApiName },
+      body: { workspaceId, objectTypeApiName, ...(permissions ? { permissions } : {}) },
     })
   }
 
@@ -524,10 +543,15 @@ export class BlueprintAuthoringApi {
     )
   }
 
-  grantAgent(agentId: string, objectTypeApiName: string) {
+  /**
+   * `permissions` is the grant's list (`read`, `read_sensitive`, `act`); left out, it is `read`.
+   * A re-grant keeps an `act` the grant already holds: the platform takes it away only when
+   * the request names it in `removePermissions`, as `local dev` does.
+   */
+  grantAgent(agentId: string, objectTypeApiName: string, permissions?: string[]) {
     return this.call('/v1/blueprint/grants/agent', {
       method: 'POST',
-      body: { agentId, objectTypeApiName },
+      body: { agentId, objectTypeApiName, ...(permissions ? { permissions } : {}) },
     })
   }
 

package/src/api/dataset-api.ts

@@ -327,6 +327,35 @@ export class DatasetApi {
     )
   }
 
+  /**
+   * A new revision of a managed (file) dataset from a CSV whose columns now
+   * allow empty values the current revision refuses: `POST
+   * /datasets/:id/revisions/from-file`, multipart with the CSV as `file` and
+   * the revision it follows as `expectedRevision`. The service allows only a
+   * widening of nullability; an added, dropped or retyped column (or a key
+   * column turned nullable) is a 409 naming it, and a file that changes
+   * nothing a 409 `DATASET_REVISION_UNCHANGED`. A runtime that predates the
+   * route answers 404, said here in words.
+   */
+  async reviseFromFile(datasetId: string, path: string, expectedRevision: number): Promise<DatasetSummary> {
+    const form = new FormData()
+    form.append('file', new Blob([readFileSync(path)]), basename(path))
+    form.append('expectedRevision', String(expectedRevision))
+    try {
+      return await this.call<DatasetSummary>(`/v1/data-integration/datasets/${encodeURIComponent(datasetId)}/revisions/from-file`, { form })
+    } catch (err) {
+      // An unknown route may answer 404 in words, not JSON.
+      const unknownRoute = err instanceof SyntaxError || (err instanceof CliError && (err.code === 'NOT_FOUND' || /not found|404/i.test(err.message)) && !/dataset/i.test(err.message))
+      if (unknownRoute) {
+        throw new CliError('This Frontera release cannot cut a new revision of a file dataset.', {
+          code: 'NOT_SUPPORTED',
+          hint: 'Keep the columns as the dataset has them, or declare a column `nullable: true` in its definition before its first load. On a local runtime, `frontera local reset` creates every dataset again from its definition.',
+        })
+      }
+      throw err
+    }
+  }
+
   createBlank(payload: {
     apiName: string
     displayName: string

package/src/api/governed-action-api.ts

@@ -39,6 +39,41 @@ export interface ActionRequestSummary {
 }
 
 /** A row of `GET /v1/blueprint/governed-actions/discovery`. */
+/**
+ * The refusal for invoking an Action with no deployment (409, `details.reason:
+ * ACTION_NOT_DEPLOYED`), as "Action <name> isn't deployed: <why>", or null
+ * when the body is some other refusal. `ACTION_FORBIDDEN` is a genuine
+ * authorization refusal and is left to the credential handling.
+ */
+export function notDeployedError(details: unknown, path: string): CliError | null {
+  const d = (details && typeof details === 'object' ? details : null) as { reason?: unknown; deploymentStatus?: unknown; readinessReason?: unknown; details?: unknown } | null
+  const inner = d && d.reason === undefined && d.details && typeof d.details === 'object' ? (d.details as typeof d) : d
+  if (!inner || inner.reason !== 'ACTION_NOT_DEPLOYED') return null
+  const name = decodeURIComponent(/\/actions\/([^/?]+)/.exec(path)?.[1] ?? 'it')
+  const why = typeof inner.readinessReason === 'string' ? inner.readinessReason : typeof inner.deploymentStatus === 'string' ? `its deployment is ${inner.deploymentStatus}` : 'it has no active deployment'
+  return new CliError(`Action ${name} isn't deployed: ${why}`, {
+    code: 'ACTION_NOT_DEPLOYED',
+    hint: name === 'it' ? 'frontera action list shows each Action’s deployment and why it cannot run' : `\`frontera action deploy ${name}\` builds its write path; \`frontera action list\` shows why each Action cannot run (in a local project, \`frontera local dev\` deploys it)`,
+    details: { reason: 'ACTION_NOT_DEPLOYED', action: name === 'it' ? null : name, deploymentStatus: inner.deploymentStatus ?? null, readinessReason: inner.readinessReason ?? null },
+  })
+}
+
+/** One published Action and whether it can run, as `?view=deployable` answers. */
+export interface DeployableActionEntry {
+  definition: { apiName: string; displayName?: string; id?: string }
+  contractDigest?: string
+  availability?: string
+  executable?: boolean
+  deploymentStatus?: string
+  reason?: string
+  /**
+   * What the deployed Action runs with that its owner should fix, without
+   * stopping it: a value it offers that the semantic type it writes refuses
+   * (`ACTION_SEMANTIC_TYPE_CONFLICT`). A request with that value is refused when submitted.
+   */
+  warnings?: Array<{ code: string; path?: string; message: string }>
+}
+
 export interface ActionDiscovery {
   actionDefinitionId: string
   apiName: string
@@ -111,11 +146,18 @@ export class GovernedActionApi {
 
     if (!response.ok) {
       const body = payload as { message?: string; code?: string; details?: unknown } | null
+      // An Action that is published but has no deployment: said as that, not as a conflict.
+      const undeployed = notDeployedError(body?.details, path)
+      if (undeployed) throw undeployed
       const credential = credentialFailure(response.status, body?.message, { token: this.token, code: body?.code, details: body?.details })
       if (credential) throw credential
-      throw new CliError(body?.message ?? `${response.status} from ${path}`, {
+      // A refusal whose reason is only in its issues ("Mutation Plan is invalid.") says the reason in the message.
+      const issues = issueLines(body?.details)
+      const said = body?.message ?? `${response.status} from ${path}`
+      throw new CliError(issues.length ? `${said} ${issues.join('; ')}` : said, {
         code: body?.code ?? 'FAILURE',
-        ...(body?.details ? { hint: JSON.stringify(body.details) } : {}),
+        ...(body?.details ? { hint: issues.length ? issues.join('\n') : JSON.stringify(body.details) } : {}),
+        ...(body?.details ? { details: body.details } : {}),
         // The status is what separates "refused" from "unknown": `action
         // submit` offers a retry only for the second.
         cause: { status: response.status, details: body?.details },
@@ -275,6 +317,27 @@ export class GovernedActionApi {
     return this.call('/v1/blueprint/actions')
   }
 
+  /**
+   * Every published Action with its readiness, the inert ones included —
+   * `?view=deployable`. The plain list keeps only Actions that can be
+   * invoked, so one published and switched off was missing from it. Null
+   * when the service predates the view (it refuses the query).
+   */
+  async listDeployableActions(): Promise<DeployableActionEntry[] | null> {
+    try {
+      return await this.call<DeployableActionEntry[]>('/v1/blueprint/actions?view=deployable')
+    } catch (err) {
+      const status = ((err as { cause?: { status?: number } }).cause)?.status
+      if (status === 400 || status === 422) return null
+      throw err
+    }
+  }
+
+  /** The Actions authored on the draft, published or not — `?view=draft`. */
+  listDraftActions(): Promise<Array<Record<string, unknown>>> {
+    return this.call('/v1/blueprint/actions?view=draft')
+  }
+
   /**
    * The ACTIVE view, never the draft: a deployment is checked against the
    * release the write path will actually read, and a draft-only property would
@@ -433,3 +496,28 @@ export class GovernedActionApi {
     return this.call(`/v1/blueprint/governed-actions/admin/bindings${query}`)
   }
 }
+
+/**
+ * A validation refusal's issues (`details.issues: [{ kind?, path, message }]`,
+ * `kind` being `invocation_input` or `invocation` for a submission), one line
+ * each as `path: message`, and a stale version's `details.currentVersion` as
+ * the version to submit instead; empty when the details carry neither.
+ */
+export function issueLines(details: unknown): string[] {
+  const d = (details && typeof details === 'object' ? details : {}) as { issues?: unknown; currentVersion?: unknown }
+  const lines: string[] = []
+  if (Array.isArray(d.issues)) {
+    for (const i of d.issues) {
+      if (!i || typeof i !== 'object') continue
+      const { path, message } = i as { path?: unknown; message?: unknown }
+      if (typeof message !== 'string' || !message) continue
+      const steps = Array.isArray(path) ? path.map(String) : typeof path === 'string' && path ? [path] : []
+      const where = steps.join('.')
+      lines.push(where ? `${where}: ${message}` : message)
+    }
+  }
+  if (typeof d.currentVersion === 'number' || typeof d.currentVersion === 'string') {
+    lines.push(`the record is now at version ${String(d.currentVersion)}: read it again and submit with expectedVersion ${String(d.currentVersion)}`)
+  }
+  return [...new Set(lines)].slice(0, 8)
+}

package/src/api/platform-api.ts

@@ -1,5 +1,6 @@
 import { FronteraClient } from '@frontera-sdk/core/client'
 
+import type { MetricQueryBody, MetricQueryResult } from '../blueprint/metric-query'
 import { organizationHeaders, selectedOrganization } from '../organization'
 
 import { CliError } from '../errors'
@@ -22,6 +23,22 @@ function statusCode(status: number): string {
   return 'FAILURE'
 }
 
+/**
+ * How a knowledge search cut its results. The cutoff is a maximum cosine
+ * distance (0 to 2, lower is stricter) while `score` is higher-is-better:
+ * with similarity scoring a score is `1 - distance / 2`, so the cutoff lets
+ * through scores above `minScore`.
+ */
+export interface KnowledgeRetrieval {
+  maxDistance?: number
+  /** `base`: the base's own match threshold; `request`: `--threshold`. */
+  thresholdFrom?: 'base' | 'request'
+  scoring?: 'similarity' | 'fusion' | 'rerank'
+  minScore?: number | null
+  /** The nearest chunk's distance when none was kept; null when the base has nothing searchable. */
+  nearestDistance?: number | null
+}
+
 export interface AgentDraft {
   agentId?: string
   revision: number
@@ -120,12 +137,49 @@ export class PlatformApi {
     return this.getList<unknown>('/v1/blueprint/metrics')
   }
 
+  /** One published metric, with its definition (measures, dimensions, timeseries). */
+  blueprintMetric(apiName: string) {
+    return this.get<unknown>(`/v1/blueprint/metrics/${encodeURIComponent(apiName)}`)
+  }
+
+  /** A metric's numbers, as an App's `useMetric` and an Agent's `blueprint_query_metric` read them (`blueprint/metric-query.ts`). */
+  blueprintMetricQuery(apiName: string, body: MetricQueryBody) {
+    return this.client.request<MetricQueryResult>(`/v1/blueprint/metrics/${encodeURIComponent(apiName)}/query`, { method: 'POST', body })
+  }
+
+  /**
+   * An aggregation over an object set (`POST /v1/blueprint/aggregate`). The
+   * metric command reads the newest value of a metric's timeseries with it: the
+   * point a `--range` window is counted back from.
+   */
+  blueprintAggregate(body: unknown) {
+    return this.client.request<{ rows?: Array<Record<string, unknown>> }>('/v1/blueprint/aggregate', { method: 'POST', body })
+  }
+
   /** How object types relate. Without these the catalog reads as a pile of
    *  disconnected tables, and nothing can be joined. */
   blueprintLinkTypes() {
     return this.getList<unknown>('/v1/blueprint/link-types')
   }
 
+  /**
+   * The saved object sets this credential can read, as the route answered.
+   *
+   * A workspace key reads its workspace's slice (`/v1/sync/object-sets`, rows
+   * name their object type); an organization key is refused there without a
+   * workspace and reads the organization's (`/v1/blueprint/object-sets`).
+   * Rows are normalized by `normalizeObjectSets`.
+   */
+  async blueprintObjectSets(): Promise<unknown> {
+    try {
+      return await this.get<unknown>('/v1/sync/object-sets')
+    } catch (err) {
+      const status = (err as { status?: number }).status
+      if (status !== 400 && status !== 401 && status !== 403 && status !== 404) throw err
+      return this.get<unknown>('/v1/blueprint/object-sets')
+    }
+  }
+
   /**
    * Run an object-set query and return rows.
    *
@@ -148,6 +202,8 @@ export class PlatformApi {
     pageToken?: string
     /** Distance ordering from a location; checked by the service. */
     nearest?: unknown
+    /** Each row of an editable type carries `_meta.recordVersion`, what an Action's `expectedSubjectVersion` names. */
+    recordVersions?: boolean
   }) {
     return this.client.request<{
       rows?: Array<Record<string, unknown>>
@@ -175,6 +231,11 @@ export class PlatformApi {
     return this.getList<unknown>('/v1/config/agents')
   }
 
+  /** Every Agent in the workspace, drafts never published included (the sync listing; `agents()` lists published ones). */
+  allAgents() {
+    return this.getList<unknown>('/v1/sync/agents')
+  }
+
   agent(id: string) {
     return this.get<unknown>(`/v1/config/agents/${encodeURIComponent(id)}`)
   }
@@ -304,6 +365,21 @@ export class PlatformApi {
     })
   }
 
+  /** Archive an Agent: out of service, its conversations kept; `restoreAgent` puts it back. The platform's delete is this archive. */
+  archiveAgent(id: string) {
+    return this.client.request<unknown>(`/v1/config/agents/${encodeURIComponent(id)}`, {
+      method: 'DELETE',
+    })
+  }
+
+  /** Put an archived Agent back into service, as it was. */
+  restoreAgent(id: string) {
+    return this.client.request<unknown>(`/v1/config/agents/${encodeURIComponent(id)}/restore`, {
+      method: 'POST',
+      body: {},
+    })
+  }
+
   agentVersions(id: string) {
     return this.getList<unknown>(`/v1/config/agents/${encodeURIComponent(id)}/versions`)
   }
@@ -657,7 +733,7 @@ export class PlatformApi {
   async knowledgeSearch(
     baseId: string,
     body: { query: string; topK?: number; threshold?: number },
-  ): Promise<{ results: Array<Record<string, unknown>> }> {
+  ): Promise<{ results: Array<Record<string, unknown>>; retrieval?: KnowledgeRetrieval }> {
     const res = await this.client.request<unknown>(
       `/v1/workspace-knowledge/${encodeURIComponent(baseId)}/search`,
       { method: 'POST', body },
@@ -669,7 +745,16 @@ export class PlatformApi {
     // search; it went unnoticed because the first base tried was empty, which
     // produces the identical output.
     const rows = (payload.results ?? payload.chunks) as Array<Record<string, unknown>> | undefined
-    return { results: Array.isArray(rows) ? rows : [] }
+    // How the cutoff applied and how to read `score` against it; absent from a service that predates it.
+    const retrieval = payload.retrieval && typeof payload.retrieval === 'object' ? (payload.retrieval as KnowledgeRetrieval) : undefined
+    return { results: Array.isArray(rows) ? rows : [], ...(retrieval ? { retrieval } : {}) }
+  }
+
+  /** The organization's embedding model (`/v1/config/embedding`); both null when it has chosen none. */
+  async embeddingSetting(): Promise<{ provider: string | null; model: string | null }> {
+    const body = PlatformApi.inner<{ provider?: unknown; model?: unknown } | null>(await this.get<unknown>('/v1/config/embedding'))
+    const text = (v: unknown) => (typeof v === 'string' && v ? v : null)
+    return { provider: text(body?.provider), model: text(body?.model) }
   }
 
   /**