Skip to content

2026 11 05 api sync - #19

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

burgaard merged 21 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.

Code review (high effort). Inline comments below cover the lines that are in the diff. These findings are on unchanged lines outside the diff:

1. seclai/seclai.py:1281 (and async :6241): run_streaming_agent_and_wait() drops the new SSE result event. dispatch() returns early for any event other than init/done, so a result event never updates last_seen. The spec now sends event: result (an AgentRunResponse whose output is the final answer) before done, and for report_success: on_result agents it can arrive while later steps are still running. If the stream closes after result and before done (a proxy idle timeout, or a long tail of post-result steps), the fallback return last_seen hands back the init snapshot with no output, even though the answer already arrived. Fix: include result in the parsed set so it updates last_seen, or return on it.

2. seclai/seclai.py:5829 (and async counterpart): the run_streaming_agent() docstring lists only "init" and "done". It should mention the new "result" event, because callers that only need the answer can stop reading there.

3. seclai/seclai.py:5811 (and async :10837): run_agent_and_poll() ignores result_reported_at. The spec now says to poll GET /agents/runs/{run_id} until result_reported_at is set. For an on_result agent, the helper keeps polling until every later step finishes, which can take much longer than needed. Consider an option to return once result_reported_at is set, or at least document the difference.

Comment thread seclai/seclai.py Resolved
Comment thread seclai/seclai.py Resolved
Comment thread CHANGELOG.md Resolved
Comment thread README.md Resolved
@burgaard

burgaard commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

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

  1. result event. run_streaming_agent_and_wait() (sync and async) now keeps the result event as the latest snapshot. If the stream ends or times out after result but before done, it returns that snapshot (whose output is the answer), not the init snapshot or a timeout error. done still wins.
  2. run_streaming_agent() docstrings now list init, result and done. They say callers who only need the answer can stop at result, and that done still reports whether the whole run succeeded.
  3. run_agent_and_poll() gains a keyword-only return_on_result=False. When it's true, the helper returns as soon as a polled run has result_reported_at set. A terminal status still returns immediately.

Each change has sync and async tests that fail without it. The same changes are being made in the JS, Go and C# SDKs, under the same option name in each language's style.

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 /code-review (high) of HEAD~3..HEAD. Found 6 issues, posted inline below. The two streaming fixes also apply to the matching lines in AsyncSeclai.

Comment thread seclai/seclai.py Resolved
Comment thread seclai/seclai.py Resolved
Comment thread seclai/seclai.py Resolved
Comment thread scripts/specfix.py Resolved
Comment thread seclai/seclai.py Resolved
Comment thread seclai/seclai.py Resolved
@burgaard

burgaard commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

On the review-body note: every streaming change this round is in both Seclai and AsyncSeclai, each with an async test next to the sync one. That covers the TransportError handling, the deadline check after the line, the removed partial-run fallbacks, return_on_result on run_streaming_agent_and_wait, and SeclaiStreamingError.run.

Also, with include_step_outputs=True, run_agent_and_poll now fetches the run once with step outputs before checking it, because the run_agent response carries none. A run that was already finished at start used to come back without them.

All in the working tree, not pushed yet.

@burgaard

burgaard commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Correction to the PR comment above. To avoid a breaking change in this minor release, the stricter streaming behaviour is opt-in via raise_on_incomplete=True on run_streaming_agent_and_wait, and it becomes the default in the next major version. By default the helper behaves as 1.9.0 did. It now returns the result snapshot when the stream ends after one, and uses a late done. Every change is in both Seclai and AsyncSeclai, with tests for both modes. 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.

One finding is on a line outside the diff:

  • seclai/seclai.py:6006 (and the async twin at ~11155): run_streaming_agent() still raises a plain SeclaiError on timeout, with no run. The CHANGELOG now says the timeout error "is now this SeclaiError subclass", but that is only true of run_streaming_agent_and_wait(). A caller who catches SeclaiStreamingError for timeouts on both streaming methods misses the generator's timeouts.

Comment thread seclai/seclai.py Resolved
Comment thread seclai/seclai.py Resolved
Comment thread seclai/seclai.py Resolved
Comment thread seclai/seclai.py Resolved
Comment thread seclai/seclai.py Resolved
@burgaard

burgaard commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

On the review-body finding: thanks, the CHANGELOG overstated it. Only run_streaming_agent_and_wait() now raises SeclaiStreamingError on its timeout; run_streaming_agent() still raises plain SeclaiError. The entry now says so.

Also this round, specfix checks every retained entry before applying any, so a stale entry leaves the spec unchanged. 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 of HEAD~1..HEAD (high effort). Two findings are on lines outside the diff, so they're listed here:

  • seclai/seclai.py:1326 / :6410: run_streaming_agent_and_wait() drops error events. dispatch() returns None for any event other than init/result/done, so a server-side event: error (which run_streaming_agent() turns into SeclaiStreamingError(message, run_id=...)) is ignored. The caller gets a generic "The stream ended before the 'done' event" error or a timeout without the server's message, or, without raise_on_incomplete, the stale init snapshot returned as if it were the run. This predates the PR, but it's in the function the PR touches.
  • seclai/seclai.py:1368 / :6452: the deadline is checked only when a line arrives. Because of that, a stalled stream is bounded only by httpx's per-read timeout (timeout=timeout_seconds), so timeout can run to about 2× before it fires. A stream that keeps sending data more often than the read timeout but slower than the deadline is checked on each line, but nothing preempts a blocked read. A wall-clock deadline (for example a remaining-time read timeout, or a cancel scope in the async client) would fix this at the root, without a per-line check.

Comment thread seclai/seclai.py Resolved
Comment thread seclai/seclai.py Resolved
Comment thread seclai/seclai.py Resolved
Comment thread scripts/specfix.py Resolved
Comment thread scripts/specfix.py Resolved
Comment thread tests/test_streaming_agent_runs.py Resolved
@burgaard

burgaard commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

On the two review-body findings:

  1. event: error ignored by the wait helper: this predates the PR and is the first item in Wait helpers ignore event: error and duplicate the stream parser #20, which rebuilds the wait helpers on one stream parser.
  2. A blocked read is bounded only by httpx's read timeout: agreed that a single wall-clock deadline that preempts blocked reads is the right fix. It belongs to the same rework in Wait helpers ignore event: error and duplicate the stream parser #20, and this PR doesn't change the read-timeout behaviour from 1.9.0.

After four review rounds on the stream and poll helpers, further findings in that area go to #20 rather than this PR.

Kim Burgaard added 6 commits November 5, 2026 21:34
…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
…2e36

acc2e36 Updated skill

git-subtree-dir: .claude/skills/seclai-changelog
git-subtree-split: acc2e3659aa88562c9dcf8b8cc2e45e113bfcfed
@burgaard
burgaard merged commit eb2e4ca 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