fix(plugins): filter non-inference profiles

This commit is contained in:
ayattara
2026-08-24 00:49:08 +00:00
parent dce89740fe
commit 6d3f296c35
18 changed files with 114 additions and 46 deletions
@@ -27,7 +27,7 @@ func (c *Controller) GetAgent(ctx context.Context, id string) (*dto.AgentDTO, er
if err != nil {
return nil, err
}
result := toAgentDTO(agent, filterGlobalProfiles(profiles))
result := c.toAgentDTO(agent, filterGlobalProfiles(profiles))
if err := c.decorateAgentDTO(ctx, &result); err != nil {
return nil, err
}
@@ -47,7 +47,7 @@ func (c *Controller) ListAgents(ctx context.Context) (*dto.ListAgentsResponse, e
if err != nil {
return nil, err
}
entry := toAgentDTO(agent, filterGlobalProfiles(profiles))
entry := c.toAgentDTO(agent, filterGlobalProfiles(profiles))
if err := c.decorateAgentDTO(ctx, &entry); err != nil {
return nil, err
}
@@ -182,7 +182,7 @@ func (c *Controller) CreateAgent(ctx context.Context, req CreateAgentRequest) (*
if err != nil {
return nil, err
}
result := toAgentDTO(agent, profiles)
result := c.toAgentDTO(agent, profiles)
c.applyCapabilityStatus(&result, agent.Name)
return &result, nil
}
@@ -302,7 +302,7 @@ func (c *Controller) UpdateAgent(ctx context.Context, req UpdateAgentRequest) (*
if err != nil {
return nil, err
}
result := toAgentDTO(agent, filterGlobalProfiles(profiles))
result := c.toAgentDTO(agent, filterGlobalProfiles(profiles))
return &result, nil
}
@@ -116,7 +116,7 @@ func (c *Controller) CreateCustomTUIAgent(ctx context.Context, req CreateCustomT
}
profiles := []*models.AgentProfile{profile}
result := toAgentDTO(agent, profiles)
result := c.toAgentDTO(agent, profiles)
return &result, nil
}
@@ -200,6 +200,6 @@ func (c *Controller) customTUIAgentDTO(ctx context.Context, agent *models.Agent)
if err != nil {
return nil, err
}
result := toAgentDTO(agent, filterGlobalProfiles(profiles))
result := c.toAgentDTO(agent, filterGlobalProfiles(profiles))
return &result, nil
}
@@ -1052,7 +1052,7 @@ func (c *Controller) cleanupEphemeralTasks(ctx context.Context, profileID string
}
}
func toAgentDTO(agent *models.Agent, profiles []*models.AgentProfile) dto.AgentDTO {
func (c *Controller) toAgentDTO(agent *models.Agent, profiles []*models.AgentProfile) dto.AgentDTO {
profileDTOs := make([]dto.AgentProfileDTO, 0, len(profiles))
for _, profile := range profiles {
profileDTOs = append(profileDTOs, toProfileDTO(profile))
@@ -1078,6 +1078,9 @@ func toAgentDTO(agent *models.Agent, profiles []*models.AgentProfile) dto.AgentD
MCPStrategy: agent.TUIConfig.MCPStrategy,
}
}
if c.agentRegistry != nil {
_, result.InferenceCapable = c.agentRegistry.GetInferenceAgent(agent.Name)
}
return result
}
@@ -143,8 +143,11 @@ type AgentDTO struct {
// flag agents that need login or reinstallation without fetching the
// full model config separately. "" for agents that aren't probed
// (mock, tui-only).
CapabilityStatus string `json:"capability_status,omitempty"`
CapabilityError string `json:"capability_error,omitempty"`
CapabilityStatus string `json:"capability_status,omitempty"`
CapabilityError string `json:"capability_error,omitempty"`
// InferenceCapable identifies agents accepted by the sessionless host
// utility runner. Profile pickers use it to prevent invalid selections.
InferenceCapable bool `json:"inference_capable"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
+4 -3
View File
@@ -874,10 +874,11 @@ func startGatewayAndServe(
agentctlclient.WithControlAuthToken(cfg.Agent.StandaloneAuthToken))
hostUtilityMgr := hostutility.NewManager(agentRegistry, cfg.Agent.StandaloneHost, cfg.Agent.StandalonePort, hostControlClient, log)
hostUtilityMgr.SetAuthToken(cfg.Agent.StandaloneAuthToken)
hostUtilityMgr.SetProfileResolver(profilebinding.New(repos.AgentSettings, func(agentID string) bool {
pluginProfileResolver := profilebinding.New(repos.AgentSettings, func(agentID string) bool {
_, ok := agentRegistry.GetInferenceAgent(agentID)
return ok
}))
})
hostUtilityMgr.SetProfileResolver(pluginProfileResolver)
hostUtilityMgr.SetManagedRuntimeSelectionStore(services.ManagedRuntimeSelections)
// Wire the host utility manager into the settings controller so
// /api/v1/agent-models/:agentName reads live capability data.
@@ -914,7 +915,7 @@ func startGatewayAndServe(
if services.Plugins != nil && services.Utility != nil {
services.Plugins.SetUtilityAgent(
pluginsUtilityAgentAdapter{svc: services.Utility, userSvc: services.User},
pluginsAgentProfileAdapter{store: repos.AgentSettings},
pluginsAgentProfileAdapter{resolver: pluginProfileResolver},
pluginsHostUtilityAdapter{mgr: hostUtilityMgr},
)
}
+12 -8
View File
@@ -1110,22 +1110,25 @@ type pluginsUtilityAgentAdapter struct {
userSvc *userservice.Service
}
type pluginAgentProfileStore interface {
GetAgentProfile(ctx context.Context, id string) (*agentsettingsmodels.AgentProfile, error)
type pluginAgentProfileResolver interface {
Resolve(ctx context.Context, id string) (*agentsettingsmodels.AgentProfile, error)
}
// pluginsAgentProfileAdapter keeps agent-settings storage errors at the
// backend boundary. The plugins package only receives the narrow execution
// eligibility record and its typed missing-profile sentinel.
type pluginsAgentProfileAdapter struct {
store pluginAgentProfileStore
resolver pluginAgentProfileResolver
}
func (a pluginsAgentProfileAdapter) GetProfileByID(ctx context.Context, id string) (*plugins.AgentProfile, error) {
profile, err := a.store.GetAgentProfile(ctx, id)
if errors.Is(err, sql.ErrNoRows) {
profile, err := a.resolver.Resolve(ctx, id)
if errors.Is(err, sql.ErrNoRows) || errors.Is(err, profilebinding.ErrProfileNotFound) {
return nil, plugins.ErrAgentProfileNotFound
}
if errors.Is(err, profilebinding.ErrProfileIneligible) {
return nil, plugins.ErrAgentProfileIneligible
}
if err != nil {
return nil, err
}
@@ -1133,9 +1136,10 @@ func (a pluginsAgentProfileAdapter) GetProfileByID(ctx context.Context, id strin
return nil, plugins.ErrAgentProfileNotFound
}
return &plugins.AgentProfile{
Enabled: profile.Enabled,
CLIPassthrough: profile.CLIPassthrough,
WorkspaceID: profile.WorkspaceID,
Enabled: profile.Enabled,
CLIPassthrough: profile.CLIPassthrough,
WorkspaceID: profile.WorkspaceID,
InferenceCapable: true,
}, nil
}
@@ -14,6 +14,7 @@ import (
userService "github.com/kandev/kandev/internal/user/service"
userStore "github.com/kandev/kandev/internal/user/store"
utilitymodels "github.com/kandev/kandev/internal/utility/models"
"github.com/kandev/kandev/internal/utility/profilebinding"
utilityservice "github.com/kandev/kandev/internal/utility/service"
utilitystore "github.com/kandev/kandev/internal/utility/store"
)
@@ -80,7 +81,7 @@ func TestPluginsUtilityAgentAdapter_ResolvesEmptyBuiltinThroughDefault(t *testin
}
func TestPluginsAgentProfileAdapter_MapsTypedNotFound(t *testing.T) {
adapter := pluginsAgentProfileAdapter{store: &pluginAgentProfileStoreStub{err: sql.ErrNoRows}}
adapter := pluginsAgentProfileAdapter{resolver: &pluginAgentProfileResolverStub{err: sql.ErrNoRows}}
_, err := adapter.GetProfileByID(context.Background(), "missing")
if !errors.Is(err, plugins.ErrAgentProfileNotFound) {
@@ -90,7 +91,7 @@ func TestPluginsAgentProfileAdapter_MapsTypedNotFound(t *testing.T) {
func TestPluginsAgentProfileAdapter_PreservesOperationalFailure(t *testing.T) {
storeErr := errors.New("agent profile database unavailable")
adapter := pluginsAgentProfileAdapter{store: &pluginAgentProfileStoreStub{err: storeErr}}
adapter := pluginsAgentProfileAdapter{resolver: &pluginAgentProfileResolverStub{err: storeErr}}
_, err := adapter.GetProfileByID(context.Background(), "configured")
if !errors.Is(err, storeErr) {
@@ -99,7 +100,7 @@ func TestPluginsAgentProfileAdapter_PreservesOperationalFailure(t *testing.T) {
}
func TestPluginsAgentProfileAdapter_PreservesEligibilityFields(t *testing.T) {
adapter := pluginsAgentProfileAdapter{store: &pluginAgentProfileStoreStub{profile: &agentsettingsmodels.AgentProfile{
adapter := pluginsAgentProfileAdapter{resolver: &pluginAgentProfileResolverStub{profile: &agentsettingsmodels.AgentProfile{
Enabled: true,
CLIPassthrough: false,
WorkspaceID: "",
@@ -109,22 +110,31 @@ func TestPluginsAgentProfileAdapter_PreservesEligibilityFields(t *testing.T) {
if err != nil {
t.Fatalf("GetProfileByID() error = %v", err)
}
if !got.Enabled || got.CLIPassthrough || got.WorkspaceID != "" {
if !got.Enabled || got.CLIPassthrough || got.WorkspaceID != "" || !got.InferenceCapable {
t.Fatalf("GetProfileByID() = %+v, want an eligible profile", got)
}
}
func TestPluginsAgentProfileAdapter_MapsIneligibleProfile(t *testing.T) {
adapter := pluginsAgentProfileAdapter{resolver: &pluginAgentProfileResolverStub{err: profilebinding.ErrProfileIneligible}}
_, err := adapter.GetProfileByID(context.Background(), "not-inference-capable")
if !errors.Is(err, plugins.ErrAgentProfileIneligible) {
t.Fatalf("GetProfileByID() error = %v, want plugin ineligible error", err)
}
}
type utilityAgentRepositoryStub struct {
utilitystore.Repository
agent *utilitymodels.UtilityAgent
}
type pluginAgentProfileStoreStub struct {
type pluginAgentProfileResolverStub struct {
profile *agentsettingsmodels.AgentProfile
err error
}
func (s *pluginAgentProfileStoreStub) GetAgentProfile(context.Context, string) (*agentsettingsmodels.AgentProfile, error) {
func (s *pluginAgentProfileResolverStub) Resolve(context.Context, string) (*agentsettingsmodels.AgentProfile, error) {
return s.profile, s.err
}
+12 -4
View File
@@ -30,6 +30,10 @@ var ErrUtilityAgentNotFound = errors.New("utility agent not found")
// profile and translate it into the configured-plugin failure contract.
var ErrAgentProfileNotFound = errors.New("agent profile not found")
// ErrAgentProfileIneligible lets backend adapters return the same typed
// eligibility result used by the sessionless host-utility profile resolver.
var ErrAgentProfileIneligible = errors.New("agent profile is not eligible for utility execution")
// UtilityAgent is the execution-relevant portion of a configured utility
// agent. backendapp adapts internal/utility/service.Service to this shape.
type UtilityAgent struct {
@@ -48,9 +52,10 @@ type utilityAgentSource interface {
// AgentProfile is the execution-relevant portion of a direct profile
// selection. backendapp adapts the agent-settings repository to this shape.
type AgentProfile struct {
Enabled bool
CLIPassthrough bool
WorkspaceID string
Enabled bool
CLIPassthrough bool
WorkspaceID string
InferenceCapable bool
}
type agentProfileSource interface {
@@ -142,6 +147,9 @@ func (h *pluginHost) invokeConfiguredAgentProfile(
if errors.Is(err, ErrAgentProfileNotFound) {
return "", status.Errorf(codes.FailedPrecondition, "configured agent profile %q not found", profileID)
}
if errors.Is(err, ErrAgentProfileIneligible) {
return "", status.Errorf(codes.FailedPrecondition, "configured agent profile %q is not eligible for utility execution", profileID)
}
if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
return "", status.FromContextError(err).Err()
}
@@ -154,7 +162,7 @@ func (h *pluginHost) invokeConfiguredAgentProfile(
if profile == nil {
return "", status.Errorf(codes.FailedPrecondition, "configured agent profile %q not found", profileID)
}
if !profile.Enabled || profile.CLIPassthrough || profile.WorkspaceID != "" {
if !profile.Enabled || profile.CLIPassthrough || profile.WorkspaceID != "" || !profile.InferenceCapable {
return "", status.Errorf(codes.FailedPrecondition, "configured agent profile %q is not eligible for utility execution", profileID)
}
return runner.ExecuteProfilePrompt(ctx, profileID, prompt)
@@ -88,7 +88,7 @@ func TestPluginHost_InvokeUtilityAgent_UsesConfiguredAgentProfileBeforeUtilityAg
utilityAgentConfigKey: "utility-agent-42",
}}
d.profiles.profilesByID = map[string]*AgentProfile{
"profile-99": {Enabled: true},
"profile-99": {Enabled: true, InferenceCapable: true},
}
got, err := d.host.InvokeUtilityAgent(context.Background(), "summarize yesterday")
@@ -164,19 +164,19 @@ func TestPluginHost_InvokeUtilityAgent_RejectsMissingOrIneligibleConfiguredAgent
{
name: "disabled profile",
config: map[string]any{agentProfileConfigKey: "disabled-profile"},
profiles: map[string]*AgentProfile{"disabled-profile": {Enabled: false}},
profiles: map[string]*AgentProfile{"disabled-profile": {Enabled: false, InferenceCapable: true}},
want: `configured agent profile "disabled-profile" is not eligible for utility execution`,
},
{
name: "CLI profile",
config: map[string]any{agentProfileConfigKey: "cli-profile"},
profiles: map[string]*AgentProfile{"cli-profile": {Enabled: true, CLIPassthrough: true}},
profiles: map[string]*AgentProfile{"cli-profile": {Enabled: true, CLIPassthrough: true, InferenceCapable: true}},
want: `configured agent profile "cli-profile" is not eligible for utility execution`,
},
{
name: "workspace profile",
config: map[string]any{agentProfileConfigKey: "workspace-profile"},
profiles: map[string]*AgentProfile{"workspace-profile": {Enabled: true, WorkspaceID: "workspace-1"}},
profiles: map[string]*AgentProfile{"workspace-profile": {Enabled: true, WorkspaceID: "workspace-1", InferenceCapable: true}},
want: `configured agent profile "workspace-profile" is not eligible for utility execution`,
},
} {
@@ -206,6 +206,27 @@ func TestPluginHost_InvokeUtilityAgent_RejectsMissingOrIneligibleConfiguredAgent
}
}
func TestPluginHost_InvokeUtilityAgent_DirectProfileRejectsNonInferenceProfile(t *testing.T) {
d := configuredUtilityHost(t)
d.host.configSchema = map[string]any{
"properties": map[string]any{
agentProfileConfigKey: map[string]any{"type": "string", "format": "agent-profile"},
},
}
d.host.configs = &fakeConfigReader{configs: map[string]any{agentProfileConfigKey: "profile-no-inference"}}
d.profiles.profilesByID = map[string]*AgentProfile{"profile-no-inference": {
Enabled: true, InferenceCapable: false,
}}
_, err := d.host.InvokeUtilityAgent(context.Background(), "hi")
if status.Code(err) != codes.FailedPrecondition {
t.Fatalf("InvokeUtilityAgent() status = %s, want %s", status.Code(err), codes.FailedPrecondition)
}
if d.utilRun.calls != 0 {
t.Fatalf("runner calls = %d, want 0", d.utilRun.calls)
}
}
func TestPluginHost_InvokeUtilityAgent_PreservesDirectProfileRunnerFailure(t *testing.T) {
runnerErr := status.Error(codes.Unavailable, "agentctl unavailable")
d := configuredUtilityHost(t)
@@ -215,7 +236,7 @@ func TestPluginHost_InvokeUtilityAgent_PreservesDirectProfileRunnerFailure(t *te
},
}
d.host.configs = &fakeConfigReader{configs: map[string]any{agentProfileConfigKey: "profile-99"}}
d.profiles.profilesByID = map[string]*AgentProfile{"profile-99": {Enabled: true}}
d.profiles.profilesByID = map[string]*AgentProfile{"profile-99": {Enabled: true, InferenceCapable: true}}
d.utilRun.err = runnerErr
_, err := d.host.InvokeUtilityAgent(context.Background(), "summarize")
@@ -54,12 +54,13 @@ function renderField(
}
describe("PluginConfigForm agent profile field", () => {
it("offers only enabled global non-CLI profiles and stores the stable ID", () => {
it("offers only enabled global non-CLI inference profiles and stores the stable ID", () => {
const onChange = renderField([
profile({ id: "eligible", label: ELIGIBLE_PROFILE_LABEL }),
profile({ id: "disabled", label: "Disabled", enabled: false }),
profile({ id: "workspace", label: "Workspace", workspace_id: "workspace-1" }),
profile({ id: "cli", label: "CLI", cli_passthrough: true }),
profile({ id: "non-inference", label: "Non-inference", inference_capable: false }),
]);
fireEvent.click(screen.getByRole("combobox"));
@@ -68,6 +69,7 @@ describe("PluginConfigForm agent profile field", () => {
expect(screen.queryByRole("option", { name: "Disabled" })).toBeNull();
expect(screen.queryByRole("option", { name: "Workspace" })).toBeNull();
expect(screen.queryByRole("option", { name: "CLI" })).toBeNull();
expect(screen.queryByRole("option", { name: "Non-inference" })).toBeNull();
fireEvent.click(screen.getByRole("option", { name: ELIGIBLE_PROFILE_LABEL }));
expect(onChange).toHaveBeenCalledWith(AGENT_PROFILE_FIELD, "eligible");
@@ -19,6 +19,7 @@ describe("utilityProfileEligibility", () => {
["disabled profile", profile({ enabled: false }), false],
["CLI passthrough profile", profile({ cli_passthrough: true }), false],
["workspace profile", profile({ workspace_id: "workspace-1" }), false],
["non-inference profile", profile({ inference_capable: false }), false],
])("returns %s = %s", (_label, candidate, expected) => {
expect(utilityProfileEligibility(candidate)).toBe(expected);
});
@@ -10,6 +10,7 @@ export const utilityProfileEligibility = (
includeWorkspaceProfiles = false,
) =>
profile.enabled !== false &&
profile.inference_capable !== false &&
(dynamicRoutingEnabled || profile.kind !== "dynamic") &&
(includeWorkspaceProfiles || (!profile.cli_passthrough && !profile.workspace_id));
@@ -24,6 +24,7 @@ describe("toAgentProfileOption", () => {
name: "claude-acp",
capability_status: undefined,
capability_error: undefined,
inference_capable: true,
};
it("maps enabled from the profile and defaults to true when absent", () => {
@@ -34,6 +35,7 @@ describe("toAgentProfileOption", () => {
enabled: false,
});
expect(enabled.enabled).toBe(false);
expect(enabled.inference_capable).toBe(true);
const legacy = toAgentProfileOption(agent, {
id: agentProfileId("p2"),
+7 -1
View File
@@ -51,6 +51,8 @@ export type AgentProfileOption = {
agent_name: string;
kind?: AgentProfileKind;
cli_passthrough: boolean;
/** Whether the profile's agent supports sessionless inference. */
inference_capable?: boolean;
/** Configured start model (ACP model ID). Empty = agent default. */
model?: string;
/** Optional explicit fallback model; ignored when auto_fallback is on. */
@@ -255,7 +257,10 @@ export function refreshSettingsAgentsCapabilities(
/** Single source of truth for mapping an API Agent+Profile to a store AgentProfileOption. */
export function toAgentProfileOption(
agent: Pick<Agent, "id" | "name" | "capability_status" | "capability_error">,
agent: Pick<
Agent,
"id" | "name" | "capability_status" | "capability_error" | "inference_capable"
>,
profile: Pick<AgentProfile, "id" | "agentDisplayName" | "name" | "workspaceId"> & {
updatedAt?: string;
kind?: AgentProfileKind;
@@ -273,6 +278,7 @@ export function toAgentProfileOption(
agent_name: agent.name,
kind: profile.kind,
cli_passthrough: profile.cliPassthrough ?? false,
inference_capable: agent.inference_capable,
model: profile.model ?? undefined,
fallback_model: profile.fallbackModel ?? undefined,
auto_fallback: profile.autoFallback ?? undefined,
+2
View File
@@ -58,6 +58,8 @@ export type Agent = {
*/
capability_status?: CapabilityStatus;
capability_error?: string;
/** Whether this agent supports sessionless host-utility inference. */
inference_capable?: boolean;
created_at: string;
updated_at: string;
};
@@ -31,8 +31,9 @@ configuration and the existing host-utility tier.
1. **Plugin config: direct profile first.** Plugins declaring `agent_invoke`
can declare an `agent_profile` field with `type: string` and
`format: agent-profile`. Settings > Plugins renders enabled, global,
non-CLI profiles and stores the selected stable ID. A missing, deleted,
disabled, CLI-passthrough, or workspace-scoped profile is a
non-CLI profiles whose agent supports sessionless inference and stores the
selected stable ID. A missing, deleted, disabled, CLI-passthrough,
workspace-scoped, or non-inference profile is a
`FailedPrecondition`. A non-empty declared `agent_profile` is the direct
execution selection and takes precedence over `utility_agent`; when it is
unset, the legacy selection remains available.
+7 -5
View File
@@ -805,13 +805,15 @@ config_schema:
required: ["agent_profile"]
```
The picker displays enabled global non-CLI profiles and stores the selected
profile's stable ID. Omit `agent_profile` from `required` only when the plugin
The picker displays enabled global non-CLI profiles whose agent supports
sessionless inference and stores the selected profile's stable ID. Omit
`agent_profile` from `required` only when the plugin
supports operating without LLM delegation; optional selectors include a
**Not set** choice. The plugin needs no provider API key because it delegates
to a kandev-configured agent. A missing, deleted, disabled, CLI-passthrough, or
workspace-scoped selection returns gRPC `FailedPrecondition`, so handle that as
"ask the operator to configure one" rather than a transient failure.
to a kandev-configured agent. A missing, deleted, disabled, CLI-passthrough,
workspace-scoped, or non-inference selection returns gRPC `FailedPrecondition`,
so handle that as "ask the operator to configure one" rather than a transient
failure.
Existing plugins may continue to declare `utility_agent` with
`format: utility-agent`; Kandev resolves that utility agent's effective
+3 -2
View File
@@ -158,7 +158,7 @@ ui: # optional native frontend plugin
| `capabilities.api_write` | no | string[] | Gates Host writes independently of `api_read`. `tasks` permits `Host.Tasks().Create` and `.Update`; `messages` permits `Host.Messages().Send`. Undeclared writes return gRPC `PermissionDenied`. |
| `capabilities.state` | no | bool | Gates `Host.GetState`/`SetState`/`DeleteState`/`ListState`. Calling any of them without this set to `true` returns gRPC `PermissionDenied`. |
| `capabilities.secrets` | no | bool | Gates `Host.RevealSecret`/`GetSecret`/`SetSecret`/`DeleteSecret`. Calling any of them without this set to `true` returns gRPC `PermissionDenied`. |
| `capabilities.agent_invoke` | no | bool | Gates `Host.InvokeUtilityAgent`: a one-shot completion for this plugin. Declare either `agent_profile` with `type: string` and `format: agent-profile`, or the legacy `utility_agent` format. The direct picker stores a stable global, enabled, non-CLI profile ID; a non-empty declared `agent_profile` takes precedence, while an unset value falls back to legacy `utility_agent`. Calling without this capability returns gRPC `PermissionDenied`; a missing, deleted, disabled, CLI-passthrough, or workspace-scoped non-empty direct selection returns gRPC `FailedPrecondition`. See ADR 0048. |
| `capabilities.agent_invoke` | no | bool | Gates `Host.InvokeUtilityAgent`: a one-shot completion for this plugin. Declare either `agent_profile` with `type: string` and `format: agent-profile`, or the legacy `utility_agent` format. The direct picker stores a stable global, enabled, non-CLI profile ID whose agent supports sessionless inference; a non-empty declared `agent_profile` takes precedence, while an unset value falls back to legacy `utility_agent`. Calling without this capability returns gRPC `PermissionDenied`; a missing, deleted, disabled, CLI-passthrough, workspace-scoped, or non-inference non-empty direct selection returns gRPC `FailedPrecondition`. See ADR 0048. |
| `capabilities.auth` | no | bool | Lets the plugin log a visitor in against an external IdP (OIDC/SAML). Its webhook validates the token, then asserts the identity to Kandev via the `X-Kandev-Auth-Login` response header (`{provider, subject, email, display_name}`); Kandev mints the session and sets the cookie, so the plugin never sees the token. Requires authentication enabled; new users are provisioned as members, and Kandev never creates an admin nor auto-links to an existing admin account. **You MUST only assert an email the IdP verified as owned by the subject; a spoofed email claim is account takeover.** Highest-privilege capability; grant only to trusted plugins. See ADR 0050. |
| `capabilities.user_state` | no | bool | Gates `host.storage` (`get`/`set`/`delete`/`list`/`subscribe`), the authenticated per-user browser storage surface at `/api/plugins/{id}/user-state/...`. Unlike `capabilities.state` (the gRPC `Host.SetState` family, written by the plugin's own backend), this is reachable directly from the plugin's frontend bundle with no Go backend required; every read/write is scoped to the calling user. Calling the route without this capability returns `403`. See [Authoring a plugin](plugins-authoring.md) and the per-user-plugin-storage decision record. |
| `webhooks[].key` | yes | string | Must be unique within the manifest. Used in the relay path `POST /api/plugins/{id}/webhooks/{key}`. |
@@ -262,7 +262,8 @@ persisting:
when the plugin must always have a selection; optional fields include a
**Not set** choice.
- A string property named `agent_profile` with `format: agent-profile` is
rendered as a picker of enabled, global, non-CLI agent profiles. The UI
rendered as a picker of enabled, global, non-CLI agent profiles whose agent
supports sessionless inference. The UI
stores the stable profile ID and keeps a stale saved value visible but
unavailable. It is the direct selection used by `Host.InvokeUtilityAgent`;
when both selectors are declared, a non-empty direct value wins and an unset