Skip to content

refactor!: one way to hold, observe and approve writes - #8

Merged
mukezhz merged 1 commit into
mainfrom
feat/simplify-api
Nov 16, 2026
Merged

mukezhz merged 1 commit into
mainfrom
feat/simplify-api

Conversation

@mukezhz

@mukezhz mukezhz commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Stacked on #7.

Problem

The approval and observability API had two ways to do several things:

  • Options.Plan (hold every write) next to NeedsApproval (hold some writes), with the results in two places (Result.Planned and *Pending). Plan and Plans sitting side by side read as a typo.
  • Options.OnCall and Options.OnEvent, two hooks for overlapping information.
  • agent.Apply(calls) and plans.Approve(id), two ways to approve.
  • Hosts had to build &codemode.Recorder{Approved: true}, an internal type, just to say "a person pressed this button".

Solution

One way to do each thing:

Before After
Options.Plan, Result.Planned Options.HoldWrites; held writes return *agent.Pending and go through Plans like any write that needs approval
Options.OnCall removed; OnEvent call events carry the call's Input
agent.Apply removed; approve with plans.Approve
&codemode.Recorder{Approved: true} codemode.WithApproval(ctx); Approved is unexported
Call.Planned, Recorder.Pending() Call.Held, Recorder.Held(): one word, "held", throughout

The common case is now five calls and three result types:

source, _ := gosource.New(gosource.Func(...))
mode, _ := codemode.FromSource(source, caller)
plans := agent.NewPlans(store, agent.PlanOptions{})
out, res, err := agent.RunAs[T](ctx, mode, model, request, agent.Options{
	Runner: runner, Plans: plans, PlanOwner: user.ID, OnEvent: log,
})
// err: *agent.Pending -> plans.Approve / plans.Reject; *agent.Error -> RunID, Stage

Examples and docs are updated: taskreport's audit log reads call events, its board delete uses WithApproval, and the CRM walkthrough confirms plans by ID. None of the removed APIs were released.

Verification

  • make test: buf lint, go test ./..., the env check and the consumer check.
  • TestHoldWritesIsADryRunThatApprovalApplies: HoldWrites holds the write, and approving the plan runs it.
  • TestOnEventSeesEachCallWithItsInput: call events carry the call's name and input.
  • The taskreport audit-line test passes on events.
  • The docs site builds with no dead links. The taskreport frontend rebuilds with no changes.
  • git grep finds no remaining uses of the removed names outside changelog history and notes.

- Options.Plan becomes Options.HoldWrites. Held writes return
  *agent.Pending like any write that needs approval, and Result.Planned
  is removed.
- Options.OnCall is removed. OnEvent carries every call, with its input,
  and taskreport's audit log reads call events.
- agent.Apply is removed. Plans are approved through agent.Plans.
- codemode.WithApproval(ctx) replaces setting Recorder.Approved, which is
  now unexported.
- Call.Planned is renamed Held, and Recorder.Pending() is renamed Held().

None of these were released.
Base automatically changed from feat/durable-plans to main November 16, 2026 06:10
@mukezhz
mukezhz merged commit 2d149d6 into main Nov 16, 2026
0 of 7 checks passed
@mukezhz
mukezhz deleted the feat/simplify-api branch November 16, 2026 06:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant