Skip to content

Commit 9b58238

Browse files
authored
fix(api): release-audit follow-ups for the agent API work (#9910)
* fix(api): name the failing field once in v2 validation errors A message that already leads with its field label no longer repeats it after the location prefix, and the CLI restates the prefix as the flag the caller typed instead of rewriting it to query.--flag. * fix(api): call the v2 error id requestId The id in error bodies is the request id that x-request-id carries and logs store as requestId; traceId already means the OTel trace id in logs, so a search by the published value found nothing. * fix(api): describe what the workflow outline actually omits Only null values are dropped, every sub-block hidden from agents is dropped (some are real configuration), and blocks whose parent container is gone are left out, so point readers at Get workflow state for the full configuration. * fix(api): prove the workspace schedules list against Postgres Adds an integration suite for listWorkspaceLiveSchedulesPage: it returns the rows the per-workflow live list reports, leaves out archived, undeployed and other-workspace workflows, and pages through createdAt ties without repeats or gaps. sortBy=createdAt now says that each deploy creates new schedule rows. * chore(skills): include the optional requestId in the v2 error shape * fix(cli): pick the handoff for --expires-in and name a refused key sim login --expires-in without --method failed on servers that offer OAuth, because OAuth was chosen and then refused the flag; a lifetime now selects the API-key handoff. A refused handoff key no longer says nothing was stored: it already exists on the account, so the CLI points at how to revoke it. * fix(api): publish the workspace logoUrl pattern without a lookahead RE2-based validators (Go, Rust, many gateways) reject lookaheads, so the OpenAPI pattern for logoUrl could not be compiled there. The rewrite accepts and refuses exactly the same values. * chore(cli-auth): drop the poll-body half of a test that could not fail The poll contract strips unknown keys and the route never reads them, so sending access and expiresInDays in the body proved nothing. The test keeps checking that the approval's access and lifetime reach the mint. * fix(workflows): refuse withheld blocks before the operations lock applyWorkflowOperations now hands the persistence primitive a reader, which skipped its pre-lock withheld-block check, so a refused batch took the row lock and re-read the graph first. The use case checks the graph it composed before writing. A failed re-read under the lock is now an internal error instead of a 400 saying the workflow has no state. * chore(api): document the CONFLICT 409 from Apply workflow operations * improvement(workflows): prove the operations conflict guard against Postgres Holds the workflow row lock to force each interleaving: an unchanged workflow with containers and a migrated legacy block commits, a write that lands after the base read is refused as a conflict, and of two concurrent applies one commits and the other is refused with nothing lost. * chore(api): tighten comments and the field-label check from review * fix(cli): name a refused handoff key exactly The poll response now carries the minted key's name (an additive, optional field), so the CLI tells the caller exactly which key in Settings → API keys to revoke, falling back to the key id for an older server. Restores the route context argument the trimmed poll test dropped. * fix(workflows): run the conflict-guard races on their own connections The applies and the lock-wait poll started inside the lock holder's transaction callback, so the transaction tripwire refused them. They now leave that context, the applies run in a permission-group scope as routes do, and an apply that settles early is reported without awaiting the ones queued on the held lock. * chore(cli-auth): declare the poll key name the server always sends * fix(workflows): count lock waiters queued behind another waiter A second FOR UPDATE waiter queues on the first waiter's tuple lock, so pg_blocking_pids names that waiter rather than the holder; the barrier now walks the chain. * fix(cli): probe the endpoint before an --expires-in handoff --expires-in without --method chose the handoff before the reachability probe, so a mistyped endpoint printed a pairing code and polled instead of failing fast. The probe now runs first. A refused key from a server that does not report its name is described by the name pattern and time it was made.
1 parent b680ad4 commit 9b58238

35 files changed

Lines changed: 780 additions & 90 deletions

‎.agents/skills/v2-api-conventions/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ The v2 surface makes one promise: **every response is the same two shapes, and a
1111
```
1212
success (single) { "data": {...} }
1313
success (collection) { "data": [...], "nextCursor": "..." | null }
14-
failure (always) { "error": { "code": "...", "message": "...", "details"?: ... } }
14+
failure (always) { "error": { "code": "...", "message": "...", "details"?: ..., "requestId"?: "..." } }
1515
```
1616

1717
Nothing else at the top level. No `success: true`, no bare `{ "error": "string" }`, no HTML.
@@ -214,7 +214,7 @@ The consequence to keep true: **never put a resource id, filter, or scope into a
214214

215215
Run this against any new or changed v2 endpoint.
216216

217-
- [ ] Success body is exactly `{data}` or `{data, nextCursor}`; failures are exactly `{error:{code,message,details?}}`.
217+
- [ ] Success body is exactly `{data}` or `{data, nextCursor}`; failures are exactly `{error:{code,message,details?,requestId?}}`, where `v2Error` alone sets `requestId` (the `x-request-id` value).
218218
- [ ] Route uses a shared builder; no hand-built `NextResponse.json`.
219219
- [ ] Query and body schemas are `.strict()`.
220220
- [ ] The contract declares a `query` — `noInputSchema` when the endpoint takes no query params, never omission.

‎apps/docs/content/docs/api-reference/getting-started.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -175,12 +175,12 @@ Rejected v2 requests use HTTP error status codes and a stable code/message envel
175175
"error": {
176176
"code": "NOT_FOUND",
177177
"message": "Workflow not found",
178-
"traceId": "3f9a1c7e"
178+
"requestId": "3f9a1c7e"
179179
}
180180
}
181181
```
182182

183-
Every response carries an `x-request-id` header, and an error repeats it as `error.traceId`. Include it when you contact support about a failed request.
183+
Every response carries an `x-request-id` header, and an error repeats the same id as `error.requestId`. Quote it when you contact support about a failed request.
184184

185185
| Status | Meaning | Action |
186186
| --- | --- | --- |

‎apps/docs/content/docs/cli/commands.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ sim login [options]
8383
| `--method <method>` | No | Credential to obtain: oauth requires OAuth support; api-key creates an API key through pairing (auto-selects when omitted). Accepted values: `oauth`, `api-key`. |
8484
| `--no-browser` | No | Print the approval URL without opening it (either login method). |
8585
| `--read-only` | No | Ask only for permission to read, never to change anything. |
86-
| `--expires-in <days>` | No | API-key login only: days until the key expires (1-365); omit for a key that never expires. |
86+
| `--expires-in <days>` | No | Log in with an API key that expires after this many days (1-365); without it an API key never expires. |
8787
| `--callback-port <port>` | No | Pin the local port the browser returns to. |
8888
| `-y, --yes` | No | Overwrite an existing API-key profile without prompting. |
8989

‎apps/docs/content/docs/cli/reference.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ sim login [options]
5050
| `--method <method>` | No | Credential to obtain: oauth requires OAuth support; api-key creates an API key through pairing (auto-selects when omitted). Accepted values: `oauth`, `api-key`. |
5151
| `--no-browser` | No | Print the approval URL without opening it (either login method). |
5252
| `--read-only` | No | Ask only for permission to read, never to change anything. |
53-
| `--expires-in <days>` | No | API-key login only: days until the key expires (1-365); omit for a key that never expires. |
53+
| `--expires-in <days>` | No | Log in with an API key that expires after this many days (1-365); without it an API key never expires. |
5454
| `--callback-port <port>` | No | Pin the local port the browser returns to. |
5555
| `-y, --yes` | No | Overwrite an existing API-key profile without prompting. |
5656

@@ -5126,7 +5126,7 @@ sim schedules list [options]
51265126
| --- | --- | --- |
51275127
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
51285128
| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
5129-
| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `createdAt`. |
5129+
| `--sort-by <value>` | No | Field used to sort the result. `createdAt` is when the schedule was created for the deployment version that runs it: each deploy creates new schedule rows, so a redeployed workflow's schedules move to the newest end. Defaults to "createdAt". Accepted values: `createdAt`. |
51305130
| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
51315131

51325132
</CommandTable>

‎apps/docs/content/docs/cli/schedules.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ sim schedules list [options]
2727
| --- | --- | --- |
2828
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
2929
| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
30-
| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `createdAt`. |
30+
| `--sort-by <value>` | No | Field used to sort the result. `createdAt` is when the schedule was created for the deployment version that runs it: each deploy creates new schedule rows, so a redeployed workflow's schedules move to the newest end. Defaults to "createdAt". Accepted values: `createdAt`. |
3131
| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
3232

3333
</CommandTable>

‎apps/docs/openapi-v2-billing.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -597,8 +597,8 @@
597597
}
598598
]
599599
},
600-
"traceId": {
601-
"description": "Identifier of this request, the same value as the `x-request-id` response header. Include it when contacting support.",
600+
"requestId": {
601+
"description": "Identifier of this request, the same id as the `x-request-id` response header. Quote it when contacting support.",
602602
"type": "string"
603603
}
604604
},

‎apps/docs/openapi-v2-files-audit.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4744,8 +4744,8 @@
47444744
}
47454745
]
47464746
},
4747-
"traceId": {
4748-
"description": "Identifier of this request, the same value as the `x-request-id` response header. Include it when contacting support.",
4747+
"requestId": {
4748+
"description": "Identifier of this request, the same id as the `x-request-id` response header. Quote it when contacting support.",
47494749
"type": "string"
47504750
}
47514751
},

‎apps/docs/openapi-v2-knowledge.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6049,8 +6049,8 @@
60496049
}
60506050
]
60516051
},
6052-
"traceId": {
6053-
"description": "Identifier of this request, the same value as the `x-request-id` response header. Include it when contacting support.",
6052+
"requestId": {
6053+
"description": "Identifier of this request, the same id as the `x-request-id` response header. Quote it when contacting support.",
60546054
"type": "string"
60556055
}
60566056
},

‎apps/docs/openapi-v2-logs.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1096,8 +1096,8 @@
10961096
}
10971097
]
10981098
},
1099-
"traceId": {
1100-
"description": "Identifier of this request, the same value as the `x-request-id` response header. Include it when contacting support.",
1099+
"requestId": {
1100+
"description": "Identifier of this request, the same id as the `x-request-id` response header. Quote it when contacting support.",
11011101
"type": "string"
11021102
}
11031103
},

‎apps/docs/openapi-v2-resources.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15082,8 +15082,8 @@
1508215082
}
1508315083
]
1508415084
},
15085-
"traceId": {
15086-
"description": "Identifier of this request, the same value as the `x-request-id` response header. Include it when contacting support.",
15085+
"requestId": {
15086+
"description": "Identifier of this request, the same id as the `x-request-id` response header. Quote it when contacting support.",
1508715087
"type": "string"
1508815088
}
1508915089
},
@@ -15266,7 +15266,7 @@
1526615266
"anyOf": [
1526715267
{
1526815268
"type": "string",
15269-
"pattern": "^(\\/(?!\\/)|https:\\/\\/)"
15269+
"pattern": "^(\\/$|\\/[^/]|https:\\/\\/)"
1527015270
},
1527115271
{
1527215272
"type": "null"

0 commit comments

Comments
 (0)