@frontera-sdk/cli 1.44.0 → 1.45.0

package/README.md

@@ -7,7 +7,8 @@ bunx @frontera-sdk/cli --help
 ```
 
 ```bash
-frontera login
+frontera auth add acme-prod --api-url https://api.frontera.example --from -
+frontera auth use acme-prod
 frontera app init shipments-console
 cd shipments-console && bun install
 frontera app dev
@@ -19,6 +20,69 @@ key never enters browser JavaScript or `.env.local`; the browser receives only
 a short-lived, App-scoped token. Existing Vite Apps remain supported with
 `--framework react` and their legacy `dev-host.html` flow.
 
+## One machine, many customers
+
+A credential is a **profile**, and the working directory selects which profile
+is in play. Two keys for the same deployment coexist under different names, and
+a command run in a customer's directory uses that customer's key with no flag.
+
+```bash
+frontera auth add acme-prod --api-url https://api.frontera.example --from -
+frontera auth add globex-dev   --api-url https://api.frontera.example --from -
+
+cd ~/Customers/acme && frontera auth use acme-prod
+cd ~/Customers/globex  && frontera auth use globex-dev
+
+frontera auth current --json    # which profile, which origin, which scope
+```
+
+`auth use` writes a gitignored `.frontera/context.json` holding a profile
+**name** — never a token and never an origin. Resolution walks up from the
+working directory and the nearest binding wins, so a nested customer project
+safely overrides its parent.
+
+Precedence is explicit over inferred: `--profile` beats `FRONTERA_PROFILE`,
+which beats the directory. `--api-url` must agree with the selected profile's
+origin — a profile's key is never sent to another deployment. `FRONTERA_TOKEN`
+still works for CI and the Computer, and requires an explicit origin alongside
+it for the same reason.
+
+Keys live in the OS credential store addressed by profile; `config.json` holds
+metadata and a short fingerprint, never key bytes. A version-1 configuration
+migrates on first use, verifying every copied secret before the old plaintext
+is dropped. `frontera login` remains as a deprecated alias that manages the
+`default` profile.
+
+| | |
+|---|---|
+| `frontera auth add <profile>` | verify a key and store it (stdin or no-echo prompt only) |
+| `frontera auth use <profile>` | bind this directory tree — no initialization needed |
+| `frontera auth current` | the resolved profile, origin, scope and provenance |
+| `frontera auth list` / `verify` / `remove` | what exists, is it still valid, delete it |
+
+## Agent harness
+
+```bash
+frontera setup            # every coding host installed here
+frontera setup codex
+frontera setup claude
+```
+
+Codex and Claude Code both install plugins from a marketplace, and both accept a
+local directory as one. The CLI carries the Frontera skills pinned at build
+time, so `setup` materializes a marketplace under
+`~/.local/share/frontera/harness` and points the host at it — nothing published,
+nothing hosted, no network. Upgrading the CLI upgrades the plugin.
+
+Nothing needs to be written into a repository. For teams that want the
+instructions versioned with the code — or for Windows checkouts, archives and
+cloud sandboxes — `frontera kit vendor` writes both host projections
+(`.agents/skills` and `.claude/skills`), a bounded managed block in `AGENTS.md`,
+a `CLAUDE.md` importing `@AGENTS.md`, and a committable
+`frontera.kit.lock.json`. `kit status`, `kit sync` and `kit doctor` report
+drift, update generated files without discarding local edits, and diagnose a
+skill reachable from two sources at once.
+
 ## The commands
 
 `frontera <noun> <verb>`. Note that `frontera init` (prepare an existing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.44.0",
+  "version": "1.45.0",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -34,11 +34,12 @@
     "test": "bun test",
     "typecheck": "bunx tsc --noEmit",
     "sync:sdk": "bun run scripts/sync-sdk.ts",
+    "sync:kit": "bun run scripts/sync-kit.ts",
     "build:release": "bun run scripts/build-release.ts"
   },
   "dependencies": {
-    "@frontera-sdk/automation": "1.43.10",
-    "@frontera-sdk/core": "1.43.10",
+    "@frontera-sdk/automation": "1.45.0",
+    "@frontera-sdk/core": "1.45.0",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },

package/src/api/automation-api.ts

@@ -232,6 +232,21 @@ export class AutomationApi {
     )
   }
 
+  /**
+   * One run, by id.
+   *
+   * `runs` lists, and a listing is where a failure is NOTICED — the message it
+   * carries is what the handler threw, and everything about how the run got
+   * there is in the steps. Fetching the run itself is what makes those two
+   * readable together after the fact, rather than only in the tail of a list
+   * that has since scrolled.
+   */
+  runById(slug: string, runId: string): Promise<AutomationRunSummary> {
+    return this.client.request<AutomationRunSummary>(
+      `/v1/automations/${encodeURIComponent(slug)}/runs/${encodeURIComponent(runId)}`,
+    )
+  }
+
   /** One run's trail. Workspace-scoped server-side, so a guessed id reads
    *  nothing. */
   runSteps(runId: string): Promise<AutomationRunStep[]> {

package/src/api/dataset-api.ts

@@ -127,10 +127,109 @@ export class DatasetApi {
     )
   }
 
+  /**
+   * Rows of a published revision — the read half of every create form above.
+   *
+   * `dataset get` shows the column CONTRACT, which is what a Blueprint binding
+   * pins, and says nothing about whether a single row is behind it. A `source`
+   * dataset whose relation went empty and a `blank` one that never carried
+   * rows present identically there, and both bind without complaint, so the
+   * contract alone cannot answer "is there data".
+   *
+   * Capped at 100 rows a page by the service, cursor-paged. A revision is
+   * immutable, so a cursor stays valid.
+   */
+  revisionRows(
+    revisionId: string,
+    body: { limit?: number; cursor?: string } = {},
+  ): Promise<{
+    columns?: Array<{ name?: string; databaseType?: string }>
+    rows?: unknown[][]
+    nextCursor?: string | null
+    readAt?: string
+    consistency?: string
+  }> {
+    return this.call(
+      `/v1/data-integration/dataset-revisions/${encodeURIComponent(revisionId)}/rows`,
+      { method: 'POST', body },
+    )
+  }
+
   listSources(): Promise<SourceSummary[]> {
     return this.page<SourceSummary>('/v1/data-integration/sources')
   }
 
+  getSource(sourceId: string): Promise<SourceSummary & Record<string, unknown>> {
+    return this.call(`/v1/data-integration/sources/${encodeURIComponent(sourceId)}`)
+  }
+
+  /**
+   * Provision a Source, and the Datasets it carries, in one call.
+   *
+   * The step that broke every scripted org stand-up: `dataset create --from-source`
+   * NAMED a Source, and nothing could make one. Postgres only today — the
+   * service takes `connectorType: 'postgres'` as a literal, so a second
+   * connector is a service change, not a CLI flag.
+   *
+   * `config.password` never comes from the definition file. The command reads
+   * it from stdin and merges it here, for the reason `secret set` states: a
+   * credential in a committed file is a credential in the repository.
+   */
+  provisionSource(body: {
+    displayName: string
+    description?: string | null
+    connectorType: 'postgres'
+    config: Record<string, unknown>
+    datasets: unknown[]
+  }): Promise<Record<string, unknown>> {
+    return this.call('/v1/data-integration/sources/provision', { method: 'POST', body })
+  }
+
+  /**
+   * Replace a Source's connection and add Datasets to it.
+   *
+   * Both concurrency tokens are required by the service and neither is
+   * optional here: `expectedUpdatedAt` and `expectedRevision` come from
+   * `source get`, and a stale pair is refused rather than merged. Datasets are
+   * ADDITIONS — omitting the field leaves every existing one in place, and
+   * there is no removal channel on this route.
+   */
+  updateSource(
+    sourceId: string,
+    body: {
+      expectedUpdatedAt: string
+      expectedRevision: number
+      displayName: string
+      description?: string | null
+      config: Record<string, unknown>
+      datasets?: unknown[]
+    },
+  ): Promise<Record<string, unknown>> {
+    return this.call(`/v1/data-integration/sources/${encodeURIComponent(sourceId)}`, {
+      method: 'PATCH',
+      body,
+    })
+  }
+
+  /** A new connection revision, leaving the Datasets alone. */
+  reviseSource(
+    sourceId: string,
+    body: { expectedRevision: number; config: Record<string, unknown> },
+  ): Promise<Record<string, unknown>> {
+    return this.call(`/v1/data-integration/sources/${encodeURIComponent(sourceId)}/revisions`, {
+      method: 'POST',
+      body,
+    })
+  }
+
+  /** Stops reads without deleting. Datasets bound to it stop refreshing. */
+  disableSource(sourceId: string, body: { expectedUpdatedAt: string }): Promise<unknown> {
+    return this.call(`/v1/data-integration/sources/${encodeURIComponent(sourceId)}/disable`, {
+      method: 'POST',
+      body,
+    })
+  }
+
   /** Columns and a sample, read from the CSV before anything is created. */
   async uploadPreview(path: string): Promise<UploadPreview> {
     const form = new FormData()

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

@@ -13,6 +13,29 @@ import type { ObjectTypeShape, PublishedActionDefinition } from '../blueprint/on
 
 interface Envelope<T> { error?: boolean; data?: T }
 
+/**
+ * A row of `GET /v1/blueprint/governed-actions/requests`.
+ *
+ * Transcribed from a real response, not guessed. The list projection carries
+ * no action apiName and no failure text — an earlier version of this interface
+ * declared both and rendered two permanently empty columns. `effectCertainty`
+ * is the field that actually matters on a failure: it says whether the effect
+ * reached the far side, which is the difference between "retry" and "do not".
+ */
+export interface ActionRequestSummary {
+  id?: string
+  lifecycle?: string
+  /** The definition's uuid. The list does not resolve it to an apiName. */
+  actionDefinitionId?: string
+  actionContractDigest?: string
+  effectCertainty?: string
+  hasEverDispatched?: boolean
+  subjectRef?: unknown
+  createdAt?: string
+  updatedAt?: string
+  deadlineAt?: string | null
+}
+
 export class GovernedActionApi {
   constructor(private readonly apiUrl: string, private readonly token: string) {}
 
@@ -42,6 +65,63 @@ export class GovernedActionApi {
       : payload) as T
   }
 
+  /**
+   * Requests raised against the Actions in this organization.
+   *
+   * The read half of a plane the CLI could only arm. `action list` says an
+   * Action is deployed and `action review` says the write path is active;
+   * neither says whether anything has ever run through it, or what happened
+   * when it did.
+   *
+   * Reads only. Invoking stays absent for the reason this module's header
+   * gives — both CLI credential kinds present a non-member principal, and the
+   * invoke check joins organization membership. The LIST gate is different:
+   * `actionRequest: ['read']`, which a key can hold.
+   *
+   * `nextCursor` rides on the envelope beside `data`, so this cannot go
+   * through `call` — that unwraps to `data` and would drop the cursor,
+   * silently capping every caller at one page.
+   */
+  async listRequests(query: { lifecycle?: string; limit?: number; cursor?: string } = {}): Promise<{
+    requests: ActionRequestSummary[]
+    nextCursor?: string
+  }> {
+    const params = new URLSearchParams()
+    if (query.lifecycle) params.set('lifecycle', query.lifecycle)
+    if (query.limit !== undefined) params.set('limit', String(query.limit))
+    if (query.cursor) params.set('cursor', query.cursor)
+    const suffix = params.size > 0 ? `?${params}` : ''
+
+    const response = await fetch(
+      `${this.apiUrl}/v1/blueprint/governed-actions/requests${suffix}`,
+      { headers: { authorization: `Bearer ${this.token}` } },
+    )
+    const text = await response.text()
+    let payload: unknown
+    try { payload = text ? JSON.parse(text) : null } catch { payload = null }
+
+    if (!response.ok) {
+      const body = payload as { message?: string; code?: string } | null
+      throw new CliError(body?.message ?? `${response.status} from /governed-actions/requests`, {
+        code: body?.code ?? 'FAILURE',
+        ...(response.status === 403
+          ? { hint: 'the credential needs actionRequest:read — mint a key that carries it' }
+          : {}),
+      })
+    }
+
+    const envelope = payload as { data?: ActionRequestSummary[]; nextCursor?: string } | null
+    return {
+      requests: envelope?.data ?? [],
+      ...(envelope?.nextCursor ? { nextCursor: envelope.nextCursor } : {}),
+    }
+  }
+
+  /** One request, with everything the surface records about how it resolved. */
+  getRequest(requestId: string): Promise<Record<string, unknown>> {
+    return this.call(`/v1/blueprint/governed-actions/requests/${encodeURIComponent(requestId)}`)
+  }
+
   /** The published Action: its definition and the digest a Binding pins. */
   publishedAction(apiName: string): Promise<{
     definition: PublishedActionDefinition

package/src/api/platform-api.ts

@@ -97,6 +97,47 @@ export class PlatformApi {
     return this.getList<unknown>('/v1/blueprint/link-types')
   }
 
+  /**
+   * Run an object-set query and return rows.
+   *
+   * The counterpart to nineteen authoring verbs that had none: a caller could
+   * create an object type, bind it to a dataset and publish a release without
+   * ever seeing a row come back, so a binding that resolved to nothing looked
+   * exactly like one that worked.
+   *
+   * `objectSet` is the expression tree, not a table name — `{ type: 'base',
+   * objectType }` is the whole of the simple case and the command builds it.
+   * Paging is cursor-based: hand `nextPageToken` back as `pageToken`. There is
+   * no offset form; the service refuses `page` rather than silently serving
+   * page 1 forever.
+   */
+  blueprintQuery(body: {
+    objectSet: unknown
+    select?: string[]
+    orderBy?: Array<{ property: string; dir: 'asc' | 'desc' }>
+    pageSize?: number
+    pageToken?: string
+  }) {
+    return this.client.request<{
+      rows?: Array<Record<string, unknown>>
+      nextPageToken?: string | null
+    }>('/v1/blueprint/query', { method: 'POST', body })
+  }
+
+  /**
+   * One object by primary key.
+   *
+   * Separate from `blueprintQuery` because it is the check a caller actually
+   * runs after a bind — "is this specific record reachable" — and expressing
+   * it as a filtered query means constructing a where-node to ask a question
+   * with a one-line answer.
+   */
+  blueprintInstance(apiName: string, pk: string) {
+    return this.get<unknown>(
+      `/v1/blueprint/object-types/${encodeURIComponent(apiName)}/instances/${encodeURIComponent(pk)}`,
+    )
+  }
+
   // ── Agents ────────────────────────────────────────────────────────────────
 
   agents() {
@@ -267,6 +308,217 @@ export class PlatformApi {
     return this.getList<unknown>('/v1/apps/catalog')
   }
 
+  /**
+   * Strip the SECOND envelope.
+   *
+   * The apps router answers `ok({ data: … })`, so after the SDK unwraps the
+   * outer `{ data, message, error }` a second `{ data }` is left. Reading a
+   * field off that layer silently yields undefined — which is how `plugin add`
+   * printed the success text for an OAuth install whose `authUrl` it had, and
+   * `plugin verify` rendered a one-row table containing a JSON blob.
+   */
+  private static inner<T>(body: unknown): T {
+    const wrapper = body as { data?: T } | null
+    return (wrapper && typeof wrapper === 'object' && 'data' in wrapper
+      ? (wrapper.data as T)
+      : (body as T))
+  }
+
+  async plugin(installId: string): Promise<Record<string, unknown>> {
+    const body = await this.get<unknown>(`/v1/apps/${encodeURIComponent(installId)}`)
+    return PlatformApi.inner<Record<string, unknown>>(body) ?? {}
+  }
+
+  /**
+   * Install a plugin.
+   *
+   * `kind` is the catalog entry, not a display name — `frontera plugin catalog`
+   * is where it comes from. An OAuth-backed install answers with an `authUrl`
+   * and lands unusable until a person opens it, which is why `plugin connect`
+   * stays reserved: the CLI can start that handshake and cannot finish it.
+   */
+  async createPluginInstall(body: {
+    kind: string
+    installName?: string
+    description?: string | null
+    config?: Record<string, unknown>
+  }): Promise<{ install?: Record<string, unknown>; authUrl?: string } & Record<string, unknown>> {
+    // `config` is REQUIRED by the route, not optional. Omitting it when the
+    // caller passed no --file answered a bare "Validation failed", so a plugin
+    // whose kind needs no configuration — every OAuth one, since the consent
+    // flow supplies it — could not be installed from the CLI at all.
+    const raw = await this.client.request<unknown>('/v1/apps/', {
+      method: 'POST',
+      body: { config: {}, ...body },
+    })
+    // Two shapes behind one envelope: `created({ data: { install, authUrl } })`
+    // when consent is pending, `created({ data: install })` when it is not. The
+    // caller reads `authUrl` to decide what to print, so both must land on the
+    // same level.
+    return PlatformApi.inner(raw) ?? {}
+  }
+
+  /** Rename, or replace stored configuration. */
+  updatePluginInstall(installId: string, body: { installName?: string; config?: Record<string, unknown> }) {
+    return this.client.request<unknown>(`/v1/apps/${encodeURIComponent(installId)}`, {
+      method: 'PUT',
+      body,
+    })
+  }
+
+  /**
+   * Policy, not configuration: whether the install is on, whether its Actions
+   * may run at all, and what a newly discovered capability defaults to.
+   */
+  patchPluginInstall(
+    installId: string,
+    body: {
+      enabled?: boolean
+      actionPolicy?: 'allow_all' | 'read_only' | 'custom'
+      newCapabilityDefault?: 'enabled' | 'disabled'
+    },
+  ) {
+    return this.client.request<unknown>(`/v1/apps/${encodeURIComponent(installId)}`, {
+      method: 'PATCH',
+      body,
+    })
+  }
+
+  deletePluginInstall(installId: string) {
+    return this.client.request<unknown>(`/v1/apps/${encodeURIComponent(installId)}`, {
+      method: 'DELETE',
+    })
+  }
+
+  /**
+   * Reachability, credentials and scopes.
+   *
+   * A failed check still answers 200 — the handler returns `ok(...)`
+   * unconditionally and the verdict is in the body, the same shape
+   * `dataset test-source` established.
+   */
+  async verifyPluginInstall(installId: string): Promise<Record<string, unknown>> {
+    const raw = await this.client.request<unknown>(
+      `/v1/apps/${encodeURIComponent(installId)}/verify`,
+      { method: 'POST' },
+    )
+    return PlatformApi.inner<Record<string, unknown>>(raw) ?? {}
+  }
+
+  /** Everything one install exposes, whether or not an agent holds it. */
+  pluginCapabilities(installId: string) {
+    return this.getList<unknown>(`/v1/apps/${encodeURIComponent(installId)}/capabilities`)
+  }
+
+  // ── Agent capabilities ────────────────────────────────────────────────────
+
+  /**
+   * What this agent may actually do.
+   *
+   * Reads the DRAFT when one exists and the live snapshot otherwise, which is
+   * the same rule the grant below writes under — so a list taken straight after
+   * a grant shows it, and `agent diff` is where the staged-vs-live difference
+   * is visible.
+   */
+  agentCapabilities(agentId: string) {
+    return this.getList<unknown>(`/v1/apps/agents/${encodeURIComponent(agentId)}/capabilities`)
+  }
+
+  /**
+   * Grant one capability to an agent.
+   *
+   * Two things this does that its name does not say. It STAGES onto the agent
+   * draft rather than writing live — nothing changes for the running agent
+   * until `frontera agent publish`. And it auto-binds the parent install if the
+   * agent did not already hold it, so a grant is never half-applied.
+   *
+   * Refused with a conflict when the capability is an Action and the install
+   * is set to `read_only`; that is a policy on the install, fixed with
+   * `frontera plugin policy`, not by retrying.
+   */
+  grantAgentCapability(agentId: string, capabilityId: string) {
+    return this.client.request<unknown>(
+      `/v1/apps/agents/${encodeURIComponent(agentId)}/capabilities/${encodeURIComponent(capabilityId)}`,
+      { method: 'POST' },
+    )
+  }
+
+  revokeAgentCapability(agentId: string, capabilityId: string) {
+    return this.client.request<unknown>(
+      `/v1/apps/agents/${encodeURIComponent(agentId)}/capabilities/${encodeURIComponent(capabilityId)}`,
+      { method: 'DELETE' },
+    )
+  }
+
+  /** Which installs the agent is bound to, with the account mode each uses. */
+  agentInstalls(agentId: string) {
+    return this.getList<unknown>(`/v1/apps/agents/${encodeURIComponent(agentId)}/installs`)
+  }
+
+  /**
+   * `agent_owned` uses one credential the workspace holds; `end_user` makes
+   * every caller connect their own. The choice is not reversible by retrying
+   * with the other value — it decides whose data the agent reaches.
+   */
+  bindAgentInstall(agentId: string, installId: string, accountMode: 'agent_owned' | 'end_user') {
+    return this.client.request<unknown>(
+      `/v1/apps/agents/${encodeURIComponent(agentId)}/installs/${encodeURIComponent(installId)}`,
+      { method: 'POST', body: { accountMode } },
+    )
+  }
+
+  unbindAgentInstall(agentId: string, installId: string) {
+    return this.client.request<unknown>(
+      `/v1/apps/agents/${encodeURIComponent(agentId)}/installs/${encodeURIComponent(installId)}`,
+      { method: 'DELETE' },
+    )
+  }
+
+  // ── Agent skills and versions ─────────────────────────────────────────────
+
+  /**
+   * Bind a workspace skill to an agent.
+   *
+   * The step that had no verb: `skill push` uploads a skill and nothing loaded
+   * it, so the only route from a bundle folder to a running agent went through
+   * `pack apply` or the Console.
+   */
+  attachAgentSkill(agentId: string, skillId: string) {
+    return this.client.request<unknown>(
+      `/v1/config/agents/${encodeURIComponent(agentId)}/workspace-skills/${encodeURIComponent(skillId)}`,
+      { method: 'POST' },
+    )
+  }
+
+  detachAgentSkill(agentId: string, skillId: string) {
+    return this.client.request<unknown>(
+      `/v1/config/agents/${encodeURIComponent(agentId)}/workspace-skills/${encodeURIComponent(skillId)}`,
+      { method: 'DELETE' },
+    )
+  }
+
+  /**
+   * Publish an earlier version's snapshot as a new one.
+   *
+   * Forward-only: it does not rewind history, it appends. `agent versions`
+   * listed what could be gone back to and nothing could go there, so the only
+   * recovery from a bad publish was to reconstruct the document by hand.
+   */
+  revertAgent(agentId: string, versionId: string, body: { acceptOrphanedKnowledge?: boolean } = {}) {
+    return this.client.request<unknown>(
+      `/v1/config/agents/${encodeURIComponent(agentId)}/versions/${encodeURIComponent(versionId)}/revert`,
+      { method: 'POST', body },
+    )
+  }
+
+  /** Re-run ingestion for a source that failed. Additive and safe to repeat. */
+  retryKnowledgeSource(baseId: string, sourceId: string) {
+    return this.client.request<unknown>(
+      `/v1/workspace-knowledge/${encodeURIComponent(baseId)}/sources/${encodeURIComponent(sourceId)}/retry`,
+      { method: 'POST', body: {} },
+    )
+  }
+
   // ── Knowledge ─────────────────────────────────────────────────────────────
 
   knowledgeBases(workspaceId: string) {
@@ -284,6 +536,47 @@ export class PlatformApi {
     return this.getList<unknown>(`/v1/workspace-knowledge/${encodeURIComponent(id)}/sources`)
   }
 
+  /**
+   * One knowledge base by id.
+   *
+   * `knowledge list` existed and `knowledge get` did not, so the only way to
+   * read back what `knowledge create` had just made was to list every base in
+   * the workspace and filter client-side.
+   */
+  async knowledgeBase(id: string): Promise<Record<string, unknown>> {
+    const body = await this.get<{ data?: Record<string, unknown> } | Record<string, unknown>>(
+      `/v1/workspace-knowledge/${encodeURIComponent(id)}`,
+    )
+    return ((body as { data?: Record<string, unknown> })?.data ?? body ?? {}) as Record<string, unknown>
+  }
+
+  /**
+   * Retrieval against a base — the read half of `knowledge upload`.
+   *
+   * Ingestion is asynchronous and a partial batch still exits 0, so "the
+   * upload succeeded" and "the corpus is searchable" are different claims and
+   * only this one can settle the second. Empty results minutes after an upload
+   * usually mean sources are still `processing`, not that retrieval is broken;
+   * the command says so rather than printing nothing.
+   */
+  async knowledgeSearch(
+    baseId: string,
+    body: { query: string; topK?: number; threshold?: number },
+  ): Promise<{ results: Array<Record<string, unknown>> }> {
+    const res = await this.client.request<unknown>(
+      `/v1/workspace-knowledge/${encodeURIComponent(baseId)}/search`,
+      { method: 'POST', body },
+    )
+    const payload = PlatformApi.inner<Record<string, unknown>>(res) ?? {}
+    // The route answers `{ results }` — named for the retrieval orchestrator it
+    // wraps, not for the chunk table underneath. An earlier version read
+    // `chunks` and therefore reported "no chunks matched" for every successful
+    // 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 : [] }
+  }
+
   /**
    * Create a workspace knowledge base.
    *