Skip to content

feat: add a run-once reservation mechanism to the workspace agent process API - #27369

Closed
ibetitsmike wants to merge 1 commit into
mainfrom
mike/codagt-757-lite/01-agent-start-tokens
Closed

ibetitsmike wants to merge 1 commit into
mainfrom
mike/codagt-757-lite/01-agent-start-tokens

Conversation

@ibetitsmike

@ibetitsmike ibetitsmike commented Jul 21, 2026 •

Copy link
Copy Markdown
Collaborator

Stack context

Part 1 of the CODAGT-757 stack. Replaces the earlier "idempotent start tokens" version of this PR after review: the reservation rule now lives in its own mechanism rather than inside process management.

Why

A chat that resumes after a crash replays tool calls history still shows as unresolved. For execute that means running the shell command a second time. Preventing it needs a rule the agent can apply to a repeated request: perform the operation once, and answer a repeat with what the first attempt produced.

That rule is not specific to starting processes. edit_files is the clearest second candidate: replaying it is actively harmful, because the text it searched for has already been replaced, so the retry either fails or matches a changed file differently.

What

agent/agentrunonce holds the rule and nothing else:

  • reserve a key before doing any work, so a concurrent caller waits instead of repeating it;
  • attach later callers presenting the same input fingerprint to the value that was published;
  • refuse a key reused with a different fingerprint;
  • release a reservation whose operation never got underway, so a waiter takes it over;
  • retain completed reservations for a while, then evict them.

The registry is generic over both the key and the published value, and never interprets either. That is what lets operations with unlike results share the rule: this PR's adapter publishes a handle to a live process that the process manager keeps managing, while a future edit_files adapter would publish a plain response value. Both fake adapters are covered in the registry's own tests.

Process starts are the only adapter here. The process manager still owns output buffers, exit state, signals, and git-watcher registration.

Reservations are scoped to the chat

Following review, the registry key is a composite of the chat and the idempotency key, so two chats that send the same key value get independent reservations instead of colliding. Chat is therefore no longer part of the fingerprint, and cross-chat reuse no longer produces a false conflict.

The fingerprint covers only what decides what gets spawned: command, requested workdir, env, and the background flag. Display intent and how long the caller waits are excluded, since neither changes the process.

Two behavioral notes:

  • Recording the fingerprint when the key is reserved means a mismatched retry is refused immediately, without first waiting out the concurrent start it could never attach to.
  • A reservation becomes attachable when the process spawns, but its retention starts when the process exits. Those are deliberately separate events; starting retention at publication would evict long-running processes mid-flight.

Machine-readable conflicts

Start conflicts carry a code, so callers do not classify them by matching error text:

Code Meaning
input_mismatch The key was used within the same chat with different parameters. Permanent; retrying cannot resolve it.
start_pending The start holding the key had not published its process yet. Unresolved; a retry may attach.

The code rides a route-specific ProcessConflictError rather than a new field on the global codersdk.Response, following the existing WatchError precedent. Agents that predate this never answered 409 here, so an uncoded conflict is reported as permanent: treating an unresolved start as permanent costs an error result, while the reverse risks running the command twice.

Review changes in this revision

  • Registry keys are {chatID, idempotencyKey} composites; the cross-chat conflict test became a cross-chat independence test.
  • ClientToken is now IdempotencyKey on the wire (idempotency_key) and in Go. No client_token reference existed anywhere at merge-base, so there is no compatibility cost.
  • ErrOwnerPending is now ErrPublicationPending, and Outcome.Owner is now Outcome.Ticket, so the API no longer uses "owner" for a concept the reviewer found unclear.
  • The unlock-then-wait section of Reserve moved into tryReserve plus waitForPublication, so no method unlocks a mutex it did not take.
  • process_internal_test.go was rewritten around shared helpers (newTestManager, startGate, startAsync, awaitStart), and the two close-before-spawn tests collapsed into one table.
  • Added comments were cut roughly in half and rewritten in plain English.

This PR was written and revised by Mux, an AI coding agent, operating on Mike's behalf.

@linear-code

linear-code Bot commented Jul 21, 2026

Copy link
Copy Markdown

CODAGT-757

@ibetitsmike

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 🎉

Reviewed commit: d3be23b9ff

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@ibetitsmike
ibetitsmike force-pushed the mike/codagt-757-lite/01-agent-start-tokens branch from d3be23b to c6f4fb5 Compare July 21, 2026 13:07
@ibetitsmike

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: c6f4fb53f3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread codersdk/workspacesdk/agentconn.go Resolved
Comment thread codersdk/workspacesdk/agentconn.go Resolved
Comment thread agent/agentproc/process.go Resolved
@ibetitsmike
ibetitsmike force-pushed the mike/codagt-757-lite/01-agent-start-tokens branch from c6f4fb5 to d9b87ba Compare July 21, 2026 22:40
@ibetitsmike

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: d9b87ba130

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@mafredri mafredri left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the atomic reservation in this PR is the right core idea, but it is being added at the wrong level.

The reusable rule is not specific to process starts:

For selected mutating tool calls, the workspace agent should perform one operation for a given ID and return the same work or result when that ID is repeated.

This stack does not need to convert every tool. It should add that shared mechanism and use execute as its first and only operation.

For example, the agent could keep an in-memory record containing:

tool-call ID
operation name
accepted input
running or completed state
result

A new ID reserves the record before doing any work. Repeating the same ID and input returns the existing state or result. Reusing the ID with different input fails.

execute would use this mechanism to start one process and retain its process ID. The existing process manager would continue to own process output, exit state, and signals.

This split keeps the useful work in this PR, especially reservation before cmd.Start and concurrent callers waiting for the owner. It also avoids embedding the shared replay rule inside process management, where another mutating tool could not reuse it later.

The scope can remain small: build the shared mechanism, connect execute, and leave every other tool unchanged.

🤖 This review was automatically generated with Coder Agents.

@ibetitsmike
ibetitsmike force-pushed the mike/codagt-757-lite/01-agent-start-tokens branch 2 times, most recently from f3c8095 to 3dfed86 Compare July 29, 2026 13:55
@ibetitsmike
ibetitsmike force-pushed the mike/codagt-757-lite/01-agent-start-tokens branch 2 times, most recently from 121599a to 3f1ac82 Compare August 1, 2026 04:01
@ibetitsmike

Copy link
Copy Markdown
Collaborator Author

Revised. Your composite-key suggestion turned out to be the largest change here, and it cascaded into #27370 and #27372 as well.

Design

Registry keys are now {chatID, idempotencyKey} composites, so two chats reusing a key value get independent reservations. Chat left the fingerprint, cross-chat reuse no longer conflicts, and the redundant chat check in #27372's by-key signal path is gone. The cross-chat conflict test is now a cross-chat independence test. This reverses my position from the last round; you found a third option that keeps isolation without the false conflict.

Naming and structure

ClientToken -> IdempotencyKey (wire tag idempotency_key), ErrOwnerPending -> ErrPublicationPending, Outcome.Owner -> Outcome.Ticket. The unlock-then-wait section of Reserve split into tryReserve plus waitForPublication, so no method unlocks a mutex it did not take. process_internal_test.go now shares newTestManager, a startGate helper, and startAsync/awaitStart.

Comments

You stopped flagging partway through PR1 and never reached #27370 or #27372, so I measured the whole stack instead of fixing only the eleven you named. Added comments were 44-53% of added code in the four core files, against roughly 20% in the same files at base:

File Before After
agent/agentproc/process.go 48% 35%
agent/agentrunonce/registry.go 48% 28%
codersdk/workspacesdk/agentconn.go 76% 51%
coderd/x/chatd/chattool/execute.go (#27370) 37% 26%

agentconn.go stays high because almost all of it is exported SDK types and error codes, where the remaining lines are doc comments rather than narration. I also removed several claims that were not verifiable, including the manifest-loading speculation you flagged and a fingerprint comment that described fields the request does not have.

One pushback

I kept the 60-minute retention rather than switching to last-N-per-chat, reasoning in the thread. Short version: retention starts at process exit, so your 2-hour case already works, and a per-chat count needs a global bound plus a cross-chat eviction order to be safe. Happy to do that as its own change if you still want it.

Revised by Mux, an AI coding agent, operating on Mike's behalf.

@github-actions github-actions Bot added the stale This issue is like stale bread. label Aug 9, 2026
@github-actions github-actions Bot closed this Aug 14, 2026
@ibetitsmike ibetitsmike reopened this Aug 27, 2026
…cess API

Adds agent/agentrunonce, a keyed reservation registry that makes a
repeated operation run once: the first caller to reserve a key performs
the work, later callers presenting the same input attach to the value
it published. The registry never interprets that value, so operations
whose results have nothing in common can share the rule. Process
starts are its first adapter; the process manager keeps owning output,
exit state, signals, and git-watcher registration.

Process starts pass a client token as the key and a digest of the
fields that decide what gets spawned (command, requested workdir, env,
background, chat) as the input fingerprint. Recording the fingerprint
when the key is reserved lets a mismatched retry fail immediately
rather than first waiting out a start it could never attach to.

Start conflicts now carry a machine-readable code so callers do not
have to match error text: input_mismatch is permanent, start_pending
means the owning start had not published a process yet and a retry may
still attach.
@ibetitsmike
ibetitsmike force-pushed the mike/codagt-757-lite/01-agent-start-tokens branch from 3f1ac82 to 22dc279 Compare August 27, 2026 14:41
@ibetitsmike

Copy link
Copy Markdown
Collaborator Author

@mafredri The stale bot closed all four PRs in this stack while they sat idle; they are reopened, and the whole stack is now rebased onto current main (about 520 commits of drift).

Rebase notes:

  • chattool/execute.go and generation_preparer.go collided with the agent-browser-session work from main. Both resolutions are plain unions: ExecuteOptions now carries AgentBrowserSession and Logger, and the env plumbing from main is untouched.
  • Part of this stack's dispatcher refactor had independently landed on main (executeTool taking options), so the rebased commits shrank slightly. Each rebased commit was diffed against its original to confirm nothing else moved.
  • Unit tests for every touched package pass locally on the rebased heads; CI is running on all four PRs.

When you have time, another pass over the stack would be appreciated. All 31 of your earlier threads have replies, including the two where I pushed back with evidence and left the final call to you.

Xum acted on Mike's behalf (@ibetitsmike).

@ibetitsmike
ibetitsmike requested a review from mafredri August 27, 2026 14:44
@github-actions github-actions Bot removed the stale This issue is like stale bread. label Aug 28, 2026
@github-actions github-actions Bot added the stale This issue is like stale bread. label Sep 5, 2026
@github-actions github-actions Bot closed this Sep 8, 2026
@mafredri mafredri reopened this Sep 9, 2026
@github-actions github-actions Bot removed the stale This issue is like stale bread. label Sep 10, 2026
@github-actions github-actions Bot added the stale This issue is like stale bread. label Sep 17, 2026
@github-actions github-actions Bot closed this Sep 20, 2026
@mafredri mafredri reopened this Sep 21, 2026
@mafredri mafredri removed the stale This issue is like stale bread. label Sep 21, 2026
@github-actions github-actions Bot added the stale This issue is like stale bread. label Sep 29, 2026
@mafredri

Copy link
Copy Markdown
Member

Closing: #29946 (merged) and #29954 replace this stack. The workspace agent now runs each chat tool call once per tool call ID, so a retry reuses the first run, and an interrupt cancels unresolved execute, edit_files, and write_file calls. #27371 stays open; the task attempt timeout is CODAGT-750.

🤖 This review was automatically generated with Coder Agents.

@mafredri mafredri closed this Sep 30, 2026
@github-actions github-actions Bot locked and limited conversation to collaborators Sep 30, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

stale This issue is like stale bread.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants