ts: mesh.jobs cancel/status/wait facades (TS parity for #1074)

[dhyansraj]

Summary

TypeScript parity for the Python mesh.jobs.cancel/status/wait facades shipped in #1077. Three new module-level async functions mirror the existing postEvent / subscribeEvents DDDI-clean pattern — callers with only a jobId no longer need to construct new JobProxy(jobId, registryUrl) and pass MCP_MESH_REGISTRY_URL explicitly.

export async function cancel(jobId: string, reason?: string): Promise<void>
export async function status(jobId: string): Promise<JobStatus>
export async function wait(jobId: string, timeoutSecs?: number): Promise<unknown>

Each: resolveRegistryUrl() → _getOrCreateProxy() (LRU-cached) → napi dispatch → translateJobError() for typed exception re-classification. Underlying napi binding (JsJobProxy.cancel/status/wait) was already exposed — no Rust changes.

JobStatus interface added alongside JobEvent / JobEventReceipt, exported from mesh.jobs. Fields mirror job_to_json in jobs_napi.rs: required fields typed T, Option<T> fields emitted as T | null (every key always present; only null-checks needed, no key-presence checks).

MeshJobsNamespace extended with cancel/status/wait alphabetically; public exports added.

Bonus generalization

resolveRegistryUrl's error message prefix generalized from "mesh.jobs.postEvent:" → "mesh.jobs:". Now accurate for all four facades — mirrors the same generalization the Python BLOCKER fix made in #1077.

Out of scope

• Java parity — separate PR per polyglot cadence (mirrors the MeshJob: consumer-pushed events into running jobs (recv_event/send_event) #1041 → ts: MeshJob event injection parity — recvEvent/sendEvent/postEvent #1043 → java: MeshJob event injection parity — recvEvent/sendEvent/postEvent #1045 trilogy pattern)
• TimeoutError typed class — wait() currently rejects with plain Error whose message starts with "timeout:". Substring contract pinned by test. Follow-up if needed.
• Caller authorization — design discussion at RFC: caller authorization on MeshJob lifecycle ops (cancel/status/post_event/subscribe) #1076

Review Notes

Independent review: 0 BLOCKER, 1 WARNING (addressed in amended commit), 5 INFOs (skipped as cosmetic).

• WARNING fixed: JobStatus interface used field?: T for nullable fields, but job_to_json always emits every field with Value::Null fallback. Tightened to field: T | null where appropriate, and field: T (no optional, no null) for fields the Rust binding emits unconditionally. Added one test pinning the every-key-present contract via Object.keys comparison.

INFOs skipped: Promise<unknown> vs Any (the stricter shape is correct), repeated try/catch boilerplate matches postEvent's style, empty toHaveBeenCalledWith() matcher is intentional for nullary calls, JSDoc null-vs-undefined nuance, doc table layout.

Test plan

• TS unit tests: 39 pass (was 23, +16 new — 15 facade tests + 1 contract test)
• uc22_meshjob_ts integration: 24/24 pass (222.8s)
• npm run build clean (no TS compile errors after type tightening)
• Vitest hoisting workaround confined to test file (import { cancel as cancelFacade }); SDK exports stay canonical — import { cancel } from "@mcpmesh/sdk" works unaliased for end users
• Cross-runtime scope: no edits to Python / Java / Rust / jobs_java.md / Python jobs.md variant
• Public-artifact framing: no naming downstream consumers; structural language throughout

Closes #1078

Summary by CodeRabbit

Release Notes

• New Features

  • Added job lifecycle management capabilities: cancel jobs, retrieve job status, and wait for job completion.
  • Enhanced job operation documentation with TypeScript implementation examples and per-runtime behavior specifications.

• Tests

  • Expanded test coverage for new job control operations and error handling scenarios.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds three new module-level async facades (cancel, status, wait) to the TypeScript mesh.jobs namespace, mirroring Python parity. Each resolves the registry URL internally and caches a JobProxy, eliminating the need for callers to pass MCP_MESH_REGISTRY_URL explicitly. Includes JobStatus type contract, comprehensive unit tests, API wiring, and user documentation.

Changes

TypeScript Job Lifecycle Facades

Layer / File(s)	Summary
JobStatus contract and facade implementations src/runtime/typescript/src/jobs.ts	New JobStatus interface models the job snapshot shape with required fields and explicit nullability for Rust Option<T> properties. Three new exported async functions (cancel, status, wait) resolve the registry URL, obtain a cached JobProxy, dispatch to N-API bindings, and translate errors via translateJobError. Error message prefix in resolveRegistryUrl() updated.
Public API surface and namespace wiring src/runtime/typescript/src/index.ts	mesh.jobs import expanded to include cancel, status, wait. MeshJobsNamespace interface and jobs constant extended with the three new methods. Public re-exports broadened to include the new functions and JobStatus type.
Comprehensive test infrastructure and facade tests src/runtime/typescript/src/__tests__/jobs.spec.ts	JobProxy mock expanded with cancel, status, wait method fields and corresponding mock functions. Test harness imports and resets new mocks. New end-to-end test suites validate registry URL resolution, argument forwarding (including null cases), error re-classification (JobNotFoundError, JobTerminalError, timeout Error with "timeout:" prefix), and proxy cache sharing across all four facades.
User-facing documentation for facades docs/concepts/jobs.md, src/core/cli/man/content/jobs_typescript.md	concepts/jobs.md operations table updated with explicit per-runtime return types for each facade; new TypeScript example section demonstrates abort_workflow, check_progress, run_to_completion. Language-specific timeout behavior documented: Python raises TimeoutError, TypeScript rejects with Error message starting with "timeout:". CLI man page adds lifecycle facades section describing mesh.jobs.cancel/status/wait calls, error behavior, and timeout handling.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• #1078: Primary objective issue—TypeScript parity for Python mesh.jobs cancel/status/wait facades.

Possibly related PRs

• dhyansraj/mcp-mesh#1043: Both PRs involve TypeScript job lifecycle plumbing; main PR adds the mesh.jobs.wait/cancel/status facades that depend on the same JobProxy.wait N-API behavior, error translation, and proxy caching infrastructure.

Poem

🐇 A rabbit hops through jobs with glee,
Now cancel, status, wait run free—
No proxy dance, no registry passed,
Just jobId calls, blazingly fast!
TypeScript and Python, now in sync,
Hop along, the façades wink. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'ts: mesh.jobs cancel/status/wait facades (TS parity for #1074)' clearly and specifically describes the main change: adding three TypeScript job control facades with reference to the Python parity issue.
Linked Issues check	✅ Passed	All coding requirements from #1078 are met: three facades (cancel/status/wait) added to mesh.jobs, JobStatus interface exported, MeshJobsNamespace extended, tests added, documentation updated, no Rust changes made.
Out of Scope Changes check	✅ Passed	All changes are in-scope: TypeScript implementations, documentation, and tests directly support the facade feature. Out-of-scope items (Java parity, caller authorization, typed TimeoutError) are correctly excluded.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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/1078-ts-mesh-jobs-facades

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/runtime/typescript/src/jobs.ts`:
- Line 84: The JobStatus.status union in jobs.ts currently omits "pending",
causing incorrect exhaustiveness and runtime assumptions; update the type
declaration for JobStatus.status to include "pending" (i.e., add "pending" to
the union alongside "working" | "input_required" | "completed" | "failed" |
"cancelled"), then scan for and update any switch statements, exhaustive
type-narrowing, or handling logic that assumes the old set (look for usages of
JobStatus.status, JobStatus, and any switch/case or exhaustive checks) to
account for the new "pending" state.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 524bed91-8b09-43be-825d-b052cedd36b1

📥 Commits

Reviewing files that changed from the base of the PR and between 01fb311 and dddd8e7.

📒 Files selected for processing (5)

• docs/concepts/jobs.md
• src/core/cli/man/content/jobs_typescript.md
• src/runtime/typescript/src/__tests__/jobs.spec.ts
• src/runtime/typescript/src/index.ts
• src/runtime/typescript/src/jobs.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add "pending" to the JobStatus.status union.

Line [84] excludes "pending", but this surface is documented as the full job-row snapshot. A submitted job can be observable in pending state before claim, so the current type can mislead exhaustive handling.

Proposed fix

-  status: "working" | "input_required" | "completed" | "failed" | "cancelled";
+  status:
+    | "pending"
+    | "working"
+    | "input_required"
+    | "completed"
+    | "failed"
+    | "cancelled";

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	status: "working" | "input_required" | "completed" | "failed" | "cancelled";
	status:
	| "pending"
	| "working"
	| "input_required"
	| "completed"
	| "failed"
	| "cancelled";

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/runtime/typescript/src/jobs.ts` at line 84, The JobStatus.status union in
jobs.ts currently omits "pending", causing incorrect exhaustiveness and runtime
assumptions; update the type declaration for JobStatus.status to include
"pending" (i.e., add "pending" to the union alongside "working" |
"input_required" | "completed" | "failed" | "cancelled"), then scan for and
update any switch statements, exhaustive type-narrowing, or handling logic that
assumes the old set (look for usages of JobStatus.status, JobStatus, and any
switch/case or exhaustive checks) to account for the new "pending" state.