feat: add metadata field to TerminalError class

Add a `metadata` field (Record<string, string>) to the TerminalError
class, enabling propagation of key-value metadata through the Restate
protocol (requires service protocol v6+).

Changes:
- TerminalError constructor now accepts an optional `metadata` option
- metadata is converted to WasmFailureMetadata format ({key, value}[])
  when sending to the VM via propose_run_completion_failure and
  sys_write_output_failure
- metadata is deserialized back to Record<string, string> when
  receiving Failure completions from the VM

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: PfisterFactor

packages/libs/restate-sdk/src/context_impl.ts

@@ -467,7 +467,9 @@ export class ContextImpl implements ObjectContext, WorkflowContext {
             this.coreVm.propose_run_completion_failure(handle, {
               code: err.code,
               message: err.message,
-              metadata: [],
+              metadata: Object.entries(err.metadata ?? {}).map(
+                ([key, value]) => ({ key, value })
+              ),
             });
           } else if (err instanceof RetryableError) {
             const maxRetryDuration =
@@ -1023,9 +1025,17 @@ function SuccessWithSerde<T>(
 
 const Failure: Completer = (value, prom) => {
   if (typeof value === "object" && "Failure" in value) {
+    const metadata = (value.Failure.metadata ?? []).reduce(
+      (acc: Record<string, string>, { key, value: v }: { key: string; value: string }) => {
+        acc[key] = v;
+        return acc;
+      },
+      {} as Record<string, string>
+    );
     prom.reject(
       new TerminalError(value.Failure.message, {
         errorCode: value.Failure.code,
+        metadata,
       })
     );
     return Promise.resolve(true);

packages/libs/restate-sdk/src/endpoint/handlers/generic.ts

@@ -480,7 +480,9 @@ export class GenericHandler implements RestateHandler {
             coreVm.sys_write_output_failure({
               code: error.code,
               message: error.message,
-              metadata: [],
+              metadata: Object.entries(error.metadata ?? {}).map(
+                ([key, value]) => ({ key, value })
+              ),
             });
             coreVm.sys_end();
             return;

packages/libs/restate-sdk/src/types/errors.ts

@@ -92,6 +92,7 @@ export class RestateError extends Error {
  */
 export class TerminalError extends RestateError {
   public override name = "TerminalError";
+  public readonly metadata: Record<string, string>;
 
   constructor(
     message: string,
@@ -104,9 +105,15 @@ export class TerminalError extends RestateError {
        * @deprecated YOU MUST NOT USE THIS FIELD, AS IT WON'T BE RECORDED AND CAN LEAD TO NON-DETERMINISM! From the next SDK version, the constructor won't accept this field anymore.
        */
       cause?: any;
+      /**
+       * Metadata key-value pairs to attach to the terminal error.
+       * These are propagated through the Restate protocol (requires service protocol v6+).
+       */
+      metadata?: Record<string, string>;
     }
   ) {
     super(message, options);
+    this.metadata = options?.metadata ?? {};
   }
 }