docs(specs): add delivery package for direct profile invocation

-co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
ayattara
2026-09-14 03:26:03 +00:00
parent 0f36c0a6b0
commit f0b0ff91a4
5 changed files with 580 additions and 0 deletions
@@ -0,0 +1,99 @@
---
status: active
system: plugins
created: 2026-09-14
owners:
- kandev
---
# Plugin Direct Agent Profile Invocation Requirements
## Overview
Plugins performing a one-shot LLM step previously chose execution identity by
selecting a utility agent, which forced them to route through a secondary
configurable object and hid the actual agent profile that would run. Users
need to select the platform agent profile directly from a plugin's settings so
the profile that executes is the profile they configured, while existing
plugins that still declare the legacy `utility_agent` selector keep working.
The plugin system owns the Host invocation contract and its configuration
state; the agents system continues to own profile eligibility and utility
execution resolution.
## Terminology
- **Direct profile selection:** a plugin `config_schema` field with
`type: string` and `format: agent-profile` whose stored value is a stable
agent-profile ID executed directly by the host.
- **Legacy utility-agent selection:** an existing `config_schema` field with
`format: utility-agent` whose stored value resolves through the utility
agent catalog, unchanged for plugins that still declare it.
- **Eligibility:** enabled, non-deleted, global, non-CLI-passthrough profiles
whose agent supports sessionless inference; the backend remains
authoritative.
## Requirements
### REQ-PLUGINS-DIRECT-PROFILE-INVOCATION-001: Direct agent profile invocation for plugins
**Intent:** Let a plugin invoke one executable agent profile of the
operator's choosing without inventing a custom utility prompt, while keeping
the public Host RPC, SDK, and capability gate source-compatible and
preserving installed legacy configurations.
**User story:** As a Kandev operator configuring a plugin such as Notes, I
want to pick the agent profile that performs the plugin's LLM step directly
in the plugin's settings, so that the profile I configured is the profile
that executes and I do not have to maintain a separate custom utility
prompt.
#### Acceptance criteria
- **AC-PLUGINS-DIRECT-PROFILE-INVOCATION-001.1:** When a plugin manifest
declares a `config_schema` field with `format: agent-profile`, Settings >
Plugins shall list only eligible platform agent profiles and shall not list
utility or custom-prompt rows, so built-in and custom utility prompts with
the same or different IDs cannot be confused with executable profiles.
- **AC-PLUGINS-DIRECT-PROFILE-INVOCATION-001.2:** When the user selects a
profile, the plugin configuration shall persist that profile's stable ID
through the shared settings save path, the contributor shall become dirty
and save successfully, and a reload shall again show the selected profile's
display label.
- **AC-PLUGINS-DIRECT-PROFILE-INVOCATION-001.3:** When a profile is disabled,
deleted, workspace-scoped, or CLI-passthrough, the picker shall exclude it
from new selections and the settings surface shall represent a previously
saved unavailable selection safely and replaceably rather than failing
render.
- **AC-PLUGINS-DIRECT-PROFILE-INVOCATION-001.4:** When a plugin with
`capabilities.agent_invoke: true` invokes `Host.InvokeUtilityAgent` with a
non-empty direct `agent_profile` configuration, the host shall route the
prompt to `ExecuteProfilePrompt` using that exact profile ID and shall not
resolve or execute a utility or custom-prompt definition.
- **AC-PLUGINS-DIRECT-PROFILE-INVOCATION-001.5:** When the direct profile
selection is missing, or the selected profile is missing or ineligible at
execution time, the host shall return a typed gRPC `FailedPrecondition`
that plugins can translate into an actionable configuration message rather
than a generic execution failure.
- **AC-PLUGINS-DIRECT-PROFILE-INVOCATION-001.6:** When a plugin's
configuration holds both a direct profile and a legacy `utility_agent`
value, the direct profile shall take precedence; when only the legacy value
exists and the active manifest declares that selector, the existing
utility-agent resolution and execution behavior shall remain unchanged.
- **AC-PLUGINS-DIRECT-PROFILE-INVOCATION-001.7:** A plugin that does not
declare `capabilities.agent_invoke` shall be denied before any profile or
configuration lookup, and operational runner failures that occur after
successful configuration validation shall remain execution errors instead
of being misreported as configuration failures.
- **AC-PLUGINS-DIRECT-PROFILE-INVOCATION-001.8:** The plugin manifest and its
contract tests shall declare the agent-profile-backed setting with a
pinned field name and format, and the plugin's package metadata shall stay
internally consistent.
## Out of scope
- Changing the public `Host.InvokeUtilityAgent(ctx, prompt)` RPC or SDK
signature, or the `agent_invoke` capability-gate semantics.
- Adding new config migration; a database or schema migration is not
required for the dual-format selection.
- Changing utility-agent resolution for plugins that continue to declare
only the legacy `utility_agent` selector.
- Changing agent-profile eligibility rules owned by the agents system.
@@ -0,0 +1,107 @@
---
status: current
system: plugins
requirements:
- REQ-PLUGINS-DIRECT-PROFILE-INVOCATION-001
created: 2026-09-14
owners:
- kandev
---
# Plugin Direct Agent Profile Invocation System Design
## Purpose and boundaries
The plugin system owns the `Host.InvokeUtilityAgent` contract and the
plugin-configuration state that selects its execution identity. This design
adds a direct agent-profile selection path beside the legacy utility-agent
selection, without changing the public RPC, SDK, or capability gate. The
agents system continues to own profile eligibility and the utility execution
resolution described by
[Profile-backed Utility Agents](../../agents/system-design/utility-agent-profiles.md).
The UI system's shared settings-save coordinator and hydration contracts
remain independent dependencies, as does
[ADR 0048](../../../decisions/0048-plugin-host-utility-agent-invoke.md) for
the invocation precedence rule.
## Requirement mapping
| Requirement | Design sections |
| --- | --- |
| `REQ-PLUGINS-DIRECT-PROFILE-INVOCATION-001` | [Configuration selection](#configuration-selection), [Host execution routing](#host-execution-routing), [Eligibility and error translation](#eligibility-and-error-translation), [Legacy compatibility](#legacy-compatibility) |
## Configuration selection
`apps/web/lib/plugins/config-schema.ts` adds the `agent-profile` renderer
format beside the existing `utility-agent` format. Settings > Plugins renders
the field through the shared utility-agent profile picker component with
`agentRegistration` data, which exposes each platform profile's name, label,
workspace scope, CLI passthrough, and `inference_capable` flag.
Eligibility filtering is `utility-execution` scoped: a profile is selectable
only when it is enabled, non-deleted, global (not workspace- or
Office-scoped), not CLI passthrough, and its agent declares
`inference_capable === true`. The picker does not fall back to matching
platform profiles against utility or custom-prompt catalog rows: rows from
`/api/v1/utility/agents` are never shown in the `agent-profile` field.
Unknown or ineligible saved IDs render through the picker's unavailable
option so the stored value stays visible-and-replaceable.
File-field hydration (`plugin-config-form.tsx`) merges its backend profile
response with the current store snapshot instead of replacing the record, so
plugin config hydration and independent profile-list updates do not clobber
each other. Store-side profile-list hydration in
`use-settings-data.ts`/`hydrator.ts` compares an incoming profile snapshot
against what is already loaded and does not overwrite a higher store
revision; a WebSocket profile update triggers a retry when the list render
would otherwise go stale.
## Host execution routing
`internal/plugins/host_utility.go` resolves the invocation identity at the
start of each call, before any execution:
1. The `agent_invoke` capability gate runs first; a plugin without it is
denied before configuration or profile lookup.
2. If the manifest's `config_schema` declares a field with
`format: agent-profile` and the stored value is non-empty, that value is
the direct profile ID. The host validates the declared format first, then
resolves the profile through the agent registry: missing or ineligible
profiles return typed `FailedPrecondition` before any runner starts, so
configuration failure and operational failure remain distinct classes.
3. With a resolved eligible profile, the host calls
`ExecuteProfilePrompt(profileID, prompt)` directly on the host-utility
tier. No utility or custom-prompt definition is looked up or executed in
this path.
4. Legacy `utility_agent` routing is consulted only when no direct profile is
selected, the active manifest declares the `utility-agent` format, and the
stored legacy value passes the existing trusted-resolution checks. Its
behavior is otherwise unchanged.
`internal/backendapp/services.go` adapts the host-utility manager's typed
revalidation errors to gRPC codes: not-found/missing selection and
ineligibility surface as `FailedPrecondition`; store failures other than
not-found are returned unchanged so they remain server-side errors rather
than misleading the plugin's configuration messaging.
## Eligibility and error translation
The Notes webhook and other plugin callers translate `FailedPrecondition`
into an actionable "select an agent profile" setup message (HTTP 412) and
leave other codes (for example `Internal`) as execution failures (HTTP 502).
Service wiring in `services.go` builds the agent-profile provider from the
same registration store used by the settings API, so the picker and the
execution path judge eligibility with one source of truth. Renaming or
reflagging a profile revalidates at the next invocation; an in-flight call
keeps the configuration resolved when it started.
## Legacy compatibility
Manifests that keep only `format: utility-agent` continue to render the
utility-agent picker and persist utility prompt IDs; their stored values
resolve and execute exactly as before this change. A plugin updating its
manifest from `utility-agent` to `agent-profile` keeps its legacy value
until the operator saves a direct selection, and
`docs/decisions/0048-plugin-host-utility-agent-invoke.md` documents the
verified-transition rule that bounds the legacy fallback to trusted
pre-transition configurations. No config migration runs; both selector
formats coexist in stored plugin configuration.