Repository navigation
rust 1.0 parity - #3214
rust 1.0 parity#3214mattsp1290 wants to merge 28 commits into
Conversation
…ust-sdk-1-0-parity/nxzo-1
…ust-sdk-1-0-parity/corrected-target
Preview approval requiredThis pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit |
| opt("parentRunId", Rule::String), | ||
| opt("input", Rule::Nested(Kind::Input)), |
There was a problem hiding this comment.
B1 (blocker): explicit nulls from MAF .NET 1.23 fail the run here.
MAF .NET 1.23 sends explicit null for optional fields, starting with RUN_STARTED.parentRunId. opt(...) treats null as a malformed value, so Rust fails all three of the MAF recordings TypeScript commits as fixtures (compatibility-boundary-optional-nulls.test.ts) on their first event: InvalidValue at /parentRunId, or /usage for the RUN_ERROR recording. TypeScript treats these nulls as absent and warns (OPTIONAL_NULLS in compatibility-boundary.ts, added in 7f62329b after this PR branched).
Suggested fix: switch to nullable(...), keeping the warning, for the positions in TypeScript's list that are still opt here:
parentRunIdandinputon these lines- event-level
subagentRunId(:364) TOOL_CALL_RESULT.role(:422)RUN_ERROR.usage(:457)- the usage entry fields
provider,reasoningTokens,cachedInputTokensandcacheWriteInputTokens(:628,:633-635) pendingToolCallIdson a success outcome (:644)
Adding the MAF recordings to the shared corpus would cover every lane.
| - name: Verify pinned TypeScript implementation and schema | ||
| run: python3 tests/interop/verify.py --pins-only |
There was a problem hiding this comment.
B2 (blocker): this step fails on the merge result, so main would go red at merge.
Merged with main at fb144a05, 20 of the 98 files in pins.json hash differently and 2 new runtime files are unpinned. verify.py --pins-only stops at sdks/typescript/packages/client/package.json before any live test runs. The fork's green run couldn't show this, because this job tests the head rather than the merge (S2). It would keep happening: 24 of the 174 merges to main since this PR branched would each have broken the pins on their own, and so would every TypeScript release.
The job already builds @ag-ui/client from the same checkout and compares exact requests, events and history, so a real interop break fails it anyway. With the pins bypassed, every other step passes on the merge result.
Suggested fix: remove the hash gate here and in check_pins() itself (tests/interop/verify.py:16-32; see the comment on tests/external-consumer/verify.py). For provenance, record the client version and git rev-parse HEAD:sdks/typescript/packages/client in the evidence instead.
| proof = output / "rust-http-proof.json" | ||
| command(cargo + ["run", "--locked", "--bin", "rust-probe", "--", str(proof)], consumer, env, log) | ||
| # The independent schema checker reads evidence only, not its Rust deps. | ||
| command(["python3", str(INTEROP / "verify.py"), str(proof)], ROOT, env, log) |
There was a problem hiding this comment.
B2, continued: removing the workflow step isn't enough on its own. This line runs tests/interop/verify.py on the consumer's evidence, and that script's main() calls check_pins() unconditionally (tests/interop/verify.py:180). So this check and the evidence oracle step fail the same way. If maintainers want a tripwire, a scheduled, non-blocking job plus a script that regenerates pins.json would keep it from blocking unrelated merges.
| ) | ||
| .await?; | ||
| } else { | ||
| let new_state: StateT = serde_json::from_value(state_val).map_err(|_| { |
There was a problem hiding this comment.
M1 (must-fix): a crafted delta can abort the whole process here.
Starting from {"op":"add","path":"/c","value":{}}, each repeat of these three operations nests the state one level deeper:
{"op":"add","path":"/n","value":{}}
{"op":"move","from":"/c","path":"/n/c"}
{"op":"move","from":"/n","path":"/c"}from_value here, and the clone and drop around it, recurse with no depth limit (serde_json's 128-level limit only applies when parsing text). Over real HTTP/SSE, a STATE_DELTA of about 456 KB (depth 4,000) overflows a tokio worker's stack, in release builds too. That's an abort, not a panic: nothing is finalized, and every task in the process dies. TypeScript gets a catchable RangeError and warns instead. Only a hostile server would send this, but the spec treats state content as crossing a trust boundary.
Suggested fix: bound depth per operation while patching (the destination's depth plus the inserted value's depth, with a limit of 128 like the parser), and reject the delta with PatchNotApplied. Checking after patching is too late, because dropping the deep value recurses too.
| let new_state: StateT = serde_json::from_value(state_val)?; | ||
| self.state = new_state; | ||
| current_mutation.state = Some(self.state.clone()); | ||
| if json_patch::patch(&mut state_val, &patches).is_err() { |
There was a problem hiding this comment.
M2 (must-fix): a malformed delta panics the client here.
[{"op":"add","path":"/a","value":1},{"op":"move","from":"/a","path":"/missing/x"}]The move removes /a and then fails to add, so json_patch::patch() can't undo the first operation and hits unreachable!("unable to undo applied patches") (json-patch 4.0.0 src/lib.rs:448; 4.2.0 is the same). The panic unwinds out of run_input, so on_run_failed and on_run_finalized never run, and under panic = "abort" the process dies. A buggy producer is enough: Python's jsonpatch.make_patch, which two example servers in this repo use, emits move, and such a delta fails once the client's state has drifted from the producer's.
state_val is a throwaway copy, so skipping the rollback is safe:
| if json_patch::patch(&mut state_val, &patches).is_err() { | |
| if json_patch::patch_unsafe(&mut state_val, &patches).is_err() { |
The same change applies at :525 and in ag-ui-core/src/replay.rs:206. With all three applied, fmt, clippy and the workspace tests pass, and 20 minutes of fuzzing found no crashes.
| opt( | ||
| "role", | ||
| Rule::Enum(&["developer", "system", "assistant", "user"]), | ||
| ), |
There was a problem hiding this comment.
D1 (spec-backed divergence: maintainer decision). An unknown role here is stripped with an UnknownEnumValue warning (:780-789), and the PR records that as a Rust override in spec/1.0/conformance/streams/unknown-enum-value-role-fatal.json, where TypeScript (a ZodError) and .NET fail the run. The spec sides with Rust: the Note in docs/spec/1.0/basic/processing.mdx:94-101 and spec/1.0/conformance/README.md:37-43 both call the fatal behaviour a gap. But the fixture's kill text asks whoever fixes the gap to update the base expectation and delete that Note in the same change, and the override adds a third behaviour instead. Rust also isn't consistent with itself: single-value literal roles (REASONING_MESSAGE_START.role at :396, TOOL_CALL_RESULT.role, ToolCall.type) stay fatal.
For maintainers: accept Rust implementing the rule ahead of TypeScript (update the base and file TypeScript and .NET follow-ups), or require parity until TypeScript is fixed?
| Event::RunStarted(e) => { | ||
| if e.thread_id != *thread_id { | ||
| return Err(AgentError::ExchangeIdentity( | ||
| "RUN_STARTED threadId does not match the request".into(), | ||
| )); | ||
| } |
There was a problem hiding this comment.
D3 (spec-backed divergence: maintainer decision): run-identity checks reject streams TypeScript accepts. This fails the run when RUN_STARTED.threadId differs from the request. :109-117 does the same for RUN_FINISHED's IDs, and check_completion (:429-441) fails when the final successful run isn't the requested one. TypeScript has no identity checks, and the corpus can't see the difference because the Rust lane copies request IDs from each fixture.
run-input.mdx:19-25 makes boundary run-ID agreement a producer MUST, which backs the RUN_FINISHED check, but echoing the request's threadId and runId is described rather than required. I found no HTTP producer in this repo that trips it. For maintainers: match TypeScript (accept the stream and emit a diagnostic), or make strict identity opt-in? If it stays strict, corpus fixtures with mismatched request IDs would record the decision for the other lanes.
| # Show clients how to apply a JSON Patch after the initial recipe snapshot. | ||
| yield StateDeltaEvent( | ||
| type=EventType.STATE_DELTA, | ||
| delta=[{"op": "replace", "path": "/recipe/cooking_time", "value": "30 min"}] | ||
| ) |
There was a problem hiding this comment.
Q2 (question for maintainers): should a Rust PR change the shared Python demo? This makes the Dojo's recipe cooking time flip from 15 to 30 minutes after every response, and regenerating apps/dojo/src/files.json for it is what causes this PR's merge conflict. No test asserts the old sequence. The alternative is a Rust-local fixture server for examples/shared_state.rs.
| } | ||
| } | ||
| }; | ||
| format!("error body omitted; inspected {inspected} bytes; {reason}") |
There was a problem hiding this comment.
Q4 (question for maintainers): should non-2xx response bodies be exposed? This deliberately returns only "error body omitted…" to avoid reflecting secrets, and I confirmed it doesn't leak them. TypeScript returns status and payload, so its users can see, for example, a FastAPI 422 validation error. An opt-in, bounded capture might be a middle ground.
| let expected = prepare_run_input(&second).unwrap().input; | ||
| assert_eq!(captured.body, serde_json::to_vec(&expected).unwrap()); |
There was a problem hiding this comment.
Q6 (question for maintainers): this oracle is self-referential. It asserts that the wire body equals the implementation's own prepare_run_input output (also :149-151), and the fixture server encodes with the PR's encoder and parses with its own normalize_run_input, so matching bugs would cancel out. Is an independently written expected body worth adding?
| run: cargo build --verbose | ||
|
|
||
| - name: Install compiler and quality tools | ||
| run: rustup toolchain install ${{ matrix.toolchain }} --profile minimal --component clippy,rustfmt |
| workspaces: sdks/community/rust | ||
| key: ${{ matrix.toolchain }} | ||
| - name: Build all public crates and test targets | ||
| run: cargo +${{ matrix.toolchain }} build --workspace --all-targets --locked |
| - name: Check formatting | ||
| run: cargo fmt -- --check | ||
|
|
||
| run: cargo +${{ matrix.toolchain }} fmt --all -- --check |
|
|
||
| - name: Run tests | ||
| run: cargo test --verbose | ||
| run: cargo +${{ matrix.toolchain }} clippy --workspace --all-targets --locked -- -D warnings |
| run: cargo test --verbose | ||
| run: cargo +${{ matrix.toolchain }} clippy --workspace --all-targets --locked -- -D warnings | ||
| - name: Complete fixture, producer, HTTP and lifecycle suites | ||
| run: cargo +${{ matrix.toolchain }} test --workspace --all-targets --locked |
| - name: Complete fixture, producer, HTTP and lifecycle suites | ||
| run: cargo +${{ matrix.toolchain }} test --workspace --all-targets --locked | ||
| - name: Doctests | ||
| run: cargo +${{ matrix.toolchain }} test --workspace --doc --locked |
| - name: Documentation warnings | ||
| env: | ||
| RUSTDOCFLAGS: -D warnings | ||
| run: cargo +${{ matrix.toolchain }} doc --workspace --no-deps --locked |
Python Preview PackagesVersion
Install with uvAdd the TestPyPI index to your [[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
explicit = trueThen install the packages you need: # Core SDK
uv add 'ag-ui-protocol==0.0.0.dev1794584658' --index testpypi
# Integrations (each already depends on the matching ag-ui-protocol preview)
uv add 'ag-ui-langgraph==0.0.0.dev1794584658' --index testpypi
uv add 'ag-ui-crewai==0.0.0.dev1794584658' --index testpypi
# NOTE: ag-ui-agent-spec depends on pyagentspec (git-only, not on PyPI).
# You will need to install pyagentspec separately from its git repo.
uv add 'ag-ui-agent-spec==0.0.0.dev1794584658' --index testpypi
uv add 'ag_ui_adk==0.0.0.dev1794584658' --index testpypi
uv add 'ag_ui_strands==0.0.0.dev1794584658' --index testpypiInstall with pippip install \
--index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple/ \
ag-ui-protocol==0.0.0.dev1794584658
Commit: 338787e |
@ag-ui/a2a-middleware
@ag-ui/a2ui-middleware
@ag-ui/event-throttle-middleware
@ag-ui/mcp-apps-middleware
@ag-ui/mcp-middleware
@ag-ui/a2a
@ag-ui/adk-js
@ag-ui/adk
@ag-ui/ag2
@ag-ui/agno
@ag-ui/antigravity
@ag-ui/aws-strands
@ag-ui/claude-agent-sdk
@ag-ui/claude-managed-agents
@ag-ui/crewai
@ag-ui/langchain
@ag-ui/langgraph
@ag-ui/llamaindex
@ag-ui/mastra
@ag-ui/openai-agents
@ag-ui/pydantic-ai
@ag-ui/vercel-ai-sdk
@ag-ui/watsonx
@ag-ui/a2ui-toolkit
create-ag-ui-app
@ag-ui/client
@ag-ui/core
@ag-ui/encoder
@ag-ui/proto
commit: |
Rust SDK re-review summaryI’m an AI agent assisting Matt, updating this summary at his request. This PR updates What remains: maintainer re-review of the implementation and API migrations below. Joshua’s changes-requested review is still outstanding. The API choices described here are implemented proposals for review, not maintainer approval; no review threads have been marked resolved. API behavior now implemented
Review fixes included
The shared Python demo scope question no longer applies: the current PR diff changes neither that demo nor Verification and current statusGitHub status rechecked November 6, 2026: the head is unchanged, GitHub reports no merge conflicts, and merging remains blocked with the changes-requested review outstanding. Check results for this head are 90 successful, two skipped automated-approval runs and one neutral Mintlify preview; none failed or pending. The documentation preview still needs a maintainer’s approval. Verification completed November 5 for this revision:
The local tests were not rerun for this wording/status update. Reproduction commands and scope are in the Rust README and HTTP interoperability README. Remaining limits
|
joshua-mo-143
left a comment
There was a problem hiding this comment.
Thanks for the thorough rework. I went through the HTTP/SSE transport, bounded error-body capture, patch application, lifecycle verification, the compatibility boundary and run_input, and they look solid. The double normalization in run_input is safe because the second pass only ever sees canonical 1.0 events.
One parity gap is worth closing before this goes in as "canonical SDK parity": MESSAGES_SNAPSHOT reconciliation ignores the TypeScript client's documented metadata["@ag-ui/client"].authoritativeActivityTypes declaration, so activity deletion can differ between the two clients (see inline). There's also a small CI cleanup for leftover branch filters.
My earlier changes-requested threads still need to be gone through individually; I haven't resolved them here.
| *message = (*replacement).clone(); | ||
| true | ||
| } else { | ||
| matches!(message.role(), Role::Activity if !declares_activity) |
There was a problem hiding this comment.
Parity gap with the TS client: this only infers activity authority from whether the snapshot contains activity messages. TS also honours metadata["@ag-ui/client"].authoritativeActivityTypes (documented in sdks/typescript/packages/client/README.md under "Activity snapshots", implemented in activity-history.ts):
["owned"]with no activity messages: TS deletes omittedownedactivities, but heredeclares_activityis false, so they're kept forever.null: TS treats every activity type as owned, even with an empty snapshot, so all omitted activities are deleted. Here they're all kept.[], or an invalid namespace/field: TS owns nothing, so omitted activities are kept even if the snapshot carries activity. Here, any activity in the snapshot deletes all omitted ones.
Suggest reading e.base.metadata in the MessagesSnapshot arm and passing an Option<Option<Vec<String>>> scope into reconcile_messages, mirroring authoritativeActivityTypes(). Then filter omitted activities by activity_type when a scope is declared. A test lifted from default.activity.test.ts would pin it down.
|
|
||
| on: | ||
| push: | ||
| branches: [main, chore/rust-updates, "feat/rust-**"] |
There was a problem hiding this comment.
chore/rust-updates and feat/rust-** look like working branches from your fork; they don't exist upstream. Could we trim both workflows (this one and rust-lint-test.yml, under both push and pull_request) to main so the triggers don't carry fork-specific names?
Follow-up to the activity snapshot reviewI’m Forg, an AI agent assisting Matt. @joshua-mo-143, commit What changedActivity deletion now matches the canonical TypeScript client.
Matching message IDs still update regardless of deletion authority. Reasoning-message reconciliation remains independent. The implementation was compared directly with TypeScript’s CI cleanup: both Rust workflows now restrict Verification for this commit
Please re-review these changes and the earlier changes-requested threads. Those threads have not been marked resolved; this update does not assume approval of the earlier API decisions. |
joshua-mo-143
left a comment
There was a problem hiding this comment.
Thanks for working through all of this. I re-checked head ac80258 against my earlier threads and the Nov 11 comment.
The authoritativeActivityTypes handling now matches activity-history.ts in every case: absent, null, an array, a malformed namespace and non-string entries. The new tests go through run_input, so they also show the metadata survives normalization. The branch filters are fixed. The earlier blockers and must-fixes are in place with tests: patch depth and rollback, optional nulls, tool-result ordering, replayed arguments, initialization mutations, the diagnostics cap, the pins removal, inventory counts and the fork URLs. Clippy with -D warnings and the full test suite pass locally too.
I'm happy for this to merge. Before the crates are published, please address these. They are cheap now and breaking later:
DiagnosticCategory(processing.rs:15),RunTerminalStatus(agent.rs:140) andEventValidationError(event.rs:774) should be#[non_exhaustive].DiagnosticCategoryalready gained a variant in this PR. The changelog implies these are covered.- The deprecated chunk hooks (subscriber.rs:211, 222, 281) never fire, and
#[deprecated]doesn't warn implementors. Anyone overriding them loses behaviour silently. Removing them would turn that into a compile error, which suits a breaking 0.2.0. - ag-ui-client forces reqwest's default TLS (native-tls). Please add features so users can pick rustls, and ideally build without the HTTP transport.
- Public config and result structs with all-public fields (
RunAgentResult,AgentConfig,RunAgentParams, encoderLimitsandEncodeError,SseLimits,ErrorBodyLimits) will break on any new field. Consider#[non_exhaustive]with constructors. apply_patch_to_copy(patch.rs:36) exposes json_patch types and aStringerror. Make it crate-private or give it a typed error.- Remove
AgUiClientError::ExchangeIdentityandEventValidationError::EmptyDelta. Neither can occur now. - Small one: mark the
reqwest::Errorfields as#[source]so error chains work.
Could you also reply to or resolve my earlier threads individually?
|
I’m Forg, an AI agent assisting Matt. The requested pre-publication follow-up is now open as draft #3385: #3385 It addresses Joshua’s seven publication concerns: extensible enums/config/result types with constructors, removal of never-fired chunk hooks and unreachable errors, optional HTTP with selectable native TLS/rustls, typed patch errors, and reqwest error source chains. Migration docs and a new feature CI matrix are included. The follow-up is stacked on this PR’s approved Local validation passed: 205 tests, 15 doctests, strict Clippy, formatting, warning-free docs, all four client feature configurations, and a three-crate publication dry-run. Two complementary reviews found no important or critical issues. Hosted CI for An individual audit of all 51 earlier inline threads links each concern to its disposition and code/test evidence, distinguishing fixes already in this PR from the follow-up and documented limitations. The audit does not mark GitHub threads or security alerts resolved. |
Current review status
Updated November 17 for
4307af4660bcabfe941803df0dc4fb62b7c8a339. Joshua approved the Rust implementation atac80258on November 12. The Rust source, Rust documentation and both Rust workflows are byte-identical between that approved revision and the current merge-sync head. All 13 returned current-head workflows passed, including Rust qualification and interoperability. The 51 earlier inline threads have a complete linked disposition audit but remain unresolved on GitHub. Pre-publication API cleanup is implemented separately in draft #3385; merge and registry publication remain separate decisions.Status reconciliation by Forg, an AI agent assisting Matt. The original scope and verification record below are historical; this section supersedes older head, replay, fixture-skip and verification statements.
Current implementation
RunAgentResult.result. Missing/whole-null results becomeNone; the redundant publicoutputfield is removed.Agent::run_input; the incomplete standalone coreReplayreducer was removed. Raw custom adapters must normalize throughCompatibilityBoundarybefore typed deserialization.Current verification
Checked November 17 for
4307af4660bcabfe941803df0dc4fb62b7c8a339: all 13 returned pull-request workflow runs completed successfully, including Rust qualification and HTTP interoperability and immutable Git consumer. This is the returned workflow inventory, not an independent branch-protection verdict.Historical local and hosted verification below was recorded November 5 for
8a9cca4845f32e179394d17e6b927e6d27a7f771, not rerun by this status reconciliation:Review and release scope
Joshua’s November 12 approval supersedes his earlier changes-requested review. Individual thread and security-alert states are not changed by the disposition audit; all 51 inline threads remain unresolved. Draft #3385 contains the requested pre-publication API follow-up and must be reconciled after this PR lands. The previous role, identity, public-struct and result-field questions have been addressed following canonical SDK behavior and Matt’s Rust-specific API decisions. The earlier shared-Python-demo scope question was stale. Reviewers should assess these implementations and API migrations rather than choose among the old alternatives.
Three optional older-peer shims remain excluded: content flattening, subagent downgrade and protocol-version declaration omission. Four tests needing a live backend remain ignored. Timeout may follow server-side work; cancellation or callback panic cannot await async finalizers.
Crates remain unpublished. Passing checks, package dry-runs and Git-consumer verification do not approve merging or constitute a registry release.
Original scope and historical verification before the review fixes
Summary
ag-ui-coreandag-ui-client0.2.0 packaging.mainand include both crate publish dry-runs.Beans milestone:
ag-ui-q761. The accepted source head is5cc34b11fb41c6f068c27410b5756dbebcb367dd. The sole commit after the runtime implementation refreshesapps/dojo/src/files.jsonfor the same Python example.Verification
cargo build --all-targetscargo fmt -- --checkcargo clippy -- -D warningscargo testcargo test -p ag-ui-client --test conformance_streams -- --nocapture(64 passed, four explicit era compatibility skips)basic_agentandshared_stateexamplesag-ui-coreandag-ui-client0.2.0 publish dry-runsAll checks and the live examples passed at
5cc34b11. The Dojo generated file check and Rust SDK CI tests passed on Ubuntu, macOS, and Windows. The separatepkg-pr-newpublish jobs failed because that GitHub app lacks access to this repository.Scope notes
The shared conformance lane checks the five expectation fields in its milestone contract. Four retired era compatibility request shims are explicitly skipped. The crates have not been published; publication is tracked separately in
ag-ui-a63b.