examples: v2.2 event-injection demos for jobs[-ts/-java]

[dhyansraj]

Summary

Adds 6 runnable agent directories (2 per runtime: event-aware-provider + event-aware-consumer) under the existing examples/jobs/ (Python), examples/jobs-ts/, examples/jobs-java/ Phase 1 example trees. Demonstrates the v2.2 MeshJob event-injection surface end-to-end:

• Provider (task=True capability): loops on recv_event(types=["work", "stop"]), processes work events, returns {processed: N, status: "stopped"} when a stop event arrives.
• Consumer: submits the provider job, spawns a subscribe_events observer that mirrors events to logs, posts 3 work events + 1 stop event via post_event, awaits result. Returns {job_id, posted_seqs, observed_count, observed_events, result}. Java additionally returns subscriber_status.

Each runtime's pair was generated with meshctl scaffold basic --no-interactive (per project convention — don't hand-write boilerplate) and then trimmed to match the Phase 1 file convention (no Dockerfile / helm-values).

All three pairs validated end-to-end against locally-built binaries: Python (4s), TypeScript (4s), Java (3s) — each returning the expected JSON shape.

The pre-existing "What's NOT in Phase 1" sections in the three READMEs (which previously claimed events were not yet shipped) have been refreshed to "What's NOT in v2.2 yet".

Review Notes

Independent review caught 7 WARNINGs (0 BLOCKERs). Addressed:

• Python subscriber cancel not awaited — subscriber.cancel() now followed by await subscriber with CancelledError swallow. Avoids "Task was destroyed but it is pending!" GC warning.
• 3 different "start registry" commands across 3 READMEs — normalized all three Phase 2 sections to the canonical local-build form ./bin/mcp-mesh-registry, with a make build note. (Phase 1 sections preserved as-is.)
• Dead max(.., 1) clamp ×3 runtimes — processed / max(processed+1, 1) simplified to processed / (processed+1) in all 3 provider files. The clamp was dead code (processed ≥ 0 ⇒ processed+1 ≥ 1).
• Cancel-doesn't-interrupt limitations (TS Promise.race timeout + Java subscriber-thread leak past EventSubscription.close()) — documented honestly in source comments. JS has no cancellation primitive without AbortController plumbing through napi; Java's close() flips a volatile flag but doesn't interrupt in-flight FFI long-polls. Plumbing true interruption is out of scope for example code.
• Java proxy.close() may stall on subscriber tail — added one-line comment explaining the shared-cached-proxy + write-lock interaction with the in-flight subscriber's read-locked listEvents call.

Skipped with reason:

• TS structure drift (Phase 1 index.ts flat vs Phase 2 src/index.ts + tsconfig.json) — meshctl scaffold output is the modern Node convention; trimming Phase 2 to match Phase 1's older flat layout would actively make it worse for users. Phase 1 is the outlier; uplift is out of scope here.
• Java application.yml vs Phase 1's application.properties — same reasoning. Scaffold output, modern Spring Boot convention.
• 9 INFOs cosmetic (typing nitpicks, magic numbers, DEBUG logging defaults, version-comment phrasing, lockfile size) — none load-bearing.

Closes #1057

Test plan

• Python end-to-end (3-terminal flow per README) — call returns expected JSON in ~4s, no asyncio warnings in consumer log
• TypeScript end-to-end — same shape, ~4s
• Java end-to-end — same shape + subscriber_status: "ok", ~3s
• All 3 READMEs show consistent ./bin/mcp-mesh-registry registry-start command in their Phase 2 sections
• Phase 1 examples unchanged (no regression)
• No deprecated/legacy mentions; public-artifact framing observed (no naming downstream consumers, no behavioral framing)

Build prerequisites for runners

The examples assume the user has run make build at the repo root once (produces bin/mcp-mesh-registry, bin/meshctl, and the per-runtime SDK artifacts). Per-language additionally:

• Python: mcp-mesh-core editable install via maturin develop --release from src/runtime/core/.
• TypeScript: make build-rust-core (napi binding) + npm install in each agent dir.
• Java: mvn install -DskipTests -pl mcp-mesh-core,mcp-mesh-sdk -am plus MESH_NATIVE_LIB_PATH pointing to a directory containing an FFI-only libmcp_mesh_core.dylib (built via CARGO_TARGET_DIR=target/ffi cargo build --no-default-features --features ffi --release from src/runtime/core/). The default cargo build includes the Python feature which Java cannot load.

Summary by CodeRabbit

Release Notes

• New Features

  • Added Phase 2 event-injection examples demonstrating event-aware job handling across Java, TypeScript, and Python languages. Includes support for per-job event subscriptions, event posting, and event-driven task workflows.

• Documentation

  • Updated job examples documentation with Phase 2 quick-start guides, expected output formats, and current limitations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8f114c4f-47b8-4c46-a37d-d389b1ffb071

📥 Commits

Reviewing files that changed from the base of the PR and between 2a7fb01 and 05511fb.

⛔ Files ignored due to path filters (2)

• examples/jobs-ts/event-aware-consumer-ts/package-lock.json is excluded by !**/package-lock.json
• examples/jobs-ts/event-aware-provider-ts/package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (17)

• examples/jobs-java/README.md
• examples/jobs-java/event-aware-consumer-java/pom.xml
• examples/jobs-java/event-aware-consumer-java/src/main/java/com/example/eventawareconsumer/EventAwareConsumerApplication.java
• examples/jobs-java/event-aware-consumer-java/src/main/resources/application.yml
• examples/jobs-java/event-aware-provider-java/pom.xml
• examples/jobs-java/event-aware-provider-java/src/main/java/com/example/eventawareprovider/EventAwareProviderApplication.java
• examples/jobs-java/event-aware-provider-java/src/main/resources/application.yml
• examples/jobs-ts/README.md
• examples/jobs-ts/event-aware-consumer-ts/package.json
• examples/jobs-ts/event-aware-consumer-ts/src/index.ts
• examples/jobs-ts/event-aware-consumer-ts/tsconfig.json
• examples/jobs-ts/event-aware-provider-ts/package.json
• examples/jobs-ts/event-aware-provider-ts/src/index.ts
• examples/jobs-ts/event-aware-provider-ts/tsconfig.json
• examples/jobs/README.md
• examples/jobs/event-aware-consumer/main.py
• examples/jobs/event-aware-provider/main.py

---

📝 Walkthrough

Walkthrough

This PR adds Phase 2 event-injection examples across Python, TypeScript, and Java runtimes, demonstrating end-to-end MeshJob event-draining workflows. Each language pair includes a provider agent that long-polls for work/stop events and a consumer agent that posts events and subscribes to event streams. README documentation is updated to describe the new Phase 2 flow and revised feature gaps.

Changes

Event-Aware Job Examples (v2.2)

Layer / File(s)	Summary
Phase 2 event-injection documentation examples/jobs*/README.md	All three language-specific README files are updated with new Phase 2 sections describing the event-aware agents, quick-start commands, expected JSON output, and revised "What's NOT in v2.2 yet" limitations.
Python event-aware provider examples/jobs/event-aware-provider/main.py	FastMCP agent with event_aware_long_task tool that long-polls for work and stop events, increments a counter on each work event, updates progress, and completes with a result when stop arrives.
Python event-aware consumer examples/jobs/event-aware-consumer/main.py	FastMCP agent with drive_event_aware_task tool that submits a job, concurrently subscribes to work events via mesh.jobs.subscribe_events, posts three work events and a stop event, and collects the terminal result.
TypeScript event-aware provider examples/jobs-ts/event-aware-provider-ts/*	FastMCP/Node.js agent (package.json, tsconfig.json, src/index.ts) with event_aware_long_task tool that long-polls controller.recvEvent, processes work events, and completes on stop.
TypeScript event-aware consumer examples/jobs-ts/event-aware-consumer-ts/*	FastMCP/Node.js agent (package.json, tsconfig.json, src/index.ts) with drive_event_aware_task tool that submits a job, subscribes to work events via mesh.jobs.subscribeEvents, posts work and stop events, and awaits the result.
Java event-aware provider examples/jobs-java/event-aware-provider-java/*	Spring Boot agent (pom.xml, application.yml, Java source) with eventAwareLongTask MeshTool that long-polls controller.recvEvent, accumulates work events, and completes on stop.
Java event-aware consumer examples/jobs-java/event-aware-consumer-java/*	Spring Boot agent (pom.xml, application.yml, Java source) with driveEventAwareTask MeshTool that submits a job, subscribes via EventSubscription, posts events via MeshJobs.postEvent, and awaits the result with timeout.

Sequence Diagram

sequenceDiagram
  participant Consumer as Consumer Agent
  participant Registry as Registry
  participant Provider as Provider Agent
  Consumer->>Registry: submit event_aware_long_task job
  Consumer->>Consumer: start event subscription (work events)
  Consumer->>Provider: post work event
  Provider->>Provider: recvEvent (work)
  Provider->>Provider: increment counter
  Consumer->>Provider: post work event
  Provider->>Provider: recvEvent (work)
  Consumer->>Provider: post work event
  Provider->>Provider: recvEvent (work)
  Consumer->>Provider: post stop event
  Provider->>Provider: recvEvent (stop)
  Provider->>Provider: complete job with result
  Consumer->>Consumer: await job result

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• dhyansraj/mcp-mesh#1051: Java SDK event-injection APIs (MeshJobs.subscribeEvents, EventSubscription) that the new Java examples depend on.
• dhyansraj/mcp-mesh#1049: TypeScript SDK mesh.jobs.subscribeEvents implementation that the new TypeScript consumer example calls.
• dhyansraj/mcp-mesh#1053: Conceptual documentation for event-injection and stream-subscription APIs referenced by the new README sections.

Poem

🐰 Three runtimes, one dance—
Provider waits for the call,
Consumer posts events,
They meet in the hall.
Phase 2 jobs now flow! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding v2.2 event-injection demos across Python, TypeScript, and Java job examples.
Linked Issues check	✅ Passed	All coding requirements from issue #1057 are met: six new agents added (event-aware-provider and event-aware-consumer for Python, TypeScript, Java), demonstrating event-injection API (recv/post/subscribe), following Phase 1 conventions, and README updates completed.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the PR objectives: new example agents, configuration files, and README updates documenting v2.2 event-injection. No extraneous modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/1057-examples-event-injection

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}