Skip to content

rust 1.0 parity - #3214

Open
mattsp1290 wants to merge 28 commits into
ag-ui-protocol:mainfrom
mattsp1290:chore/rust-updates
Open

mattsp1290 wants to merge 28 commits into
ag-ui-protocol:mainfrom
mattsp1290:chore/rust-updates

Conversation

@mattsp1290

@mattsp1290 mattsp1290 commented Oct 26, 2026 •

Copy link
Copy Markdown
Collaborator

Current review status

Updated November 17 for 4307af4660bcabfe941803df0dc4fb62b7c8a339. Joshua approved the Rust implementation at ac80258 on 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

  • AG-UI 1.0 Rust core, client and encoder, with reconciled history, activity/reasoning handling and restored deprecated thinking/binary translation.
  • Optional-null compatibility normalization; bounded atomic state/activity patches; corrected tool-result ordering, replayed arguments and transport initialization.
  • Canonical SDK parity: reject unknown present text roles, tolerate request/start/finish ID mismatches like TypeScript, and expose a single optional success-only RunAgentResult.result. Missing/whole-null results become None; the redundant public output field is removed.
  • Named public protocol structs are non-exhaustive, with constructors/defaults for downstream use. Migration documentation and examples use the supported construction APIs.
  • HTTP status errors capture a bounded body prefix by default (64 KiB/two seconds), omit it from normal Display/Debug, and provide explicit inspection with truncation/timeout/read-failure metadata. Zero-byte configuration disables capture.
  • Recorded streams use a custom agent through Agent::run_input; the incomplete standalone core Replay reducer was removed. Raw custom adapters must normalize through CompatibilityBoundary before typed deserialization.
  • Immutable Git installation recipe, path-and-version crate dependencies, package/license updates and merge-result interoperability with source provenance and fresh immutable-head Git consumer verification.

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:

  • Hosted Rust qualification passed: Linux Rust 1.88 and stable, macOS stable and Windows stable, including build, formatting, Clippy, tests, doctests and documentation. Ubuntu stable also passed the three-crate workspace package dry-run.
  • Hosted HTTP interoperability and immutable Git consumer passed.
  • Local Rust 1.88 and stable suites each passed 198 tests, with zero failures and four live-backend tests ignored. Local doctests, warning-free docs, Clippy and package dry-run passed.
  • Both local Rust and TypeScript probes passed eight real HTTP exchanges, each checked with an independent schema/framing/history oracle and five negative controls. A separate fresh Rust 1.88 consumer passed against that November 5 public Git commit with its own lockfile.
  • November 5 GitHub check inventory: 90 successful, one skipped, one neutral; none failed or pending.

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

  • Bring the Rust core and client up to the AG-UI 1.0 wire format, including string IDs, event/message types, state replay, reasoning and activity handling, and legacy thinking translation.
  • Add shared fixture and conformance coverage, update the Rust documentation and examples, and prepare ag-ui-core and ag-ui-client 0.2.0 packaging.
  • Make the Rust CI lane run on pull requests to main and include both crate publish dry-runs.

Beans milestone: ag-ui-q761. The accepted source head is 5cc34b11fb41c6f068c27410b5756dbebcb367dd. The sole commit after the runtime implementation refreshes apps/dojo/src/files.json for the same Python example.

Verification

  • cargo build --all-targets
  • cargo fmt -- --check
  • cargo clippy -- -D warnings
  • cargo test
  • cargo test -p ag-ui-client --test conformance_streams -- --nocapture (64 passed, four explicit era compatibility skips)
  • Local Python SSE starter with the Rust basic_agent and shared_state examples
  • ag-ui-core and ag-ui-client 0.2.0 publish dry-runs

All 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 separate pkg-pr-new publish 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.

@mattsp1290
mattsp1290 requested a review from a team as a code owner October 26, 2026 18:19
@mintlify

mintlify Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 4307af4.

Approve preview

@joshua-mo-143 joshua-mo-143 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

see comments

Comment on lines +444 to +445
opt("parentRunId", Rule::String),
opt("input", Rule::Nested(Kind::Input)),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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:

  • parentRunId and input on these lines
  • event-level subagentRunId (:364)
  • TOOL_CALL_RESULT.role (:422)
  • RUN_ERROR.usage (:457)
  • the usage entry fields provider, reasoningTokens, cachedInputTokens and cacheWriteInputTokens (:628, :633-635)
  • pendingToolCallIds on a success outcome (:644)

Adding the MAF recordings to the shared corpus would cover every lane.

Comment thread .github/workflows/rust-lint-test.yml Outdated
Comment on lines +110 to +111
- name: Verify pinned TypeScript implementation and schema
run: python3 tests/interop/verify.py --pins-only

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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(|_| {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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() {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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:

Suggested change
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.

Comment on lines +369 to +372
opt(
"role",
Rule::Enum(&["developer", "system", "assistant", "user"]),
),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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?

Comment on lines +90 to +95
Event::RunStarted(e) => {
if e.thread_id != *thread_id {
return Err(AgentError::ExchangeIdentity(
"RUN_STARTED threadId does not match the request".into(),
));
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

Comment on lines +98 to +102
# 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"}]
)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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}")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

Comment on lines +105 to +106
let expected = prepare_run_input(&second).unwrap().input;
assert_eq!(captured.body, serde_json::to_vec(&expected).unwrap());

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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
@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Python Preview Packages

Version 0.0.0.dev1794584658 published to TestPyPI.

Warning: These packages are built from contributor code that may not yet have been vetted for correctness or security. Install at your own risk and do not use in production.

Install with uv

Add the TestPyPI index to your pyproject.toml:

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
explicit = true

Then 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 testpypi

Install with pip

pip install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  ag-ui-protocol==0.0.0.dev1794584658

Use --extra-index-url https://pypi.org/simple/ so pip can resolve
transitive dependencies (pydantic, fastapi, etc.) from real PyPI.


Commit: 338787e

@pkg-pr-new

pkg-pr-new Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@ag-ui/a2a-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2a-middleware@3214

@ag-ui/a2ui-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2ui-middleware@3214

@ag-ui/event-throttle-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/event-throttle-middleware@3214

@ag-ui/mcp-apps-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/mcp-apps-middleware@3214

@ag-ui/mcp-middleware

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/mcp-middleware@3214

@ag-ui/a2a

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2a@3214

@ag-ui/adk-js

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/adk-js@3214

@ag-ui/adk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/adk@3214

@ag-ui/ag2

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/ag2@3214

@ag-ui/agno

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/agno@3214

@ag-ui/antigravity

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/antigravity@3214

@ag-ui/aws-strands

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/aws-strands@3214

@ag-ui/claude-agent-sdk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/claude-agent-sdk@3214

@ag-ui/claude-managed-agents

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/claude-managed-agents@3214

@ag-ui/crewai

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/crewai@3214

@ag-ui/langchain

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/langchain@3214

@ag-ui/langgraph

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/langgraph@3214

@ag-ui/llamaindex

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/llamaindex@3214

@ag-ui/mastra

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/mastra@3214

@ag-ui/openai-agents

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/openai-agents@3214

@ag-ui/pydantic-ai

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/pydantic-ai@3214

@ag-ui/vercel-ai-sdk

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/vercel-ai-sdk@3214

@ag-ui/watsonx

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/watsonx@3214

@ag-ui/a2ui-toolkit

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/a2ui-toolkit@3214

create-ag-ui-app

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/create-ag-ui-app@3214

@ag-ui/client

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/client@3214

@ag-ui/core

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/core@3214

@ag-ui/encoder

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/encoder@3214

@ag-ui/proto

pnpm add https://pkg.pr.new/ag-ui-protocol/ag-ui/@ag-ui/proto@3214

commit: 4307af4

@mattsp1290

mattsp1290 commented Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator Author

Rust SDK re-review summary

I’m an AI agent assisting Matt, updating this summary at his request.

This PR updates ag-ui-core, ag-ui-client and ag-ui-encoder for AG-UI 1.0. The revision covered here is 8a9cca4845f32e179394d17e6b927e6d27a7f771.

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

  • Text roles: a supplied role on TEXT_MESSAGE_START or TEXT_MESSAGE_CHUNK must be developer, system, assistant or user. Unknown values fail validation rather than being stripped. This follows Python/TypeScript behavior and addresses the role-validation question.
  • Run and thread identifiers: mismatches between the request, RUN_STARTED and RUN_FINISHED are accepted, following TypeScript. This addresses the identity-validation question. Event ordering, terminal completion and checks for unfinished text/tool/subagent streams still apply.
  • One result field: RunAgentResult.result is Option<JsonValue>; the redundant public output field is removed. A successful finish, including an omitted outcome, may expose a result. Missing or whole-value null becomes None; cancelled/interrupted runs and producer errors have no result. False, zero and nested nulls remain intact.
  • Extensible protocol records: named public protocol structs are #[non_exhaustive] with constructors or defaults, allowing fields to be added later. Downstream callers must replace struct literals with the provided constructor or Default, then assign optional fields. Protocol enums are also non-exhaustive.
  • HTTP error bodies: non-success responses retain a body prefix bounded to 64 KiB and two seconds by default. Display/Debug omit the body. Explicit http_error_body() inspection exposes bytes/text, truncation and the reason capture stopped, including read failure or timeout. A zero-byte limit disables capture. Captured content may contain secrets and needs filtering before logging or sharing.

Review fixes included

  • State and activity patches use a working copy, commit only on success, and enforce a maximum JSON depth of 128 before each operation. This avoids partial state changes and the patch library’s rollback panic.
  • Tool results stay next to their calls without replacing unrelated messages when IDs collide. Replayed tool arguments replace the saved arguments on the first new chunk instead of duplicating them. Server-echoed messages enter history, and on_run_initialized changes reach the outgoing request.
  • Explicit nulls on supported optional fields are normalized. Deprecated THINKING_* events and legacy binary content are translated rather than discarded.
  • Recorded streams run through a custom Agent::run adapter and Agent::run_input, using the same lifecycle validation and history processing as HTTP. The incomplete standalone core Replay reducer was removed.
  • Installation docs use the upstream repository and an immutable Git revision. Crates use path-and-version dependencies. Packaging, license files and migration notes are updated.
  • Interoperability checks exercise the PR merge result, record source provenance instead of blocking on fixed TypeScript file hashes, and compare actual HTTP requests/events/history with independently authored expectations. A separate fresh Git consumer verifies the exact contributor head.

The shared Python demo scope question no longer applies: the current PR diff changes neither that demo nor apps/dojo/src/files.json.

Verification and current status

GitHub 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:

  • Hosted Rust qualification passed on Linux with Rust 1.88 and stable, plus macOS and Windows with stable: build, formatting, Clippy, tests, doctests and documentation. Ubuntu stable also passed the three-crate workspace package dry-run.
  • Hosted HTTP interoperability and fresh Git consumer passed.
  • The recorded local Rust 1.88 and stable suites each passed 198 tests, with zero failures and four live-backend tests ignored. Doctests, warning-free docs, Clippy and package dry-run passed.
  • The recorded local Rust and TypeScript probes each passed eight real HTTP exchanges, with independent schema, framing and history checks and five deliberately corrupted cases that the verifier rejected. A separate fresh Rust 1.88 consumer passed against this public Git revision with its own lockfile.

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

  • Custom adapters reading raw JSON must call CompatibilityBoundary before typed deserialization so compatibility warnings are not lost.
  • Three optional older-peer conversions remain excluded: flattening structured content, downgrading subagent events and omitting protocol-version declarations.
  • Four live-backend tests remain ignored. A timeout can happen after server-side work starts; cancellation or a callback panic cannot await asynchronous finalizers.
  • Crates remain unpublished. Passing checks, package dry-runs and Git-consumer tests do not constitute a registry release or approval to merge.

@joshua-mo-143 joshua-mo-143 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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 omitted owned activities, but here declares_activity is 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.

Comment thread .github/workflows/rust-interop.yml Outdated

on:
push:
branches: [main, chore/rust-updates, "feat/rust-**"]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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?

@mattsp1290

Copy link
Copy Markdown
Collaborator Author

Follow-up to the activity snapshot review

I’m Forg, an AI agent assisting Matt. @joshua-mo-143, commit ac80258 addresses both findings in your latest review.

What changed

Activity deletion now matches the canonical TypeScript client. MESSAGES_SNAPSHOT reads metadata["@ag-ui/client"].authoritativeActivityTypes:

  • A string array deletes omitted activities only for the listed types.
  • null deletes every omitted activity, including when the snapshot is empty.
  • [] or a malformed namespace/declaration deletes no omitted activities.
  • An absent namespace or absent declaration preserves the previous inference from whether the snapshot contains activities.

Matching message IDs still update regardless of deletion authority. Reasoning-message reconciliation remains independent. The implementation was compared directly with TypeScript’s activity-history.ts and snapshot reducer.

CI cleanup: both Rust workflows now restrict push and pull_request branch filters to main. Fork branches targeting main still trigger pull-request checks.

Verification for this commit

  • Reproduced the empty-snapshot/explicit-null bug before applying the fix.
  • Added a 24-case authority/metadata matrix and a matching-ID replacement regression.
  • Local Rust 1.88: 200 tests passed, eight doctests passed, plus strict workspace Clippy and formatting checks.
  • Hosted Rust qualification and interoperability passed. All 13 substantive workflows are green, including all 39 E2E jobs.

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 joshua-mo-143 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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) and EventValidationError (event.rs:774) should be #[non_exhaustive]. DiagnosticCategory already 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, encoder Limits and EncodeError, 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 a String error. Make it crate-private or give it a typed error.
  • Remove AgUiClientError::ExchangeIdentity and EventValidationError::EmptyDelta. Neither can occur now.
  • Small one: mark the reqwest::Error fields as #[source] so error chains work.

Could you also reply to or resolve my earlier threads individually?

@mattsp1290

mattsp1290 commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator Author

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 ac80258 head. Its incremental commit is 99c0677; until #3214 merges, the follow-up’s main-based diff also contains this PR. Neither PR has been merged, and no crates have been published.

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 99c06777 is now green: all 13 substantive workflows, including eight Rust qualification/feature jobs, interoperability and all 39 E2E jobs.

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.

This branch has not been deployed

No deployments
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.

5 participants