fix(office): routine create/save persists every field and can arm a cron schedule (#3759)

Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com>
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
This commit is contained in:
Henry
2026-09-17 21:34:22 +08:00
committed by GitHub
parent b99ac97a24
commit cf9c98ded0
37 changed files with 4127 additions and 286 deletions
+116
View File
@@ -0,0 +1,116 @@
---
created: 2026-09-17
status: done
requirements:
- REQ-OFFICE-ROUTINE-WIRE-001
- REQ-OFFICE-ROUTINE-WIRE-002
- REQ-OFFICE-ROUTINE-WIRE-003
- REQ-OFFICE-ROUTINE-WIRE-004
system_design:
- ../../specs/office/system-design/routine-wire-contract.md
---
# Implementation plan: Office routine wire contract (camelCase/snake_case adapter)
## Overview
The Office routine HTTP contract is snake_case in both directions
(`apps/backend/internal/office/routines/dto.go`), while the web client sent
and read camelCase. Go's `encoding/json` matches case-insensitively but does
not fold underscores, so every multi-word key was silently discarded on
write, a cron trigger could not be armed at all, and reads rendered blanks,
placeholders, or the characters of a JSON-encoded string one per line. This
plan closes that gap with a single adapter at the client's API boundary that
translates in both directions, so no HTTP contract, Go struct tag, database
column, or scheduler behavior changes.
## Scope
In scope: a create/update/trigger request builder that emits the exact
snake_case keys the backend binds, JSON-encoding `task_template` and
`variables` as strings (REQ-001); a create-routine and detail-view control
flow that arms, replaces, and reports on a cron trigger correctly (REQ-002);
a response adapter that unwraps envelopes, decodes JSON-encoded string
fields, and produces camelCase models with no snake_case fallback casts and
no `as unknown as` (REQ-003); and the same normalization applied to routine
runs, including the previously-missing `dispatchFingerprint`, `linkedTaskId`
and `createdAt` (REQ-004).
Out of scope: any HTTP contract, Go struct tag, database column, or
scheduler behavior change; clearing an armed cron schedule; enqueueing more
than one run per resumed tick; and the pre-existing `AgentRunSummary` wire
shape consumed by `app/office/agents/[id]/`, which this capability does not
own (system design, [Out of scope](../../specs/office/system-design/routine-wire-contract.md#out-of-scope)).
## Technical approach
`apps/web/lib/api/domains/office-routine-api.ts` builds every create/update/
trigger request body from typed inputs, emitting only the contract's
snake_case keys and JSON-encoding `task_template`/`variables` before they
leave the client. `apps/web/lib/api/domains/office-routine-normalize.ts` is
the single response-side adapter: it unwraps the envelope, decodes the two
JSON-encoded string fields back into objects (falling back to `{}` for
anything that isn't a JSON object per the requirement's definition), and
maps every wire field to its camelCase model field with no
`as`/`as unknown as` cast. `apps/web/lib/api/domains/office-api.ts` now calls
through these two modules instead of shipping ad hoc request/response
shapes. `apps/web/app/office/routines/[id]/cron-reconcile.ts` centralizes the
create-before-delete replacement logic for a changed cron schedule (REQ-002:
AC-002.4 through AC-002.11), including the two-cron-trigger and
failed-relist error messages. `routine-row.tsx` and `routine-detail-view.tsx`
were changed to consume model-shape fields exclusively; `routine-row.tsx`
also gained a defensive `templateText` guard (a non-string `task_template`
title/description, reachable only because this branch is the first time that
field's content reaches JSX, would otherwise crash React's renderer).
`create-routine-dialog.tsx`'s `onSubmit` now returns `Promise<boolean>` so a
rejected `createRoutine` leaves the dialog open with the user's input intact
instead of silently resetting the form. `routine-wire-scan.test.ts` is the
static scan required by AC-003.10 and AC-003.18: it asserts no snake_case
wire key and no `as unknown as` appear under
`apps/web/app/office/routines/**` plus
`apps/web/src/office-routine-client-routes.tsx`, and that the set of files
outside that scope reading `s.office.routines` is exactly the two enumerated
in the system design's Testing section.
## Implementation waves and parallel candidates
- [x] [Task 01: camelCase/snake_case adapter and cron-reconcile control flow](task-01-wire-adapter.md) (`done`) — REQ-001, REQ-002, REQ-003, REQ-004
Single wave: the request builder, response adapter, and the UI components
that consume them all change together behind one contract, so there is no
useful task split.
## Verification results
`pnpm --filter @kandev/web run typecheck`, `pnpm --filter @kandev/web run lint`
and `pnpm --filter @kandev/web run test` (vitest, full `app/office/routines`
and `lib/api/domains/office-routine-*` suites) all green. `pnpm run
i18n:ratchet` and `pnpm run i18n:check` clean across English, `pt-pt`,
`zh-cn`, `zh-hk`, `zh-tw` and pseudo. `pnpm run build` (Vite production
build) succeeds. `apps/web/e2e` Playwright run green, including
`routines-ui.spec.ts` (create dialog persists assignee/policies/task
template and arms a cron trigger; detail view save persists a changed
schedule; list/detail render persisted assignee, policy and declared
variables; an unrecognized persisted status hides the next-fire countdown; a
post-create refetch failure reports its own toast and still closes the
dialog), `routine-catch-up-policy-ui.spec.ts`, `routine-fire.spec.ts`,
`agentctl-cli.spec.ts`'s routines coverage, and the i18n pseudo-locale
coverage check for the routines pages. Four independent review rounds
(code-reviewer, security-reviewer, test-supervisor, plus a cross-vendor
outside voice) converged with no residual defect; the final round's one
verified finding (a React crash on a non-string `task_template` field) and
one pre-existing regression (the create dialog silently discarding form
input on a rejected create) were both fixed and covered by regression tests
in the same round.
## Risks and out of scope
- The client cannot validate that the server actually stored what it sent;
it can only prove it sent the contract's exact keys and shapes. Any future
DTO change on the backend needs a matching adapter change, not the reverse.
- `app/office/agents/[id]/` reads `s.office.routines` for `AgentRunSummary`
data this capability does not own; those two files are deliberately
excluded from the AC-003.10/AC-003.18 static scan rather than migrated.
- Clearing an already-armed cron schedule from the UI remains unbuilt
(system design, Out of scope); AC-002.13 only covers leaving it untouched
when the submitted expression is empty after trimming.
@@ -0,0 +1,157 @@
---
id: "01-wire-adapter"
title: "camelCase/snake_case adapter and cron-reconcile control flow"
status: done
wave: 0
depends_on: []
plan: "plan.md"
requirements:
- REQ-OFFICE-ROUTINE-WIRE-001
- REQ-OFFICE-ROUTINE-WIRE-002
- REQ-OFFICE-ROUTINE-WIRE-003
- REQ-OFFICE-ROUTINE-WIRE-004
acceptance_criteria:
- AC-OFFICE-ROUTINE-WIRE-001.1
- AC-OFFICE-ROUTINE-WIRE-001.2
- AC-OFFICE-ROUTINE-WIRE-001.3
- AC-OFFICE-ROUTINE-WIRE-001.4
- AC-OFFICE-ROUTINE-WIRE-001.5
- AC-OFFICE-ROUTINE-WIRE-001.6
- AC-OFFICE-ROUTINE-WIRE-001.7
- AC-OFFICE-ROUTINE-WIRE-001.8
- AC-OFFICE-ROUTINE-WIRE-001.9
- AC-OFFICE-ROUTINE-WIRE-001.10
- AC-OFFICE-ROUTINE-WIRE-001.11
- AC-OFFICE-ROUTINE-WIRE-002.1
- AC-OFFICE-ROUTINE-WIRE-002.2
- AC-OFFICE-ROUTINE-WIRE-002.3
- AC-OFFICE-ROUTINE-WIRE-002.4
- AC-OFFICE-ROUTINE-WIRE-002.5
- AC-OFFICE-ROUTINE-WIRE-002.6
- AC-OFFICE-ROUTINE-WIRE-002.7
- AC-OFFICE-ROUTINE-WIRE-002.8
- AC-OFFICE-ROUTINE-WIRE-002.9
- AC-OFFICE-ROUTINE-WIRE-002.10
- AC-OFFICE-ROUTINE-WIRE-002.11
- AC-OFFICE-ROUTINE-WIRE-002.12
- AC-OFFICE-ROUTINE-WIRE-002.13
- AC-OFFICE-ROUTINE-WIRE-002.14
- AC-OFFICE-ROUTINE-WIRE-003.1
- AC-OFFICE-ROUTINE-WIRE-003.2
- AC-OFFICE-ROUTINE-WIRE-003.3
- AC-OFFICE-ROUTINE-WIRE-003.4
- AC-OFFICE-ROUTINE-WIRE-003.5
- AC-OFFICE-ROUTINE-WIRE-003.6
- AC-OFFICE-ROUTINE-WIRE-003.7
- AC-OFFICE-ROUTINE-WIRE-003.8
- AC-OFFICE-ROUTINE-WIRE-003.9
- AC-OFFICE-ROUTINE-WIRE-003.10
- AC-OFFICE-ROUTINE-WIRE-003.11
- AC-OFFICE-ROUTINE-WIRE-003.12
- AC-OFFICE-ROUTINE-WIRE-003.13
- AC-OFFICE-ROUTINE-WIRE-003.14
- AC-OFFICE-ROUTINE-WIRE-003.15
- AC-OFFICE-ROUTINE-WIRE-003.16
- AC-OFFICE-ROUTINE-WIRE-003.17
- AC-OFFICE-ROUTINE-WIRE-003.18
- AC-OFFICE-ROUTINE-WIRE-003.19
- AC-OFFICE-ROUTINE-WIRE-004.1
- AC-OFFICE-ROUTINE-WIRE-004.2
- AC-OFFICE-ROUTINE-WIRE-004.3
- AC-OFFICE-ROUTINE-WIRE-004.4
- AC-OFFICE-ROUTINE-WIRE-004.5
system_design:
- ../../specs/office/system-design/routine-wire-contract.md
---
# Task 01: camelCase/snake_case adapter and cron-reconcile control flow
## Summary
The routines UI sent and read camelCase against a snake_case backend
contract, so multi-word fields (assignee, policies, task template, cron
schedule, declared variables) were silently discarded on write and rendered
as blanks, placeholders, or one character per line on read, and a cron
trigger could not be armed at all. This task adds a single adapter pair at
the client's API boundary — a request builder that emits the contract's
exact snake_case keys and a response normalizer that produces camelCase
models with no snake_case fallback and no unchecked cast — plus the
cron-reconcile control flow that replaces an armed trigger correctly when
its schedule changes.
## In scope
- `apps/web/lib/api/domains/office-routine-api.ts`: request builders for
create/update routine and create routine trigger, emitting only the keys
and shapes `apps/backend/internal/office/routines/dto.go` binds.
- `apps/web/lib/api/domains/office-routine-normalize.ts`: the response-side
adapter — envelope unwrap, JSON-string decode for `task_template` and
`variables`, and the routine/trigger/run camelCase mapping.
- `apps/web/lib/api/domains/office-api.ts`: wires the two modules above into
the existing exported API surface.
- `apps/web/app/office/routines/[id]/cron-reconcile.ts`: create-before-delete
trigger replacement, the two-cron-trigger warning, and the failed-relist
message.
- `apps/web/app/office/routines/{routine-row.tsx, routines-content.tsx,
create-routine-dialog.tsx, [id]/routine-detail-view.tsx, [id]/page.tsx}`,
`apps/web/app/office/agents/[id]/layout.tsx`,
`apps/web/app/office/lib/catch-up-max.ts`,
`apps/web/src/office-routine-client-routes.tsx`: consume model-shape
fields exclusively; `create-routine-dialog.tsx`'s `onSubmit` returns
`Promise<boolean>` so a rejected create leaves the dialog open.
- `apps/web/app/office/routines/routine-wire-scan.test.ts`: the static
no-snake_case / no-`as unknown as` scan required by AC-003.10, and the
closed-set assertion required by AC-003.18.
- `apps/web/src/locales/{en,pt-pt,zh-cn,zh-hk,zh-tw,pseudo}/office.json`: the
new trigger-replacement and stale-schedule toast copy (AC-002.12).
- `apps/web/e2e/tests/office/routines-ui.spec.ts` and the routine
catch-up/fire/agentctl-cli E2E suites touched by the model-shape change.
## Acceptance
Every acceptance criterion under REQ-OFFICE-ROUTINE-WIRE-001 through
REQ-OFFICE-ROUTINE-WIRE-004 in
[the requirements](../../specs/office/requirements/routine-wire-contract.md),
listed in this file's frontmatter.
## Verification
```bash
cd apps/web
pnpm run typecheck
pnpm run lint
pnpm run test -- app/office/routines lib/api/domains/office-routine-api.test.ts lib/api/domains/office-routine-normalize.test.ts
pnpm run i18n:ratchet
pnpm run i18n:check
pnpm run build
pnpm run e2e:run -- routines-ui routine-catch-up-policy-ui routine-fire
```
## Files likely touched
See `## In scope` above; full diff stat against the branch's merge-base:
`git diff --stat $(git merge-base HEAD origin/main)..HEAD`.
## Dependencies
None — single task, single wave.
## Parallelism
Not applicable: the request builder, response adapter, and the components
that consume them change together behind one contract.
## Results
Shipped on `feature/routines-ui-camelcas-rf9`. Four independent review
rounds (code-reviewer, security-reviewer, test-supervisor, and a
cross-vendor outside voice) converged with no residual defect. The final
round's one verified new finding — a React crash on a non-string
`task_template.title`/`.description`, reachable only because this branch is
the first time that field's content reaches JSX — was fixed with a
`templateText` guard and regression test. A second, pre-existing
finding surfaced by that same round's test work — the create dialog
resetting and losing the operator's input on a rejected `createRoutine` call
— was fixed by making `onSubmit` report success/failure and only
closing/resetting on success, with regression coverage in
`routines-content.test.tsx`.
@@ -0,0 +1,339 @@
---
status: draft
system: office
created: 2026-09-17
owners:
- kandev
---
# Office Routine Wire Contract Requirements
## Overview
The Office routine HTTP contract is snake_case in both directions:
`CreateRoutineRequest`, `UpdateRoutineRequest` and `CreateTriggerRequest`
(`apps/backend/internal/office/routines/dto.go`) bind keys like `task_template`
and `cron_expression`, and `models.Routine`, `models.RoutineTrigger` and
`models.RoutineRun` serialize the same keys. The web client sends and reads
camelCase. Go's `encoding/json` matches case-insensitively but does not fold
underscores, so every multi-word key crosses the boundary and is discarded.
This is measured, not inferred: binding the real DTOs through `gin`
`ShouldBindJSON`, a camelCase routine body binds `name` alone, a camelCase
`cronExpression` is rejected as a 400, and a `task_template` sent as a JSON
object fails to bind.
Both consequences are live. On write, a routine's assignee, policies, catch-up
max and task template are silently dropped, so the UI reports success and
persists defaults. On the trigger path nothing is silent: a cron schedule cannot
be armed at all, removing the product's only path to an unattended routine. On read, only `routine-row.tsx` has snake_case fallbacks
and only for two fields, so the detail form, the expanded row, the Schedule
card and the Runs list render blanks.
This capability makes the web client speak the contract the backend publishes.
It changes no HTTP contract, no Go struct tag, no database column and no
scheduler behavior.
## Terminology
Wire shape, model shape, adapter, envelope, arm, patch field, effective
timezone and trimmed expression are defined in the system design's
[Terminology](../system-design/routine-wire-contract.md#terminology).
## Requirements
### REQ-OFFICE-ROUTINE-WIRE-001: Routine configuration written from the UI is persisted
**Intent:** A create or save that reports success must have persisted what the
operator chose. Today every multi-word field is discarded and the operator is
told it worked.
**User story:** As an operator, I want the assignee, policies and task template
I pick to be saved, so that a routine does what I configured it to do.
#### Acceptance criteria
- **AC-OFFICE-ROUTINE-WIRE-001.1:** When the client creates a routine, the
system shall send each supplied value AC-001.11 admits under its contract
key: `name`,
`description`, `task_template`, `assignee_agent_profile_id`,
`concurrency_policy`, `catch_up_policy`, `catch_up_max`, `variables`.
- **AC-OFFICE-ROUTINE-WIRE-001.2:** When the client creates a routine, the
system shall send no key outside AC-001.1's set, and in particular no
camelCase spelling of any of them.
- **AC-OFFICE-ROUTINE-WIRE-001.3:** When the client sends `task_template` or
`variables`, the system shall send a JSON-encoded string, never a JSON object,
because the bound fields are Go strings and an object is rejected as a 400.
- **AC-OFFICE-ROUTINE-WIRE-001.4:** When the client updates a routine, the
system shall include exactly the patch fields AC-001.10 and AC-001.11 admit,
so a field the caller did not supply is absent from the request body and the
stored value is unchanged.
- **AC-OFFICE-ROUTINE-WIRE-001.5:** When a caller supplies an empty string for
`assignee_agent_profile_id`, `description` or `task_template` on update, the
system shall send it, because an empty string clears and an absent key
preserves (AC-001.11).
- **AC-OFFICE-ROUTINE-WIRE-001.6:** When the client creates a routine, the
system shall not send `workspace_id` or `status`, because the handler takes
the workspace from the route and forces `active`.
- **AC-OFFICE-ROUTINE-WIRE-001.7:** When a caller does not supply
`concurrency_policy` or `catch_up_policy`, the system shall omit that key and
shall not substitute a client-side default, so the server defaults
(`skip_if_active`, `summarize_missed`) apply.
- **AC-OFFICE-ROUTINE-WIRE-001.8:** When the routine list toggle pauses or
resumes a routine, the system shall send `status` alone and shall not widen
the patch to any other field.
- **AC-OFFICE-ROUTINE-WIRE-001.9:** When the client updates a routine, the
system shall send no key outside AC-001.1's set plus `status`, and in
particular no camelCase spelling of any of them. `status` is an update key
and not a create key (AC-001.6).
- **AC-OFFICE-ROUTINE-WIRE-001.10:** When a caller supplies an empty
`concurrency_policy` or `catch_up_policy` on update, the system shall omit
that key rather than send the empty string, because `Valid()`
(`models/enums.go`) rejects it with a 400. Those two keys are the only ones
where empty means omit; every other update key transmits its empty string and
clears (AC-001.11).
- **AC-OFFICE-ROUTINE-WIRE-001.11:** When the system builds an update body, the
clearable set shall be `name`, `description`, `task_template`,
`assignee_agent_profile_id`, `status` and `variables`, not AC-001.5's three:
`UpdateRoutineRequest` types all six as pointers and `applyRoutineUpdates`
(`routines/handler.go`) assigns each one unvalidated, so an empty string
supplied for any of the six is stored rather than ignored. The system shall
not send an empty `status` (AC-003.17), and shall omit a `catch_up_max` below 1
from a create or an update body rather than send it, because `*int` stores
what is sent (AC-003.13).
### REQ-OFFICE-ROUTINE-WIRE-002: A cron schedule can be armed and changed from the UI
**Intent:** A routine with no cron trigger never fires unattended. The trigger
create call is currently rejected outright, so the UI cannot arm one.
**User story:** As an operator, I want to set a routine's schedule in the UI,
so that the routine runs without me firing it by hand.
#### Acceptance criteria
- **AC-OFFICE-ROUTINE-WIRE-002.1:** When the client creates a routine trigger,
the system shall send `kind`, `cron_expression`, `timezone`, `public_id`,
`signing_mode` and `secret` under those keys, omitting any the caller did not
supply.
- **AC-OFFICE-ROUTINE-WIRE-002.2:** When the create-routine flow is submitted
with trigger kind `cron` and a non-empty trimmed expression, the system shall
arm a cron trigger on the new routine, and the created trigger's `next_run_at`
shall be non-null. A next fire time is a trigger field, not a routine field.
- **AC-OFFICE-ROUTINE-WIRE-002.3:** When the detail view opens for a routine
that has a cron trigger, the system shall seed the form with that trigger's
stored expression and timezone.
- **AC-OFFICE-ROUTINE-WIRE-002.4:** When the detail view is saved, the draft's
trimmed expression matches the stored trigger's expression exactly, and the
draft's effective timezone matches the stored trigger's effective timezone,
the system shall issue no trigger create and no trigger delete.
- **AC-OFFICE-ROUTINE-WIRE-002.5:** When the detail view is saved with a changed
expression or timezone, the system shall create the replacement trigger before
deleting the superseded one. When the routine has no cron trigger yet, the
system shall create one and delete nothing.
- **AC-OFFICE-ROUTINE-WIRE-002.6:** When that replacement create is rejected,
the system shall leave the existing trigger in place, shall issue no delete,
shall show the server's error message in an error toast, and shall show no
success toast.
- **AC-OFFICE-ROUTINE-WIRE-002.7:** When the replacement create succeeds and the
subsequent delete fails, the system shall re-list the routine's triggers and
show an error toast naming the delete failure and stating how many cron
triggers that re-list found, because two cron triggers both fire. When the
re-list itself fails, the toast shall instead state that the
trigger's fate is unknown and the page needs a reload.
- **AC-OFFICE-ROUTINE-WIRE-002.8:** When a routine has more than one cron
trigger, the system shall seed, replace and display the first cron trigger in
the order the list endpoint returned (`ORDER BY created_at`), and shall leave
the others untouched. That order is always read from an endpoint response
(AC-002.11).
- **AC-OFFICE-ROUTINE-WIRE-002.9:** When a save updates the routine and its
trigger create or delete then fails, the system shall show an error toast
naming the trigger error and stating that the routine's own fields were saved
and the schedule was not, shall show no success toast, and shall re-list the
routine's triggers. A failed re-list is AC-002.11's case, not this one.
- **AC-OFFICE-ROUTINE-WIRE-002.10:** When the create-routine flow creates the
routine and its cron trigger create then fails, the system shall close the
create dialog, refresh the routine list so the new routine is visible, and
show an error toast naming the trigger error and stating that the routine was
created without a schedule. The routine is not deleted.
- **AC-OFFICE-ROUTINE-WIRE-002.11:** When the system creates or deletes a
trigger, it shall render the routine's triggers from a fresh list response
rather than from a locally spliced array. When that re-list fails after the
create and delete both succeeded, the system shall report the save as
succeeded and state that the displayed schedule may be stale until a reload.
- **AC-OFFICE-ROUTINE-WIRE-002.12:** When AC-002.7, AC-002.9, AC-002.10 or
AC-002.11 shows a message today's code has no string for, that message shall
be a translated `office`-namespace key present in English, `pt-pt`, `zh-cn`,
`zh-hk` and `zh-tw`.
- **AC-OFFICE-ROUTINE-WIRE-002.13:** When the detail view is saved with a cron
expression that is empty after trimming, the system shall issue no trigger
create and no trigger delete, leaving any existing trigger armed. Clearing a
schedule is out of scope below.
- **AC-OFFICE-ROUTINE-WIRE-002.14:** When the system decides whether a cron
expression is empty, it shall decide on the trimmed expression, and when it
sends one it shall send that trimmed string, so whitespace alone is empty at
every gate and never reaches the server. The three live gates disagree today
(system design, [Control flow](../system-design/routine-wire-contract.md#control-flow)).
### REQ-OFFICE-ROUTINE-WIRE-003: Routine and trigger reads render persisted values
**Intent:** The list, the expanded row, the detail form and the Schedule card
must show what is stored. Today they show blanks, placeholders and, for declared
variables, the characters of a JSON string one per line.
**User story:** As an operator, I want the routine pages to show the stored
configuration, so that I can see what a routine will actually do.
#### Acceptance criteria
- **AC-OFFICE-ROUTINE-WIRE-003.1:** When a routine endpoint returns a routine,
the system shall produce a model whose `taskTemplate`,
`assigneeAgentProfileId`, `concurrencyPolicy`, `catchUpPolicy`, `catchUpMax`,
`variables`, `lastRunAt`, `workspaceId`, `createdAt` and `updatedAt` carry the
persisted values.
- **AC-OFFICE-ROUTINE-WIRE-003.2:** When a routine endpoint returns a trigger,
the system shall produce a model whose `routineId`, `cronExpression`,
`timezone`, `publicId`, `signingMode`, `nextRunAt`, `lastFiredAt`, `enabled`,
`createdAt` and `updatedAt` carry the persisted values. `created_at` and
`updated_at` are mapped, not direct: the model declares them camelCase.
- **AC-OFFICE-ROUTINE-WIRE-003.3:** When the wire carries `task_template` or
`variables` as a JSON-encoded string, the system shall parse it into an object
before it reaches a component.
- **AC-OFFICE-ROUTINE-WIRE-003.4:** When that string is empty, is not valid
JSON, or does not decode to a JSON object, the system shall produce an empty
object rather than raising or passing the raw string through. A JSON object
here means a non-null, non-array object, so `null`, `[]`, `[{"a":1}]`, `3` and
`"text"` all produce the empty object.
- **AC-OFFICE-ROUTINE-WIRE-003.5:** When a response is enveloped, the system
shall unwrap it by reading the envelope key alone, so a caller receives the
resource or the array and never a wrapper object. On a list endpoint a missing
key, a `null` payload and a non-array payload all produce the empty array. On
a single-resource endpoint the same three cases are an error (AC-003.15), not
an empty model. A body that is not an object has no envelope key and takes the
same branch as a missing one.
- **AC-OFFICE-ROUTINE-WIRE-003.6:** When a routine or trigger field is absent or
`null`, the system shall produce the empty string for a field the model
declares as a required string, `{}` for one it declares as a required object
(`taskTemplate`), `undefined` for a field the model declares optional, and
`false` for `enabled`, and shall not substitute a policy value the server did
not send. `status` and `kind` are required strings and take the
same rule as any other (AC-003.16).
- **AC-OFFICE-ROUTINE-WIRE-003.7:** When a list response contains an element
that is not a JSON object in AC-003.4's sense, the system shall drop that
element and keep the rest.
- **AC-OFFICE-ROUTINE-WIRE-003.8:** When a list response is returned, the system
shall preserve the server's element order and shall not re-sort.
- **AC-OFFICE-ROUTINE-WIRE-003.9:** When a trigger is normalized, the system
shall map only the fields the model declares, so the wire's `secret` key does
not enter the client model or the store.
- **AC-OFFICE-ROUTINE-WIRE-003.10:** When a component renders a routine, trigger
or run, it shall read only model-shape fields. The claim is checked by a scan
over `apps/web/app/office/routines/**` plus
`apps/web/src/office-routine-client-routes.tsx` asserting two negatives: no
snake_case wire key from the three mapping tables, and no `as unknown as`.
That removes `routine-row.tsx`'s two snake_case fallback casts and all four
envelope casts. The fourth is `syncCronTrigger`'s, which alone has no
bare-resource fallback and would silently drop the created trigger if it
survived the unwrap (system design,
[Components and responsibilities](../system-design/routine-wire-contract.md#components-and-responsibilities)).
- **AC-OFFICE-ROUTINE-WIRE-003.11:** When a routine declares variables, the
expanded row shall render one entry per declared variable name, not one entry
per character of the encoded string.
- **AC-OFFICE-ROUTINE-WIRE-003.12:** When the wire carries `catch_up_max`, the
system shall carry the stored number into the model unchanged and shall not
clamp it, because the server normalizes at use
(`models.NormaliseCatchUpMax`, ceiling 1000) and the model must report what is
stored.
- **AC-OFFICE-ROUTINE-WIRE-003.13:** When a routine form seeds a catch-up max
below 1, or the operator enters one below 1, the system shall use 25, because
the server treats a sub-1 stored value as 25. `min={1}` enforces nothing here:
no routine form saves through a form submit.
- **AC-OFFICE-ROUTINE-WIRE-003.14:** When the wire carries an empty `status`,
the system shall carry the empty string into the model unchanged, because the
empty string is a firing status the scheduler and `isRoutineFiring` both
honour, and substituting `active` would assert a value no writer set.
- **AC-OFFICE-ROUTINE-WIRE-003.15:** When a single-resource endpoint returns a
body whose resource is missing, `null`, not a JSON object in AC-003.4's sense,
or an object carrying no non-empty `id`, the system shall reject the call with
an error rather than produce a model built from nothing. The create-routine flow reads the new routine's `id`
to arm its trigger, so an empty model would skip arming silently.
- **AC-OFFICE-ROUTINE-WIRE-003.16:** When the adapter produces a routine,
trigger or run model, it shall do so without a type assertion, so
`Routine.status`, `RoutineRun.status` and `RoutineTrigger.kind` shall each
admit any string the server stored. None is validated on write, so `""`
(AC-003.14, AC-004.5) and an arbitrary `unknown` are both reachable.
- **AC-OFFICE-ROUTINE-WIRE-003.17:** When the detail form seeds from a routine
whose `status` is not one of the control's three options, `""` included, the
control shall show no selected option, and a save that left it untouched shall
omit `status` from the patch rather than write back a value no writer set
(AC-001.11). A `""` routine shall still read as firing wherever firing state
is shown (AC-003.14). No `unset` option is added.
- **AC-OFFICE-ROUTINE-WIRE-003.18:** When a file outside AC-003.10's scanned set
reads `s.office.routines`, it shall consume model shape and shall test firing
state through `isRoutineFiring` rather than comparing `status` to a literal.
Two such files exist, both under `app/office/agents/[id]/`, and both are
outside the scan because they also consume `AgentRunSummary`, a wire shape
this contract does not own. The scan shall assert that the set of files
reading `s.office.routines` under `apps/web/app/**` is exactly the three that
do today, enumerated in the system design's
[Testing](../system-design/routine-wire-contract.md#testing), so a new
consumer fails the check rather than escaping the bound. AC-003.10's set is
larger: most of its files take routines as props.
- **AC-OFFICE-ROUTINE-WIRE-003.19:** When `CoordinatorRoutineHint` renders for
a CEO agent with a firing assigned routine present in `s.office.routines`, it
shall not show the "no scheduled wake-ups" hint. The criterion is the
component, not `/office/agents/:id`: nothing on that route populates the
store, so the hint shows there regardless (system design, Out of scope). This
capability owns the change: `assigneeAgentProfileId` is `undefined` for every
routine today, so the hint is unconditional until the assignee transmits.
### REQ-OFFICE-ROUTINE-WIRE-004: Routine run reads render persisted values
**Intent:** The Runs tab reads the same boundary and is broken the same way:
`dispatch_fingerprint`, `linked_task_id` and `created_at` never reach the model,
so every run shows placeholders and no linked task.
**User story:** As an operator, I want the Runs list to show when each run
happened and which task it created, so that I can tell whether a routine is
working.
#### Acceptance criteria
- **AC-OFFICE-ROUTINE-WIRE-004.1:** When a runs endpoint returns runs, the
system shall produce models whose `id`, `source`, `status`, `routineId`,
`triggerId`, `triggerPayload`, `linkedTaskId`, `coalescedIntoRunId`,
`dispatchFingerprint`, `catchUpMissedTicks`, `catchUpFirstMissedAt`,
`catchUpTruncated`, `startedAt`, `completedAt` and `createdAt` carry the
persisted values. `id`, `source` and `status` are named even though their
spellings match, because the adapter maps declared fields explicitly and
never spreads.
- **AC-OFFICE-ROUTINE-WIRE-004.2:** When a run's `catch_up_missed_ticks` is
absent, the system shall produce `undefined` and shall not produce `0`,
because absence is never represented as a stored zero (`routine-catch-up.md`
AC-002.3).
- **AC-OFFICE-ROUTINE-WIRE-004.3:** When a run row renders, it shall show the
run's creation time and, when the run created a task, the linked task id.
`run-row.tsx` already renders both; this verifies the values stop being
placeholders.
- **AC-OFFICE-ROUTINE-WIRE-004.4:** When the manual fire endpoint is called, the
system shall continue to send `{"variables": ...}` unchanged, which already
matches the contract.
- **AC-OFFICE-ROUTINE-WIRE-004.5:** When a run field is absent or `null`, the
system shall apply AC-003.6's rule to it. Absence is ordinary: a manually
fired run has no `trigger_id`, and a `received` run has neither `started_at`
nor `completed_at`. An empty or unrecognized `status` renders the unlabeled
badge `run-row.tsx` already produces, so no new copy is added.
## Concurrency, retry and ordering
Stated in the system design's
[Concurrency, retry and ordering](../system-design/routine-wire-contract.md#concurrency-retry-and-ordering):
they are properties of the server contract, not client choices, and AC-001.4,
AC-002.8, AC-002.11 and AC-003.8 depend on them.
## Out of scope
Listed in the system design's
[Out of scope](../system-design/routine-wire-contract.md#out-of-scope). Each
names what is not built here and what a later capability would have to settle.
@@ -0,0 +1,554 @@
---
status: draft
system: office
requirements:
- REQ-OFFICE-ROUTINE-WIRE-001
- REQ-OFFICE-ROUTINE-WIRE-002
- REQ-OFFICE-ROUTINE-WIRE-003
- REQ-OFFICE-ROUTINE-WIRE-004
---
# Office Routine Wire Contract System Design
## Purpose and boundaries
The Office system publishes the routine HTTP contract, so it owns the
translation between that contract and the web client's model shape. This
design places that translation in one adapter at the client's API boundary and
forbids it anywhere else.
Adjacent contracts this design uses but does not own: the routine HTTP
endpoints and DTOs (`apps/backend/internal/office/routines`), the routine
models (`apps/backend/internal/office/models`), and the shared fetch helpers
(`apps/web/lib/api/client.ts`). None of them change.
## Terminology
These terms are used throughout, here and in the requirements, which reference
this section rather than restating them.
- **Wire shape:** the JSON object the backend emits or binds, snake_case, with
`task_template` and `variables` carried as JSON-encoded strings.
- **Model shape:** the camelCase TypeScript types in
`apps/web/lib/state/slices/office/types.ts` that components consume.
- **Adapter:** the single translation point between wire shape and model
shape, in both directions.
- **Envelope:** the single-key object a routine endpoint wraps a resource in
(`{"routine": ...}`, `{"trigger": ...}`, `{"run": ...}`, `{"routines": [...]}`).
- **Arm:** create a cron trigger with a satisfiable expression, so the routine
will fire unattended.
- **Patch field:** a field the caller supplied to an update call; one the
caller did not supply is not a patch field.
- **Effective timezone:** a trigger's `timezone` with absent, `null` and the
empty string all read as `UTC`, matching `CreateRoutineTrigger`, which
rewrites an empty `Timezone` to `UTC` before storing it. Two effective
timezones are equal when their strings match exactly: no case folding, no
alias resolution, no offset comparison.
- **Trimmed expression:** a cron expression with leading and trailing
whitespace removed (AC-002.14).
## Requirement mapping
| Requirement | Design section |
| --- | --- |
| `REQ-OFFICE-ROUTINE-WIRE-001` | [Data and contracts](#data-and-contracts), [Control flow](#control-flow) |
| `REQ-OFFICE-ROUTINE-WIRE-002` | [Control flow](#control-flow), [Failure and recovery](#failure-and-recovery) |
| `REQ-OFFICE-ROUTINE-WIRE-003` | [Data and contracts](#data-and-contracts), [Components and responsibilities](#components-and-responsibilities) |
| `REQ-OFFICE-ROUTINE-WIRE-004` | [Data and contracts](#data-and-contracts) |
## Components and responsibilities
- **Routine wire adapter** (`apps/web/lib/api/domains/`): the only code that
knows a routine key is spelled `catch_up_policy`. Read direction normalizes
wire to model; write direction builds the request body from the model. It
maps declared fields explicitly and never spreads the raw object, so an
unmapped wire key such as `secret` cannot reach the store.
- **Routine API functions** (`office-api.ts`): call the adapter on the way out
and on the way back, and unwrap the response envelope so callers receive a
resource or an array.
- **Routine components** (`apps/web/app/office/routines/`): consume model shape
only. `routine-row.tsx`'s two snake_case fallback casts and four envelope
casts are removed, because the adapter now guarantees what they were
defending against. The envelope casts are in `routines-content.tsx`,
`app/office/routines/[id]/page.tsx`, `src/office-routine-client-routes.tsx`
and `[id]/routine-detail-view.tsx`. The fourth is the one that fails silently
if it is missed: `syncCronTrigger` ends `.trigger ?? null` where the other
three end in a bare-resource fallback (`?? (x as Resource)`), so against an
unwrapped return it yields `null`, the created trigger is dropped from local
state, and the page shows no schedule after an arm that succeeded. AC-003.10's
second negative is what catches it.
- **Office store slice**: unchanged. `setRoutines` is the only ingress and its
only feeder is `listRoutines`; the Go boot payload ships `"routines": []`
and no WebSocket event carries a routine, so the adapter has no bypass.
This mirrors the agent profile boundary in the same file (`normalizeAgent`,
`agentPayload`, `stringifyJSONField`) and `normalizeProject`. It follows
ADR-0036: a protocol shape is normalized
at the adapter and the frontend renders only the normalized contract.
## Data and contracts
Read direction. Left is the wire key, right is the model field.
| Routine | Model | Note |
| --- | --- | --- |
| `id`, `name`, `description`, `status` | same | single-word; `status` carries `""` unchanged (AC-003.14) |
| `workspace_id` | `workspaceId` | |
| `task_template` | `taskTemplate` | JSON string, parsed to object |
| `assignee_agent_profile_id` | `assigneeAgentProfileId` | |
| `concurrency_policy` | `concurrencyPolicy` | passthrough, no default substituted |
| `catch_up_policy` | `catchUpPolicy` | passthrough |
| `catch_up_max` | `catchUpMax` | number, `undefined` when absent, never clamped client-side |
| `variables` | `variables` | JSON string, parsed to object |
| `last_run_at` | `lastRunAt` | `null` maps to `undefined` |
| `created_at`, `updated_at` | `createdAt`, `updatedAt` | |
| Trigger | Model |
| --- | --- |
| `routine_id` | `routineId` |
| `cron_expression` | `cronExpression` |
| `public_id` | `publicId` |
| `signing_mode` | `signingMode` |
| `next_run_at` | `nextRunAt` |
| `last_fired_at` | `lastFiredAt` |
| `secret` | not mapped |
| `created_at`, `updated_at` | `createdAt`, `updatedAt` |
| `kind`, `timezone`, `enabled`, `id` | direct |
| Run | Model |
| --- | --- |
| `id`, `source`, `status` | direct |
| `routine_id`, `trigger_id` | `routineId`, `triggerId` |
| `trigger_payload` | `triggerPayload` |
| `linked_task_id` | `linkedTaskId` |
| `coalesced_into_run_id` | `coalescedIntoRunId` |
| `dispatch_fingerprint` | `dispatchFingerprint` |
| `catch_up_missed_ticks` | `catchUpMissedTicks`, `undefined` when absent |
| `catch_up_first_missed_at` | `catchUpFirstMissedAt` |
| `catch_up_truncated` | `catchUpTruncated` |
| `started_at`, `completed_at`, `created_at` | `startedAt`, `completedAt`, `createdAt` |
| `skip_reason`, `pause_id`, `causation_id` | not mapped, not rendered |
Model type changes (`types.ts`). The read mapping above cannot be written
without a cast against today's types, and AC-003.16 forbids the cast, so three
declarations widen to `string`. The server validates none of the three on
write, so each closed union is a claim the wire does not honour (AC-003.16):
- `Routine.status` becomes `string`. `models.Routine.Status` is a plain Go
string, `applyRoutineUpdates` assigns the patch pointer unguarded, and
`CanFire()` treats `""` as firing, so both `""` (AC-003.14) and an arbitrary
`unknown` written by the API, agentctl or config sync are reachable.
`RoutineStatus` stays as the union the client writes (`UpdateRoutinePatch`),
the direction the client does control. `Routine.status` has three consumers,
not one, and two of them need a change:
- `isRoutineFiring(status: string)` already takes a plain string and is
correct as written.
- `CoordinatorRoutineHint` (`app/office/agents/[id]/layout.tsx`) tests
`r.status === "active"` directly, bypassing `isRoutineFiring`, so a firing
`""` routine would read as not-firing. It moves to `isRoutineFiring`
(AC-003.18). That surface changes whether we touch it or not: the same
expression tests `r.assigneeAgentProfileId === agentId`, `undefined` for
every routine today (AC-003.19).
- `buildDraft` (`routine-detail-view.tsx`) narrows with
`(routine.status as DraftState["status"]) ?? "active"`, and `??` catches
neither. The cast goes; AC-003.17's unset control replaces it.
- `RoutineRun.status` becomes `string` the same way (AC-004.5). Blast radius is
nil: `RoutineRunStatus` has one reference, and `run-row.tsx`'s two lookup
tables are typed `Record<string, string>` with an `?? run.status` fallback, so
an unrecognized status renders as an unlabeled badge and needs no new copy.
- `RoutineTrigger.kind` becomes `string`. `CreateRoutineTrigger`
(`routines/service.go`) validates `cron_expression` for a cron trigger and
never validates `kind`. `RoutineTriggerKind` stays as the union the client
writes (`CreateTriggerInput.kind`). The `kind === "cron"` comparisons in `routine-detail-view.tsx` are unaffected.
No widening changes a rendered value; each makes the declared type match what
the wire can carry. No exhaustive `switch` exists over any of the three unions.
Widening rather than casting is the point: a cast at the adapter would defeat
AC-003.9's explicit-mapping discipline, which is what keeps `secret` out of the
store.
Write-side input types (`types.ts`, next to the model types). The write mapper
takes these rather than `Partial<Routine>`: the model's `taskTemplate` is a
`Record<string, unknown>` and cannot express AC-001.5's clearing empty string,
and `RoutineTrigger` does not declare the `secret` AC-002.1 requires:
- `CreateRoutineInput`: `name`, and optional `description`, `taskTemplate`,
`assigneeAgentProfileId`, `concurrencyPolicy`, `catchUpPolicy`, `catchUpMax`,
`variables`. No `status` and no `workspaceId` (AC-001.6).
- `UpdateRoutinePatch`: every `CreateRoutineInput` field optional, plus
`status`. This is the key set AC-001.9 fixes.
- `CreateTriggerInput`: `kind`, and optional `cronExpression`, `timezone`,
`publicId`, `signingMode`, `secret`.
`taskTemplate` and `variables` are typed `Record<string, unknown> | string` on
both input types, so an operator-cleared template is an expressible `""` rather
than a cast.
Write direction. A field the caller did not supply is absent from the body;
`JSON.stringify` drops an `undefined` value, so an explicitly supplied empty
string still serializes and still clears the stored value. `task_template` and
`variables` are encoded with the existing `stringifyJSONField` shape: an object
becomes its JSON text, a string passes through, `undefined` stays `undefined`.
An empty `concurrencyPolicy` or `catchUpPolicy` is dropped rather than sent,
because `Valid()` rejects it with a 400 (AC-001.10); those two are the only
fields where empty means omit rather than clear.
Everything else `UpdateRoutineRequest` types as a pointer clears on an empty
string, and that is six fields rather than AC-001.5's three: `name`,
`description`, `task_template`, `assignee_agent_profile_id`, `status` and
`variables` (`dto.go`, applied by `applyRoutineUpdates` as an unguarded
nil-check-then-assign). `status` is the consequential one: an empty status is stored unvalidated and
`CanFire()` treats it as firing, so AC-001.11 forbids sending one and AC-003.17
keeps an unset control from producing one. `catch_up_max` is a `*int`, so `0`
and negatives are storable and distinct from absent; the client sends neither
(AC-001.11, and [Failure and recovery](#failure-and-recovery) for why the
control is not the mechanism).
Envelopes. `listRoutines` unwraps `routines`; `getRoutine`, `createRoutine` and
`updateRoutine` unwrap `routine`; `createRoutineTrigger` unwraps `trigger`;
`listRoutineTriggers` unwraps `triggers`; `runRoutine` unwraps `run`;
`listRoutineRuns` and `listAllRoutineRuns` unwrap `runs`. The unwrap reads the
named key and nothing else. There is no bare-resource tolerance: a body that is
already the resource carries no envelope key, so it takes the missing-key
branch. Tolerating one would need a shape discriminator to tell a bare routine
from a malformed body, since neither has the key, and getting it wrong is the
same silent skip the next paragraph closes. Nothing on this contract sends a
bare resource: every routine response is enveloped by `RoutineResponse`,
`RoutineListResponse`, `TriggerResponse`, `TriggerListResponse`,
`RoutineRunResponse` or `RunListResponse` (`routines/dto.go`).
The two directions fail differently. A list unwrap that finds a missing key, a
`null` payload or a non-array payload yields the empty array, which every list
caller already renders (AC-003.5). A single-resource unwrap throws on those same
three cases and on an object carrying no non-empty `id`, because its callers
read fields off the result: `createRoutine`'s caller reads the new routine's
`id` to arm the trigger, and `{}` would otherwise pass the object check, produce
`id: ""` and arm `/routines//triggers` - the silent skip AC-003.15 exists to
prevent.
Return types change from the enveloped shape to the resource shape, so the
`as unknown as` casts at the call sites listed above disappear. This is a
compile-time change inside the web app; no other package imports these
functions.
## Control flow
Create routine: dialog state, then the write mapper, then `POST
/workspaces/:wsId/routines`, then the read normalizer on the 201 body, then the
routine id for the optional trigger step. Workspace comes from the path and
status is forced server-side, so neither is in the body.
Save routine: the write mapper over the patch fields only, then `PATCH
/routines/:id`, then the cron reconciliation below. The list toggle is the same
path with a one-key patch (AC-001.8), which AC-001.9's key set admits.
Trigger state after reconciliation comes from `listRoutineTriggers`, not from
splicing the local array (AC-002.11). That is what makes AC-002.8's "the order
the list endpoint returned" true after a replacement, and how AC-002.7 learns
whether a failed delete left the superseded trigger behind. It costs one extra
GET per reconciliation that changed something; an unchanged save issues none.
Trigger equality for AC-002.4 compares the expression exactly and the effective
timezone, where absent, `null` and `""` all read as `UTC`. The server normalizes
the same way on the way in, so a stored `UTC` and an unset draft are the same
schedule and must not churn the trigger.
Cron emptiness is decided on the trimmed expression, and the trimmed string is
what is sent (AC-002.14). Three live sites disagree today:
`create-routine-dialog.tsx`'s step gate trims, `routines-content.tsx`'s arm step
gates on raw truthiness, and `syncCronTrigger` trims the gate but transmits
`draft.cronExpression` untrimmed. That disagreement is invisible while the key
is dropped and observable once it transmits: `" "` becomes a silent no-op on
one path and a server 400 toast on another, and an untrimmed stored expression
compares unequal to the trimmed draft on every later save (AC-002.4). No stored
expression can carry stray whitespace from this UI today; one written by the API
or by config is replaced on the next save, which is correct rather than churn. One trim at the boundary settles all three sites.
Status seeding. `buildDraft` seeds the status control from `routine.status`,
where `?? "active"` catches neither `""` nor an unrepresentable stored value.
Either leaves the control unselected and contributes no `status` patch field
unless the operator picks one, which is AC-001.4's rule applied rather than a
new one (AC-003.17). A `""` routine still reads as firing everywhere firing
state is shown, because those read `isRoutineFiring`. The `<SelectValue />`
gains no placeholder text: neither value is reachable through this UI, and
inventing a placeholder would mean a new key in five locales for a state the
operator cannot create. Coercing the display to `active` instead would write
`active` back on the next save and commit a value no writer set, turning a
read-only visit into a mutation.
Cron reconciliation replaces its current delete-then-create order with
create-then-delete. The reason is a new failure mode this fix introduces: once
`cron_expression` actually transmits, the server validates it with
`shared.NextCronTime` and answers 400 on a bad expression. Under the old order
the superseded trigger is already gone by then, so a typo costs the operator a
working schedule. Under the new order a rejected create leaves the existing
trigger armed. The cost is a window in which both triggers exist, which a
delete failure leaves open and AC-002.7 requires be reported rather than
swallowed. That toast is the only signal, which is why it carries the count:
the page shows neither the duplicate nor a way out, because AC-002.8 displays
the first cron trigger by `created_at` - after a failed delete, the superseded
one - and `deleteRoutineTrigger`'s only call site is this reconciliation, which
swaps which trigger is orphaned rather than removing one. The routine fires
twice per tick until the extra is deleted through the API. Still the right
trade: a duplicate fire is recoverable, a lost schedule is not.
Reads: server component loader, client route loader and list fetch all call the
same API functions, so all three get model shape with no per-caller unwrap.
## Failure and recovery
- A non-2xx response rejects through the existing fetch helper. Callers keep
their `try`/`catch` and their toasts. The adapter swallows nothing.
- A malformed `task_template` or `variables` string yields an empty object.
A routine with corrupt template JSON renders with empty template fields
instead of failing the page.
- A trigger create rejected by `ErrInvalidTrigger` surfaces the server's
message, which names the bad expression. No local cron parser is added; the
server owns cron validity.
- `listRoutineTriggers` already has a per-routine `.catch` returning an empty
list. That stays: one routine's trigger fetch failing must not blank the list.
- The create-routine flow is two calls. A trigger failure after a successful
routine create leaves an unscheduled routine, reported rather than undone
(AC-002.10). The same split applies to the detail save (AC-002.9).
- The four partial-failure paths each have a named observable, because
"surface the error" is not one. A rejected replacement create (AC-002.6) and
a rejected create-flow trigger (AC-002.10) show the server's message, and
AC-002.10 also closes the dialog and refreshes the list rather than inviting a
second create. A failed delete (AC-002.7) and a failed trigger step after a committed routine
update (AC-002.9) both re-list first and report what that list shows. None of
the four shows a success toast.
- AC-002.7, AC-002.9 and AC-002.10 need copy that does not exist today: each
path is `toast.error(err.message)` now, and the server's message cannot say
which half of a two-call flow succeeded. That is new `office`-namespace copy,
so it carries the five-locale obligation (`pt-pt`, `zh-cn`, `zh-hk`, `zh-tw`
alongside English, `pnpm run i18n:zh-hant` for the Traditional pair) and the
new-code ratchet enforces it. AC-002.12 states it so the build does not meet
it as a surprise.
- AC-003.15's rejection throws from the adapter, a plain `.ts` file, where
`scripts/check-nonjsx-copy.mjs` scans internal error strings as copy. The
message is either translated or carries an `// i18n-exempt:` line comment; a
bare literal fails the ratchet rather than review.
- `catch_up_max` is normalized by the server at use, not by the client. The
control's `min={1}` is not what keeps a sub-1 value off the wire. The detail
view and the create dialog both carry this control, neither saves through a
form submit, and both spell the handler `Number(e.target.value) || 25`, which
catches only `0` and `NaN`. Each form supplies the coercion, using 25 below 1
(AC-003.13), and the write mapper omits a below-1 value (AC-001.11).
## Concurrency, retry and ordering
These are properties of the server contract the client cannot change, stated so
no implementer has to invent them; each names the residual it leaves rather
than a mitigation.
- **Retry:** the adapter adds no retry. Routine calls keep `fetchJson`, not
`fetchJsonWithRetry`.
- **Create is not idempotent:** the create endpoints carry no idempotency key,
so a retried create produces a second routine or a second trigger. The
adapter does not add one.
- **Last write wins, over the whole row:** routine update has no
optimistic-concurrency token, and the server's update is read-modify-write
rather than a column-scoped patch: `doUpdateRoutine` (`routines/handler.go`)
reads the routine, applies the patch in memory, and calls `UpdateRoutine`,
whose statement (`repository/sqlite/routines.go`) writes every routine column
from that struct. Two concurrent savers therefore overwrite each other's
fields even when their patches are disjoint, and what survives is whichever
database write lands second, not whichever response arrives second. AC-001.4
narrows the request body, not the write. Removing the residual needs the
optimistic concurrency the requirements exclude.
- **Concurrent trigger creates:** two savers replacing the same cron trigger
can leave two triggers. This is the same residual as AC-002.7 and is
surfaced, not prevented.
- **Server ordering:** routines are `ORDER BY name`, triggers `ORDER BY
created_at`, runs `ORDER BY created_at DESC`. None carries a tiebreak column,
so two rows with an equal sort key have an order this contract does not
define. The client preserves whatever order it receives (AC-003.8). For
triggers the consequence is stronger than display order: AC-002.8 replaces the
first cron trigger, so two stored in the same clock tick leave which one gets
replaced undefined. Closing that needs the tiebreak column the requirements
exclude; AC-002.11 confines it to a real endpoint response, not a local array.
## Persistence
None. This is a client-side serialization boundary: no schema, no migration, no
stored state change. The observable difference is that values the operator
already intended to store now arrive.
## Security
`secret` is redacted to `""` by `redactTriggerSecrets` before any list
response, and the model does not declare it. Explicit field mapping, rather
than an object spread, is what keeps that true if the redaction ever regresses.
No routine field is a credential; no new field is exposed.
## Observability
No new metrics or logs. The existing `routing_*` and routine counters are
backend-side and unaffected.
## Testing
Vitest at the adapter is where the contract is pinned, because that is the
boundary the defect lives at:
- serialized request body keys for routine create, routine update and trigger
create, asserting the exact key set and that no camelCase key is present
- update omits an unsupplied field and transmits an explicitly empty string
- `task_template` and `variables` serialize as strings, never objects
- read normalization for routine, trigger and run, including JSON-string
parsing, the malformed-JSON fallback, `null` handling, element order,
dropped non-object elements, and `secret` exclusion
- the two unwrap failure directions: a list envelope that is missing, `null` or
non-array yields `[]`; a single-resource envelope that is missing, `null`,
non-object, or an object with no non-empty `id` throws (AC-003.5, AC-003.15)
- an array-valued `variables` or `task_template` string yields `{}`, not an
index-keyed object (AC-003.4)
- run normalization carries `id`, `source` and `status` (AC-004.1), absent
optional run fields stay `undefined`, and an absent run `status` normalizes to
`""` without a cast (AC-004.5, AC-003.16)
- an update body built from a patch that clears `variables` or `description`
transmits the empty string, and one with an empty policy omits the key
(AC-001.10, AC-001.11)
- a cron expression is trimmed before it is sent (AC-002.14)
The REQ-002 orchestration behaviors are pinned by component tests over
`routine-detail-view` and the create dialog with the API module mocked, next to
the existing `create-routine-dialog.test.tsx`. Playwright cannot drive a failed
DELETE or a rejected create without a fault-injection surface the app does not
have, and these are the criteria a builder would otherwise have to invent a test
shape for:
- an unchanged save issues no trigger create and no trigger delete, including
when the stored timezone is `UTC` and the draft's is unset (AC-002.4)
- a changed expression creates before it deletes (AC-002.5)
- a rejected create issues no delete and leaves the stored expression displayed
(AC-002.6)
- a failed delete re-lists and reports the trigger count it found; a re-list
that also fails reports the state as unknown (AC-002.7)
- a routine update that succeeds followed by a failing trigger step reports both
halves and shows no success toast (AC-002.9)
- a create-flow trigger failure closes the dialog, refreshes the list, and
reports the routine as created without a schedule (AC-002.10)
- reconciliation renders the re-listed triggers, not a spliced array (AC-002.11)
- a whitespace-only expression arms nothing in the create flow and issues
neither create nor delete on the detail save (AC-002.14)
- a `""`-status routine leaves the status control unselected and its save patch
omits `status`, while the page still reads the routine as firing (AC-003.17)
`CoordinatorRoutineHint` is tested where it lives, next to the agent layout,
with the store seeded: the hint is hidden for a CEO with a firing assigned
routine, including one whose status is `""`, and shown when no assigned routine
is firing (AC-003.19). The seeding is required, not convenient: the agents route
never populates `s.office.routines` (Out of scope), so this cannot honestly be
an E2E check. It is the one behavior change outside the routines directory, so it is the one place a passing routines suite
would not have covered.
AC-003.10 is checked by a scan, not by reading. A vitest case reads
`apps/web/app/office/routines/**` plus
`apps/web/src/office-routine-client-routes.tsx` and asserts three things.
- **No snake_case wire key appears.** The key set is the left columns of the
three mapping tables above, restricted to keys containing an underscore. The
restriction is load-bearing rather than cosmetic: those columns also hold
`id`, `name`, `description`, `status`, `kind`, `timezone`, `enabled`,
`variables` and `source`, which are legitimate model-shape property names
appearing throughout these files, so a scan over the unrestricted key set must
fail correct code and could never pass. An underscore-bearing key has no
model-shape spelling, so a match is always a violation. Two exclusions are
required for the scan to be able to pass, and both are decidable line by line:
`*.test.ts`/`*.test.tsx` files, whose comments cite `catch_up_max` when they
name the catch-up criteria they cover, and lines whose first non-whitespace
characters are `//` or `*`, because `routine-row.tsx` explains `next_run_at`
in prose that survives this change. A comment cannot make a component read a
wire field, so excluding them narrows nothing the criterion claims. Run over
the tree today with those exclusions it reports exactly the three
`routine-row.tsx` fallback lines this capability deletes, which is what makes
it a passing assertion afterwards rather than a permanent red.
- **No `as unknown as` appears.** This is the half no key scan can reach:
`syncCronTrigger`'s cast contains no wire key. The bounded set holds nine
occurrences across six sites today: two fallback casts in `routine-row.tsx`
and four envelope unwraps, three of which spell the cast twice because they
carry a bare-resource fallback. All nine go, so the assertion is zero rather
than a count.
- **The consumer set of `s.office.routines` has not grown.** Scanned over
`apps/web/app/**`, which excludes `lib/state/slices/office/office-slice.ts`,
the slice that declares the array rather than consuming it. The set must be
exactly the three files that read it today:
`app/office/routines/routines-content.tsx`,
`app/office/agents/[id]/layout.tsx` and
`app/office/agents/[id]/runs/runs-list-view.tsx` (AC-003.18). Asserting
AC-003.10's whole set instead could never pass: most of those files take
routines as props. Those two are
excluded from the key scan deliberately, not by oversight: both also consume
`AgentRunSummary`, a snake_case wire shape owned by a different contract, so
`run.routine_id` and `run.task_id` are correct code there and no key scan can
tell them from a violation. Asserting the consumer set instead keeps the
exclusion honest and self-maintaining, because a third consumer fails this
case rather than escaping the bound in silence.
The file bound makes the negative decidable where a repo-wide claim would not
be, and the key set comes from the tables, so a key added to the contract later
is added to the scan by the same edit.
Playwright covers the round trip the wire bug currently makes impossible to
write honestly: seed a routine through the API, drive the real create and save
flows, and read the persisted value back. The user-visible surfaces are
`/office/routines` (list row, expanded detail, Runs tab), `/office/routines/:id`
(form seeding, save, schedule card) and the create dialog. Existing specs to
extend rather than duplicate: `routines-ui.spec.ts`,
`routine-catch-up-policy-ui.spec.ts` and its mobile sibling
`mobile-routine-catch-up-policy-ui.spec.ts`. No new component, layout or
interaction pattern is introduced, so the same adapter feeds both and the
mobile spec remains the check that it does.
## Out of scope
- **Changing the HTTP contract.** The backend keeps snake_case JSON tags. An
existing wire spelling is the public contract and stays: the same keys are
consumed by the agentctl CLI, the YAML config loader, config import/export
and config sync. Fixing the client is the safer change.
- **Populating `s.office.routines` anywhere but `/office/routines`.** Only that
route's two page files call `setRoutines`, so a direct visit to
`/office/agents/:id` renders `CoordinatorRoutineHint` against an empty array
and shows the hint whatever the assignee is. AC-003.19 is scoped to the
component for that reason. A fix needs a second store feeder, falsifying the
single-ingress property above, or a per-page fetch with its own loading and
error contract. Neither is a wire-contract change.
- **Adding a tiebreak column to any routine list query.** Changing it is a
backend ordering decision with its own compatibility surface.
- **Optimistic concurrency for routine update.** An `expected_*` guard is a
contract change to the update DTO.
- **Making the routine update and its trigger replacement atomic.** No endpoint
accepts both. AC-002.9 makes the split outcome explicit instead.
- **Rejecting an empty routine `name`.** `name` is single-word, so it already
transmits and already clears; this capability neither introduces nor worsens
it. Guarding it is a form-validation change with its own copy.
- **Switching a routine from cron to webhook in the detail view.** Selecting
`webhook` leaves the existing cron trigger armed, so the routine keeps firing.
This is pre-existing and not worsened by the wire fix. It needs a
trigger-kind transition contract of its own: what happens to the cron trigger,
whether a webhook trigger is minted, and what `public_id` and `signing_mode`
it gets.
- **Creating or configuring webhook triggers from the UI.** `public_id`,
`signing_mode` and `secret` have no controls. AC-002.1 makes the adapter carry
them so a future surface needs no boundary change; no surface is added here.
- **Clearing a routine's schedule from the detail view.** Emptying the cron
expression leaves the trigger armed (AC-002.13), so the routine keeps firing.
This is pre-existing. Removing a schedule needs its own contract: whether
empty means delete, whether an operator can disarm without deleting, and what
`enabled` is for. Guessing that empty means delete would let a cleared field
destroy a working schedule silently.
- **Clearing a routine's assignee from the detail view.** The assignee Select
has no unassigned option. AC-001.5 makes the boundary able to express the
clear; adding the control is a UI change this capability excludes.
- **Surfacing `skip_reason`, `pause_id` and `causation_id` on runs.** They are
on the wire and absent from the run model. Nothing renders them, so they stay
unmapped.
- **The divergence between the create dialog's `coalesce_if_active` default and
the server's `skip_if_active`.** Once the field transmits, the dialog's choice
is what persists. Which default is correct is a product decision, not a
serialization one.
## Related decisions
- [ADR-0036: Normalize ACP shell output at the adapter boundary](../../../decisions/0036-normalize-acp-shell-output-at-adapter-boundary.md)