Repository navigation
2026 11 05 api sync - #19
Conversation
…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
…kills/seclai-sdk-review-triage'
…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
left a comment
There was a problem hiding this comment.
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.
|
On the two findings in the review body, both addressed in the working tree (not pushed yet):
|
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
left a comment
There was a problem hiding this comment.
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 nodone, the code returnslastSeenif its status is notpending. It does not checkreported. That return also fires for a bareinitsnapshot whose status isrunning, which has no answer inoutput. The new README and JSDoc say this case throwsSeclaiStreamingError(see the inline comment on README.md:364). Returnreportedwhen it is set; otherwise throw, or make the docs match the code.
|
On the review-body finding: fixed in the working tree, not pushed yet.
The Python, Go and C# SDKs follow the same rule. |
|
Correction to the PR comment above. Returning a snapshot when the stream ends without |
burgaard
left a comment
There was a problem hiding this comment.
Code review (high effort) of HEAD~1..HEAD. Findings on lines outside the PR diff:
- src/client.ts:1320:
throwOnIncompleteis ignored when the server answers with plain JSON.runStreamingAgentAndWaitreturnsresponse.json()unconditionally, so a JSON body holding apending/runningrun is returned as if finished, even though the docs saythrowOnIncompletethrowsSeclaiStreamingErrorwhenever the run has not finished beforedone.returnOnResultcallers also can't tell this apart. Checkstatushere whenthrowOnIncompleteis set, as the SSE path does. - src/client.ts:471 (
anySignal, whichrunStreamingAgentAndWaituses): an abort listener is added to the caller'ssignaland is never removed. A caller that reuses one long-livedAbortSignalacross manyrunStreamingAgentAndWaitcalls collects one listener per call, and each keeps its combinedAbortControlleralive. This bug was already there, but this PR adds more abort handling in the same function. Remove the listeners in thefinally.
|
On the two review-body findings:
|
burgaard
left a comment
There was a problem hiding this comment.
Code review of HEAD~1..HEAD (high effort). 6 findings, posted inline.
burgaard
left a comment
There was a problem hiding this comment.
Code review of HEAD~1..HEAD (high effort). Findings on lines outside the PR diff:
-
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, callsgetAgentRun(), and returns the run if it is terminal, or throwsPolling aborted.one round trip later. This contradicts the "no fetch after an abort" rule this commit applies to the prefetch. Checksignal.abortedafter the sleep, or make the sleep abortable. -
src/client.ts:1595 — an already-aborted signal still starts a run.
runAgentAndPoll(..., { signal })withsignal.aborted === truePOSTs/agents/{id}/runs(a real, billable run) and only checks the signal afterwards. Check the signal beforerunAgent(). -
src/client.ts:1595/1608/1626 —
signalis not passed torunAgent()orgetAgentRun(), and the sleep ignores it. An abort cannot cancel an in-flight request and waits up topollIntervalMs(2 s by default) to take effect. That is why the code needs special abort checks in two places. Passingsignalinto the requests and the sleep (the streaming helpers already do this withanySignal) fixes the root cause in one place and makes findings 1 and 2 fall out. -
src/client.ts:1571 — the JSDoc does not describe the abort behavior.
@throwslists onlySeclaiStreamingError. It does not mentionSeclaiError("Polling aborted."), or that after an abort a finished start response is returned without step outputs even whenincludeStepOutputsis set. -
src/client.ts:1617-1622 — the timeout can overshoot by up to
pollIntervalMsplus one request. The timeout is checked only before the sleep. WithtimeoutMs: 3000, pollIntervalMs: 2000, the call can run for about 4 s or more before it throws. This was already the case before this commit.
|
On the five review-body findings: Finding 4 is fixed in the working tree, not pushed yet. The Findings 1, 2, 3 and 5 move to #20, not this PR:
All four were already in 1.8.0, and they share one fix: passing |
burgaard
left a comment
There was a problem hiding this comment.
Code review (high effort) of HEAD~1..HEAD. Findings on lines outside the diff:
- src/client.ts:1601 — A pre-aborted
signalstill starts a run.runAgent()is called beforesignalis checked and isn't given the signal, sorunAgentAndPoll(id, body, { signal: alreadyAborted })creates a real, billable agent run and then throws"Polling aborted."(or returns it if it finished at once). Checkopts?.signal?.abortedbeforerunAgent, or pass the signal into the request. - src/client.ts:1630 — The sleep and the in-flight
getAgentRunignoresignal, so an abort takes up topollIntervalMsplus one request round-trip to land (2 s+ by default, more with a long interval). Make the sleep abortable (clear the timer and reject onabort) and pass the signal togetAgentRun. - src/client.ts:1625 —
timeoutMsis checked only before the sleep, so the call can run past it bypollIntervalMs+ one request (e.g.timeoutMs: 1000, pollIntervalMs: 60000waits about 60 s). Clamp the sleep to the time left. - src/client.ts:1611–1619 — The terminal-status check (
completed/failed/cancelledorreturnOnResult && result_reported_at) appears twice, once before the loop and once inside it. A smallisDone(run)helper would keep the two copies from drifting apart.
|
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:
The fix for the first three is the same: pass |
…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
left a comment
There was a problem hiding this comment.
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.
burgaard
left a comment
There was a problem hiding this comment.
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()callsrunAgent()even whensignalis already aborted. Called with an already-abortedAbortController().signal, it still POSTs/runsand starts a billable run. If that run is not finished, the call then throwsPolling 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 checkif (opts?.signal?.aborted) throw new SeclaiError("Polling aborted.")beforerunAgent()would prevent this. Per the rules for spec-sync PRs, file it as an issue.
|
On the review-body finding: a pre-aborted |
burgaard
left a comment
There was a problem hiding this comment.
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.
burgaard
left a comment
There was a problem hiding this comment.
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:33still 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.
…2e36 acc2e36 Updated skill git-subtree-dir: .claude/skills/seclai-changelog git-subtree-split: acc2e3659aa88562c9dcf8b8cc2e45e113bfcfed
No description provided.