Alassane
cc33b2a813
Co-authored-by: ayattara <alassane.yattara@savoirfairelinux.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
51 lines
3.7 KiB
Markdown
51 lines
3.7 KiB
Markdown
---
|
|
status: active
|
|
system: plugins
|
|
created: 2026-09-14
|
|
owners:
|
|
- kandev
|
|
---
|
|
|
|
# Explicit Plugin Utility Invocation Requirements
|
|
|
|
## Overview
|
|
|
|
The plugin system owns the public Host invocation contract. Agent settings own profiles and the platform default utility profile.
|
|
A plugin can save a preferred profile in its configuration. It must pass that preference explicitly when it requests a completion.
|
|
These requirements replace REQ-PLUGINS-DIRECT-PROFILE-INVOCATION-001. The user accepted this direction after review of PR #2870.
|
|
The implementation and verification are recorded in the [implementation plan](../../../plans/plugin-explicit-utility-invocation/plan.md).
|
|
|
|
## Terminology
|
|
|
|
- **Default profile:** the profile selected in Settings > Utility Agents under Default utility agent model.
|
|
- **Override:** an agent-profile ID supplied in a single invocation. It is not a utility-agent record ID.
|
|
- **Plugin preference:** a profile ID saved by the plugin through the existing configuration service.
|
|
- **Utility completion:** one prompt and one text response, without a task session or caller-selected working directory.
|
|
|
|
## Requirements
|
|
|
|
### REQ-PLUGINS-EXPLICIT-UTILITY-001: Explicit utility execution selection
|
|
|
|
**Intent:** Make execution selection visible in the invocation contract and keep plugin configuration ownership with the caller.
|
|
|
|
#### Acceptance criteria
|
|
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.1:** When the caller omits an override or supplies an empty profile ID, the host shall use the current default profile.
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.2:** When the caller supplies an eligible profile ID, the host shall use that exact profile, independent of the default.
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.3:** Plugin configuration, field names, manifest selectors, and legacy transition metadata shall not determine invocation selection.
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.4:** A missing or ineligible explicit override shall return FailedPrecondition without executing a different profile.
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.5:** An unset, missing, or ineligible default shall return FailedPrecondition when the caller omits an override.
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.6:** Without agent_invoke permission, the call shall fail before settings access, profile lookup, or execution.
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.7:** Cancellation and operational failures shall remain distinct from configuration failures. No failure shall trigger implicit profile fallback.
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.8:** Changes to the default shall affect subsequent default invocations. A default change shall not redirect an explicit override or an invocation already dispatched.
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.9:** The plugin shall read its saved preference and pass it explicitly. Saving, clearing, and reloading a preference shall preserve that behavior.
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.10:** A host that cannot honor the explicit selection contract shall reject the new client call before execution. It shall not silently ignore an override.
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.11:** Existing prompt-only clients on the revised host shall use the platform default. Migration documentation shall state this behavior change.
|
|
- **AC-PLUGINS-EXPLICIT-UTILITY-001.12:** Invocation shall remain a single text completion. It shall not create a task, session, or worktree, or accept a caller-selected working directory.
|
|
|
|
## Out of scope
|
|
|
|
- General agent execution, cwd, streaming, tools, session lifecycle, and arbitrary execution options.
|
|
- Changes to eligibility: profiles remain enabled, global, non-CLI-passthrough, and explicitly inference-capable.
|
|
- UI redesign, new configuration storage, automatic conversion of utility-agent record IDs into profile IDs, or new capability grants.
|