@ganglion/xacpx 0.23.0-beta.5 → 0.23.0-beta.7

package/dist/cli.js

@@ -28499,7 +28499,7 @@ function buildXacpxMcpToolRegistry(input) {
     })
   }, {
     name: "agent_send",
-    description: "Send a high-value asynchronous peer message to another agent. ONLY use this when: (1) you have critical information that directly alters the target's current work (e.g. breaking schema change, interface takeover), or (2) you need an unblocking decision only the target can provide. DO NOT send acknowledgments ('Received', 'OK', 'Working on it'), status polling ('Are you done?'), or conversational chatter. One-way notifications require NO reply. Provide replyTo when answering an earlier message. Completion modes: none (one-way message; no completion signal is returned), notify (after the peer turn triggered by this message reaches terminal state, xacpx notifies the sender that the peer completed/failed/cancelled), result (after the peer turn reaches terminal state, xacpx returns the peer's bounded final assistant result to the sender). Note agent_send still returns delivery admission immediately.",
+    description: "Send a high-value asynchronous peer message to another agent. ONLY use this when: (1) you have critical information that directly alters the target's current work (e.g. breaking schema change, interface takeover), or (2) you need an unblocking decision only the target can provide. DO NOT send acknowledgments ('Received', 'OK', 'Working on it'), status polling ('Are you done?'), or conversational chatter. One-way notifications require NO reply. Provide replyTo when answering an earlier message. Completion modes: none (one-way message; no completion signal is returned), notify (after the peer turn triggered by this message reaches terminal state, xacpx notifies the sender that the peer completed/failed/cancelled), result (after the peer turn reaches terminal state, xacpx returns the peer's bounded final assistant result to the sender). Note agent_send still returns delivery admission immediately. mode='interrupt' requests cancellation of the target Agent's current turn and reserves this message as its highest-priority next turn; xacpx waits for the current turn to fully settle before starting the message, and never runs the two turns in parallel. Some runtimes may finish the current turn instead of stopping immediately. Use interrupt only when waiting behind ordinary queued work would materially harm the task. The default/auto mode NEVER selects interrupt, and xacpx never escalates a message to interrupt based on its wording.",
     inputSchema: exports_external.object({
       to: exports_external.string().min(1).optional().describe("Target opaque handle from agent_list"),
       selector: exports_external.object({
@@ -28508,7 +28508,7 @@ function buildXacpxMcpToolRegistry(input) {
         agent: exports_external.string().min(1).optional().describe("Target agent type")
       }).strict().refine((s) => Boolean(s.displayName || s.workspace || s.agent), "Target selector must specify at least one criterion (displayName, workspace, or agent)").optional().describe("Target selector criteria when handle is not known"),
       message: exports_external.string().min(1).describe("Concise, actionable message content"),
-      mode: exports_external.enum(["auto", "steer", "queue", "interrupt"]).optional().describe("Delivery mode (default: auto -> queue)"),
+      mode: exports_external.enum(["auto", "steer", "queue", "interrupt"]).optional().describe("Delivery mode (default: auto -> queue). 'interrupt' REQUESTS cancellation of the target's current turn and reserves this message as its highest-priority next turn; xacpx waits for the current turn to fully settle first, and some runtimes may finish it instead of stopping immediately. 'auto' and 'queue' never cancel. 'steer' injects into the target's active turn when the runtime supports it."),
       replyTo: exports_external.string().min(1).optional().describe("Message ID being replied to, if continuing a thread"),
       completion: exports_external.enum(["none", "notify", "result"]).optional().describe("Completion notification mode: 'none' (one-way message; no completion signal is returned), 'notify' (notifies sender when peer turn reaches terminal state), or 'result' (returns peer's bounded final assistant result). Note agent_send still returns delivery admission immediately.")
     }).strict().refine((data) => data.to !== undefined && data.selector === undefined || data.to === undefined && data.selector !== undefined, {
@@ -50667,7 +50667,7 @@ class AgentEndpointRegistry {
       activity: {
         status: isRunning ? "working" : "idle"
       },
-      capabilities: queueOnlyCapabilities({ completion: true }),
+      capabilities: queueOnlyCapabilities({ completion: true, interrupt: true }),
       endpointKind: "logical",
       channelId: getChannelIdFromChatKey(session3.alias)
     };
@@ -50718,7 +50718,7 @@ function queueOnlyCapabilities(options) {
     receive: true,
     steer: false,
     queue: true,
-    interrupt: false,
+    interrupt: options?.interrupt ?? false,
     conversation: true,
     completion: options?.completion ?? false
   };
@@ -50981,7 +50981,8 @@ var init_agent_message_router = __esm(() => {
     "TARGET_UNAVAILABLE",
     "MESSAGE_QUEUE_FULL",
     "DELIVERY_DENIED",
-    "COMPLETION_NOT_SUPPORTED"
+    "COMPLETION_NOT_SUPPORTED",
+    "TARGET_NOT_INTERRUPTIBLE"
   ]);
   AgentMessageRouter = class AgentMessageRouter {
     deps;
@@ -51636,6 +51637,9 @@ var init_agent_message_router = __esm(() => {
         createdAt,
         ...input.replyTo ? { replyTo: input.replyTo } : {}
       };
+      if (message.requestedMode === "interrupt" && target.endpoint.capabilities.interrupt !== true) {
+        throw new AgentMessagingError("TARGET_NOT_INTERRUPTIBLE", "The target does not support explicit interrupt delivery.");
+      }
       if (message.completion !== "none") {
         if (target.endpoint.capabilities.completion !== true) {
           throw new AgentMessagingError("COMPLETION_NOT_SUPPORTED", `Completion mode '${message.completion}' requires a target that advertises completion capability.`);
@@ -52454,10 +52458,11 @@ class LocalAgentMessageDeliveryAdapter {
         source: message.from,
         target: message.to
       };
-      const res = await this.deps.deliverLogicalTurn(target.runtime.alias, renderedText, message.id, peerOrigin);
+      const res = await this.deps.deliverLogicalTurn(target.runtime.alias, renderedText, message.id, peerOrigin, message.requestedMode);
       return {
         status: res.status,
-        modeUsed: "queue"
+        modeUsed: res.modeUsed ?? "queue",
+        ...res.targetState ? { targetState: res.targetState } : {}
       };
     }
     const session3 = target.runtime.kind === "logical" ? await this.deps.resolveLogicalSession(target.runtime.transportSession) : this.deps.resolveWorkerSession(target.runtime);
@@ -60156,6 +60161,7 @@ class TurnQueue {
   settledRequestIds = new Map;
   static SETTLED_REQUEST_IDS_MAX = 2000;
   queues = new Map;
+  pendingInterrupts = new Map;
   draining = new Set;
   removing = new Set;
   resolveKey(chatKey, sessionAlias, concurrencyKey) {
@@ -60163,7 +60169,7 @@ class TurnQueue {
       return concurrencyKey;
     }
     const directKey = turnKey(chatKey, sessionAlias);
-    if (this.inFlight.has(directKey) || this.queues.has(directKey) || this.draining.has(directKey) || this.removing.has(directKey)) {
+    if (this.inFlight.has(directKey) || this.queues.has(directKey) || this.draining.has(directKey) || this.removing.has(directKey) || this.pendingInterrupts.has(directKey)) {
       return directKey;
     }
     const cleanAlias = sessionAlias.includes(":") ? sessionAlias.split(":").pop() : sessionAlias;
@@ -60183,6 +60189,10 @@ class TurnQueue {
       if (k === directKey || k.endsWith(":" + cleanAlias) || k.endsWith(" " + cleanAlias) || k === cleanAlias)
         return k;
     }
+    for (const k of this.pendingInterrupts.keys()) {
+      if (k === directKey || k.endsWith(":" + cleanAlias) || k.endsWith(" " + cleanAlias) || k === cleanAlias)
+        return k;
+    }
     return directKey;
   }
   queueLength(chatKey, sessionAlias, concurrencyKey) {
@@ -60254,6 +60264,99 @@ class TurnQueue {
     this.recordSettledRequestId(params.promptRequestId);
     return { status: "injected" };
   }
+  pendingInterruptCount(chatKey, sessionAlias, concurrencyKey) {
+    return this.pendingInterrupts.has(this.resolveKey(chatKey, sessionAlias, concurrencyKey)) ? 1 : 0;
+  }
+  submitPeerInterrupt(params) {
+    const key = this.resolveKey(params.chatKey, params.sessionAlias, params.concurrencyKey);
+    if (this.removing.has(key)) {
+      return { status: "rejected", reason: "target-unavailable" };
+    }
+    if (params.promptRequestId !== undefined && params.isPeerMessage) {
+      const pendingDup = this.pendingInterrupts.get(key);
+      if (pendingDup?.promptRequestId === params.promptRequestId) {
+        return { status: "queued", modeUsed: "interrupt", queueItemId: pendingDup.id };
+      }
+      if (this.hasSettledRequestId(params.promptRequestId)) {
+        return { status: "injected", modeUsed: "prompt" };
+      }
+      const queuedDup = (this.queues.get(key) ?? []).some((item2) => item2.promptRequestId === params.promptRequestId);
+      const inFlightDup = this.inFlight.get(key)?.promptRequestId === params.promptRequestId;
+      if (queuedDup || inFlightDup) {
+        return { status: "injected", modeUsed: "prompt" };
+      }
+    }
+    const existing = this.inFlight.get(key);
+    const busy = this.draining.has(key) || existing !== undefined;
+    if (!busy) {
+      const idle = this.submitPeerTurn(params);
+      if (idle.status === "rejected")
+        return idle;
+      if (idle.status === "queued") {
+        return { status: "rejected", reason: "queue-full" };
+      }
+      return { status: "injected", modeUsed: "prompt" };
+    }
+    const pending = this.pendingInterrupts.get(key);
+    if (pending) {
+      this.emitPeerInterrupt("rejected_pending", params.chatKey, params.sessionAlias, pending, {
+        requestMessageId: params.peerOrigin?.requestMessageId,
+        promptRequestId: params.promptRequestId,
+        pendingRequestMessageId: pending.peerOrigin?.requestMessageId
+      });
+      return { status: "rejected", reason: "queue-full" };
+    }
+    const id = randomUUID13();
+    const item = {
+      id,
+      text: params.text,
+      enqueuedAt: new Date().toISOString(),
+      senderId: params.senderId,
+      executionContext: {
+        chatKey: params.chatKey,
+        sessionAlias: params.sessionAlias,
+        ...params.boundSessionAlias ? { boundSessionAlias: params.boundSessionAlias } : {}
+      },
+      concurrencyKey: params.concurrencyKey,
+      isPeerMessage: true,
+      allowRestoreArchived: false,
+      ...params.isOwner !== undefined ? { isOwner: params.isOwner } : {},
+      ...params.preserveCoordinatorRoute !== undefined ? { preserveCoordinatorRoute: params.preserveCoordinatorRoute } : {},
+      ...params.accountId !== undefined ? { accountId: params.accountId } : {},
+      ...params.media !== undefined ? { media: params.media } : {},
+      ...params.agentMentions !== undefined ? { agentMentions: params.agentMentions } : {},
+      ...params.promptRequestId !== undefined ? { promptRequestId: params.promptRequestId } : {},
+      ...params.peerOrigin !== undefined ? { peerOrigin: params.peerOrigin } : {},
+      ...params.trustedPeerCompletion !== undefined ? { trustedPeerCompletion: params.trustedPeerCompletion } : {}
+    };
+    this.pendingInterrupts.set(key, item);
+    this.recordSettledRequestId(params.promptRequestId);
+    const predecessorWasAlreadyAborted = existing?.controller.signal.aborted ?? false;
+    this.emitPeerInterrupt("reserved", params.chatKey, params.sessionAlias, item, {
+      predecessorWasAlreadyAborted
+    });
+    if (existing && !predecessorWasAlreadyAborted) {
+      existing.controller.abort();
+      this.emitPeerInterrupt("abort_signalled", params.chatKey, params.sessionAlias, item);
+    }
+    this.emitQueueUpdated(params.chatKey, params.sessionAlias, key);
+    return { status: "queued", modeUsed: "interrupt", queueItemId: id };
+  }
+  emitPeerInterrupt(kind, chatKey, sessionAlias, item, ids) {
+    if (!this.deps.onPeerInterruptEvent)
+      return;
+    try {
+      this.deps.onPeerInterruptEvent({
+        kind,
+        chatKey,
+        sessionAlias,
+        ...ids?.requestMessageId !== undefined ? { requestMessageId: ids.requestMessageId } : item?.peerOrigin?.requestMessageId !== undefined ? { requestMessageId: item.peerOrigin.requestMessageId } : {},
+        ...ids?.promptRequestId !== undefined ? { promptRequestId: ids.promptRequestId } : item?.promptRequestId !== undefined ? { promptRequestId: item.promptRequestId } : {},
+        ...ids?.pendingRequestMessageId !== undefined ? { pendingRequestMessageId: ids.pendingRequestMessageId } : {},
+        ...ids?.predecessorWasAlreadyAborted !== undefined ? { predecessorWasAlreadyAborted: ids.predecessorWasAlreadyAborted } : {}
+      });
+    } catch {}
+  }
   hasSettledRequestId(id) {
     const expiresAt = this.settledRequestIds.get(id);
     if (expiresAt === undefined)
@@ -60293,11 +60396,20 @@ class TurnQueue {
   }
   emitQueueUpdated(chatKey, sessionAlias, queueKey) {
     const key = queueKey ?? this.resolveKey(chatKey, sessionAlias);
-    const items = (this.queues.get(key) ?? []).map((q) => ({
-      id: q.id,
-      textPreview: q.text.length > QUEUE_PREVIEW_MAX ? q.text.slice(0, QUEUE_PREVIEW_MAX) : q.text,
-      enqueuedAt: q.enqueuedAt
-    }));
+    const interrupt = this.pendingInterrupts.get(key);
+    const items = interrupt ? [{
+      id: interrupt.id,
+      textPreview: interrupt.text.length > QUEUE_PREVIEW_MAX ? interrupt.text.slice(0, QUEUE_PREVIEW_MAX) : interrupt.text,
+      enqueuedAt: interrupt.enqueuedAt,
+      kind: "interrupt"
+    }] : [];
+    for (const q of this.queues.get(key) ?? []) {
+      items.push({
+        id: q.id,
+        textPreview: q.text.length > QUEUE_PREVIEW_MAX ? q.text.slice(0, QUEUE_PREVIEW_MAX) : q.text,
+        enqueuedAt: q.enqueuedAt
+      });
+    }
     this.deps.emitQueueUpdated(chatKey, sessionAlias, items);
   }
   async submit(params) {
@@ -60397,6 +60509,7 @@ class TurnQueue {
     };
     let result;
     try {
+      const turnStarted = params.turnStarted ? params.promptRequestId !== undefined && params.turnStarted.promptRequestId === undefined ? { ...params.turnStarted, promptRequestId: params.promptRequestId } : params.turnStarted : params.promptRequestId !== undefined ? { promptRequestId: params.promptRequestId } : undefined;
       result = await this.deps.runTurn({
         chatKey: params.chatKey,
         sessionAlias: params.sessionAlias,
@@ -60405,7 +60518,7 @@ class TurnQueue {
         senderId: params.senderId,
         isOwner: params.isOwner,
         accountId: params.accountId,
-        turnStarted: params.turnStarted,
+        turnStarted,
         media: params.media,
         agentMentions: params.agentMentions,
         allowRestoreArchived: params.allowRestoreArchived,
@@ -60418,7 +60531,7 @@ class TurnQueue {
     } finally {
       if (idleTimer)
         this.clearTimer(idleTimer);
-      if ((this.queues.get(key)?.length ?? 0) > 0) {
+      if ((this.queues.get(key)?.length ?? 0) > 0 || this.pendingInterrupts.has(key)) {
         this.draining.add(key);
       }
       const detection = result?.postTurnDetection;
@@ -60435,40 +60548,50 @@ class TurnQueue {
     };
   }
   advanceQueue(key) {
+    const interrupt = this.pendingInterrupts.get(key);
+    if (interrupt) {
+      this.pendingInterrupts.delete(key);
+      this.emitPeerInterrupt("started", interrupt.executionContext.chatKey, interrupt.executionContext.sessionAlias, interrupt);
+      this.drainQueuedPrompt(key, interrupt);
+      return;
+    }
     const q = this.queues.get(key);
     const next = q?.shift();
     if (q && q.length === 0)
       this.queues.delete(key);
     if (next) {
-      this.emitQueueUpdated(next.executionContext.chatKey, next.executionContext.sessionAlias, key);
-      const concurrencyKey = next.concurrencyKey ?? key;
-      const turnStarted = next.isPeerMessage ? { queueItemId: next.id, ...next.promptRequestId !== undefined ? { promptRequestId: next.promptRequestId } : {} } : { prompt: next.text, queueItemId: next.id, ...next.promptRequestId !== undefined ? { promptRequestId: next.promptRequestId } : {} };
-      this.submit({
-        chatKey: next.executionContext.chatKey,
-        sessionAlias: next.executionContext.sessionAlias,
-        boundSessionAlias: next.executionContext.boundSessionAlias,
-        concurrencyKey,
-        text: next.text,
-        senderId: next.senderId,
-        queueable: true,
-        drained: true,
-        isPeerMessage: next.isPeerMessage,
-        allowRestoreArchived: next.allowRestoreArchived,
-        preserveCoordinatorRoute: next.preserveCoordinatorRoute,
-        promptRequestId: next.promptRequestId,
-        peerOrigin: next.peerOrigin,
-        trustedPeerCompletion: next.trustedPeerCompletion,
-        ...next.isOwner !== undefined ? { isOwner: next.isOwner } : {},
-        ...next.accountId !== undefined ? { accountId: next.accountId } : {},
-        ...next.media !== undefined ? { media: next.media } : {},
-        ...next.agentMentions !== undefined ? { agentMentions: next.agentMentions } : {},
-        turnStarted
-      });
+      this.drainQueuedPrompt(key, next);
     } else {
       this.draining.delete(key);
       this.inFlight.delete(key);
     }
   }
+  drainQueuedPrompt(key, next) {
+    this.emitQueueUpdated(next.executionContext.chatKey, next.executionContext.sessionAlias, key);
+    const concurrencyKey = next.concurrencyKey ?? key;
+    const turnStarted = next.isPeerMessage ? { queueItemId: next.id, ...next.promptRequestId !== undefined ? { promptRequestId: next.promptRequestId } : {} } : { prompt: next.text, queueItemId: next.id, ...next.promptRequestId !== undefined ? { promptRequestId: next.promptRequestId } : {} };
+    this.submit({
+      chatKey: next.executionContext.chatKey,
+      sessionAlias: next.executionContext.sessionAlias,
+      boundSessionAlias: next.executionContext.boundSessionAlias,
+      concurrencyKey,
+      text: next.text,
+      senderId: next.senderId,
+      queueable: true,
+      drained: true,
+      isPeerMessage: next.isPeerMessage,
+      allowRestoreArchived: next.allowRestoreArchived,
+      preserveCoordinatorRoute: next.preserveCoordinatorRoute,
+      promptRequestId: next.promptRequestId,
+      peerOrigin: next.peerOrigin,
+      trustedPeerCompletion: next.trustedPeerCompletion,
+      ...next.isOwner !== undefined ? { isOwner: next.isOwner } : {},
+      ...next.accountId !== undefined ? { accountId: next.accountId } : {},
+      ...next.media !== undefined ? { media: next.media } : {},
+      ...next.agentMentions !== undefined ? { agentMentions: next.agentMentions } : {},
+      turnStarted
+    });
+  }
   cancelTurn(chatKey, sessionAlias, concurrencyKey) {
     const key = this.resolveKey(chatKey, sessionAlias, concurrencyKey);
     const entry = this.inFlight.get(key);
@@ -60480,12 +60603,21 @@ class TurnQueue {
   }
   async clearSession(chatKey, sessionAlias, concurrencyKey) {
     const key = this.resolveKey(chatKey, sessionAlias, concurrencyKey);
+    const guardPreexisting = this.removing.has(key);
+    this.removing.add(key);
     const droppedFirst = this.queues.get(key);
     if (droppedFirst) {
       this.queues.delete(key);
       this.emitQueueUpdated(chatKey, sessionAlias, key);
       this.notifyQueuedPeerCancelled(droppedFirst);
     }
+    const droppedInterruptFirst = this.pendingInterrupts.get(key);
+    if (droppedInterruptFirst) {
+      this.pendingInterrupts.delete(key);
+      this.emitPeerInterrupt("cancelled_before_start", droppedInterruptFirst.executionContext.chatKey, droppedInterruptFirst.executionContext.sessionAlias, droppedInterruptFirst);
+      this.notifyQueuedPeerCancelled([droppedInterruptFirst]);
+      this.emitQueueUpdated(chatKey, sessionAlias, key);
+    }
     const entry = this.inFlight.get(key);
     if (entry) {
       entry.controller.abort();
@@ -60496,10 +60628,17 @@ class TurnQueue {
         this.emitQueueUpdated(chatKey, sessionAlias, key);
         this.notifyQueuedPeerCancelled(droppedSecond);
       }
+      const droppedInterruptSecond = this.pendingInterrupts.get(key);
+      if (droppedInterruptSecond) {
+        this.pendingInterrupts.delete(key);
+        this.emitPeerInterrupt("cancelled_before_start", droppedInterruptSecond.executionContext.chatKey, droppedInterruptSecond.executionContext.sessionAlias, droppedInterruptSecond);
+        this.notifyQueuedPeerCancelled([droppedInterruptSecond]);
+        this.emitQueueUpdated(chatKey, sessionAlias, key);
+      }
     }
-    const cleared = !this.inFlight.has(key) && !this.draining.has(key);
-    if (cleared) {
-      this.removing.add(key);
+    const cleared = !this.inFlight.has(key) && !this.draining.has(key) && !this.pendingInterrupts.has(key);
+    if (cleared) {} else if (!guardPreexisting) {
+      this.removing.delete(key);
     }
     return { cleared };
   }
@@ -60508,6 +60647,14 @@ class TurnQueue {
   }
   cancelQueuedItem(chatKey, sessionAlias, itemId, concurrencyKey) {
     const key = this.resolveKey(chatKey, sessionAlias, concurrencyKey);
+    const pendingInterrupt = this.pendingInterrupts.get(key);
+    if (pendingInterrupt?.id === itemId) {
+      this.pendingInterrupts.delete(key);
+      this.emitQueueUpdated(chatKey, sessionAlias, key);
+      this.emitPeerInterrupt("cancelled_before_start", pendingInterrupt.executionContext.chatKey, pendingInterrupt.executionContext.sessionAlias, pendingInterrupt);
+      this.notifyQueuedPeerCancelled([pendingInterrupt]);
+      return { cancelled: true };
+    }
     const q = this.queues.get(key);
     if (!q)
       return { cancelled: false };
@@ -60578,6 +60725,7 @@ class ControlService {
       ...this.deps.onTurnIdleTimeout ? { onIdleTimeout: this.deps.onTurnIdleTimeout } : {},
       ...this.deps.cancelDrainTimeoutMs !== undefined ? { cancelDrainTimeoutMs: this.deps.cancelDrainTimeoutMs } : {},
       ...this.deps.onQueuedPeerCancelled ? { onQueuedPeerCancelled: this.deps.onQueuedPeerCancelled } : {},
+      ...this.deps.onPeerInterruptEvent ? { onPeerInterruptEvent: this.deps.onPeerInterruptEvent } : {},
       emitQueueUpdated: (chatKey, sessionAlias, items) => this.deps.events.emit({
         type: "queue-updated",
         chatKey,
@@ -60865,6 +61013,7 @@ class ControlService {
       return {
         alias: toDisplaySessionAlias(session3.alias),
         agent: session3.agent,
+        driver: session3.driver,
         workspace: session3.workspace,
         transportSession: session3.transportSession,
         running,
@@ -61101,7 +61250,7 @@ class ControlService {
     if (!session3 || session3.archived === true) {
       throw new AgentMessagingError("TARGET_UNAVAILABLE", "The target Agent session is not currently available or is archived.");
     }
-    const admission = this.turnQueue.submitPeerTurn({
+    const peerParams = {
       chatKey: input.chatKey,
       sessionAlias: input.sessionAlias,
       boundSessionAlias: internalAlias,
@@ -61113,17 +61262,28 @@ class ControlService {
       allowRestoreArchived: false,
       preserveCoordinatorRoute: true,
       peerOrigin: input.peerOrigin
-    });
-    if (admission.status === "rejected") {
-      if (admission.reason === "queue-full") {
-        throw new AgentMessagingError("MESSAGE_QUEUE_FULL", "The target Agent's message queue is full.");
-      }
-      if (admission.reason === "target-unavailable") {
-        throw new AgentMessagingError("TARGET_UNAVAILABLE", "The target Agent session is currently being removed or archived.");
+    };
+    if (input.requestedMode === "interrupt") {
+      const admission2 = this.turnQueue.submitPeerInterrupt(peerParams);
+      if (admission2.status === "rejected") {
+        this.throwPeerAdmissionError(admission2.reason, "interrupt");
       }
-      throw new AgentMessagingError("DELIVERY_FAILED", `Peer turn admission rejected: ${admission.reason}`);
+      return admission2.status === "injected" ? { status: "injected", modeUsed: "prompt", targetState: "idle" } : { status: "queued", modeUsed: "interrupt", targetState: "running" };
+    }
+    const admission = this.turnQueue.submitPeerTurn(peerParams);
+    if (admission.status === "rejected") {
+      this.throwPeerAdmissionError(admission.reason, "peer");
     }
-    return { status: admission.status };
+    return { status: admission.status, modeUsed: "queue" };
+  }
+  throwPeerAdmissionError(reason, mode) {
+    if (reason === "queue-full") {
+      throw new AgentMessagingError("MESSAGE_QUEUE_FULL", mode === "interrupt" ? "The target Agent already has a pending peer interrupt; only one interrupt may be reserved at a time." : "The target Agent's message queue is full.");
+    }
+    if (reason === "target-unavailable") {
+      throw new AgentMessagingError("TARGET_UNAVAILABLE", "The target Agent session is currently being removed or archived.");
+    }
+    throw new AgentMessagingError("DELIVERY_FAILED", `Peer turn admission rejected: ${reason}`);
   }
   async submitCompletionTurn(input) {
     const session3 = await this.deps.sessions.getSession(input.sourceAlias);
@@ -61234,9 +61394,9 @@ var init_control_service = __esm(() => {
   init_native_session_history();
   init_workspace_fs();
   init_workspace_git();
+  init_turn_support();
   init_session_turn_runner();
   init_turn_queue();
-  init_turn_support();
   init_command_timeouts();
   MODEL_SET_SETTLE_BUDGET_MS = 2 * (DEFAULT_MANAGEMENT_COMMAND_TIMEOUT_MS + BRIDGE_REQUEST_TIMEOUT_GRACE_MS);
 });
@@ -62892,7 +63052,7 @@ async function buildApp(paths, deps = {}) {
         return null;
       }
     },
-    deliverLogicalTurn: async (alias, renderedText, messageId, peerOrigin) => {
+    deliverLogicalTurn: async (alias, renderedText, messageId, peerOrigin, requestedMode) => {
       if (controlRef) {
         const chatKey = `relay:agent-message:${alias}`;
         return await controlRef.submitPeerTurn({
@@ -62902,10 +63062,11 @@ async function buildApp(paths, deps = {}) {
           text: renderedText,
           senderId: "agent-messaging",
           messageId,
+          requestedMode,
           peerOrigin
         });
       }
-      return { status: "queued" };
+      return { status: "queued", modeUsed: "queue" };
     },
     deliverCompletionTurn: async (alias, completion, requestMessageId) => {
       if (controlRef) {
@@ -63090,6 +63251,16 @@ async function buildApp(paths, deps = {}) {
         idleMs
       });
     },
+    onPeerInterruptEvent: (event) => {
+      logger.info(`agent_messaging.peer_interrupt_${event.kind}`, "peer interrupt lane event", {
+        chatKey: event.chatKey,
+        sessionAlias: event.sessionAlias,
+        ...event.requestMessageId !== undefined ? { requestMessageId: event.requestMessageId } : {},
+        ...event.promptRequestId !== undefined ? { promptRequestId: event.promptRequestId } : {},
+        ...event.pendingRequestMessageId !== undefined ? { pendingRequestMessageId: event.pendingRequestMessageId } : {},
+        ...event.predecessorWasAlreadyAborted !== undefined ? { predecessorWasAlreadyAborted: event.predecessorWasAlreadyAborted } : {}
+      });
+    },
     agentMessaging: {
       deliverInbound: async (input) => await agentMessaging.deliverInbound(input),
       deliverInboundCompletion: async (input) => await agentMessaging.deliverInboundCompletion(input),

package/dist/control/control-event-bus.d.ts

@@ -14,6 +14,9 @@ export interface QueuedItemInfo {
     id: string;
     textPreview: string;
     enqueuedAt: string;
+    /** v0.4: present ONLY for a reserved-but-not-started peer interrupt
+     *  (snapshot-first item). Additive and backward compatible. */
+    kind?: "interrupt";
 }
 export type ControlEvent = {
     type: "turn-output";

package/dist/control/control-service.d.ts

@@ -6,15 +6,16 @@ import type { CreateScheduledTaskInput, ScheduledTaskService } from "../schedule
 import type { ScheduledTaskRecord } from "../scheduled/scheduled-types";
 import type { CancelTaskInput, OrchestrationService, OrchestrationTaskFilter } from "../orchestration/orchestration-service";
 import type { OrchestrationTaskRecord } from "../orchestration/orchestration-types";
-import type { AgentMessageCompletion } from "../orchestration/agent-messaging-types";
+import type { AgentMessageCompletion, AgentMessageMode } from "../orchestration/agent-messaging-types";
 import type { ControlEventBus } from "./control-event-bus";
 import type { AgentCatalogEntry } from "../config/agent-catalog";
 import { type BrowseDirsResult, type DirListing, type FileContent, type SearchOptions, type SearchResult, type WorkspaceDiff } from "./workspace-fs";
 import { type GitCheckoutOptions, type GitCommitResult, type GitPushOptions, type GitStatus, type GitWorktreeCreateOptions, type GitWorktreeCreateResult } from "./workspace-git";
 import type { AgentEndpointView, AgentMessageTraceRecord } from "../orchestration/agent-messaging-types";
 import type { PromptAttachmentRef } from "@ganglion/xacpx-relay-protocol";
-import type { UploadStore } from "./upload-store.js";
 import { type TurnIdleTimeoutDetail, type PeerTurnOrigin } from "./turn-support";
+import type { PeerInterruptEvent } from "./turn-queue";
+import type { UploadStore } from "./upload-store.js";
 import type { AppLogger } from "../logging/app-logger";
 export interface ModelSetRequestOptions {
     /** Connector-side deadline derived from the Hub request lifetime. */
@@ -23,6 +24,12 @@ export interface ModelSetRequestOptions {
 export interface ControlSessionInfo {
     alias: string;
     agent: string;
+    /** The acpx driver backing `agent`, resolved from the agent's config at listing
+     *  time. Lets the web render the brand icon without an agents-map lookup — which
+     *  fails for sleeping sessions whose rows live outside the active session list.
+     *  Optional: mirrors ResolvedSession.driver (custom agents always resolve one,
+     *  but the type stays tolerant). */
+    driver?: string;
     workspace: string;
     transportSession: string;
     running: boolean;
@@ -111,6 +118,7 @@ export interface ControlServiceDeps {
         peerOrigin: PeerTurnOrigin;
         promptRequestId?: string;
     }) => void;
+    onPeerInterruptEvent?: (event: PeerInterruptEvent) => void;
     agentMessaging?: {
         deliverInbound(input: {
             sourceNodeId: string;
@@ -394,10 +402,17 @@ export declare class ControlService {
         text: string;
         senderId: string;
         messageId: string;
+        /** v0.4: "interrupt" routes through TurnQueue.submitPeerInterrupt (reserve →
+         *  abort → true-settle → priority drain); every other mode keeps the
+         *  non-cancelling peer path. */
+        requestedMode?: AgentMessageMode;
         peerOrigin?: PeerTurnOrigin;
     }): Promise<{
         status: "injected" | "queued";
+        modeUsed: "prompt" | "queue" | "interrupt";
+        targetState?: "idle" | "running";
     }>;
+    private throwPeerAdmissionError;
     submitCompletionTurn(input: {
         sourceAlias: string;
         completion: AgentMessageCompletion;

package/dist/control/turn-queue.d.ts

@@ -5,6 +5,10 @@ export interface QueuedItemSnapshot {
     id: string;
     textPreview: string;
     enqueuedAt: string;
+    /** v0.4: present ONLY for a reserved-but-not-started peer interrupt
+     *  (snapshot-first item). Lets the existing per-item cancel surface reach
+     *  the interrupt slot by id (spec §11.1) without a new RPC. */
+    kind?: "interrupt";
 }
 export interface TurnQueueDeps {
     runTurn(req: TurnRequest, signal: AbortSignal, onActivity: () => void): Promise<TurnResult>;
@@ -21,6 +25,20 @@ export interface TurnQueueDeps {
         peerOrigin: PeerTurnOrigin;
         promptRequestId?: string;
     }) => void;
+    onPeerInterruptEvent?: (event: PeerInterruptEvent) => void;
+}
+/** v0.4: structured peer-interrupt lifecycle event (spec §17). Ids and lane
+ *  keys only — never message content. */
+export interface PeerInterruptEvent {
+    kind: "reserved" | "abort_signalled" | "started" | "cancelled_before_start" | "rejected_pending";
+    chatKey: string;
+    sessionAlias: string;
+    requestMessageId?: string;
+    promptRequestId?: string;
+    /** rejected_pending only: requestMessageId of the reservation that occupied
+     *  the slot (the event's own ids describe the REJECTED request). */
+    pendingRequestMessageId?: string;
+    predecessorWasAlreadyAborted?: boolean;
 }
 export interface SubmitParams {
     chatKey: string;
@@ -42,6 +60,7 @@ export interface SubmitParams {
     allowRestoreArchived?: boolean;
     preserveCoordinatorRoute?: boolean;
     /** Hub-issued pre-write correlation; stored on the queue item and carried onto the
+  
      *  drained turn-started so the hub can correlate a queue item back to its
      *  pre-written inbound row (see PromptPayload.promptRequestId). */
     promptRequestId?: string;
@@ -56,6 +75,23 @@ export type SubmitResult = TurnResult | {
     queued: true;
     queueItemId: string;
 };
+/** v0.4: result of `submitPeerInterrupt`. `queued`+`interrupt` = busy target:
+ * the reservation is held and the predecessor cancel has been signalled.
+ * `injected`+`prompt` = idle target: ordinary synchronous peer admission with
+ * zero cancellations. Rejections reuse the existing reasons ("target-unavailable",
+ * "queue-full" — the latter also enforces the one-pending-interrupt slot rule,
+ * spec §8/§16). */
+export type PeerInterruptAdmission = {
+    status: "injected";
+    modeUsed: "prompt";
+} | {
+    status: "queued";
+    modeUsed: "interrupt";
+    queueItemId: string;
+} | {
+    status: "rejected";
+    reason: string;
+};
 export declare class TurnQueue {
     private readonly deps;
     private readonly setTimer;
@@ -72,6 +108,7 @@ export declare class TurnQueue {
     private readonly settledRequestIds;
     private static readonly SETTLED_REQUEST_IDS_MAX;
     private readonly queues;
+    private readonly pendingInterrupts;
     private readonly draining;
     private readonly removing;
     private resolveKey;
@@ -83,6 +120,20 @@ export declare class TurnQueue {
         status: "rejected";
         reason: string;
     };
+    /** v0.4 test/observability seam: 1 when a reserved-but-not-started peer
+     *  interrupt occupies the lane's slot, else 0 (spec §7: at most one). */
+    pendingInterruptCount(chatKey: string, sessionAlias: string, concurrencyKey?: string): number;
+    /**
+     * v0.4 Peer Interrupt Delivery (spec §6.4/§9): atomic reserve → abort →
+     * true-settle → priority-drain, owned entirely by this lane. Synchronous:
+     * by the time the accepted result returns, the reservation exists in the
+     * lane and a live predecessor's AbortController has been signalled. The
+     * interrupting turn itself starts only after the predecessor's `settled`
+     * resolves and its inFlight entry is gone (drain hand-off in advanceQueue).
+     * Router-level cancel();submit() races are impossible by construction here.
+     */
+    submitPeerInterrupt(params: SubmitParams): PeerInterruptAdmission;
+    private emitPeerInterrupt;
     private hasSettledRequestId;
     private recordSettledRequestId;
     /** Terminal cancellation for queued peer items dropped before execution. */
@@ -90,6 +141,7 @@ export declare class TurnQueue {
     private emitQueueUpdated;
     submit(params: SubmitParams): Promise<SubmitResult>;
     private advanceQueue;
+    private drainQueuedPrompt;
     cancelTurn(chatKey: string, sessionAlias: string, concurrencyKey?: string): boolean;
     /** Tear down all turn state for a session that is being removed or archived: drop every
      *  queued prompt, abort a running turn, and wait (bounded) for it to unwind. The queue is
@@ -104,9 +156,14 @@ export declare class TurnQueue {
      *  in-flight turn and dropped every queued prompt (emitting `queue-updated([])`). The caller
      *  should surface a retry, not present the failure as a no-op.
      *
-     *  On `cleared: true` it arms a teardown guard (the busy gate now rejects new turns for this
-     *  session) so a scheduled turn cannot cold-start during the caller's transport teardown. The
-     *  caller MUST call `finishClear` once teardown settles (success or failure) to release it. */
+     *  The teardown guard (`removing`) is armed SYNCHRONOUSLY on ENTRY — before
+     *  any await — so peer admissions (`submitPeerTurn` / `submitPeerInterrupt`)
+     *  fail closed `target-unavailable` for the ENTIRE clear lifecycle; a peer
+     *  interrupt arriving mid-unwind can never be reserved and drained onto the
+     *  dying session. On `cleared: true` the guard stays armed across the
+     *  caller's transport teardown; on `cleared: false` it is released so a
+     *  retry sees a usable lane. The caller MUST call `finishClear` once
+     *  teardown settles (success or failure) to release the guard. */
     clearSession(chatKey: string, sessionAlias: string, concurrencyKey?: string): Promise<{
         cleared: boolean;
     }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganglion/xacpx",
-  "version": "0.23.0-beta.5",
+  "version": "0.23.0-beta.7",
   "description": "随时随地通过聊天频道（微信 / 飞书 / 元宝等）远程控制 `acpx` 上的 Claude Code、Codex 等 Agents。",
   "keywords": [
     "acpx",