Outside Agent

Delete one capability eval (and its run history) — pass `evalId`. Returns `{ ok: true }`.

deleteCapabilityEval

Permanently remove ONE knowledge-base source — and its indexed chunks — from an agent's knowledge base. Pass `{ agentId, sourceId }`, where `sourceId` is an `id` from getKnowledgeBase's `sources` (or a `sourceId` seedKnowledgeText returned). Use this to CORRECT the base when a fact is disproved or superseded — delete the stale source outright instead of seeding a 'disregard the above' document, which would leave contradictory passages competing in retrieval forever. (seedKnowledgeText already UPSERTS by exact title and gates near-duplicates; reach for delete when there's no clean replacement to re-seed, e.g. dropping a whole obsolete source.) Deleting a FILE source removes the WHOLE file's chunks, not one fact within it. Irreversible — re-seed to restore. No-op-safe: an unknown or already-deleted `sourceId` (or one on an agent you don't own) returns a not-found error. Returns `{ ok: true }`.

deleteKnowledgeSource

Remove a connector from the agent (by `connectorId`). The agent can no longer use that toolkit; existing end-user connections are left untouched.

disableConnector

Dismiss one OPEN flag without converting it — for a one-off the creator confirms needs no guard (a user typo, a transient outage, behavior that is actually correct). Pass `flagId`; returns the resolved flag. Prefer convertFlagToEval when in doubt: a dismissed flag protects nothing, a converted one guards the behavior forever.

dismissFlag

Compile the draft and run it against generated scenarios WITHOUT publishing, returning a COMPACT summary instead of the full traces: `{ scenarioCount, repliedCount, failures, coverage }`, where each failure is `{ scenario, command, target, code, reason }`. This is the fast way to spot a payload/wiring bug — e.g. "every scenario fails on SendMessage because the message field is missing" — without paging through the full cascade. `coverage` is the INVERSE signal: `coverage.rulesNeverFired` lists reactive rules that fired in NO scenario (usually a wrong `when.event`, an unsatisfiable `condition`, or a dangling `then.target`) — treat a non-empty list as likely dead wiring, NOT a pass; `coverage.intentsWithoutScenario` lists behaviorIntents no scenario exercised (usually because the intent has no `examples`, so it was never tested — add one). Drill into simulateBuild only when you need the full trace for one scenario. Read-only.

simulateBuildSummary

Compile the draft and run it against generated scenarios WITHOUT publishing; returns the FULL event-cascade traces per scenario. This can be LARGE — prefer simulateBuildSummary for a compact pass/fail-at-a-glance read, and only call this when you need the full cascade to debug a specific scenario.

simulateBuild

Run the SAME compile + safety/purpose review that publishAgent runs, but WITHOUT publishing — returns `{ canPublish, blockers, findings, validation, delta? }`. simulateBuild only checks behavior (rules → events); this checks publish-readiness, so use it to iterate on review blockers cheaply before going live. `canPublish: true` with no blockers means publishAgent would succeed. `blockers` is the friendly human-facing list; each carries STRUCTURED targeting — `subjectId` (the exact rule/intent/capability id flagged), `subjectKind`, `fieldPath`, and a `quote` of the offending span — so you fix the right thing in one pass instead of guessing which item the review meant. `findings` is the FULL machine shape publishAgent's report carries (id, category, severity: info|warning|blocker, confidence 0..1, summary, evidence[], subjectId, fieldPath, suggestedRemediation, ...) for EVERY severity — so you can iterate blockers off reviewAgent ALONE with no publish round-trip and never under-count. Read verdict STABILITY from `confidence`: a deterministic gate emits confidence 1 (reproducible); a finding with severity "blocker" and confidence < 0.8 is a MARGINAL LLM-judge verdict that did NOT gate publish (it may shift run-to-run). `validation` is core's static validation block (errors/warnings). To track progress across iterations, pass `priorBlockers` (the `blockers` array you got from your LAST reviewAgent call); the result then includes a `delta` of `{ cleared, introduced, kept }` so you can tell whether your last edit helped. The review also dry-runs the draft and promotes a runtime failure (a rule that fails on every message) to a distinct "a rule fails when it runs" blocker, separate from "a behavior has no rule". Note the review depends on `replyMode` (a deterministic agent skips the AI judge — see setAuthoredConfig).

reviewAgent

Enable one external connector on the agent so it can act in that third-party app on behalf of the end user. `connectorId` MUST be a real toolkit id (from listConnectors / getConnector) — an id that doesn't exist in the provider's catalog is rejected, so discover it first instead of guessing. Optionally pass `enabledTools` (a subset of the connector's tool slugs) to narrow what the agent may call — recommended for large toolkits (check `toolCount`) so you don't load hundreds of tools into the model. To actually USE the connector in conversation you ALSO need to attach the `connector-tool` capability in setAuthoredConfig and reference this `connectorId` in your guidance/reactive rules (via the ListConnectorTools / CallConnectorTool commands). The end user connects their own account at runtime via OAuth; until they do, the connector is enabled but not yet usable for that user. Optionally set `bindingPolicy` to control HOW the connector authorizes (ADR 0005): `{ default: 'creator'|'none', override: 'forbidden'|'allowed'|'required' }`. `default` says whether the agent carries a creator-set account (`creator`) or none; `override` says whether an end user may bind their own. `creator`+`forbidden` = LOCKED to the creator's one account (users can't override — e.g. a Meta Page, a shared brand inbox); `creator`+`allowed` = the creator's account is the default but a user MAY connect their own (e.g. a shared Gmail); `none`+`required` = every user must connect their own (today's default); `none`+`allowed` = optional per-user. `none`+`forbidden` is invalid and is rejected. Omit `bindingPolicy` for today's per-user behavior. CUSTOM HTTP CONNECTOR (no Composio toolkit needed): to call an API Composio does NOT cover — a carrier/AMS REST API, an internal service — OR to POST to a Zapier catch-hook, pass a `manifest` instead of relying on the catalog: `{ provider: 'http', baseUrl, auth: { type: 'none'|'bearer'|'header', header? }, tools: [{ name, method, path, params?, body?, responseMap? }] }` (auth carries NO secret field — the key is set in the Console, never here). A manifest connector needs NO catalog entry and NO per-end-user OAuth — `connectorId` is YOUR OWN chosen slug (e.g. 'coastal-ams'), the existence check is SKIPPED, and it is callable as soon as enabled (still attach `connector-tool` + reference the id in guidance/reactive rules). In each tool, `path` may contain `{param}` placeholders filled from `params` (a map of name→'string'|'number'|'boolean'); `body` (write methods) is the JSON body fields; `responseMap` projects the raw JSON into clean fields for the agent as `{ outField: '$.json.path' }` (tiny JSONPath — `$.a.b`, `$.arr[0].c`). CREDENTIAL — for `bearer`/`header` auth, DO NOT put a token here: LEAVE `secretRef` UNSET. A raw API key must NEVER pass through this tool — it would enter your context and the transcript. There is a dedicated WRITE-ONLY Console field for the key, so do NOT ask the creator for a secret NAME, do NOT tell them to set a server/env var, and do NOT hunt for an MCP tool to store the secret (there is none) — the creator types the actual key themselves in the Console (agent Configuration → "Connector API keys") AFTER you author the shape. During the interview just ask the auth TYPE (bearer vs a header name); never ask where the key is stored. Author only the SHAPE (`auth: { type: 'bearer' }`, or `{ type: 'header', header: 'X-Api-Key' }`) with no `secretRef`; the connector is then in a PENDING-CREDENTIAL state, and this tool's response returns `credentialRequired` — RELAY it to the creator: they enter the real key in the Console on the agent's Configuration page, under "Connector API keys", which stores it encrypted and mints the handle. Publish is BLOCKED until the key is set. IMPORTANT — the `baseUrl` and each tool's catch-hook `path` ARE creator-specific: when a creator says "post to my Zapier" / "connect my API", ASK for the real hook URL and use it VERBATIM; NEVER invent, guess, or leave a placeholder like `/hooks/catch/<id>/<key>` — but the API KEY is the one thing you do NOT take here (it goes to the Console). A no-auth Zapier hook needs no credential: `auth: { type: 'none' }` and it's usable immediately. And do NOT route a Zapier catch-hook or a plain REST API through listConnectors/Composio — those are custom `http` connectors defined by THIS manifest, not Composio toolkits (listConnectors only covers Composio's OAuth toolkits). Zapier is just an http connector whose tool is a POST to the catch-hook: `{ provider:'http', baseUrl:'https://hooks.zapier.com', auth:{type:'none'}, tools:[{ name:'log_call_note', method:'POST', path:'/hooks/catch/<id>/<key>', body:{ summary:'string', phone:'string' } }] }`. Outbound requests are guarded (only public hosts; loopback/private/link-local are blocked outside dev), and a manifest write is still governed by an `actionBudgets` `connector_write` entry.

enableConnector

Generate the STANDARD BATTERY for behavior intents that don't have one yet: for each intent, the platform writes three scenario evals — a 'happy' path, an 'edge' case, and an 'adversarial' probe (a user actively trying to make the agent violate the requirement) — each linked to its intent, tagged, and persisted with `origin: 'generated'`. Returns `{ generated, alreadyGeneratedIntentIds, unknownIntentIds }` where `generated` is the created evals. The battery is FROZEN once COMPLETE: an intent whose generated cases already cover all three tags is SKIPPED (listed in `alreadyGeneratedIntentIds`), so every config version replays the identical suite and version-to-version score deltas mean the AGENT changed, not the tests. An INCOMPLETE battery (an earlier interrupted write) self-heals: its remnants are replaced with a fresh trio. Delete a generated case to force regeneration. Pass `intentIds` to scope generation; omit it to cover every intent without a battery. This is what gives every requirement a comparable rigor floor. NOTE: runQualitySuite runs this automatically for every uncovered intent before grading, so you rarely need to call it yourself — use it to write tests WITHOUT grading, or with `intentIds` to scope regeneration after deleting a case. This spends model credits, so it is credit-gated.

generateEvalBattery

Resolve one AuthoredConfig recipe by `name` (from listRecipes), returning `{ name, title, description, config }` — a real, schema-valid config skeleton with the wiring already correct. The `config` is a SHAPE TO ADAPT, not a finished agent: replace the placeholder purpose/persona/message text and `<…>` markers, pick real capability ids (cross-check getCatalog) and connectors (listConnectors), then pass it to setAuthoredConfig. Returns null if no such recipe exists. Read-only.

getRecipe

Look up one connector by its toolkit `connectorId` (e.g. from listConnectors, or one you already know like "gmail"). This is the RELIABLE exact-existence check (unlike listConnectors' page-limited substring search). Returns `{ connector, providerMode }`: `connector` carries its `title`, `description`, `categories`, `noAuth`, and `toolCount`, OR is `null` when no such toolkit exists. A genuinely absent slug resolves to `connector: null` — it is NOT an error; an `ok:false` error means an ACTUAL provider failure (timeout/auth/5xx), so retry it rather than concluding the toolkit is missing. `providerMode` makes the null authoritative: `connector: null` proves absence only when `providerMode` is `live-composio` (the real credentialed catalog); on `no-catalog` (keyless dev) EVERY lookup is null and proves nothing. Use it to confirm an id and decide whether to scope `enabledTools` before enableConnector. Read-only.

getConnector

Read one of the creator's agents by id (name, status, slug, visibility). Read-only.

getAgent

Get the <script> snippet and step-by-step install instructions to add this agent as a floating chat widget on a website. Requires the agent to be PUBLISHED and to have webWidget.enabled set (turn it on with setAuthoredConfig, then publish). Returns `{ enabled, slug, snippet, scriptUrl, previewUrl, appearance, instructions: { generic, byPlatform, selected? } }`: paste `snippet` just before </body> on every page. Pass an optional `platform` (shopify | wix | wordpress | webflow | squarespace | html) to get tailored steps under `instructions.selected`. If the widget is off or the agent isn't published yet, `snippet` is null and `instructions.generic` says what to do first. Read-only.

getWidgetEmbedCode

Provision (or retry) the Twilio phone number for a PUBLISHED sms/voice agent, AND the way to READ an agent's number over this surface. Decoupled from publish: publishing kicks issuance off in the background, so call this to check/retry it explicitly — e.g. after publishAgent returned `numberPending`, or after a transient failure. IDEMPOTENT: if the agent already has an active number it is returned unchanged. Returns `{ ok: true, e164, status }`, or `{ ok: false, reason }` — `no_inventory` (no number available, try again later), `provisioning_failed` (transient infra, retry), `not_configured` (server is missing Twilio settings — NOT retryable, tell the operator), `agent_not_published` (publish first), `already_has_number` (it already has an active number). On `already_has_number` the result ALSO carries `e164` + `status` for the existing number (so you can read and hand the creator the agent's number even when the background issuance already provisioned it before you called this); while it's still provisioning, `e164` is null and `status` is `provisioning` — call again shortly.

issueNumber

Discover the TRIGGER types a connector can fire (the inbound/event side — e.g. "a new Google Task was added"). Pass `connectorId` (a real toolkit id from listConnectors). Returns each trigger's `type` (use it in setAuthoredConfig's `connectorTriggers`), `name`, and `description`. A trigger lets the agent ACT ON ITS OWN when something happens in the end user's connected account — distinct from connector tools, which the agent calls on demand. To use one: declare it in `connectorTriggers` AND add a reactive rule with `when: { event: "ConnectorTriggerReceived" }` that does something (notify, call a tool, …). Read-only.

listConnectorTriggers

List the E.164 numbers allowed to reach a PRIVATE agent (oldest first, each with its optional label). The owner is implicitly allowed and is NOT in this list. Read-only.

listAllowedNumbers

List the agent's capability evals with their latest result — pass `agentId` (optionally `instanceId` to scope to one capability). Each returns `{ id, capabilityInstanceId, moduleId, evalKind, name, input, expected, lastScore, lastRunAt, ... }`; `lastScore` (0..1) and `lastRunAt` are null until the eval has been run. Read-only.

listCapabilityEvals

List the run history for one eval, newest first — pass `evalId`. Each run is `{ id, score, output, rationale, judgeModality, configRef, ranAt }`, where `configRef` identifies which config version was exercised (for spotting regressions across edits). Read-only.

listCapabilityEvalRuns

Return the BUILT-IN capability catalog (the palette of skills with their ids, config shapes, and examples) so you use real capability ids, not guesses. PREFER getCatalogSummary first — the FULL catalog serializes every module's JSON Schema plus the worked examples and is large enough to exceed an MCP client's per-result token cap. Pass `moduleIds: ["<id>", …]` to fetch the full JSON Schema for ONLY those modules (discover the ids with getCatalogSummary); omit it only when you truly need the whole palette. For EXTERNAL connectors (Google Calendar, Gmail, a CRM, …), use listConnectors instead — those are enabled separately with enableConnector. Each module also carries the FULL `pitfalls` it declares — its KNOWN failure modes (`code`, `failureMode`, `guidance`, `severity`): how the capability is commonly misused and how to avoid it, so you wire it right the first time (getCatalogSummary lists only `code` + `severity`; this is where the prose lives — the same pitfalls are re-checked at the end-of-build review).

getCatalog

Return the COMPACT capability catalog — per module, the config keys it needs, its commands (with required + accepted payload fields) and the events it emits (the fields a rule can read as `event.<field>`) — WITHOUT the full JSON Schemas. It also carries `valueExprForms`: the full vocabulary a `then.payload` leaf may take — `{const}`, `{object}`, `{template}` (interpolate `{{name}}` placeholders in a string with `vars` — each var itself a value-expr — for a personalized body/message), and every `{ref}` root (`event.`, `endUser.id` — the trusted server-known identity of the person, bind durable keys like a data-table keyField or escalation id to it, `state.`, `settings.`, and `chain.<EventType>.last.payload.<field>` to pull a value from an event emitted EARLIER in the same reactive chain) — so you don't have to infer the ref forms from examples. An order of magnitude smaller than getCatalog: prefer this when you're wiring reactiveRules and just need the field names, and only fall back to getCatalog when you need a full schema. Each module also lists any `pitfalls` it declares — its KNOWN failure modes — but here as `code` + `severity` ONLY (no prose): enough to see THAT a capability has common misuses and how serious. Pull the full `failureMode` + `guidance` for the ones that matter with getCatalog({ moduleIds }) — the same modules you fetch full schemas for when wiring (the same pitfalls are re-checked at the end-of-build review). Read-only.

getCatalogSummary

List the canonical AuthoredConfig RECIPES — known-good starting shapes for common agent patterns (conversational, no-LLM deterministic bot, scheduled reminder, escalating reminder ladder that self-cancels, classify-and-branch routing, human escalation, RSVP/guest list, owner-uploaded roster/worklist, per-user scheduled recap, multi-step generate-then-deliver, knowledge-base grounded, connector-trigger reaction). Pass `query` with the task IN YOUR OWN WORDS (e.g. `listRecipes({ query: "chase an overdue invoice until paid" })` or `"answer from our FAQ"`) and the best-fitting recipes are ranked first; omit it to skim the whole library. Returns each recipe's `name`, `title`, `description`, and `keywords`. Fetch the full skeleton with getRecipe(name), adapt it (purpose/persona/message text + capability choices), then setAuthoredConfig it. Start here instead of composing a config from scratch. Read-only.

listRecipes

List the interactions the creator FLAGGED while reviewing real conversations on the Console — the feedback inbox this loop drains. Returns the agent's flags newest-first, each `{ id, correlationId, excerpt, note, status, evalId }`: `excerpt` is the transcript span frozen at flag time (`{ role: 'user'|'agent', text }[]` — what actually happened), `note` is the creator's correction (what SHOULD have happened — treat it as the requirement), DISPUTED TESTS: a `correlationId` starting `eval:` flags an EXISTING test from the Quality page's conversation view — the creator read the test's conversation and believes the RUBRIC is wrong, not the agent. For those, review the eval (the id follows `eval:`) and its criteria against the excerpt + note; if the creator is right, FIX THE TEST (replace it via deleteCapabilityEval + addScenarioEval with corrected criteria, or adjust the behaviorIntent) and then dismissFlag — do NOT convertFlagToEval (that would mint a duplicate test), `status` walks 'open' → 'converted' | 'dismissed' (default filter: 'open'; pass `status: 'all'` for history), and `evalId` points at the scenario eval a converted flag became. THE LOOP: a flag is a failing test the agent already failed for real. Process each open flag: (1) read the excerpt + note and decide whether it reveals a MISSING requirement — if so, add a behaviorIntent for it first (setAuthoredConfig/patchAuthoredConfig); (2) convertFlagToEval with sharpened judge criteria and the intent link; (3) fix the config so the behavior actually changes (guidance, soul, rules, or an intent example); (4) runQualitySuite and confirm the flag-derived eval passes AND nothing else regressed; (5) publish. Dismiss (dismissFlag) only what the creator confirms is a one-off. Read-only.

listFlaggedInteractions

List the creator's agents (id, name, status, slug). Read-only.

listAgents

List the connectors currently enabled on the agent (each with its `connectorId` and the `enabledTools` scope, if any). Read-only.

listEnabledConnectors

List the agent's EVAL-able capability instances — the individual steps you can write re-runnable unit tests against. Compiles the DRAFT and returns one entry per instance: `{ instanceId, moduleId, evalKind, judge, supportsDeterministic }`. Use `instanceId` as the `capabilityInstanceId` when you add an eval. `evalKind` is `capability` (feed it an input, score the output) or `tool-selection` (feed the composer a user message, assert which tools it calls). `supportsDeterministic` says whether an exact `deterministic` matcher is allowed; `judge` (`text`|`image`|null) says which model judge scores fuzzy outputs. Read-only.

listEvalTargets

List the valid `then.target` instances for the agent's reactive rules — so you don't have to guess an instance id or probe with a bad rule to learn it. Compiles the DRAFT and returns `{ targets }`, each `{ id, module, emits }`: `id` is a compiled capability instance usable DIRECTLY as a rule's `then.target`, `module` is the capability it runs (for an ATTACHED capability the bare module id — e.g. "messenger" — is ALSO a valid target and additionally enables synchronous payload validation), and `emits` are the event types that instance can produce (wire another rule's `when.event` off one to chain behaviors). The list includes the auto-wired BASELINE instances (the agentic composer + `replier`) and the `escalation` instance when human-in-the-loop is on — targets that aren't in getCatalog and are otherwise undiscoverable. Read-only.

listTargets

List the valid `when.event` values a reactive rule can fire on for this agent — so you don't have to hand-assemble them from getCatalog + the draft, or probe with a bad rule to learn them. Compiles the DRAFT and returns `{ triggerEvents }`, each `{ event, source, emittedBy }`: `event` is the type usable DIRECTLY as a rule's `when.event`; `source` is how it becomes fireable — `builtin` (`MessageReceived`, the universal external chat entry point, always present), `capability` (an event an ATTACHED capability instance emits — `emittedBy` lists the instance ids, so you can chain a rule off another rule's command), `connector-trigger` (`ConnectorTriggerReceived`, present ONLY when a connector trigger subscription is in the draft's `connectorTriggers`), or `signal` (a custom composer signal you declared). An event NOT in this list is unfireable for this draft: attach the capability/connector trigger or declare the signal first. This is the `when.event` companion to listTargets (which lists the valid `then.target`). Read-only.

listTriggerEvents

Apply a PARTIAL update to an already-configured agent without resending the whole config — tightens the iterate loop when you only want to change one field. Pass `agentId` and `set`, an object of the top-level fields to change (e.g. `{ purpose: "…" }`, `{ channels: ["web","sms"] }`, `{ guidance: [...] }`, `{ activityDisplay: "all" }`). Each key in `set` REPLACES that field wholesale (arrays/objects are NOT deep-merged — predictable); fields you omit are left untouched. The merged config is re-validated exactly like setAuthoredConfig (capability ids + reactive-rule payloads are checked, so a bad patch is rejected with the same field-level errors), and the result returns the full merged config plus any `channelAdvisories` and `capabilityAdvisories` (the known pitfalls of the attached capabilities). The agent must already have a config (create it with createAgent/createConversationalAgent and setAuthoredConfig first). PROTECTED REQUIREMENTS: patching `behaviorIntents` to drop or downgrade a published `priority: "must"` intent is rejected unless you pass `acknowledgeRemovals: [<the intent id>]` — the same durable-requirement guard as setAuthoredConfig, so an incremental edit can't silently erase a hard requirement. QUALITY LOOP: after changing an agent's behavior (soul, behaviorIntents, capabilities, guidance), run runQualitySuite and read `rollup.regressions` — it diffs against the previous completed run and shows exactly which requirements your change made WORSE ('newly_failing', 'score_drop', 'requirement_dropped'). New behaviorIntents get their standard test battery written automatically by that same call. Don't publish a change that introduced regressions without either fixing it or telling the creator why it's acceptable.

patchAuthoredConfig

Preview what the DRAFT would do with ONE user message, WITHOUT publishing and WITHOUT the scenario harness — pass `agentId` and `message`. Returns `{ reply, producedTypes, failures }`: the reply the agent would send, the event cascade it triggered (so you can see which rules fired), and any command failures. NOTE: this is a DETERMINISTIC preview — the rule wiring and which capabilities fire are faithful, but the reply TEXT is a stand-in, not the live model's exact wording (that appears once published). Use it to catch a silent agent, a mis-wired rule, or a failing command far faster than a publish round-trip. Read-only.

tryAgent

Arm the draft's AGENT-WIDE standing schedules (declared on the scheduler capability's `config.schedules: [{ label, spec }]`) on the agent-level session and advance its clock, returning each firing's cascade — so you can confirm an agent-wide cadence (a weekly announcement, a daily digest) ARMS and drives its `TimerFired` rule WITHOUT hand-firing a TimerFired. Returns `{ correlationId, until, armed, firings, events, failures? }`: `armed` is what was scheduled, `firings` are the occurrences that fell due (label + 0-based occurrence + firedAt), `events` is the produced cascade (look for the broadcast/digest each firing drove). Omit `until` for a deterministic default window (35 days past each schedule's anchor); pass an ISO `until` for a specific horizon. `armed: []` means no standing schedules are configured. Read-only — nothing is persisted or sent.

previewSchedule

Compile the agent's guidance into runtime policies, run the full safety review, and publish it to the web. On success returns the public link (the creator can share it immediately). Phone numbers are DECOUPLED from publish: when the agent has an sms/voice channel, publishing KICKS OFF number issuance in the background and returns `numberPending: true` — it does NOT wait for or fail on the number. Call `issueNumber` to check/retry the number (it's idempotent), or read it later via getAgent. If the review blocks publishing, returns the blockers to fix — adjust the config and call again. PENDING RESULT: the safety review runs server-side; if it hasn't finished within the in-request window, this returns `{ pending: true, buildId }` (NOT an error and NOT a timeout — the build keeps running). When you get that, call `getPublishStatus` with the returned `buildId` to read the final outcome; do NOT re-call publishAgent (that starts a NEW build). AFTER PUBLISH: the platform re-grades the published agent automatically in the background (the same suite runQualitySuite runs); call getQualityReport a few minutes later to read the fresh grade and its `regressions`, and treat a post-publish regression as a bug to fix, not noise.

publishAgent

Force the agent's LIVE conversations onto a specific published build NOW — the opt-in override for an urgent or safety fix. By DEFAULT a re-publish does NOT touch conversations already in flight: each one stays pinned to the build it started on and only re-resolves to the latest at its own idle gap or continue-as-new boundary (and even then only if the change is compatible). This tool is the deliberate firehose for when you can't wait for that. Pass `{ agentId, buildId, mode? }` where `buildId` is the TARGET build (the one you just published — read it from getAgent / the publish result). `mode` is `"compatible-only"` (the DEFAULT — safe): a conversation the target build is BREAKING for (it would strand that conversation's accumulated in-flight state) is SKIPPED and reported back, never migrated; only compatible conversations are swapped. `mode: "all"` is the explicit DATA-LOSS override: it migrates EVERY conversation including breaking ones, and lists each breaking one under `dataLossOverrides` so the loss is on record — use it only when the fix is more important than the in-flight state. Returns a compatibility report `{ buildId, total, migrated, skipped, endedOrIdle, skippedReasons: [{ correlationId, reasons }], dataLossOverrides? }`: `migrated` got the swap, `skipped` were breaking (compatible-only), `endedOrIdle` had already ended (nothing to migrate — they pick up the latest on their next turn anyway), and `skippedReasons` explains WHY each was breaking. A migrated conversation swaps forward-only (its future turns use the new build; past events are never re-folded) and surfaces a DefinitionUpgraded event on its next turn.

forceMigrateLiveConversations

Read the agent's EVAL COVERAGE at a glance — which capability steps have re-runnable unit tests, which steps are still UNTESTED, and which existing evals never ran, are failing, or are orphaned — so you close the gaps instead of re-deriving them from listEvalTargets + listCapabilityEvals. Compiles the DRAFT and returns `{ targets, orphanedEvals, summary }`. Each target is an eval-able instance (same shape as listEvalTargets) plus its rolled-up cases: `evalCount`, `neverRunCount` (authored but never executed), `failingCount` (last score < 0.7), and `evals` (each case's id, name, lastScore, lastRunAt). An UNCOVERED target (`evalCount: 0`) carries a `suggestion` — a concrete first case to author for that step (the right input shape and expectation kind). `orphanedEvals` are cases whose target instance no longer exists in the current draft (left behind by a config edit) — delete them or re-add them against the new instance id. `summary` totals it: `{ targetCount, coveredCount, uncoveredCount, evalCount, neverRunCount, failingCount, orphanedCount }`. Workflow to CLOSE a gap: getEvalCoverage → addCapabilityEval for each uncovered target (start from its `suggestion`) → runCapabilityEval to score each new case → getEvalCoverage again to confirm `uncoveredCount: 0` and nothing failing. Read-only.

getEvalCoverage

Read the agent's knowledge base: how many sources it has and their processing status. You can add reference TEXT directly with seedKnowledgeText; FILE uploads still go through the Outside Agent Console (the manageUrl from setAuthoredConfig/publishAgent). Use THIS tool to check whether sources have finished indexing. Returns `{ total, counts: { ready, processing, pending, failed }, ready, sources: [{ id, title, sourceType, status, errorMessage }] }`. `ready` is true once at least one source is embedded and searchable. After you seed text (or the creator uploads files) call this: if `counts.processing` or `counts.pending` is non-zero indexing is still running (call again shortly); once `ready` is true you can confirm the knowledge base was added successfully and continue. A `failed` source carries a friendly `errorMessage`. Read-only.

getKnowledgeBase

Read the Quality report — the same single view the Console Quality page shows, in one call. Returns `{ understood, built, tested, flags, latestRun, runs }`: `understood` is the requirement ledger (every behaviorIntent's `intentId`/`statement` — what the platform believes the agent must do; EVERY requirement weighs the same in the grade, the config's `priority` field is ignored by grading; if a requirement is wrong or missing, fix the config's `behaviorIntents`); `built` lists the compiled capability instances, channels, `soulPresent`, and `replyMode` (what actually got wired); `tested` describes the suite's shape (`testCount`, `scenarioCount`, `generatedCount`, `authoredCount`, `intentsWithoutBattery` — intents the next runQualitySuite will auto-cover — and `testCountByIntent`, live per-requirement test counts); `gradeStale` is true when the config or the test set changed since the latest completed run (e.g. a flag was just converted) — the standing grade doesn't cover the change until runQualitySuite runs again; `flags.openCount` says how many creator-flagged real interactions await processing (listFlaggedInteractions to read them); `latestRun` + `runs` carry the grade history (see runQualitySuite for the rollup shape). Use it to answer 'did the platform understand the ask, is it tested, and what is the grade' before and after changes. Read-only.

getQualityReport

Load an agent's REQUIREMENT LEDGER before you change it — read this FIRST when taking over or editing an existing agent, so you don't regenerate over requirements it already commits to. Returns `{ purpose, intents, ledgerStatus, unverifiedMustIntentIds, summary }`. `intents` is every recorded behaviorIntent with its `priority`, its `sourceQuote` provenance, and a `coverage` roll-up (how many linked evals, and how many are passing/failing/never-run) — so you see what the agent must do AND which requirements are actually verified. `ledgerStatus` is `healthy` (records must-have requirements), `thin` (has behavior but NO must intent — nothing protects it across edits; call suggestBehaviorIntents to backfill), or `empty` (a fresh agent). `unverifiedMustIntentIds` are the must intents with no passing eval — add one with addCapabilityEval (intentId) so a later change can't silently break them. `summary` gives capability/rule counts + channels for orientation. Pair with getAuthoredConfig for the full config. Read-only.

getAgentSpec

Read what a PUBLISHED agent actually DID at runtime — the durable domain events it folded, newest first, across all of its conversations. The investigative companion to getAgent (which shows config): use THIS to see whether a side effect actually happened. Every capability outcome is here — `EmailSent` vs `EmailFailed`, `CallFailed`, `PaymentCaptureFailed`, etc. — so you can confirm e.g. that an email truly sent rather than trusting the agent's reply text. Input: `{ agentId, limit? (default 50, max 200), conversationId?, type? (exact, e.g. "EmailFailed"), failuresOnly? (only events whose type ends in "Failed"), since? (ISO instant) }`. Returns `{ agentId, total, matched, returned, truncated, events: [{ id, type, at, source, conversationId, causationId?, failed, payload }] }` — payloads are redacted (data: URIs dropped, long strings truncated). `failed` flags failure events at a glance; `truncated` means more matched than the page returned (raise `limit` or filter by `conversationId`/`since`). Read-only.

getAgentTimeline

Capture the RAW source you are building this agent from — BEFORE you reviewAgent/publishAgent — so the safety review can verify nothing was dropped. The review runs an advisory `requirement_coverage` pass that compares this source against the assembled agent and WARNS (it never blocks) about any requirement that did not make it in; those warnings come back in reviewAgent's `findings` for you to fix. Pass `messages`: the build conversation as role-tagged turns, oldest-first — `role: "creator"` for the human's own words (paste the dropped transcript or brief as one creator message; or each of their answers), and `role: "builder"` for YOUR questions and framing. CAPTURE BOTH SIDES, in order: a terse creator answer ("yes", "after two tries", "text my cell") is only a requirement together with the builder question it answered, so recording the answer WITHOUT its question loses the requirement. Recording the full back-and-forth also lets a later reversal ("actually, drop SMS") correctly cancel an earlier ask instead of looking like a dropped one. Appends (does not replace): call once with the whole exchange, or turn-by-turn as you interview — the messages accumulate in order. This does NOT change the agent's config; it only records what to check the config against. Owner-gated to your own agent.

recordSourceRequirements

Remove an E.164 number from a private agent's allow-list (matched exactly). The owner keeps access regardless. Owner-scoped.

removeAllowedNumber

Log an improvement, blocker, or opportunity you hit WHILE building — feedback for the platform team about the build surface itself, NOT a message to the creator. Call this whenever the tools or catalog get in your way: a capability the spec NEEDED that doesn't exist (`kind: "blocker"`); a limitation you had to work AROUND but shipped anyway (`kind: "opportunity"`); or a clunky/missing/confusing MCP tool, catalog gap, or unclear error (`kind: "improvement"`). Logging it is fire-and-forget: it stores a row for the team and DOES NOT change or block this build — keep building. Input: `{ kind, title, body, severity?, capabilityArea?, agentId?, context? }`. Make `title` a one-line summary and `body` concrete — what you needed, why you couldn't do it with today's tools, and what would have helped (name the exact tool/capability id/field and quote the error or catalog absence). `severity` is `blocks-build` | `degrades` | `nice-to-have`; `capabilityArea` is a coarse tag (e.g. "scheduling", "communication", "knowledge"); pass the `agentId` you're building and any structured `context` (the failing call, ids) to help triage. Returns `{ id, status: "new", message }`. Prefer ONE feedback row per distinct gap (don't spam duplicates). This is the right channel for 'the platform should be able to…' — use it instead of silently faking a required integration or abandoning a `must` behavior.

reportBuilderFeedback