agent-relay 8.3.6 → 8.4.0

package/dist/index.cjs

@@ -175,11 +175,13 @@ __export(index_exports, {
   MessageReactedPredicate: () => MessageReactedPredicate,
   MessageReadPredicate: () => MessageReadPredicate,
   RelayCapabilityError: () => RelayCapabilityError,
+  RelayError: () => RelayError,
   RelaycastMessagingClient: () => RelaycastMessagingClient,
   StaticPatterns: () => StaticPatterns,
   StatusPredicate: () => StatusPredicate,
   ToolCalledPredicate: () => ToolCalledPredicate,
   TracedError: () => TracedError,
+  TypedActionPredicate: () => TypedActionPredicate,
   actionSchemaToJsonSchema: () => actionSchemaToJsonSchema,
   agentRelayAgent: () => agentRelayAgent,
   agentTokenRecoveryMessage: () => agentTokenRecoveryMessage,
@@ -201,6 +203,7 @@ __export(index_exports, {
   createRequestEnvelope: () => createRequestEnvelope,
   createRequestHandler: () => createRequestHandler,
   createTraceableError: () => createTraceableError,
+  createTypedActionHandle: () => createTypedActionHandle,
   createWorkspaceFacade: () => createWorkspaceFacade,
   defineHarness: () => defineHarness,
   findGitRoot: () => findGitRoot,
@@ -233,6 +236,7 @@ __export(index_exports, {
   isSpawnOrReleaseCommandFast: () => isSpawnOrReleaseCommandFast,
   isValidAgentName: () => isValidAgentName,
   logAndTraceError: () => logAndTraceError,
+  logRelayHandlerError: () => logRelayHandlerError,
   mapModelToCli: () => mapModelToCli,
   matchesSelector: () => matchesSelector,
   nextHarnessName: () => nextHarnessName,
@@ -275,7 +279,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // ../../node_modules/@relaycast/sdk/dist/version.js
-var SDK_VERSION = "2.6.0";
+var SDK_VERSION = "3.1.1";
 
 // ../../node_modules/@relaycast/types/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -15313,10 +15317,16 @@ var UnsubscribeEventSchema = external_exports.object({
 var PingEventSchema = external_exports.object({
   type: external_exports.literal("ping")
 });
+var ResyncEventSchema = external_exports.object({
+  type: external_exports.literal("resync"),
+  last_seen_seq: external_exports.number(),
+  since: external_exports.string().optional()
+});
 var ClientEventSchema = external_exports.discriminatedUnion("type", [
   SubscribeEventSchema,
   UnsubscribeEventSchema,
-  PingEventSchema
+  PingEventSchema,
+  ResyncEventSchema
 ]);
 var ChannelMessagePayloadSchema = CoreMessagePayloadSchema.extend({
   attachments: external_exports.array(FileAttachmentSchema)
@@ -15450,6 +15460,13 @@ var FileUploadedEventSchema = external_exports.object({
 var PongEventSchema = external_exports.object({
   type: external_exports.literal("pong")
 });
+var ResyncAckEventSchema = external_exports.object({
+  type: external_exports.literal("resync_ack"),
+  last_seen_seq: external_exports.number(),
+  current_seq: external_exports.number(),
+  replayed: external_exports.number(),
+  gap_detected: external_exports.boolean()
+});
 var WebhookReceivedEventSchema = external_exports.object({
   type: external_exports.literal("webhook.received"),
   webhook_id: external_exports.string(),
@@ -15542,6 +15559,11 @@ var WsPermanentlyDisconnectedEventSchema = external_exports.object({
 var WsCloseEventSchema = external_exports.object({
   type: external_exports.literal("close")
 });
+var WsResyncedEventSchema = external_exports.object({
+  type: external_exports.literal("resynced"),
+  replayed: external_exports.number(),
+  gap_detected: external_exports.boolean()
+});
 var ServerEventSchema = external_exports.discriminatedUnion("type", [
   MessageCreatedEventSchema,
   MessageUpdatedEventSchema,
@@ -15576,7 +15598,8 @@ var ServerEventSchema = external_exports.discriminatedUnion("type", [
   DeliveryDeliveredEventSchema,
   DeliveryDeferredEventSchema,
   DeliveryFailedEventSchema,
-  PongEventSchema
+  PongEventSchema,
+  ResyncAckEventSchema
 ]);
 var RelaycastMessageEventSchema = external_exports.discriminatedUnion("type", [
   MessageCreatedEventSchema,
@@ -15620,12 +15643,14 @@ var WsClientEventSchema = external_exports.discriminatedUnion("type", [
   DeliveryDeferredEventSchema,
   DeliveryFailedEventSchema,
   PongEventSchema,
+  ResyncAckEventSchema,
   // Client-only events
   WsOpenEventSchema,
   WsErrorEventSchema,
   WsReconnectingEventSchema,
   WsPermanentlyDisconnectedEventSchema,
-  WsCloseEventSchema
+  WsCloseEventSchema,
+  WsResyncedEventSchema
 ]);
 
 // ../../node_modules/@relaycast/types/dist/api.js
@@ -15923,22 +15948,22 @@ var SDK_ORIGIN = Object.freeze({
   client: "@relaycast/sdk",
   version: SDK_VERSION
 });
-var HARNESS_HEADER = "X-Relaycast-Harness";
+var ORIGIN_ACTOR_HEADER = "X-Relaycast-Origin-Actor";
 var AGENT_RELAY_DISTINCT_ID_HEADER = "X-Agent-Relay-Distinct-Id";
 var AGENT_RELAY_DISTINCT_ID_QUERY = "agent_relay_distinct_id";
-var HARNESS_MAX_LENGTH = 120;
+var ORIGIN_ACTOR_MAX_LENGTH = 128;
 var AGENT_RELAY_DISTINCT_ID_MAX_LENGTH = 128;
-var HARNESS_ALLOWED = /^[a-z0-9 ._\-/():=;,+]+$/i;
+var ORIGIN_ACTOR_ALLOWED = /^[a-z0-9 ._\-/():=;,+@]+$/i;
 var AGENT_RELAY_DISTINCT_ID_ALLOWED = /^[a-z0-9._:-]+$/i;
-function sanitizeHarness(raw) {
+function sanitizeOriginActor(raw) {
   if (!raw)
     return void 0;
   const trimmed = raw.trim();
   if (!trimmed)
     return void 0;
-  if (!HARNESS_ALLOWED.test(trimmed))
+  if (!ORIGIN_ACTOR_ALLOWED.test(trimmed))
     return void 0;
-  return trimmed.slice(0, HARNESS_MAX_LENGTH).toLowerCase();
+  return trimmed.slice(0, ORIGIN_ACTOR_MAX_LENGTH).toLowerCase();
 }
 function sanitizeAgentRelayDistinctId(raw) {
   if (!raw)
@@ -15995,6 +16020,7 @@ function decamelizeKey(key) {
 }
 
 // ../../node_modules/@relaycast/sdk/dist/ws.js
+var SEEN_EVENT_IDS_MAX = 2048;
 var INTERNAL_WS_ORIGIN = /* @__PURE__ */ Symbol("relaycast.internal.ws-origin");
 function readInternalWsOrigin(options) {
   return options[INTERNAL_WS_ORIGIN];
@@ -16031,8 +16057,14 @@ var WsClient = class {
   originSurface;
   originClient;
   originVersion;
-  originHarness;
+  originActor;
   agentRelayDistinctId;
+  /** Highest `agent_seq` observed across delivered events; null until the first stamped event. */
+  lastSeenSeq = null;
+  /** Receive time of the last seq-stamped event, used as `since` for DB-backed replay. */
+  lastEventAt = null;
+  /** Recently dispatched event ids (insertion-ordered for LRU eviction) for replay dedupe. */
+  seenEventIds = /* @__PURE__ */ new Set();
   constructor(options) {
     const origin = readInternalWsOrigin(options) ?? SDK_ORIGIN;
     this.token = options.token;
@@ -16047,7 +16079,7 @@ var WsClient = class {
     this.originSurface = origin.surface;
     this.originClient = origin.client;
     this.originVersion = origin.version;
-    this.originHarness = sanitizeHarness(origin.harness ?? options.harness);
+    this.originActor = sanitizeOriginActor(origin.originActor ?? options.originActor);
     this.agentRelayDistinctId = sanitizeAgentRelayDistinctId(origin.agentRelayDistinctId ?? options.agentRelayDistinctId);
   }
   connect() {
@@ -16060,8 +16092,8 @@ var WsClient = class {
     wsUrl.searchParams.set(decamelizeKey("originSurface"), this.originSurface);
     wsUrl.searchParams.set(decamelizeKey("originClient"), this.originClient);
     wsUrl.searchParams.set(decamelizeKey("originVersion"), this.originVersion);
-    if (this.originHarness) {
-      wsUrl.searchParams.set("harness", this.originHarness);
+    if (this.originActor) {
+      wsUrl.searchParams.set("origin_actor", this.originActor);
     }
     if (this.agentRelayDistinctId) {
       wsUrl.searchParams.set(AGENT_RELAY_DISTINCT_ID_QUERY, this.agentRelayDistinctId);
@@ -16089,12 +16121,34 @@ var WsClient = class {
       this.startPing();
       const openEvent = { type: "open" };
       this.emit("open", openEvent);
+      this.sendResync();
     };
     ws.onmessage = (event) => {
       if (this.ws !== ws)
         return;
       try {
         const parsed = JSON.parse(String(event.data));
+        if (parsed !== null && typeof parsed === "object") {
+          if (typeof parsed.agent_seq === "number" && Number.isFinite(parsed.agent_seq)) {
+            this.lastSeenSeq = parsed.agent_seq;
+            this.lastEventAt = (/* @__PURE__ */ new Date()).toISOString();
+          }
+          if (parsed.type === "resync_ack") {
+            const resyncedEvent = {
+              type: "resynced",
+              replayed: typeof parsed.replayed === "number" ? parsed.replayed : 0,
+              gapDetected: parsed.gap_detected === true
+            };
+            this.emit("resynced", resyncedEvent);
+            return;
+          }
+          if (typeof parsed.id === "string" && parsed.id.length > 0 && typeof parsed.type === "string") {
+            const dedupeKey = `${parsed.type}:${parsed.id}`;
+            if (this.seenEventIds.has(dedupeKey))
+              return;
+            this.rememberEventId(dedupeKey);
+          }
+        }
         const result = ServerEventSchema.safeParse(parsed);
         if (result.success) {
           this.emit(result.data.type, camelizeKeys(result.data));
@@ -16214,6 +16268,29 @@ var WsClient = class {
       this.ws.send(JSON.stringify(data));
     }
   }
+  /**
+   * Request replay of events missed while disconnected. The server replays its
+   * resync ring past `last_seen_seq`, falls back to a DB-backed replay from
+   * `since` when the gap exceeds the ring, and answers with `resync_ack`.
+   * No-op until at least one seq-stamped event has been received.
+   */
+  sendResync() {
+    if (this.lastSeenSeq === null)
+      return;
+    this.sendJson({
+      type: "resync",
+      last_seen_seq: this.lastSeenSeq,
+      ...this.lastEventAt ? { since: this.lastEventAt } : {}
+    });
+  }
+  rememberEventId(key) {
+    this.seenEventIds.add(key);
+    if (this.seenEventIds.size > SEEN_EVENT_IDS_MAX) {
+      const oldest = this.seenEventIds.values().next().value;
+      if (oldest !== void 0)
+        this.seenEventIds.delete(oldest);
+    }
+  }
   startPing() {
     this.stopPing();
     this.pingTimer = setInterval(() => {
@@ -16425,7 +16502,7 @@ var AgentClient = class {
       surface: this.client.originSurface,
       client: this.client.originClient,
       version: this.client.originVersion,
-      ...this.client.originHarness ? { harness: this.client.originHarness } : {},
+      ...this.client.originActor ? { originActor: this.client.originActor } : {},
       ...this.client.agentRelayDistinctId ? { agentRelayDistinctId: this.client.agentRelayDistinctId } : {}
     }));
     this.ws.on("open", () => {
@@ -16581,6 +16658,15 @@ var AgentClient = class {
       }
       return this.ws.on("permanently_disconnected", (e) => handler(e.attempt));
     },
+    resynced: (handler) => {
+      if (!this.ws) {
+        throw new Error("WebSocket not connected. Call connect() first.");
+      }
+      return this.ws.on("resynced", (e) => {
+        const event = e;
+        handler({ replayed: event.replayed, gapDetected: event.gapDetected });
+      });
+    },
     // Wildcard
     any: (handler) => {
       if (!this.ws) {
@@ -31494,7 +31580,7 @@ var HttpClient = class _HttpClient {
   _originSurface;
   _originClient;
   _originVersion;
-  _originHarness;
+  _originActor;
   _agentRelayDistinctId;
   _retryPolicy;
   constructor(options) {
@@ -31504,7 +31590,7 @@ var HttpClient = class _HttpClient {
     this._originSurface = origin.surface;
     this._originClient = origin.client;
     this._originVersion = origin.version;
-    this._originHarness = sanitizeHarness(origin.harness ?? options.harness);
+    this._originActor = sanitizeOriginActor(origin.originActor ?? options.originActor);
     this._agentRelayDistinctId = sanitizeAgentRelayDistinctId(origin.agentRelayDistinctId ?? options.agentRelayDistinctId);
     this._retryPolicy = normalizeRetryPolicy(options.retryPolicy);
   }
@@ -31523,9 +31609,9 @@ var HttpClient = class _HttpClient {
   get originVersion() {
     return this._originVersion;
   }
-  /** Sanitized harness identifier, or `undefined` when none was supplied. */
-  get originHarness() {
-    return this._originHarness;
+  /** Sanitized originActor identifier, or `undefined` when none was supplied. */
+  get originActor() {
+    return this._originActor;
   }
   /** Sanitized Agent Relay distinct id, or `undefined` when none was supplied. */
   get agentRelayDistinctId() {
@@ -31539,7 +31625,7 @@ var HttpClient = class _HttpClient {
       surface: this._originSurface,
       client: this._originClient,
       version: this._originVersion,
-      ...this._originHarness ? { harness: this._originHarness } : {},
+      ...this._originActor ? { originActor: this._originActor } : {},
       ...this._agentRelayDistinctId ? { agentRelayDistinctId: this._agentRelayDistinctId } : {}
     }));
   }
@@ -31557,7 +31643,7 @@ var HttpClient = class _HttpClient {
       "X-Relaycast-Origin-Surface": this._originSurface,
       "X-Relaycast-Origin-Client": this._originClient,
       "X-Relaycast-Origin-Version": this._originVersion,
-      ...this._originHarness ? { [HARNESS_HEADER]: this._originHarness } : {},
+      ...this._originActor ? { [ORIGIN_ACTOR_HEADER]: this._originActor } : {},
       ...this._agentRelayDistinctId ? { [AGENT_RELAY_DISTINCT_ID_HEADER]: this._agentRelayDistinctId } : {},
       ...options?.headers || {}
     };
@@ -31687,7 +31773,7 @@ var RelayCast = class _RelayCast {
       surface: this.client.originSurface,
       client: this.client.originClient,
       version: this.client.originVersion,
-      ...this.client.originHarness ? { harness: this.client.originHarness } : {}
+      ...this.client.originActor ? { originActor: this.client.originActor } : {}
     }));
   }
   connect() {
@@ -31732,6 +31818,10 @@ var RelayCast = class _RelayCast {
     error: (handler) => this.onEvent("error", handler),
     reconnecting: (handler) => this.ws.on("reconnecting", (e) => handler(e.attempt)),
     permanentlyDisconnected: (handler) => this.ws.on("permanently_disconnected", (e) => handler(e.attempt)),
+    resynced: (handler) => this.ws.on("resynced", (e) => {
+      const event = e;
+      handler({ replayed: event.replayed, gapDetected: event.gapDetected });
+    }),
     any: (handler) => this.ws.on("*", handler)
   };
   static async createWorkspace(name, options) {
@@ -32724,6 +32814,7 @@ function actionContext(input) {
 }
 
 // ../sdk/dist/relaycast-telemetry.js
+var ORIGIN_ACTOR_ENV = "AGENT_RELAY_ORIGIN_ACTOR";
 var HARNESS_ENV_KEYS = [
   "AGENT_RELAY_HARNESS",
   "AGENT_RELAY_ORCHESTRATOR_HARNESS",
@@ -32737,11 +32828,18 @@ function nonEmpty(value) {
   const trimmed = value?.trim();
   return trimmed ? trimmed : void 0;
 }
+function resolveOriginActor(env) {
+  const explicit = nonEmpty(env[ORIGIN_ACTOR_ENV]);
+  if (explicit)
+    return explicit;
+  const harness = HARNESS_ENV_KEYS.map((key) => nonEmpty(env[key])).find((value) => Boolean(value));
+  return harness ? `agent-relay-cli/agent/${harness}` : void 0;
+}
 function relaycastTelemetryOptions(explicit = {}, env = defaultEnv()) {
-  const harness = nonEmpty(explicit.harness) ?? HARNESS_ENV_KEYS.map((key) => nonEmpty(env[key])).find((value) => Boolean(value));
+  const originActor = nonEmpty(explicit.originActor) ?? resolveOriginActor(env);
   const agentRelayDistinctId = nonEmpty(explicit.agentRelayDistinctId) ?? nonEmpty(env.AGENT_RELAY_DISTINCT_ID);
   return {
-    ...harness ? { harness } : {},
+    ...originActor ? { originActor } : {},
     ...agentRelayDistinctId ? { agentRelayDistinctId } : {}
   };
 }
@@ -33428,7 +33526,7 @@ function createRelaycastClient(options) {
     baseUrl: options.baseUrl,
     retryPolicy: options.retryPolicy,
     ...relaycastTelemetryOptions({
-      harness: options.harness,
+      originActor: options.originActor,
       agentRelayDistinctId: options.agentRelayDistinctId
     })
   }));
@@ -33456,6 +33554,7 @@ var RelaycastMessagingClient = class {
     },
     get: async (name) => normalizeAgent(await this.relaycast.agents.get(name)),
     register: async (input) => normalizeAgentRegistration(await this.relaycast.agents.register(input)),
+    registerOrRotate: async (input) => normalizeAgentRegistration(this.relaycast.agents.registerOrRotate ? await this.relaycast.agents.registerOrRotate(input) : await this.relaycast.agents.register(input)),
     me: async () => normalizeAgent(await this.requireAgentClient("agents.me").me()),
     update: async (name, input) => normalizeAgent(await this.relaycast.agents.update(name, input)),
     delete: async (name) => {
@@ -33801,270 +33900,38 @@ var RelaycastMessagingClient = class {
   }
 };
 
-// ../sdk/dist/facade.js
-function resolveAgentName(ref) {
-  if (typeof ref === "string")
-    return stripSigil(ref);
-  const value = ref.handle ?? ref.name ?? ref.id;
-  if (!value) {
-    throw new Error("Unable to resolve agent name: reference has no name, handle, or id.");
-  }
-  return stripSigil(value);
-}
-function resolveAgentToken(ref) {
-  return ref && typeof ref !== "string" ? ref.token : void 0;
+// ../sdk/dist/listeners.js
+function logRelayHandlerError(error101, context) {
+  const where = context.action ? `action "${context.action}"` : `"${context.selector ?? "unknown"}"`;
+  console.warn(`[agent-relay] ${context.source} handler for ${where} threw:`, error101);
 }
 function stripSigil(value) {
   return value.startsWith("@") || value.startsWith("#") ? value.slice(1) : value;
 }
-function isChannelTarget(to) {
-  return to.startsWith("#");
-}
-function deliveryToMode(delivery) {
-  if (!delivery)
-    return void 0;
-  return delivery === "immediate" || delivery === "next-tool-call" ? "steer" : "wait";
-}
-function buildText(text, mentions) {
-  let body = text ?? "";
-  if (mentions?.length) {
-    const handles = mentions.map((mention) => `@${resolveAgentName(mention)}`);
-    const missing = handles.filter((handle) => !body.includes(handle));
-    if (missing.length) {
-      body = body ? `${missing.join(" ")} ${body}` : missing.join(" ");
-    }
-  }
-  return body;
-}
-function resolveMessageId(ref) {
-  if (!ref) {
-    throw new Error("reply requires a `messageId` or `thread`.");
-  }
-  if (typeof ref === "string")
-    return ref;
-  const value = ref.id ?? ref.threadId;
-  if (!value) {
-    throw new Error("Unable to resolve a message id from the provided thread reference.");
-  }
-  return value;
-}
-function createEnrichedMessages(base, resolveFrom) {
-  const enriched = Object.create(base);
-  enriched.send = async (input) => {
-    if ("channel" in input && input.channel) {
-      return base.send(input);
-    }
-    const sendInput = input;
-    const messages = resolveFrom(sendInput.from);
-    const text = buildText(sendInput.text ?? sendInput.msg, sendInput.mentions);
-    if (Array.isArray(sendInput.to)) {
-      return messages.groupDirect({
-        participants: sendInput.to.map(resolveAgentName),
-        text,
-        attachments: sendInput.attachments,
-        mode: sendInput.mode,
-        idempotencyKey: sendInput.idempotencyKey
-      });
-    }
-    if (isChannelTarget(sendInput.to)) {
-      return messages.send({
-        channel: stripSigil(sendInput.to),
-        text,
-        blocks: sendInput.blocks,
-        attachments: sendInput.attachments,
-        mode: sendInput.mode,
-        idempotencyKey: sendInput.idempotencyKey
-      });
-    }
-    return messages.direct({
-      to: resolveAgentName(sendInput.to),
-      text,
-      attachments: sendInput.attachments,
-      mode: sendInput.mode,
-      idempotencyKey: sendInput.idempotencyKey
-    });
-  };
-  enriched.reply = async (input) => {
-    const messages = resolveFrom(input.from);
-    return messages.reply({
-      messageId: resolveMessageId(input.messageId ?? input.thread),
-      text: input.text,
-      blocks: input.blocks,
-      idempotencyKey: input.idempotencyKey
-    });
-  };
-  enriched.react = (async (arg1, arg2) => {
-    if (typeof arg1 === "string") {
-      return base.react(arg1, arg2);
-    }
-    const messageId = typeof arg1.message === "string" ? arg1.message : arg1.message.id;
-    const messages = resolveFrom(arg1.agent);
-    return messages.react(messageId, arg1.emoji);
-  });
-  enriched.dm = async (input) => {
-    const messages = resolveFrom(input.from);
-    return messages.direct({
-      to: resolveAgentName(input.to),
-      text: input.text ?? input.msg ?? "",
-      attachments: input.attachments,
-      mode: input.mode,
-      idempotencyKey: input.idempotencyKey
-    });
-  };
-  return enriched;
-}
-function createWorkspaceFacade(messaging, deps) {
-  const register = async (agents) => {
-    if (!deps) {
-      throw new Error("register() is only available on the workspace client.");
-    }
-    const list = Array.isArray(agents) ? agents : [agents];
-    const inputs = list.map((agent) => typeof agent === "string" ? { name: stripSigil(agent) } : {
-      name: resolveAgentName(agent),
-      type: agent.type,
-      persona: agent.persona,
-      metadata: agent.metadata
-    });
-    const seen = /* @__PURE__ */ new Set();
-    for (const { name } of inputs) {
-      if (seen.has(name)) {
-        throw new Error(`Duplicate agent name in register(): "${name}".`);
-      }
-      seen.add(name);
-    }
-    const clients = [];
-    for (const input of inputs) {
-      clients.push(deps.buildAgentClient(await messaging.agents.register(input)));
-    }
-    return Array.isArray(agents) ? clients : clients[0];
-  };
-  return {
-    info: () => messaging.workspace.info(),
-    register,
-    reconnect: async ({ apiToken }) => {
-      if (!deps) {
-        throw new Error("reconnect() is only available on the workspace client.");
-      }
-      return deps.reconnectAgent(apiToken);
-    }
-  };
-}
-function registerFacadeAction(actions, def, wiring) {
-  const allowed = def.availableTo?.map(resolveAgentName);
-  const policy = allowed || def.policy ? async (input, ctx) => {
-    if (allowed && !allowed.includes(ctx.caller.name)) {
-      return {
-        allowed: false,
-        reason: `${ctx.caller.name} is not permitted to call ${def.name}.`
-      };
-    }
-    return def.policy ? def.policy(input, ctx) : { allowed: true };
-  } : void 0;
-  const localHandle = actions.register({
-    name: def.name,
-    description: def.description,
-    input: def.input,
-    inputSchema: def.inputSchema,
-    output: def.output,
-    outputSchema: def.outputSchema,
-    visibility: def.visibility,
-    policy,
-    handler: (input, ctx) => def.handler({ input, agent: ctx.caller, ctx })
-  });
-  const relayUnsubscribe = wireRelayAction(actions, def, wiring, allowed);
-  if (!relayUnsubscribe) {
-    return localHandle;
-  }
-  return {
-    unregister: () => {
-      relayUnsubscribe();
-      localHandle.unregister();
-    }
-  };
-}
-function wireRelayAction(actions, def, wiring, allowed) {
-  const commands = wiring?.messaging.commands;
-  if (!wiring || !commands?.agentScoped?.() || !commands.available?.()) {
-    return void 0;
-  }
-  const handlerAgent = wiring.handlerAgent;
-  if (!handlerAgent) {
-    return void 0;
-  }
-  void commands.register({
-    command: def.name,
-    description: def.description ?? def.name,
-    handlerAgent,
-    inputSchema: actionSchemaToJsonSchema(def.inputSchema ?? def.input),
-    outputSchema: actionSchemaToJsonSchema(def.outputSchema ?? def.output),
-    ...allowed ? { availableTo: allowed } : {}
-  }).catch((error101) => {
-    console.error(`[agent-relay] failed to register action descriptor "${def.name}":`, error101);
-  });
-  const unsubscribe = wiring.messaging.events.on("actionInvoked", async (event) => {
-    if (event.actionName !== def.name) {
-      return;
-    }
-    await handleActionInvoked(actions, commands, def.name, event);
-  });
-  try {
-    wiring.messaging.events.connect();
-  } catch (error101) {
-    console.error(`[agent-relay] failed to open the event stream for action "${def.name}":`, error101);
-  }
-  return unsubscribe;
-}
-async function handleActionInvoked(actions, commands, actionName, event) {
-  let input = {};
+function runHandler(handler, event, report) {
   try {
-    const invocation = await commands.getInvocation(actionName, event.invocationId);
-    input = invocation.input ?? {};
+    void Promise.resolve(handler(event)).catch(report);
   } catch (error101) {
-    console.error(`[agent-relay] failed to load invocation "${event.invocationId}":`, error101);
+    report(error101);
   }
-  const result = await actions.invoke({
-    name: actionName,
-    input,
-    caller: { name: event.callerName, type: "agent" }
-  });
-  try {
-    await commands.completeInvocation(actionName, event.invocationId, result.ok ? { output: toOutputRecord(result.output) } : { error: result.error?.message ?? "handler failed" });
-  } catch (error101) {
-    console.error(`[agent-relay] failed to complete invocation "${event.invocationId}":`, error101);
-  }
-}
-function toOutputRecord(output) {
-  if (output !== null && typeof output === "object" && !Array.isArray(output)) {
-    return output;
-  }
-  return { value: output };
 }
-function createNotifyHandler(messages, target, options) {
-  return async () => {
-    const subject = options.subject ? `@${resolveAgentName(options.subject)}` : void 0;
-    const label = options.type ?? options.action ?? "notification";
-    const text = options.text ?? [`[${label}]`, subject].filter(Boolean).join(" ");
-    await messages.dm({
-      to: resolveAgentName(target),
-      text,
-      mode: deliveryToMode(options.delivery)
-    });
+function makeReporter(context, info) {
+  return (error101) => {
+    if (!context.onError) {
+      logRelayHandlerError(error101, info);
+      return;
+    }
+    try {
+      context.onError(error101, info);
+    } catch {
+    }
   };
 }
-
-// ../sdk/dist/listeners.js
-function stripSigil2(value) {
-  return value.startsWith("@") || value.startsWith("#") ? value.slice(1) : value;
-}
-function runHandler(handler, event) {
-  void Promise.resolve(handler(event)).catch(() => {
-  });
-}
 var MessageCreatedPredicate = class {
   channel;
   mentioned;
   in(channel) {
-    this.channel = stripSigil2(channel);
+    this.channel = stripSigil(channel);
     return this;
   }
   mentions(agent) {
@@ -34072,30 +33939,33 @@ var MessageCreatedPredicate = class {
     return this;
   }
   subscribe(context, handler) {
+    const report = makeReporter(context, { source: "listener", selector: "message.created" });
     return context.events.on("messageCreated", (event) => {
-      if (this.channel && stripSigil2(event.channel) !== this.channel)
+      if (this.channel && stripSigil(event.channel) !== this.channel)
         return;
       if (this.mentioned && !messageMentions(event, this.mentioned))
         return;
-      runHandler(handler, event);
+      runHandler(handler, event, report);
     });
   }
 };
 function messageMentions(event, name) {
   const mentions = event.message.mentions ?? [];
-  if (mentions.some((mention) => stripSigil2(mention) === name))
+  if (mentions.some((mention) => stripSigil(mention) === name))
     return true;
   return event.message.text?.includes(`@${name}`) ?? false;
 }
 var MessageReadPredicate = class {
   subscribe(context, handler) {
-    return context.events.on("messageRead", (event) => runHandler(handler, event));
+    const report = makeReporter(context, { source: "listener", selector: "message.read" });
+    return context.events.on("messageRead", (event) => runHandler(handler, event, report));
   }
 };
 var MessageReactedPredicate = class {
   subscribe(context, handler) {
-    const off1 = context.events.on("reactionAdded", (event) => runHandler(handler, event));
-    const off2 = context.events.on("reactionRemoved", (event) => runHandler(handler, event));
+    const report = makeReporter(context, { source: "listener", selector: "message.reacted" });
+    const off1 = context.events.on("reactionAdded", (event) => runHandler(handler, event, report));
+    const off2 = context.events.on("reactionRemoved", (event) => runHandler(handler, event, report));
     return () => {
       off1();
       off2();
@@ -34135,6 +34005,11 @@ var ActionPredicate = class {
     return this;
   }
   subscribe(context, handler) {
+    const report = makeReporter(context, {
+      source: "listener",
+      selector: this.phase,
+      action: this.action
+    });
     return context.onActionEvent((event) => {
       if (event.action !== this.action)
         return;
@@ -34142,10 +34017,61 @@ var ActionPredicate = class {
         return;
       if (this.caller && event.caller.name !== this.caller)
         return;
-      runHandler(handler, event);
+      runHandler(handler, event, report);
     });
   }
 };
+var TypedActionPredicate = class {
+  action;
+  phase;
+  caller;
+  constructor(action, phase) {
+    this.action = action;
+    this.phase = phase;
+  }
+  calledBy(agent) {
+    this.caller = resolveAgentName(agent);
+    return this;
+  }
+  subscribe(context, handler) {
+    const report = makeReporter(context, {
+      source: "listener",
+      selector: this.phase,
+      action: this.action
+    });
+    return context.onActionEvent((event) => {
+      if (event.action !== this.action)
+        return;
+      if (event.type !== this.phase)
+        return;
+      if (this.caller && event.caller.name !== this.caller)
+        return;
+      runHandler(handler, toTypedActionEvent(event), report);
+    });
+  }
+};
+function toTypedActionEvent(raw) {
+  return {
+    type: raw.type,
+    action: raw.action,
+    agent: raw.caller,
+    ...raw.input !== void 0 ? { input: raw.input } : {},
+    ...raw.output !== void 0 ? { output: raw.output } : {},
+    ...raw.error !== void 0 ? { error: raw.error } : {},
+    ...raw.reason !== void 0 ? { reason: raw.reason } : {},
+    at: raw.at
+  };
+}
+function createTypedActionHandle(name, unregister) {
+  return {
+    name,
+    unregister,
+    invoked: () => new TypedActionPredicate(name, "action.invoked"),
+    completed: () => new TypedActionPredicate(name, "action.completed"),
+    failed: () => new TypedActionPredicate(name, "action.failed"),
+    denied: () => new TypedActionPredicate(name, "action.denied")
+  };
+}
 var StatusPredicate = class {
   agentId;
   status;
@@ -34154,12 +34080,16 @@ var StatusPredicate = class {
     this.status = status;
   }
   subscribe(context, handler) {
+    const report = makeReporter(context, {
+      source: "listener",
+      selector: `agent.status.${this.status}`
+    });
     return context.onSessionEvent(({ agentId, event }) => {
       if (agentId !== this.agentId)
         return;
       const matches = event.type === "status.changed" && event.status === this.status || event.type === `status.${this.status}`;
       if (matches)
-        runHandler(handler, event);
+        runHandler(handler, event, report);
     });
   }
 };
@@ -34176,6 +34106,7 @@ var ToolCalledPredicate = class {
     return this;
   }
   subscribe(context, handler) {
+    const report = makeReporter(context, { source: "listener", selector: `tool.called:${this.tool}` });
     return context.onSessionEvent(({ agentId, event }) => {
       if (agentId !== this.agentId)
         return;
@@ -34183,7 +34114,7 @@ var ToolCalledPredicate = class {
         return;
       if (this.filter && !this.filter(event))
         return;
-      runHandler(handler, event);
+      runHandler(handler, event, report);
     });
   }
 };
@@ -34195,7 +34126,7 @@ var PUBLIC_MESSAGE_TYPE = {
   groupDmReceived: "group_dm.received"
 };
 function buildEnvelope(message, channelName) {
-  const channel = message.channel ?? (channelName ? { name: stripSigil2(channelName) } : void 0);
+  const channel = message.channel ?? (channelName ? { name: stripSigil(channelName) } : void 0);
   return {
     ...message.from ? { from: message.from } : {},
     ...message.target ? { to: message.target } : {},
@@ -34258,7 +34189,7 @@ function matchesSelector(selector, type) {
     return type.startsWith(selector.slice(0, -1));
   return selector === type;
 }
-function createListenerHub(baseEvents, actions) {
+function createListenerHub(baseEvents, actions, options) {
   const sessionHandlers = /* @__PURE__ */ new Set();
   const events = createEnrichedEvents(baseEvents);
   const context = {
@@ -34268,7 +34199,8 @@ function createListenerHub(baseEvents, actions) {
     onSessionEvent: (handler) => {
       sessionHandlers.add(handler);
       return () => sessionHandlers.delete(handler);
-    }
+    },
+    ...options?.onError ? { onError: options.onError } : {}
   };
   const addListener = (selector, handler) => {
     try {
@@ -34278,29 +34210,49 @@ function createListenerHub(baseEvents, actions) {
     if (typeof selector !== "string") {
       return selector.subscribe(context, handler);
     }
+    const report = makeReporter(context, { source: "listener", selector });
     const offs = [
       context.events.on("any", (raw) => {
         const evt = toPublicMessagingEvent(raw);
         if (evt && matchesSelector(selector, evt.type))
-          runHandler(handler, evt);
+          runHandler(handler, evt, report);
       }),
       context.onActionEvent((raw) => {
         const evt = toPublicActionEvent(raw);
         if (matchesSelector(selector, evt.type))
-          runHandler(handler, evt);
+          runHandler(handler, evt, report);
       }),
       context.onSessionEvent(({ agentId, event }) => {
         const evt = toPublicSessionEvent(agentId, event);
         if (matchesSelector(selector, evt.type))
-          runHandler(handler, evt);
+          runHandler(handler, evt, report);
       })
     ];
     return () => offs.forEach((off) => off());
   };
+  const once = (selector, handler) => {
+    let done = false;
+    let off;
+    const wrapped = (event) => {
+      if (done)
+        return;
+      done = true;
+      off?.();
+      return handler(event);
+    };
+    off = addListener(selector, wrapped);
+    if (done)
+      off();
+    return () => {
+      done = true;
+      off?.();
+    };
+  };
   return {
     events,
     on: (predicate, handler) => predicate.subscribe(context, handler),
     addListener,
+    once,
     action: (name) => new ActionPredicate(name),
     agent: (input) => createAgentHandle(input),
     emitSessionEvent: (agentId, event) => {
@@ -34329,6 +34281,263 @@ function createAgentHandle(input) {
   };
 }
 
+// ../sdk/dist/facade.js
+function resolveAgentName(ref) {
+  if (typeof ref === "string")
+    return stripSigil2(ref);
+  const value = ref.handle ?? ref.name ?? ref.id;
+  if (!value) {
+    throw new Error("Unable to resolve agent name: reference has no name, handle, or id.");
+  }
+  return stripSigil2(value);
+}
+function resolveAgentToken(ref) {
+  return ref && typeof ref !== "string" ? ref.token : void 0;
+}
+function stripSigil2(value) {
+  return value.startsWith("@") || value.startsWith("#") ? value.slice(1) : value;
+}
+function isChannelTarget(to) {
+  return to.startsWith("#");
+}
+function deliveryToMode(delivery) {
+  if (!delivery)
+    return void 0;
+  return delivery === "immediate" || delivery === "next-tool-call" ? "steer" : "wait";
+}
+function buildText(text, mentions) {
+  let body = text ?? "";
+  if (mentions?.length) {
+    const handles = mentions.map((mention) => `@${resolveAgentName(mention)}`);
+    const missing = handles.filter((handle) => !body.includes(handle));
+    if (missing.length) {
+      body = body ? `${missing.join(" ")} ${body}` : missing.join(" ");
+    }
+  }
+  return body;
+}
+function resolveMessageId(ref) {
+  if (!ref) {
+    throw new Error("reply requires a `messageId` or `thread`.");
+  }
+  if (typeof ref === "string")
+    return ref;
+  const value = ref.id ?? ref.threadId;
+  if (!value) {
+    throw new Error("Unable to resolve a message id from the provided thread reference.");
+  }
+  return value;
+}
+function createEnrichedMessages(base, resolveFrom) {
+  const enriched = Object.create(base);
+  enriched.send = async (input) => {
+    if ("channel" in input && input.channel) {
+      return base.send(input);
+    }
+    const sendInput = input;
+    const messages = resolveFrom(sendInput.from);
+    const text = buildText(sendInput.text ?? sendInput.msg, sendInput.mentions);
+    if (Array.isArray(sendInput.to)) {
+      return messages.groupDirect({
+        participants: sendInput.to.map(resolveAgentName),
+        text,
+        attachments: sendInput.attachments,
+        mode: sendInput.mode,
+        idempotencyKey: sendInput.idempotencyKey
+      });
+    }
+    if (isChannelTarget(sendInput.to)) {
+      return messages.send({
+        channel: stripSigil2(sendInput.to),
+        text,
+        blocks: sendInput.blocks,
+        attachments: sendInput.attachments,
+        mode: sendInput.mode,
+        idempotencyKey: sendInput.idempotencyKey
+      });
+    }
+    return messages.direct({
+      to: resolveAgentName(sendInput.to),
+      text,
+      attachments: sendInput.attachments,
+      mode: sendInput.mode,
+      idempotencyKey: sendInput.idempotencyKey
+    });
+  };
+  enriched.reply = async (input) => {
+    const messages = resolveFrom(input.from);
+    return messages.reply({
+      messageId: resolveMessageId(input.messageId ?? input.thread),
+      text: input.text,
+      blocks: input.blocks,
+      idempotencyKey: input.idempotencyKey
+    });
+  };
+  enriched.react = (async (arg1, arg2) => {
+    if (typeof arg1 === "string") {
+      return base.react(arg1, arg2);
+    }
+    const messageId = typeof arg1.message === "string" ? arg1.message : arg1.message.id;
+    const messages = resolveFrom(arg1.agent);
+    return messages.react(messageId, arg1.emoji);
+  });
+  enriched.dm = async (input) => {
+    const messages = resolveFrom(input.from);
+    return messages.direct({
+      to: resolveAgentName(input.to),
+      text: input.text ?? input.msg ?? "",
+      attachments: input.attachments,
+      mode: input.mode,
+      idempotencyKey: input.idempotencyKey
+    });
+  };
+  return enriched;
+}
+function createWorkspaceFacade(messaging, deps) {
+  const register = async (agents, options) => {
+    if (!deps) {
+      throw new Error("register() is only available on the workspace client.");
+    }
+    const list = Array.isArray(agents) ? agents : [agents];
+    const inputs = list.map((agent) => typeof agent === "string" ? { name: stripSigil2(agent) } : {
+      name: resolveAgentName(agent),
+      type: agent.type,
+      persona: agent.persona,
+      metadata: agent.metadata
+    });
+    const seen = /* @__PURE__ */ new Set();
+    for (const { name } of inputs) {
+      if (seen.has(name)) {
+        throw new RelayError("name_conflict", `Duplicate agent name in register(): "${name}".`);
+      }
+      seen.add(name);
+    }
+    const registerOne = !options?.strict && messaging.agents.registerOrRotate ? messaging.agents.registerOrRotate.bind(messaging.agents) : messaging.agents.register.bind(messaging.agents);
+    const clients = [];
+    for (const input of inputs) {
+      clients.push(deps.buildAgentClient(await registerOne(input)));
+    }
+    return Array.isArray(agents) ? clients : clients[0];
+  };
+  return {
+    info: () => messaging.workspace.info(),
+    register,
+    reconnect: async ({ apiToken }) => {
+      if (!deps) {
+        throw new Error("reconnect() is only available on the workspace client.");
+      }
+      return deps.reconnectAgent(apiToken);
+    }
+  };
+}
+function reportActionError(wiring, action, operation, message, error101) {
+  if (wiring.onError) {
+    try {
+      wiring.onError(error101, { source: "action", action, operation });
+    } catch {
+    }
+    return;
+  }
+  console.error(`[agent-relay] ${message}`, error101);
+}
+function registerFacadeAction(actions, def, wiring) {
+  const allowed = def.availableTo?.map(resolveAgentName);
+  const policy = allowed || def.policy ? async (input, ctx) => {
+    if (allowed && !allowed.includes(ctx.caller.name)) {
+      return {
+        allowed: false,
+        reason: `${ctx.caller.name} is not permitted to call ${def.name}.`
+      };
+    }
+    return def.policy ? def.policy(input, ctx) : { allowed: true };
+  } : void 0;
+  const localHandle = actions.register({
+    name: def.name,
+    description: def.description,
+    input: def.input,
+    inputSchema: def.inputSchema,
+    output: def.output,
+    outputSchema: def.outputSchema,
+    visibility: def.visibility,
+    policy,
+    handler: (input, ctx) => def.handler({ input, agent: ctx.caller, ctx })
+  });
+  const relayUnsubscribe = wireRelayAction(actions, def, wiring, allowed);
+  return createTypedActionHandle(def.name, () => {
+    relayUnsubscribe?.();
+    localHandle.unregister();
+  });
+}
+function wireRelayAction(actions, def, wiring, allowed) {
+  const commands = wiring?.messaging.commands;
+  if (!wiring || !commands?.agentScoped?.() || !commands.available?.()) {
+    return void 0;
+  }
+  const handlerAgent = wiring.handlerAgent;
+  if (!handlerAgent) {
+    return void 0;
+  }
+  void commands.register({
+    command: def.name,
+    description: def.description ?? def.name,
+    handlerAgent,
+    inputSchema: actionSchemaToJsonSchema(def.inputSchema ?? def.input),
+    outputSchema: actionSchemaToJsonSchema(def.outputSchema ?? def.output),
+    ...allowed ? { availableTo: allowed } : {}
+  }).catch((error101) => {
+    reportActionError(wiring, def.name, "register", `failed to register action descriptor "${def.name}":`, error101);
+  });
+  const unsubscribe = wiring.messaging.events.on("actionInvoked", async (event) => {
+    if (event.actionName !== def.name) {
+      return;
+    }
+    await handleActionInvoked(actions, commands, def.name, event, wiring);
+  });
+  try {
+    wiring.messaging.events.connect();
+  } catch (error101) {
+    reportActionError(wiring, def.name, "connect", `failed to open the event stream for action "${def.name}":`, error101);
+  }
+  return unsubscribe;
+}
+async function handleActionInvoked(actions, commands, actionName, event, wiring) {
+  let input = {};
+  try {
+    const invocation = await commands.getInvocation(actionName, event.invocationId);
+    input = invocation.input ?? {};
+  } catch (error101) {
+    reportActionError(wiring, actionName, "load_invocation", `failed to load invocation "${event.invocationId}":`, error101);
+  }
+  const result = await actions.invoke({
+    name: actionName,
+    input,
+    caller: { name: event.callerName, type: "agent" }
+  });
+  try {
+    await commands.completeInvocation(actionName, event.invocationId, result.ok ? { output: toOutputRecord(result.output) } : { error: result.error?.message ?? "handler failed" });
+  } catch (error101) {
+    reportActionError(wiring, actionName, "complete_invocation", `failed to complete invocation "${event.invocationId}":`, error101);
+  }
+}
+function toOutputRecord(output) {
+  if (output !== null && typeof output === "object" && !Array.isArray(output)) {
+    return output;
+  }
+  return { value: output };
+}
+function createNotifyHandler(messages, target, options) {
+  return async () => {
+    const subject = options.subject ? `@${resolveAgentName(options.subject)}` : void 0;
+    const label = options.type ?? options.action ?? "notification";
+    const text = options.text ?? [`[${label}]`, subject].filter(Boolean).join(" ");
+    await messages.dm({
+      to: resolveAgentName(target),
+      text,
+      mode: deliveryToMode(options.delivery)
+    });
+  };
+}
+
 // ../sdk/dist/agent-relay.js
 var AgentRelay = class _AgentRelay {
   messaging;
@@ -34340,14 +34549,18 @@ var AgentRelay = class _AgentRelay {
   enrichedMessages;
   workspaceFacade;
   hub;
+  errorHooks = /* @__PURE__ */ new Set();
   constructor(options = {}) {
-    const { messaging, actions, workspaceKey, createAgentMessaging, ...messagingOptions } = options;
+    const { messaging, actions, workspaceKey, createAgentMessaging, onError, ...messagingOptions } = options;
     const resolvedWorkspaceKey = workspaceKey ?? messagingOptions.apiKey;
     this.workspaceKey = resolvedWorkspaceKey;
     this.messagingOptions = { ...messagingOptions, workspaceKey: resolvedWorkspaceKey };
     this.messaging = messaging ?? new RelaycastMessagingClient(this.messagingOptions);
     this.actions = actions ?? new ActionRegistry();
     this.createAgentMessaging = createAgentMessaging ?? ((token) => new RelaycastMessagingClient({ ...this.messagingOptions, agentToken: token }));
+    if (onError) {
+      this.errorHooks.add(onError);
+    }
   }
   static async createWorkspace(input) {
     const options = typeof input === "string" ? { name: input } : input;
@@ -34358,7 +34571,7 @@ var AgentRelay = class _AgentRelay {
     });
     const workspaceKey = extractWorkspaceKey(workspace);
     if (!workspaceKey) {
-      throw new Error("Workspace created, but the response did not include a workspace key.");
+      throw new RelayError("transport_error", "Workspace created, but the response did not include a workspace key.", { retryable: false });
     }
     return new _AgentRelay({
       workspaceKey,
@@ -34391,7 +34604,9 @@ var AgentRelay = class _AgentRelay {
   }
   get listenerHub() {
     if (!this.hub) {
-      this.hub = createListenerHub(this.messaging.events, this.actions);
+      this.hub = createListenerHub(this.messaging.events, this.actions, {
+        onError: (error101, context) => this.reportError(error101, context)
+      });
     }
     return this.hub;
   }
@@ -34422,7 +34637,7 @@ var AgentRelay = class _AgentRelay {
       id: registration.id,
       name: registration.name,
       token: registration.token
-    });
+    }, { onError: (error101, context) => this.reportError(error101, context) });
   }
   /** Rehydrate a live client from a persisted agent token, resolving identity from the relay. */
   async reconnectAgent(apiToken) {
@@ -34432,15 +34647,43 @@ var AgentRelay = class _AgentRelay {
       id: identity.id,
       name: identity.name,
       token: apiToken
-    });
+    }, { onError: (error101, context) => this.reportError(error101, context) });
   }
   registerAction(def) {
-    return registerFacadeAction(this.actions, def, { messaging: this.messaging });
+    return registerFacadeAction(this.actions, def, {
+      messaging: this.messaging,
+      onError: (error101, context) => this.reportError(error101, context)
+    });
   }
-  /** Subscribe by dotted event name, `'*'`/prefix wildcard, or a predicate. */
   addListener(selector, handler) {
     return this.listenerHub.addListener(selector, handler);
   }
+  once(selector, handler) {
+    return this.listenerHub.once(selector, handler);
+  }
+  /**
+   * Register a hook that receives listener and action handler errors. Returns
+   * an unsubscribe callback. When no hook is registered, errors are logged as
+   * console warnings.
+   */
+  onError(hook) {
+    this.errorHooks.add(hook);
+    return () => {
+      this.errorHooks.delete(hook);
+    };
+  }
+  reportError(error101, context) {
+    if (this.errorHooks.size === 0) {
+      logRelayHandlerError(error101, context);
+      return;
+    }
+    for (const hook of this.errorHooks) {
+      try {
+        hook(error101, context);
+      } catch {
+      }
+    }
+  }
   action(name) {
     return this.listenerHub.action(name);
   }
@@ -34470,9 +34713,9 @@ function extractWorkspaceKey(payload) {
   const value = payload.workspaceKey ?? payload.workspace_key ?? payload.apiKey ?? payload.api_key ?? data.workspaceKey ?? data.workspace_key ?? data.apiKey ?? data.api_key;
   return typeof value === "string" && value.trim() ? value : void 0;
 }
-function agentRelayAgent(messaging, actions, handlerAgent) {
+function agentRelayAgent(messaging, actions, handlerAgent, options) {
   const messages = createEnrichedMessages(messaging.messages, () => messaging.messages);
-  const hub = createListenerHub(messaging.events, actions);
+  const hub = createListenerHub(messaging.events, actions, { onError: options?.onError });
   return {
     messaging,
     agents: messaging.agents,
@@ -34486,15 +34729,16 @@ function agentRelayAgent(messaging, actions, handlerAgent) {
     webhooks: messaging.webhooks,
     capabilities: messaging.commands,
     workspace: createWorkspaceFacade(messaging),
-    registerAction: (def) => registerFacadeAction(actions, def, { messaging, handlerAgent }),
-    addListener: (selector, handler) => hub.addListener(selector, handler),
+    registerAction: (def) => registerFacadeAction(actions, def, { messaging, handlerAgent, onError: options?.onError }),
+    addListener: ((selector, handler) => hub.addListener(selector, handler)),
+    once: ((selector, handler) => hub.once(selector, handler)),
     action: (name) => hub.action(name),
     agent: (input) => hub.agent(input),
     emitSessionEvent: (agentId, event) => hub.emitSessionEvent(agentId, event)
   };
 }
-function assembleAgentClient(messaging, actions, identity) {
-  const base = agentRelayAgent(messaging, actions, identity.name);
+function assembleAgentClient(messaging, actions, identity, options) {
+  const base = agentRelayAgent(messaging, actions, identity.name, options);
   const handle = createAgentHandle(identity);
   return {
     ...base,
@@ -36069,11 +36313,13 @@ function generateRequestId(prefix = "") {
   MessageReactedPredicate,
   MessageReadPredicate,
   RelayCapabilityError,
+  RelayError,
   RelaycastMessagingClient,
   StaticPatterns,
   StatusPredicate,
   ToolCalledPredicate,
   TracedError,
+  TypedActionPredicate,
   actionSchemaToJsonSchema,
   agentRelayAgent,
   agentTokenRecoveryMessage,
@@ -36095,6 +36341,7 @@ function generateRequestId(prefix = "") {
   createRequestEnvelope,
   createRequestHandler,
   createTraceableError,
+  createTypedActionHandle,
   createWorkspaceFacade,
   defineHarness,
   findGitRoot,
@@ -36127,6 +36374,7 @@ function generateRequestId(prefix = "") {
   isSpawnOrReleaseCommandFast,
   isValidAgentName,
   logAndTraceError,
+  logRelayHandlerError,
   mapModelToCli,
   matchesSelector,
   nextHarnessName,