Skip to content

fix: harden workflow execution and refresh release integration guidance - #30

Merged
Zhoujie628 merged 19 commits into
project-openan:mainfrom
Zhoujie628:main
Aug 31, 2026
Merged

fix: harden workflow execution and refresh release integration guidance#30
Zhoujie628 merged 19 commits into
project-openan:mainfrom
Zhoujie628:main

Conversation

@Zhoujie628

@Zhoujie628 Zhoujie628 commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Keep workflow scheduling and standard A2A transport separate from host-owned A2A-T content generation, validation and business callbacks.
  • Harden cancellation propagation, execution-owned resource cleanup, registry response deadlines and credential handling.
  • Preserve multiple business outputs from arbitrary terminal workflow nodes and isolate per-request cancellation from independent authorization/notification channels.
  • Improve protocol log readability without hiding extension business content, and keep mandatory credential redaction.
  • Refine sample notification inputs and offline SDK validation fixtures.
  • Publish host-neutral bilingual integration guidance, an executable HostQuickStart example and compilation checks for documentation snippets.
  • Require sample verification in CI and clean up release metadata and shared ignore rules.

Scope and review notes

This PR targets the common/direct implementation on main. Vendor-specific forwarding code and configuration remain on dev and are not included.

The comparison includes earlier committed Java formatting and cleanup work as well as the functional changes above. The final hardening and ignore-rule cleanup were committed separately; no additional whole-file formatting was applied in those changes.

The supported baseline remains A2A-T SDK 1.1.0 and A2A Java SDK 1.2.0.Final. No older-SDK compatibility layer is introduced.

Validation

  • JDK 17: mvn -o -B -Dstyle.color=never clean verify on main: 229 tests, zero failures, errors or skips.
  • Companion dev verification: 282 tests, zero failures, errors or skips, including direct and forwarding-simulator end-to-end scenarios.
  • Default single-city negotiation, independent extension lifecycle, cancellation, terminal-output aggregation and executable documentation examples are covered.
  • Relative documentation file links and git diff --check passed.
  • All proposed commits have DCO signoffs.

These results use the released SDK artifacts with an offline LLM provider and local protocol simulators. They do not constitute live-model or production OMC acceptance. Cross-worktree end-to-end runs must execute sequentially because they share local server ports.

No release publication, tag or automatic merge is requested.

@Zhoujie628
fix(logging): decode printable ASCII unicode escapes in the wire display
edfd071 
Protobuf-JSON also escapes angle brackets and ampersands as unicode
escapes for HTML safety, so authorization and notification prompts
still displayed sequences like <授权策略的操作类型> as escaped text
after the non-ASCII decoding. The display now decodes every printable
non-structural escape; quotes, backslashes and control characters stay
escaped so the displayed JSON remains readable.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
fix(logging): keep extension-URI business content visible in the wire…
d732d67 
… display

Restores the URI guard in WireLog.sensitive() and its redaction test:
extension-URI keys (e.g. the Authorization-T extension URI in message
metadata) are protocol identifiers, not credential fields, so their
values are business content and stay visible; HTTP Authorization
headers and credential-shaped keys remain masked.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
fix(samples): carry an explicit notification subscription condition
fb31cb5 
The demo subscription passed an empty subscription condition. The
fromData rendering collapses the blank slot to a bare section header,
and real-LLM semantic validation rejects that prompt as a missing
parameter (code=content.param_missing), so the pre-positioned
Notification-T subscription never validated. The offline E2E provider
never flagged this because its canned responses do not judge section
content. Carry an explicit subnet constraint so the rendered section is
complete and validates against a real LLM.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
test(samples): raise the offline LLM provider's fidelity to real judg…
6c69760 
…ments

The offline E2E provider answers from the observed prompt source, but its
verdict accepted a Notification-T subscription whose rendered condition
section was blank - a gap a real provider rejects as a missing
parameter, which is exactly how the empty demo condition went unnoticed
until a real-LLM run. The verdict now rejects a blank rendered
subscription condition, and a dead hardcoded negotiation fromText
acceptance branch (unreachable: the samples only use fromData
negotiation generation) is removed so no SDK response shape is stubbed
in the offline provider.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
docs: add the demo end-to-end A2A-T SDK call inventory to the guide
8645e0c 
Lists every a2a-t-sdk invocation in the SpringSpnDemo business chain in
business-time order (inbound Task-T validation, per-city Task-T
generation, the negotiation propose/accept loop, pre-positioned
authorization and notification, and subscription validation), with the
calling role and the sample class implementing each step. States the
coverage explicitly: all 8 validate interfaces and all 7 fromData
generation interfaces are exercised with real calls; fromText
generation is not used by the samples.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
docs: order the SDK call inventory by real business timing
80004e8 
Authorization and notification are pre-positioned operations: the
workbench generates both payloads before dispatching the workflow tasks
and sends them alongside the Task-T message, and the OMC validates them
on receipt before diagnosis runs. Move those four steps ahead of the
Task-T dispatch and negotiation loop so the inventory reflects when the
calls actually happen.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
docs: authorization and subscription go on their own channels, not wi…
3e9eb4c 
…th Task-T

The inventory wording implied the pre-positioned authorization and
notification payloads travel with the Task-T message. They do not: the
authorization rides its own one-shot channel and the notification its
own long-lived subscription channel, both sent before the workflow
tasks are dispatched. Pair each operation's generation with the OMC-side
validation and drop the piggyback wording.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
docs: fix mermaid sequence-diagram parse errors
47e678f 
Semicolons are statement separators in mermaid, so the message labels
'Validate proposal; generate reply' and 'Same task/context; final reply
content' broke the diagram parser (Expecting arrow, got NEWLINE). Reword
the two labels; the same lines appeared in the workbench integration
guide and both language versions of the design doc.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
chore: remove dead code surfaced by a full reference audit
b3f7b58 
- SseNormalization and its test: the javadoc still claimed the default
  workflow client calls it after deserializing each response, but the
  ProtocolResponses refactor took over response assembly and no
  production code references the class anymore.
- AgentAuthManager.extractExtensionUris: private helper with no call
  sites.
- A2ATransport.getAgentNames and updateAgentCards: public methods with
  no callers in main or test sources and no documentation references;
  the initial release keeps no speculative surface.

RegistryClient stays: it is the documented registry-center integration
point (API reference and architecture diagram). Full reactor verify
passes 271/271 after the removal.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
refactor(model): avoid wildcard-capture inference in MessageContent s…
a11f691 
…napshot

The stream map with a method reference over List<Part<?>> makes some
IDE inference engines resolve the mapper's return as a capture of the
wildcard instead of the declared Part<?>, surfacing a false
List<? extends Part<?>> mismatch even though javac accepts the code.
Rewrite the snapshot as an explicit loop so the element type is stated
at every step and no inference is required.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
style(model): drop redundant private on @value class fields
2f85392 
Lombok @value makes fields private and final by default, so the explicit
private modifier on TaskRequest and TaskResult field declarations is
redundant; the bytecode visibility is unchanged (verified via javap).

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
refactor(samples): migrate off the deprecated A2ATErrorCodes constants
3957dcd 
A2ATErrorCodes is Deprecated(forRemoval) in A2A-T SDK 1.1.0; its
constants delegate to the ErrorCatalog enum. Compare the retryable
validation codes against ErrorCatalog.NEGOTIATION_SEMANTIC_REJECTED and
ErrorCatalog.SLOT_RULE_VIOLATION directly - identical runtime codes,
no deprecated reference left in the engine.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
style: apply the shared Java formatting profile on main
593aaa4 
Same formatter pass the dev branch already carries: consistent
indentation, import ordering, and javadoc line wrapping across the
workflow-engine, samples, and spring-boot-starter sources. No
behavioral change; brings the common files byte-identical to dev so
future dev-to-main cherry-picks no longer conflict on formatting.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
refactor: adopt dev's code cleanup on shared wire-log and transport f…
f4e2c79 
…iles

Dev's second formatting pass also applied code cleanup to four common
files: null-safe required-flag check in A2ATransport, the concise
ByteArrayOutputStream-to-string conversion in WireLog, an obsolete cast
removal in ExecutePsopTest, and wildcard assertion imports in
A2ATransportHeaderTest. Take dev's versions so the common files are
byte-identical across branches.

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
fix(engine): harden cancellation, discovery deadlines and credential …
a204f65 
…handling

Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
fix(samples): preserve terminal outputs and isolate execution lifecycles
6264180 
Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
docs: publish host-neutral integration guidance and executable examples
3e73e3d 
Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
chore(release): require sample checks and sanitize build metadata
f4394da 
Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
chore: keep local reference exclusions out of shared gitignore
fc63df9 
Signed-off-by: Zhoujie628 <zhoujie628@users.noreply.github.com>
@Zhoujie628
Zhoujie628 requested a review from a team as a code owner August 31, 2026 08:03
@Zhoujie628
Zhoujie628 merged commit 9324297 into project-openan:main Aug 31, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Zhoujie628