The five-method HostAdapter.

The adapter is the authority

Cambiary issues no identities and stores no permissions of its own. The adapter is where your app tells the platform who a user is, what they can see, what they may do, and how to act on their behalf. Because the contract is generic, the platform core never changes to support a new host.

interface HostAdapter {
  validateToken(token: string): Promise<UserIdentity>;   // who is this user?
  getContext(ref: ContextRef): Promise<HostContext>;     // what are they looking at?
  getPermissions(user: UserIdentity): Promise<Permission[]>; // what may they do?
  executeTool(tool: string, args: unknown): Promise<ToolResult>; // run an approved action
  pushNotification(msg: Notification): Promise<void>;    // notify the host
}

validateToken

The platform hands your adapter the host token exactly as your app issued it. Your validateToken is the real authority — validate it against your existing auth (JWT, session, or API key) and return the resolved user identity. A rejected token stops the run before any context is resolved.

getContext

Given a reference (entity type + id + view), return governed, minimized context. The model sees references and counts, not raw records — so getContext resolves the reference into just enough governed context for the agent to reason, and cross-entity or cross-conversation mixing is blocked at the boundary.

getPermissions

Return what the user is allowed to do. The platform computes effective permission as the intersection of user, delegated agent, and org policy — fail-closed, so a sensitive tool with any missing input is denied. Your getPermissions supplies the user half of that math.

executeTool

Run an approved action against your services. executeTool is only ever reached after the governance gate has run permission, policy, and approval — the runtime can never call your services directly. Assign each tool a risk level so the platform knows what auto-approves versus what pauses for a human.

• read_only — may run automatically.
• safe_create — low-risk creation.
• controlled_write — pauses for explicit human approval.
• destructive — hard-blocked.

pushNotification

Deliver an update from an agent back into the host — a completed run, a result ready to review, or a message for the user — through whatever notification channel your app already uses.

In-process vs out-of-process

The same contract runs two ways. In-process, the adapter is a TypeScript class the platform calls directly — the lowest-latency option when your backend is Node. Out-of-process, the adapter is a set of HTTP endpoints in any language, reached at the adapterUrl you registered — so a C#, PHP, or Python backend implements the exact same five methods behind HTTP.

• In-process — a TypeScript class; direct calls, no network hop.
• Out-of-process — HTTP endpoints in any language at your registered adapterUrl.

Every tool call described above is dispatched through the governance gate — permission, policy, approval, audit, and the platform-level controls are set out on the security and data-handling page. For host-specific worked examples, see the integration paths.