@mcpmesh/sdk 2.1.0 → 2.2.4

package/dist/jobs.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Public `mesh.jobs` namespace — convenience helpers for the MeshJob
+ * event-injection primitive (Phase 1, MeshJob substrate; event-channel
+ * extension landed in v2.2).
+ *
+ * The primary surfaces are:
+ *
+ *   - {@link postEvent} — fire-and-forget helper to push an event into a
+ *     running job by id, without holding a `JobProxy` reference. Intended
+ *     for MCP tool bodies that receive a `jobId` in their request payload
+ *     (e.g. a "submit_user_input" tool exposed by an orchestrator agent).
+ *
+ *   - {@link JobNotFoundError} / {@link JobTerminalError} — typed `Error`
+ *     subclasses translated from the Rust core's `JobError` variants. The
+ *     napi binding surfaces all `JobError` variants as a plain `Error`
+ *     today (see `src/runtime/core/src/jobs_napi.rs::job_error_to_napi`),
+ *     so we re-classify on the TypeScript side via stable
+ *     error-message substrings ("job is terminal" / "job not found").
+ *
+ * The `JobController` / `JobProxy` napi-rs classes from `@mcpmesh/core`
+ * already expose `recvEvent` / `sendEvent` methods directly — application
+ * code calls them via the `MeshJob`-typed parameter the framework
+ * injects. This module just adds the helper + error classes around that
+ * surface, mirroring Python's `mesh.jobs.post_event` API one-for-one.
+ */
+import { JobProxy } from "@mcpmesh/core";
+/**
+ * Event posted into a running job's event log. Matches the OpenAPI
+ * `JobEvent` schema field-for-field (and the Rust `JobEvent` /
+ * Python `job_event_to_pydict` shape). Returned by `JobController.recvEvent`.
+ */
+export interface JobEvent {
+    /** Server-assigned job UUID this event belongs to. */
+    job_id: string;
+    /** Per-job monotonic sequence number assigned by the registry. */
+    seq: number;
+    /** User-supplied event type tag (e.g. "signal", "user_input"). */
+    type: string;
+    /** Arbitrary JSON-shaped payload carried with the event (or `null`). */
+    payload: unknown;
+    /** W3C trace context propagated by the poster (or `null`). */
+    trace_context: unknown;
+    /** Identifier of the agent that posted the event (or `null`). */
+    posted_by: string | null;
+    /** Unix epoch seconds at which the registry created the row. */
+    created_at: number;
+}
+/**
+ * Receipt returned by `JobProxy.sendEvent` / `postEvent`. Matches the
+ * OpenAPI `JobEventPostResponse` schema field-for-field.
+ */
+export interface JobEventReceipt {
+    /** Server-assigned job UUID the event was posted into. */
+    job_id: string;
+    /** Per-job monotonic sequence number assigned by the registry. */
+    seq: number;
+    /** Unix epoch seconds at which the registry created the row. */
+    created_at: number;
+}
+/**
+ * The targeted job does not exist (or has been swept) in the registry.
+ *
+ * Translated from the Rust `JobError::Other(BackendError::NotFound)`
+ * path (`GET/POST /jobs/{id}/events` → HTTP 404).
+ */
+export declare class JobNotFoundError extends Error {
+    readonly name = "JobNotFoundError";
+    constructor(message: string);
+}
+/**
+ * The targeted job is in a terminal state (completed / failed /
+ * cancelled) and no longer accepts events.
+ *
+ * Translated from the Rust `JobError::JobTerminal` variant — the
+ * registry returns HTTP 409 once the job row is terminal and the Rust
+ * layer maps that to `JobTerminal`.
+ */
+export declare class JobTerminalError extends Error {
+    readonly name = "JobTerminalError";
+    constructor(message: string);
+}
+/**
+ * Re-classify a generic `Error` raised by the napi layer into one of the
+ * typed subclasses, if the message matches. Returns the original error
+ * (or a typed clone) — callers should `throw` the returned value.
+ *
+ * Exported so tests can exercise the substring contract without a real
+ * napi failure path.
+ */
+export declare function translateJobError(err: unknown): unknown;
+/**
+ * Return a process-cached `JobProxy` for the given
+ * `(registryUrl, jobId)` pair, constructing one on first miss.
+ *
+ * Cache is a bounded LRU: hits bump the entry to the most-recent end of
+ * the insertion-order map, misses on a full cache evict the
+ * least-recent entry before inserting. Exported only for tests; not
+ * part of the public API.
+ */
+export declare function _getOrCreateProxy(registryUrl: string, jobId: string): JobProxy;
+/**
+ * Clear the JobProxy cache. Exposed for tests — not part of the public
+ * API. Equivalent to dropping all entries; the underlying napi handles
+ * are released when JS GC runs.
+ */
+export declare function _clearProxyCache(): void;
+/**
+ * Post an event to a running job by ID.
+ *
+ * Convenience helper for tool bodies that hold a `jobId` (e.g. from a
+ * request body, a token lookup, or a stashed reference) but do NOT
+ * have a `JobProxy` reference in scope. Constructs (or reuses, via the
+ * LRU cache) a `JobProxy` bound to the current agent's registry URL
+ * and forwards the call.
+ *
+ * Mirrors Python's `mesh.jobs.post_event` API one-for-one.
+ *
+ * @param jobId - Target job's server-assigned id.
+ * @param eventType - Event type tag (e.g. `"extend_deadline"`,
+ *   `"user_input"`, or any user-defined string). The running handler
+ *   can filter via `await job.recvEvent(["..."])`.
+ * @param payload - Optional JSON-serializable payload carried with the
+ *   event. `undefined`/`null` is normalized to an empty object before
+ *   forwarding — the Rust layer accepts either.
+ * @returns Receipt `{ job_id, seq, created_at }`. `seq` is the
+ *   server-assigned sequence number useful for stitching follow-up
+ *   `recvEvent` calls.
+ *
+ * @throws {@link JobNotFoundError} If the registry doesn't know the
+ *   job (sweep already removed it, or wrong id).
+ * @throws {@link JobTerminalError} If the job has already reached a
+ *   terminal state — no more events accepted.
+ * @throws Error For transport errors (registry unreachable, 5xx after
+ *   retries, malformed payload, etc.) — the underlying error message
+ *   is preserved.
+ *
+ * @example
+ * Inside an MCP tool body that holds a job id:
+ * ```ts
+ * agent.addTool({
+ *   name: "submit_user_input",
+ *   capability: "submit_user_input",
+ *   parameters: z.object({ jobId: z.string(), text: z.string() }),
+ *   execute: async ({ jobId, text }) => {
+ *     const receipt = await mesh.jobs.postEvent(
+ *       jobId,
+ *       "user_input",
+ *       { text },
+ *     );
+ *     return { posted_seq: receipt.seq };
+ *   },
+ * });
+ * ```
+ */
+export declare function postEvent(jobId: string, eventType: string, payload?: unknown): Promise<JobEventReceipt>;
+/**
+ * Options for {@link subscribeEvents}. All fields are optional —
+ * defaults match Python's `mesh.jobs.subscribe_events` keyword args.
+ */
+export interface SubscribeEventsOptions {
+    /**
+     * Optional event-type filter applied server-side. Only events whose
+     * `type` matches one of these is yielded. Omit for all types.
+     */
+    types?: string[];
+    /**
+     * Initial cursor (default `0` ≡ from the beginning of the event log).
+     * Pass a higher value to skip historical events. Accepts both
+     * `number` and `bigint` for callers stitching from an `i64`-sourced
+     * cursor.
+     */
+    after?: number | bigint;
+    /**
+     * Long-poll wait budget per registry call (in seconds). Default `30`.
+     * Capped at `60` by the registry. Pass `null` to skip the long-poll
+     * entirely (single immediate read; rarely needed — tight-poll callers
+     * should pass `0` instead).
+     */
+    longPollSecs?: number | null;
+}
+/**
+ * Subscribe to events posted to a running job by ID.
+ *
+ * Long-lived async iterator. Each call manages its own cursor —
+ * multiple subscribers can observe the same job's events independently
+ * without affecting the producer's `recvEvent` consumption (the
+ * producer's cursor is per-controller; this observer's cursor is
+ * per-call).
+ *
+ * The iterator runs indefinitely until the caller breaks out of the
+ * `for await` loop or the underlying registry returns
+ * {@link JobNotFoundError}. There is no automatic terminal-state
+ * detection — use a synthetic event type (e.g. `{ type: "ended" }`)
+ * posted by your application to signal iteration end.
+ *
+ * Mirrors Python's `mesh.jobs.subscribe_events` one-for-one.
+ *
+ * @param jobId - Target job's server-assigned id.
+ * @param options - Optional filter / cursor / long-poll knobs.
+ * @yields Event objects: `{ seq, type, payload, trace_context,
+ *   posted_by, created_at, job_id }`.
+ *
+ * @throws {@link JobNotFoundError} If the job has been reaped from the
+ *   registry (404 on the `GET /jobs/{id}/events` endpoint).
+ * @throws Error For transport errors (registry unreachable, 5xx after
+ *   retries, malformed payload, etc.) — the underlying error message
+ *   is preserved.
+ *
+ * @example
+ * Mirror events from a running job into a downstream system:
+ * ```ts
+ * for await (const event of mesh.jobs.subscribeEvents(jobId, {
+ *   types: ["progress", "result"],
+ * })) {
+ *   await downstream.publish(event);
+ *   if (event.type === "result") break; // caller-defined termination
+ * }
+ * ```
+ */
+export declare function subscribeEvents(jobId: string, options?: SubscribeEventsOptions): AsyncGenerator<JobEvent, void, unknown>;
+//# sourceMappingURL=jobs.d.ts.map

package/dist/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../src/jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAC;IACvB,iEAAiE;IACjE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB;AAoBD;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,sBAAsB;gBACvB,OAAO,EAAE,MAAM;CAG5B;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,sBAAsB;gBACvB,OAAO,EAAE,MAAM;CAG5B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAwBvD;AAmCD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAuB9E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AA6BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,eAAe,CAAC,CAc1B;AAMD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAuB,eAAe,CACpC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,sBAA2B,GACnC,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAmEzC"}

package/dist/jobs.js

@@ -0,0 +1,363 @@
+/**
+ * Public `mesh.jobs` namespace — convenience helpers for the MeshJob
+ * event-injection primitive (Phase 1, MeshJob substrate; event-channel
+ * extension landed in v2.2).
+ *
+ * The primary surfaces are:
+ *
+ *   - {@link postEvent} — fire-and-forget helper to push an event into a
+ *     running job by id, without holding a `JobProxy` reference. Intended
+ *     for MCP tool bodies that receive a `jobId` in their request payload
+ *     (e.g. a "submit_user_input" tool exposed by an orchestrator agent).
+ *
+ *   - {@link JobNotFoundError} / {@link JobTerminalError} — typed `Error`
+ *     subclasses translated from the Rust core's `JobError` variants. The
+ *     napi binding surfaces all `JobError` variants as a plain `Error`
+ *     today (see `src/runtime/core/src/jobs_napi.rs::job_error_to_napi`),
+ *     so we re-classify on the TypeScript side via stable
+ *     error-message substrings ("job is terminal" / "job not found").
+ *
+ * The `JobController` / `JobProxy` napi-rs classes from `@mcpmesh/core`
+ * already expose `recvEvent` / `sendEvent` methods directly — application
+ * code calls them via the `MeshJob`-typed parameter the framework
+ * injects. This module just adds the helper + error classes around that
+ * surface, mirroring Python's `mesh.jobs.post_event` API one-for-one.
+ */
+import { JobProxy } from "@mcpmesh/core";
+// ---------------------------------------------------------------------------
+// Typed error classes
+// ---------------------------------------------------------------------------
+//
+// The Rust core's `JobError::Other(BackendError::NotFound)` and
+// `JobError::JobTerminal` variants currently surface as plain `Error` from
+// the napi layer (see `src/runtime/core/src/jobs_napi.rs::job_error_to_napi`).
+// Until the napi binding switches to a custom exception type, we
+// re-classify on the TypeScript side via stable substrings emitted by the
+// NAPI wrapper's explicit error remap in
+// `src/runtime/core/src/jobs_napi.rs` (`job_error_to_napi` at lines
+// 85-102, specifically the `JobTerminal` arm at 97-99). The wrapper
+// deliberately remaps `JobError::Display` to a stable SDK-facing format
+// — do NOT collapse this remap thinking it just passes core's Display
+// through; the substring contract here depends on it. Both classes
+// derive from `Error` so existing `catch (Error)` handlers continue to
+// catch them.
+/**
+ * The targeted job does not exist (or has been swept) in the registry.
+ *
+ * Translated from the Rust `JobError::Other(BackendError::NotFound)`
+ * path (`GET/POST /jobs/{id}/events` → HTTP 404).
+ */
+export class JobNotFoundError extends Error {
+    name = "JobNotFoundError";
+    constructor(message) {
+        super(message);
+    }
+}
+/**
+ * The targeted job is in a terminal state (completed / failed /
+ * cancelled) and no longer accepts events.
+ *
+ * Translated from the Rust `JobError::JobTerminal` variant — the
+ * registry returns HTTP 409 once the job row is terminal and the Rust
+ * layer maps that to `JobTerminal`.
+ */
+export class JobTerminalError extends Error {
+    name = "JobTerminalError";
+    constructor(message) {
+        super(message);
+    }
+}
+/**
+ * Re-classify a generic `Error` raised by the napi layer into one of the
+ * typed subclasses, if the message matches. Returns the original error
+ * (or a typed clone) — callers should `throw` the returned value.
+ *
+ * Exported so tests can exercise the substring contract without a real
+ * napi failure path.
+ */
+export function translateJobError(err) {
+    if (!(err instanceof Error) ||
+        err instanceof JobNotFoundError ||
+        err instanceof JobTerminalError) {
+        return err;
+    }
+    const msg = err.message ?? "";
+    const msgLower = msg.toLowerCase();
+    // Order matters: "job is terminal" is the JobTerminal variant's Display
+    // prefix (see jobs_napi.rs::job_error_to_napi); "job not found" is
+    // BackendError::NotFound's Display prefix.
+    if (msgLower.includes("job is terminal")) {
+        const typed = new JobTerminalError(msg);
+        typed.cause = err;
+        return typed;
+    }
+    if (msgLower.includes("job not found")) {
+        const typed = new JobNotFoundError(msg);
+        typed.cause = err;
+        return typed;
+    }
+    return err;
+}
+// ---------------------------------------------------------------------------
+// JobProxy cache (mirror of Python's `_get_or_create_proxy`)
+// ---------------------------------------------------------------------------
+//
+// `postEvent` used to construct a fresh `JobProxy` on every call. Each
+// proxy wraps a Rust `reqwest::Client` with its own connection pool, so a
+// steady-state sender that fires off `postEvent` in a hot loop would
+// force a fresh TCP/TLS handshake against the registry on every call.
+// Cache by `(registryUrl, jobId)` for the process lifetime; the cache
+// key is invalidated naturally when a different registry URL or job id is
+// used.
+//
+// Bounded LRU eviction: long-lived senders that post events to many
+// distinct jobs (e.g. a router fanning out across thousands of jobs) would
+// otherwise grow the cache without bound. `Map` preserves insertion
+// order; deleting + re-inserting on hit and shifting off the first key on
+// overflow gives us O(1) LRU semantics. The Rust `JobProxy` does not
+// expose an explicit `close()` over napi — eviction just drops the Map
+// entry and lets JS GC release the wrapped `reqwest::Client` connection
+// pool when no JS references remain.
+const _PROXY_CACHE_DEFAULT_MAX = 256;
+function proxyCacheMax() {
+    const raw = process.env.MCP_MESH_JOBPROXY_CACHE_MAX;
+    if (!raw)
+        return _PROXY_CACHE_DEFAULT_MAX;
+    const value = parseInt(raw, 10);
+    if (!Number.isFinite(value) || value <= 0)
+        return _PROXY_CACHE_DEFAULT_MAX;
+    return value;
+}
+const _proxyCache = new Map();
+/**
+ * Return a process-cached `JobProxy` for the given
+ * `(registryUrl, jobId)` pair, constructing one on first miss.
+ *
+ * Cache is a bounded LRU: hits bump the entry to the most-recent end of
+ * the insertion-order map, misses on a full cache evict the
+ * least-recent entry before inserting. Exported only for tests; not
+ * part of the public API.
+ */
+export function _getOrCreateProxy(registryUrl, jobId) {
+    const key = `${registryUrl} ${jobId}`;
+    const existing = _proxyCache.get(key);
+    if (existing !== undefined) {
+        // Bump to most-recent end of insertion order: delete + re-set.
+        _proxyCache.delete(key);
+        _proxyCache.set(key, existing);
+        return existing;
+    }
+    const proxy = new JobProxy(jobId, registryUrl);
+    const maxSize = proxyCacheMax();
+    while (_proxyCache.size >= maxSize) {
+        // Evict LRU = first entry in insertion order. The Map iterator yields
+        // keys in insertion order; pull the oldest and delete it. Dropping
+        // the entry releases our reference to the JobProxy; JS GC reclaims
+        // the wrapped reqwest client (and its connection pool) when no other
+        // refs exist.
+        const oldest = _proxyCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        _proxyCache.delete(oldest);
+    }
+    _proxyCache.set(key, proxy);
+    return proxy;
+}
+/**
+ * Clear the JobProxy cache. Exposed for tests — not part of the public
+ * API. Equivalent to dropping all entries; the underlying napi handles
+ * are released when JS GC runs.
+ */
+export function _clearProxyCache() {
+    _proxyCache.clear();
+}
+// ---------------------------------------------------------------------------
+// postEvent convenience helper
+// ---------------------------------------------------------------------------
+/**
+ * Discover the registry base URL the running agent is bound to.
+ *
+ * Mirrors Python's `mesh.jobs._resolve_registry_url`: the canonical
+ * source is the `MCP_MESH_REGISTRY_URL` environment variable. The
+ * configuration pipeline writes this on agent startup and every
+ * job-substrate code path reads it.
+ *
+ * @throws Error if the variable isn't set — the caller can't post an
+ *   event without knowing which registry to target.
+ */
+function resolveRegistryUrl() {
+    const url = process.env.MCP_MESH_REGISTRY_URL;
+    if (!url) {
+        throw new Error("mesh.jobs.postEvent: MCP_MESH_REGISTRY_URL is not set; " +
+            "cannot resolve registry base URL. Ensure the calling " +
+            "process is running inside a mesh agent.");
+    }
+    return url;
+}
+/**
+ * Post an event to a running job by ID.
+ *
+ * Convenience helper for tool bodies that hold a `jobId` (e.g. from a
+ * request body, a token lookup, or a stashed reference) but do NOT
+ * have a `JobProxy` reference in scope. Constructs (or reuses, via the
+ * LRU cache) a `JobProxy` bound to the current agent's registry URL
+ * and forwards the call.
+ *
+ * Mirrors Python's `mesh.jobs.post_event` API one-for-one.
+ *
+ * @param jobId - Target job's server-assigned id.
+ * @param eventType - Event type tag (e.g. `"extend_deadline"`,
+ *   `"user_input"`, or any user-defined string). The running handler
+ *   can filter via `await job.recvEvent(["..."])`.
+ * @param payload - Optional JSON-serializable payload carried with the
+ *   event. `undefined`/`null` is normalized to an empty object before
+ *   forwarding — the Rust layer accepts either.
+ * @returns Receipt `{ job_id, seq, created_at }`. `seq` is the
+ *   server-assigned sequence number useful for stitching follow-up
+ *   `recvEvent` calls.
+ *
+ * @throws {@link JobNotFoundError} If the registry doesn't know the
+ *   job (sweep already removed it, or wrong id).
+ * @throws {@link JobTerminalError} If the job has already reached a
+ *   terminal state — no more events accepted.
+ * @throws Error For transport errors (registry unreachable, 5xx after
+ *   retries, malformed payload, etc.) — the underlying error message
+ *   is preserved.
+ *
+ * @example
+ * Inside an MCP tool body that holds a job id:
+ * ```ts
+ * agent.addTool({
+ *   name: "submit_user_input",
+ *   capability: "submit_user_input",
+ *   parameters: z.object({ jobId: z.string(), text: z.string() }),
+ *   execute: async ({ jobId, text }) => {
+ *     const receipt = await mesh.jobs.postEvent(
+ *       jobId,
+ *       "user_input",
+ *       { text },
+ *     );
+ *     return { posted_seq: receipt.seq };
+ *   },
+ * });
+ * ```
+ */
+export async function postEvent(jobId, eventType, payload) {
+    const registryUrl = resolveRegistryUrl();
+    const proxy = _getOrCreateProxy(registryUrl, jobId);
+    const safePayload = payload !== undefined && payload !== null ? payload : {};
+    try {
+        const receipt = (await proxy.sendEvent(eventType, safePayload));
+        return receipt;
+    }
+    catch (err) {
+        const translated = translateJobError(err);
+        if (translated !== err) {
+            throw translated;
+        }
+        throw err;
+    }
+}
+/**
+ * Subscribe to events posted to a running job by ID.
+ *
+ * Long-lived async iterator. Each call manages its own cursor —
+ * multiple subscribers can observe the same job's events independently
+ * without affecting the producer's `recvEvent` consumption (the
+ * producer's cursor is per-controller; this observer's cursor is
+ * per-call).
+ *
+ * The iterator runs indefinitely until the caller breaks out of the
+ * `for await` loop or the underlying registry returns
+ * {@link JobNotFoundError}. There is no automatic terminal-state
+ * detection — use a synthetic event type (e.g. `{ type: "ended" }`)
+ * posted by your application to signal iteration end.
+ *
+ * Mirrors Python's `mesh.jobs.subscribe_events` one-for-one.
+ *
+ * @param jobId - Target job's server-assigned id.
+ * @param options - Optional filter / cursor / long-poll knobs.
+ * @yields Event objects: `{ seq, type, payload, trace_context,
+ *   posted_by, created_at, job_id }`.
+ *
+ * @throws {@link JobNotFoundError} If the job has been reaped from the
+ *   registry (404 on the `GET /jobs/{id}/events` endpoint).
+ * @throws Error For transport errors (registry unreachable, 5xx after
+ *   retries, malformed payload, etc.) — the underlying error message
+ *   is preserved.
+ *
+ * @example
+ * Mirror events from a running job into a downstream system:
+ * ```ts
+ * for await (const event of mesh.jobs.subscribeEvents(jobId, {
+ *   types: ["progress", "result"],
+ * })) {
+ *   await downstream.publish(event);
+ *   if (event.type === "result") break; // caller-defined termination
+ * }
+ * ```
+ */
+export async function* subscribeEvents(jobId, options = {}) {
+    const { types, after = 0, longPollSecs = 30 } = options;
+    const registryUrl = resolveRegistryUrl();
+    const proxy = _getOrCreateProxy(registryUrl, jobId);
+    // Cursor as `number` because the napi binding types `after` as
+    // `number` (i64 → JS Number). Accept `bigint` in the input options
+    // for callers stitching from another i64 source, but coerce down to
+    // `number` for the binding boundary — guarding the overflow case so
+    // an out-of-range i64 cursor surfaces as an explicit RangeError
+    // rather than silently truncating.
+    let cursor;
+    if (typeof after === "bigint") {
+        if (after > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new RangeError(`subscribeEvents: 'after' cursor exceeds Number.MAX_SAFE_INTEGER (${Number.MAX_SAFE_INTEGER}); per-job seq overflowed JS Number range. Got: ${after}`);
+        }
+        cursor = Number(after);
+    }
+    else {
+        cursor = after ?? 0;
+    }
+    // The binding type signature is `number | null | undefined`; the
+    // Python sibling accepts `None` for "single immediate read", and we
+    // forward that through verbatim.
+    const wait = longPollSecs;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        let result;
+        try {
+            result = (await proxy.listEvents(cursor, types, wait));
+        }
+        catch (err) {
+            const translated = translateJobError(err);
+            if (translated !== err) {
+                throw translated;
+            }
+            throw err;
+        }
+        const { events, nextAfter } = result;
+        for (const event of events) {
+            const seq = event.seq;
+            // Reject booleans explicitly: `typeof true === "boolean"` but
+            // JS often widens bool↔number; the registry contract is integer
+            // seqs, so a bool here is a wire-level malformed payload.
+            if (typeof seq === "boolean") {
+                throw new Error(`subscribeEvents: registry returned event with boolean 'seq': ${JSON.stringify(event)}`);
+            }
+            if (typeof seq !== "number" && typeof seq !== "bigint") {
+                throw new Error(`subscribeEvents: registry returned event without integer 'seq': ${JSON.stringify(event)}`);
+            }
+            const seqNum = typeof seq === "bigint" ? Number(seq) : seq;
+            if (seqNum > cursor)
+                cursor = seqNum;
+            // listEvents returns ascending-seq; cursor advance before yield
+            // ensures correctness across consumer cancellation.
+            yield event;
+        }
+        // Empty pages (or pages filtered by `types` server-side) still
+        // advance the cursor via the registry-supplied watermark, so
+        // subsequent polls don't re-scan the same filtered range.
+        if (nextAfter > cursor)
+            cursor = nextAfter;
+    }
+}
+//# sourceMappingURL=jobs.js.map

package/dist/jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.js","sourceRoot":"","sources":["../src/jobs.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -97,6 +97,18 @@ export interface MeshJob {
     updateProgress?(progress: number, message?: string): Promise<void>;
     complete?(result: unknown): Promise<void>;
     fail?(error: string): Promise<void>;
+    /**
+     * Wait for the next event posted into this job's event log.
+     *
+     * Returns the event object on arrival, `null` on timeout. Cursor is
+     * per-controller-instance (shared across `clone`s); a fresh
+     * controller for the same `jobId` replays from seq=0.
+     *
+     * Mirrors Python's `MeshJob.recv_event` (event-channel extension that
+     * shipped with v2.2 via PR #1041). Throws on `JobNotFound` /
+     * transport-layer failures; `timeoutSecs` rejects NaN/Infinity/negative.
+     */
+    recvEvent?(types?: string[], timeoutSecs?: number): Promise<import("./jobs.js").JobEvent | null>;
     submit?(payload?: Record<string, unknown>, options?: {
         maxDuration?: number;
         maxRetries?: number;
@@ -106,6 +118,15 @@ export interface MeshJob {
     wait?(timeoutSecs?: number): Promise<unknown>;
     status?(): Promise<Record<string, unknown>>;
     cancel?(reason?: string): Promise<void>;
+    /**
+     * Post an event into this job's event log. The running handler
+     * (inside the `task: true` job) will see it on its next `recvEvent`
+     * call — or wake immediately if it's currently long-polling.
+     *
+     * Mirrors Python's `MeshJob.send_event`. Throws `JobNotFoundError` /
+     * `JobTerminalError` for the corresponding registry error codes.
+     */
+    sendEvent?(eventType: string, payload?: unknown): Promise<import("./jobs.js").JobEventReceipt>;
 }
 /**
  * Dependency specification for mesh tool DI.