@openacp/cli 2026.410.3 → 2026.414.1

package/dist/index.js

@@ -793,6 +793,8 @@ var init_events = __esm({
       TURN_START: "turn:start",
       /** Turn ended (always fires, even on error) — read-only, fire-and-forget. */
       TURN_END: "turn:end",
+      /** After a turn completes — full assembled agent text, read-only, fire-and-forget. */
+      AGENT_AFTER_TURN: "agent:afterTurn",
       // --- Session lifecycle ---
       /** Before a new session is created — modifiable, can block. */
       SESSION_BEFORE_CREATE: "session:beforeCreate",
@@ -850,6 +852,8 @@ var init_events = __esm({
       MESSAGE_QUEUED: "message:queued",
       /** Fired when a queued message starts processing. */
       MESSAGE_PROCESSING: "message:processing",
+      /** Fired when a queued message is rejected (e.g. blocked by middleware). */
+      MESSAGE_FAILED: "message:failed",
       // --- System lifecycle ---
       /** Fired after kernel (core + plugin infrastructure) has booted. */
       KERNEL_BOOTED: "kernel:booted",
@@ -870,7 +874,22 @@ var init_events = __esm({
       PLUGIN_UNLOADED: "plugin:unloaded",
       // --- Usage ---
       /** Fired when a token usage record is captured (consumed by usage plugin). */
-      USAGE_RECORDED: "usage:recorded"
+      USAGE_RECORDED: "usage:recorded",
+      // --- Identity lifecycle ---
+      /** Fired when a new user+identity record is created. */
+      IDENTITY_CREATED: "identity:created",
+      /** Fired when user profile fields change. */
+      IDENTITY_UPDATED: "identity:updated",
+      /** Fired when two identities are linked (same person). */
+      IDENTITY_LINKED: "identity:linked",
+      /** Fired when an identity is unlinked into a new user. */
+      IDENTITY_UNLINKED: "identity:unlinked",
+      /** Fired when two user records are merged during a link operation. */
+      IDENTITY_USER_MERGED: "identity:userMerged",
+      /** Fired when a user's role changes. */
+      IDENTITY_ROLE_CHANGED: "identity:roleChanged",
+      /** Fired when a user is seen (throttled). */
+      IDENTITY_SEEN: "identity:seen"
     };
     SessionEv = {
       /** Agent produced an event (text, tool_call, etc.) during a turn. */
@@ -2829,14 +2848,20 @@ var init_api_client = __esm({
 });
 
 // src/plugins/notifications/notification.ts
-var NotificationManager;
+var NotificationService;
 var init_notification = __esm({
   "src/plugins/notifications/notification.ts"() {
     "use strict";
-    NotificationManager = class {
+    NotificationService = class {
       constructor(adapters) {
         this.adapters = adapters;
       }
+      identityResolver;
+      /** Inject identity resolver for user-targeted notifications. */
+      setIdentityResolver(resolver) {
+        this.identityResolver = resolver;
+      }
+      // --- Legacy API (backward compat with NotificationManager) ---
       /**
        * Send a notification to a specific channel adapter.
        *
@@ -2865,6 +2890,62 @@ var init_notification = __esm({
           }
         }
       }
+      // --- New user-targeted API ---
+      /**
+       * Send a notification to a user across all their linked platforms.
+       * Fire-and-forget — never throws, swallows all errors.
+       */
+      async notifyUser(target, message, options) {
+        try {
+          await this._resolveAndDeliver(target, message, options);
+        } catch {
+        }
+      }
+      async _resolveAndDeliver(target, message, options) {
+        if ("channelId" in target && "platformId" in target) {
+          const adapter = this.adapters.get(target.channelId);
+          if (!adapter?.sendUserNotification) return;
+          await adapter.sendUserNotification(target.platformId, message, {
+            via: options?.via,
+            topicId: options?.topicId,
+            sessionId: options?.sessionId
+          });
+          return;
+        }
+        if (!this.identityResolver) return;
+        let identities = [];
+        if ("identityId" in target) {
+          const identity = await this.identityResolver.getIdentity(target.identityId);
+          if (!identity) return;
+          const user = await this.identityResolver.getUser(identity.userId);
+          if (!user) return;
+          identities = await this.identityResolver.getIdentitiesFor(user.userId);
+        } else if ("userId" in target) {
+          identities = await this.identityResolver.getIdentitiesFor(target.userId);
+        }
+        if (options?.onlyPlatforms) {
+          identities = identities.filter((i) => options.onlyPlatforms.includes(i.source));
+        }
+        if (options?.excludePlatforms) {
+          identities = identities.filter((i) => !options.excludePlatforms.includes(i.source));
+        }
+        for (const identity of identities) {
+          const adapter = this.adapters.get(identity.source);
+          if (!adapter?.sendUserNotification) continue;
+          try {
+            await adapter.sendUserNotification(identity.platformId, message, {
+              via: options?.via,
+              topicId: options?.topicId,
+              sessionId: options?.sessionId,
+              platformMention: {
+                platformUsername: identity.platformUsername,
+                platformId: identity.platformId
+              }
+            });
+          } catch {
+          }
+        }
+      }
     };
   }
 });
@@ -3356,9 +3437,16 @@ async function createApiServer(options) {
   });
   const authPreHandler = createAuthPreHandler(options.getSecret, options.getJwtSecret, options.tokenStore);
   app.decorateRequest("auth", null, []);
+  let booted = false;
+  app.addHook("onReady", async () => {
+    booted = true;
+  });
   return {
     app,
     registerPlugin(prefix, plugin, opts) {
+      if (booted) {
+        return;
+      }
       const wrappedPlugin = async (pluginApp, pluginOpts) => {
         if (opts?.auth !== false) {
           pluginApp.addHook("onRequest", authPreHandler);
@@ -3452,7 +3540,8 @@ var init_sse_manager = __esm({
           BusEvent.PERMISSION_REQUEST,
           BusEvent.PERMISSION_RESOLVED,
           BusEvent.MESSAGE_QUEUED,
-          BusEvent.MESSAGE_PROCESSING
+          BusEvent.MESSAGE_PROCESSING,
+          BusEvent.MESSAGE_FAILED
         ];
         for (const eventName of events) {
           const handler = (data) => {
@@ -3534,7 +3623,8 @@ data: ${JSON.stringify(data)}
           BusEvent.PERMISSION_RESOLVED,
           BusEvent.SESSION_UPDATED,
           BusEvent.MESSAGE_QUEUED,
-          BusEvent.MESSAGE_PROCESSING
+          BusEvent.MESSAGE_PROCESSING,
+          BusEvent.MESSAGE_FAILED
         ];
         for (const res of this.sseConnections) {
           const filter = res.sessionFilter;
@@ -10024,7 +10114,11 @@ var init_adapter = __esm({
           }
           return prev(method, payload, signal);
         });
-        this.registerCommandsWithRetry();
+        const onCommandsReady = ({ commands }) => {
+          this.core.eventBus.off(BusEvent.SYSTEM_COMMANDS_READY, onCommandsReady);
+          this.syncCommandsWithRetry(commands);
+        };
+        this.core.eventBus.on(BusEvent.SYSTEM_COMMANDS_READY, onCommandsReady);
         this.bot.use((ctx, next) => {
           const chatId = ctx.chat?.id ?? ctx.callbackQuery?.message?.chat?.id;
           if (chatId !== this.telegramConfig.chatId) return;
@@ -10148,10 +10242,19 @@ var init_adapter = __esm({
                   });
                 } catch {
                 }
-              } else if (response.type === "text" || response.type === "error") {
-                const text3 = response.type === "text" ? response.text : `\u274C ${response.message}`;
+              } else if (response.type === "text" || response.type === "error" || response.type === "adaptive") {
+                let text3;
+                let parseMode;
+                if (response.type === "adaptive") {
+                  const variant = response.variants?.["telegram"];
+                  text3 = variant?.text ?? response.fallback;
+                  parseMode = variant?.parse_mode;
+                } else {
+                  text3 = response.type === "text" ? response.text : `\u274C ${response.message}`;
+                  parseMode = "Markdown";
+                }
                 try {
-                  await ctx.editMessageText(text3, { parse_mode: "Markdown" });
+                  await ctx.editMessageText(text3, { ...parseMode && { parse_mode: parseMode } });
                 } catch {
                 }
               }
@@ -10241,12 +10344,16 @@ ${p}` : p;
         throw new Error("unreachable");
       }
       /**
-       * Register Telegram commands in the background with retries.
-       * Non-critical — bot works fine without autocomplete commands.
+       * Sync Telegram autocomplete commands after all plugins are ready.
+       * Merges STATIC_COMMANDS (hardcoded system commands) with plugin commands
+       * from the registry, deduplicating by command name. Non-critical.
        */
-      registerCommandsWithRetry() {
+      syncCommandsWithRetry(registryCommands) {
+        const staticNames = new Set(STATIC_COMMANDS.map((c2) => c2.command));
+        const pluginCommands = registryCommands.filter((c2) => c2.category === "plugin" && !staticNames.has(c2.name) && /^[a-z0-9_]+$/.test(c2.name)).map((c2) => ({ command: c2.name, description: c2.description.slice(0, 256) }));
+        const allCommands = [...STATIC_COMMANDS, ...pluginCommands].slice(0, 100);
         this.retryWithBackoff(
-          () => this.bot.api.setMyCommands(STATIC_COMMANDS, {
+          () => this.bot.api.setMyCommands(allCommands, {
             scope: { type: "chat", chat_id: this.telegramConfig.chatId }
           }),
           "setMyCommands"
@@ -10433,6 +10540,15 @@ OpenACP will automatically retry until this is resolved.`;
               message_thread_id: topicId
             });
             break;
+          case "adaptive": {
+            const variant = response.variants?.["telegram"];
+            const text3 = variant?.text ?? response.fallback;
+            await this.bot.api.sendMessage(chatId, text3, {
+              message_thread_id: topicId,
+              ...variant?.parse_mode && { parse_mode: variant.parse_mode }
+            });
+            break;
+          }
           case "error":
             await this.bot.api.sendMessage(
               chatId,
@@ -10541,12 +10657,25 @@ ${lines.join("\n")}`;
           }
           ctx.replyWithChatAction("typing").catch(() => {
           });
-          this.core.handleMessage({
-            channelId: "telegram",
-            threadId: String(threadId),
-            userId: String(ctx.from.id),
-            text: forwardText
-          }).catch((err) => log36.error({ err }, "handleMessage error"));
+          const fromName = [ctx.from.first_name, ctx.from.last_name].filter(Boolean).join(" ") || void 0;
+          this.core.handleMessage(
+            {
+              channelId: "telegram",
+              threadId: String(threadId),
+              userId: String(ctx.from.id),
+              text: forwardText
+            },
+            // Inject structured channel user info into TurnMeta so plugins can identify
+            // the sender by name without adapter-specific fields on IncomingMessage.
+            {
+              channelUser: {
+                channelId: "telegram",
+                userId: String(ctx.from.id),
+                displayName: fromName,
+                username: ctx.from.username
+              }
+            }
+          ).catch((err) => log36.error({ err }, "handleMessage error"));
         });
         this.bot.on("message:photo", async (ctx) => {
           const threadId = ctx.message.message_thread_id;
@@ -11259,6 +11388,8 @@ var ChannelAdapter = class {
   }
   async archiveSessionTopic(_sessionId) {
   }
+  async sendUserNotification(_platformId, _message, _options) {
+  }
 };
 
 // src/core/utils/streams.ts
@@ -12714,16 +12845,16 @@ var PromptQueue = class {
    * immediately. Otherwise, it's buffered and the returned promise resolves
    * only after the prompt finishes processing.
    */
-  async enqueue(text3, attachments, routing, turnId) {
+  async enqueue(text3, userPrompt, attachments, routing, turnId, meta) {
     if (this.processing) {
       return new Promise((resolve7) => {
-        this.queue.push({ text: text3, attachments, routing, turnId, resolve: resolve7 });
+        this.queue.push({ text: text3, userPrompt, attachments, routing, turnId, meta, resolve: resolve7 });
       });
     }
-    await this.process(text3, attachments, routing, turnId);
+    await this.process(text3, userPrompt, attachments, routing, turnId, meta);
   }
   /** Run a single prompt through the processor, then drain the next queued item. */
-  async process(text3, attachments, routing, turnId) {
+  async process(text3, userPrompt, attachments, routing, turnId, meta) {
     this.processing = true;
     this.abortController = new AbortController();
     const { signal } = this.abortController;
@@ -12733,7 +12864,7 @@ var PromptQueue = class {
     });
     try {
       await Promise.race([
-        this.processor(text3, attachments, routing, turnId),
+        this.processor(text3, userPrompt, attachments, routing, turnId, meta),
         new Promise((_, reject) => {
           signal.addEventListener("abort", () => reject(new Error("Prompt aborted")), { once: true });
         })
@@ -12754,7 +12885,7 @@ var PromptQueue = class {
   drainNext() {
     const next = this.queue.shift();
     if (next) {
-      this.process(next.text, next.attachments, next.routing, next.turnId).then(next.resolve);
+      this.process(next.text, next.userPrompt, next.attachments, next.routing, next.turnId, next.meta).then(next.resolve);
     }
   }
   /**
@@ -12776,6 +12907,13 @@ var PromptQueue = class {
   get isProcessing() {
     return this.processing;
   }
+  /** Snapshot of queued (not yet processing) items — used for queue inspection by callers. */
+  get pendingItems() {
+    return this.queue.map((item) => ({
+      userPrompt: item.userPrompt,
+      turnId: item.turnId
+    }));
+  }
 };
 
 // src/core/sessions/permission-gate.ts
@@ -12857,17 +12995,31 @@ import * as fs8 from "fs";
 
 // src/core/sessions/turn-context.ts
 import { nanoid } from "nanoid";
-function createTurnContext(sourceAdapterId, responseAdapterId, turnId) {
+function extractSender(meta) {
+  const identity = meta?.identity;
+  if (!identity || !identity.userId || !identity.identityId) return null;
   return {
-    turnId: turnId ?? nanoid(8),
-    sourceAdapterId,
-    responseAdapterId
+    userId: identity.userId,
+    identityId: identity.identityId,
+    displayName: identity.displayName,
+    username: identity.username
   };
 }
 function getEffectiveTarget(ctx) {
   if (ctx.responseAdapterId === null) return null;
   return ctx.responseAdapterId ?? ctx.sourceAdapterId;
 }
+function createTurnContext(sourceAdapterId, responseAdapterId, turnId, userPrompt, finalPrompt, attachments, meta) {
+  return {
+    turnId: turnId ?? nanoid(8),
+    sourceAdapterId,
+    responseAdapterId,
+    userPrompt,
+    finalPrompt,
+    attachments,
+    meta
+  };
+}
 var SYSTEM_EVENT_TYPES = /* @__PURE__ */ new Set([
   "session_end",
   "system_message",
@@ -12962,7 +13114,7 @@ var Session = class extends TypedEmitter {
     this.log = createSessionLogger(this.id, moduleLog);
     this.log.info({ agentName: this.agentName }, "Session created");
     this.queue = new PromptQueue(
-      (text3, attachments, routing, turnId) => this.processPrompt(text3, attachments, routing, turnId),
+      (text3, userPrompt, attachments, routing, turnId, meta) => this.processPrompt(text3, userPrompt, attachments, routing, turnId, meta),
       (err) => {
         this.log.error({ err }, "Prompt execution failed");
         const message = err instanceof Error ? err.message : String(err);
@@ -13042,6 +13194,10 @@ var Session = class extends TypedEmitter {
   get promptRunning() {
     return this.queue.isProcessing;
   }
+  /** Snapshot of queued (not yet processing) items — for inspection by API consumers. */
+  get queueItems() {
+    return this.queue.pendingItems;
+  }
   // --- Context Injection ---
   /** Store context markdown to be prepended to the next prompt (used for session resume with history). */
   setContext(markdown) {
@@ -13061,24 +13217,31 @@ var Session = class extends TypedEmitter {
    * then adds it to the PromptQueue. Returns a turnId that callers can use to correlate
    * queued/processing events before the prompt actually runs.
    */
-  async enqueuePrompt(text3, attachments, routing, externalTurnId) {
+  async enqueuePrompt(text3, attachments, routing, externalTurnId, meta) {
     const turnId = externalTurnId ?? nanoid2(8);
+    const turnMeta = meta ?? { turnId };
+    const userPrompt = text3;
     if (this.middlewareChain) {
-      const payload = { text: text3, attachments, sessionId: this.id, sourceAdapterId: routing?.sourceAdapterId };
+      const payload = { text: text3, attachments, sessionId: this.id, sourceAdapterId: routing?.sourceAdapterId, meta: turnMeta };
       const result = await this.middlewareChain.execute(Hook.AGENT_BEFORE_PROMPT, payload, async (p) => p);
-      if (!result) return turnId;
+      if (!result) throw new Error("PROMPT_BLOCKED");
       text3 = result.text;
       attachments = result.attachments;
     }
-    await this.queue.enqueue(text3, attachments, routing, turnId);
+    await this.queue.enqueue(text3, userPrompt, attachments, routing, turnId, turnMeta);
     return turnId;
   }
-  async processPrompt(text3, attachments, routing, turnId) {
+  async processPrompt(text3, userPrompt, attachments, routing, turnId, meta) {
     if (this._status === "finished") return;
     this.activeTurnContext = createTurnContext(
       routing?.sourceAdapterId ?? this.channelId,
       routing?.responseAdapterId,
-      turnId
+      turnId,
+      userPrompt,
+      text3,
+      // finalPrompt (after middleware transformations)
+      attachments,
+      meta
     );
     this.emit(SessionEv.TURN_STARTED, this.activeTurnContext);
     this.promptCount++;
@@ -13113,6 +13276,13 @@ ${text3}`;
     if (accumulatorListener) {
       this.on(SessionEv.AGENT_EVENT, accumulatorListener);
     }
+    const turnTextBuffer = [];
+    const turnTextListener = (event) => {
+      if (event.type === "text" && typeof event.content === "string") {
+        turnTextBuffer.push(event.content);
+      }
+    };
+    this.on(SessionEv.AGENT_EVENT, turnTextListener);
     const mw = this.middlewareChain;
     const afterEventListener = mw ? (event) => {
       mw.execute(Hook.AGENT_AFTER_EVENT, { sessionId: this.id, event, outgoingMessage: { type: "text", text: "" } }, async (e) => e).catch(() => {
@@ -13122,7 +13292,16 @@ ${text3}`;
       this.agentInstance.on(SessionEv.AGENT_EVENT, afterEventListener);
     }
     if (this.middlewareChain) {
-      this.middlewareChain.execute(Hook.TURN_START, { sessionId: this.id, promptText: processed.text, promptNumber: this.promptCount }, async (p) => p).catch(() => {
+      this.middlewareChain.execute(Hook.TURN_START, {
+        sessionId: this.id,
+        promptText: processed.text,
+        promptNumber: this.promptCount,
+        turnId: this.activeTurnContext?.turnId ?? turnId ?? "",
+        meta,
+        userPrompt: this.activeTurnContext?.userPrompt,
+        sourceAdapterId: this.activeTurnContext?.sourceAdapterId,
+        responseAdapterId: this.activeTurnContext?.responseAdapterId
+      }, async (p) => p).catch(() => {
       });
     }
     let stopReason = "end_turn";
@@ -13148,8 +13327,20 @@ ${text3}`;
       if (afterEventListener) {
         this.agentInstance.off(SessionEv.AGENT_EVENT, afterEventListener);
       }
+      this.off(SessionEv.AGENT_EVENT, turnTextListener);
+      const finalTurnId = this.activeTurnContext?.turnId ?? turnId ?? "";
       if (this.middlewareChain) {
-        this.middlewareChain.execute(Hook.TURN_END, { sessionId: this.id, stopReason, durationMs: Date.now() - promptStart }, async (p) => p).catch(() => {
+        this.middlewareChain.execute(Hook.TURN_END, { sessionId: this.id, stopReason, durationMs: Date.now() - promptStart, turnId: finalTurnId, meta }, async (p) => p).catch(() => {
+        });
+      }
+      if (this.middlewareChain) {
+        this.middlewareChain.execute(Hook.AGENT_AFTER_TURN, {
+          sessionId: this.id,
+          turnId: finalTurnId,
+          fullText: turnTextBuffer.join(""),
+          stopReason,
+          meta
+        }, async (p) => p).catch(() => {
         });
       }
       this.activeTurnContext = null;
@@ -14279,7 +14470,7 @@ var SessionBridge = class {
       if (this.shouldForward(event)) {
         this.dispatchAgentEvent(event);
       } else {
-        this.deps.eventBus?.emit(BusEvent.AGENT_EVENT, { sessionId: this.session.id, event });
+        this.deps.eventBus?.emit(BusEvent.AGENT_EVENT, { sessionId: this.session.id, turnId: "", event });
       }
     });
     if (!this.session.agentInstance.onPermissionRequest || this.session.agentInstance.onPermissionRequest.__bridgeId === void 0) {
@@ -14332,14 +14523,16 @@ var SessionBridge = class {
       this.deps.sessionManager.patchRecord(this.session.id, { currentPromptCount: count });
     });
     this.listen(this.session, SessionEv.TURN_STARTED, (ctx) => {
-      if (ctx.sourceAdapterId !== "sse") {
-        this.deps.eventBus?.emit(BusEvent.MESSAGE_PROCESSING, {
-          sessionId: this.session.id,
-          turnId: ctx.turnId,
-          sourceAdapterId: ctx.sourceAdapterId,
-          timestamp: (/* @__PURE__ */ new Date()).toISOString()
-        });
-      }
+      this.deps.eventBus?.emit(BusEvent.MESSAGE_PROCESSING, {
+        sessionId: this.session.id,
+        turnId: ctx.turnId,
+        sourceAdapterId: ctx.sourceAdapterId,
+        userPrompt: ctx.userPrompt,
+        finalPrompt: ctx.finalPrompt,
+        attachments: ctx.attachments,
+        sender: extractSender(ctx.meta),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
     });
     if (this.session.latestCommands !== null) {
       this.session.emit(SessionEv.AGENT_EVENT, { type: "commands_update", commands: this.session.latestCommands });
@@ -14505,6 +14698,7 @@ var SessionBridge = class {
     }
     this.deps.eventBus?.emit(BusEvent.AGENT_EVENT, {
       sessionId: this.session.id,
+      turnId: this.session.activeTurnContext?.turnId ?? "",
       event
     });
     return outgoing;
@@ -14631,8 +14825,7 @@ var SessionFactory = class {
       const payload = {
         agentName: params.agentName,
         workingDir: params.workingDirectory,
-        userId: "",
-        // userId is not part of SessionCreateParams — resolved upstream
+        userId: params.userId ?? "",
         channelId: params.channelId,
         threadId: ""
         // threadId is assigned after session creation
@@ -14706,6 +14899,7 @@ var SessionFactory = class {
       const failedSessionId = createParams.existingSessionId ?? `failed-${Date.now()}`;
       this.eventBus.emit(BusEvent.AGENT_EVENT, {
         sessionId: failedSessionId,
+        turnId: "",
         event: guidance
       });
       throw err;
@@ -14734,7 +14928,8 @@ var SessionFactory = class {
       this.eventBus.emit(BusEvent.SESSION_CREATED, {
         sessionId: session.id,
         agent: session.agentName,
-        status: session.status
+        status: session.status,
+        userId: createParams.userId
       });
     }
     return session;
@@ -15254,7 +15449,7 @@ var AgentSwitchHandler = class {
       message: `Switching from ${fromAgent} to ${toAgent}...`
     };
     session.emit(SessionEv.AGENT_EVENT, startEvent);
-    eventBus.emit(BusEvent.AGENT_EVENT, { sessionId, event: startEvent });
+    eventBus.emit(BusEvent.AGENT_EVENT, { sessionId, turnId: "", event: startEvent });
     eventBus.emit(BusEvent.SESSION_AGENT_SWITCH, {
       sessionId,
       fromAgent,
@@ -15317,7 +15512,7 @@ var AgentSwitchHandler = class {
         message: resumed ? `Switched to ${toAgent} (resumed previous session).` : `Switched to ${toAgent} (new session).`
       };
       session.emit(SessionEv.AGENT_EVENT, successEvent);
-      eventBus.emit(BusEvent.AGENT_EVENT, { sessionId, event: successEvent });
+      eventBus.emit(BusEvent.AGENT_EVENT, { sessionId, turnId: "", event: successEvent });
       eventBus.emit(BusEvent.SESSION_AGENT_SWITCH, {
         sessionId,
         fromAgent,
@@ -15332,7 +15527,7 @@ var AgentSwitchHandler = class {
         message: `Failed to switch to ${toAgent}: ${errorMessage}`
       };
       session.emit(SessionEv.AGENT_EVENT, failedEvent);
-      eventBus.emit(BusEvent.AGENT_EVENT, { sessionId, event: failedEvent });
+      eventBus.emit(BusEvent.AGENT_EVENT, { sessionId, turnId: "", event: failedEvent });
       eventBus.emit(BusEvent.SESSION_AGENT_SWITCH, {
         sessionId,
         fromAgent,
@@ -16102,11 +16297,55 @@ var PluginStorageImpl = class {
   async list() {
     return Object.keys(this.readKv());
   }
+  async keys(prefix) {
+    const all = Object.keys(this.readKv());
+    return prefix ? all.filter((k) => k.startsWith(prefix)) : all;
+  }
+  async clear() {
+    this.writeChain = this.writeChain.then(() => {
+      this.writeKv({});
+    });
+    return this.writeChain;
+  }
   /** Returns the plugin's data directory, creating it lazily on first access. */
   getDataDir() {
     fs14.mkdirSync(this.dataDir, { recursive: true });
     return this.dataDir;
   }
+  /**
+   * Creates a namespaced storage instance scoped to a session.
+   * Keys are prefixed with `session:{sessionId}:` to isolate session data
+   * from global plugin storage in the same backing file.
+   */
+  forSession(sessionId) {
+    const prefix = `session:${sessionId}:`;
+    return {
+      get: (key) => this.get(`${prefix}${key}`),
+      set: (key, value) => this.set(`${prefix}${key}`, value),
+      delete: (key) => this.delete(`${prefix}${key}`),
+      list: async () => {
+        const all = await this.keys(prefix);
+        return all.map((k) => k.slice(prefix.length));
+      },
+      keys: async (p) => {
+        const full = p ? `${prefix}${p}` : prefix;
+        const all = await this.keys(full);
+        return all.map((k) => k.slice(prefix.length));
+      },
+      clear: async () => {
+        this.writeChain = this.writeChain.then(() => {
+          const data = this.readKv();
+          for (const key of Object.keys(data)) {
+            if (key.startsWith(prefix)) delete data[key];
+          }
+          this.writeKv(data);
+        });
+        return this.writeChain;
+      },
+      getDataDir: () => this.getDataDir(),
+      forSession: (nestedId) => this.forSession(`${sessionId}:${nestedId}`)
+    };
+  }
 };
 
 // src/core/plugin/plugin-context.ts
@@ -16170,9 +16409,52 @@ function createPluginContext(opts) {
       requirePermission(permissions, "storage:read", "storage.list");
       return storageImpl.list();
     },
+    async keys(prefix) {
+      requirePermission(permissions, "storage:read", "storage.keys");
+      return storageImpl.keys(prefix);
+    },
+    async clear() {
+      requirePermission(permissions, "storage:write", "storage.clear");
+      return storageImpl.clear();
+    },
     getDataDir() {
       requirePermission(permissions, "storage:read", "storage.getDataDir");
       return storageImpl.getDataDir();
+    },
+    forSession(sessionId) {
+      requirePermission(permissions, "storage:read", "storage.forSession");
+      const scoped = storageImpl.forSession(sessionId);
+      return {
+        get: (key) => {
+          requirePermission(permissions, "storage:read", "storage.get");
+          return scoped.get(key);
+        },
+        set: (key, value) => {
+          requirePermission(permissions, "storage:write", "storage.set");
+          return scoped.set(key, value);
+        },
+        delete: (key) => {
+          requirePermission(permissions, "storage:write", "storage.delete");
+          return scoped.delete(key);
+        },
+        list: () => {
+          requirePermission(permissions, "storage:read", "storage.list");
+          return scoped.list();
+        },
+        keys: (prefix) => {
+          requirePermission(permissions, "storage:read", "storage.keys");
+          return scoped.keys(prefix);
+        },
+        clear: () => {
+          requirePermission(permissions, "storage:write", "storage.clear");
+          return scoped.clear();
+        },
+        getDataDir: () => {
+          requirePermission(permissions, "storage:read", "storage.getDataDir");
+          return scoped.getDataDir();
+        },
+        forSession: (nestedId) => storage.forSession(`${sessionId}:${nestedId}`)
+      };
     }
   };
   const ctx = {
@@ -16223,6 +16505,26 @@ function createPluginContext(opts) {
         await router.send(_sessionId, _content);
       }
     },
+    notify(target, message, options) {
+      requirePermission(permissions, "notifications:send", "notify()");
+      const svc = serviceRegistry.get("notifications");
+      if (svc?.notifyUser) {
+        svc.notifyUser(target, message, options).catch(() => {
+        });
+      }
+    },
+    defineHook(_name) {
+    },
+    async emitHook(name, payload) {
+      const qualifiedName = `plugin:${pluginName}:${name}`;
+      return middlewareChain.execute(qualifiedName, payload, (p) => p);
+    },
+    async getSessionInfo(sessionId) {
+      requirePermission(permissions, "sessions:read", "getSessionInfo()");
+      const sessionMgr = serviceRegistry.get("session-info");
+      if (!sessionMgr) return void 0;
+      return sessionMgr.getSessionInfo(sessionId);
+    },
     registerMenuItem(item) {
       requirePermission(permissions, "commands:register", "registerMenuItem()");
       const menuRegistry = serviceRegistry.get("menu-registry");
@@ -17272,7 +17574,7 @@ var OpenACPCore = class {
    *
    * If no session is found, the user is told to start one with /new.
    */
-  async handleMessage(message) {
+  async handleMessage(message, initialMeta) {
     log16.debug(
       {
         channelId: message.channelId,
@@ -17281,10 +17583,12 @@ var OpenACPCore = class {
       },
       "Incoming message"
     );
+    const turnId = nanoid3(8);
+    const meta = { turnId, ...initialMeta };
     if (this.lifecycleManager?.middlewareChain) {
       const result = await this.lifecycleManager.middlewareChain.execute(
         Hook.MESSAGE_INCOMING,
-        message,
+        { ...message, meta },
         async (msg) => msg
       );
       if (!result) return;
@@ -17319,9 +17623,6 @@ var OpenACPCore = class {
       }
       return;
     }
-    this.sessionManager.patchRecord(session.id, {
-      lastActiveAt: (/* @__PURE__ */ new Date()).toISOString()
-    });
     let text3 = message.text;
     if (this.assistantManager?.isAssistant(session.id)) {
       const pending = this.assistantManager.consumePendingSystemPrompt(message.channelId);
@@ -17334,23 +17635,85 @@ User message:
 ${text3}`;
       }
     }
-    const sourceAdapterId = message.routing?.sourceAdapterId ?? message.channelId;
-    const routing = sourceAdapterId !== message.routing?.sourceAdapterId ? { ...message.routing, sourceAdapterId } : message.routing;
-    if (sourceAdapterId && sourceAdapterId !== "sse" && sourceAdapterId !== "api") {
-      const turnId = nanoid3(8);
-      this.eventBus.emit(BusEvent.MESSAGE_QUEUED, {
+    const enrichedMeta = message.meta ?? meta;
+    await this._dispatchToSession(session, text3, message.attachments, {
+      sourceAdapterId: message.routing?.sourceAdapterId ?? message.channelId,
+      responseAdapterId: message.routing?.responseAdapterId
+    }, turnId, enrichedMeta);
+  }
+  /**
+   * Shared dispatch path for sending a prompt to a session.
+   * Called by both handleMessage (Telegram) and handleMessageInSession (SSE/API)
+   * after their respective middleware/enrichment steps.
+   */
+  async _dispatchToSession(session, text3, attachments, routing, turnId, meta) {
+    this.sessionManager.patchRecord(session.id, {
+      lastActiveAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    this.eventBus.emit(BusEvent.MESSAGE_QUEUED, {
+      sessionId: session.id,
+      turnId,
+      text: text3,
+      sourceAdapterId: routing.sourceAdapterId,
+      attachments,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      queueDepth: session.queueDepth + 1,
+      sender: extractSender(meta)
+    });
+    session.enqueuePrompt(text3, attachments, routing, turnId, meta).catch((err) => {
+      const reason = err instanceof Error ? err.message : String(err);
+      log16.warn({ err, sessionId: session.id, turnId, reason }, "enqueuePrompt failed \u2014 emitting message:failed");
+      this.eventBus.emit(BusEvent.MESSAGE_FAILED, {
         sessionId: session.id,
         turnId,
-        text: text3,
-        sourceAdapterId,
-        attachments: message.attachments,
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        queueDepth: session.queueDepth
+        reason
       });
-      await session.enqueuePrompt(text3, message.attachments, routing, turnId);
-    } else {
-      await session.enqueuePrompt(text3, message.attachments, routing);
+    });
+  }
+  /**
+   * Send a message to a known session, running the full message:incoming → agent:beforePrompt
+   * middleware chain (same as handleMessage) but without the threadId-based session lookup.
+   *
+   * Used by channels that already hold a direct session reference (e.g. SSE adapter, api-server),
+   * where looking up by channelId+threadId is unreliable (API sessions may have no threadId).
+   *
+   * @param session  The target session — caller is responsible for validating its status.
+   * @param message  Sender context and message content.
+   * @param initialMeta  Optional adapter-specific context to seed the TurnMeta bag
+   *                     (e.g. channelUser with display name/username).
+   * @param options  Optional turnId override and response routing.
+   */
+  async handleMessageInSession(session, message, initialMeta, options) {
+    const turnId = options?.externalTurnId ?? nanoid3(8);
+    const meta = { turnId, ...initialMeta };
+    let text3 = message.text;
+    let { attachments } = message;
+    let enrichedMeta = meta;
+    if (this.lifecycleManager?.middlewareChain) {
+      const payload = {
+        channelId: message.channelId,
+        threadId: session.id,
+        userId: message.userId,
+        text: text3,
+        attachments,
+        meta
+      };
+      const result = await this.lifecycleManager.middlewareChain.execute(
+        Hook.MESSAGE_INCOMING,
+        payload,
+        async (p) => p
+      );
+      if (!result) return { turnId, queueDepth: session.queueDepth };
+      text3 = result.text;
+      attachments = result.attachments;
+      enrichedMeta = result.meta ?? meta;
     }
+    const routing = {
+      sourceAdapterId: message.channelId,
+      responseAdapterId: options?.responseAdapterId
+    };
+    await this._dispatchToSession(session, text3, attachments, routing, turnId, enrichedMeta);
+    return { turnId, queueDepth: session.queueDepth };
   }
   // --- Unified Session Creation Pipeline ---
   /**
@@ -17462,7 +17825,7 @@ ${text3}`;
         } else if (processedEvent.type === "error") {
           session.fail(processedEvent.message);
         }
-        this.eventBus.emit(BusEvent.AGENT_EVENT, { sessionId: session.id, event: processedEvent });
+        this.eventBus.emit(BusEvent.AGENT_EVENT, { sessionId: session.id, turnId: session.activeTurnContext?.turnId ?? "", event: processedEvent });
       });
       session.on(SessionEv.STATUS_CHANGE, (_from, to) => {
         this.sessionManager.patchRecord(session.id, {
@@ -17474,6 +17837,18 @@ ${text3}`;
       session.on(SessionEv.PROMPT_COUNT_CHANGED, (count) => {
         this.sessionManager.patchRecord(session.id, { currentPromptCount: count });
       });
+      session.on(SessionEv.TURN_STARTED, (ctx) => {
+        this.eventBus.emit(BusEvent.MESSAGE_PROCESSING, {
+          sessionId: session.id,
+          turnId: ctx.turnId,
+          sourceAdapterId: ctx.sourceAdapterId,
+          userPrompt: ctx.userPrompt,
+          finalPrompt: ctx.finalPrompt,
+          attachments: ctx.attachments,
+          sender: extractSender(ctx.meta),
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      });
     }
     this.sessionFactory.wireSideEffects(session, {
       eventBus: this.eventBus,
@@ -19792,7 +20167,7 @@ export {
   MenuRegistry,
   MessageTransformer,
   MessagingAdapter,
-  NotificationManager,
+  NotificationService as NotificationManager,
   OpenACPCore,
   OutputModeResolver,
   PRODUCT_GUIDE,