[PLAN] Define "Execution Principal" contract for sessionless, queued, and outside-in AI runs (#3573899) · Issues · project / ai

[PLAN] Define "Execution Principal" contract for sessionless, queued, and outside-in AI runs

>>> [!note] Migrated issue   Reported by: [scott falconer](https://www.drupal.org/user/52557) >>> Problem/Motivation Currently, the AI subsystem largely assumes that tool execution and access checks rely on the active web session ('\Drupal::currentUser()'). As we move toward autonomous background agents, cron runs, queue workers (Symfony Messenger), and outside-in orchestration (MCP), this assumption breaks down. Attempts to solve sessionless execution by creating "synthetic users" or performing "temporary role masquerading" (e.g., <a href="https://git.drupalcode.org/project/ai_agents/-/work_items/3518167" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/ai_agents/-/work_items/3518167</a>) introduce severe systemic risks: <ol> <li>Security & Privilege Ambiguity: Faking roles without a fully loaded, real user account bypasses core invariants. If an ephemeral role fails to revert correctly, it risks severe privilege escalation.</li> <li>Cache Poisoning: Core access checks cache against the real evaluated account. Synthetic sessions and masqueraded roles can cause cache context leaking <a href="https://www.drupal.org/project/drupal/issues/2628870" title="Status: Needs work">#2628870: Access result caching per user(.permissions) does not check for correct user</a>.</li> <li>Governance Breakdown: Revisions, audit logs, Content Moderation, and Workspaces require a stable, real user entity to track who authored a change. Ephemeral roles break this traceability.</li> </ol> In short: Because LLM agents are fundamentally non-deterministic, the platform architecture they run on must be hyper-deterministic. Proposed Resolution Establish a formal "Execution Principal" contract across the AI ecosystem. Any actor (human, background agent, or external orchestrator) performing work on the platform must be evaluated safely, deterministically, and with a clear audit trail. To achieve this, we must explicitly separate who/what caused the run from who executes the run, and formalize the execution modality. Definitions <ul> <li>Executor (Execution Principal): The real, loadable Drupal user entity the system uses for access checks and tool execution (possibly a dedicated service account for background/outside-in work).</li> <li>Initiator: The upstream origin that caused the run to exist. The initiator is not required to be a human. It can be anonymous, a system trigger (cron/queue), or an external authenticated subject (MCP/orchestration credential).</li> <li>Modality: How the run is being executed ('interactive', 'background', 'outside_in', 'scheduled'). Modality maps to a policy profile dictating which guardrails, budgets, and rate limits apply.</li> </ul> Invariants / Non-goals <ul> <li>Executor MUST be a loadable Drupal user entity (a service account is permitted and highly recommended for background/outside-in agents). </li> <li>No synthetic users and no temporary role mutation at runtime.</li> <li>Initiator MUST be recorded for provenance as an initiator descriptor:</li> <li>The system MUST capture at least one of:</li> <li> - 'initiator_uid' (may be 0), OR</li> <li> 'initiator_subject' (a string describing the authenticated credential or system trigger, e.g. 'system:cron', 'system:messenger', 'mcp:apikey:<id>', 'oauth:sub:').</id></li> <li>The initiator does not have to be a human; it is the upstream origin of the run.</li> <li>External callers MUST NOT choose executor_uid or the initiator descriptor.</li> <li> - For outside-in HTTP entry points (MCP, orchestration APIs), executor and initiator MUST be resolved server-side from trusted configuration + authenticated credentials.</li> <li> - Example: An MCP entry point maps an incoming API key or OAuth token to a designated Drupal Service Account and initiator subject via configuration, rather than trusting arbitrary fields passed in JSON payloads.</li> <li> Attribution: When an operation creates or modifies an entity, the revision author MUST be the Executor. </li> <li> The Initiator is preserved in the run metadata/logs for provenance.</li> <li>Safe Context Switching: All background/sessionless context switching MUST use core's 'account_switcher' (or a documented equivalent) and MUST switch back in a 'finally' block.</li> <li>Token Security / Token Context</li> - no token replacement on untrusted LLM outputs by default - allow-list tokens if supported - token evaluation context must be explicit (default initiator), never implicitly executor </ul> Execution Envelope / Metadata To support safe background queuing and observability (<a href="https://www.drupal.org/project/ai/issues/3533109" title="Status: Active">#3533109: [Meta] AI Logging/Observability</a>), internal dispatchers (Messenger, queues) and API boundaries must carry a standardized run metadata envelope. Strategic note: This envelope is the strict contract that every AI tool invocation flows through. It is foundational infrastructure and intentionally extensible for future AX metadata (benchmark tags, intent descriptors, behavioral observability), even if those are not in immediate scope. Required: - 'run_id' (uuid) - 'modality' ('interactive' | 'background' | 'outside_in') - Modality maps to a policy profile (e.g., rate limits, backoff rules, tool frequency limits). - mode: execute|simulate - 'executor_uid' (required; must resolve to a loadable user entity) - 'initiator_uid' (optional; may be 0) - 'initiator_subject' (optional; REQUIRED if 'initiator_uid' is not present) Optional but recommended: - 'thread_id' - environment_id (server-derived; mismatch must fail-safe before execution) - 'correlation_id' (if distinct from 'run_id') - 'caller_run_id' (if this run was spawned by another run; enables chain-of-custody) - 'source' ('ui', 'cron', 'messenger', 'mcp', 'orchestration') Definition of Done / Acceptance Criteria <ul> <li> [ ] Terminology is formally defined in AI Core architecture docs/interfaces (Initiator, Executor/Execution Principal, Modality, Run ID).</li> <li> [ ] A canonical "run metadata envelope" is specified (fields + meaning) as a class/struct/value object.</li> <li> [ ] A reference implementation path is agreed upon for:</li> <li> - How an executor is configured for autonomous agents.</li> <li> - How the envelope is propagated in Messenger payloads.</li> <li> - How outside-in entry points securely resolve incoming credentials to a local executor + initiator descriptor.</li> <li>[ ] Hard constraints are enforced in the architecture:</li> <li> - No temporary role mutation.</li> <li> - Executor must be loadable.</li> <li> - 'account_switcher' is used and always reverts ('try/finally').</li> <li>[ ] Explicit negative tests exist and are enforced:</li> <li> Context switching always reverts via 'try/finally'.</li> <li> - Negative: A run dispatched with a non-existent or invalid `executor_uid` MUST fail and halt *before* any tool execution occurs.</li> <li> - Negative: A tool call MUST NOT silently fall back to `\Drupal::currentUser()` if an execution envelope is present (preventing privilege leakage).</li> <li> - Negative: Outside-in endpoints MUST ignore/reject caller-supplied 'executor_uid' / initiator fields if maliciously provided in request bodies.</li> <li> Tool access checks evaluate strictly against the executor.</li> </ul> > Related issue: [Issue #3518167](https://www.drupal.org/node/3518167) > Related issue: [Issue #3556389](https://www.drupal.org/node/3556389) > Related issue: [Issue #3560619](https://www.drupal.org/node/3560619) > Related issue: [Issue #3493260](https://www.drupal.org/node/3493260) > Related issue: [Issue #3533109](https://www.drupal.org/node/3533109) > Related issue: [Issue #3554797](https://www.drupal.org/node/3554797) > Related issue: [Issue #3575927](https://www.drupal.org/node/3575927)

issue