package agentapi import ( "context" "database/sql" "errors" "fmt" "math" "sort" "strings" "time" "github.com/google/uuid" "golang.org/x/xerrors" "google.golang.org/protobuf/encoding/protojson" "google.golang.org/protobuf/proto" "storj.io/drpc/drpcerr" "cdr.dev/slog/v3" agentproto "github.com/coder/coder/v2/agent/proto" "github.com/coder/coder/v2/coderd/database" "github.com/coder/coder/v2/coderd/database/dbtime" "github.com/coder/coder/v2/codersdk" "github.com/coder/coder/v2/codersdk/workspacesdk" "github.com/coder/quartz" ) // Server-side caps on a single PushContextState request. The agent // enforces its own caps (64KiB per resource payload, 2MiB aggregate, // 500 resources; see agent/agentcontext/resolve.go), but coderd // cannot trust a workspace process, so pushes are re-validated here // with headroom above the agent caps: // // - maxContextResourcesPerPush allows excluded stub entries past // the agent's 500-resource cap. // - maxContextResourceBodyBytes covers protojson and base64 // expansion of a 64KiB payload. // - maxContextAggregateBodyBytes matches the 4MiB DRPC message // cap so the invariant survives transport changes. // - The string and hash caps bound the remaining row columns; // source doubles as a btree primary key column, which PostgreSQL // limits to roughly 2704 bytes per index entry. const ( maxContextResourcesPerPush = 1000 maxContextResourceBodyBytes = 256 * 1024 maxContextAggregateBodyBytes = 4 * 1024 * 1024 maxContextSourceBytes = 1024 maxContextErrorBytes = 4096 maxContextHashBytes = 64 ) // ContextAPI implements the v2.10 PushContextState RPC. It persists // the latest pushed snapshot per workspace agent across two tables // (workspace_agent_context_snapshots and // workspace_agent_context_resources) so later phases can hydrate // chats and surface drift to the dashboard. // // The handler is a pure write path: nothing else in coderd reads // these rows yet. If a bug here returns errors the agent's RunPush // loop backs off and the workspace keeps behaving exactly like it // did before v2.10. type ContextAPI struct { AgentID uuid.UUID // Workspace caches workspace fields for the duration of the agent // connection so dbauthz can authorize against the workspace RBAC // object without re-fetching the workspace on every push. Workspace *CachedWorkspaceFields Log slog.Logger Clock quartz.Clock Database database.Store // DirtyMarker hydrates chats from, and marks chats dirty against, the // snapshot persisted by a push. It is nil when chatd is not running, // in which case PushContextState stays a pure write path. DirtyMarker ContextDirtyMarker // Disabled rejects every push with a dRPC Unimplemented code. The // agent's DRPCPusher translates that code into ErrPushUnimplemented, // which terminates its RunPush loop for the life of the connection, // exactly as if coderd predated the v2.10 Agent API. This is the // deployment-wide kill switch for context sync write load // (CODER_DISABLE_WORKSPACE_AGENT_CONTEXT_SYNC). Disabled bool // Experiments gates Agent Plugins data. With agent-plugins disabled, // plugin data is dropped but the aggregate hash is stored as sent. Experiments codersdk.Experiments } // ContextDirtyMarker hydrates chats from, and marks chats dirty against, a // freshly persisted agent context snapshot. It is implemented by chatd and // injected at coderd construction so this package neither imports the chat // domain nor performs chat-authorized writes directly. type ContextDirtyMarker interface { // HydrateAndMarkChatsDirty runs inside the PushContextState // transaction using the supplied store. It hydrates chats for the // agent that have no pinned hash yet (no dirty event) and flips // already-pinned chats whose hash differs from aggregateHash. It // returns a callback that publishes the resulting dirty watch events; // the caller invokes it only after the transaction commits. The // callback is a no-op when nothing transitioned to dirty. HydrateAndMarkChatsDirty(ctx context.Context, tx database.Store, agentID uuid.UUID, aggregateHash []byte, snapshotError string, now time.Time) (publishDirty func(), err error) } // PushContextState persists a snapshot pushed by the workspace // agent. The transaction upserts the snapshot row, upserts each // resource, then deletes any resources whose source is not in the // incoming set so the stored snapshot and resource table always // agree. It runs at repeatable read isolation (with retries) so two // concurrent pushes cannot interleave their writes; the loser of the // conflict re-runs the version gate against the winner's committed // state. // // Returns accepted = false (without writing) when the push is a // replay or out-of-order resend: the agent's per-process version // counter is monotonic, and only an initial = true push from a // freshly-booted agent resets that baseline. Replays and stale // retransmits leave the stored state untouched. // // Authorization happens in dbauthz: every query in the transaction // authorizes the actor (the agent's token subject) against the // workspace that owns the agent. func (a *ContextAPI) PushContextState(ctx context.Context, req *agentproto.PushContextStateRequest) (*agentproto.PushContextStateResponse, error) { if a.Disabled { // The Unimplemented code (not a plain error) is what tells the // agent to stop pushing instead of retrying with backoff. return nil, drpcerr.WithCode( xerrors.New("agentapi: workspace agent context sync is disabled on this deployment"), drpcerr.Unimplemented, ) } if req == nil { return nil, xerrors.New("agentapi: PushContextState request is nil") } if err := validateContextPushRequest(req); err != nil { return nil, err } rows, err := validateAndConvertContextResources(req.Resources, a.Experiments) if err != nil { return nil, err } // Attach the cached workspace RBAC object so dbauthz can take its // fast path. On failure (or when unset, e.g. prebuilds) dbauthz // falls back to fetching the workspace by agent ID. if a.Workspace != nil { injected, err := a.Workspace.ContextInject(ctx) if err != nil { a.Log.Debug(ctx, "failed to inject cached workspace RBAC object", slog.Error(err)) } else { ctx = injected } } clock := a.Clock if clock == nil { clock = quartz.NewReal() } now := dbtime.Time(clock.Now()) activeSources := make([]string, 0, len(rows)) for _, r := range rows { activeSources = append(activeSources, r.Source) } sort.Strings(activeSources) var accepted bool // publishDirty is captured from the final (committed) attempt and // invoked after the transaction commits; ReadModifyUpdate may re-run // the closure on serialization conflicts. var publishDirty func() err = database.ReadModifyUpdate(a.Database, func(tx database.Store) error { // The closure re-runs on serialization conflicts; reset any // state carried over from a rolled-back attempt. accepted = false publishDirty = nil existing, err := tx.GetLatestWorkspaceAgentContextSnapshot(ctx, a.AgentID) switch { case errors.Is(err, sql.ErrNoRows): // No previous snapshot; first push always wins. case err != nil: return xerrors.Errorf("get latest snapshot: %w", err) default: // Accept either a fresh agent process (initial) or // a strictly newer version. Out-of-order or replayed // pushes leave the stored state untouched. // //nolint:gosec // existing.Version is a uint64 round-tripped via BIGINT; non-negative by construction. if !req.Initial && req.Version <= uint64(existing.Version) { return nil } } _, err = tx.UpsertWorkspaceAgentContextSnapshot(ctx, database.UpsertWorkspaceAgentContextSnapshotParams{ WorkspaceAgentID: a.AgentID, //nolint:gosec // Bounded by validateContextPushRequest. Version: int64(req.Version), AggregateHash: append([]byte(nil), req.AggregateHash...), SnapshotError: req.SnapshotError, ReceivedAt: now, }) if err != nil { return xerrors.Errorf("upsert snapshot: %w", err) } for _, r := range rows { r.WorkspaceAgentID = a.AgentID r.Now = now _, err = tx.UpsertWorkspaceAgentContextResource(ctx, r) if err != nil { return xerrors.Errorf("upsert resource %q: %w", r.Source, err) } } err = tx.DeleteStaleWorkspaceAgentContextResources(ctx, database.DeleteStaleWorkspaceAgentContextResourcesParams{ WorkspaceAgentID: a.AgentID, ActiveSources: activeSources, }) if err != nil { return xerrors.Errorf("delete stale resources: %w", err) } // Hydrate and dirty chats against the snapshot just written, in the // same transaction so a concurrent refresh cannot interleave with // the version gate. Events are published only after commit. if a.DirtyMarker != nil { publishDirty, err = a.DirtyMarker.HydrateAndMarkChatsDirty(ctx, tx, a.AgentID, req.AggregateHash, req.SnapshotError, now) if err != nil { return xerrors.Errorf("hydrate and mark chats dirty: %w", err) } } accepted = true return nil }) if err != nil { return nil, err } if !accepted { a.Log.Debug(ctx, "PushContextState dropped: replay or out-of-order", slog.F("agent_id", a.AgentID), slog.F("version", req.Version), slog.F("initial", req.Initial), ) return &agentproto.PushContextStateResponse{Accepted: false}, nil } // The snapshot committed; fan out dirty watch events to chats whose // pinned context drifted from this push. if publishDirty != nil { publishDirty() } a.Log.Debug(ctx, "PushContextState accepted", slog.F("agent_id", a.AgentID), slog.F("version", req.Version), slog.F("initial", req.Initial), slog.F("resources", len(rows)), ) return &agentproto.PushContextStateResponse{Accepted: true}, nil } // validateContextPushRequest enforces the request-level caps: counts // and sizes a compromised workspace could otherwise inflate to DoS // coderd or bloat the database. The resource count includes resources // nested in plugins. func validateContextPushRequest(req *agentproto.PushContextStateRequest) error { if req.Version > math.MaxInt64 { return xerrors.Errorf("agentapi: PushContextState version %d exceeds int64 range", req.Version) } if len(req.AggregateHash) > maxContextHashBytes { return xerrors.Errorf("agentapi: PushContextState aggregate hash is %d bytes, exceeds %d byte cap", len(req.AggregateHash), maxContextHashBytes) } if len(req.SnapshotError) > maxContextErrorBytes { return xerrors.Errorf("agentapi: PushContextState snapshot error is %d bytes, exceeds %d byte cap", len(req.SnapshotError), maxContextErrorBytes) } if n := contextResourceCount(req.Resources); n > maxContextResourcesPerPush { return xerrors.Errorf("agentapi: PushContextState has %d resources, exceeds %d resource cap", n, maxContextResourcesPerPush) } return nil } func contextResourceCount(resources []*agentproto.ContextResource) int { n := len(resources) for _, r := range resources { plugin := r.GetPlugin() n += len(plugin.GetSkills()) + len(plugin.GetMcpServers()) } return n } // validateAndConvertContextResources translates wire resources into // upsert parameters while rejecting structurally invalid input: // // - empty, oversized, or duplicate sources (the PK depends on // uniqueness and indexes the source column), // - unknown body variants, // - invalid plugin names, misplaced nested resources, and OK plugin // names used more than once, // - unknown status enum values, // - per-resource and aggregate body sizes past the server caps. // // A plugin resource becomes one row for the plugin and one row per // nested skill and MCP server. plugin_name is the plugin's name on each // nested row and on the row of an OK plugin. With the agent-plugins // experiment off, plugin resources and their nested resources are // dropped without validation. The plugin name uniqueness check runs // only after every resource passes its own checks. // // Validation is deliberately strict here so a misbehaving agent // cannot poison the snapshot table. Phase 2 readers can then trust // that every row maps to a known proto variant. // // WorkspaceAgentID and Now are left unset; the caller fills them at // upsert time. func validateAndConvertContextResources(resources []*agentproto.ContextResource, experiments codersdk.Experiments) ([]database.UpsertWorkspaceAgentContextResourceParams, error) { pluginsEnabled := experiments.Enabled(codersdk.ExperimentAgentPlugins) c := contextRowConverter{ rows: make([]database.UpsertWorkspaceAgentContextResourceParams, 0, len(resources)), seen: make(map[string]struct{}, len(resources)), } var okPlugins []*agentproto.ContextResource for i, r := range resources { if r == nil { return nil, xerrors.Errorf("agentapi: PushContextState resource at index %d is nil", i) } _, isPlugin := r.Body.(*agentproto.ContextResource_Plugin) if isPlugin && !pluginsEnabled { continue } location := fmt.Sprintf("resource at index %d", i) var pluginName string if isPlugin && r.Status == agentproto.ContextResource_OK { pluginName = r.GetPlugin().GetName() } if err := c.add(r, location, pluginName); err != nil { return nil, err } if !isPlugin { continue } if err := c.addNested(r, location); err != nil { return nil, err } if r.Status == agentproto.ContextResource_OK { okPlugins = append(okPlugins, r) } } if err := validateUniquePluginNames(okPlugins); err != nil { return nil, err } return c.rows, nil } // contextRowConverter accumulates a push's rows, the sources seen so // far, and the aggregate body size. type contextRowConverter struct { rows []database.UpsertWorkspaceAgentContextResourceParams seen map[string]struct{} aggregateBodyBytes int } // add validates r and appends its row with pluginName as its // plugin_name. location names r in errors that cannot quote its source. func (c *contextRowConverter) add(r *agentproto.ContextResource, location, pluginName string) error { if r.Source == "" { return xerrors.Errorf("agentapi: PushContextState %s has empty source", location) } if len(r.Source) > maxContextSourceBytes { return xerrors.Errorf("agentapi: PushContextState %s has %d byte source, exceeds %d byte cap", location, len(r.Source), maxContextSourceBytes) } if _, ok := c.seen[r.Source]; ok { return xerrors.Errorf("agentapi: PushContextState duplicate source %q", r.Source) } c.seen[r.Source] = struct{}{} if len(r.GetSourcePath()) > maxContextSourceBytes { return xerrors.Errorf("resource %q: source path is %d bytes, exceeds %d byte cap", r.Source, len(r.GetSourcePath()), maxContextSourceBytes) } if len(r.Error) > maxContextErrorBytes { return xerrors.Errorf("resource %q: error is %d bytes, exceeds %d byte cap", r.Source, len(r.Error), maxContextErrorBytes) } if len(r.ContentHash) > maxContextHashBytes { return xerrors.Errorf("resource %q: content hash is %d bytes, exceeds %d byte cap", r.Source, len(r.ContentHash), maxContextHashBytes) } if r.SizeBytes > math.MaxInt64 { return xerrors.Errorf("resource %q: size %d exceeds int64 range", r.Source, r.SizeBytes) } kind, body, err := marshalContextResourceBody(r) if err != nil { return xerrors.Errorf("resource %q: %w", r.Source, err) } if len(body) > maxContextResourceBodyBytes { return xerrors.Errorf("resource %q: body is %d bytes, exceeds %d byte cap", r.Source, len(body), maxContextResourceBodyBytes) } if err := validatePluginName(r); err != nil { return xerrors.Errorf("resource %q: %w", r.Source, err) } c.aggregateBodyBytes += len(body) if c.aggregateBodyBytes > maxContextAggregateBodyBytes { return xerrors.Errorf("agentapi: PushContextState aggregate body size exceeds %d byte cap", maxContextAggregateBodyBytes) } status, err := contextResourceStatus(r.Status) if err != nil { return xerrors.Errorf("resource %q: %w", r.Source, err) } //nolint:exhaustruct // WorkspaceAgentID and Now are filled by the caller at upsert time. c.rows = append(c.rows, database.UpsertWorkspaceAgentContextResourceParams{ Source: r.Source, SourcePath: r.GetSourcePath(), BodyKind: kind, Body: body, ContentHash: append([]byte(nil), r.ContentHash...), //nolint:gosec // Bounded above. SizeBytes: int64(r.SizeBytes), Status: status, Error: r.Error, PluginName: pluginName, }) return nil } // addNested validates and appends the skills and MCP servers nested in // plugin resource r, which must have passed add. location names r. // // - only an OK plugin may nest resources, // - each entry of skills must carry a skill body and a source under // "/skills/", with either path separator, // - each entry of mcp_servers must carry an mcp_server body with a // non-empty server_name and the source "/". // // The skills/ check is a string prefix, not path containment. Errors // quote only capped or validated strings. func (c *contextRowConverter) addNested(r *agentproto.ContextResource, location string) error { plugin := r.GetPlugin() if len(plugin.GetSkills())+len(plugin.GetMcpServers()) == 0 { return nil } if r.Status != agentproto.ContextResource_OK { return xerrors.Errorf("resource %q: a plugin whose status is not OK must not nest resources", r.Source) } name := plugin.GetName() skillsPrefix := strings.ReplaceAll(r.Source, `\`, "/") + "/skills/" for i, skill := range plugin.GetSkills() { if _, ok := skill.GetBody().(*agentproto.ContextResource_Skill); !ok { return xerrors.Errorf("resource %q: skills[%d] must carry a skill body", r.Source, i) } if err := c.add(skill, fmt.Sprintf("%s skills[%d]", location, i), name); err != nil { return err } if !strings.HasPrefix(strings.ReplaceAll(skill.Source, `\`, "/"), skillsPrefix) { return xerrors.Errorf("resource %q: plugin skill source must be under %q", skill.Source, r.Source+"/skills/") } } for i, server := range plugin.GetMcpServers() { if _, ok := server.GetBody().(*agentproto.ContextResource_McpServer); !ok { return xerrors.Errorf("resource %q: mcp_servers[%d] must carry an mcp_server body", r.Source, i) } if err := c.add(server, fmt.Sprintf("%s mcp_servers[%d]", location, i), name); err != nil { return err } serverName := server.GetMcpServer().GetServerName() if serverName == "" { return xerrors.Errorf("resource %q: plugin MCP server_name is required", server.Source) } if server.Source != name+"/"+serverName { return xerrors.Errorf("resource %q: plugin MCP server source must be %q", server.Source, name+"/") } } return nil } // validatePluginName checks the name of a plugin resource: an OK plugin // must have one, and a non-empty name must pass // workspacesdk.ValidatePluginName. func validatePluginName(r *agentproto.ContextResource) error { plugin, ok := r.Body.(*agentproto.ContextResource_Plugin) if !ok { return nil } name := plugin.Plugin.GetName() if name == "" { if r.Status == agentproto.ContextResource_OK { return xerrors.New("plugin name is required on an OK plugin resource") } return nil } return workspacesdk.ValidatePluginName(name) } // validateUniquePluginNames rejects two OK plugin resources with the // same name. func validateUniquePluginNames(plugins []*agentproto.ContextResource) error { sources := make(map[string]string, len(plugins)) for _, r := range plugins { name := r.GetPlugin().GetName() if first, ok := sources[name]; ok { return xerrors.Errorf("agentapi: PushContextState OK plugin name %q is used by both %q and %q", name, first, r.Source) } sources[name] = r.Source } return nil } // marshalContextResourceBody picks the body variant set on the wire // resource and returns the (body_kind, body_jsonb) pair stored in // the resource row. The body is protojson encoded so the schema can // be evolved by adding fields to the proto without coderd changes, // and a future reader can round-trip back to the proto type by // switching on body_kind. // // Body is always populated, even on non-OK statuses: the wire // guarantees the oneof variant is set so coderd can still attribute // the failure to a known kind. For variants with no content fields // (mcp_config), an empty JSON object is stored. A plugin body is stored // without skills and mcp_servers. func marshalContextResourceBody(r *agentproto.ContextResource) (kind database.WorkspaceAgentContextBodyKind, body []byte, err error) { switch b := r.Body.(type) { case *agentproto.ContextResource_InstructionFile: payload := b.InstructionFile if payload == nil { payload = &agentproto.InstructionFileBody{} } body, err = marshalBody(payload) return database.WorkspaceAgentContextBodyKindInstructionFile, body, err case *agentproto.ContextResource_Skill: payload := b.Skill if payload == nil { payload = &agentproto.SkillMetaBody{} } body, err = marshalBody(payload) return database.WorkspaceAgentContextBodyKindSkill, body, err case *agentproto.ContextResource_McpConfig: payload := b.McpConfig if payload == nil { payload = &agentproto.MCPConfigBody{} } body, err = marshalBody(payload) return database.WorkspaceAgentContextBodyKindMcpConfig, body, err case *agentproto.ContextResource_McpServer: payload := b.McpServer if payload == nil { payload = &agentproto.MCPServerBody{} } body, err = marshalBody(payload) return database.WorkspaceAgentContextBodyKindMcpServer, body, err case *agentproto.ContextResource_AcpHarness: payload := b.AcpHarness if payload == nil { payload = &agentproto.ACPHarnessBody{} } body, err = marshalBody(payload) return database.WorkspaceAgentContextBodyKindAcpHarness, body, err case *agentproto.ContextResource_Plugin: body, err = marshalBody(&agentproto.PluginBody{ Name: b.Plugin.GetName(), Version: b.Plugin.GetVersion(), Description: b.Plugin.GetDescription(), }) return database.WorkspaceAgentContextBodyKindPlugin, body, err case nil: return "", nil, xerrors.Errorf("missing body variant; status %s requires a typed body", r.Status) default: return "", nil, xerrors.Errorf("unsupported body variant %T", r.Body) } } // contextBodyMarshalOptions produces deterministic-ish JSON for the // body so the stored value compares equal across pushes that yield // equivalent protos. Strict canonicalization (RFC 8785) is not // required here; the enum column plus the protojson round trip give // us a stable enough store. var contextBodyMarshalOptions = protojson.MarshalOptions{ UseProtoNames: true, EmitUnpopulated: false, } // marshalBody is a small wrapper around protojson.Marshal that // keeps the body encoding in one place; future phases that read // these rows mirror the call with protojson.Unmarshal into the // matching proto.Message. func marshalBody(msg proto.Message) ([]byte, error) { out, err := contextBodyMarshalOptions.Marshal(msg) if err != nil { return nil, xerrors.Errorf("marshal body: %w", err) } return out, nil } // contextResourceStatus translates the wire status enum to the // database enum. STATUS_UNSPECIFIED is rejected: every well-formed // snapshot row needs an explicit status so cache invalidation, dirty // fan-out, and the Sources drawer can reason about partial pushes // deterministically. func contextResourceStatus(s agentproto.ContextResource_Status) (database.WorkspaceAgentContextResourceStatus, error) { switch s { case agentproto.ContextResource_OK: return database.WorkspaceAgentContextResourceStatusOk, nil case agentproto.ContextResource_OVERSIZE: return database.WorkspaceAgentContextResourceStatusOversize, nil case agentproto.ContextResource_UNREADABLE: return database.WorkspaceAgentContextResourceStatusUnreadable, nil case agentproto.ContextResource_INVALID: return database.WorkspaceAgentContextResourceStatusInvalid, nil case agentproto.ContextResource_EXCLUDED: return database.WorkspaceAgentContextResourceStatusExcluded, nil default: return "", xerrors.Errorf("unknown status %d", s) } }