feat(agent): add agent socket API #20717

SasSwart · 2025-11-11T14:45:50Z

This is number 2 of 5 pull requests in an effort to add agent script ordering. It adds a drpc API that is exposed via a local socket. This API serves access to a lightweight DAG based dependency manager that was inspired by systemd.

In follow-up PRs:

This unit manager will be plumbed into the workspace agent struct.
CLI commands will use this agentsocket api to express dependencies between coder scripts

I used an LLM to produce some of these changes, but I have conducted thorough self review and consider this contribution to be ready for an external reviewer.

agent/agentsocket/service.go

agent/agentsocket/server.go

mafredri · 2025-11-14T14:34:36Z

agent/agentsocket/proto/agentsocket.proto

+  // Request whether a unit is ready to be started. That is, all dependencies are satisfied.
+	rpc SyncReady(SyncReadyRequest) returns (SyncReadyResponse);
+  // Get the status of a unit and list its dependencies.
+	rpc SyncStatus(SyncStatusRequest) returns (SyncStatusResponse);


Is the flow going to be:

SyncWant(fooscript, barscript)

SyncWant(fooscript, bazscript)

while ! SyncReady(fooscript)

SyncStart(fooscript)

...

SyncComplete(fooscript)

I assume SyncStatus is more useful or debugging than actual script writing (which is fine).

Also, wdyt about supporting watch vs polling?

One more thought, what happens if I reverse the order of want and start? So start -> want want -> ready. (I imagine users will feel it's natural to start immediately once your script gets going, it may be wrong use but still.)

Your described flow is correct. Although SyncStart should probably do the polling server side.

In terms of watch vs poll, we agreed with Cian to only poll for now. We can implement watch later.

To your last thought:

Want should almost always be called before Start.

Wants that are added after Start will only be applied on the next Start.

We could add a guard to say that dependencies cannot be added to a unit that has been started.

On further consideration: we do need to think about what happens when a script fails (without being marked as such) and gets retried. The status will be stuck in "started".

agent/agentsocket/proto/agentsocket.proto

agent/agentsocket/server.go

agent/agentsocket/service.go

mafredri · 2025-11-14T15:17:47Z

agent/agentsocket/socket_unix.go

+
+	// Fall back to /tmp with user-specific path
+	uid := os.Getuid()
+	return filepath.Join("/tmp", fmt.Sprintf("coder-agent-%d.sock", uid)), nil


(I wonder if this might create conflicts between tests. Especially later on with CLI support and CLI tests. Consider adding a CLI flag to configure it.)

agent/agentsocket/socket_windows.go

agent/agentsocket/server.go

agent/agentsocket/service.go

agent/agentsocket/service_test.go

Further slim down the agentsocket proxy simplify the agentsocket server interface avoid two race conditions use t.Cleanup where applicable

agent/agentsocket/proto/agentsocket.proto

agent/agentsocket/server.go

mafredri · 2025-11-21T08:58:14Z

agent/agentsocket/server.go

+func (s *Server) acceptConnections() {
+	// In an edge case, Stop() might race with acceptConnections() and set s.listener to nil.
+	// Therefore, we grab a copy of the listener under a lock. We might still get a nil listener,
+	// but then we know close has already run and we can return early.


Outdated comment (no Stop). Entire comment is not needed after my suggestion for type Service.

mafredri · 2025-11-21T09:00:21Z

agent/agentsocket/socket_unix.go

+
+// getDefaultSocketPath returns the default socket path for Unix-like systems
+func getDefaultSocketPath() (string, error) {
+	// Try XDG_RUNTIME_DIR first


Please leave this for future refactor, but it's a good idea to handle these types of things in the agent, and pass them down rather than have each component do their own thing.

mafredri · 2025-11-21T09:02:06Z

agent/agentsocket/socket_unix.go

+	}
+
+	// Try to connect to see if it's actually listening
+	conn, err := net.Dial("unix", path)


Can we use net.Dialer{}.DialContext(ctx, ...) here so we don't block forever if the socket is in a bad state or there's a bad agent listening on it?

make gen

…duction agents must specify a well-known agentsocket path and clients must be able to specify the socket to address

DanielleMaywood

stamping with a nit about a comment

DanielleMaywood · 2025-11-21T10:44:10Z

agent/agentsocket/server.go

+
+	server.listener = listener
+
+	// This context is canceled by s.Stop() when the server is stopped.


Suggested change

// This context is canceled by s.Stop() when the server is stopped.

// This context is canceled by s.Close() when the server is stopped.

I think this comment is outdated?

I thought I got to that one 😄. On it. Thanks!

mtojek

post-merge LGTM! Thank you both

github-actions bot assigned SasSwart Nov 11, 2025

SasSwart changed the title ~~Jjs/internal 1095 branch2 socket server~~ feat(agent): add agent socket API Nov 11, 2025

SasSwart changed the base branch from main to jjs/internal-1095-branch1-unit-manager November 11, 2025 14:47

SasSwart force-pushed the jjs/internal-1095-branch2-socket-server branch from bf9e8fd to 1daf67e Compare November 12, 2025 13:39

mafredri self-requested a review November 14, 2025 12:02

SasSwart force-pushed the jjs/internal-1095-branch2-socket-server branch from a17863a to 9fdc98d Compare November 14, 2025 13:02

SasSwart marked this pull request as ready for review November 14, 2025 13:03

SasSwart requested a review from DanielleMaywood November 14, 2025 13:03

mafredri reviewed Nov 14, 2025

View reviewed changes

Base automatically changed from jjs/internal-1095-branch1-unit-manager to main November 19, 2025 17:03

SasSwart added 13 commits November 20, 2025 07:23

feat(agent): add agent socket server infrastructure

0a4128e

appease the linter

e2d84cf

Fix build issues post rebase

8f6f2a2

dont regenerate the agentsocket files when we build dylib

87f44f1

fix unit manager service tests

6ca4dba

Use mac compatible socket paths for agentsocket service testing

18eb10c

improve macos socket path helper

fbaced7

fix function signatures for the agentsocket api on windows

63e70ad

disable the agentsocket API on windows

1852f51

Disable agentsocket api on windows

0c53bf4

adjust to updates from upstream after rebase

9c7de90

add and mature agentsocket tests

035f675

reduce overhead on the agentsocket api

79d783a

SasSwart force-pushed the jjs/internal-1095-branch2-socket-server branch from f7245fa to 79d783a Compare November 20, 2025 07:23

SasSwart added 3 commits November 20, 2025 07:35

adjust the agentsocket API to the unit manager updates

54b0fc7

Move unit validation into the unit manager

d9c2537

Further slim down the agentsocket proto

a6f0f78

DanielleMaywood reviewed Nov 20, 2025

View reviewed changes

SasSwart added 2 commits November 20, 2025 14:05

remove defunct code and protect against a race

33bdc92

Review notes

57198a2

Further slim down the agentsocket proxy simplify the agentsocket server interface avoid two race conditions use t.Cleanup where applicable

make fmt

cf62a92

mafredri reviewed Nov 21, 2025

View reviewed changes

SasSwart added 4 commits November 21, 2025 09:06

Add a test to ensure that duplicate dependencies are not added

758f1cf

consistent indentation for agentsocket.proto

04fc6df

Add a timeout to socket detection

5a679e8

make gen

Default to a random agentsocket path to avoid conflicts in tests. Pro…

b63a8b1

…duction agents must specify a well-known agentsocket path and clients must be able to specify the socket to address

DanielleMaywood approved these changes Nov 21, 2025

View reviewed changes

Rename outdated comment

484099c

SasSwart merged commit 2840fdc into main Nov 21, 2025
30 checks passed

SasSwart deleted the jjs/internal-1095-branch2-socket-server branch November 21, 2025 11:09

github-actions bot locked and limited conversation to collaborators Nov 21, 2025

mtojek reviewed Nov 21, 2025

View reviewed changes


		server.listener = listener

		// This context is canceled by s.Stop() when the server is stopped.

	// This context is canceled by s.Stop() when the server is stopped.
	// This context is canceled by s.Close() when the server is stopped.

feat(agent): add agent socket API #20717

feat(agent): add agent socket API #20717

Uh oh!

Conversation

SasSwart commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mafredri Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DanielleMaywood left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mtojek left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

SasSwart commented Nov 11, 2025 •

edited

Loading

mafredri Nov 14, 2025 •

edited

Loading