Files
coder/coderd/agentapi/manifest.go
J. Scott MillerandGarrett Delfosse 38e74c4506 feat: add agent-plugins experiment and Agent API v2.17 plugin messages (#29320)
Linear:
[CODAGT-1101](https://linear.app/codercom/issue/CODAGT-1101/agent-plugins-read-only-support-behind-the-agent-plugins-experiment)

**tl;dr:** Adds the `agent-plugins` experiment and the Agent API v2.17
messages that carry Agent Plugins data from the agent to coderd. First
of eight stacked PRs adding read-only [Agent
Plugins](https://agent-plugins.org/) v1.0.0 support.

A plugin is a directory with a `plugin.json` manifest, skills under
`skills/`, and an optional `mcp.json`. Across the stack, the agent
discovers plugins in `plugins/` and `.agents/plugins/` under its scan
roots (for example `~/.coder/plugins/<name>`), chatd lists their skills
with plugin attribution, the agent runs the MCP servers of plugins in
the workspace working directory, and the Agents page shows plugin
attribution in the chat context. Hooks, commands, agents, install flows,
and org-managed plugins are out of scope. Background:
[research/agent-plugins-standard.md](https://github.com/coder/scott-misc/blob/main/research/agent-plugins-standard.md)
(internal).

This PR adds `codersdk.ExperimentAgentPlugins` and a `PluginBody` oneof
variant on `ContextResource` (tag 18) that carries the validated
manifest fields and nests the plugin's skills and MCP servers.
`Manifest` gains `agent_plugins_enabled` (field 23), which coderd sets
when the experiment is enabled; the agent discovers plugins only then.
coderd stores each nested resource as its own row with the plugin's name
in a new `plugin_name` column (migration 000642), which the hydrate, MCP
sync, and re-pin queries copy. With the experiment off,
`PushContextState` drops plugin resources and everything nested in them.
Otherwise it rejects pushes with plugin names that fail
`workspacesdk.ValidatePluginName` (the spec's name grammar, shared by
agent and coderd), OK plugins without a name or with a duplicate name, a
non-OK plugin that nests resources, nested entries of the wrong kind,
plugin skill sources outside `<plugin source>/skills/`, and plugin MCP
servers with an empty `server_name` or a source other than `<plugin
name>/<server_name>`. Nested resources count toward the 1000-resource
cap.

Agents now dial v2.17, so a new agent needs a coderd that supports it,
as with every Agent API minor. Turning the experiment off does not
remove plugin data already pinned to existing chats.

<!-- pr-map:start -->
<details><summary>PR map</summary>

`main..4b0cfc9657`

| Category | Files | + | - |
|---|---:|---:|---:|
| prod (backend) | 15 | 342 | 78 |
| test (backend) | 9 | 534 | 3 |
| migrations | 2 | 14 | 0 |
| generated (backend) | 7 | 1216 | 1027 |
| generated (frontend) | 1 | 2 | 0 |
| **Total** | 34 | 2108 | 1108 |

1. `coderd/agentapi/context.go` (+211/-51, API): drops plugin resources
when the experiment is off; otherwise validates plugin names and
nesting, and stores each nested skill and MCP server as its own row with
the plugin's name.
2. `agent/proto/agent.proto` (+39/-9, API): `PluginBody` with nested
`skills` and `mcp_servers`, and `Manifest.agent_plugins_enabled`.
3. `codersdk/workspacesdk/frontmatter.go` (+31/-0): `ValidatePluginName`
and `MaxPluginNameLength` (manifest name grammar).
4. `coderd/database/queries/chats.sql`, `workspaceagentcontext.sql`,
migration 000642 (+28/-7, DB): the `plugin_name` column on both context
resource tables, copied by the hydrate, MCP sync, and re-pin queries.
5. `codersdk/agentsdk/agentsdk.go`, `agent/agent.go` (+18/-4, API):
`Manifest.AgentPluginsEnabled` and `ConnectRPC217WithRole`; the agent
dials v2.17.
6. `coderd/agentapi/api.go`, `manifest.go` (+4): the manifest flag
follows the experiment.
7. `tailnet/proto/version.go` (+8/-1, API): Agent API v2.17.
8. `codersdk/deployment.go` (+4, API): the `agent-plugins` experiment.

</details>
<!-- pr-map:end -->

---

This PR was generated by Coder Agents on behalf of @jscottmiller.

Co-authored-by: Garrett Delfosse <delfossegarrett@gmail.com>
2026-11-13 10:39:16 -05:00

386 lines
14 KiB
Go

package agentapi
import (
"context"
"database/sql"
"errors"
"net/url"
"strings"
"time"
"github.com/google/uuid"
"golang.org/x/sync/errgroup"
"golang.org/x/xerrors"
"google.golang.org/protobuf/types/known/durationpb"
"tailscale.com/tailcfg"
agentproto "github.com/coder/coder/v2/agent/proto"
"github.com/coder/coder/v2/coderd/database"
"github.com/coder/coder/v2/coderd/database/db2sdk"
"github.com/coder/coder/v2/coderd/database/dbauthz"
"github.com/coder/coder/v2/coderd/externalauth"
"github.com/coder/coder/v2/coderd/workspaceapps/appurl"
"github.com/coder/coder/v2/coderd/workspacesecrets"
"github.com/coder/coder/v2/codersdk"
"github.com/coder/coder/v2/tailnet"
)
type ManifestAPI struct {
AccessURL *url.URL
AppHostname string
ExternalAuthConfigs []*externalauth.Config
DisableDirectConnections bool
DerpForceWebSockets bool
DisableUserSecretFilePath bool
AgentPluginsEnabled bool
WorkspaceID uuid.UUID
// WorkspaceBuildID is the build that created the agent. Its live secrets
// are delivered in the manifest.
WorkspaceBuildID uuid.UUID
AgentFn func(ctx context.Context) (database.WorkspaceAgent, error)
Database database.Store
DerpMapFn func() *tailcfg.DERPMap
}
func (a *ManifestAPI) GetManifest(ctx context.Context, _ *agentproto.GetManifestRequest) (*agentproto.Manifest, error) {
var (
dbApps []database.WorkspaceApp
scripts []database.GetWorkspaceAgentScriptsByAgentIDsRow
metadata []database.WorkspaceAgentMetadatum
workspace database.Workspace
devcontainers []database.WorkspaceAgentDevcontainer
)
workspaceAgent, err := a.AgentFn(ctx)
if err != nil {
return nil, xerrors.Errorf("getting workspace agent: %w", err)
}
var eg errgroup.Group
eg.Go(func() (err error) {
dbApps, err = a.Database.GetWorkspaceAppsByAgentID(ctx, workspaceAgent.ID)
if err != nil && !xerrors.Is(err, sql.ErrNoRows) {
return err
}
return nil
})
eg.Go(func() (err error) {
// nolint:gocritic // This is necessary to fetch agent scripts!
scripts, err = a.Database.GetWorkspaceAgentScriptsByAgentIDs(dbauthz.AsSystemRestricted(ctx), []uuid.UUID{workspaceAgent.ID})
return err
})
eg.Go(func() (err error) {
metadata, err = a.Database.GetWorkspaceAgentMetadata(ctx, database.GetWorkspaceAgentMetadataParams{
WorkspaceAgentID: workspaceAgent.ID,
Keys: nil, // all
})
return err
})
eg.Go(func() (err error) {
workspace, err = a.Database.GetWorkspaceByID(ctx, a.WorkspaceID)
if err != nil {
return xerrors.Errorf("getting workspace by id: %w", err)
}
return err
})
eg.Go(func() (err error) {
devcontainers, err = a.Database.GetWorkspaceAgentDevcontainersByAgentID(ctx, workspaceAgent.ID)
if err != nil && !errors.Is(err, sql.ErrNoRows) {
return err
}
return nil
})
err = eg.Wait()
if err != nil {
return nil, xerrors.Errorf("fetching workspace agent data: %w", err)
}
// Fetch user secrets for injection into the agent manifest.
// This runs after the errgroup because it needs workspace.OwnerID.
//nolint:gocritic // System context needed to read secrets for the workspace owner.
userSecrets, err := a.Database.ListUserSecretsWithValues(dbauthz.AsSystemRestricted(ctx), workspace.OwnerID)
if err != nil {
return nil, xerrors.Errorf("getting user secrets: %w", err)
}
//nolint:gocritic // Only the workspace secret manager reads values.
workspaceSecrets, err := a.Database.ListActiveWorkspaceSecrets(dbauthz.AsWorkspaceSecretManager(ctx), a.WorkspaceBuildID)
if err != nil {
return nil, xerrors.Errorf("getting workspace secrets: %w", err)
}
appSlug := appurl.ApplicationURL{
AppSlugOrPort: "{{port}}",
AgentName: workspaceAgent.Name,
WorkspaceName: workspace.Name,
Username: workspace.OwnerUsername,
}
vscodeProxyURI := vscodeProxyURI(appSlug, a.AccessURL, a.AppHostname)
envs, err := db2sdk.WorkspaceAgentEnvironment(workspaceAgent)
if err != nil {
return nil, err
}
var gitAuthConfigs uint32
for _, cfg := range a.ExternalAuthConfigs {
if codersdk.EnhancedExternalAuthProvider(cfg.Type).Git() {
gitAuthConfigs++
}
}
apps, err := dbAppsToProto(dbApps, workspaceAgent, workspace.OwnerUsername, workspace, a.AppHostname)
if err != nil {
return nil, xerrors.Errorf("converting workspace apps: %w", err)
}
protoScripts, err := dbAgentScriptsToProto(scripts)
if err != nil {
return nil, xerrors.Errorf("converting workspace agent scripts: %w", err)
}
var parentID []byte
if workspaceAgent.ParentID.Valid {
parentID = workspaceAgent.ParentID.UUID[:]
}
secretFilePathPolicy := workspacesecrets.FilePathAllowed
if a.DisableUserSecretFilePath {
secretFilePathPolicy = workspacesecrets.FilePathBlocked
}
return &agentproto.Manifest{
AgentId: workspaceAgent.ID[:],
AgentName: workspaceAgent.Name,
OwnerUsername: workspace.OwnerUsername,
WorkspaceId: workspace.ID[:],
WorkspaceBuildId: a.WorkspaceBuildID[:],
WorkspaceName: workspace.Name,
TemplateId: workspace.TemplateID[:],
TemplateName: workspace.TemplateName,
GitAuthConfigs: gitAuthConfigs,
EnvironmentVariables: envs,
Directory: workspaceAgent.Directory,
VsCodePortProxyUri: vscodeProxyURI,
MotdPath: workspaceAgent.MOTDFile,
DisableDirectConnections: a.DisableDirectConnections,
DerpForceWebsockets: a.DerpForceWebSockets,
AgentPluginsEnabled: a.AgentPluginsEnabled,
ParentId: parentID,
DerpMap: tailnet.DERPMapToProto(a.DerpMapFn()),
Scripts: protoScripts,
Apps: apps,
Metadata: dbAgentMetadataToProtoDescription(metadata),
Devcontainers: dbAgentDevcontainersToProto(devcontainers),
Secrets: dbSecretsToProto(userSecrets, workspaceSecrets, secretFilePathPolicy),
}, nil
}
func vscodeProxyURI(app appurl.ApplicationURL, accessURL *url.URL, appHost string) string {
// Proxying by port only works for subdomains. If subdomain support is not
// available, return an empty string.
if appHost == "" {
return ""
}
// This will handle the ports from the accessURL or appHost.
appHost = appurl.SubdomainAppHost(appHost, accessURL)
// Return the url with a scheme and any wildcards replaced with the app slug.
return accessURL.Scheme + "://" + strings.ReplaceAll(appHost, "*", app.String())
}
func dbAgentMetadataToProtoDescription(metadata []database.WorkspaceAgentMetadatum) []*agentproto.WorkspaceAgentMetadata_Description {
ret := make([]*agentproto.WorkspaceAgentMetadata_Description, len(metadata))
for i, metadatum := range metadata {
ret[i] = dbAgentMetadatumToProtoDescription(metadatum)
}
return ret
}
func dbAgentMetadatumToProtoDescription(metadatum database.WorkspaceAgentMetadatum) *agentproto.WorkspaceAgentMetadata_Description {
return &agentproto.WorkspaceAgentMetadata_Description{
DisplayName: metadatum.DisplayName,
Key: metadatum.Key,
Script: metadatum.Script,
Interval: durationpb.New(time.Duration(metadatum.Interval)),
Timeout: durationpb.New(time.Duration(metadatum.Timeout)),
}
}
func dbAgentScriptsToProto(scripts []database.GetWorkspaceAgentScriptsByAgentIDsRow) ([]*agentproto.WorkspaceAgentScript, error) {
ret := make([]*agentproto.WorkspaceAgentScript, len(scripts))
for i, script := range scripts {
converted, err := dbAgentScriptToProto(script)
if err != nil {
return nil, xerrors.Errorf("script %s: %w", script.ID, err)
}
ret[i] = converted
}
return ret, nil
}
// dbAgentScriptToProto goes through db2sdk.WorkspaceAgentScript so the
// manifest and the REST API agree on what a valid dependency list is.
func dbAgentScriptToProto(script database.GetWorkspaceAgentScriptsByAgentIDsRow) (*agentproto.WorkspaceAgentScript, error) {
sdkScript, err := db2sdk.WorkspaceAgentScript(script)
if err != nil {
return nil, err
}
var dependencies []*agentproto.WorkspaceAgentScriptDependency
if len(sdkScript.Dependencies) > 0 {
dependencies = make([]*agentproto.WorkspaceAgentScriptDependency, len(sdkScript.Dependencies))
}
for i, dependency := range sdkScript.Dependencies {
requirement, err := workspaceAgentScriptDependencyRequirementToProto(dependency.Requirement)
if err != nil {
return nil, xerrors.Errorf("dependency %d: %w", i, err)
}
dependencies[i] = &agentproto.WorkspaceAgentScriptDependency{
PrerequisiteResourceAddress: dependency.PrerequisiteResourceAddress,
Requirement: requirement,
}
}
return &agentproto.WorkspaceAgentScript{
Id: script.ID[:],
LogSourceId: script.LogSourceID[:],
LogPath: script.LogPath,
Script: script.Script,
Cron: script.Cron,
RunOnStart: script.RunOnStart,
RunOnStop: script.RunOnStop,
StartBlocksLogin: script.StartBlocksLogin,
Timeout: durationpb.New(time.Duration(script.TimeoutSeconds) * time.Second),
DisplayName: script.DisplayName,
ResourceAddress: sdkScript.ResourceAddress,
Dependencies: dependencies,
}, nil
}
func workspaceAgentScriptDependencyRequirementToProto(requirement codersdk.WorkspaceAgentScriptDependencyRequirement) (agentproto.WorkspaceAgentScriptDependency_Requirement, error) {
switch requirement {
case codersdk.WorkspaceAgentScriptDependencyRequirementSuccess:
return agentproto.WorkspaceAgentScriptDependency_REQUIREMENT_SUCCESS, nil
case codersdk.WorkspaceAgentScriptDependencyRequirementCompletion:
return agentproto.WorkspaceAgentScriptDependency_REQUIREMENT_COMPLETION, nil
default:
// db2sdk already rejected anything else. The error stays so a new
// requirement can never fall through to UNSPECIFIED unnoticed.
return agentproto.WorkspaceAgentScriptDependency_REQUIREMENT_UNSPECIFIED, xerrors.Errorf("unsupported requirement %q", requirement)
}
}
func dbAppsToProto(dbApps []database.WorkspaceApp, agent database.WorkspaceAgent, ownerName string, workspace database.Workspace, appHostname string) ([]*agentproto.WorkspaceApp, error) {
ret := make([]*agentproto.WorkspaceApp, len(dbApps))
for i, dbApp := range dbApps {
var err error
ret[i], err = dbAppToProto(dbApp, agent, ownerName, workspace, appHostname)
if err != nil {
return nil, xerrors.Errorf("parse app %v (%q): %w", i, dbApp.Slug, err)
}
}
return ret, nil
}
func dbAppToProto(dbApp database.WorkspaceApp, agent database.WorkspaceAgent, ownerName string, workspace database.Workspace, appHostname string) (*agentproto.WorkspaceApp, error) {
sharingLevelRaw, ok := agentproto.WorkspaceApp_SharingLevel_value[strings.ToUpper(string(dbApp.SharingLevel))]
if !ok {
return nil, xerrors.Errorf("unknown app sharing level: %q", dbApp.SharingLevel)
}
healthRaw, ok := agentproto.WorkspaceApp_Health_value[strings.ToUpper(string(dbApp.Health))]
if !ok {
return nil, xerrors.Errorf("unknown app health: %q", dbApp.SharingLevel)
}
// SubdomainName should be empty if AppHostname is not configured
subdomainName := ""
if appHostname != "" {
subdomainName = db2sdk.AppSubdomain(dbApp, agent.Name, workspace.Name, ownerName)
}
return &agentproto.WorkspaceApp{
Id: dbApp.ID[:],
Url: dbApp.Url.String,
External: dbApp.External,
Slug: dbApp.Slug,
DisplayName: dbApp.DisplayName,
Command: dbApp.Command.String,
Icon: dbApp.Icon,
Subdomain: dbApp.Subdomain,
SubdomainName: subdomainName,
SharingLevel: agentproto.WorkspaceApp_SharingLevel(sharingLevelRaw),
Healthcheck: &agentproto.WorkspaceApp_Healthcheck{
Url: dbApp.HealthcheckUrl,
Interval: durationpb.New(time.Duration(dbApp.HealthcheckInterval) * time.Second),
Threshold: dbApp.HealthcheckThreshold,
},
Health: agentproto.WorkspaceApp_Health(healthRaw),
Hidden: dbApp.Hidden,
}, nil
}
func dbAgentDevcontainersToProto(devcontainers []database.WorkspaceAgentDevcontainer) []*agentproto.WorkspaceAgentDevcontainer {
ret := make([]*agentproto.WorkspaceAgentDevcontainer, len(devcontainers))
for i, dc := range devcontainers {
var subagentID []byte
if dc.SubagentID.Valid {
subagentID = dc.SubagentID.UUID[:]
}
ret[i] = &agentproto.WorkspaceAgentDevcontainer{
Id: dc.ID[:],
Name: dc.Name,
WorkspaceFolder: dc.WorkspaceFolder,
ConfigPath: dc.ConfigPath,
SubagentId: subagentID,
}
}
return ret
}
// dbSecretsToProto builds the manifest secrets from the user's and the
// agent build's secrets, delivering each on the targets Resolve assigns.
func dbSecretsToProto(userSecrets []database.UserSecret, workspaceSecrets []database.WorkspaceSecret, policy workspacesecrets.FilePathPolicy) []*agentproto.WorkspaceSecret {
user := make([]workspacesecrets.Secret, 0, len(userSecrets))
for _, s := range userSecrets {
user = append(user, workspacesecrets.Secret{
ID: s.ID,
EnvName: s.EnvName,
FilePath: s.FilePath,
Enabled: s.Enabled,
Value: s.Value,
})
}
build := make([]workspacesecrets.Secret, 0, len(workspaceSecrets))
for _, s := range workspaceSecrets {
// ListActiveWorkspaceSecrets only returns rows that still hold a
// value; the check guards against a cleared row slipping through.
if !s.Value.Valid {
continue
}
build = append(build, workspacesecrets.Secret{
ID: s.ID,
EnvName: s.EnvName,
FilePath: s.FilePath,
Value: s.Value.String,
})
}
resolvedUser, resolvedBuild := workspacesecrets.Resolve(user, build, policy)
ret := make([]*agentproto.WorkspaceSecret, 0, len(user)+len(build))
for _, r := range append(resolvedUser, resolvedBuild...) {
if !r.Delivered() {
continue
}
ret = append(ret, &agentproto.WorkspaceSecret{
EnvName: r.DeliveredEnvName,
FilePath: r.DeliveredFilePath,
Value: []byte(r.Value),
})
}
return ret
}