AI, retrieval & agent protocols

In wildo.saas.config.ts, capability enablement and runtime-scoped provider declarations are separate. This reduced selection follows Wonder Todos; merge these properties into the existing configuration. Import EngineCapability from @wildo-ai/saas-models and defineSaaSProviders from @wildo-ai/platform-config-lib. WildoDiscoveredProviderCatalog comes from the application’s generated .wildo-saas/generated/provider-catalog.types.

engineCapabilities: {
  [EngineCapability.AI_LLM]: { enabled: true },
},
providers: defineSaaSProviders<WildoDiscoveredProviderCatalog>({
  scopes: {
    backend: {
      providers: {
        anthropic: {
          engineCapabilities: [EngineCapability.AI_LLM],
          providerCapabilities: ['LLM_CHAT'],
          protocols: ['LLM_PROVIDER'],
        },
      },
      selection: {
        [EngineCapability.AI_LLM]: { primary: 'anthropic', whenUnavailable: [] },
      },
    },
  },
}),

The deployment must also supply the selected provider’s credentials through its secret configuration. Synchronize the application configuration with wildo config sync so the backend consumes the generated provider runtime. This backend declaration does not enable a provider in the companion or frontend scopes. The agent below explicitly names anthropic; the selection policy does not rewrite that agent’s provider after a failed request.

Define an agent, then register it

The declaration below is the framework’s support-ticket example. Its agent is active, its provider and operation agree in both configuration and operation definition, and its prompt specifies the business task. The module must include it in flowsActors.agents; a file existing on disk does not register an agent.

export const ticketTriageAgent: FlowsActors_Agent = {
  ref: TICKET_TRIAGE_AGENT_REF,
  displayName: 'Support Ticket Triage',
  status: FlowsActors_Agent_Status.ACTIVE,
  config: {
    providerRef: 'anthropic',
    modelApplicability: LLM_Model_Applicability.STRUCTURED_AUTHORING,
    operationKey: LLMProvider_OperationKey.GENERATE_STRUCTURED,
    reasoningEffort: LLMProvider_ReasoningEffort.LOW,
    accessControl: [{ primaryScope: ResourcePrimaryScope.APPLICATION, requiresApproval: false }],
    riskLevel: ResourceOperationRiskLevel.LOW,
  },
  operationDefinition: {
    operationKey: LLMProvider_OperationKey.GENERATE_STRUCTURED,
    providerRef: 'anthropic',
    inputSchema: LLMProvider_GenerateStructuredInputSchema,
    outputSchema: LLMProvider_GenerateStructuredOutputSchema,
    operationContextSchema: LLMProvider_OperationContext_BaseSchema,
  } satisfies LLMProvider_OperationDefinitionBase,
  promptSpec: {
    role: 'You triage inbound customer support tickets for a SaaS product.',
    persona: 'You are terse and literal. You classify only what the ticket actually says.',
    skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
    instructions: [
      'Choose exactly one category. When a ticket spans several, pick the one the customer is asking you to ACT on.',
      'Reserve "high" urgency for outages, data loss, or failed payments. Frustrated tone alone is not urgency.',
      'Summarize what the customer wants, never what you would do about it.',
      'Never infer facts the ticket does not state — no account ids, no product names, no dates.',
    ],
  },
  createdAt: '2026-08-01T00:00:00.000Z',
};

Provider availability and agent selection are different decisions. A provider selection list does not mean a pinned agent automatically switches vendors after a failed request. Keep providerRef aligned with the operation contract and enable the corresponding provider in the runtime scope. Per-call material belongs in invocation input, not in the durable agent prompt.

Register the declaration and define the result

The backend module contributes the agent through flowsActors. This excerpt is the registration object from the example; include it in the owning module’s existing contribution rather than replacing other registered agents:

export const moduleBackend_FlowsActorsRegistry: { agents: FlowsActors_Agent[] } = {
  agents: [ticketTriageAgent],
};

The invocation below uses this application-owned response contract. The descriptions tell the model what the fields mean; parsing the returned value establishes that it has the expected shape.

enum TicketCategory {
  BILLING = 'billing',
  BUG = 'bug',
  FEATURE_REQUEST = 'feature_request',
  ACCOUNT = 'account',
  OTHER = 'other',
}
enum TicketUrgency {
  LOW = 'low',
  MEDIUM = 'medium',
  HIGH = 'high',
}

const TicketTriageSchema = z.object({
  category: z.enum(TicketCategory)
    .describe('The single best-fitting category for the ticket.'),
  urgency: z.enum(TicketUrgency)
    .describe(`How quickly a human must respond. "${TicketUrgency.HIGH}" only for outages, data loss, or billing failures.`),
  summary: z.string().max(200)
    .describe('One-sentence neutral summary of what the customer is asking for.'),
});

A successful call returns a category, urgency and summary. The application still decides how those values affect routing or service commitments; a valid enum is not proof that the model classified the ticket correctly.

Invoke it with a response contract

The same example calls the registered agent with its ticket schema and validates the returned object. TicketTriageSchema is the application-owned Zod output contract; the service receives AgentsBackendService through dependency injection.

@injectable()
export class TicketTriageBackendService {
  constructor(
    @inject(SAAS_SERVICE_TYPES.AgentsBackendService) private readonly agentsService: AgentsBackendService,
  ) {}
  public async triageTicket(ticketBody: string): Promise<z.infer<typeof TicketTriageSchema>> {
    const invocation: FlowsActors_Agent_Invocation<
      typeof LLMProvider_GenerateStructuredInputSchema,
      typeof LLMProvider_GenerateStructuredOutputSchema,
      typeof LLMProvider_OperationContext_BaseSchema
    > = {
      agentRef: TICKET_TRIAGE_AGENT_REF,
      initiator: {},
      invocationContext: [],
      input: {
        prompt: `Triage this support ticket:\n\n${ticketBody}`,
        schema: TicketTriageSchema,
      },
      output: { object: {} },
      executionContext: { callTimestamp: new Date().toISOString() },
      artifactBindings: [],
    };
    const result = await this.agentsService.invokeAgent(invocation);
    return TicketTriageSchema.parse((result.output as { object: unknown }).object);
  }
}

This excerpt from llm-agent-invocation.example.ts selects STRUCTURED_AUTHORING within Anthropic. The registry resolves it to a concrete model before requests run; downstream execution receives that resolved configuration.

export const ticketTriageAgent: FlowsActors_Agent = {
  ref: TICKET_TRIAGE_AGENT_REF,
  displayName: 'Support Ticket Triage',
  status: FlowsActors_Agent_Status.ACTIVE,
  config: {
    providerRef: 'anthropic',
    modelApplicability: LLM_Model_Applicability.STRUCTURED_AUTHORING,
    operationKey: LLMProvider_OperationKey.GENERATE_STRUCTURED,
    reasoningEffort: LLMProvider_ReasoningEffort.LOW,
    accessControl: [{ primaryScope: ResourcePrimaryScope.APPLICATION, requiresApproval: false }],
    riskLevel: ResourceOperationRiskLevel.LOW,
  },
  operationDefinition: {
    operationKey: LLMProvider_OperationKey.GENERATE_STRUCTURED,
    providerRef: 'anthropic',
    inputSchema: LLMProvider_GenerateStructuredInputSchema,
    outputSchema: LLMProvider_GenerateStructuredOutputSchema,
    operationContextSchema: LLMProvider_OperationContext_BaseSchema,
  } satisfies LLMProvider_OperationDefinitionBase,
  promptSpec: {
    role: 'You triage inbound customer support tickets for a SaaS product.',
    persona: 'You are terse and literal. You classify only what the ticket actually says.',
    skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
    instructions: [
      'Choose exactly one category. When a ticket spans several, pick the one the customer is asking you to ACT on.',
      'Reserve "high" urgency for outages, data loss, or failed payments. Frustrated tone alone is not urgency.',
      'Summarize what the customer wants, never what you would do about it.',
      'Never infer facts the ticket does not state — no account ids, no product names, no dates.',
    ],
  },
  createdAt: '2026-08-01T00:00:00.000Z',
};

Author exactly one of modelApplicability or model. The explicit model is the escape hatch for a pinned or custom deployment. Registration refuses a class the selected provider cannot serve; it does not silently substitute another type of work. Reasoning settings are validated against the resolved model. This is registration-time policy, not dynamic per-request benchmarking or vendor failover.

This is the companion’s actual logo-agent definition. It separates image settings from language-model sampling and declares image output explicitly. Register the agent in its owning runtime and enable an image provider there before invoking it.

export const LOGO_GENERATION_AGENT_REF = 'brand.logo.generation.agent';
export function buildLogoGenerationAgent(): FlowsActors_Agent {
  return {
    ref: LOGO_GENERATION_AGENT_REF,
    displayName: 'Logo Generation Agent',
    status: FlowsActors_Agent_Status.ACTIVE,
    outputModality: FlowsActors_IO_PartKind.IMAGE,
    inputModalities: [FlowsActors_IO_PartKind.TEXT],
    config: {
      providerRef: 'openai',
      model: ImageProvider_Model.OPEN_AI_GPT_IMAGE_1_5,
      operationKey: ImageProvider_OperationKey.GENERATE_IMAGE,
      size: ImageProvider_Size.SQUARE_1024,
      quality: ImageProvider_Quality.HIGH,
      background: ImageProvider_Background.TRANSPARENT,
      outputFormat: ImageProvider_OutputFormat.PNG,
      n: 1,
      accessControl: [{
        primaryScope: ResourcePrimaryScope.APPLICATION,
        requiresApproval: false,
      }],
      riskLevel: ResourceOperationRiskLevel.LOW,
    },
    operationDefinition: {
      operationKey: ImageProvider_OperationKey.GENERATE_IMAGE,
      providerRef: 'openai',
      inputSchema: ImageProvider_GenerateImageInputSchema,
      outputSchema: ImageProvider_GenerateImageOutputSchema,
      operationContextSchema: ImageProvider_OperationContext_BaseSchema,
    } satisfies ImageProvider_OperationDefinitionBase,
    promptSpec: {
      role: 'You are a brand identity designer generating a single application logo. You receive a '
        + 'fully-assembled visual brief (brand name, mark direction, visual tone, symbolism) and render '
        + 'exactly one clean, production-ready logo mark that honours it.',
      skillType: FlowsActors_Agent_Skill_Type.GENERATION,
      instructions: [],
    },
    createdAt: '2026-07-11T00:00:00.000Z',
  };
}

The executor validates provider enablement, credentials and the image runtime binding, then runs the provider call through its limiter. Output contains images, each with base64 and mediaType; persistence and publication are separate application decisions. The current executor generates from the text prompt. It does not pass reference images to the provider, so this execution path does not support reference-image editing.

Supply a brief and consume the image

This selected companion call runs the registered logo agent. render.prompt is the visual brief already assembled by the workflow; traceContext identifies this run for observation. The invocation uses the image schemas imported alongside the declaration.

const invocation: FlowsActors_Agent_Invocation<
  typeof ImageProvider_GenerateImageInputSchema,
  typeof ImageProvider_GenerateImageOutputSchema,
  typeof ImageProvider_OperationContext_BaseSchema
> = {
  agentRef: LOGO_GENERATION_AGENT_REF,
  initiator: {},
  invocationContext: [],
  input: { prompt: render.prompt },
  output: { images: [] },
  executionContext: { callTimestamp: new Date().toISOString() },
  artifactBindings: [],
};

const result = await this.agentsService.invokeAgent(invocation, traceContext);
const output = result.output as ImageProvider_GenerateImageOutput;
const masterImage = output?.images?.[0];

The workflow checks that masterImage.base64 is nonempty before decoding and processing it. Its logo-specific cleanup, asset staging and derived icons happen afterward. Keep those application decisions separate from generation: another image feature may store the returned bytes through its own file resource instead.

This excerpt adapts the companion’s registered binding; ApplicationCodingAgentBinding is its application-owned type. The matching execution profile must be authored in runtime configuration. It keeps provider, model and execution profile together. A coding agent requires executionProfileRef; unlike a language-model API call, it cannot omit the authority and environment under which its subprocess runs.

const codingAgentBinding = {
  ref: 'application-coding.agent',
  displayName: 'Application Coding Agent',
  providerRef: 'anthropic',
  executionProfileRef: 'claude-code-acp',
  model: LLM_Model.CLAUDE_OPUS_5,
} satisfies ApplicationCodingAgentBinding;

The ACP runner negotiates the protocol, opens or resumes the session, exchanges turns and answers permission requests. Enforcement depends on which callbacks the provider actually raises. The dispatch layer checks the provider’s declared permission-escalation behavior before accepting a restrictive ceiling. Do not describe mutation scope as an operating-system sandbox: a child doing its own I/O without a relevant callback is a different boundary, and the recorded run/change set remains important.

Author the matching companion execution profile

The binding above names claude-code-acp. Declare that same key under providerConfigurations.anthropic[ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL].executionProfiles in wildo.saas.config.ts. This selected profile follows Wonder Todos’ development setup; the omitted settings govern recording and data-processing declarations, not provider selection. The AgentClientProtocol_* enums, APPLICATION_ENVIRONMENT and ExternalProvider_ExchangeProtocol_Kind come from @wildo-ai/external-connectors-models.

providerConfigurations: {
  anthropic: {
    [ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL]: {
      defaultExecutionProfileRef: 'claude-code-acp',
      executionProfiles: {
        'claude-code-acp': {
          runnerHost: AgentClientProtocol_RunnerHost.BACKEND_SUBPROCESS,
          authMode: AgentClientProtocol_AuthMode.HOST_MANAGED,
          allowedApplicationEnvironments: [APPLICATION_ENVIRONMENT.DEVELOPMENT],
          workingDirectoryPolicy: AgentClientProtocol_WorkingDirectoryPolicy.WORKSPACE_ROOT,
          permissionCeiling: AgentClientProtocol_PermissionCeiling.UNRESTRICTED,
          hostConfigurationInheritance: AgentClientProtocol_HostConfigurationInheritance.APPLICATION_SCOPED,
          turnTimeoutMs: 30 * 60_000,
          maxAutoContinuations: 12,
          awaitingInputTtlMs: 30 * 60_000,
        },
      },
    },
  },
},

HOST_MANAGED uses the operator’s existing agent login. The provider owns its launch command; the host supplies the workspace at invocation. The unrestricted ceiling admits all tool categories; declared locations and available approval options still govern individual requests. It is not a sandbox: filesystem confinement still depends on participating callbacks, and the host must inspect the resulting changes.

Enable EngineCapability.AI_CODING_AGENT, then merge this entry into providers.scopes.companion.providers. EngineCapability comes from @wildo-ai/saas-models. An AI_LLM backend entry cannot substitute for this companion transport:

anthropic: {
  engineCapabilities: [EngineCapability.AI_CODING_AGENT],
  providerCapabilities: ['CODING_AGENT'],
  protocols: ['AGENT_CLIENT_PROTOCOL'],
},

Run wildo config sync after configuration changes. The host needs the provider’s supported agent installation and login before dispatch; selecting a model does not install or authenticate the subprocess. Application runtime language generation has its own backend provider setup.

Dispatch the task in a trusted workspace

The companion constructs this invocation after admitting its typed task and rendering the task prompt. A resumed run supplies the operator’s answer and the existing session ID; a new run supplies the rendered task.

const invocation: FlowsActors_Agent_Invocation<
  typeof CodingAgent_RunTaskInputSchema,
  typeof CodingAgent_RunTaskOutputSchema,
  typeof CodingAgent_OperationContext_BaseSchema
> = {
  agentRef: APPLICATION_CODING_AGENT_REF,
  initiator: {},
  invocationContext: [],
  input: resume
    ? { prompt: resume.answerPrompt, continuationOfSessionId: resume.continuationOfSessionId }
    : { prompt: renderedPrompt },
  output: { finalMessage: '', stopReason: CodingAgent_StopReason.END_TURN },
  executionContext: { callTimestamp: new Date().toISOString() },
  artifactBindings: [],
};

The call also receives the trusted workspace and task-location predicate. This reduced excerpt omits the companion’s event collection and turn-classification callbacks; it shows where workspace and cancellation enter the runtime:

const response = await this.agentsService.invokeAgent(
  invocation,
  traceContext,
  {
    workspaceRootPath: this.companionContext.saasRoot,
    isPermittedCodingLocation: buildApplicationCodingTaskLocationPredicate(
      this.companionContext.saasRoot,
      task.mutationScope.allowedPathPrefixes,
      task.mutationScope.prohibitedPathPrefixes,
    ),
    ...(this.activeRun ? { codingSessionAbortSignal: this.activeRun.abortController.signal } : {}),
  },
);
const codingOutput = response.output as Partial<CodingAgent_RunTaskOutput> | undefined;
const text = codingOutput?.finalMessage;
const stopReason = codingOutput?.stopReason;

finalMessage is not itself acceptance of the changes. The host checks the stop reason, records the run and inspects the resulting change set. A parked run is asking for input, not reporting a finished implementation. Permission callbacks constrain participating operations; they do not turn arbitrary subprocess I/O into a filesystem sandbox.

Match the reader to the document format

The extraction service downloads the file through its resolved storage provider. Plain text is read directly. PDFs use the local text-layer reader; .docx, .xlsx, .pptx, .odt, .ods and .odp use the ZIP/XML reader.

The Office reader extracts text from the document’s parts. Its partCount represents those units—for example, slides in a presentation—rather than inventing a printed page count. Extraction returns text plus metadata such as character and word counts.

A PDF with no text layer needs provider-backed recognition. Legacy binary .doc, .xls and .ppt also require a provider that declares support for their media type. Choose accepted upload formats according to the paths your deployment enables.

Make the local path an intentional field choice

This shared-schema declaration is adapted from Wonder Todos’ knowledge documents. It selects a smaller, locally readable MIME set from that application’s full list. Keep it in the resource schema used by the factory; a standalone unused schema does not register a corpus.

import { z } from 'zod';
import { initZodDecorators, z_file, RAGChunkingStrategy } from '@wildo-ai/zod-decorators';

initZodDecorators(z);

export const KnowledgeDocument = z.object({
  document: z_file({
    allowedMimeTypes: [
      'application/pdf',
      'text/plain',
      'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    ],
    multiple: false,
    textExtraction: { ocr: false },
    ragSource: {
      chunkingStrategy: RAGChunkingStrategy.RECURSIVE,
      chunkSize: 1_500,
      chunkOverlap: 200,
    },
  }).optional(),
});

These options make separate decisions: the MIME list admits uploads, textExtraction chooses whether a provider may read them, and ragSource selects the extracted text for chunking. A PDF MIME type does not establish that its pages contain a readable text layer. Do not add legacy binary Office formats to a local-only field merely because the general document MIME group includes them.

After a normal upload and record write, this single-file field holds { fileId, updatedAt }. Ingestion reads the stored bytes once the file is eligible, extracts text and derives chunks; retrieval becomes usable after successful ingestion and search-index readiness. The retrieval guide connects those chunks to an authorized query. Upload success alone is not an indexing receipt.

When ingestion reads a file field, it passes that field’s extraction choice to the service. This is the connection in rag-ingestion.backend.service.ts:

extracted = await this.fileTextExtraction.extractText(file, input.executionContext, {
  allowProviderExtraction: input.fieldMeta.textExtraction?.ocr === true,
});

Only an explicit ocr: true permits provider-backed extraction. An absent setting or false keeps the field on its local path. Even with a provider selected, plain text is handled directly.

Read the outcome according to the input

These are format paths, not a guarantee that every file with that extension is readable. Keep failed downloads and parser outcomes distinct from successful extraction of an empty document.

Distinguish unreadable content from an unavailable service

A malformed document and a failed storage download need different treatment. Parsing failures identify unreadable bytes; storage and provider availability failures remain failures that can be retried. When a provider fails, a usable local text layer can still supply the result.

If neither path can read a scan during a provider outage, extraction fails rather than reporting an empty document. That preserves an existing retrieval corpus for a later retry. The extracted text can then flow into the field’s retrieval configuration, which separately controls indexing and chunking.

Declare source fields, then call retrieval from an authorized operation using the caller’s context.

Use .ragSource() on selected text fields and z_file({ ragSource: ... }) for file-backed text. Forward the operation’s executionContext unchanged to retrieve. Narrow with resourceTypes where the feature should search only a specific corpus. Inspect searchStatus, embeddingStatus, refusedResourceTypes and truncation; a failed search, refused corpus and healthy empty search are separate outcomes. Search execution errors remain in operational logs; the result exposes safe availability diagnostics. Scores rank one query’s results and are not universal confidence percentages. PostgreSQL and MongoDB stores exist, with adapter-specific search infrastructure requirements.

Prepare the store that owns the records

Chunk storage follows the resource’s persistence adapter. Do not introduce a second database solely because a field becomes a corpus source.

MongoDB indexes build asynchronously. A ready lexical arm can serve without vectors, and an available vector arm can operate while lexical search is unavailable. If neither usable arm can run, their availability reports produce failed search status. If only one requested arm runs, search status is degraded. Execution exceptions are still caught and logged, preserving the turn with failed search status and empty context. When an aggregate aborts before returning reliable arm reports, those requested arms are marked unknown. None of these outcomes should be described as an empty knowledge base.

Connect the declaration to the query

The following declaration is adapted from Wonder Todos’ knowledge-document schema. The decorator initialization and imports belong in the shared schema module. Fields without ragSource remain outside the corpus.

import { z } from 'zod';
import { initZodDecorators, RAGChunkingStrategy } from '@wildo-ai/zod-decorators';

initZodDecorators(z);

const KnowledgeText = z.object({
  title: z.string().min(1).max(200).ragSource(),
  body: z.string().max(200_000).ragSource({
    chunkingStrategy: RAGChunkingStrategy.MARKDOWN,
    chunkSize: 1_200,
    chunkOverlap: 150,
  }).optional(),
  internalReviewNotes: z.string().optional(),
});

Inside the registered ask custom-operation handler, the application resolves the retrieval service lazily from its container and forwards the caller’s existing context. This is the actual call shape; question, limit and maxContextCharacters come from the operation’s validated request. projectAnswer is the operation’s response mapper; it retains source identifiers and passages.

retrievalService ??= container.get<RagRetrievalBackendService>(
  SAAS_SERVICE_TYPES.RagRetrievalService,
);

const result = await retrievalService.retrieve({
  query: question,
  executionContext,
  resourceTypes: [TasksManager_ResourceType.KNOWLEDGE_DOCUMENTS],
  expandRelationships: false,
  ...(limit !== undefined && { limit }),
  ...(maxContextCharacters !== undefined && { maxContextCharacters }),
});

return projectAnswer(question, result);

The surrounding operation owns its request/response DTOs and role declaration, and registers through createResourceCustomServiceImplementation. The assistant’s function tool calls that same operation through executeCustomOperation; it does not expose an unscoped retrieval endpoint or accept tenant identity from the model.

Size the context and keep its attribution

Inside the operation, consume the actual result instead of treating a passages array as a complete answer. This illustrative projection preserves the service’s attribution and diagnostics; keep operational refusal details in an appropriate authenticated response or diagnostics surface.

const sources = result.rows.map((row) => ({
  resourceType: row.resourceType,
  resourceId: row.resourceId,
  header: row.header,
  passages: row.passages,
}));

return {
  context: result.rows.map((row) => row.contextText).join('\n\n'),
  sources,
  mode: result.mode,
  searchStatus: result.searchStatus,
  embeddingStatus: result.embeddingStatus,
  searches: result.searches,
  chunkHitCount: result.chunkHitCount,
  contextCharacters: result.contextCharacters,
  refusedResourceTypes: result.refusedResourceTypes,
  truncation: result.truncation,
};

searchStatus distinguishes a healthy search from a degraded, failed or unattempted one. embeddingStatus separately distinguishes an intentionally absent provider from a failed query embedding. mode describes the requested search; searches reports actual arm outcomes for each admitted resource type. If an aggregate call aborts before returning those outcomes, requested arms are marked unknown rather than claiming they ran.

contextText retains the row/field framing already assembled by the engine. Keep the source IDs beside the generated answer so the interface can provide citations. The model still needs instructions about how to use that context and what to do when it cannot support an answer.

For attached documents, use the local extraction declaration or explicitly configure provider-backed recognition. Source-field chunking, background ingestion and this query are separate stages of the same corpus.

The following configuration excerpts belong in three existing configuration sections, not one object. Preserve any capabilities already declared for OpenAI when adding embeddings. Application setup enables AI_EMBEDDINGS, declares a provider serving it and selects that provider for the runtime scope.

// In engineCapabilities:
[EngineCapability.AI_EMBEDDINGS]: { enabled: true },

// In the runtime scope's providers:
openai: {
  engineCapabilities: [EngineCapability.AI_EMBEDDINGS],
  providerCapabilities: ['LLM_EMBEDDINGS'],
  protocols: ['EMBEDDINGS_PROVIDER'],
},

// In that scope's selection:
[EngineCapability.AI_EMBEDDINGS]: {
  primary: 'openai',
  whenUnavailable: [],
},

EmbeddingsBackendService.resolveBinding distinguishes a deliberately absent provider from a selected but broken configuration. With no provider, successfully ingested corpus text remains lexically searchable once its search indexes are ready; vectors can be produced later. The binding records provider, model and dimensions; changing the model requires the corpus to converge to the new vector space. Applications should not write a separate embedding loop for resource-backed retrieval.

Keep queries in the corpus’s vector space

Resource retrieval consumes embeddings through this service path after resolving its binding. The excerpt is internal framework code: query is the validated search text, applicability is the selected retrieval class, and resolution.binding is the configured binding checked earlier.

const embedded = await this.embeddings.embedTexts({
  texts: [query],
  purpose: EmbeddingsProvider_TextPurpose.QUERY,
  applicability,
});
const vector = embedded.vectors[0];
if (!vector) {
  throw new Error('Embeddings provider returned no vector for the query text.');
}
return {
  embeddingClass: resolution.binding.applicability,
  embeddingModel: embedded.model,
  embeddingDims: embedded.dims,
  vector,
};

The corpus worker uses the corresponding corpus purpose. Model and dimensions travel with the vector so retrieval can distinguish matching bindings from stale embeddings. Application features normally call resource retrieval and consume attributed passages; they do not need to manipulate these vectors directly. Configure AI_EMBEDDINGS and its provider in the runtime that runs both retrieval and the embedding worker.

This declaration selects markdown chunking and a deliberate overlap. The same ingestion pipeline is used by the live write path and reconciliation, so a later chunking change can rebuild existing material as well as future writes.

const knowledgeText = z.object({
  title: z.string().min(1).max(200).ragSource(),
  body: z.string().max(200_000).ragSource({
    chunkingStrategy: RAGChunkingStrategy.MARKDOWN,
    chunkSize: 1_200,
    chunkOverlap: 150,
  }).optional(),
});

The embedding drain runs on its five-minute schedule and processes a bounded backlog, including embeddings stamped with an old model binding. The hourly sweep checks content and chunking stamps, removes orphan sets, repairs scope stamps and reports embedding backlog; it also visits missing sets. These are converging background mechanisms, not a promise that every change becomes semantically searchable synchronously. No application-owned chunk cleanup or embedding scheduler is needed for this path.

Run the workers and inspect convergence

The engine registers both batch factories during application startup. The deployment must run its batch/cron execution infrastructure, with the RAG chunk store and ingestion services available. Vector work additionally needs an enabled embeddings provider and its credentials in the worker runtime. The drain reports an absent provider rather than manufacturing vectors; it leaves the text corpus available for lexical retrieval.

Inspect the completed batch results and their structured summary logs. A declaration alone does not establish that a worker ran or that the backlog cleared:

After a source or model change, expect migration and backlog counters to converge. Repeated failures or a backlog that does not drain need inspection of the recorded provider/ingestion errors, rather than another application-owned scheduler.

These reserved provider kinds are intentionally absent from executable backend protocol arms. The agent configuration union currently has language-model, image and coding arms.

// Reserved exchange-protocol names; not runnable backend protocols.
AUDIO_PROVIDER = "audio_provider",
VIDEO_PROVIDER = "video_provider",

To add audio or video generation, implement the operation schemas, provider runtime binding, modality-specific agent configuration, dispatch and output handling. Those layers must work together before an application can invoke the new generation operation. The vocabulary drift tests keep reserved protocol names distinct from executable contracts.

This connected example adapts Wonder Todos to one narrow workflow: read a task, retrieve policy passages and request a reviewed rename. It deliberately omits the reference assistant’s list and create tools. First complete the backend provider setup; this agent needs an enabled Anthropic connection and credentials in that runtime.

The agent, system and registry below share the same references. knowledgeBaseAskTool is the application-owned tool explained below; import it and its reference from the adjacent knowledge-base-tool.ts. The other imports use the package roots:

import { z } from 'zod';
import {
  resourceReadTool, resourceWriteTool,
  type FlowActorSystem_InitializationFactoryMap, type FunctionTool,
} from '@wildo-ai/saas-backend-lib';
import {
  Actor_ExecutionMode, Actor_Role_Category, CoreResourceOperation,
  FlowActorSystem_Kind, FlowActorSystem_Status, FlowActorSystem_Visibility,
  FlowsActors_Agent_Skill_Type, FlowsActors_Agent_Status,
  ResourceOperationRiskLevel, ResourcePrimaryScope,
  type ActorSystem, type FlowsActors_Agent,
} from '@wildo-ai/saas-models';
import {
  LLMProvider_ChatCompletionInputSchema, LLMProvider_ChatCompletionOutputSchema,
  LLMProvider_OperationContext_BaseSchema, LLMProvider_OperationKey, LLM_Model,
  type LLMProvider_OperationDefinitionBase,
} from '@wildo-ai/external-connectors-models';
import { TasksManager_ResourceType } from '@wonder-todos/shared-lib';
import { knowledgeBaseAskTool, KNOWLEDGE_BASE_ASK_TOOL_REF } from './knowledge-base-tool';

const TODO_ASSISTANT_CHAT_AGENT_REF = 'todo-assistant.chat.agent';
const TODO_ASSISTANT_SYSTEM_REF = 'todo-assistant';
const readTask = resourceReadTool(TasksManager_ResourceType.TODOS);
const renameTask = resourceWriteTool(TasksManager_ResourceType.TODOS, CoreResourceOperation.UPDATE, {
  requiresHumanApproval: true,
  inputSchema: z.object({
    id: z.string().min(1).describe('Task id returned by the read tool.'),
    title: z.string().min(1).max(200).describe('The new title explicitly requested by the user.'),
  }),
});

The rename tool exposes only the record ID and new title. Its approval flag pauses that particular call; approval does not replace the operation’s access checks. Reusing the tools’ functionRef values below prevents a separate list of hand-typed names drifting away from the registry.

const todoAssistantChatAgent: FlowsActors_Agent = {
  ref: TODO_ASSISTANT_CHAT_AGENT_REF,
  displayName: 'Todo Assistant',
  status: FlowsActors_Agent_Status.ACTIVE,
  config: {
    providerRef: 'anthropic',
    model: LLM_Model.CLAUDE_SONNET_5,
    operationKey: LLMProvider_OperationKey.CHAT_COMPLETION,
    accessControl: [{ primaryScope: ResourcePrimaryScope.APPLICATION, requiresApproval: false }],
    riskLevel: ResourceOperationRiskLevel.LOW,
  },
  operationDefinition: {
    operationKey: LLMProvider_OperationKey.CHAT_COMPLETION,
    providerRef: 'anthropic',
    inputSchema: LLMProvider_ChatCompletionInputSchema,
    outputSchema: LLMProvider_ChatCompletionOutputSchema,
    operationContextSchema: LLMProvider_OperationContext_BaseSchema,
  } satisfies LLMProvider_OperationDefinitionBase,
  promptSpec: {
    role: 'Help the user understand policy documents and rename their tasks when asked.',
    skillType: FlowsActors_Agent_Skill_Type.CHAT,
    instructions: [
      `Use ${readTask.functionRef} to resolve an existing task before proposing a rename.`,
      `Use ${KNOWLEDGE_BASE_ASK_TOOL_REF} for policy questions. Read outcome and notes before answering.`,
      'For matched results, answer only from the returned passages and name their documents.',
      'For nothing-matched, say no relevant passages were found. For refused, explain access was refused; do not claim the information is absent.',
      'If notes report withheld or truncated material, explain that the answer covers only the returned material.',
      `Call ${renameTask.functionRef} only for an explicitly requested rename. Its approval request is the review step.`,
      'Report a rename as completed only after the tool returns a successful result.',
    ],
  },
  capabilities: {
    tools: { functionRefs: [readTask.functionRef, KNOWLEDGE_BASE_ASK_TOOL_REF, renameTask.functionRef], mcpRefs: [] },
  },
  createdAt: '2026-07-12T00:00:00.000Z',
};

The prompt gives the tools their conversational purpose. The tool schemas, execution context and operation checks enforce the application contract; instructions alone do not establish access control. A refused search and an empty search require different answers even though both can return no sources.

Connect an agent, a system and a view

A FlowsActors_Agent defines the model invocation and structured prompt. An ActorSystem gives that agent a frontend-visible identity. A frontend view points to the system; it does not duplicate the prompt or tool definitions.

This actor-system declaration follows Wonder Todos and points to the agent just declared:

const todoAssistantActorSystem: ActorSystem = {
  ref: TODO_ASSISTANT_SYSTEM_REF,
  displayName: 'Todo Assistant',
  description: 'Read tasks, explain policy passages and request reviewed task renames.',
  kind: FlowActorSystem_Kind.ACTOR,
  status: FlowActorSystem_Status.ACTIVE,
  visibility: FlowActorSystem_Visibility.FRONTEND,
  config: {
    timeout: 60000,
    accessControl: [{
      primaryScope: ResourcePrimaryScope.APPLICATION,
      requiresApproval: false,
    }],
    riskLevel: ResourceOperationRiskLevel.LOW,
  },
  actors: [{
    ref: 'assistant',
    displayName: 'Assistant',
    roleCategory: Actor_Role_Category.OPERATOR,
    executionMode: Actor_ExecutionMode.AGENTIC,
    agentRef: TODO_ASSISTANT_CHAT_AGENT_REF,
  }],
  createdAt: '2026-07-12T00:00:00.000Z',
};

FRONTEND makes the system discoverable by the view. AGENTIC and agentRef select the conversational agent; the system is not itself the prompt. Register the system factory, agent and tools on the backend module’s flowsActors contribution:

export const moduleBackend_FlowsActorsRegistry: {
  flowActorSystemsFactoryMap: FlowActorSystem_InitializationFactoryMap;
  agents: FlowsActors_Agent[];
  functionTools: FunctionTool[];
} = {
  flowActorSystemsFactoryMap: { [TODO_ASSISTANT_SYSTEM_REF]: () => todoAssistantActorSystem },
  agents: [todoAssistantChatAgent],
  functionTools: [readTask, knowledgeBaseAskTool, renameTask],
};

Mount the registry on the owning backend module. This is the relevant composition in backend-api/src/modules/tasks-manager/index.ts; retain the module’s other contributions:

import type { BackendDomainModule } from '@wildo-ai/saas-backend-lib';
import resourcesModule from './resources';
import { moduleBackend_FlowsActorsRegistry } from './addons/flows-actors';

const backendModule: BackendDomainModule = {
  ...resourcesModule,
  flowsActors: moduleBackend_FlowsActorsRegistry,
};

That module must remain in the application’s backend module registry. Exporting an agent file alone does not make it available. The frontend view names todo-assistant, the system names todo-assistant.chat.agent, and that agent names exactly the three registered function tools.

Connect a policy question to the knowledge operation

Wonder Todos’ adjacent knowledge-base-tool.ts owns knowledgeBaseAskTool and KNOWLEDGE_BASE_ASK_TOOL_REF. Its model-facing input contains a question and optional passage limit; identity comes from the conversation. These selected declarations show the tool’s entry contract; the execution body follows separately.

import { z } from 'zod';
import type { FunctionTool, FunctionToolExecutionContext } from '@wildo-ai/saas-backend-lib';
import { KnowledgeDocuments_Operations, TasksManager_ResourceType, type AskKnowledgeBaseResponse } from '@wonder-todos/shared-lib';

export const KNOWLEDGE_BASE_ASK_TOOL_REF =
  `resource.${TasksManager_ResourceType.KNOWLEDGE_DOCUMENTS}.${KnowledgeDocuments_Operations.ASK}`;

const knowledgeToolContract: Pick<FunctionTool, 'functionRef' | 'description' | 'inputSchema'> = {
  functionRef: KNOWLEDGE_BASE_ASK_TOOL_REF,
  description: 'Search readable policy documents. Read outcome and notes; answer from attributed passages.',
  inputSchema: z.object({
    question: z.string().min(3).max(1_000),
    limit: z.number().int().min(1).max(25).optional(),
  }),
};

Inside execute(args, ctx), the reference implementation resolves the declared ASK operation and reconstructs its context from verified authentication. These are the actual dispatch steps, with explanatory comments shortened:

const { resourcesRegistry, servicesRegistryHandler, executionContextCreator } = ctx.services;
const askOperation = resourcesRegistry.getOperationFromPath(
  resourcesRegistry.getServiceOperationPathDefault(
    TasksManager_ResourceType.KNOWLEDGE_DOCUMENTS,
    KnowledgeDocuments_Operations.ASK,
  ),
);

const contextIds: Record<string, string> = ctx.organizationId ? { organizationId: ctx.organizationId } : {};
const executionContext = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, askOperation, contextIds);

const answer = await servicesRegistryHandler.executeCustomOperation<AskKnowledgeBaseResponse>(
  TasksManager_ResourceType.KNOWLEDGE_DOCUMENTS,
  KnowledgeDocuments_Operations.ASK,
  executionContext,
  undefined,
  { question: args.question, ...(args.limit !== undefined && { limit: args.limit }) },
);

ASK is a collection operation, so there is no record ID in this dispatch. The operation invokes retrieval with this execution context and projects its response. Context construction is not operation admission: this handwritten reference tool calls the service directly, whereas the generic read/write tool factories explicitly run authorization and operation-rate policy checks first. A custom tool needs those checks at its dispatch boundary; executeCustomOperation does not supply controller-equivalent admission by itself.

Preserve what the search actually established

The ASK operation returns passages and their provenance, plus refusal, withheld-row and truncation information. The tool projects that into the model’s result. These selected steps follow the reference tool’s result handling:

const sources = answer.sources.map(source => ({
  knowledgeDocumentId: source.knowledgeDocumentId,
  header: source.header,
  contextText: source.contextText,
}));
const withheldRows = answer.droppedUnreadableRows + answer.droppedByReadFailure;
const notes: string[] = [];
if (withheldRows > 0) notes.push('Some matching documents were withheld; the answer is partial.');
if (answer.reachedContextCharacterBudget) notes.push('The matched text reached the context budget; narrow the question.');
if (sources.length === 0 && answer.refusedResourceTypes.length > 0) {
  notes.push('Search was refused; this does not establish that the information is absent.');
} else if (sources.length === 0) {
  notes.push('No matching passages were found; do not substitute an unsupported answer.');
}
return {
  question: answer.question,
  mode: answer.mode,
  sources,
  outcome: sources.length > 0
    ? 'matched'
    : (answer.refusedResourceTypes.length > 0 ? 'refused' : 'nothing-matched'),
  notes,
};

contextText retains the framing that associates passages with their document. mode distinguishes hybrid from lexical-only retrieval; lexical-only is a supported result. The agent’s instructions above consume outcome and notes instead of treating every empty result as proof that no policy exists. The returned text becomes input to the conversational model, which can explain it and name its sources; a later rename follows the separate approval-gated resource tool.

What happens during a turn

The browser continues a discussion by reusing its executionId. It sends the new message; the server loads previous turns. Owner, credential and agent-instance fields remain part of the persistence lookup rather than trusting an identifier by itself.

Use the streaming conversational path for tool-using chat. The buffered one-shot invocation is a different contract: declared function tools do not execute there. Coding sessions also have their own progress events rather than this token-delta channel.

resourceReadTool supplies a bounded lookup. resourceWriteTool covers creating or updating one record and takes the model-facing input schema you author. Import both from @wildo-ai/saas-backend-lib; use your application’s resource enum rather than copying a string from an example.

This excerpt follows Wonder Todos’ lookup and update tools, with a reduced set of editable fields. It preserves the update’s human approval gate:

const functionTools = [
  resourceReadTool(TasksManager_ResourceType.TODOS),
  resourceWriteTool(TasksManager_ResourceType.TODOS, CoreResourceOperation.UPDATE, {
    requiresHumanApproval: true,
    inputSchema: z.object({
      id: z.string().min(1)
        .describe('Id of the todo to update. Resolve it with the read tool.'),
      title: z.string().min(1).max(200).optional()
        .describe('New title, if the user asked to rename it.'),
      status: z.enum(Todos_Status).optional()
        .describe('New status.'),
    }),
  }),
];

requiresHumanApproval: true pauses the proposed update for review before execution. Approval does not replace the operation’s authorization: the person must still be allowed to update that record.

The id addresses the existing record; the remaining fields become the patch. Do not include ownership fields or identity in this schema. The factory reconstructs execution context from verified authentication and the active organization.

Register these tools under the backend module’s flowsActors.functionTools, then list their exact references on the agent:

capabilities: {
  tools: {
    functionRefs: [
      `resource.${TasksManager_ResourceType.TODOS}.read`,
      `resource.${TasksManager_ResourceType.TODOS}.${CoreResourceOperation.UPDATE}`,
    ],
    mcpRefs: [],
  },
},

This is a fragment of the registered agent declaration. The model only receives registered tools selected by its references. A tool declaration elsewhere in a module does not grant it automatically to every agent.

Preserve the operation’s behavior

The shared dispatch path resolves the public operation, checks authorization, charges its declared rate limit and then invokes the service pipeline. Updates authorize the same record identifier they dispatch. The result is projected through the operation’s response contract before it reaches the model.

A read uses search when a query is supplied and an exposed search operation is available, otherwise list. Authorization and rate-limit refusals are not converted into a successful list fallback. The default lookup is bounded; this is not an unrestricted dataset export.

For a custom tool, use the shared resource-operation dispatch contract and an explicit response projection. Calling a service directly does not automatically reproduce controller-boundary authorization and rate limits. Prompt instructions describe intended use; they do not replace those checks.

Keep local and external tools distinct

functionRefs selects registered local tools. mcpRefs selects configured external MCP servers whose tools are discovered at turn start. External calls use their server connection and credential policy; they do not become local resource operations merely because the same assistant calls them.

An unavailable external server contributes no tools to that turn and the runtime logs the reason. This avoids showing the model tools that could not be discovered, while allowing the conversation to continue with the available set.

The gate is declared on the callable tool, not in prompt prose. This application excerpt keeps the update schema narrow and enables the gate:

resourceWriteTool(TasksManager_ResourceType.TODOS, CoreResourceOperation.UPDATE, {
  requiresHumanApproval: true,
  inputSchema: z.object({
    id: z.string().min(1)
      .describe('Id of the todo to update. Resolve it with the read tool.'),
    title: z.string().min(1).max(200).optional()
      .describe('New title, if requested.'),
    description: z.string().max(1000).optional()
      .describe('New description or notes.'),
    status: z.enum(Todos_Status).optional()
      .describe('New status.'),
  }),
})

Register this tool on the backend module and include its generated resource.<type>.update reference in the agent’s functionRefs. The agent invokes it normally; the runtime intercepts the call before executing its effect.

Follow the decision through the application

The default approval window is 24 hours. Expiry is checked when a decision is used; do not treat it as a separate background timeout workflow. Approval signatures derive from the provisioned application primary secret, so an unsigned fallback is not part of the contract.

Compose review into a custom surface

The standard host already places approval beside the active conversation. A custom screen can use FlowsActors_ApprovalRequest within the existing flows-actors context:

function ConversationDecision({ executionId }: { executionId: string }) {
  return (
    <FlowsActors_ApprovalRequest
      executionId={executionId}
      allowArgumentModification={false}
    />
  );
}

The wrapper obtains the pending decision and response function from context. This example chooses read-only arguments; its default supports modification. FlowsActors_ApprovalQueue serves a different placement: outstanding decisions across conversations.

A machine principal that cannot provide the required human decision is refused at the gate. Approval does not override authorization, and a stale decision cannot approve a different pending call.

A FlowsActorsViewDefinition references one registered system through singular systemRef. This current Wonder Todos declaration creates an addressable application-level view:

const flowsActorsViewsConfig: FlowsActorsViewDefinition[] = [{
  ref: 'todo-assistant-view',
  scope: FrontendView_ScopeMode.APPLICATION,
  isAddressable: true,
  operationLike: CoreResourceOperation.READ,
  primaryScope: ResourcePrimaryScope.ORGANIZATIONS,
  systemRef: 'todo-assistant',
  layoutPreset: 'Default',
}];

Import the view contract and scope enum from @wildo-ai/saas-frontend-lib/companion, and the resource enums from @wildo-ai/saas-models. Contribute the array through the frontend module’s flowsActorsViews; a launcher references todo-assistant-view. The backend must register the corresponding FRONTEND-visible actor system. A string match between these references is the connection between the screen and runtime.

Choose the level of composition

Available elements do not all appear automatically in the standard host. For example, a citation component needs citation data and placement in a screen; declaring an assistant does not create a citation panel. A graph display similarly does not execute a flow.

Keep decisions attached to the conversation

The host renders FlowsActors_ApprovalRequest with the active execution identifier. The wrapper gets the pending arguments and response action from context; it does not establish a second decision channel. Custom surfaces can use that wrapper beside their own messages or use a queue for decisions elsewhere.

The host loads persisted history when the user or system changes and continues a thread using its existing executionId. This is distinct from rendering the transient streamed answer; both need to refer to the same discussion.

FlowActorSystem separates ActorSystem and FlowSystem using kind. An actor system contains actors; a flow system contains its graph. Do not parse either through the shared base shape and assume the kind-specific fields are retained.

function describeSystem(system: FlowActorSystem) {
  if (system.kind === FlowActorSystem_Kind.ACTOR) {
    return {
      ref: system.ref,
      actorCount: system.actors.length,
    };
  }
  return { ref: system.ref, kind: system.kind };
}

This is a type-narrowing example, not a flow runner. The shared union is currently type-only because the flow trigger and step unions do not have a complete runtime validation schema.

Keep modeling and execution distinct

The flow service reports a configuration error rather than marking unexecuted work complete. Do not wire a production process to this entry point on the strength of the graph types alone. For an in-app assistant, declare an actor system and use the conversational path described alongside this capability.

Add mcp to an existing resource operation variant. This selected task-resource configuration shows exposure beside the operation’s route variant and role requirement:

operationsConfiguration: {
  [CoreResourceOperation.READ]: {
    variants: [
      {
        variantType: ResourceOperationVariantType.API_CALL,
        isDefault: true,
        roles: [CORE_ORG_ROLES.ORG_MEMBER],
        riskLevel: ResourceOperationRiskLevel.LOW,
        mcp: {
          exposed: true,
          description: 'Fetch a single task by its id, including its title, status, priority, and assignee.',
        },
      },
    ],
  },
},

This belongs inside the existing resource factory declaration, which supplies resource identity and schemas; keep its current imports and other operations. It is not a separate server implementation.

The adapter composes the tool name from resource and operation identifiers and derives its input schema. It advertises collection query arguments using the operation’s allowed filters rather than inventing an independent search contract.

Discover before calling

Use an authenticated MCP client against the deployment’s /mcp endpoint. Request tools/list, then use the returned tool name and inputSchema when constructing tools/call. This JSON-RPC body illustrates a discovered read tool; replace the record ID with a task accessible to the caller:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "tasks__read",
    "arguments": { "taskId": "accessible-task-id" }
  }
}

The client supplies transport headers appropriate to its negotiated revision and a Bearer token issued for that MCP audience. A name in the catalogue is discovery information, not a grant of authority. Dispatch resolves the operation again, authorizes the caller and uses the service layer.

Interpret results at the right level

A successful invocation returns the operation result inside the MCP response. Collection results preserve their pagination shape. Field-validation and business-rule failures can become actionable tool errors; authentication failures remain authentication signals so the client can repair its credentials. Build the integration around the advertised schema, including any value envelope, rather than guessing from a REST example.

The operation’s own declared rateLimit policy also runs on MCP dispatch, keyed to the verified credential in a separate MCP bucket. The transport’s blanket principal throttle is additional; it does not replace that authored policy.

The backend assembly accepts resourceServerInstances. This excerpt is adapted from Wonder Todos’ existing declaration:

const resourceServerInstances: ResourceServerInstance[] = [
  {
    ref: 'support',
    kind: ResourceServerKind.MCP,
    displayName: 'Support',
    description: 'Tools for looking up records.',
  },
  {
    ref: 'concierge',
    kind: ResourceServerKind.A2A,
    displayName: 'Concierge',
    description: 'An agent for application questions.',
    actorSystemRefs: ['todo-assistant'],
  },
];

Use the existing backend bootstrap imports for ResourceServerInstance and ResourceServerKind, and pass this array in its resourceServerInstances field. The actor reference must resolve to an exposable system registered by the application.

Assign operations to their tool server

On each selected operation, use mcp: { exposed: true, servers: ['support'], description: '…' }. Explicit membership is exclusive: that operation leaves the default /mcp catalogue and belongs to /mcp/support. An operation without named membership stays on the default surface.

For A2A, actorSystemRefs narrows the skills on the named agent card. An unresolved instance or system reference must not broaden the selection to the default catalogue.

Predict the default and named catalogues

A registered ACTOR system with an AGENTIC actor and an agentRef is eligible for the default A2A card. Giving concierge an actorSystemRefs list selects from those systems; it does not remove them from the default agent. Omitting that list on a named agent exposes all eligible systems on that named card. An unknown instance does not fall back to the default.

For the declarations above, assume todo-assistant is registered and a read operation is explicitly exposed with servers: ['support']:

Naming curates MCP membership exclusively, while A2A naming adds a separately addressed selection. Card or catalogue membership is still different from permission to invoke a business operation.

Obtain credentials for the intended address

Use the published instance audience when requesting a token, then call that instance. Audience matching confines an issued token; it does not decide which audiences a registered client is allowed to request. Use roles to deny business operations, and named instances to curate discovery and separate issued credentials.

mcp.exposed opts an operation in. Eligibility also depends on a reachable resource scope, a default URL-bearing operation, a usable tool name, no unimplemented acknowledgement, and membership in the addressed server.

This selected implementation excerpt shows the invocation-side conditions after resolving the resource and checking the composed name:

return config.operations.find(
  (operation) =>
    String(operation.operationIdentifier) === operationIdentifier
    && isDefaultUrlBearingOperation(operation, String(operation.operationIdentifier))
    && this.isMcpExposed(operation)
    && !this.isAcknowledgedUnimplemented(operation)
    && this.isOnMcpServerInstance(operation, instanceRef),
);

Check discovery and invocation together

When changing an operation’s exposure or implementation acknowledgement, verify both tools/list and a direct tools/call using its previous name. Absence from the catalogue alone does not prove that invocation was withdrawn.

The adapter also checks the composed resource/operation tool name against its accepted naming grammar. A malformed name is omitted rather than making every other tool unusable to a strict client. These eligibility checks concern whether the tool can be offered; the caller’s roles are still checked when executing it.

Configure the application endpoint and the token audience in your MCP client. Its negotiated revision determines the required request metadata and response envelope; do not add one newest-version header policy to every caller.

The current implementation names its served revisions in MCP_SUPPORTED_PROTOCOL_VERSIONS:

export const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = [
  '2026-07-28',
  '2025-11-25',
  '2025-06-18',
  '2025-03-26',
];

This is the local implementation’s supported set, not a claim about future versions or independently certified conformance.

Follow the negotiated handshake path

For the locally supported 2025-06-18 path, send this body to the MCP endpoint with Content-Type: application/json and Accept: application/json. Initialization is public; tool discovery and calls still need the caller’s token.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "integration-example", "version": "1.0.0" }
  }
}

For that supported request, the controller returns:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "wildo-mcp", "version": "1.0.0" }
  }
}

Check the returned revision, then send {"jsonrpc":"2.0","method":"notifications/initialized"} without an ID. The endpoint accepts this notification with HTTP 202 and no response body. Subsequent requests carry MCP-Protocol-Version: 2025-06-18; authenticated discovery adds the audience-bound Bearer token. A supported requested revision is echoed; an unsupported request can receive another served revision, which the client must check before continuing.

Declare the stateless revision on each request

The local 2026-07-28 path uses per-request metadata instead. After discovering support with server/discover, this example asks for the caller’s tools. Replace the address and token with the chosen endpoint and its credential:

POST /api/v1/mcp HTTP/1.1
Host: application.example.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer <endpoint-access-token>
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/list

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}

The header revision mirrors the body metadata, and Mcp-Method mirrors the method. For tools/call, also send Mcp-Name matching the discovered params.name. Mismatches are rejected before dispatch. Stateless success results carry resultType: "complete"; tools/list also carries cache hints appropriate to its caller-specific catalogue. Those fields do not belong to the older handshake example above.

An anonymous tools/list request is challenged rather than receiving the authenticated catalogue. Public transport discovery does not authorize tool use. These exchanges describe the local controller’s served paths, not an independent protocol-conformance result.

Keep version selection distinct from authorization

The controller separates a declared revision from the default used to interpret an undeclared request. Handshake negotiation chooses a compatible handshake-era response. Its stateless path validates per-request revision and method metadata.

Use an MCP client to manage these details instead of reproducing the transport in product code. The server is a tools surface; protocol compatibility does not imply support for every optional MCP feature.

The agent card advertises the application’s eligible actor systems as skills. A named agent can narrow that list. The caller selects a skill with metadata.skillId; when exactly one is exposed, the resolver can choose it without that field. Unknown skill references are rejected rather than spending a model turn on a fallback.

Send a message under the right identity

This adapted example follows the application’s delegated-write probe. Set agentUrl to the published A2A endpoint and token to a Bearer token issued for that audience. contextId is optional on the first turn:

async function sendMessage(
  agentUrl: string,
  token: string,
  text: string,
  contextId?: string,
  skillId?: string,
) {
  const message = {
    role: 'user',
    parts: [{ kind: 'text', text }],
    ...(contextId ? { contextId } : {}),
    ...(skillId ? { metadata: { skillId } } : {}),
  };
  const response = await fetch(agentUrl, {
    method: 'POST',
    headers: { 'content-type': 'application/json', Authorization: `Bearer ${token}` },
    body: JSON.stringify({
      jsonrpc: '2.0', id: 1, method: 'message/send',
      params: { message },
    }),
  });
  return { status: response.status, body: await response.json() };
}

Retain contextId to continue the conversation. A task’s id addresses work you can poll or reattach to; a conversation context alone is not a task handle.

Choose how the caller follows the work

These are the supported 0.2.5 method and state spellings. Other supported dialects project the corresponding names. A stream attached to an existing task is different from a direct message stream: closing that subscription does not cancel the underlying task.

Ask for an addressable task

This request follows the application’s a2a-resubscribe.e2e.ts probe. Send it to the same audience-bound agentUrl with the authenticated headers shown above. The message and identifiers are illustrative; select an actual skill from the card when several are exposed.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "kind": "text", "text": "Summarize the records I can access." }]
    },
    "configuration": { "blocking": false }
  }
}

A successfully opened task returns this shape. Values below are illustrative, not a recorded execution:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "kind": "task",
    "id": "task-id-returned-by-the-server",
    "contextId": "conversation-id-returned-by-the-server",
    "status": { "state": "working", "timestamp": "2026-09-11T12:00:00.000Z" }
  }
}

Check both JSON-RPC errors and the returned result kind. If nonblocking task creation fails, this transport falls back to a blocking reply; never treat a message’s ID as a task ID. If an approval pause cannot create its task, the transport returns an error instead.

With a returned task ID, send tasks/get with params: { id: taskId }, or follow task updates and reattachment. Reattachment supplies current and future state, not a replay of every missed text delta. An approval pause uses the same task shape with status.state: "input-required"; approval itself remains in the application.

Distinguish conversation ownership from permission

The verified token determines the execution principal and owner scope. The client’s text cannot grant a different tenant identity. Operations reached during the turn continue through the application’s service and authorization contracts.

A delegated user can reach behavior available to that user; a machine caller has its own principal. Approval-required actions may pause the work for a decision. Your actor system defines its instructions and tools; the protocol supplies the external conversation and task transport.

Choose skillId from the addressed agent card whenever it exposes several skills. It can be omitted when exactly one eligible actor system is exposed. Keep the same intended skill when continuing a conversation.

The implementation distinguishes its 0.2.5 and 1.0 dialects from method names. These two request bodies illustrate the same task lookup; use a task owned by the authenticated caller:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tasks/get",
  "params": { "id": "owned-task-id" }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "GetTask",
  "params": { "id": "owned-task-id" }
}

Both examples need the published agent URL and a Bearer token for that audience. The exact request fields accepted by a client SDK should follow its dialect; the transport normalizer adapts them before service dispatch.

Start work without waiting for the answer

These paired examples follow Wildo’s dialect normalizer and task projection. POST either body to the published agent URL with Content-Type: application/json and a Bearer token for that endpoint audience. The messages are alternatives, not two steps of one turn. They select the published todo-assistant skill; replace metadata.skillId with a skill ID from the chosen card. A card exposing several skills requires an explicit selection.

Earlier vocabulary, requesting a nonblocking turn:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "message/send",
  "params": {
    "message": { "role": "user", "messageId": "request-10", "parts": [{ "kind": "text", "text": "Summarize my current tasks." }] },
    "metadata": { "skillId": "todo-assistant" },
    "configuration": { "blocking": false }
  }
}

Representative successful task creation response; IDs and timestamp are illustrative:

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "kind": "task",
    "id": "task-10",
    "contextId": "conversation-10",
    "status": { "state": "working", "timestamp": "2026-09-12T09:00:00.000Z" }
  }
}

Later vocabulary expresses the same choice with an inverted flag:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "SendMessage",
  "params": {
    "message": { "role": "user", "messageId": "request-11", "parts": [{ "kind": "text", "text": "Summarize my current tasks." }] },
    "metadata": { "skillId": "todo-assistant" },
    "return_immediately": true
  }
}

The response retains the task shape while changing the state vocabulary:

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "kind": "task",
    "id": "task-11",
    "contextId": "conversation-11",
    "status": { "state": "TASK_STATE_WORKING", "timestamp": "2026-09-12T09:00:00.000Z" }
  }
}

Keep the returned task ID for tasks/get or GetTask; contextId identifies the conversation, not the task. Subsequent lookups may report completion, failure or an input request. The local normalizer also accepts returnImmediately for the later flag.

Task creation can fail: this implementation then falls back to a blocking message reply. Check result.kind before starting a task-following loop. A direct message stream is a different path and normally returns message frames; an approval pause can materialize a task. Use the task follow-up example when you have received a task.

Translate the whole exchange

The boundary maps method names, task-state spelling and non-blocking configuration, then serializes replies for the detected dialect. Merely renaming the request method would leave a client misreading the response.

Not every operation has a counterpart in both dialects: the implementation’s task listing is a later-dialect operation. Read the published agent card and use a compatible client rather than assuming a one-to-one replacement for every method.

Start a nonblocking turn using the paired request and response example. Continue only when result.kind is task; save result.id and keep using the same endpoint and authenticated owner. The following bodies use illustrative task-10 from that example. Substitute the actual returned ID.

POST this request with Accept: text/event-stream and the same audience-bound Bearer token:

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tasks/resubscribe",
  "params": { "id": "task-10" }
}

The stream first reports the task’s current state, then follows subsequent changes. It does not reconstruct missing token history. An already terminal task can be reported and the stream closed immediately. The later method name is SubscribeToTask. Every task frame uses the requested method’s state vocabulary: tasks/resubscribe retains lowercase states; SubscribeToTask uses TASK_STATE_*, consistently with GetTask. This applies to the initial task and each subsequent update.

Choose a stream or a callback

An existing task can be followed with tasks/resubscribe using its ID and the caller’s authenticated identity. Reattachment returns the current state and follows subsequent changes; it is not a replay of every token emitted while disconnected.

For push delivery, first obtain an owned task ID and a publicly reachable HTTPS webhook. This request body follows the application’s push-notification probe:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tasks/pushNotificationConfig/set",
  "params": {
    "taskId": "task-10",
    "url": "https://integration.example.com/agent-updates",
    "authentication": {
      "scheme": "Bearer",
      "credentials": "callback-secret"
    }
  }
}

Send it to the agent endpoint with its audience-bound token. Store the returned configuration ID to inspect or remove this callback later. Secrets are not echoed in configuration responses.

Read a callback as a status update

A registered callback observes later task transitions; registering after completion does not replay an earlier transition. This representative body follows the current push payload builder. Its timestamp and identifiers are illustrative:

{
  "statusUpdate": {
    "taskId": "task-10",
    "contextId": "conversation-10",
    "status": { "state": "completed", "timestamp": "2026-09-12T09:00:05.000Z" },
    "final": true
  }
}

This HTTP callback body is a status event, not a JSON-RPC result or the generated answer. The dispatcher currently uses canonical lowercase task states for push delivery. Authenticate the configured callback credential, then read the task through the agent endpoint to reconcile its current status. A successful nonblocking turn stores its reply as task output, exposed as a text artifact on the completed task. An authorized task lookup or task subscription returns that artifact; the status-only callback does not carry the reply. Cancellation and approval pauses do not publish a successful result. Do not apply the request-dialect state projection to this payload by assumption.

Treat callback delivery as an external request

The outbound target guard checks the callback address; delivery rechecks its destination rather than trusting only the original registration. Literal private addresses and prohibited host shapes are refused, and redirects are not followed. This path does not pin DNS resolution to the connection, so deployment egress controls must cover hostnames that resolve into private networks. Use a receiver that authenticates the configured credential and handles repeated delivery safely.

Delivery records and retry processing make failures inspectable. A receiver outage does not turn a callback into proof that the underlying task failed. Inspect the task separately when reconciling progress.

Send this body to the A2A endpoint with the task owner’s authorized token:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tasks/cancel",
  "params": { "id": "owned-task-id" }
}

The task must belong to the caller’s permitted scope. Cancellation broadcasts the task ID through Redis; the replica holding that task’s local AbortController reacts. This reaches the running model/tool loop instead of merely closing the caller’s text stream.

Keep liveness evidence separate

While executing a turn, its replica refreshes a lease. The mechanism also records that lease establishment succeeded. The abandoned-task sweep considers corroborating evidence before persisting an abandonment verdict: an unreadable lease store is not proof that the worker died.

Run the deployment’s Redis and batch infrastructure for the cross-replica and cleanup behavior. Cancellation is cooperative; it does not promise rollback of business operations already completed. Inspect the returned task state and any completed side effects rather than treating a stop request as transactional undo.

The engine derives an upload-grant tool for each user-uploadable file field on an exposed create or update operation. Generated-document fields do not acquire a user upload tool. No second hand-authored MCP operation is needed.

Discover the derived name and its schema in tools/list. Supply the existing record ID for an update, and optionally the declared name, MIME type, size and requested lifetime. These file facts let the engine reject an impossible upload before issuing a link.

Request, transfer, then save

Reuse the discovered contracts

In an initialized, authenticated MCP client, first call tools/list and select the derived grant tool for the intended field and its parent UPDATE tool. Use the actual names and record-ID property from those descriptors. This illustrative client function takes those selections as arguments; it does not assume a universal tool name or an id field.

async function requestFileHandoff({ client, grantTool, grantArguments }) {
  const decode = (response) => {
    if (response.isError) throw new Error('MCP tool refused the request');
    if (response.structuredContent !== undefined) return response.structuredContent;
    const text = response.content.find((item) => item.type === 'text')?.text;
    if (!text) throw new Error('MCP tool returned no JSON result');
    return JSON.parse(text);
  };
  const grant = decode(await client.callTool({
    name: grantTool.name,
    arguments: {
      ...grantArguments,
      expiresInMinutes: 10,
    },
  }));

  return {
    uploadPageUrl: grant.uploadPageUrl,
    uploadCommand: grant.uploadCommand,
    async finish({ parentTool, parentArguments, fieldName, multiple }) {
      const response = await fetch(grant.statusUrl);
      if (!response.ok) throw new Error(`Status HTTP ${response.status}`);
      const status = await response.json();
      if (status.state !== 'redeemed' || !status.file?.fileId) {
        throw new Error('Wait for the file upload before saving');
      }
      const value = {
        ...(multiple ? { fileIds: [status.file.fileId] } : { fileId: status.file.fileId }),
        updatedAt: new Date().toISOString(),
      };
      return decode(await client.callTool({
        name: parentTool.name,
        arguments: { ...parentArguments, [fieldName]: value },
      }));
    },
  };
}

For an UPDATE, both grantArguments and parentArguments must identify the same record using the property advertised by their tool schemas. fieldName and multiple come from the declared file field and parent input schema. Supply any other required parent arguments. The example replaces that field with one file; preserve existing IDs for an append workflow.

Show the returned page to the person, or follow the returned upload command locally. Call finish only after the upload; a pending result is a reason to wait, not to save an invented ID. Scanning and the ordinary parent write can still refuse attachment. The shared upload recipe shows the actual multipart transfer, status response and final record read-back. Keep token-bearing handoff/status URLs out of logs.

The public upload origin comes from backend configuration. Configure that public URL correctly so the returned links can be reached outside the server. The grant authorizes one upload to the selected field; it does not replace the parent operation’s permission check. If it expires, request a new grant rather than fabricating a file ID.

The token-budget feature already exists in Wildo. Grant an allowance on an existing organization or user plan instead of declaring the feature again. This adapted excerpt belongs in that plan’s ProductDefinition in the application’s shared product catalog; preserve its other grants and pricing fields:

import {
  A2A_TOKEN_BUDGET_FEATURE_ID,
  LimitGrantMode,
} from '@wildo-ai/saas-models';

// Within the existing ProductDefinition:
grantedLimits: {
  [A2A_TOKEN_BUDGET_FEATURE_ID]: { value: 100_000, mode: LimitGrantMode.SET },
},

This example grants 100,000 tokens for the tenant’s UTC calendar month. The amount is an illustrative application decision, not Wildo’s default. The plan must be active for the tenant through the normal product/billing configuration. Other applicable grants, profiles and overrides participate in feature resolution, so inspect the tenant’s effective limit when verifying the result. Application scope uses a feature profile or manual override because it has no plan billing rail.

Understand when admission is checked

The service resolves the live allowance and reads accumulated consumption before a turn. After consumption is known, it records those tokens against the tenant’s UTC calendar month. This selected gate is the comparison, not a precharge:

if (consumedTokens >= allowanceTokens) {
  return { kind: 'over_budget', reason: A2ATokenBudgetDenialReason.ALLOWANCE_EXHAUSTED, allowanceTokens, consumedTokens };
}
return { kind: 'ok' };

An exhausted budget refuses further turns. Already-running turns can complete and add usage beyond the threshold; this is not an exact dollar ceiling or a single-turn maximum overrun.

Distinguish the three counting rules

The blanket throttle uses server-verified identity, not an identifier supplied in a prompt. A delegated user has a user bucket; organization-owned machine clients share the organization bucket. A separately declared operation policy can distinguish those machine credentials, while the blanket owner throttle still applies.

Keep the failure policies distinct

The owner-based burst throttle allows requests through if its limiter storage fails. It complements the budget but does not reserve future tokens. Use model-call telemetry to observe actual consumption and investigate metering failures.

Enable the observability capability and select its provider in the runtime scope that makes the model calls. These excerpts adapt Wonder Todos’ configuration; they belong in three existing sections of wildo.saas.config.ts:

// In engineCapabilities:
[EngineCapability.LLM_OBSERVABILITY]: { enabled: true },

// In the runtime scope's providers:
posthog: {
  engineCapabilities: [EngineCapability.LLM_OBSERVABILITY],
  providerCapabilities: ['LLM_OBSERVABILITY'],
  protocols: [],
},

// In the same scope's selection:
[EngineCapability.LLM_OBSERVABILITY]: {
  primary: 'posthog',
  whenUnavailable: [],
},

Supply the provider’s POSTHOG_PROJECT_API_KEY through runtime secret configuration and install its declared posthog-node dependency in that runtime. POSTHOG_HOST selects the provider endpoint when needed. Observability has no request/response exchange protocol here; its provider supplies a trace sink.

Author content capture and sampling in the environment’s infrastructure configuration. This illustrative fragment keeps content capture off and requests all calls; it is separate from the provider declaration and the OTLP activation switch:

observability: {
  llmObservability: {
    captureContent: false,
    sampleRate: 1,
  },
},

Configuration synchronization projects this policy into the executing process’s environment. The following shows its generated result, not a file to maintain by hand:

# WILDO_LLM_OBS_CAPTURE_CONTENT is omitted; capture defaults to false.
WILDO_LLM_OBS_SAMPLE_RATE=1

The absent capture flag keeps prompts and completions out of provider capture; 1 requests no deliberate sampling drop. Delivery still remains best effort. Local structured-log content is separately gated by AgentTraceabilityLevel.DEBUG_VERBOSE; turning on provider capture does not change that logger policy.

Understand the inherited trace

Trace sinks consume AgentCallTraceEmission. The built-in logger extracts usage, duration and outcome from that envelope. This selected implementation excerpt shows ordinary metadata and the separate verbose-content gate:

this.logger.info('agent-call-trace', {
  agentRef: trace.agentRef,
  outcome: trace.outcome,
  ...(trace.attempt ? { attempt: trace.attempt } : {}),
  ...(trace.context?.usage ? { usage: trace.context.usage } : {}),
  ...(trace.context?.executionTime != null ? { executionTimeMs: trace.context.executionTime } : {}),
  ...(trace.context?.finishReason ? { finishReason: trace.context.finishReason } : {}),
  ...(trace.error ? { error: trace.error } : {}),
  ...(context?.attributes ? { attributes: context.attributes } : {}),
  ...(verbose ? { input: trace.input, output: trace.output } : {}),
});

verbose is determined from the resolved AgentTraceabilityLevel.DEBUG_VERBOSE policy. Selecting richer trace content is a deliberate policy decision, not a prerequisite for token and latency metadata.

Add a provider when you need aggregation

The observability sink resolves the configured provider lazily. The PostHog implementation accepts sampling and a separate captureContent choice; content capture starts off. Its runtime client is an optional dependency required where that provider actually executes.

Generation and embedding records differ. Generation usage includes prompt and completion tokens; embeddings summarize input use and vector dimensions. Raw embedding vectors are excluded from analytics even when content capture is enabled.

Use telemetry for observation

Composite sinks isolate failures and flush children during shutdown. A failed analytics sink should not fail the model call it observes. Sampling and best-effort delivery mean provider records are operational signals, not a complete accounting ledger. Budgets are enforced by the separate admission mechanism, not by the existence of a telemetry event.

These commands run from the Wildo repository root against the running Wonder Todos development stack. They invoke the complete scenarios, including helpers that the excerpt below relies on:

pnpm --dir examples/wonder-todos exec tsx e2e/mcp-hostile.e2e.ts
pnpm --dir examples/wonder-todos exec tsx e2e/a2a-hostile.e2e.ts

Use a disposable test deployment. The runners provision organizations and users, seed OAuth clients and records, attempt reads and writes, inspect stored effects and clean up their fixtures. They are not read-only probes.

e2e/wt-config.ts resolves endpoints through the testing environment contract and local defaults. Infrastructure credentials come from the configured WILDO_E2E_* inputs or the running stack’s gitignored .env.wildo-platform; fixture helpers own the disposable users and OAuth clients. Keep those values outside the website and result report. Pointing only the HTTP URL at another application does not adapt its resource names, fixture model or backing-store configuration.

The related a2a-dialects.e2e.ts, a2a-resubscribe.e2e.ts, a2a-push-notifications.e2e.ts and a2a-approval-hostile.e2e.ts scenarios use the same pnpm --dir examples/wonder-todos exec tsx e2e/<file> entry pattern. Callback-delivery acknowledgement additionally needs a reachable receiver admitted by the outbound-address policy; a registration or delivery attempt alone is not proof that it arrived.

Record what the run proved

Record the application/deployment, source revision, addressed endpoint/instance, scenario command, positive controls and storage effects. A failure to reach the endpoint or provider is an unexecuted scenario, not a passed refusal test. Independent client verification remains tracked in #6 for MCP and #7 for A2A.

MCP can assert directly on a tool response. A2A is model-mediated: a safe final answer does not establish that the model attempted the prohibited call. Inspect attempted-tool evidence and the resulting storage effects. An own-record control proves the model can use the tool; it does not prove it tried the foreign-record action as well.

Pair refusal with a working control

A refused call could mean the tool was unavailable. The MCP hostile scenario first proves the addressed surface can serve the caller’s own row, then targets a foreign row with the same token. This selected test excerpt uses the lane’s existing rpc, check and disclosesId helpers:

const ownRead = await rpc('tools/call', { name: 'todos__read', arguments: { todoId: aTodoId } }, tokenASupport, 'support');
check('C-0 CONTROL org A CAN read its OWN row on the support surface',
  disclosesId(ownRead, aTodoId));

const foreignRead = await rpc('tools/call', { name: 'todos__read', arguments: { todoId: bTodoId } }, tokenASupport, 'support');
check('C-1 org A canNOT READ org B\'s row through tools/call',
  !disclosesId(foreignRead, bTodoId));

The broader lane checks collection reads, write effects, named-instance confusion and token audience mismatch. A2A scenarios separately exercise skill routing, tenant writes and approval paths, because a REST or MCP test does not automatically prove the conversation path.

Verify the effect, not just the response

These are test assets and a repeatable verification approach, not a claim that every application is independently certified. Run the relevant scenarios against the configured deployment when changing exposure, roles or task routing; preserve the positive controls that establish what each refusal actually proves.

An organization administrator creates the credential through the organization API-key resource. Supply a recognizable name, the roles the integration needs and an optional expiry. The requested roles must fall within the caller’s grant ceiling. The organization-scoped route selects the account; application keys use their separate application resource.

The creation response includes plainKey once, alongside the key record. Save that value in the integration’s credential store before leaving the creation step. For an organization integration, it starts with sk_org_; the application variant uses sk_app_.

Set RESOURCE_URL to an allowed endpoint within that key’s scope and API_KEY to the returned plainKey. This is the request contract declared in api-keys.shared.schemas.ts and exercised by external-access-auth.e2e.ts:

curl "$RESOURCE_URL" \
  -H "Authorization: $API_KEY"

The header contains the raw key, without a Bearer prefix. The backend resolves its machine principal, scope and roles before authorizing the requested operation. A successfully authenticated key can still receive an authorization refusal when its role or tenant does not match the operation.

Keep the secret and the authority separate

The API-key create handler checks the requested roles, creates secret material and lets the normal resource path persist the hash. Its response adds the plaintext key once:

This implementation excerpt from api-keys.custom-impl.backend.service.ts shows the decision in context; explanatory source comments are omitted.

export function buildApiKeyMintHandlers(scope: ApiKeyScope, roleHierarchyResolver: RoleHierarchyResolver): ApiKeyImplHandlers {
  return {
    prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
      assertRequestedRolesWithinCallerCeiling(executionContext, (input as { roles?: string[] }).roles, utils.errorBuilder, roleHierarchyResolver);
      const { plainKey, keyPrefix, hashedKey } = generateApiKeyMaterial(scope);
      PLAINTEXT_KEY_BY_EC.set(executionContext, plainKey);
      return { ...(input as Record<string, unknown>), keyPrefix, hashedKey };
    },
    postfixCoreOperations: async (_id, createdKey, executionContext, _operationPath, _utils) => {
      if (!createdKey || typeof createdKey !== 'object') return createdKey;
      const plainKey = PLAINTEXT_KEY_BY_EC.get(executionContext);
      PLAINTEXT_KEY_BY_EC.delete(executionContext);
      if (!plainKey) return createdKey;
      return { ...(createdKey as Record<string, unknown>), plainKey };
    },
  };
}

Store the one-time result in the integration

Capture plainKey from the creation response and place it in the integration’s credential store. Subsequent resource reads do not recover the plaintext value. The authenticated request resolves the key’s organization or application and the roles assigned at creation.

Choose rotation when you need the old secret to stop working at a known time. Regeneration is not the same retirement policy.

Rotate with fresh proof and an explicit cutoff

For the default organization-key ROTATE operation, the caller needs ORG_ADMIN and a single-use reauthentication proof. A recently established session alone does not satisfy the operation’s explicit step-up requirement. Application-level administration uses its separately authorized variant; do not substitute that route for an organization administrator’s call.

This illustrative JavaScript runs in a trusted first-party administration client. reauthUrl is the application’s /auth/reauth API endpoint; rotateUrl is the selected key’s default ROTATE URL from its generated operation contract. sessionToken belongs to the administrator, not to the integration whose key is being replaced. This example uses a locally enrolled password accepted by the effective step-up policy; the standard interface handles other supported factors.

async function rotateIntegrationKey({ reauthUrl, rotateUrl, sessionToken, password, cutoff }) {
  const json = async (response) => {
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const body = await response.json();
    return body.data ?? body;
  };
  const headers = { authorization: `Bearer ${sessionToken}`, 'content-type': 'application/json' };
  const proof = await json(await fetch(reauthUrl, {
    method: 'POST', headers,
    body: JSON.stringify({ method: 'PASSWORD', password }),
  }));
  if (!proof.reAuthToken) throw new Error('Reauthentication returned no operation proof');

  const replacement = await json(await fetch(rotateUrl, {
    method: 'PUT',
    headers: { ...headers, 'x-reauth-token': proof.reAuthToken },
    body: JSON.stringify({ oldKeyInvalidationDate: cutoff.toISOString() }),
  }));
  if (!replacement.plainKey) {
    throw new Error('Rotation returned no replacement secret');
  }

  // Hand this directly to the integration's credential store, not a log.
  return {
    plainKey: replacement.plainKey,
    oldKeyId: replacement.oldKeyId,
    oldKeyInvalidationDate: replacement.oldKeyInvalidationDate,
  };
}

Choose a future cutoff that leaves time to distribute and verify the replacement. Omitting oldKeyInvalidationDate defaults to immediate retirement, not a grace period. Save the returned plainKey once, switch the integration, verify a real permitted request with the new raw key, then verify the prior value is refused after the returned cutoff. Subsequent reads cannot recover the secret.

The proof is short-lived and single-use. A retry may require a new proof; if the rotation response was lost, investigate the key state before blindly rotating again. REGENERATE deliberately has different semantics: it keeps the prior secret without a scheduled cutoff and does not carry the same explicit rotation step-up gate. Neither operation grants new roles.

Keep role changes out of secret maintenance

These resources do not expose an ordinary roles-changing update. Their lifecycle handlers accept their own inputs and do not use rotation as a second path to grant authority. If the integration needs different responsibilities, provision the appropriate credential rather than treating a secret replacement as a permissions change.

Create the organization or application OAuth client through its resource operation. Set its allowed grants and roles, retain the one-time plainSecret, then use the token endpoint. A client using client_credentials acts as itself.

The token issuer carries the resolved scope and principal into the signed claim:

This implementation excerpt from machine-token-issuer.backend.service.ts shows the decision in context; explanatory source comments are omitted.

public async issueClientAccessToken(request: MachineAccessTokenRequest): Promise<MachineAccessTokenResponse> {
    const maxMinutes = this.appConfigService.config.jwt.accessTokenExpirationMinutes;
    const requestedMinutes = request.expiresInMinutes ?? maxMinutes;
    const minutes = Math.max(1, Math.min(requestedMinutes, maxMinutes));

    const claim: Jwt_MachineToken_CreationParameter = {
      type: request.scopeType === ResourcePrimaryScope.ORGANIZATIONS
        ? ExecutionContext_ExecutionType.ORGANIZATION_MACHINE
        : ExecutionContext_ExecutionType.APPLICATION_MACHINE,
      clientId: request.clientId,
      scopeId: request.scopeId,
      roles: request.roles,
    };

    const accessToken = await this.jwtService.createJwtForMachineToken(claim, {
      audience: request.audience,
      expiresInMinutes: minutes,
    });

    this.logger.debug('Issued machine client-credentials access token', {
      clientId: request.clientId,
      scopeType: request.scopeType,
      scopeId: request.scopeId,
      audience: request.audience,
      expiresInMinutes: minutes,
    });

    return { accessToken, tokenType: 'Bearer', expiresIn: minutes * 60 };
  }

Request the intended resource

The token request names grant_type=client_credentials, the client credential and the resource audience. Present the returned access_token as a Bearer credential to that resource. The token endpoint checks that this client allows the grant and that the requested resource is known.

The public token endpoint uses the application’s configured access-token lifetime. It does not accept a requested lifetime. The expiresInMinutes option shown above belongs to the internal issuer API; its callers may shorten the policy maximum.

The following request follows external-access-auth.e2e.ts. Set BACKEND_URL to the application backend, CLIENT_SECRET to the one-time secret and RESOURCE_AUDIENCE to a resource identifier advertised by that deployment.

curl "$BACKEND_URL/oauth/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode "resource=$RESOURCE_AUDIENCE"

The response supplies access_token, token_type and expires_in. Save access_token as ACCESS_TOKEN; set RESOURCE_URL to an endpoint in that audience for which the client has permission:

curl "$RESOURCE_URL" -H "Authorization: Bearer $ACCESS_TOKEN"

An audience match is necessary but does not grant an operation role. A valid organization client still cannot use its token to operate on another organization’s records.

Separate the client secret from tokens already issued

The client secret is used to obtain tokens. A Bearer token is a signed snapshot of the client’s roles and scope with its own expiry. Changing the first does not rewrite the second.

There is no dedicated OAuth-client deactivate/reactivate operation pair in this resource contract. The status row above describes an admission condition, not an extra management endpoint.

Rotation and regeneration update the same client record; the returned plainSecret is the one-time value to install in the integration. Regeneration is therefore not an immediate retirement of the previous secret. Choose rotation with a deliberate cutoff when the outgoing secret must stop obtaining tokens.

The ordinary API and supported external machine-token paths verify the signature, issuer, audience and token expiry, then construct machine authority from the claims. They do not look up the client again in those Bearer branches. Operation authorization and scope checks still apply; this is not a promise that every request succeeds until expiry.

Direct authentication with the OAuth client secret is different: that path reads the client and checks its status and expiry for the request. User-delegated agent tokens also follow a different validation path. Do not extend this machine-Bearer behavior to every kind of credential.

Make the cutover observable

Use the application’s configured access-token lifetime and the token response’s expires_in when planning the overlap. The public token endpoint does not accept a shorter lifetime requested by the integrating service.

For a controlled rotation, keep a pre-rotation token and test these separate outcomes in a disposable integration:

1. Obtain a new token with the replacement secret and call an operation the client is allowed to use.
2. After the chosen cutoff, confirm the old secret can no longer obtain a token.
3. Check the pre-rotation Bearer separately: the secret cutoff does not itself revoke that token. Token expiry and the resource’s other authorization checks remain its boundaries.
4. Confirm the same token is refused after expiry. Keep an authorized fresh-token call as a control so a missing route or stopped service is not mistaken for revocation.

These checks distinguish a successful secret replacement from withdrawal of already issued access. If the product requires immediate client-wide invalidation of machine Bearers, the current authentication paths do not supply that guarantee.

Design business code for a machine caller

Machine identity is recorded independently from user identity. A machine-created record may have no creator user ID, so custom business logic should use the execution context’s principal rather than assuming every authorized action has a human userId.

User delegation is a separate flow: agent tokens represent a consenting person, while this client represents the service itself.

Discovery publishes the browser-facing consent URL, token endpoint, supported grants and signing-key information. The browser-facing authorization flow uses a registered redirect URI, state, a PKCE S256 challenge and the intended resource.

At exchange, the provider verifies the code against the original client, redirect and verifier before issuing anything:

This implementation excerpt from oauth-provider-token.backend.service.ts shows the decision in context; explanatory source comments are omitted.

const grant = await authCodeService.exchangeAuthorizationCode({
      code: request.code,
      clientId: request.clientId,
      redirectUri: request.redirectUri,
      codeVerifier: request.codeVerifier,
      presentedClientSecret: request.clientSecret,
    });

Build a public client’s authorization request

Use a registered public client with authorization-code access, an exact registered callback URI and an allowed MCP or A2A resource audience. Public registration uses PKCE rather than a client secret. A confidential client additionally authenticates at token exchange; do not place that secret in browser JavaScript.

This illustrative browser client uses metadata from a trusted, configured discovery URL. The browser must return to the same client origin/tab so its pending state remains available. A production client can use an OAuth library for this protocol bookkeeping; these functions expose the values that must stay connected.

async function beginDelegation({ discoveryUrl, clientId, redirectUri, resource }) {
  const response = await fetch(discoveryUrl);
  if (!response.ok) throw new Error(`Discovery HTTP ${response.status}`);
  const metadata = await response.json();
  const base64url = (bytes) => btoa(String.fromCharCode(...bytes))
    .replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
  const challenge = base64url(new Uint8Array(await crypto.subtle.digest(
    'SHA-256', new TextEncoder().encode(verifier),
  )));
  const state = base64url(crypto.getRandomValues(new Uint8Array(32)));
  sessionStorage.setItem('wildo-delegation', JSON.stringify({
    state, verifier, clientId, redirectUri, resource,
    tokenEndpoint: metadata.token_endpoint,
  }));

  const authorize = new URL(metadata.authorization_endpoint);
  authorize.search = new URLSearchParams({
    response_type: 'code', client_id: clientId,
    redirect_uri: redirectUri, scope: 'openid', state,
    code_challenge: challenge, code_challenge_method: 'S256',
    resource,
  }).toString();
  window.location.assign(authorize.href);
}

The discovered authorization endpoint is the frontend consent page. Wildo handles login and the person’s decision there. Its authenticated backend authorization/decision calls return JSON containing redirect_to; the frontend navigates to it. Your external client receives the callback, not the first-party session token or the internal consent token. Denial returns an error rather than a usable code. Consent may be bypassed only where the provider’s client/user policy permits it.

Validate the callback before exchanging its code

Run this on the registered callback page. This compact example allows one outstanding authorization attempt per tab; starting another replaces the pending attempt. It removes the pending entry before exchange, so a failed exchange starts a new authorization rather than replaying the code indefinitely.

async function finishDelegation() {
  const saved = sessionStorage.getItem('wildo-delegation');
  if (!saved) throw new Error('No pending authorization');
  const pending = JSON.parse(saved);
  const callback = new URL(window.location.href);
  const expected = new URL(pending.redirectUri);
  if (callback.origin !== expected.origin || callback.pathname !== expected.pathname
      || callback.searchParams.get('state') !== pending.state) {
    throw new Error('Authorization callback does not match the pending request');
  }
  sessionStorage.removeItem('wildo-delegation');
  if (callback.searchParams.has('error')) throw new Error('Authorization was not granted');
  const code = callback.searchParams.get('code');
  if (!code) throw new Error('Authorization returned no code');

  const response = await fetch(pending.tokenEndpoint, {
    method: 'POST',
    headers: { 'content-type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code', client_id: pending.clientId,
      redirect_uri: pending.redirectUri, code, code_verifier: pending.verifier,
      resource: pending.resource,
    }),
  });
  if (!response.ok) throw new Error(`Token exchange HTTP ${response.status}`);
  const token = await response.json();
  if (!token.access_token) throw new Error('Token exchange returned no access token');
  return { accessToken: token.access_token, expiresIn: token.expires_in, resource: pending.resource };
}

The token request reuses the original redirect URI and verifier. Its resource echo is optional in the server contract, but must match when supplied; the authorization code already binds the audience. Keep the returned access token in the client’s appropriate credential/session handling, out of URLs and logs. Call only the returned intended resource using the delegated agent-request example.

Keep the grant families distinct

Authorization-code delegation does not issue an unrestricted first-party API session or a refresh token. It requires a valid agent resource audience. Identity scopes such as openid, email and profile control identity claims; they do not grant business operations.

Complete the browser handoff correctly

The frontend consent route is the browser authorization endpoint. The authenticated backend authorize call returns JSON containing redirect_to; the frontend navigates after receiving it. This avoids trying to follow a cross-origin client redirect inside an authenticated XHR.

Use interactive consent for the person’s decision, and machine clients when no person is delegating.

Configure auth.dynamicClientRegistration. It is disabled by default; when disabled the endpoint returns 404 and discovery does not advertise it. The default limit is ten registrations per source IP per hour.

In the backend-authored application’s auth section, enable the public door and choose a rate ceiling. These are the fields declared by DynamicClientRegistrationConfigSchema:

dynamicClientRegistration: {
  enabled: true,
  maxRegistrationsPerHourPerIp: 10,
},

The public endpoint checks that an incoming registration is not asking to grant itself business roles:

This implementation excerpt from oauth-provider-controller.backend.service.ts shows the decision in context; explanatory source comments are omitted.

if (body.roles !== undefined) {
      this.sendRegistrationError(res, 'invalid_client_metadata', 'roles cannot be requested at dynamic registration');
      return;
    }
    const requestedScopes = typeof body.scope === 'string' ? body.scope.split(/\s+/).filter(Boolean) : [];
    const beyondIdentity = requestedScopes.filter((scope) => !OIDC_SUPPORTED_IDENTITY_SCOPES.includes(scope));
    if (beyondIdentity.length > 0) {
      this.sendRegistrationError(res, 'invalid_client_metadata', `scope(s) not available to a dynamically registered client: ${beyondIdentity.join(', ')}`);
      return;
    }

Register a public authorization-code client

Send the tool’s client_name and non-empty redirect_uris to /oauth/register. Redirects must pass the safe-URI policy: HTTPS, or permitted loopback HTTP, without embedded credentials or fragments. The returned client metadata describes what was actually registered.

For example, a tool can register the following illustrative HTTPS callback. Replace the example URL with the tool’s actual callback and BACKEND_URL with the application’s backend:

curl "$BACKEND_URL/oauth/register" \
  -H 'Content-Type: application/json' \
  --data '{
    "client_name": "Customer workspace tool",
    "redirect_uris": ["https://tool.example/callback"],
    "grant_types": ["authorization_code"],
    "token_endpoint_auth_method": "none",
    "scope": "openid profile email"
  }'

A successful response is HTTP 201 with client_id and the accepted metadata. It also returns a one-time registration_access_token and registration_client_uri for managing that registration. Store them securely: the management token is distinct from an OAuth client secret and does not authorize business API calls.

No OAuth client secret is returned. The tool uses client_id to start authorization with PKCE and user consent; it acts for that person rather than as an independently privileged machine.

Choose the onboarding policy for your audience

Enable this for clients that need the registration mechanism. Client metadata documents provide another identity-onboarding path. Neither mechanism bypasses consent, resource-audience checks or the person’s operation permissions.

auth.cimd selects DISABLED, ALLOWLIST or OPEN through CimdTrustPolicy. Disabled is the default. An allowlist entry can be the exact client URL or a bare host; the full URL is the narrower choice.

Import CimdTrustPolicy from @wildo-ai/saas-backend-lib. In the backend-authored application’s auth section, an exact-URL allowlist looks like this. The example hostname is illustrative; use the tool’s real HTTPS document URL.

cimd: {
  policy: CimdTrustPolicy.ALLOWLIST,
  allowedClients: ['https://tool.example/client.json'],
},

This uses the same configuration surface as Wonder Todos’ saas-config.backend.ts, with a narrowly selected client URL.

Publish a matching client document

The document supplies client_id, client_name and redirect_uris. Its client_id must equal the URL being resolved. The redirect used by authorization must exactly match a registered redirect, rather than merely share an origin or path prefix.

For the URL allowed above, serve JSON with a matching identity:

{
  "client_id": "https://tool.example/client.json",
  "client_name": "Customer workspace tool",
  "redirect_uris": ["https://tool.example/callback"],
  "token_endpoint_auth_method": "none"
}

The tool sends that full metadata URL as client_id on its authorization request, together with its redirect URI, state, PKCE challenge, identity scopes and target resource. Wildo resolves the document, checks the chosen redirect and continues to the user’s authorization step. Publishing this file does not itself create a token or a machine role.

The resolver applies URL and outbound-target checks even for allowlisted clients. It bounds fetch duration and size, validates the response and caches documents within a bounded lifetime. A metadata change is therefore not an instantaneous withdrawal of all previously fetched metadata.

Use the authentication mode the provider accepts

This implementation accepts the public-client none token-endpoint authentication method for metadata-document clients. It rejects unsupported authentication methods rather than silently treating a client claiming private-key authentication as public.

Published identity does not grant business authority. The tool still uses PKCE and user consent, then receives an audience-bound delegated token. Choose registered machine clients when the service should act under its own roles.

The backend creates a single-use consent-request token containing the authorization details. The frontend sends the decision using that token; the client does not get to replace the destination or scopes in a second request. This is the decision callback in Auth_OAuthConsent:

This implementation excerpt from Auth_OAuthConsent.tsx shows the decision in context; explanatory source comments are omitted.

const decide = useCallback(
    async (decision: 'approve' | 'deny') => {
      if (!consent || submittingRef.current) return;
      submittingRef.current = true;
      setStatus('submitting');
      setErrorLabel(null);
      try {
        const { redirect_to } = await getManualCallsHttpClient().oauthConsentDecision(
          consent.consent_token,
          decision,
          decision === 'approve' && remember,
        );
        window.location.assign(redirect_to);
      } catch {
        submittingRef.current = false;
        setStatus('error');
        setErrorLabel(UserOAuthConsentLabel.ERROR_DECISION);
      }
    },
    [consent, remember],
  );

Distinguish a trusted client from a user-approved client

A registered client configured not to prompt can skip consent only within its trust boundary. An organization client does not silently gain the same treatment for users outside that organization. A membership lookup failure forces the prompt.

Self-registered and metadata-document clients cannot declare themselves trusted. They still need the person’s authorization and the permitted code flow.

Remember only an affirmative choice

The remember control starts off. An approval with that choice can create a remembered grant; denying does not store an approval. The grant avoids an unnecessary future prompt only when it covers the same user, client, target and requested identity scopes.

Consent authorizes the handoff, not every business action. The endpoint continues checking the person’s actual permissions when a tool uses the resulting token.

The lookup is keyed by user, client and resource. Only an unexpired grant covering every requested scope returns true; a failed read returns false so the person is asked again:

This implementation excerpt from oidc-authorization-code.backend.service.ts shows the decision in context; explanatory source comments are omitted.

public async hasCoveringConsentGrant(userId: string, clientId: string, resource: string | undefined, requestedScopes: string[]): Promise<boolean> {
    try {
      const grant = await this.readConsentGrant(userId, clientId, resource);
      if (!grant) return false;
      if (grant.expiresAt && new Date(grant.expiresAt).getTime() <= Date.now()) return false;
      const granted = new Set(grant.scopes ?? []);
      return requestedScopes.every((s) => granted.has(s));
    } catch {
      return false;
    }
  }

Keep the target in the business key

The opt-in checkbox stores or widens the grant when the person approves. Widening combines the newly approved scopes with the existing set and renews expiry using auth.consentGrantLifetimeDays or the framework default. A unique user/client/resource key and conflict reread handle simultaneous initial approvals.

Let the person inspect and withdraw their approvals

Use the person’s ordinary application session, not the delegated token issued to the external tool. The owner-facing list operation is:

curl "$BACKEND_URL/oauth-consent-grants" \
  -H "Authorization: Bearer $USER_TOKEN"

The resource is scoped to the authenticated user even though its URL has no user-ID segment. Its standalone ownership relationship keeps that parent out of the path; the backend still confines the result to the caller. READ, LIST and DELETE require APP_USER; creating or updating remembered grants is reserved for the internal consent-decision flow.

Let the person choose an approval from that result by client, target resource and approved scopes. Keep the selected record’s _id as GRANT_ID, then withdraw it with:

curl -X DELETE "$BACKEND_URL/oauth-consent-grants/$GRANT_ID" \
  -H "Authorization: Bearer $USER_TOKEN"

Refresh the list to confirm the selected approval is gone. Do not treat a client ID or resource URL as the grant record ID, and do not submit another person’s user ID to choose the owner. On a later authorization request, that deleted record can no longer justify skipping consent; other client/user consent policies still apply.

Set the approval lifetime deliberately

The default is 180 days. The optional backend-authored auth.consentGrantLifetimeDays accepts an integer from 1 to 3650. Keep the existing authentication configuration and add the property there; the setting applies when a grant is created or renewed by approval. It does not rewrite an existing record’s expiresAt merely because configuration changed.

Separate remembered approval from token authority

The grant belongs to the user as a resource they can list and revoke. Withdrawing it removes the reason to skip a future prompt; it is not itself the access token. Identity scopes in the record control identity information, while operation access follows the user’s roles at request time.

Remembering approval does not create a refresh token or extend an already-issued token’s lifetime.

The authorization request names the intended resource. The code exchange reads that stored audience and rejects a different resource echoed by the token request. It then verifies the audience against the registered delegatable endpoints:

This implementation excerpt from oauth-provider-token.backend.service.ts shows the decision in context; explanatory source comments are omitted.

const requestedAudience = grant.resource;
    if (!requestedAudience) {
      throw this._oauthError(ErrorType.AUTHORIZATION, ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED, 'invalid_target',
        'the `resource` parameter (RFC 8707) is required for the authorization_code grant');
    }
    if (request.resource && request.resource !== requestedAudience) {
      throw this._oauthError(ErrorType.AUTHORIZATION, ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED, 'invalid_target',
        'the token-request `resource` does not match the resource authorized at the authorization endpoint');
    }
    const allowedDelegatedAudiences = this.container
      .get<ResourceServerInstancesRegistryBackendService>(SAAS_SERVICE_TYPES.ResourceServerInstancesRegistry)
      .listResourceServerAudiences(DELEGATED_TOKEN_RESOURCE_SERVERS);
    if (!allowedDelegatedAudiences.includes(requestedAudience)) {
      throw this._oauthError(ErrorType.AUTHORIZATION, ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED, 'invalid_target',
        `resource '${requestedAudience}' is not a delegatable agent endpoint (A2A / MCP)`);
    }

Keep identity and business permissions separate

The delegated access claim includes the user, their authorization version and azp, which identifies the authorizing client. Business roles are resolved at request time; granting an identity scope does not grant the ability to edit a record.

Before issuance the provider checks that the user remains active and has a usable authorization version. The delegated token lifetime is capped and no refresh token is returned. The connected tool must return through authorization when it needs a new delegation.

Call through the agent contract

Present the returned Bearer token to the audience it names and use that endpoint’s MCP or A2A contract. The resource server verifies the audience before dispatching the operation. This preserves a different boundary from a machine principal, whose roles belong to the registered service rather than a consenting user.

Carry the delegation into an MCP request

Use the complete discovery and PKCE recipe to obtain accessToken, expiresIn and the original resource. For an MCP delegation, that resource is the exact chosen MCP endpoint, including a named instance when applicable. It is not the application’s general API origin.

After the MCP handshake has negotiated the locally supported 2025-06-18 revision and sent the initialized notification, this illustrative request lists the tools available to the consenting person:

const response = await fetch(resource, {
  method: 'POST',
  headers: {
    authorization: `Bearer ${accessToken}`,
    'content-type': 'application/json',
    accept: 'application/json',
    'MCP-Protocol-Version': '2025-06-18',
  },
  body: JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }),
});
if (!response.ok) throw new Error(`MCP HTTP ${response.status}`);
const envelope = await response.json();
if (envelope.error) throw new Error('MCP discovery was refused');
const tools = envelope.result.tools;

Select a tool and its argument schema from that authenticated result before calling it. Tool exposure and the person’s current business permissions still determine what can execute. An empty catalogue is not permission to invent a tool name. Other negotiated revisions require their own metadata, so let the client’s transport handle version changes.

For A2A, apply the same audience-bound Bearer to the selected A2A endpoint using its request and response contract. An agent token does not become a first-party API session merely because both endpoints belong to the same application.

Bind delegation to the intended write

The grant service stores the field, operation, minter and concrete upload URL in the token. An update grant also names the target row. This excerpt from file-upload-grant.backend.service.ts follows field validation; comments are omitted.

const constraint = await this.constraintResolver.resolve({ resourceType: target.resourceType, fieldName: target.fieldName });
this.assertDeclarationFitsConstraint(params.declared, constraint, executionContext, target);
const expiresInMinutes = params.expiresInMinutes ?? FILE_UPLOAD_GRANT_DEFAULT_MINUTES;

const metadataWithoutUrl: Omit<FileUploadGrantMetadata, 'uploadUrl' | 'producedFileId'> = {
  fieldName: target.fieldName,
  operation: target.operation,
  minter: { entityType: minter.uploadedByEntityType, id: minter.uploadedBy },
};

const token = await this.consumableTokenService.createToken({
  tokenType: CoreConsumableTokenTypes.FILE_UPLOAD_GRANT,
  consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
  expiresIn: { value: expiresInMinutes, unit: DurationUnit.MINUTES },
  organizationId: executionContext.initiatorIds?.organizationId,
  userId: executionContext.initiatorIds?.userId,
  resourceIdentifier: String(target.resourceType),
  relatedId: target.resourceId,
  roles: [...(executionContext.initiatorRoles ?? [])],
  metadata: { ...metadataWithoutUrl, uploadUrl: params.uploadUrl },
});

Configure the addresses the recipient must reach

The HTTP mint route reads runtime.endPoints.main_backend_api.publicUrl from the application’s resolved configuration. It refuses minting when that address is absent; it does not construct a trusted upload destination from the incoming Host header. The returned upload and status URLs must be reachable by the party receiving the grant, not only from inside the application’s container network.

For a human drop page, the application must also declare a frontend service. The default frontend selected by configuration needs its own runtime.endPoints[frontendServiceName].publicUrl; the service must be present in frontendServices. The grant service builds uploadPageUrl from that address and the public upload-grant route. Configure deployment addresses through the normal application environment setup, then inspect the resolved values instead of adding a second URL authority inside a custom caller.

Check the returned uploadUrl and statusUrl, and inspect whether uploadPageUrl is present before offering a browser link. A headless deployment can accept the delegated upload through the backend contract; it does not acquire a hosted upload page merely by minting a grant.

Use the returned upload instructions

Both mint doors return the upload URL, a credential header, shell upload commands and a status URL. When a frontend is configured, the response also supplies the browser drop-page URL. Use those returned values so the client follows the exact bound route.

The default lifetime is 15 minutes with a framework ceiling of 60 minutes. Anonymous sessions and consumable-token callers cannot mint another grant. Ordinary operation authorization still applies; the grant does not create permission to read or modify other records.

Carry one file through the complete handoff

This illustrative browser JavaScript follows the Wonder Todos attachment test. recordUrl is the existing todo-list’s API URL, bearer belongs to a caller allowed to update it, and file is a selected File. Start with an empty attachments field: this example replaces its value with one file. An add-to-existing workflow must preserve the current IDs and handle concurrent edits.

async function attachFile({ recordUrl, bearer, file }) {
  const readJson = async (response) => {
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  };
  const authority = { authorization: `Bearer ${bearer}` };
  const jsonHeaders = { ...authority, 'content-type': 'application/json' };

  const grant = await readJson(await fetch(`${recordUrl}/files/attachments/grant`, {
    method: 'POST',
    headers: jsonHeaders,
    body: JSON.stringify({ expiresInMinutes: 10 }),
  }));

  const form = new FormData();
  form.append('file', file, file.name);
  await readJson(await fetch(grant.uploadUrl, {
    method: 'POST',
    headers: { [grant.uploadHeader.name]: grant.uploadHeader.value },
    body: form,
  }));

  const status = await readJson(await fetch(grant.statusUrl));
  if (status.state !== 'redeemed' || !status.file?.fileId) {
    throw new Error('The grant has not produced a file ID');
  }
  const attachments = {
    fileIds: [status.file.fileId],
    updatedAt: new Date().toISOString(),
  };

  await readJson(await fetch(recordUrl, {
    method: 'PUT',
    headers: jsonHeaders,
    body: JSON.stringify({ attachments }),
  }));
  return readJson(await fetch(recordUrl, { headers: authority }));
}

The upload request carries only the returned grant header; the final write and read use the original Bearer. Let FormData set the multipart content type. For a human handoff, show uploadPageUrl and resume at the status read after upload instead of transferring bytes in this function. That browser URL requires a configured frontend.

Inspect the record in the final response (response.data for an enveloped response, otherwise the response itself): it should contain the same ID in attachments.fileIds. A single-file field instead uses { fileId, updatedAt }. A redeemed grant proves that bytes produced a file, not that scanning has finished or the parent accepted it: pending scanning can still delay attachment. Check file readiness and retain the produced ID while resolving a pending result; do not redeem the same grant again to retry the parent write.

Handle retries according to the claim point

Route matching and actionable file validation happen before the single-use token is consumed. Consumption occurs before the file row and byte write, so concurrent redemptions cannot both start an accepted upload. A refusal before that point can leave the grant usable; a failure after consumption requires a new grant.

The upload is attributed to the minter recorded in the grant. Possession of the link does not establish the identity of the person holding it. Status exposes the produced file ID when write-back succeeds, while the final resource create or update uses the caller’s normal operation permissions.

Give an MCP caller the same upload path

Opt the parent CREATE or UPDATE operation into MCP with mcp: { exposed: true, description: '…' } on its supported default URL-bearing variant. When that request contains a user-uploadable file field, Wildo derives the upload-grant tool and adds instructions to the parent’s description. There is no second upload tool implementation to author.

For a resource named todos with an exposed CREATE operation and an attachments field, the derived name is todos__create.upload_grant.attachments. Discover the actual name and input schema in the server’s tool list: UPDATE also requires the parent’s instance identifier, while CREATE does not.

This illustrative tools/call request declares the file before minting, so an impossible MIME type or size can be refused before upload:

{
  "method": "tools/call",
  "params": {
    "name": "todos__create.upload_grant.attachments",
    "arguments": {
      "name": "inspection.jpg",
      "mimeType": "image/jpeg",
      "size": 184320,
      "expiresInMinutes": 10
    }
  }
}

Read the grant object from the tool result, then use the returned instructions rather than constructing an upload URL yourself.

A grant inherits the exposed parent operation’s gating; it does not grant the caller broader record access. Upload success, processing readiness and successful parent attachment remain separate steps. Treat the header and token-bearing page/status URLs as bearer credentials and keep them out of public logs.