Plugin SDK
Agent access
Experimental contract: trusted actors, scoped credentials and authenticated work sessions.
Experimental actor contract v1; credential scopes v1 and v2. Domain adopters: Tasks, Calendar 0.0.2, Integrations 0.0.2, native Wiki collection tools, Contacts, Meetings and Sessions.
Wiki services require explicit collection roles in newly issued credentials.
Native wiki_collections, wiki_query, wiki_read and article edits through
wiki_command support service actors; collection creation remains human-only.
Legacy context selections remain read-only and dormant per-article service
roles stay dormant. Producer writes (source.write, source.move and
article.write with source) remain user-only: their private author receipts
have no managed custody contract yet. Granting an editor does not expose those
receipts. A producer-managed Wiki (managedBy set in its metadata) refuses every
service-actor command with UNAVAILABLE, including lifting the marker: the
producer overwrites agent edits on its next run, so the Wiki runtime reads the
metadata into every service actor's scope and refuses in authorize; people keep
the cooperative marker. The host audits service attribution.
One owner retains context; each managed service has a stable service:<uuid> actor ID, independently revocable credentials and explicit collection roles. Creating a service creates no user, organization or copied context. Personal OAuth and independently owned agent accounts remain unchanged. User guide.
Trusted execution context
DomainExecutionContext.actor is host-issued attribution: version: 1, type, id, ownerUserId; service calls additionally have a non-secret credentialId and server-generated sessionId. actorId retains existing human IDs and equals the namespaced service ID for services. These values must never be read from command input, names or imported reporter labels. There is no delegated subject.
A runtime must declare serviceActorVersion: 1; a tool must separately declare serviceAccess: "allowed". Missing adoption fails closed. Old plugins remain user-only. These flags do not grant access. The host applies current permissions to every operation, reference, export and replay. Fixed audienceUserIds remains a human-only ceiling; Messages therefore rejects services until its own versioned audience contract is ready.
Before opting in, audit participants, authors, assignment, notifications, private records, approval and idempotency. Store incompatible identity/session additions in a new plugin-owned format. Tasks writes v5 while retaining strict v1–v4 codecs and the unchanged public summary v1. Its authenticated journal identifies services and their work sessions; active service leases require the matching authenticated session. Lease IDs are visible coordination references, not authentication.
Authority
Effective service access intersects the service's current binding, the credential's original permission set and collection/version ceiling, the granting owner's current rights, current membership and protected-parent policy. Legacy v1 credentials retain one owner-custodied collection. V2 credentials can combine multiple collections, explicit connection operations and selected core containers. No onward delegation of received shares. Removing the owner's membership destroys its incarnation; rejoining does not revive old services.
V2 constructs a separate core catalog, search and file projection from owner-issued object/wiki/bucket/workspace selections. Workspace memory requires an explicit memoryVersion: 1 ceiling on a workspace or stable fact grant. Legacy keys never acquire it implicitly. Personal facts remain private unless individually selected; administration remains absent. A selected workspace is a hard ceiling for this managed credential; ordinary personal workspace views remain soft filters. Fact origin is never an ACL. Optional plugin integrations are offered only for compatible service-aware providers; unsupported security never falls back to personal OAuth. Required reference checks remain live.
Workspace memory
Each service has an owner-custodied home workspace. recall unions only its live
workspace/fact grants; names can repeat across workspaces, while stable fact IDs
identify revisions. Hidden origin nodes and link endpoints are omitted. Ordinary
personal memory calls cannot see workspace rows. A forgotten/recreated name gets
a new identity and does not inherit the old fact grant.
Managed remember and forget require an operation UUID and exact revision
(null only for creation). New facts default to the agent home. Writes intersect
immutable and live permissions. Required review persists a proposal without
changing canonical memory; single/session/permanent approval binds the exact fact,
grant and applicable session. Retry the identical operation after owner review.
Revision conflicts require a fresh read and proposal. Replays recheck authority;
there is no service purge or self-approval. Owner UI, export and account erasure
retain the workspace boundary.
Credential-bound work sessions
Each credential receives a server-generated session ID. The transport bearer proves the binding; supplying a visible session ID proves nothing. A runtime must issue a separate credential for every concurrent worker. Two processes sharing a bearer are the same work session, a deliberate limit rather than inferred process isolation. Reconnect resumes it; rotation creates a new session under the same stable service principal. OAuth credentials expire after 30 days. Manually issued managed credentials may be unlimited until revoked; one issued with an OAuth bearer additionally ends with that OAuth grant (below). Revocation does not erase an existing lease: Tasks lets its collection custodian explicitly recover it with a reason recorded under the custodian identity; services cannot use this path.
Expiry and revocation are enforced independently of editable library-key fields. Lifecycle writes and plugin operations share transaction/row locks, fencing new writes and replays after revocation returns. Already delivered data cannot be recalled. A plugin release keeps a credential only when everything a service can reach through the plugin is declared exactly as before; any change to such a declaration requires a new credential, so old ceilings do not silently acquire new capabilities.
What a plugin release does to a credential. The ceiling pins each plugin by its version and, since AV08-E4, by the digest of its service-reachable surface: on each collection and connection grant (grants[].pluginVersion and surfaceDigest, v1 the same two fields) and on bucket and workspace grants (contextGrants[].plugins[]). A pin holds while the organization runs that version or a version whose surface digest is the pinned one (pinMatches, the one rule every pin site applies; operator's answer B to Q002, decision 2026-11-15 "A managed credential survives a plugin release that keeps its reachable surface"). The digest is the sha256 of one canonical description of the surface, defined once in service-surface.ts (serviceSurfaceJson): the whole manifest except its version (the authorization policy with resources, permissions and roles; the formats with their read, write, history and draft permissions; the actions with their permissions and approval floor requiresApproval; the datasets) and the schemas it names; every tool with serviceAccess: "allowed" with its name, input schema, execution actions and annotations; the service adoption (serviceActorVersion), the collection type, creator role and create permission, the creation role and record grant policy per declared format; and the runtime's other declarations (containers, context fields, traversal roles, path trees, projection fields, protected permissions and the like). The classification of every runtime and tool member lives next to it (runtimeSurfaceCoverage, toolSurfaceCoverage); a member the SDK adds fails the SDK's typecheck until it is classified there. Four limits are part of the contract. The digest sees declarations, not behaviour: a command that keeps its schema and starts doing more passes unnoticed, the residual risk the operator accepted with that answer. A runtime that declares an approval floor, tools or operations only as functions (managedExternalApproval, externalOperation, externalTools, dynamicTools and the other members classified opaque) gets no digest, so its credentials keep the exact version pin; Integrations is one. The digest covers the runtime only: the Wiki's transitional managed tools (get_wiki, list_wikis, declared through the host's internal transitional contract, not the runtime) are outside it; they read only through the reader the host binds to the credential's live grants, and they leave with the transitional extension. And a credential issued before AV08-E4 carries no digest and keeps the exact version pin as well. Once no pin of a credential holds for a plugin the organization runs, the access the credential carries for that plugin is dead, and both sides are told. The agent: a refusal of a managed caller whose credential pins an installed, enabled plugin in a way the running plugin no longer matches keeps the host code UNAVAILABLE and carries publicCode: "CREDENTIAL_OUTDATED" (PluginHostError), which the plugin tools print with the instruction that the owner must issue a new credential and that retrying does not help; collections(pluginId) and query({ pluginId }) for such a plugin refuse the same way instead of answering an empty list. The condition reads the credential's own scope and the organization's running plugin versions, never the target, so a known and an unknown id answer alike; the host code stays UNAVAILABLE because callers that read it as "nothing here" (a search over several wikis and objects) must keep working for what the credential still carries. The owner: the action item platform.agent-connect appears with revision outdated until one valid credential carries every saved access at the installed versions (action items), and agent_access_list names the plugins per credential (credentials[].outdatedPlugins). A saved connection policy pins the version as well (setManagedExternalAccess), issuance copies it and a release upgrade leaves it alone: agent_access_list marks such a grant (externalGrants[].outdated), and the owner saves the connection's permissions again before a new credential helps.
Owner control plane
Use ordinary owner OAuth outside untrusted model loops. Management of one service never grants content to its administrator implicitly.
| MCP tool | Non-secret effect |
|---|---|
agent_access_list | Own services, grantable collections/roles and credential/session references; agent_id narrows to one service, agent_id with credential_id previews one credential |
agent_access_create | Named identity, no initial authority |
agent_access_grant | Current collection role or removal, optionally expiring |
agent_access_revoke | Permanent revocation of exactly one credential (credential_id; with agent_id it must belong to that service, else nothing is revoked) or, only with the explicit revoke_agent: true and agent_id, the whole service |
access_preview | Dry run of a grant or context selection (also a bucket membership or workspace assignment): what each live credential and a newly issued credential would reach afterwards. Nothing is changed |
plugin_identity | Managed caller's authenticated actor/session references |
Issuance is not a model-facing tool. A trusted controller posts { agentId, collectionId, expiresIn } to /mcp/agent-credentials, with personal OAuth for this server's MCP resource. The response is no-store and contains one-time credential, id, sessionId, expiresAt, scope. Put only the managed bearer into the agent transport. Never log it or put it into a model prompt. Browser issuance is available under Apps & API-Keys and uses the same scoped host registration with a same-origin form.
A credential issued with OAuth ends with that OAuth grant (DECISIONS 2026-11-06, "OAuth-issued credentials are bound to their grant"). Issuance through /mcp/agent-credentials records the bearer's OAuth client, its consent and its browser session on the credential (managed_credential.oauth_client_id, oauth_consent_id, oauth_session_id, migration 0158). Every use re-checks them (oauthOriginLive, inside loadManagedCredential):
- Consent withdrawal ends the credential at the next request.
- A disabled client ends it the same way.
- A person's end of the issuing session ends it when the session row and the session's refresh families are deleted. On v2 that is sign-out, session revocation or a ban.
- An expired session ends nothing, as long as the client still holds a live refresh family (AV02-D11 (a)).
This applies even to an "unlimited" credential, which therefore lives only as long as the controller's grant does. A credential issued in the browser records no OAuth grant and keeps its own expiry and revocation.
Feedback reports under the owner (AV08-SUP7). The owner may save a feedback-reporter grant for an agent (POST /api/v2/agents/feedback, {agentId, allowed}; a managed_agent_access row of kind feedback whose target is the agent). A v2 credential issued afterwards carries it as scope.feedback: { id }, and its /mcp connection then serves submit_feedback, list_my_feedback, get_feedback and reply_to_feedback. Reports are the owner's: the reporter authority is the owner's user and member with the OAuth client and consent the credential was issued under, so only a credential issued with the owner's OAuth bearer (a consent-bearing client, e.g. a controller after a device sign-in) can report; a browser-issued one cannot. Every call and replay re-checks the credential (loadManagedCredential, OAuth origin included), the feedback ceiling and the saved grant. Support operations are never part of this grant.
Support operations for an agent of support staff (AV08-SUP8). An owner who is live support staff may save a support grant for an agent (POST /api/v2/agents/support, {agentId, operations}; a managed_agent_access row of kind feedback-support naming some of read, triage, reply, note, never redact; every named operation must be one the owner's staff row holds; an empty list removes it). A v2 credential issued afterwards carries it as scope.support: { id, operations }, and the agent's own /mcp connection then serves the support tools of those operations (list_feedback, get_feedback_admin, reply_to_feedback_admin, add_feedback_note, triage_feedback); /mcp/admin-feedback keeps its own audience. Every call and replay requires the live credential, the ceiling, the saved grant and the owner's live staff row holding the operation, checked by the resolver, by withFeedback's locks and by the managed arm of feedback_support_allowed (migration 0201). The audit row names the service actor and the staff person it acts for.
The library hashes keys; only verification material and non-secret authority references are persisted. An unmapped managed library key is unusable. The reserved mk_agent.v1. prefix fails closed on older deployments. No synthetic user session or second authentication engine.
Machine clients (client credentials)
A machine client without a browser can reach one managed agent's context over the OAuth client-credentials grant (AV08-N8d, decision AV08-D6 (a)). The client is bound to the agent: it gets that agent's ceiling and ends when the agent's access ends.
- Issuance. Only the owner registers a client, for one agent. Over the trusted controller:
POST /mcp/agent-clientswith{ agentId, collectionId | collectionIds, expiresIn, jwks? }and personal OAuth. In the browser session:POST /api/v2/agents/clients/issuewith{ agentId, collectionIds, expiresIn, jwks? }, same-origin, on the person's own account; it records no OAuth origin.expiresInis in seconds and must be finite (at most 30 days). Dynamic registration, CIMD, pre-registration, operator one-offs and MCP tools cannot create such a client. Both answers areno-store. Each carries a server-generated client idmk-agent-<uuid>and eitherprivate_key_jwtas the token endpoint authentication, when you send a publicjwks(preferred), or a one-time client secret whose expiry is no later than the credential's.- The controller route answers 201. Beside the managed credential's
id,sessionId,expiresAtandscopeit holdsclient:{ client_id, token_endpoint_auth_method, client_secret?, client_secret_expires_at? }. - The browser procedure answers 200 with a flat shape:
{ id, sessionId, expiresAt, clientId, tokenEndpointAuthMethod, clientSecret?, clientSecretExpiresAt? }.
- The controller route answers 201. Beside the managed credential's
- Token.
POST /api/auth/oauth2/tokenwithgrant_type=client_credentialsandresource=<MCP_ORIGIN>/mcp. The client is linked to the personal/mcpresource only and holds the one scopemeinkontext:agent. It never gets/api/v2, the feedback resource, an introspection or issuer role or the key mint. - Binding. Only the
mcpservice accepts the token. It resolves the caller on every request from the verifiedclient_id: that client's one live binding (unique by migration 0184), the managed credential's live check including its OAuth origin, and the owner's consent under the binding's reference. No claim of the token selects the binding, and the caller is the agent'sservice:<uuid>actor. Audit rows carryoauthClientId. - End. Revoking the agent or the credential revokes the binding and disables the
oauth_clientin the same transaction. The next request is refused, and so is every further token request. The credential's expiry and the end of the issuing OAuth grant (above) end the client too. A new ceiling means a new credential and a new client; no update path exists.
Scope and verification
The plugins that declare serviceActorVersion: 1 and mark tools serviceAccess: "allowed" are Tasks, Calendar (since 0.0.2, PR #377: calendar_collections, calendar_query, calendar_command; calendar_free_busy since AV08-F1), Integrations, Wiki, Contacts, Meetings and Sessions; each is bounded by the credential's explicit collection roles. A declarative Studio plugin admits managed agents only to the commands its definition opens with serviceAccess: "allowed" (definition version 3): its compiled runtime then declares serviceActorVersion: 1, the agent reaches those commands through plugin_command within its collection role, and every other command and generic create or update stays refused (AV08-F18). Messages, declarative plugins without such a command, attenuated service-run grants and verified human delegation remain separate gates. A service's approval means the service acted; neither ownership nor personal OAuth alone proves human presence. No Moss account migration, historical identity remapping or kiosk cutover.
Real-store/auth/MCP tests check ceilings, isolated discovery, live rights, same-agent sessions, attribution, expiry, revocation, replay and existing human access. A separate versioned external model suite, Agenten-Zugänge und Urheberschaft, uses readable Langfuse scenarios and state-based evaluators. Read the acceptance record for actual execution evidence and outstanding gates; tests present in source are not evidence of a passing model run.
Agent definition at connect
A managed connection whose credential reaches Core objects (a v2 scope,
managedContext) gets its definition over the standard MCP surface alone
(AV08-SUP9). The initialize and server/discover instructions are the fixed
managed base followed by the digest of the objects the credential reaches,
composed by the same callerDigest as a person's connect: instructions,
skills and the other kinds by section, the compact variant (compactCallerDigest,
within the 2,048-character cap) for the clients DIGEST_COMPACT_CLIENTS names.
The digest names objects only; the agent's memory is read with recall. The
connection declares the SEP-2640 skills extension and answers skills/list,
skills/get and skill:// reads, in both protocol eras, from the same catalog
(managedCatalog, which re-enters the host's live grant checks): a skill the
credential does not reach is unknown on every path (-32602). A credential
that selects no object keeps the fixed base and lists no skill. A client polls
for changes with list_workspace_objects and its if_none_match etag; no
second change marker exists. Code: apps/server/src/mcp/managed-connect.ts and
the managed branch of apps/server/src/mcp/pipeline.ts.
Multi-scope issuance and context selection
managedCredentialScopeSchema accepts both versions without upgrading existing
credentials. The trusted POST /mcp/agent-credentials endpoint accepts legacy
collectionId or collectionIds; the latter creates v2 and includes the owner's
saved context and connection-operation selections. An empty collection array is
valid only when another explicit selection exists. No model-facing tool issues a
credential. Registration rebuilds the saved scope under the owner lock before
storing it, so a caller cannot forge permissions or grant IDs.
Core grants identify an object, whole wiki, owned bucket or optional owned workspace. Live selection IDs intersect the immutable ceiling before discovery, search, content, original source bytes and replay. Wiki/bucket contents resolve on every access; removal is immediate. Bucket plugin content is read-only and pins supported plugin versions at issuance. Core content never includes domain records. Existing personal OAuth and v1 projection stay unchanged.
The agent's home workspace covers the plugin content lying in it (WS-BUCKETS
P2, DECISIONS 2026-10-27 D5): a plugin root linked to the home — and its
children — is reachable through the home grant alone, with the plugin's
creator role while the owner's live write policy is direct, and otherwise the
plugin's role covering the most read permissions with the ceiling limited to
those reads (a reader role may carry a command permission; it never passes the
ceiling), for plugins that adopted service access and
have no external operations (Integrations keeps its explicit per-connection
grants). The workspace grant pins the versions of exactly the plugins the
coverage reaches, the service-capable ones without external operations, at
issuance like a bucket grant (since MAAV-04; a credential issued before it may
still pin Integrations, which outdates it once at Integrations' next release
until a new credential replaces it); a credential issued before the coverage carries
no pins and stays as narrow as it was. Links resolve live, so content moved
into or out of the home follows at once, and the owner's own rights still
bound every access. Explicit single shares of a root remain possible and are
unchanged.
Integration collection roles establish live RBAC; they do not disclose sibling connections. Only connections with a live explicit operation grant inside the credential ceiling are visible. The Secrets provider remains user-only: the executor may use an owner-established credential binding without exposing its payload or management capabilities to the agent.
Matching an external operation
managedExternalOperationPolicy(scope, target) matches one validated v2 authority
layer against the host-resolved plugin version, collection, resource, operation,
schema digest and required permission. It returns denied when no explicit
operation matches. All matching operation restrictions participate, so array
order cannot bypass a denial or required review. A matching stale schema or
missing permission denies rather than borrowing authority from another grant.
Grants for different operations are independent; collection grants never confer
external connection authority.
Resolve the credential ceiling and live grants separately, then intersect their results with the plugin's own approval requirement. Do not supply target metadata from model arguments: derive it from the authorized resource and reviewed runtime. The host still checks owner/member incarnation, ancestry, expiry, installation, protected parents and replay. This helper alone authorizes no provider dispatch.
Requestor and reviewer binding
managedReviewBindingSchema describes host-issued metadata for an original service
request and its maximum 15-minute review window. It binds owner organization and
membership incarnation, service actor, credential/session, effect/resource/action,
request digest and an authorization-snapshot digest. The host must also cap expiry
at the original credential and live grant deadlines.
matchManagedReviewBinding(stored, current, reviewer, now) rejects any changed
binding, expired/future request or reviewer other than the authenticated human
owner. current must be rebuilt by the host after live checks, never copied from
client input or the stored record without revalidation. The authorization digest
must cover policy/grant revisions, plugin/schema/adapter identity, destination,
credential binding generations and relevant record revisions. Hash canonical
validated content; do not hash display labels or trust a model-provided digest.
A current result is only identity/freshness compatibility, not approval or
permission to dispatch. The trusted same-origin action must still record the
human's deliberate approval and atomically admit the exact stored effect. No
MCP approval method or mutable approved field is introduced. The existing
service remains the requestor; the reviewer is recorded separately.
Implemented review and dispatch path
The effect ledger keeps service identity and server-generated session in its idempotency namespace. Its authorization snapshot pins the original credential, owner/member incarnation, session, plugin/policy, connection revision, schema, destination, adapter and credential binding generations. The sealed operation contains the exact original arguments. Owner browser approval accepts only the effect ID and reloads these arguments; it never accepts edited request content. Review has a fifteen-minute ceiling and revalidates the still-live original credential on every admission. Owner approval is audited separately from service dispatch. Atomic dispatch claiming and existing outcome-unknown fencing prevent repeated approval from redispatching a write.
managedExternalApproval is an optional plugin-owned approval floor. Without
it, writes require review. Integrations 0.0.2 explicitly permits owner-configured
standing authority for its reviewed operations; the immutable credential and
live operation grant can still require review or deny. This includes sensitive
reads. Dynamic tools require both runtime adoption and per-tool serviceAccess.
Studio authoring, workflow credential issuance, secrets and control-plane tools
remain unavailable to managed callers.
Owner access inspection and presentation
The account UI groups grants, issued credentials and a credential-specific live inspection under each agent. Inspection calls the same managed host/catalog checks using the selected existing key; it cannot issue, widen or execute an external effect. Content includes the selected object/container provenance. Provider credential readiness is separate from action authority. The result is a point-in-time view, not a promise that a later operation will succeed.
Runtimes may supply accessLabels, a map from role IDs or external operation
names to { de, en } labels.
These are presentation metadata only; manifest permissions remain authoritative.
The host does not translate domain permission semantics or infer new grants.
Context multi-selection is atomic and reselecting an existing grant preserves its
identity. Removing and later re-adding a grant does not revive an old credential.
Pending review links expose metadata only and retain the existing owner-bound,
original-request review admission when opened.
Operation labels do not change names, snapshots, approval matching or credential ceilings. Unlabelled operations use their tool title or name.