v0.14.0 C4 Model: Agent Capabilities and Durable Storage

• Status: Implementing
• Target: v0.14.0
• Date: 2026-08-03
• Audience: Cognition maintainers, platform architects, security reviewers, and operators
• Category: Architectural change and feature
• Layers: 1 (Foundation), 2 (Persistence), 3 (Execution), 4 (Agent Runtime), 6 (API & Streaming), and 7 (Observability)

Purpose

This document uses the C4 model to describe the proposed v0.14.0 architecture:

1. Adopt Deep Agents 0.7.x and its current backend protocol.
2. Use Deep Agents-native Skills discovered from each Agent sandbox workspace.
3. Make remote MCP connections part of each agent's configuration and remove Cognition's global MCP-server subsystem.
4. Support database-backed durable records and S3-compatible durable file bodies without making Cognition classify or enforce a builder's deployment environment.

One agent, versioned configuration

One logical agent exists per exact effective_scope. PUT and PATCH continue to update that agent. Each successful update creates an internal, immutable configuration revision that is activated atomically; it does not create another agent. A run pins the active revision at startup, and the next run uses the latest active revision.

Intentional breaking change

v0.14.0 does not provide dual-read, dual-write, compatibility endpoints, legacy MCP transport adapters, or automatic conversion of existing skill and MCP records. Builders must redeploy agents using the new configuration shape.

Implementation is in progress on release/v0.14.0. This document is the review contract for the breaking architecture, not evidence that every acceptance criterion has already shipped.

The detailed MCP schema, transport-security profiles, readiness states, and executable security tests are defined in the v0.14.0 MCP Runtime and Authentication Contract.

C4 Scope and Notation

The document provides the five views relevant to this change:

View	Question answered
Level 1: System context	Who uses Cognition, and which external systems does it use?
Level 2: Containers	Which deployable applications and data stores make up the solution?
Level 3: Components	Which major components inside the Cognition service implement it?
Dynamic	How do configuration activation and run startup behave over time?
Deployment	Where does each container run, and how is host persistence prevented?

The diagrams use standard Mermaid shapes for compatibility with the existing MkDocs renderer. C4 defines the abstraction and relationships; it does not require a particular drawing notation. See the official C4 descriptions of system context, container, component, dynamic, and deployment diagrams.

Level 1: System Context

flowchart LR
    builder["Person / External System<br/>Builder control plane<br/><br/>Defines agents and supplies authorized scope"]
    cognition["Software System<br/>Cognition v0.14<br/><br/>Runs scoped AI agents with API, streaming, persistence, sandboxing, and observability"]
    identity["External Software System<br/>Identity service<br/><br/>Optional MCP OAuth and workload-token-exchange authority"]
    mcp["External Software System<br/>Remote MCP service or builder endpoint<br/><br/>Provides tools selected by an agent definition"]
    telemetry["External Software System<br/>Observability platform<br/><br/>Receives logs, metrics, and traces"]

    builder -->|"Deploys agents; starts sessions and runs"| cognition
    cognition -->|"OAuth or builder-provided transport auth when configured"| identity
    cognition -->|"Discovers and invokes agent-selected tools"| mcp
    cognition -->|"Exports scope-safe telemetry"| telemetry

System responsibilities

Cognition is responsible for:

• validating and serving complete agent configuration;
• carrying builder-authorized effective_scope: dict[str, str] unchanged;
• passing the builder-mounted sandbox Skills directory to Deep Agents;
• loading only an agent's declared MCP tools;
• enforcing explicit MCP authentication and endpoint policy outside model control;
• routing durable data to the builder-selected database, object, or local backend;
• isolating execution in a non-host sandbox; and
• reporting configuration, storage, MCP, and runtime behavior explicitly.

Cognition is not responsible for builder IAM, tenant authorization, roles, bindings, billing, entitlement logic, upstream provider credentials, or a general credential vault. The builder establishes authority before calling Cognition. Cognition may act as a standard MCP OAuth client or authenticate its workload to a builder-controlled endpoint.

Level 2: Container View

This logical view shows the recommended distributed container set. The deployment views later in the document show builder-selected local alternatives.

flowchart LR
    builder["External System<br/>Builder control plane"]
    identity["External System<br/>OAuth / workload identity service"]
    mcp["External System<br/>Remote MCP gateway/services"]
    obs["External System<br/>OTLP / metrics / logs platform"]

    subgraph cognition_boundary["Cognition v0.14 system boundary"]
        service["Application Container<br/>Cognition service<br/><br/>FastAPI, streaming, Deep Agents runtime"]
        database[("Data Store<br/>PostgreSQL-compatible database<br/><br/>Definitions, revisions, manifests, sessions, runs, checkpoints")]
        objects[("Data Store<br/>S3-compatible object storage<br/><br/>Artifacts, files, memories, contracts, evals, policies")]
        sandbox["Execution Container Pool<br/>Isolated sandboxes<br/><br/>Ephemeral per-session workspaces"]
    end

    builder -->|"HTTPS + exact trusted scope"| service
    service -->|"Definitions, state, manifests"| database
    service -->|"Durable file bodies"| objects
    service -->|"Commands and file transfer"| sandbox
    service -->|"Optional OAuth / token exchange"| identity
    service -->|"Streamable HTTP MCP"| mcp
    service -->|"Logs, metrics, traces"| obs

Container catalog

Container	Responsibility	Scaling and tenancy
Cognition service	API, streaming, configuration activation, runtime assembly, policy enforcement	Stateless replicas; exact scope on every request and run
Database	Transactional metadata and LangGraph durability	Canonical scope stored with every runtime-owned record
S3-compatible store	Immutable durable file bodies	Opaque scope-derived key prefixes; manifest remains the authority
Sandbox pool	Code execution and temporary workspace	Isolated per session; never the durable source of record

Recommended distributed data placement

Data class	Recommended distributed location
Agent identity, active revision, configuration manifests	Database
Sessions, runs, events, messages, checkpoints	Database
Encrypted MCP OAuth token state	Database
Skill bundles	Builder-selected files under the isolated sandbox workspace
Artifact, file, memory, contract, eval, and policy bodies	S3-compatible store
Deep Agents transient state	DB-backed checkpointer through StateBackend
Execution workspace	Ephemeral isolated sandbox
Telemetry	External stdout, OTLP, or metrics exporter

Level 3: Cognition Service Components

flowchart TB
    client["External builder or runtime client"]
    mcp_ext["Remote MCP services"]
    identity_ext["Identity service"]
    db[("Database")]
    s3[("S3-compatible store")]
    sandbox_ext["Sandbox pool"]
    obs_ext["Observability platform"]

    subgraph service["Cognition service container"]
        api["Component · Layer 6<br/>Agent and Run API<br/><br/>HTTP, validation, streaming"]
        scope["Component · Layer 1<br/>Trusted Scope Context<br/><br/>Canonical scope and correlation IDs"]
        revision["Component · Layer 4<br/>Agent Revision Coordinator<br/><br/>Validates, stages, and activates config"]
        skill["Component · Layer 3/4<br/>Sandbox Skills Contract<br/><br/>Workspace root and native discovery path"]
        resolver["Component · Layer 4<br/>Scoped Runtime Resolver<br/><br/>Pins active agent revision"]
        backend_factory["Component · Layer 4<br/>Composite Backend Factory<br/><br/>State, S3, and sandbox routes"]
        mcp_loader["Component · Layer 4<br/>MCP Tool Loader<br/><br/>Independent discovery and canonical tools"]
        mcp_security["Component · Layer 4<br/>MCP Transport Security<br/><br/>OAuth, workload identity, endpoint policy"]
        runtime["Component · Layer 4<br/>Deep Agents Runtime<br/><br/>Model, tools, skills, middleware"]
        execution["Component · Layer 3<br/>Sandbox Adapter<br/><br/>Isolated commands and transfers"]
        repository["Component · Layer 2<br/>Config and Manifest Repositories<br/><br/>Exact-scope persistence"]
        object_backend["Component · Layer 2<br/>S3 object client<br/><br/>Artifact body persistence only"]
        telemetry["Component · Layer 7<br/>Telemetry Adapters<br/><br/>Events, logs, metrics, traces"]
    end

    client --> api
    api --> scope
    api --> revision
    api --> resolver
    revision --> skill
    revision --> repository
    skill --> object_backend
    resolver --> repository
    resolver --> backend_factory
    resolver --> mcp_loader
    mcp_loader --> mcp_security
    resolver --> runtime
    backend_factory --> object_backend
    backend_factory --> execution
    runtime --> backend_factory
    runtime --> mcp_loader
    repository --> db
    object_backend --> s3
    execution --> sandbox_ext
    mcp_security --> mcp_ext
    mcp_security --> identity_ext
    mcp_security -.-> telemetry
    scope -.->|"Trusted runtime context"| revision
    scope -.->|"Trusted runtime context"| resolver
    scope -.->|"Model-invisible runtime context"| mcp_security
    api -.-> telemetry
    revision -.-> telemetry
    resolver -.-> telemetry
    object_backend -.-> telemetry
    mcp_loader -.-> telemetry
    telemetry --> obs_ext

Component responsibilities

Component	Key contract
Agent and Run API	PUT/PATCH mutate one logical agent; run creation supplies exact scope
Trusted Scope Context	Runtime authority comes from trusted ingress, never model arguments
Agent Revision Coordinator	Publishes either the old complete revision or the new complete revision
Sandbox Skills Contract	Exposes workspace_root and <workspace_root>/skills to Deep Agents; builders mount selected bundles
Scoped Runtime Resolver	Resolves active revision once and pins it for the run
Composite Backend Factory	Builds upstream-aligned artifact routes and sandbox execution
MCP Tool Loader	Discovers each declared server independently and builds canonical tool identities
MCP Transport Security	Applies endpoint-bound none, MCP OAuth, workload token exchange, or environment-backed bearer configuration for discovery and invocation
S3 object client	Stores immutable artifact/file bodies beneath database-authoritative manifests

Dynamic View 1: Update One Agent

sequenceDiagram
    autonumber
    participant B as Builder
    participant A as Agent API
    participant R as Revision Coordinator
    participant S as Skill Adapter
    participant O as S3 Store
    participant D as Database

    B->>A: PUT /agents/{name} + exact scope + complete config
    A->>R: Update logical agent
    R->>S: Validate skill bundles and MCP declarations
    S-->>R: Canonical manifest
    R->>O: Upload immutable file bodies
    O-->>R: Object keys + checksums
    R->>D: Transaction: insert inactive revision and manifests
    R->>D: Atomically set agent.active_revision
    D-->>R: Activated revision
    R-->>A: Same agent identity + new config revision
    A-->>B: 200 with active revision

    Note over R,D: A failure before activation leaves the previous revision active.
    Note over R,O: Unreferenced uploads are observable and lifecycle-cleaned.

The public operation updates one agent. Immutable revisions are an internal run-consistency, audit, and cache mechanism—not separate Agents or a public historic-version selector. A builder rollback re-submits the desired complete configuration and creates a new active snapshot.

Dynamic View 2: Start a Run

sequenceDiagram
    autonumber
    participant C as Client
    participant A as Run API
    participant R as Runtime Resolver
    participant D as Database
    participant O as S3 Backend
    participant M as MCP Tool Loader
    participant I as Transport Security
    participant X as Remote MCP
    participant G as Deep Agents Runtime

    C->>A: Start run + session + exact scope
    A->>R: Resolve scoped agent
    R->>D: Read logical agent and active revision by exact scope
    D-->>R: Agent config revision
    R->>O: Resolve skill paths and manifests
    R->>M: Build declared MCP tool set with trusted runtime context
    M->>I: Resolve each server's declared auth type
    I->>X: Per-server discovery over authenticated streamable HTTP
    X-->>M: Tools or explicit failure
    R->>G: Model + revisioned skills + tools + CompositeBackend
    G-->>A: Stream events pinned to revision
    A-->>C: SSE response

    Note over R,G: The run never changes revision mid-execution.
    Note over A,R: A later run in the same session resolves the latest active revision.

Required MCP failures stop before model execution. Optional failures emit a structured degraded-capability event and status. Authentication applies to both discovery and later invocation; readiness is a freshness-qualified observation, not authorization truth.

Deployment Views

Recommended distributed deployment: no host persistence

flowchart LR
    operator["Operator / deployment platform"]

    subgraph compute["Stateless compute cluster"]
        service["Cognition service replicas<br/>Read-only image<br/>No durable volume<br/>No local sandbox"]
    end

    subgraph execution["Isolated execution infrastructure"]
        sandboxes["Docker, Kubernetes, or Lambda MicroVM sandboxes<br/>Ephemeral session workspaces"]
    end

    subgraph data["Durable managed infrastructure"]
        postgres[("PostgreSQL-compatible database")]
        object_store[("S3-compatible object storage")]
    end

    subgraph integrations["Builder-operated integrations"]
        mcp_gateway["Remote MCP gateway/services"]
        identity["Optional identity service<br/>MCP OAuth / workload token exchange"]
        observability["OTLP / logs / metrics platform"]
    end

    operator --> service
    service --> postgres
    service --> object_store
    service --> sandboxes
    service --> mcp_gateway
    service --> identity
    service --> observability

In this topology the builder configures database, S3-compatible, external telemetry, and isolated-sandbox backends. Failure of a selected database or S3 backend must never silently select a local or memory fallback.

Cognition does not infer that a deployment is "production" or reject a builder-selected backend based on an environment classifier. Builders choose and operate the storage posture appropriate for their application.

Local and development example: host-backed storage

flowchart LR
    developer["Developer"]

    subgraph workstation["Local workstation or development container"]
        service["Cognition service<br/>Development profile"]
        local_db[("SQLite or in-memory persistence")]
        local_files[("Local filesystem or S3-compatible file backend")]
        local_sandbox["Local or Docker sandbox"]
    end

    developer --> service
    service --> local_db
    service --> local_files
    service --> local_sandbox

SQLite, in-memory persistence, local file backends, and local sandbox execution are supported. They do not require an "unsafe" override. These backends are intended for local and development setups, but Cognition does not enforce that intent. Builders own deployment classification and storage policy.

Agent Configuration Mapping

The external shape remains one complete agent definition:

This configuration and revision boundary is governed by ADR-0003: Agent-Owned Capability Revisions.

name: support-agent
skills:
  support-policy:
    files:
      SKILL.md:
        text: |
          ---
          name: support-policy
          description: Apply the support escalation policy.
          ---
          Read references/escalation.md before escalating.
      references/escalation.md:
        text: "# Escalation policy"
mcp:
  servers:
    records:
      transport: streamable_http
      url: https://mcp.example.internal/api
      required: true
      auth:
        type: mcp_oauth

Skills mapping

• Builder-selected Skill directories are mounted before sandbox initialization at <sandbox workspace root>/skills/<skill-name>/SKILL.md.
• Cognition passes that one root directly through create_deep_agent(skills=[sandbox.skills_root]); no Skill registry, inline Agent payload, private virtual route, or object-store path is used.
• scripts/, references/, and assets/ remain regular Skill bundle files; scripts execute only in the isolated sandbox, never in the Cognition process.
• The builder owns registry ingestion, validation, selection, and mounting. Cognition owns the portable sandbox workspace contract only.

MCP mapping

The authentication boundary is governed by ADR-0004: MCP Transport Authentication and Builder Authorization.

• Only servers declared by the active agent revision contribute tools.
• v0.14 supports remote streamable_http only. Legacy MCP SSE, local stdio, websocket, and stateful sessions are not accepted.
• Cognition uses the upstream MultiServerMCPClient and discovers each server independently so an optional failure cannot discard healthy tools.
• Canonical tool identity is (server_alias, provider_tool_name). Visible name rendering is deterministic and not Agent-configurable; identity or rendering collisions fail before model execution.
• The four supported authentication types are none, mcp_oauth, workload_token_exchange, and static_bearer. The environment-backed static_bearer mode is supported but not recommended; Cognition does not enforce a production classifier.
• Raw credentials, headers, API keys, custom authentication callbacks, URLs, audiences, scope, and server aliases never come from model-controlled values.
• Authentication covers discovery and invocation through Cognition's mandatory MCP client factory. LangChain interceptors provide runtime access but are not an optional Agent middleware security boundary.
• Workload token exchange authenticates the Cognition workload for one builder-selected audience/resource. A builder-controlled endpoint remains authoritative for live Agent-level authorization and upstream provider credentials.
• MCP resources and prompts are deferred; this release aligns the documented Deep Agents MCP-tools surface.

The complete schema, deployment profiles, context-projection rules, readiness model, and acceptance tests are in the MCP Runtime and Authentication Contract.

Deep Agents Backend Composition

Durable placement and backend routing are governed by ADR-0005: Durable State Placement and Backend Composition.

CompositeBackend(
    default=StateBackend(runtime),
    routes={
        "/artifacts/": artifact_backend,
        "/files/": artifact_backend,
        "/memories/": artifact_backend,
        "/contracts/": artifact_backend,
        "/evals/": artifact_backend,
        "/policies/": artifact_backend,
    },
)

The artifact persistence layer uses database manifests and optional immutable S3 object bodies. A write uploads a body, verifies its checksum, and atomically advances the manifest. ls, glob, and metadata filtering use the database index; bounded reads and grep obtain eligible object bodies. write follows the Deep Agents 0.7 overwrite contract, and delete is enabled only for routes whose policy permits it.

In local/dev, the routed S3 backend may be replaced by a local filesystem or in-memory backend. The virtual paths, scope behavior, and Deep Agents protocol remain the same across deployment profiles.

Every manifest stores canonical effective_scope, an opaque scope digest, normalized path, media type, size, checksum, version, resource class, object key, run/Agent attribution where applicable, and audit metadata. Knowledge of an object key is never authorization.

Architectural Decisions

The durable decisions are recorded in focused ADRs. This proposal retains their v0.14 delivery details and acceptance criteria.

ADR	Decision	Rationale
ADR-0003	Agent-owned capability revisions	Immutable MCP configuration, run consistency, and a builder-owned sandbox Skills boundary
ADR-0004	Standards-based MCP authentication and builder authorization	Four explicit transport modes, model-independent authentication, and live builder authorization
ADR-0005	Durable state placement and backend composition	Database manifests, immutable S3 bodies, explicit state/S3/sandbox routes, and builder-owned deployment policy

Existing-to-Target Mapping

Existing Cognition surface	v0.14 target
AgentDefinition.skills or inline Skill payload	Removed; builders mount standard bundles under <sandbox workspace>/skills
Single-string registered skill content	Removed; Skill bundles remain external filesystem packages
Standalone /skills as authoritative runtime source	Removed; the selected sandbox workspace is the runtime source
Global /mcp-servers CRUD and ConfigRegistry entity	Removed
Runtime-wide resolve_mcp_configs()	Active agent revision's MCP declarations
Custom MCP connection models and translation	Upstream client plus mandatory transport-security and per-server discovery adapters
Scope injected into MCP tool arguments	Default-deny deployment-approved context from request.runtime; never model arguments
Artifact bodies in database	Manifest in database, body in S3-compatible storage
Host workspace watchers and .cognition runtime state	Supported when selected by the builder; intended for local/dev

No automatic conversion maps global MCP or standalone skill records into agents. Builders explicitly redeploy the desired capabilities in each v0.14 agent.

Multi-Tenancy Invariants

1. Agent lookup and mutation use exact trusted scope.
2. Same-named agents in different scopes have distinct revisions, manifests, objects, MCP sets, checkpoints, caches, and sandboxes.
3. Builder-defined scope keys are preserved; no fixed user/org/project vocabulary is assumed.
4. Session and run scope is immutable. Each run also pins one agent revision.
5. Exact scope is checked before manifest access or object-store operations.
6. Scope is never model-supplied authority.
7. Read, list, update, delete, clone, export, cache, and administrative paths receive the same cross-scope tests as runtime reads.
8. Cognition quotas cover its durable objects, MCP servers, discovered tools, and concurrent discovery attempts per exact scope and agent. Builders own Skill-package quotas before mounting into a sandbox.

Research Baseline

The dependency and behavior snapshot is dated 2026-08-03:

• deepagents 0.7.1 is the v0.14 target and current release-branch resolution.
• Deep Agents skills use Agent Skills directories and backend-relative paths.
• Deep Agents MCP tools use MultiServerMCPClient.get_tools() and pass the result as agent tools.
• LangChain MCP adapters support streamable HTTP, standard authentication, per-server discovery, and runtime-aware tool interceptors.
• MCP Authorization defines the standard direct-provider OAuth path and target-resource binding.
• OAuth 2.0 Token Exchange defines the built-in workload token-exchange mode used with builder-controlled endpoints.
• Deep Agents backends provide StateBackend, StoreBackend, FilesystemBackend, CompositeBackend, and the public backend protocol.
• The Deep Agents 0.7 changelog removes compatibility shims, changes write semantics, exposes delete when supported, and tightens file-result contracts.
• langchain-mcp-adapters 0.3.1 is the v0.14 target and current release-branch resolution.

The target constraints should be compatible-minor ranges:

deepagents = "~=0.7.1"
langchain-mcp-adapters = "~=0.3.1"

Cognition's backends have been adapted to the Deep Agents 0.7 protocol on the release branch. Agent-owned MCP configuration, all four authentication modes, per-server discovery, readiness, OAuth persistence and handoff, removal of the global MCP subsystem, native sandbox Skills discovery, and removal of the standalone Skill registry are implemented. Digest-addressed S3 publication, complete database manifests, selected-backend readiness, and the durable /files/ route are in validation. The remaining work is dependency and release-image validation.

Delivery and Upgrade Boundary

Phase	Outcome
Phase 0	Approve the revised C4 and MCP contracts and finalize OpenAPI fields and builder-owned deployment configuration
Wave 1	Upgrade Deep Agents and MCP adapters; implement current backend contracts without shims
Wave 2	Add per-agent MCP, explicit auth types, per-server discovery, readiness, canonical tool identity, and remove global MCP logic
Wave 3	Add manifests, S3 object persistence, durable routes, storage health, and no-host-persistence deployment tests
Wave 4	Establish the sandbox workspace Skills contract and native Deep Agents discovery
Wave 5	Run isolation, selected-backend, breaking-surface, and release-image gates

v0.14 has no runtime or data compatibility contract with the removed skill and MCP configuration surfaces:

1. /skills mutation, /mcp-servers, global MCP resolution, legacy MCP SSE, and their registry entities are removed without adapters or dual reads.
2. Existing skill and MCP records are not loaded or converted automatically.
3. Builders deploy MCP declarations through the new Agent schema and mount selected Skill bundles into the sandbox workspace.
4. The database schema change may remove or archive obsolete records, but the v0.14 runtime never consumes them.
5. Operators that may need to return to v0.13 must take a database and object store backup before upgrading.

Internal snapshots provide run consistency but are not a public rollback or historic-selection API. A builder restores an earlier definition by submitting it again, which creates a new active snapshot. A release rollback to v0.13 requires restoring the v0.13 application and its backup; v0.14 does not emulate the old data model.

Observability

Logs, metrics, events, and traces must cover:

• agent revision validation, activation, and cache invalidation;
• skill upload, manifest commit, load, and metadata refresh;
• object-store latency, bytes, checksum failures, health, and orphan cleanup;
• MCP discovery, readiness, tool count, required failure, and optional degradation;
• rejection of removed configuration fields and endpoints; and
• selected backend identity and storage-routing readiness.

Logs and traces may contain bounded correlation identifiers, configuration revision, resource class, server alias, authentication type, and opaque scope digest. Metrics use low-cardinality dimensions only; session, run, agent, revision, server, and scope identifiers must never become metric labels. Signals must not contain raw scope values, file or skill bodies, OAuth payloads, MCP headers, credentials, tool arguments, or tool results. Readiness signals include the observation timestamp so stale discovery cannot appear current.

Risks and Mitigations

Risk	Mitigation
Deep Agents 0.7 breaks existing adapters	Complete Wave 1 backend contract tests before configuration work
An agent update exposes partial S3 state	Upload immutable bodies, then atomically activate the database manifest
A cached graph retains old capabilities	Include the active configuration revision in cache identity
Global MCP removal changes tool availability	Document the break and require explicit per-agent redeployment
Model content changes endpoint, identity, or authorization	Bind transport to validated agent configuration and trusted runtime context; never accept transport controls from tool arguments
Shared workload identity is mistaken for Agent isolation	Treat it as workload authentication only; require live builder authorization and separate workload identities where cryptographic Agent or tenant isolation is required
Revocation is delayed by cached workload tokens	Use short expiry, prohibit refresh-token persistence for this mode, and authorize every invocation at the builder endpoint
OAuth discovery expands the egress or redirect surface	Pin the configured MCP origin, validate redirects and metadata, and apply deployment DNS and egress policy
Object keys expose tenant vocabulary	Use opaque keyed scope digests and authorize through manifests
Database or S3 outage causes unintended local fallback	Fail explicitly for the selected backend; never change storage mode implicitly
Broad delete removes durable data	Exact-scope checks, route permissions, immutable bodies, delayed cleanup

Acceptance Criteria

• One exact-scope logical agent is updated atomically; revisions are internal configuration snapshots, not additional agents.
• A run pins one revision, while the next run in an existing session uses the latest active revision.
• Deep Agents discovers SKILL.md and supporting files from the routed backend; custom-subagent selection matches upstream behavior.
• Only per-agent MCP servers contribute tools. Required failure stops execution; optional failure produces visible degraded status.
• Every MCP server declares one supported authentication type: none, mcp_oauth, workload_token_exchange, or static_bearer. The environment-backed bearer mode is marked not recommended and reads only a named environment variable. Agent configuration rejects raw headers, raw tokens, arbitrary secret values, and callbacks.
• Authentication is applied uniformly to independent per-server discovery and invocation. Canonical tool identity is (server_alias, provider_tool_name), and duplicate identities fail configuration or discovery.
• Direct MCP OAuth follows the server's standard authorization flow. A workload token-exchange profile selects only builder deployment configuration, and a builder-controlled gateway receives trusted, model-invisible runtime context; externally revoked authorization denies the next invocation even during a pinned run.
• Optional server failure preserves tools from healthy servers. Required server failure stops before model execution with a typed, redacted error. Readiness becomes stale or unknown without being represented as authorization truth.
• All executable criteria in the MCP Runtime and Authentication Contract are release-blocking.
• Scope and correlation metadata comes from trusted runtime context and is absent from model-visible tool schemas and arguments.
• The global MCP routes, registry entity, runtime resolver, and custom connection translation layer are removed.
• A builder can configure a no-host-persistence topology using database, S3-compatible, external telemetry, and isolated sandbox backends.
• SQLite, in-memory persistence, local file backends, and local sandbox execution remain supported without an unsafe override or environment classifier.
• Failure of the selected database or S3 backend is explicit and never changes storage mode implicitly.
• Cross-scope tests cover agent CRUD, revisions, skills, files, caches, checkpoints, MCP, listing, and deletion for arbitrary scope keys.
• Removed APIs, registry records, legacy SSE, and global resolution have no compatibility handler, dual-read path, or automatic conversion.
• API, runtime, deployment, upgrade, security, and capability documentation is updated, and the category-specific Definition of Done in AGENTS.md is met.

Non-Goals

• Multiple agent records for configuration history
• Backward compatibility or automatic conversion for v0.13 skill and MCP records
• Cognition-managed IAM, authorization, roles, billing, or entitlements
• A general credential vault, arbitrary secret-reference API, raw credential or header injection, or provider-specific identity implementation
• Experimental OAuth delegation or a claim that one shared workload identity provides cryptographic Agent-level isolation
• Shared skill catalogs or arbitrary Agent-controlled host paths
• MCP resources, prompts, local stdio, or stateful sessions
• Durable execution workspaces on the Cognition host
• Provider-specific storage abstractions beyond the S3-compatible contract

Decision Requested

Approve this C4 model and its MCP Runtime and Authentication Contract as the revised v0.14.0 architecture baseline. After approval, update the focused ADRs and define the remaining OpenAPI schemas and implementation issues before continuing the MCP authentication work.