> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/concepts/execution-ownership.md). # Execution ownership & fail-closed Execution ownership is the field on every capability that says **who is allowed to run it**: `algenta_managed`, where the engine executes the work server-side, or `client_managed`, where the engine refuses to run the work and hands it back to a caller-provided **adapter** to execute. It is set per provider profile (`default_execution_owner`) and constrained by what each provider declares it supports (`supported_execution_owners`), then carried on the routed capability and into the execution session. When the owner cannot be honored on a real server-side path, execution **fails closed**: the engine returns a failed session with an explicit error code instead of running the capability on a fallback or guessed path. ## Why it exists The capability plane routes a single objective across very different providers — governed datasets and Algenta runtime libraries the engine runs itself, alongside MCP tools, skills, and native tools that only the customer's environment can run. Some of those operations have side effects (calling an external system, mutating customer state). The dangerous failure is not an error; it is **silent execution on the wrong actor** — the engine quietly running something it was never meant to run, or returning an empty result that a planner treats as success. Execution ownership removes that ambiguity. Every capability carries its owner explicitly, and `POST /v1/capabilities/execute` will only run a capability whose owner is `algenta_managed` **and** for which a real server-side path exists. A `client_managed` capability never executes inside the engine — it returns a failed session telling the caller to run it through their adapter. A capability whose type has no Algenta-managed execution path returns a distinct failed session rather than a wrong-path result. There is no default that runs the work anyway. ## The two owners | Owner | Who executes | What the engine does on `execute` | | ----------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `algenta_managed` | The Algenta engine, server-side | Runs the capability if a real path exists (governed dataset summary/schema, runtime-library call, instruction skills/prompts); otherwise returns a failed session | | `client_managed` | Your adapter, in your environment | Never runs the work; returns a failed session with `client_managed_capability_requires_adapter` so your adapter executes it | ## A concrete example `POST /v1/capabilities/execute` resolves the capability, opens an execution session, and branches on the owner. You call it with the routed capability: ```json POST /v1/capabilities/execute { "capability_id": "cap_01h...", "binding_id": "bnd_01h...", "input": { } } ``` A `client_managed` capability fails closed before any provider call — the engine returns a `200` with a failed session and the deferral error code: ```json { "execution_session_id": "ses_01h...", "capability_id": "cap_01h...", "provider_id": "prv_01h...", "binding_id": "bnd_01h...", "execution_owner": "client_managed", "status": "failed", "output": null, "error": { "code": "client_managed_capability_requires_adapter", "message": "This capability is marked client_managed and must execute through a customer-provided adapter." } } ``` An `algenta_managed` capability whose kind has no server-side path also fails closed rather than running on a guessed path: ```json { "execution_session_id": "ses_01h...", "capability_id": "cap_01h...", "provider_id": "prv_01h...", "binding_id": "bnd_01h...", "execution_owner": "algenta_managed", "status": "failed", "output": null, "error": { "code": "algenta_managed_capability_not_executable", "message": "This capability type does not have an Algenta-managed execution path. Use routeCapabilities() plus the customer execution node." } } ``` A failed session surfaces over the API as a normal `200` execution response with `status: "failed"` and a populated `error` object (`code` + `message`); routing-level rejections raise the capability-plane error envelope `{"error": {"code", "message", "details"}}`. The owner-related error codes are: | Code | When it fires | | ------------------------------------------------ | ---------------------------------------------------------------------------------- | | `client_managed_capability_requires_adapter` | Owner is `client_managed`; the engine refuses and defers to your adapter | | `algenta_managed_capability_not_executable` | Owner is `algenta_managed` but the capability kind has no server-side path | | `preview_capability_not_executable` | A preview dataset capability has no concrete `dataset_id` to run | | `dataset_execution_requires_governed_query_path` | A dataset operation other than `summary`/`schema` must use the governed query path | | `runtime_library_metadata_missing` | A runtime-library capability is missing its `module`/`function` metadata | The set of owners a provider supports is declared up front (`supported_execution_owners` on the provider, `default_execution_owner` on the profile, a non-null `capability_execution_owner` column), so an unsupported or unresolved owner is rejected at configuration time rather than discovered at execution time. ## Use this when * You are calling `POST /v1/capabilities/execute` and need to know whether the engine will run the capability or hand it back to you. * You are building the **adapter** that executes `client_managed` capabilities and want the exact deferral contract and error code. * You routed an objective and the selected capability or a fallback has `execution_owner: client_managed` — that capability must run in your environment. * You got a failed execution session with `*_not_executable` or `*_requires_adapter` and need to map the code to the right next action. * You are deciding which provider profile to register and which owners it should support. ## Next {% content-ref url="/pages/bjkEhVUT4VwGkNpsxVeo" %} [The capability plane](/concepts/capability-plane.md) {% endcontent-ref %} {% content-ref url="/pages/bdxaaDSHzNrLgMm0q7zu" %} [Glossary](/help/glossary.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.algenta.ai/concepts/execution-ownership.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.