Skip to content

2026 11 05 api sync - #19

Merged
burgaard merged 28 commits into
mainfrom
2026-11-05-api-sync
Nov 6, 2026
Merged

burgaard merged 28 commits into
mainfrom
2026-11-05-api-sync

Conversation

@burgaard

@burgaard burgaard commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

No description provided.

Kim Burgaard added 9 commits November 5, 2026 12:13
…88e7

65188e7 Addressed review findings
0f1b9d6 Updated skills and guards
aea19cd Updated skills
3558844 Add the surface check; report API version changes; record the changelog rule
9ac3bdb Add provenance banner to the vendored skills
4abc72a Tweak Go handling
22d0637 Updated version link instructions for Go
ae892f0 Updated skill to clarify type handling
fad3662 Added shared skill to update SDK change logs
REVERT: f6aa6eb Updated skills and guards
REVERT: 5b4e063 Updated skills
REVERT: 14a086e Addressed review comments
REVERT: 4a9410f Addressed review comments
REVERT: 683ba85 Addressed review comments
REVERT: f16043e Addressed review comments
REVERT: 9f5a04b More audit tool fixes
REVERT: 20f845d Addressed review comments
REVERT: 77cecda Updated the audit-tool
REVERT: b62c912 Updated tools
REVERT: 177d423 Internal review fixes
REVERT: a2aa7ef Add the surface check; report API version changes; record the changelog rule
REVERT: e89d300 Note that a typed façade is invisible to the returns check
REVERT: 4f4113d Note that dated versioning gives one operation two legal response shapes
REVERT: 5ab0384 Add returns and models audits; fix spec-diff and extractor defects
REVERT: 07d1323 Fixed gaps
REVERT: b6e5468 Addressed review comments
REVERT: 6189884 Tweaks
REVERT: ea07ba9 Add provenance banner to the vendored skills
REVERT: 58ff6ce Do not check in python cache files
REVERT: 9b18406 Added scripts and skill to help update SDKs

git-subtree-dir: .claude/skills/seclai-changelog
git-subtree-split: 65188e7f93892656b46f6cfadd24d0ab999d8b7a
c04694e Addressed review findings
99b3f5a Addressed review comments and added skills
c71fbe5 Addressed review findings
79a0130 Addressed review findings
35319db Addressed review findings
6b7ba9e Addressed review findings
1cb3d57 Addressed review findings

git-subtree-dir: .claude/skills/seclai-sdk-sync
git-subtree-split: c04694ef8ba895d064dc194790d5363a15f1b09e
…it e45417d

git-subtree-dir: .claude/skills/seclai-sdk-review-triage
git-subtree-split: e45417d9df908012689529c5cc06f670ac8ee22a
7b225d4 Addressed review comments
44177a2 Addressed review comments
7d62432 Addressed review comments
c4072df Addressed review comments
a05fa4d Sync tool fixes

git-subtree-dir: .claude/skills/seclai-sdk-sync
git-subtree-split: 7b225d4c0c87d6089fd50eb94ae14d49452dd3f1

@burgaard burgaard left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Automated review (high effort). Findings on lines outside this PR's diff:

1. src/client.ts:1285: runStreamingAgentAndWait() ignores the new result SSE event. The synced spec adds event: result, which carries the run's answer once result_reported_at is set. For an on_result agent it can arrive while later steps still run. The parser only keeps init and done. If a slow step after the result step (a human_in_the_loop or wait step, say) pushes done past timeoutMs (default 60s), the helper throws SeclaiStreamingError and drops the answer it already received. A stream that ends after result but before done falls back to the init snapshot (pending) and throws too. Track the result payload as lastSeen, and return it on timeout or early end (or add an option to return on result). The runStreamingAgent() JSDoc example (around line 1335) also still tells callers to read the answer from done, while the spec now says to take it from result.

2. src/types.ts:530: the retired retry fields are not marked deprecated, while input is. CreateEvaluationResultRequest still offers retry_triggered and retry_count as plain optional fields. With SeclaiApiVersion.Latest (now 2026-11-04), retry_triggered: true returns a 400. max_retries and retry_on_failure on UpdateAgentRequest are now documented as "Deprecated: has no effect". This PR adds a @deprecated override for SetSlackTriggerConfigRequest.input, but these fields get no compile-time hint, so a caller who moves to Latest gets a runtime 400 with no warning in the editor. Apply the same @deprecated treatment to them.

Comment thread README.md Resolved
Comment thread README.md Resolved
Comment thread CHANGELOG.md Resolved
Comment thread src/types.ts Resolved
Comment thread tests/client.test.ts Resolved
@burgaard

burgaard commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

On the two findings in the review body, both addressed in the working tree (not pushed yet):

  1. result event. runStreamingAgentAndWait() now tracks the result SSE event. If the stream ends, or timeoutMs elapses, after result but before done, it returns the result snapshot (whose output is the answer) instead of throwing. done still wins. The runStreamingAgent() example now reads the answer from result. The tests fail without the fix.
  2. Retired fields. max_retries/retry_on_failure on UpdateAgentRequest and retry_count/retry_triggered on CreateEvaluationResultRequest are now @deprecated, with the spec's wording: no effect, and retry_triggered: true returns 400 from 2026-11-04. The generated type still declares these fields, so the intersection pattern used for input didn't make the editor flag them. Each is now Omit-ted from the generated type and added back with @deprecated. Setting them still compiles, and surface 1.8.0 reports no breaking change.

Kim Burgaard added 3 commits November 5, 2026 16:36
37a397d Addressed review comments
a08b53f Addressed review comments
2ee73d8 Addressed review comments
39b0862 Fixed C# sync findings

git-subtree-dir: .claude/skills/seclai-sdk-sync
git-subtree-split: 37a397db1b640e7674aff2359cb1c04a0c898fda

@burgaard burgaard left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Automated review of HEAD~3..HEAD (high effort). Findings are inline, except this one, whose line is outside the PR diff:

  • src/client.ts:1309-1311 (runStreamingAgentAndWait, end-of-stream path): when the stream closes with no done, the code returns lastSeen if its status is not pending. It does not check reported. That return also fires for a bare init snapshot whose status is running, which has no answer in output. The new README and JSDoc say this case throws SeclaiStreamingError (see the inline comment on README.md:364). Return reported when it is set; otherwise throw, or make the docs match the code.

Comment thread README.md Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/types.ts Resolved
Comment thread tests/client.test.ts Resolved
@burgaard

burgaard commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

On the review-body finding: fixed in the working tree, not pushed yet.

  • runStreamingAgentAndWait() no longer returns lastSeen when the stream closes. Without a done event it always throws SeclaiStreamingError, with the latest snapshot (result, else init) in the new err.run. A bare init followed by end of stream now throws, and the message says no result had been reported.
  • Returning early on result is opt-in through returnOnResult.

The Python, Go and C# SDKs follow the same rule.

@burgaard

burgaard commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Correction to the PR comment above. Returning a snapshot when the stream ends without done was released behaviour, so it stays the default for now, and the README and JSDoc say so plainly: the default may return a run that hasn't finished, so check status and result_reported_at. The new opt-in throwOnIncomplete: true throws SeclaiStreamingError whenever the stream ends or breaks before done, with the latest snapshot in err.run. It becomes the default in the next major version. In the working tree, not pushed yet.

@burgaard burgaard left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Code review (high effort) of HEAD~1..HEAD. Findings on lines outside the PR diff:

  • src/client.ts:1320: throwOnIncomplete is ignored when the server answers with plain JSON. runStreamingAgentAndWait returns response.json() unconditionally, so a JSON body holding a pending/running run is returned as if finished, even though the docs say throwOnIncomplete throws SeclaiStreamingError whenever the run has not finished before done. returnOnResult callers also can't tell this apart. Check status here when throwOnIncomplete is set, as the SSE path does.
  • src/client.ts:471 (anySignal, which runStreamingAgentAndWait uses): an abort listener is added to the caller's signal and is never removed. A caller that reuses one long-lived AbortSignal across many runStreamingAgentAndWait calls collects one listener per call, and each keeps its combined AbortController alive. This bug was already there, but this PR adds more abort handling in the same function. Remove the listeners in the finally.

Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
@burgaard

burgaard commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

On the two review-body findings:

  1. throwOnIncomplete on a plain-JSON reply: fixed in the working tree, not pushed yet. With throwOnIncomplete, a JSON reply whose run hasn't finished now throws SeclaiStreamingError with the run in run, unless returnOnResult is set and result_reported_at is. Without the options the reply is returned as before. A test covers all three cases.
  2. The anySignal listener leak: already in 1.8.0, and this PR doesn't change it. It moves to the follow-up PR that rebuilds the wait helpers on one stream parser, which will remove the listeners.

@burgaard burgaard left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Code review of HEAD~1..HEAD (high effort). 6 findings, posted inline.

Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread tests/client.test.ts Resolved

@burgaard burgaard left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Code review of HEAD~1..HEAD (high effort). Findings on lines outside the PR diff:

  1. src/client.ts:1624-1626 — an abort during the poll sleep still sends a GET. The abort check runs before setTimeout, never after it. Abort 100 ms into a 2 s sleep: the loop wakes, calls getAgentRun(), and returns the run if it is terminal, or throws Polling aborted. one round trip later. This contradicts the "no fetch after an abort" rule this commit applies to the prefetch. Check signal.aborted after the sleep, or make the sleep abortable.

  2. src/client.ts:1595 — an already-aborted signal still starts a run. runAgentAndPoll(..., { signal }) with signal.aborted === true POSTs /agents/{id}/runs (a real, billable run) and only checks the signal afterwards. Check the signal before runAgent().

  3. src/client.ts:1595/1608/1626 — signal is not passed to runAgent() or getAgentRun(), and the sleep ignores it. An abort cannot cancel an in-flight request and waits up to pollIntervalMs (2 s by default) to take effect. That is why the code needs special abort checks in two places. Passing signal into the requests and the sleep (the streaming helpers already do this with anySignal) fixes the root cause in one place and makes findings 1 and 2 fall out.

  4. src/client.ts:1571 — the JSDoc does not describe the abort behavior. @throws lists only SeclaiStreamingError. It does not mention SeclaiError("Polling aborted."), or that after an abort a finished start response is returned without step outputs even when includeStepOutputs is set.

  5. src/client.ts:1617-1622 — the timeout can overshoot by up to pollIntervalMs plus one request. The timeout is checked only before the sleep. With timeoutMs: 3000, pollIntervalMs: 2000, the call can run for about 4 s or more before it throws. This was already the case before this commit.

Comment thread src/client.ts Resolved
Comment thread tests/client.test.ts Resolved
@burgaard

burgaard commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

On the five review-body findings:

Finding 4 is fixed in the working tree, not pushed yet. The runAgentAndPoll JSDoc now lists SeclaiError("Polling aborted.") under @throws. It also says that after an abort, a start run that has already finished is returned without step outputs, even when includeStepOutputs is set.

Findings 1, 2, 3 and 5 move to #20, not this PR:

  • an abort during the sleep still sends one more GET;
  • an already-aborted signal still starts a run;
  • signal isn't passed to the requests or the sleep;
  • the timeout can overshoot by up to one poll interval.

All four were already in 1.8.0, and they share one fix: passing signal through the start request, the polls and the sleep. That's part of the rework in #20.

@burgaard burgaard left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Code review (high effort) of HEAD~1..HEAD. Findings on lines outside the diff:

  • src/client.ts:1601 — A pre-aborted signal still starts a run. runAgent() is called before signal is checked and isn't given the signal, so runAgentAndPoll(id, body, { signal: alreadyAborted }) creates a real, billable agent run and then throws "Polling aborted." (or returns it if it finished at once). Check opts?.signal?.aborted before runAgent, or pass the signal into the request.
  • src/client.ts:1630 — The sleep and the in-flight getAgentRun ignore signal, so an abort takes up to pollIntervalMs plus one request round-trip to land (2 s+ by default, more with a long interval). Make the sleep abortable (clear the timer and reject on abort) and pass the signal to getAgentRun.
  • src/client.ts:1625 — timeoutMs is checked only before the sleep, so the call can run past it by pollIntervalMs + one request (e.g. timeoutMs: 1000, pollIntervalMs: 60000 waits about 60 s). Clamp the sleep to the time left.
  • src/client.ts:1611–1619 — The terminal-status check (completed/failed/cancelled or returnOnResult && result_reported_at) appears twice, once before the loop and once inside it. A small isDone(run) helper would keep the two copies from drifting apart.

Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
@burgaard

burgaard commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

On the four review-body findings: no change in this PR. All four were in 1.8.0, and they're tracked in #20, where poll/stream-helper findings now go:

  • an already-aborted signal still starts a run;
  • an abort is noticed only at the next poll check;
  • timeoutMs can overshoot by up to one poll interval;
  • the done check is written out twice.

The fix for the first three is the same: pass signal through the start request, the polls and an abortable sleep, and cap the sleep at the time left. That rework also folds the duplicated check into one. This round only corrected the JSDoc so it describes the abort behaviour exactly; that's in the working tree, not pushed yet.

Kim Burgaard added 5 commits November 5, 2026 21:35
…3cbd

9c53cbd Fix where semver messages go

git-subtree-dir: .claude/skills/seclai-changelog
git-subtree-split: 9c53cbd8681392f472f09d710bcfd37af094b10c
…17d..7a14236

7a14236 Updated rules and skills to reduce review churn
70dfef1 Updated rules and skills to reduce review churn

git-subtree-dir: .claude/skills/seclai-sdk-review-triage
git-subtree-split: 7a14236fd95b8e296bdf10b8263bf7c663066358

@burgaard burgaard left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Review of HEAD~6..HEAD (high effort). Abort semantics, the duplicated terminal predicate, and the stream/poll helper rework already have recorded decisions (tracked in #20), so they are not reopened here. Findings below are labelled by evidence class.

Comment thread README.md Resolved
Comment thread src/client.ts Resolved
Comment thread CHANGELOG.md Resolved
Comment thread tests/client.test.ts Resolved

@burgaard burgaard left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Code review of HEAD~1..HEAD (41dfe4a, "Addressed review comments").

One finding is on a line outside the PR diff, so it is here:

  • src/client.ts:1605, already in 1.8.0 (Proven): runAgentAndPoll() calls runAgent() even when signal is already aborted. Called with an already-aborted AbortController().signal, it still POSTs /runs and starts a billable run. If that run is not finished, the call then throws Polling aborted. and leaves the run orphaned. This commit makes a finished run come back after an abort, but the start request is still sent. A check if (opts?.signal?.aborted) throw new SeclaiError("Polling aborted.") before runAgent() would prevent this. Per the rules for spec-sync PRs, file it as an issue.

Comment thread src/client.ts Resolved
Comment thread README.md Resolved
Comment thread CHANGELOG.md Resolved
Comment thread src/client.ts Resolved
@burgaard

burgaard commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

On the review-body finding: a pre-aborted signal still starting a run was already 1.8.0's behaviour, and it's recorded in #20. The fix there passes signal through the start request, the polls and the sleep. No change in this PR.

@burgaard burgaard left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Code review of HEAD~1..HEAD (028eab3, "Addressed review comments"). Five findings, posted inline. The changed code at this commit only edits docs and adds a test; the findings are about claims this commit made and places it did not update.

Comment thread src/errors.ts Resolved
Comment thread tests/client.test.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved
Comment thread src/client.ts Resolved

@burgaard burgaard left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Code review of HEAD~1..HEAD (two doc-comment edits). No finding changes runtime behaviour; findings are contract/doc accuracy.

Not in the PR diff:

  • Consequence (sibling SDK): seclai-csharp/src/Seclai/Exceptions/StreamingException.cs:33 still says "for a polled run, the last poll" — the wording this commit corrects in JS. When the timeout elapses before any poll, the C#/JS helpers hold the start (RunAgent) response, not a poll. Worth the same edit there if the C# helper behaves the same.

Comment thread src/errors.ts Resolved
Comment thread src/errors.ts Resolved
Comment thread src/client.ts Resolved
Kim Burgaard added 3 commits November 5, 2026 23:56
…2e36

acc2e36 Updated skill

git-subtree-dir: .claude/skills/seclai-changelog
git-subtree-split: acc2e3659aa88562c9dcf8b8cc2e45e113bfcfed
@burgaard
burgaard merged commit 335767f into main Nov 6, 2026
1 check passed
@burgaard
burgaard deleted the 2026-11-05-api-sync branch November 6, 2026 08:58
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