docs(specs): add delivery package for direct profile invocation
-co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user