meinKontextDocs
Navigation & Suche

Plugin SDK

Agenten-Zugänge

Experimenteller Vertrag: geprüfte Akteure, begrenzte Zugänge und authentifizierte Arbeitssitzungen.

SDK 0.1 · ExperimentalMarkdown

Diese technische Anleitung wird derzeit auf Englisch gepflegt. Navigation und Nutzer-Anleitungen sind auf Deutsch verfügbar.

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 toolNon-secret effect
agent_access_listOwn services, grantable collections/roles and credential/session references; agent_id narrows to one service, agent_id with credential_id previews one credential
agent_access_createNamed identity, no initial authority
agent_access_grantCurrent collection role or removal, optionally expiring
agent_access_revokePermanent 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_previewDry 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_identityManaged 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-clients with { agentId, collectionId | collectionIds, expiresIn, jwks? } and personal OAuth. In the browser session: POST /api/v2/agents/clients/issue with { agentId, collectionIds, expiresIn, jwks? }, same-origin, on the person's own account; it records no OAuth origin. expiresIn is 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 are no-store. Each carries a server-generated client id mk-agent-<uuid> and either private_key_jwt as the token endpoint authentication, when you send a public jwks (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, expiresAt and scope it holds client: { 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? }.
  • Token. POST /api/auth/oauth2/token with grant_type=client_credentials and resource=<MCP_ORIGIN>/mcp. The client is linked to the personal /mcp resource only and holds the one scope meinkontext:agent. It never gets /api/v2, the feedback resource, an introspection or issuer role or the key mint.
  • Binding. Only the mcp service accepts the token. It resolves the caller on every request from the verified client_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's service:<uuid> actor. Audit rows carry oauthClientId.
  • End. Revoking the agent or the credential revokes the binding and disables the oauth_client in 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.