service-bridge 1.6.0-dev.32 → 1.7.0-dev.34

package/README.md

@@ -73,7 +73,7 @@ Node.js SDK for [ServiceBridge](https://servicebridge.dev) — production-ready
 
 **Saga / distributed transactions** — DAG workflows with typed steps (`rpc`, `event`, `event_wait`, `sleep`, child workflow). Compensations and rollbacks via workflow step dependencies.
 
-**AI agent orchestration** — Stream LLM tokens via realtime run streams with replay. Orchestrate multi-step AI pipelines as workflows.
+**AI agent orchestration** — Stream LLM tokens via realtime trace streams with replay. Orchestrate multi-step AI pipelines as workflows.
 
 **Full-stack observability** — Every RPC call, event delivery, workflow step, and HTTP request traced automatically. One timeline, one dashboard. Prometheus metrics and Loki-compatible log API included.
 
@@ -236,7 +236,7 @@ Every step above — RPC, event publish, event delivery, workflow execution —
 - **Metrics** — Prometheus-compatible `/metrics` endpoint (30+ metric families)
 - **Logs** — structured log ingest with Loki-compatible query API
 - **Alerts** — runtime alerts for delivery failures, errors, and service health
-- **Dashboard** — realtime web UI for runs, events, workflows, jobs, DLQ, service map, and service keys
+- **Dashboard** — realtime web UI for traces, events, workflows, jobs, DLQ, service map, and service keys
 
 ---
 
@@ -262,7 +262,7 @@ Every step above — RPC, event publish, event delivery, workflow execution —
 ### Cross-SDK parity notes
 
 ServiceBridge keeps the core API shape consistent across Node.js, Go, and Python:
-constructor, RPC, events, jobs, workflows, `runWorkflow`, streams, serve/stop, and `ServiceBridgeError`.
+constructor, RPC, events, jobs, workflows, `executeWorkflow`, streams, serve/stop, and `ServiceBridgeError`.
 
 Constructor-level defaults for `timeout`, `retries`, and `retryDelay` are available
 across all three SDKs. Parity differences are naming-only (language idioms):
@@ -326,6 +326,15 @@ rpc<T = unknown>(fn: string, payload?: unknown, opts?: RpcOpts): Promise<T>
 
 Calls a registered RPC handler on another service. Direct gRPC path, no proxy.
 
+**Function name formats** — `fn` accepts two formats:
+
+| Format | Example | When to use |
+|---|---|---|
+| Plain name | `"charge"` | Function name is globally unique across all services. Resolved automatically via service discovery. |
+| Canonical name | `"payments/charge"` | Multiple services expose a function with the same plain name, or you want to be explicit about the target service. |
+
+Both formats are interchangeable when the name is unique globally. Canonical format is recommended in production for clarity and to avoid ambiguity as your service count grows.
+
 `RpcOpts`:
 
 | Option | Type | Description |
@@ -338,6 +347,10 @@ Calls a registered RPC handler on another service. Direct gRPC path, no proxy.
 | `mode` | `"direct" \| "proxy"` | Transport mode. `"direct"` (default) connects directly to the worker. `"proxy"` routes through the control plane when direct connection is unavailable. |
 
 ```ts
+// plain name — works when "get" is unique across services
+const user = await sb.rpc<{ id: string; name: string }>("get", { id: "u_1" });
+
+// canonical name — explicit service target, always unambiguous
 const user = await sb.rpc<{ id: string; name: string }>("users/get", { id: "u_1" }, {
   timeout: 5000,
   retries: 2,
@@ -378,6 +391,16 @@ await sb.event("orders.created", { orderId: "ord_42" }, {
 
 ---
 
+### `publishEvent(topic, payload?, opts?)`
+
+```ts
+publishEvent(topic: string, payload?: unknown, opts?: PublishEventOpts): Promise<string>
+```
+
+Publishes an event via the established worker session stream. Requires an active worker session — call after `serve()`. Resolves with `messageId` once the server confirms with `publish_ack`. Times out after 30 s if no ack. Use `event()` when not serving (e.g. caller-only services); use `publishEvent()` from within a worker for lower-latency publishing over the existing session.
+
+---
+
 ### `job(target, opts)`
 
 ```ts
@@ -458,44 +481,44 @@ await sb.workflow("checkout.flow", steps, { stepTimeoutMs: 60_000 });
 
 ---
 
-### `runWorkflow(name, input?, opts?)`
+### `executeWorkflow(name, input?, opts?)`
 
 ```ts
-runWorkflow(name: string, input?: unknown, opts?: RunWorkflowOpts): Promise<{ runId: string; traceId: string }>
+executeWorkflow(name: string, input?: unknown, opts?: ExecuteWorkflowOpts): Promise<{ traceId: string; groupTraceId: string }>
 ```
 
-Starts a workflow run on demand. The workflow must be registered first via `workflow()`.
-An alternative to scheduling via `job(target, { via: "workflow" })` — triggers the run immediately.
+Starts a workflow execution on demand. The workflow must be registered first via `workflow()`.
+An alternative to scheduling via `job(target, { via: "workflow" })` — triggers the execution immediately.
 
 | Parameter | Type | Default | Description |
 |---|---|---|---|
 | `name` | `string` | required | Name of a previously registered workflow. |
 | `input` | `unknown` | `undefined` | Optional JSON-serializable input payload. |
 
-Returns `{ runId, traceId }`. Use `traceId` with `watchRun()` to observe execution in real time.
+Returns `{ traceId, groupTraceId }`. Use `traceId` with `watchTrace()` to observe execution in real time.
 
-`RunWorkflowOpts`:
+`ExecuteWorkflowOpts`:
 
 | Option | Type | Description |
 |---|---|---|
-| `traceId` | `string` | Override trace ID for this workflow run. |
+| `traceId` | `string` | Override trace ID for this workflow execution. |
 
 ```ts
-const { runId, traceId } = await sb.runWorkflow("user.onboarding", { userId: "u_123" });
+const { traceId, groupTraceId } = await sb.executeWorkflow("user.onboarding", { userId: "u_123" });
 ```
 
 ---
 
-### `cancelWorkflowRun(runId)`
+### `cancelWorkflow(traceId)`
 
 ```ts
-cancelWorkflowRun(runId: string): Promise<void>
+cancelWorkflow(traceId: string): Promise<void>
 ```
 
 Cancels a running workflow instance.
 
 ```ts
-await sb.cancelWorkflowRun("run_01HQ...XYZ");
+await sb.cancelWorkflow("trace_01HQ...XYZ");
 ```
 
 ---
@@ -542,7 +565,7 @@ sb.handleRpc("ai/generate", async (payload: { prompt: string }, ctx) => {
 
 | Method | Signature | Description |
 |---|---|---|
-| `write` | `write(data: unknown, key?: string): Promise<void>` | Append a real-time chunk to the run stream. |
+| `write` | `write(data: unknown, key?: string): Promise<void>` | Append a real-time chunk to the trace stream. |
 | `end` | `end(key?: string): Promise<void>` | No-op placeholder for API symmetry (lifecycle managed by runtime). |
 
 ---
@@ -584,7 +607,7 @@ a consumer, the delivery moves to DLQ with reason `delivery_ttl_exceeded`.
 - `ctx.retry(delayMs?)` — ask for redelivery with optional delay
 - `ctx.reject(reason)` — move to DLQ immediately, bypassing remaining retries
 - `ctx.refs` — metadata (`topic`, `groupName`, `messageId`, `attempt`, `headers`)
-- `ctx.stream.write(...)` — append real-time chunks to run stream
+- `ctx.stream.write(...)` — append real-time chunks to trace stream
 
 ```ts
 sb.handleEvent("orders.*", async (payload, ctx) => {
@@ -702,32 +725,32 @@ await sb.registerHttpEndpoint({
 
 ---
 
-### `watchRun(runId, opts?)`
+### `watchTrace(traceId, opts?)`
 
 ```ts
-watchRun(runId: string, opts?: WatchRunOpts): AsyncIterable<RunStreamEvent>
+watchTrace(traceId: string, opts?: WatchTraceOpts): AsyncIterable<TraceStreamEvent>
 ```
 
-Subscribes to a run stream with replay and live updates. `runId` is the stream
-identifier used by `ctx.stream.write(...)` (typically a trace ID).
+Subscribes to a trace stream with replay and live updates. `traceId` is the stream
+identifier used by `ctx.stream.write(...)`.
 
-`WatchRunOpts`:
+`WatchTraceOpts`:
 
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `key` | `string` | `""` | Stream key filter (`""` = all keys). |
 | `fromSequence` | `number` | `0` | Replay from sequence cursor. |
 
-`RunStreamEvent`:
+`TraceStreamEvent`:
 
 | Field | Type | Description |
 |---|---|---|
-| `type` | `"chunk" \| "run_complete"` | Event kind. |
-| `runId` | `string` | Stream/run identifier being watched. |
+| `type` | `"chunk" \| "trace_complete"` | Event kind. |
+| `traceId` | `string` | Trace identifier being watched. |
 | `key` | `string` | Stream lane key. |
 | `sequence` | `number` | Monotonic sequence number. |
 | `data` | `unknown` | JSON-decoded chunk payload. |
-| `runStatus` | `string \| undefined` | Final status on `run_complete`. |
+| `traceStatus` | `string \| undefined` | Final status on `trace_complete`. |
 
 Behavior:
 
@@ -737,11 +760,11 @@ Behavior:
 - Enforces internal queue limit `256`; overflow is fatal (consumer must drain promptly).
 
 ```ts
-for await (const evt of sb.watchRun(runId, { key: "output", fromSequence: 0 })) {
+for await (const evt of sb.watchTrace(traceId, { key: "output", fromSequence: 0 })) {
   if (evt.type === "chunk") {
     process.stdout.write(String((evt.data as { token?: string }).token ?? ""));
   }
-  if (evt.type === "run_complete") break;
+  if (evt.type === "trace_complete") break;
 }
 ```
 
@@ -766,18 +789,18 @@ if (tc) {
 }
 ```
 
-#### `runWithTraceContext(ctx, fn)`
+#### `withTraceContext(ctx, fn)`
 
 ```ts
-runWithTraceContext<T>(ctx: { traceId: string; spanId: string }, fn: () => T): T
+withTraceContext<T>(ctx: { traceId: string; spanId: string }, fn: () => T): T
 ```
 
 Runs a function inside an explicit trace context.
 
 ```ts
-import { runWithTraceContext } from "service-bridge";
+import { withTraceContext } from "service-bridge";
 
-runWithTraceContext({ traceId: "trace-1", spanId: "span-1" }, async () => {
+withTraceContext({ traceId: "trace-1", spanId: "span-1" }, async () => {
   await sb.event("audit.log", { action: "user.login" });
 });
 ```

package/dist/express.js

@@ -1,5 +1,5 @@
 // http/src/express.ts
-import { runWithTraceContext } from "service-bridge";
+import { withTraceContext } from "service-bridge";
 
 // http/src/trace.ts
 function parseTraceparent(traceparent) {
@@ -86,7 +86,7 @@ function servicebridgeMiddleware(options) {
     };
     res.on("finish", onFinish);
     res.on("close", onFinish);
-    runWithTraceContext({ traceId: span.traceId, spanId: span.spanId }, () => {
+    withTraceContext({ traceId: span.traceId, spanId: span.spanId }, () => {
       next();
     });
   };

package/dist/fastify.js

@@ -1,5 +1,5 @@
 // http/src/fastify.ts
-import { runWithTraceContext } from "service-bridge";
+import { withTraceContext } from "service-bridge";
 
 // http/src/trace.ts
 function parseTraceparent(traceparent) {
@@ -111,7 +111,7 @@ function wrapHandler(handler) {
     const traceId = request.traceId;
     const spanId = request.spanId;
     if (traceId && spanId) {
-      return runWithTraceContext({ traceId, spanId }, () => handler(request, reply));
+      return withTraceContext({ traceId, spanId }, () => handler(request, reply));
     }
     return handler(request, reply);
   };

package/dist/index.js

@@ -336,7 +336,7 @@ var traceStorage = new AsyncLocalStorage;
 function getTraceContext() {
   return traceStorage.getStore();
 }
-function runWithTraceContext(ctx, fn) {
+function withTraceContext(ctx, fn) {
   return traceStorage.run(ctx, fn);
 }
 var servicebridgePackageDefinition = protoLoader.loadFileDescriptorSetFromBuffer(Buffer.from(DESCRIPTOR_SET_BASE64, "base64"), {
@@ -948,6 +948,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
   let workerSessionReconnectTimer = null;
   let workerSessionPingTimer = null;
   let workerSessionPositionTimer = null;
+  const pendingPublishAcks = new Map;
   let v2Session = null;
   let serveState = null;
   let heartbeatTimer = null;
@@ -1012,6 +1013,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
             parent_span_id: op.parentSpanId,
             fn: op.fn,
             span_type: op.spanType ?? "",
+            target_service: op.targetService ?? "",
             started_at: op.startedAt,
             input: op.inputBuf,
             attempt: op.attempt
@@ -1033,6 +1035,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
             parent_span_id: op.parentSpanId ?? "",
             fn: op.fn,
             span_type: op.spanType ?? "",
+            target_service: op.targetService ?? "",
             started_at: op.startedAt,
             duration_ms: op.durationMs,
             success: op.success,
@@ -1272,7 +1275,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
   function normalizeUnknownErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
   }
-  function reportCallStartAsync(traceId, spanId, parentSpanId, fn, startedAt, inputBuf, attempt, spanType) {
+  function reportCallStartAsync(traceId, spanId, parentSpanId, fn, startedAt, inputBuf, attempt, spanType, targetService) {
     if (!isOnline) {
       enqueueOffline({
         type: "reportCallStart",
@@ -1281,6 +1284,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
         parentSpanId,
         fn,
         spanType,
+        targetService,
         startedAt,
         inputBuf,
         attempt
@@ -1293,6 +1297,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       parentSpanId,
       fn,
       spanType,
+      targetService,
       startedAt,
       inputBuf,
       attempt
@@ -1310,6 +1315,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
           parentSpanId,
           fn,
           spanType,
+          targetService,
           startedAt,
           inputBuf,
           attempt
@@ -1319,7 +1325,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       reportSDKError("report-call-start", err);
     });
   }
-  function reportCallAsync(traceId, spanId, fn, startedAt, inputBuf, success, attempt, outputBuf, error = "", spanType, parentSpanId = "") {
+  function reportCallAsync(traceId, spanId, fn, startedAt, inputBuf, success, attempt, outputBuf, error = "", spanType, parentSpanId = "", targetService) {
     const durationMs = computeDurationMs(startedAt);
     if (!isOnline) {
       enqueueOffline({
@@ -1328,6 +1334,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
         spanId,
         fn,
         spanType,
+        targetService,
         parentSpanId,
         startedAt,
         durationMs,
@@ -1344,6 +1351,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       spanId,
       fn,
       spanType,
+      targetService,
       parentSpanId,
       startedAt,
       durationMs,
@@ -1365,6 +1373,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
           spanId,
           fn,
           spanType,
+          targetService,
           parentSpanId,
           startedAt,
           durationMs,
@@ -1482,7 +1491,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
         registrationFollowUpPromise = registrationSyncPromise.catch(() => {}).then(() => {
           registrationFollowUpPromise = null;
           if (serveState)
-            return reconcileRegistrations(reason + "-followup");
+            return reconcileRegistrations(`${reason}-followup`);
         });
       }
       return registrationFollowUpPromise;
@@ -1605,12 +1614,14 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       });
     }, delayMs);
   }
-  function makeStreamWriter(runId) {
+  function makeStreamWriter(traceId) {
     const append = (data, key = "default") => {
-      if (!isOnline || !runId)
+      if (!isOnline || !traceId)
         return Promise.resolve();
       const dataBuf = Buffer.from(JSON.stringify(data));
-      if (sessionSend({ stream_append: { run_id: runId, key, data: dataBuf } })) {
+      if (sessionSend({
+        stream_append: { trace_id: traceId, key, data: dataBuf }
+      })) {
         return Promise.resolve();
       }
       return Promise.resolve();
@@ -1628,7 +1639,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       return fnHandlers.get(name.slice(slash + 1));
     return;
   }
-  async function invokeRpcHandler(req, runId) {
+  async function invokeRpcHandler(req, traceId) {
     const entry = lookupFnHandler(req.function_name || "");
     if (!entry) {
       return {
@@ -1660,7 +1671,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       const rpcCtx = {
         traceId: traceCtx.traceId,
         spanId: traceCtx.spanId,
-        stream: makeStreamWriter(runId)
+        stream: makeStreamWriter(traceId)
       };
       try {
         const result = await entry.handler(parsed, rpcCtx);
@@ -1675,7 +1686,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       }
     });
   }
-  async function invokeEventHandler(req, runId) {
+  async function invokeEventHandler(req, traceId) {
     const groupName = typeof req.group_name === "string" ? req.group_name : undefined;
     const entry = groupName ? eventHandlers.get(groupName) : undefined;
     if (!entry) {
@@ -1714,7 +1725,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
         reject(reason) {
           rejectReason = reason || "rejected_by_consumer";
         },
-        stream: makeStreamWriter(runId)
+        stream: makeStreamWriter(traceId)
       };
       try {
         await entry.handler(parsed, ctx);
@@ -1749,8 +1760,8 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       });
       return;
     }
-    const runIdMeta = call.metadata.get("servicebridge-run-id");
-    const runId = typeof runIdMeta[0] === "string" ? runIdMeta[0] : "";
+    const traceIdMeta = call.metadata.get("servicebridge-trace-id");
+    const traceId = typeof traceIdMeta[0] === "string" ? traceIdMeta[0] : "";
     const workerTraceId = call.request.trace_id || crypto.randomUUID();
     const workerSpanId = call.request.span_id || crypto.randomUUID();
     const workerParentSpanId = call.request.parent_span_id || "";
@@ -1759,14 +1770,14 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
     const rpcStartedAt = Date.now();
     const rpcInputBuf = call.request.payload ?? Buffer.alloc(0);
     reportCallStartAsync(workerTraceId, workerSpanId, workerParentSpanId, fnName, rpcStartedAt, rpcInputBuf, 1, workerSpanType);
-    const response = await invokeRpcHandler(call.request, runId);
+    const response = await invokeRpcHandler(call.request, traceId);
     reportCallAsync(workerTraceId, workerSpanId, fnName, rpcStartedAt, rpcInputBuf, response.success ?? true, 1, response.output ?? Buffer.alloc(0), response.error ?? "", workerSpanType, workerParentSpanId);
     cb(null, response);
   }
   async function handleDeliver(call, cb) {
     const req = call.request;
-    const runIdMeta = call.metadata.get("servicebridge-run-id");
-    const runId = typeof runIdMeta[0] === "string" ? runIdMeta[0] : "";
+    const traceIdMeta = call.metadata.get("servicebridge-trace-id");
+    const traceId = typeof traceIdMeta[0] === "string" ? traceIdMeta[0] : "";
     const result = await invokeEventHandler({
       message_id: String(req.message_id ?? ""),
       group_name: String(req.group_name ?? ""),
@@ -1776,7 +1787,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       trace_id: String(req.trace_id ?? ""),
       parent_span_id: String(req.parent_span_id ?? ""),
       attempt: Number(req.attempt ?? 0)
-    }, runId);
+    }, traceId);
     cb(null, {
       ack: result.ack === true,
       error: result.error ?? "",
@@ -1826,6 +1837,71 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
     try {
       if (deadlineUnixMs > 0 && Date.now() > deadlineUnixMs) {
         result.error = "command deadline exceeded";
+      } else if (command.task_command) {
+        const tc = command.task_command;
+        if (tc.type === 1) {
+          const fn = tc.meta?.fn ?? "";
+          const tcParentSpanId = String(tc.parent_span_id ?? "");
+          const tcReq = {
+            function_name: fn,
+            payload: tc.payload ? Buffer.from(tc.payload) : Buffer.alloc(0),
+            trace_id: String(tc.trace_id ?? ""),
+            span_id: String(tc.span_id ?? ""),
+            parent_span_id: tcParentSpanId
+          };
+          const tcTraceId = tcReq.trace_id || crypto.randomUUID();
+          const tcSpanId = tcReq.span_id || crypto.randomUUID();
+          const tcStartedAt = Date.now();
+          const tcStreamTraceId = tc.meta?.trace_id ?? "";
+          reportCallStartAsync(tcTraceId, tcSpanId, tcParentSpanId, fn, tcStartedAt, tcReq.payload, tc.attempt ?? 1, "rpc");
+          const tcResult = await invokeRpcHandler(tcReq, tcStreamTraceId);
+          reportCallAsync(tcTraceId, tcSpanId, fn, tcStartedAt, tcReq.payload, tcResult.success, tc.attempt ?? 1, tcResult.output ?? Buffer.alloc(0), tcResult.error ?? "", "rpc", tcParentSpanId);
+          result.success = tcResult.success;
+          result.output = tcResult.output ?? Buffer.alloc(0);
+          result.error = tcResult.error ?? "";
+        } else if (tc.type === 2) {
+          const evTraceId = String(tc.trace_id ?? "");
+          const evParentSpanId = String(tc.parent_span_id ?? "");
+          const evSpanId = String(tc.span_id ?? "") || crypto.randomUUID();
+          const evTopic = tc.meta?.topic ?? "";
+          const evGroupName = tc.meta?.group_name ?? "";
+          const evMessageId = tc.meta?.message_id ?? "";
+          const evStreamTraceId = tc.meta?.trace_id ?? "";
+          const evAttempt = tc.attempt ?? 0;
+          const evPayload = tc.payload ? Buffer.from(tc.payload) : Buffer.alloc(0);
+          const reservedMetaKeys = new Set([
+            "fn",
+            "topic",
+            "group_name",
+            "message_id",
+            "trace_id"
+          ]);
+          const evHeaders = {};
+          for (const [k, v] of Object.entries(tc.meta ?? {})) {
+            if (!reservedMetaKeys.has(k))
+              evHeaders[k] = v;
+          }
+          const evStartedAt = Date.now();
+          reportCallStartAsync(evTraceId, evSpanId, evParentSpanId, evTopic, evStartedAt, evPayload, Number(evAttempt), "event");
+          const evResult = await invokeEventHandler({
+            message_id: evMessageId,
+            group_name: evGroupName,
+            topic: evTopic,
+            payload: evPayload,
+            headers: evHeaders,
+            trace_id: evTraceId,
+            parent_span_id: evParentSpanId,
+            attempt: Number(evAttempt)
+          }, evStreamTraceId);
+          reportCallAsync(evTraceId, evSpanId, evTopic, evStartedAt, evPayload, evResult.ack === true, Number(evAttempt), Buffer.alloc(0), evResult.error ?? "", "event", evParentSpanId);
+          result.success = evResult.ack === true;
+          result.ack = evResult.ack === true;
+          result.retry_after_ms = evResult.retry_after_ms ?? 0;
+          result.reject_reason = evResult.reject_reason ?? "";
+          result.error = evResult.error ?? "";
+        } else {
+          result.error = `unsupported task_command type: ${tc.type}`;
+        }
       } else if (command.rpc) {
         const rpc = command.rpc;
         const rpcParentSpanId = String(rpc.parent_span_id ?? "");
@@ -1842,7 +1918,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
         const fnName = rpcReq.function_name;
         const rpcStartedAt = Date.now();
         reportCallStartAsync(workerTraceId, workerSpanId, rpcParentSpanId, fnName, rpcStartedAt, rpcReq.payload, 1, rpcSpanType);
-        const rpcResult = await invokeRpcHandler(rpcReq, String(rpc.run_id ?? ""));
+        const rpcResult = await invokeRpcHandler(rpcReq, String(rpc.trace_id ?? ""));
         reportCallAsync(workerTraceId, workerSpanId, fnName, rpcStartedAt, rpcReq.payload, rpcResult.success, 1, rpcResult.output ?? Buffer.alloc(0), rpcResult.error ?? "", rpcSpanType, rpcParentSpanId);
         result.success = rpcResult.success;
         result.output = rpcResult.output ?? Buffer.alloc(0);
@@ -1858,7 +1934,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
           trace_id: String(event.trace_id ?? ""),
           parent_span_id: String(event.parent_span_id ?? ""),
           attempt: Number(event.attempt ?? 0)
-        }, String(event.run_id ?? ""));
+        }, String(event.trace_id ?? ""));
         result.success = eventResult.ack === true;
         result.ack = eventResult.ack === true;
         result.retry_after_ms = eventResult.retry_after_ms ?? 0;
@@ -1989,6 +2065,20 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       if (msg.flow_update && v2Session) {
         v2Session.onFlowControlUpdate(msg.flow_update.new_window_size ?? 0, msg.flow_update.reason ?? "");
       }
+      if (msg.publish_ack) {
+        const ack = msg.publish_ack;
+        const reqId = ack.request_id ?? "";
+        const pending = pendingPublishAcks.get(reqId);
+        if (pending) {
+          pendingPublishAcks.delete(reqId);
+          clearTimeout(pending.timer);
+          if (ack.error) {
+            pending.reject(new Error(ack.error));
+          } else {
+            pending.resolve(ack.message_id ?? "");
+          }
+        }
+      }
       if (msg.dispatch) {
         processWorkerSessionCommand(msg.dispatch).catch((err) => {
           reportSDKError("worker-session-command", err);
@@ -2048,11 +2138,14 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       const outputSchema = fmeta?.outputSchema;
       const inputBuf = inputSchema ? encodeWithSchema(inputSchema, payload) : toJsonBuffer(payload);
       const telemetryInputBuf = toJsonBuffer(payload);
+      const _parsedCanonical = parseCanonicalFunctionName(canonical);
+      const rpcFnName = _parsedCanonical?.fnName ?? canonical;
+      const rpcServiceName = _parsedCanonical?.serviceName ?? "";
       const rootSpanId = crypto.randomUUID();
       const parentSpanId = opts?.parentSpanId ?? tc?.spanId ?? "";
       const rootStartedAt = Date.now();
       const hasRetries = maxRetries > 0;
-      reportCallStartAsync(traceId, rootSpanId, parentSpanId, canonical, rootStartedAt, telemetryInputBuf, 1, "rpc");
+      reportCallStartAsync(traceId, rootSpanId, parentSpanId, rpcFnName, rootStartedAt, telemetryInputBuf, 1, "rpc", rpcServiceName);
       return traceStorage.run({ traceId, spanId: rootSpanId }, async () => {
         if (opts?.mode === "proxy") {
           return await new Promise((resolve, reject) => {
@@ -2064,15 +2157,15 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
               timeout_ms: timeout
             }, meta, { deadline: new Date(Date.now() + timeout) }, (err, res) => {
               if (err) {
-                reportCallAsync(traceId, rootSpanId, canonical, rootStartedAt, telemetryInputBuf, false, 1, undefined, String(err), "rpc", parentSpanId);
+                reportCallAsync(traceId, rootSpanId, rpcFnName, rootStartedAt, telemetryInputBuf, false, 1, undefined, String(err), "rpc", parentSpanId, rpcServiceName);
                 return reject(normalizeServiceError(err, fn, "control-plane"));
               }
               if (!res?.success) {
                 const errMsg = res?.error ?? "proxy call failed";
-                reportCallAsync(traceId, rootSpanId, canonical, rootStartedAt, telemetryInputBuf, false, 1, undefined, errMsg, "rpc", parentSpanId);
+                reportCallAsync(traceId, rootSpanId, rpcFnName, rootStartedAt, telemetryInputBuf, false, 1, undefined, errMsg, "rpc", parentSpanId, rpcServiceName);
                 return reject(normalizeServiceError(new Error(errMsg), fn, "worker"));
               }
-              reportCallAsync(traceId, rootSpanId, canonical, rootStartedAt, telemetryInputBuf, true, 1, res.output, "", "rpc", parentSpanId);
+              reportCallAsync(traceId, rootSpanId, rpcFnName, rootStartedAt, telemetryInputBuf, true, 1, res.output, "", "rpc", parentSpanId, rpcServiceName);
               try {
                 const out = res.output?.length ? outputSchema ? decodeWithSchema(outputSchema, res.output) : JSON.parse(res.output.toString()) : undefined;
                 resolve(out);
@@ -2089,10 +2182,9 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
         for (let attempt = 1;attempt <= maxRetries + 1; attempt++) {
           const attemptSpanId = hasRetries ? crypto.randomUUID() : rootSpanId;
           const attemptParentId = hasRetries ? rootSpanId : parentSpanId;
-          const attemptFn = canonical;
           const attemptStartedAt = hasRetries ? Date.now() : rootStartedAt;
           if (hasRetries) {
-            reportCallStartAsync(traceId, attemptSpanId, attemptParentId, attemptFn, attemptStartedAt, telemetryInputBuf, attempt, "rpc");
+            reportCallStartAsync(traceId, attemptSpanId, attemptParentId, rpcFnName, attemptStartedAt, telemetryInputBuf, attempt, "rpc", rpcServiceName);
           }
           try {
             const attemptTimeoutMs = timeout;
@@ -2141,22 +2233,22 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
             const result = outputSchema ? decodeWithSchema(outputSchema, outputBuf) : outputBuf?.length ? JSON.parse(outputBuf.toString()) : {};
             const encodedOutput = outputBuf?.length ? toJsonBuffer(result) : Buffer.alloc(0);
             if (hasRetries) {
-              reportCallAsync(traceId, attemptSpanId, attemptFn, attemptStartedAt, telemetryInputBuf, true, attempt, encodedOutput, "", "rpc", attemptParentId);
-              reportCallAsync(traceId, rootSpanId, canonical, rootStartedAt, telemetryInputBuf, true, attempt, encodedOutput, "", "rpc", parentSpanId);
+              reportCallAsync(traceId, attemptSpanId, rpcFnName, attemptStartedAt, telemetryInputBuf, true, attempt, encodedOutput, "", "rpc", attemptParentId, rpcServiceName);
+              reportCallAsync(traceId, rootSpanId, rpcFnName, rootStartedAt, telemetryInputBuf, true, attempt, encodedOutput, "", "rpc", parentSpanId, rpcServiceName);
             } else {
-              reportCallAsync(traceId, rootSpanId, canonical, rootStartedAt, telemetryInputBuf, true, attempt, encodedOutput, "", "rpc", parentSpanId);
+              reportCallAsync(traceId, rootSpanId, rpcFnName, rootStartedAt, telemetryInputBuf, true, attempt, encodedOutput, "", "rpc", parentSpanId, rpcServiceName);
             }
             return result;
           } catch (e) {
             lastError = e;
             const errMsg = normalizeUnknownErrorMessage(e);
             if (hasRetries) {
-              reportCallAsync(traceId, attemptSpanId, attemptFn, attemptStartedAt, telemetryInputBuf, false, attempt, undefined, errMsg, "rpc", attemptParentId);
+              reportCallAsync(traceId, attemptSpanId, rpcFnName, attemptStartedAt, telemetryInputBuf, false, attempt, undefined, errMsg, "rpc", attemptParentId, rpcServiceName);
               if (attempt > maxRetries) {
-                reportCallAsync(traceId, rootSpanId, canonical, rootStartedAt, telemetryInputBuf, false, attempt, undefined, errMsg, "rpc", parentSpanId);
+                reportCallAsync(traceId, rootSpanId, rpcFnName, rootStartedAt, telemetryInputBuf, false, attempt, undefined, errMsg, "rpc", parentSpanId, rpcServiceName);
               }
             } else {
-              reportCallAsync(traceId, rootSpanId, canonical, rootStartedAt, telemetryInputBuf, false, attempt, undefined, errMsg, "rpc", parentSpanId);
+              reportCallAsync(traceId, rootSpanId, rpcFnName, rootStartedAt, telemetryInputBuf, false, attempt, undefined, errMsg, "rpc", parentSpanId, rpcServiceName);
             }
             if (attempt <= maxRetries) {
               await new Promise((r) => setTimeout(r, baseDelay * 2 ** (attempt - 1)));
@@ -2184,6 +2276,36 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
         }, meta, unaryDeadlineOptions(), (err, res) => err ? reject(normalizeServiceError(err, `publish:${topic}`)) : resolve(res?.message_id ?? ""));
       });
     },
+    publishEvent(topic, payload, opts) {
+      const stream = workerSessionStream;
+      if (!stream) {
+        return Promise.reject(new Error("publishEvent requires an active worker session (call serve() first)"));
+      }
+      const tc = traceStorage.getStore();
+      const requestId = crypto.randomUUID();
+      const msg = {
+        request_id: requestId,
+        topic,
+        payload: toJsonBuffer(payload),
+        headers: toWireStringMap(opts?.headers),
+        trace_id: opts?.traceId ?? tc?.traceId ?? "",
+        parent_span_id: opts?.parentSpanId ?? tc?.spanId ?? ""
+      };
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pendingPublishAcks.delete(requestId);
+          reject(new Error(`publishEvent timed out after 30 s (topic="${topic}", request_id="${requestId}")`));
+        }, 30000);
+        pendingPublishAcks.set(requestId, { resolve, reject, timer });
+        try {
+          stream.write({ publish_message: msg });
+        } catch (err) {
+          pendingPublishAcks.delete(requestId);
+          clearTimeout(timer);
+          reject(normalizeServiceError(err, `publish-event:${topic}`));
+        }
+      });
+    },
     handleRpc(fn, handler, opts) {
       fnHandlers.set(fn, { handler, opts: opts ?? {} });
       return svc;
@@ -2343,36 +2465,35 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
       }
       return name;
     },
-    async runWorkflow(name, input, opts) {
+    async executeWorkflow(name, input, opts) {
       await _controlReady;
       const payload = toJsonBuffer(input ?? {});
       return new Promise((resolve, reject) => {
-        stub.RunWorkflow({
+        stub.ExecuteWorkflow({
           name,
           input: payload,
           service_name: service
         }, meta, unaryDeadlineOptions(), (err, res) => {
           if (err) {
-            reject(normalizeServiceError(err, "run-workflow"));
+            reject(normalizeServiceError(err, "execute-workflow"));
             return;
           }
           resolve({
-            runId: res?.run_id ?? "",
             traceId: res?.trace_id ?? ""
           });
         });
       });
     },
-    async cancelWorkflowRun(runId) {
+    async cancelWorkflow(traceId) {
       await _controlReady;
       await new Promise((resolve, reject) => {
-        stub.CancelWorkflow({ run_id: runId }, meta, unaryDeadlineOptions(), (err, res) => {
+        stub.CancelWorkflow({ trace_id: traceId }, meta, unaryDeadlineOptions(), (err, res) => {
           if (err) {
-            reject(normalizeServiceError(err, "cancel-workflow-run"));
+            reject(normalizeServiceError(err, "cancel-workflow"));
             return;
           }
           if (!res?.cancelled) {
-            reject(new Error(`workflow run ${runId} was not cancelled`));
+            reject(new Error(`workflow trace ${traceId} was not cancelled`));
             return;
           }
           resolve();
@@ -2419,12 +2540,12 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
         }
       }
     },
-    watchRun(runId, opts) {
+    watchTrace(traceId, opts) {
       const key = opts?.key ?? "";
       const fromSeq = opts?.fromSequence ?? 0;
-      const WATCH_RUN_QUEUE_LIMIT = 256;
-      const WATCH_RUN_RETRY_MIN_MS = 500;
-      const WATCH_RUN_RETRY_MAX_MS = 5000;
+      const WATCH_TRACE_QUEUE_LIMIT = 256;
+      const WATCH_TRACE_RETRY_MIN_MS = 500;
+      const WATCH_TRACE_RETRY_MAX_MS = 5000;
       return {
         [Symbol.asyncIterator]() {
           let stream = null;
@@ -2432,7 +2553,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
           let cancelled = false;
           let done = false;
           let fatalError = null;
-          let reconnectDelay = WATCH_RUN_RETRY_MIN_MS;
+          let reconnectDelay = WATCH_TRACE_RETRY_MIN_MS;
           let lastSequence = fromSeq;
           const queue = [];
           const waiters = [];
@@ -2458,21 +2579,21 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
                 data = JSON.parse(rawData.toString());
               } catch (cause) {
                 throw new ServiceBridgeError({
-                  message: `watchRun received non-JSON chunk for ${runId}`,
+                  message: `watchTrace received non-JSON chunk for ${traceId}`,
                   component: "sdk",
-                  operation: `watch-run:${runId}`,
+                  operation: `watch-trace:${traceId}`,
                   severity: "fatal",
                   cause
                 });
               }
             }
             return {
-              type: chunk.type === "run_complete" ? "run_complete" : "chunk",
-              runId,
+              type: chunk.type === "trace_complete" ? "trace_complete" : "chunk",
+              traceId,
               key: chunk.key || key,
               sequence: Number(chunk.sequence ?? 0),
               data,
-              runStatus: chunk.run_status || undefined
+              traceStatus: chunk.trace_status || undefined
             };
           }
           function clearReconnectTimer() {
@@ -2514,11 +2635,11 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
               }
               return;
             }
-            if (queue.length >= WATCH_RUN_QUEUE_LIMIT) {
+            if (queue.length >= WATCH_TRACE_QUEUE_LIMIT) {
               fail(new ServiceBridgeError({
-                message: `watchRun consumer is not draining fast enough for ${runId}`,
+                message: `watchTrace consumer is not draining fast enough for ${traceId}`,
                 component: "sdk",
-                operation: `watch-run:${runId}`,
+                operation: `watch-trace:${traceId}`,
                 severity: "fatal"
               }));
               return;
@@ -2537,14 +2658,14 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
             waiters.length = 0;
           }
           function shouldRetry(err) {
-            if (metadataValue(err, "servicebridge-run-stream-retryable") === "true") {
+            if (metadataValue(err, "servicebridge-trace-stream-retryable") === "true") {
               return true;
             }
             const code = err?.code;
             return code === grpc.status.UNAVAILABLE || code === grpc.status.UNKNOWN || code === grpc.status.DEADLINE_EXCEEDED || code === grpc.status.RESOURCE_EXHAUSTED;
           }
           function maybeUpdateResumeSequence(err) {
-            const parsed = Number(metadataValue(err, "servicebridge-run-stream-resume-from") ?? 0);
+            const parsed = Number(metadataValue(err, "servicebridge-trace-stream-resume-from") ?? 0);
             if (Number.isFinite(parsed) && parsed > lastSequence) {
               lastSequence = parsed;
             }
@@ -2557,7 +2678,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
               reconnectTimer = null;
               start();
             }, delay);
-            reconnectDelay = Math.min(reconnectDelay * 2, WATCH_RUN_RETRY_MAX_MS);
+            reconnectDelay = Math.min(reconnectDelay * 2, WATCH_TRACE_RETRY_MAX_MS);
           }
           function start() {
             if (cancelled || done || fatalError || stream)
@@ -2565,25 +2686,25 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
             if (!dataPlaneStub) {
               fail(new ServiceBridgeError({
                 message: "DataPlane service is not available in this runtime version",
-                component: "watch-run",
-                operation: "watch-run-unavailable",
+                component: "watch-trace",
+                operation: "watch-trace-unavailable",
                 severity: "fatal"
               }));
               return;
             }
             try {
-              const current = dataPlaneStub.WatchRun({ run_id: runId, key, from_seq: lastSequence }, meta);
+              const current = dataPlaneStub.WatchTrace({ trace_id: traceId, key, from_seq: lastSequence }, meta);
               let endedWithOK = false;
               stream = current;
               current.on("data", (chunk) => {
                 if (stream !== current || cancelled || done || fatalError)
                   return;
-                reconnectDelay = WATCH_RUN_RETRY_MIN_MS;
+                reconnectDelay = WATCH_TRACE_RETRY_MIN_MS;
                 let event;
                 try {
                   event = parseChunk(chunk);
                 } catch (err) {
-                  fail(err instanceof ServiceBridgeError ? err : normalizeServiceError(err, `watch-run:${runId}`));
+                  fail(err instanceof ServiceBridgeError ? err : normalizeServiceError(err, `watch-trace:${traceId}`));
                   return;
                 }
                 if (event.sequence > 0) {
@@ -2592,7 +2713,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
                   lastSequence = event.sequence;
                 }
                 enqueue(event);
-                if (event.type === "run_complete") {
+                if (event.type === "trace_complete") {
                   finish();
                 }
               });
@@ -2602,10 +2723,10 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
                 clearStream(false);
                 maybeUpdateResumeSequence(err);
                 if (!shouldRetry(err)) {
-                  fail(normalizeServiceError(err, `watch-run:${runId}`));
+                  fail(normalizeServiceError(err, `watch-trace:${traceId}`));
                   return;
                 }
-                reconnectDelay = metadataValue(err, "servicebridge-run-stream-disconnect-reason") ? WATCH_RUN_RETRY_MIN_MS : reconnectDelay;
+                reconnectDelay = metadataValue(err, "servicebridge-trace-stream-disconnect-reason") ? WATCH_TRACE_RETRY_MIN_MS : reconnectDelay;
                 scheduleReconnect();
               });
               current.on("status", (statusInfo) => {
@@ -2633,7 +2754,7 @@ function servicebridge(url, serviceKey, serviceOrOpts = {}, maybeGlobalOpts = {}
             } catch (err) {
               maybeUpdateResumeSequence(err);
               if (!shouldRetry(err)) {
-                fail(normalizeServiceError(err, `watch-run:${runId}`));
+                fail(normalizeServiceError(err, `watch-trace:${traceId}`));
                 return;
               }
               scheduleReconnect();
@@ -2728,9 +2849,9 @@ function captureConsole(svc) {
   }
 }
 export {
+  withTraceContext,
   validateV2Config,
   servicebridge,
-  runWithTraceContext,
   getTraceContext,
   V2SessionClient,
   ServiceBridgeError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "service-bridge",
-  "version": "1.6.0-dev.32",
+  "version": "1.7.0-dev.34",
   "type": "module",
   "description": "ServiceBridge SDK for Node.js — production-ready RPC, durable events, workflows, jobs, and distributed tracing. One Go runtime + PostgreSQL replaces Istio, RabbitMQ, Temporal, and Jaeger.",
   "keywords": [