@openacp/cli 2026.410.3 → 2026.414.1

package/dist/cli.js

@@ -1244,11 +1244,11 @@ mockServices.context(overrides?)     // buildContext, registerProvider
 ctx.registerCommand({
   name: 'mycommand',
   description: 'Does something useful',
-  usage: '<arg>',
+  usage: '[arg]',
   category: 'plugin',
   async handler(args) {
     const input = args.raw.trim()
-    if (!input) return { type: 'error', message: 'Usage: /mycommand <arg>' }
+    if (!input) return { type: 'error', message: 'Usage: /mycommand [arg]' }
     return { type: 'text', text: \\\`Result: \\\${input}\\\` }
   },
 })
@@ -1811,6 +1811,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",
@@ -1868,6 +1870,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",
@@ -1888,7 +1892,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. */
@@ -2014,7 +2033,16 @@ function createSecurityPlugin() {
         handler: async (payload, next) => {
           const access2 = await guard.checkAccess(payload);
           if (!access2.allowed) {
-            ctx.log.info(`Access denied: ${access2.reason}`);
+            ctx.log.info(`Access denied for user=${payload.userId} channel=${payload.channelId}: ${access2.reason}`);
+            const adapter = core.adapters?.get?.(payload.channelId);
+            if (adapter?.sendMessage && payload.threadId) {
+              adapter.sendMessage(payload.threadId, {
+                type: "error",
+                message: `Access denied: ${access2.reason ?? "You are not allowed to use this service."}`
+              }).catch((err) => {
+                ctx.log.warn(`Failed to send access-denied message to adapter: ${err}`);
+              });
+            }
             return null;
           }
           return next();
@@ -2035,6 +2063,711 @@ var init_security = __esm({
   }
 });
 
+// src/plugins/identity/types.ts
+function formatIdentityId(source, platformId) {
+  return `${source}:${platformId}`;
+}
+var init_types = __esm({
+  "src/plugins/identity/types.ts"() {
+    "use strict";
+  }
+});
+
+// src/plugins/identity/identity-service.ts
+import { nanoid } from "nanoid";
+var IdentityServiceImpl;
+var init_identity_service = __esm({
+  "src/plugins/identity/identity-service.ts"() {
+    "use strict";
+    init_types();
+    IdentityServiceImpl = class {
+      /**
+       * @param store - Persistence layer for user/identity records and indexes.
+       * @param emitEvent - Callback to publish events on the EventBus.
+       * @param getSessionsForUser - Optional function to look up sessions for a userId.
+       */
+      constructor(store, emitEvent, getSessionsForUser) {
+        this.store = store;
+        this.emitEvent = emitEvent;
+        this.getSessionsForUser = getSessionsForUser;
+      }
+      registeredSources = /* @__PURE__ */ new Set();
+      // ─── Lookups ───
+      async getUser(userId) {
+        return this.store.getUser(userId);
+      }
+      async getUserByUsername(username) {
+        const userId = await this.store.getUserIdByUsername(username);
+        if (!userId) return void 0;
+        return this.store.getUser(userId);
+      }
+      async getIdentity(identityId) {
+        return this.store.getIdentity(identityId);
+      }
+      async getUserByIdentity(identityId) {
+        const identity = await this.store.getIdentity(identityId);
+        if (!identity) return void 0;
+        return this.store.getUser(identity.userId);
+      }
+      async getIdentitiesFor(userId) {
+        return this.store.getIdentitiesForUser(userId);
+      }
+      async listUsers(filter) {
+        return this.store.listUsers(filter);
+      }
+      /**
+       * Case-insensitive substring search across displayName, username, and platform
+       * usernames. Designed for admin tooling, not high-frequency user-facing paths.
+       */
+      async searchUsers(query) {
+        const all = await this.store.listUsers();
+        const q = query.toLowerCase();
+        const matched = [];
+        for (const user of all) {
+          const nameMatch = user.displayName.toLowerCase().includes(q) || user.username && user.username.toLowerCase().includes(q);
+          if (nameMatch) {
+            matched.push(user);
+            continue;
+          }
+          const identities = await this.store.getIdentitiesForUser(user.userId);
+          const platformMatch = identities.some(
+            (id) => id.platformUsername && id.platformUsername.toLowerCase().includes(q)
+          );
+          if (platformMatch) matched.push(user);
+        }
+        return matched;
+      }
+      async getSessionsFor(userId) {
+        if (!this.getSessionsForUser) return [];
+        return this.getSessionsForUser(userId);
+      }
+      // ─── Mutations ───
+      /**
+       * Creates a user + identity pair atomically.
+       * The first ever user in the system is auto-promoted to admin — this ensures
+       * there is always at least one admin when bootstrapping a fresh instance.
+       */
+      async createUserWithIdentity(data) {
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        const userId = `u_${nanoid(12)}`;
+        const identityId = formatIdentityId(data.source, data.platformId);
+        const count = await this.store.getUserCount();
+        const role = count === 0 ? "admin" : data.role ?? "member";
+        const user = {
+          userId,
+          displayName: data.displayName,
+          username: data.username,
+          role,
+          identities: [identityId],
+          pluginData: {},
+          createdAt: now,
+          updatedAt: now,
+          lastSeenAt: now
+        };
+        const identity = {
+          identityId,
+          userId,
+          source: data.source,
+          platformId: data.platformId,
+          platformUsername: data.platformUsername,
+          platformDisplayName: data.platformDisplayName,
+          createdAt: now,
+          updatedAt: now
+        };
+        await this.store.putUser(user);
+        await this.store.putIdentity(identity);
+        await this.store.setSourceIndex(data.source, data.platformId, identityId);
+        if (data.username) {
+          await this.store.setUsernameIndex(data.username, userId);
+        }
+        this.emitEvent("identity:created", { userId, identityId, source: data.source, displayName: data.displayName });
+        return { user, identity };
+      }
+      async updateUser(userId, changes) {
+        const user = await this.store.getUser(userId);
+        if (!user) throw new Error(`User not found: ${userId}`);
+        if (changes.username !== void 0 && changes.username !== user.username) {
+          if (changes.username) {
+            const existingId = await this.store.getUserIdByUsername(changes.username);
+            if (existingId && existingId !== userId) {
+              throw new Error(`Username already taken: ${changes.username}`);
+            }
+            await this.store.setUsernameIndex(changes.username, userId);
+          }
+          if (user.username) {
+            await this.store.deleteUsernameIndex(user.username);
+          }
+        }
+        const updated = {
+          ...user,
+          ...changes,
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        await this.store.putUser(updated);
+        this.emitEvent("identity:updated", { userId, changes: Object.keys(changes) });
+        return updated;
+      }
+      async setRole(userId, role) {
+        const user = await this.store.getUser(userId);
+        if (!user) throw new Error(`User not found: ${userId}`);
+        const oldRole = user.role;
+        await this.store.putUser({ ...user, role, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
+        this.emitEvent("identity:roleChanged", { userId, oldRole, newRole: role });
+      }
+      async createIdentity(userId, identity) {
+        const user = await this.store.getUser(userId);
+        if (!user) throw new Error(`User not found: ${userId}`);
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        const identityId = formatIdentityId(identity.source, identity.platformId);
+        const record = {
+          identityId,
+          userId,
+          source: identity.source,
+          platformId: identity.platformId,
+          platformUsername: identity.platformUsername,
+          platformDisplayName: identity.platformDisplayName,
+          createdAt: now,
+          updatedAt: now
+        };
+        await this.store.putIdentity(record);
+        await this.store.setSourceIndex(identity.source, identity.platformId, identityId);
+        const updatedUser = {
+          ...user,
+          identities: [...user.identities, identityId],
+          updatedAt: now
+        };
+        await this.store.putUser(updatedUser);
+        return record;
+      }
+      /**
+       * Links two identities into a single user.
+       *
+       * When identities belong to different users, the younger (more recently created)
+       * user is merged into the older one. We keep the older user as the canonical
+       * record because it likely has more history, sessions, and plugin data.
+       *
+       * Merge strategy for pluginData: per-namespace, the winning user's data takes
+       * precedence. The younger user's data only fills in missing namespaces.
+       */
+      async link(identityIdA, identityIdB) {
+        const identityA = await this.store.getIdentity(identityIdA);
+        const identityB = await this.store.getIdentity(identityIdB);
+        if (!identityA) throw new Error(`Identity not found: ${identityIdA}`);
+        if (!identityB) throw new Error(`Identity not found: ${identityIdB}`);
+        if (identityA.userId === identityB.userId) return;
+        const userA = await this.store.getUser(identityA.userId);
+        const userB = await this.store.getUser(identityB.userId);
+        if (!userA) throw new Error(`User not found: ${identityA.userId}`);
+        if (!userB) throw new Error(`User not found: ${identityB.userId}`);
+        const [keep, merge] = userA.createdAt <= userB.createdAt ? [userA, userB] : [userB, userA];
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        for (const identityId of merge.identities) {
+          const identity = await this.store.getIdentity(identityId);
+          if (!identity) continue;
+          const updated = { ...identity, userId: keep.userId, updatedAt: now };
+          await this.store.putIdentity(updated);
+        }
+        const mergedPluginData = { ...merge.pluginData };
+        for (const [ns, nsData] of Object.entries(keep.pluginData)) {
+          mergedPluginData[ns] = nsData;
+        }
+        if (merge.username) {
+          await this.store.deleteUsernameIndex(merge.username);
+        }
+        const updatedKeep = {
+          ...keep,
+          identities: [.../* @__PURE__ */ new Set([...keep.identities, ...merge.identities])],
+          pluginData: mergedPluginData,
+          updatedAt: now
+        };
+        await this.store.putUser(updatedKeep);
+        await this.store.deleteUser(merge.userId);
+        const linkedIdentityId = identityA.userId === merge.userId ? identityIdA : identityIdB;
+        this.emitEvent("identity:linked", { userId: keep.userId, identityId: linkedIdentityId, linkedFrom: merge.userId });
+        this.emitEvent("identity:userMerged", {
+          keptUserId: keep.userId,
+          mergedUserId: merge.userId,
+          movedIdentities: merge.identities
+        });
+      }
+      /**
+       * Separates an identity from its user into a new standalone account.
+       * Throws if it's the user's last identity — unlinking would produce a
+       * ghost user with no way to authenticate.
+       */
+      async unlink(identityId) {
+        const identity = await this.store.getIdentity(identityId);
+        if (!identity) throw new Error(`Identity not found: ${identityId}`);
+        const user = await this.store.getUser(identity.userId);
+        if (!user) throw new Error(`User not found: ${identity.userId}`);
+        if (user.identities.length <= 1) {
+          throw new Error(`Cannot unlink the last identity from user ${identity.userId}`);
+        }
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        const newUserId = `u_${nanoid(12)}`;
+        const newUser = {
+          userId: newUserId,
+          displayName: identity.platformDisplayName ?? identity.platformUsername ?? "User",
+          role: "member",
+          identities: [identityId],
+          pluginData: {},
+          createdAt: now,
+          updatedAt: now,
+          lastSeenAt: now
+        };
+        await this.store.putUser(newUser);
+        await this.store.putIdentity({ ...identity, userId: newUserId, updatedAt: now });
+        const updatedUser = {
+          ...user,
+          identities: user.identities.filter((id) => id !== identityId),
+          updatedAt: now
+        };
+        await this.store.putUser(updatedUser);
+        this.emitEvent("identity:unlinked", {
+          userId: user.userId,
+          identityId,
+          newUserId
+        });
+      }
+      // ─── Plugin data ───
+      async setPluginData(userId, pluginName, key, value) {
+        const user = await this.store.getUser(userId);
+        if (!user) throw new Error(`User not found: ${userId}`);
+        const pluginData = { ...user.pluginData };
+        pluginData[pluginName] = { ...pluginData[pluginName] ?? {}, [key]: value };
+        await this.store.putUser({ ...user, pluginData, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
+      }
+      async getPluginData(userId, pluginName, key) {
+        const user = await this.store.getUser(userId);
+        if (!user) return void 0;
+        return user.pluginData[pluginName]?.[key];
+      }
+      // ─── Source registry ───
+      registerSource(source) {
+        this.registeredSources.add(source);
+      }
+      /**
+       * Resolves a username mention to platform-specific info for the given source.
+       * Finds the user by username, then scans their identities for the matching source.
+       * Returns found=false when no user or no identity for that source exists.
+       */
+      async resolveCanonicalMention(username, source) {
+        const user = await this.getUserByUsername(username);
+        if (!user) return { found: false };
+        const identities = await this.store.getIdentitiesForUser(user.userId);
+        const sourceIdentity = identities.find((id) => id.source === source);
+        if (!sourceIdentity) return { found: false };
+        return {
+          found: true,
+          platformId: sourceIdentity.platformId,
+          platformUsername: sourceIdentity.platformUsername
+        };
+      }
+      async getUserCount() {
+        return this.store.getUserCount();
+      }
+    };
+  }
+});
+
+// src/plugins/identity/store/kv-identity-store.ts
+var KvIdentityStore;
+var init_kv_identity_store = __esm({
+  "src/plugins/identity/store/kv-identity-store.ts"() {
+    "use strict";
+    KvIdentityStore = class {
+      constructor(storage) {
+        this.storage = storage;
+      }
+      // === User CRUD ===
+      async getUser(userId) {
+        return this.storage.get(`users/${userId}`);
+      }
+      async putUser(record) {
+        await this.storage.set(`users/${record.userId}`, record);
+      }
+      async deleteUser(userId) {
+        await this.storage.delete(`users/${userId}`);
+      }
+      /**
+       * Lists all users, optionally filtered by role or source.
+       * Filtering by source requires scanning all identity records for the user,
+       * which is acceptable given the expected user count (hundreds, not millions).
+       */
+      async listUsers(filter) {
+        const keys = await this.storage.keys("users/");
+        const users = [];
+        for (const key of keys) {
+          const user = await this.storage.get(key);
+          if (!user) continue;
+          if (filter?.role && user.role !== filter.role) continue;
+          if (filter?.source) {
+            const hasSource = user.identities.some((id) => id.startsWith(`${filter.source}:`));
+            if (!hasSource) continue;
+          }
+          users.push(user);
+        }
+        return users;
+      }
+      // === Identity CRUD ===
+      async getIdentity(identityId) {
+        return this.storage.get(`identities/${identityId}`);
+      }
+      async putIdentity(record) {
+        await this.storage.set(`identities/${record.identityId}`, record);
+      }
+      async deleteIdentity(identityId) {
+        await this.storage.delete(`identities/${identityId}`);
+      }
+      /**
+       * Fetches all identity records for a user by scanning their identities array.
+       * Avoids a full table scan by leveraging the user record as a secondary index.
+       */
+      async getIdentitiesForUser(userId) {
+        const user = await this.getUser(userId);
+        if (!user) return [];
+        const records = [];
+        for (const identityId of user.identities) {
+          const record = await this.getIdentity(identityId);
+          if (record) records.push(record);
+        }
+        return records;
+      }
+      // === Secondary indexes ===
+      async getUserIdByUsername(username) {
+        return this.storage.get(`idx/usernames/${username.toLowerCase()}`);
+      }
+      async getIdentityIdBySource(source, platformId) {
+        return this.storage.get(`idx/sources/${source}/${platformId}`);
+      }
+      // === Index mutations ===
+      async setUsernameIndex(username, userId) {
+        await this.storage.set(`idx/usernames/${username.toLowerCase()}`, userId);
+      }
+      async deleteUsernameIndex(username) {
+        await this.storage.delete(`idx/usernames/${username.toLowerCase()}`);
+      }
+      async setSourceIndex(source, platformId, identityId) {
+        await this.storage.set(`idx/sources/${source}/${platformId}`, identityId);
+      }
+      async deleteSourceIndex(source, platformId) {
+        await this.storage.delete(`idx/sources/${source}/${platformId}`);
+      }
+      async getUserCount() {
+        const keys = await this.storage.keys("users/");
+        return keys.length;
+      }
+    };
+  }
+});
+
+// src/plugins/identity/middleware/auto-register.ts
+function createAutoRegisterHandler(service, store) {
+  const lastSeenThrottle = /* @__PURE__ */ new Map();
+  return async (payload, next) => {
+    const { channelId, userId, meta } = payload;
+    const identityId = formatIdentityId(channelId, userId);
+    const channelUser = meta?.channelUser;
+    let identity = await store.getIdentity(identityId);
+    let user;
+    if (!identity) {
+      const result = await service.createUserWithIdentity({
+        displayName: channelUser?.displayName ?? userId,
+        username: channelUser?.username,
+        source: channelId,
+        platformId: userId,
+        platformUsername: channelUser?.username,
+        platformDisplayName: channelUser?.displayName
+      });
+      user = result.user;
+      identity = result.identity;
+    } else {
+      user = await service.getUser(identity.userId);
+      if (!user) return next();
+      const now = Date.now();
+      const lastSeen = lastSeenThrottle.get(user.userId);
+      if (!lastSeen || now - lastSeen > LAST_SEEN_THROTTLE_MS) {
+        lastSeenThrottle.set(user.userId, now);
+        await store.putUser({ ...user, lastSeenAt: new Date(now).toISOString() });
+      }
+      if (channelUser) {
+        const needsUpdate = channelUser.displayName !== void 0 && channelUser.displayName !== identity.platformDisplayName || channelUser.username !== void 0 && channelUser.username !== identity.platformUsername;
+        if (needsUpdate) {
+          await store.putIdentity({
+            ...identity,
+            platformDisplayName: channelUser.displayName ?? identity.platformDisplayName,
+            platformUsername: channelUser.username ?? identity.platformUsername,
+            updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        }
+      }
+    }
+    if (meta) {
+      meta.identity = {
+        userId: user.userId,
+        identityId: identity.identityId,
+        displayName: user.displayName,
+        username: user.username,
+        role: user.role
+      };
+    }
+    return next();
+  };
+}
+var LAST_SEEN_THROTTLE_MS;
+var init_auto_register = __esm({
+  "src/plugins/identity/middleware/auto-register.ts"() {
+    "use strict";
+    init_types();
+    LAST_SEEN_THROTTLE_MS = 5 * 60 * 1e3;
+  }
+});
+
+// src/plugins/identity/routes/users.ts
+var users_exports = {};
+__export(users_exports, {
+  registerIdentityRoutes: () => registerIdentityRoutes
+});
+function registerIdentityRoutes(app, deps) {
+  const { service, tokenStore } = deps;
+  function resolveUserId(request) {
+    return tokenStore?.getUserId?.(request.auth?.tokenId);
+  }
+  app.get("/users", async (request) => {
+    const { source, role, q } = request.query;
+    if (q) return service.searchUsers(q);
+    return service.listUsers({ source, role });
+  });
+  app.get("/users/me", async (request, reply) => {
+    const userId = resolveUserId(request);
+    if (!userId) return reply.status(403).send({ error: "Identity not set up" });
+    const user = await service.getUser(userId);
+    if (!user) return reply.status(404).send({ error: "User not found" });
+    return user;
+  });
+  app.put("/users/me", async (request, reply) => {
+    const userId = resolveUserId(request);
+    if (!userId) {
+      return reply.status(403).send({ error: "Identity not set up. Call POST /identity/setup first." });
+    }
+    const body = request.body;
+    return service.updateUser(userId, {
+      displayName: body.displayName,
+      username: body.username,
+      avatarUrl: body.avatarUrl,
+      timezone: body.timezone,
+      locale: body.locale
+    });
+  });
+  app.get("/users/:userId", async (request, reply) => {
+    const { userId } = request.params;
+    const user = await service.getUser(userId);
+    if (!user) return reply.status(404).send({ error: "User not found" });
+    return user;
+  });
+  app.put("/users/:userId/role", async (request, reply) => {
+    const callerUserId = resolveUserId(request);
+    if (!callerUserId) return reply.status(403).send({ error: "Identity not set up" });
+    const caller = await service.getUser(callerUserId);
+    if (!caller || caller.role !== "admin") return reply.status(403).send({ error: "Admin only" });
+    const { userId } = request.params;
+    const { role } = request.body;
+    await service.setRole(userId, role);
+    return { ok: true };
+  });
+  app.get("/users/:userId/identities", async (request) => {
+    const { userId } = request.params;
+    return service.getIdentitiesFor(userId);
+  });
+  app.get("/resolve/:identityId", async (request, reply) => {
+    const { identityId } = request.params;
+    const user = await service.getUserByIdentity(identityId);
+    if (!user) return reply.status(404).send({ error: "Identity not found" });
+    const identity = await service.getIdentity(identityId);
+    return { user, identity };
+  });
+  app.post("/link", async (request, reply) => {
+    const callerUserId = resolveUserId(request);
+    if (!callerUserId) return reply.status(403).send({ error: "Identity not set up" });
+    const caller = await service.getUser(callerUserId);
+    if (!caller || caller.role !== "admin") return reply.status(403).send({ error: "Admin only" });
+    const { identityIdA, identityIdB } = request.body;
+    await service.link(identityIdA, identityIdB);
+    return { ok: true };
+  });
+  app.post("/unlink", async (request, reply) => {
+    const callerUserId = resolveUserId(request);
+    if (!callerUserId) return reply.status(403).send({ error: "Identity not set up" });
+    const caller = await service.getUser(callerUserId);
+    if (!caller || caller.role !== "admin") return reply.status(403).send({ error: "Admin only" });
+    const { identityId } = request.body;
+    await service.unlink(identityId);
+    return { ok: true };
+  });
+  app.get("/search", async (request) => {
+    const { q } = request.query;
+    if (!q) return [];
+    return service.searchUsers(q);
+  });
+}
+var init_users = __esm({
+  "src/plugins/identity/routes/users.ts"() {
+    "use strict";
+  }
+});
+
+// src/plugins/identity/routes/setup.ts
+var setup_exports = {};
+__export(setup_exports, {
+  registerSetupRoutes: () => registerSetupRoutes
+});
+import { randomBytes } from "crypto";
+function registerSetupRoutes(app, deps) {
+  const { service, tokenStore } = deps;
+  app.post("/setup", async (request, reply) => {
+    const auth = request.auth;
+    if (!auth?.tokenId) return reply.status(401).send({ error: "JWT required" });
+    const existingUserId = tokenStore?.getUserId?.(auth.tokenId);
+    if (existingUserId) {
+      const user2 = await service.getUser(existingUserId);
+      if (user2) return user2;
+    }
+    const body = request.body;
+    if (body?.linkCode) {
+      const entry = linkCodes.get(body.linkCode);
+      if (!entry || entry.expiresAt < Date.now()) {
+        return reply.status(401).send({ error: "Invalid or expired link code" });
+      }
+      linkCodes.delete(body.linkCode);
+      await service.createIdentity(entry.userId, {
+        source: "api",
+        platformId: auth.tokenId
+      });
+      tokenStore?.setUserId?.(auth.tokenId, entry.userId);
+      return service.getUser(entry.userId);
+    }
+    if (!body?.displayName) return reply.status(400).send({ error: "displayName is required" });
+    const { user } = await service.createUserWithIdentity({
+      displayName: body.displayName,
+      username: body.username,
+      source: "api",
+      platformId: auth.tokenId
+    });
+    tokenStore?.setUserId?.(auth.tokenId, user.userId);
+    return user;
+  });
+  app.post("/link-code", async (request, reply) => {
+    const auth = request.auth;
+    if (!auth?.tokenId) return reply.status(401).send({ error: "JWT required" });
+    const userId = tokenStore?.getUserId?.(auth.tokenId);
+    if (!userId) return reply.status(403).send({ error: "Identity not set up" });
+    const code = randomBytes(16).toString("hex");
+    const expiresAt = Date.now() + 5 * 60 * 1e3;
+    for (const [k, v] of linkCodes) {
+      if (v.expiresAt < Date.now()) linkCodes.delete(k);
+    }
+    linkCodes.set(code, { userId, expiresAt });
+    return { linkCode: code, expiresAt: new Date(expiresAt).toISOString() };
+  });
+}
+var linkCodes;
+var init_setup = __esm({
+  "src/plugins/identity/routes/setup.ts"() {
+    "use strict";
+    linkCodes = /* @__PURE__ */ new Map();
+  }
+});
+
+// src/plugins/identity/index.ts
+function createIdentityPlugin() {
+  return {
+    name: "@openacp/identity",
+    version: "1.0.0",
+    description: "User identity, cross-platform linking, and role-based access",
+    essential: false,
+    permissions: [
+      "storage:read",
+      "storage:write",
+      "middleware:register",
+      "services:register",
+      "services:use",
+      "events:emit",
+      "events:read",
+      "commands:register",
+      "kernel:access"
+    ],
+    optionalPluginDependencies: {
+      "@openacp/api-server": ">=1.0.0"
+    },
+    async setup(ctx) {
+      const store = new KvIdentityStore(ctx.storage);
+      const service = new IdentityServiceImpl(store, (event, data) => {
+        ctx.emit(event, data);
+      });
+      ctx.registerService("identity", service);
+      ctx.registerMiddleware(Hook.MESSAGE_INCOMING, {
+        priority: 110,
+        handler: createAutoRegisterHandler(service, store)
+      });
+      ctx.registerCommand({
+        name: "whoami",
+        description: "Set your username and display name",
+        usage: "@username [Display Name]",
+        category: "plugin",
+        async handler(args2) {
+          const raw = args2.raw.trim();
+          if (!raw) return { type: "error", message: "Usage: /whoami @username [Display Name]" };
+          const tokens = raw.split(/\s+/);
+          const first = tokens[0];
+          const usernameRaw = first.startsWith("@") ? first.slice(1) : first;
+          if (!/^[a-zA-Z0-9_.-]+$/.test(usernameRaw)) {
+            return { type: "error", message: "Invalid username. Only letters, numbers, _ . - allowed." };
+          }
+          const username = usernameRaw;
+          const displayName = tokens.slice(1).join(" ") || void 0;
+          const identityId = formatIdentityId(args2.channelId, args2.userId);
+          const user = await service.getUserByIdentity(identityId);
+          if (!user) {
+            return { type: "error", message: "Identity not found. Send a message first." };
+          }
+          try {
+            await service.updateUser(user.userId, { username, ...displayName && { displayName } });
+            const parts = [`@${username}`];
+            if (displayName) parts.push(`"${displayName}"`);
+            return { type: "text", text: `\u2705 Profile updated: ${parts.join(" ")}` };
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { type: "error", message };
+          }
+        }
+      });
+      const apiServer = ctx.getService("api-server");
+      if (apiServer) {
+        const tokenStore = ctx.getService("token-store");
+        const { registerIdentityRoutes: registerIdentityRoutes2 } = await Promise.resolve().then(() => (init_users(), users_exports));
+        const { registerSetupRoutes: registerSetupRoutes2 } = await Promise.resolve().then(() => (init_setup(), setup_exports));
+        apiServer.registerPlugin("/api/v1/identity", async (app) => {
+          registerIdentityRoutes2(app, { service, tokenStore: tokenStore ?? void 0 });
+          registerSetupRoutes2(app, { service, tokenStore: tokenStore ?? void 0 });
+        }, { auth: true });
+      }
+      ctx.log.info(`Identity service ready (${await service.getUserCount()} users)`);
+    }
+  };
+}
+var identity_default;
+var init_identity = __esm({
+  "src/plugins/identity/index.ts"() {
+    "use strict";
+    init_identity_service();
+    init_kv_identity_store();
+    init_auto_register();
+    init_types();
+    init_events();
+    identity_default = createIdentityPlugin();
+  }
+});
+
 // src/core/utils/read-text-file.ts
 var read_text_file_exports = {};
 __export(read_text_file_exports, {
@@ -3631,7 +4364,7 @@ var init_history_recorder = __esm({
       }
       states = /* @__PURE__ */ new Map();
       debounceTimers = /* @__PURE__ */ new Map();
-      onBeforePrompt(sessionId, text5, attachments, sourceAdapterId) {
+      onBeforePrompt(sessionId, text5, attachments, sourceAdapterId, meta) {
         let state = this.states.get(sessionId);
         if (!state) {
           state = {
@@ -3652,6 +4385,9 @@ var init_history_recorder = __esm({
         if (sourceAdapterId) {
           userTurn.sourceAdapterId = sourceAdapterId;
         }
+        if (meta && Object.keys(meta).length > 0) {
+          userTurn.meta = meta;
+        }
         state.history.turns.push(userTurn);
         const assistantTurn = {
           index: state.history.turns.length,
@@ -3986,7 +4722,7 @@ var init_context = __esm({
         ctx.registerMiddleware(Hook.AGENT_BEFORE_PROMPT, {
           priority: 200,
           handler: async (payload, next) => {
-            recorder.onBeforePrompt(payload.sessionId, payload.text, payload.attachments, payload.sourceAdapterId);
+            recorder.onBeforePrompt(payload.sessionId, payload.text, payload.attachments, payload.sourceAdapterId, payload.meta);
             return next();
           }
         });
@@ -4485,14 +5221,20 @@ var init_speech = __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.
        *
@@ -4521,6 +5263,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 {
+          }
+        }
+      }
     };
   }
 });
@@ -4538,11 +5336,10 @@ function createNotificationsPlugin() {
     essential: false,
     // Depends on security so the notification service is only active for authorized sessions
     pluginDependencies: { "@openacp/security": "^1.0.0" },
-    permissions: ["services:register", "kernel:access"],
+    permissions: ["services:register", "services:use", "kernel:access", "events:read"],
     async install(ctx) {
-      const { settings, terminal } = ctx;
-      await settings.setAll({ enabled: true });
-      terminal.log.success("Notifications defaults saved");
+      await ctx.settings.setAll({ enabled: true });
+      ctx.terminal.log.success("Notifications defaults saved");
     },
     async configure(ctx) {
       const { terminal, settings } = ctx;
@@ -4565,8 +5362,16 @@ function createNotificationsPlugin() {
     },
     async setup(ctx) {
       const core = ctx.core;
-      const manager = new NotificationManager(core.adapters);
-      ctx.registerService("notifications", manager);
+      const service = new NotificationService(core.adapters);
+      const identity = ctx.getService("identity");
+      if (identity) service.setIdentityResolver(identity);
+      ctx.on("plugin:loaded", (data) => {
+        if (data?.name === "@openacp/identity") {
+          const id = ctx.getService("identity");
+          if (id) service.setIdentityResolver(id);
+        }
+      });
+      ctx.registerService("notifications", service);
       ctx.log.info("Notifications service ready");
     }
   };
@@ -6866,7 +7671,7 @@ var init_viewer_routes = __esm({
 // src/plugins/tunnel/viewer-store.ts
 import * as fs17 from "fs";
 import * as path20 from "path";
-import { nanoid } from "nanoid";
+import { nanoid as nanoid2 } from "nanoid";
 var log10, MAX_CONTENT_SIZE, EXTENSION_LANGUAGE, ViewerStore;
 var init_viewer_store = __esm({
   "src/plugins/tunnel/viewer-store.ts"() {
@@ -6927,7 +7732,7 @@ var init_viewer_store = __esm({
           log10.debug({ filePath, size: content.length }, "File too large for viewer");
           return null;
         }
-        const id = nanoid(12);
+        const id = nanoid2(12);
         const now = Date.now();
         this.entries.set(id, {
           id,
@@ -6953,7 +7758,7 @@ var init_viewer_store = __esm({
           log10.debug({ filePath, size: combined }, "Diff content too large for viewer");
           return null;
         }
-        const id = nanoid(12);
+        const id = nanoid2(12);
         const now = Date.now();
         this.entries.set(id, {
           id,
@@ -6975,7 +7780,7 @@ var init_viewer_store = __esm({
           log10.debug({ label, size: output.length }, "Output too large for viewer");
           return null;
         }
-        const id = nanoid(12);
+        const id = nanoid2(12);
         const now = Date.now();
         this.entries.set(id, {
           id,
@@ -7424,9 +8229,9 @@ __export(token_store_exports, {
   parseDuration: () => parseDuration
 });
 import { readFile as readFile2, writeFile } from "fs/promises";
-import { randomBytes } from "crypto";
+import { randomBytes as randomBytes2 } from "crypto";
 function generateTokenId() {
-  return `tok_${randomBytes(12).toString("hex")}`;
+  return `tok_${randomBytes2(12).toString("hex")}`;
 }
 function parseDuration(duration) {
   const match = duration.match(/^(\d+)(h|d|m)$/);
@@ -7573,6 +8378,18 @@ var init_token_store = __esm({
           this.lastUsedSaveTimer = null;
         }
       }
+      /** Associate a user ID with a token. Called by identity plugin after /identity/setup. */
+      setUserId(tokenId, userId) {
+        const token = this.tokens.get(tokenId);
+        if (token) {
+          token.userId = userId;
+          this.scheduleSave();
+        }
+      }
+      /** Get the user ID associated with a token. */
+      getUserId(tokenId) {
+        return this.tokens.get(tokenId)?.userId;
+      }
       /**
        * Generates a one-time authorization code that can be exchanged for a JWT.
        *
@@ -7580,7 +8397,7 @@ var init_token_store = __esm({
        * the App, which exchanges it for a proper JWT without ever exposing the raw API secret.
        */
       createCode(opts) {
-        const code = randomBytes(16).toString("hex");
+        const code = randomBytes2(16).toString("hex");
         const now = /* @__PURE__ */ new Date();
         const ttl = opts.codeTtlMs ?? 30 * 60 * 1e3;
         const stored = {
@@ -8100,9 +8917,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, plugin2, opts) {
+      if (booted) {
+        return;
+      }
       const wrappedPlugin = async (pluginApp, pluginOpts) => {
         if (opts?.auth !== false) {
           pluginApp.addHook("onRequest", authPreHandler);
@@ -8181,7 +9005,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) => {
@@ -8263,7 +9088,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;
@@ -8533,7 +9359,6 @@ var sessions_exports = {};
 __export(sessions_exports, {
   sessionRoutes: () => sessionRoutes
 });
-import { nanoid as nanoid2 } from "nanoid";
 async function sessionRoutes(app, deps) {
   app.get("/", { preHandler: requireScopes("sessions:read") }, async () => {
     const summaries = deps.core.sessionManager.listAllSessions();
@@ -8708,26 +9533,37 @@ async function sessionRoutes(app, deps) {
         }
         attachments = await resolveAttachments(fileService, sessionId, body.attachments);
       }
-      const sourceAdapterId = body.sourceAdapterId ?? "api";
-      const turnId = body.turnId ?? nanoid2(8);
-      deps.core.eventBus.emit(BusEvent.MESSAGE_QUEUED, {
-        sessionId,
-        turnId,
-        text: body.prompt,
-        sourceAdapterId,
-        attachments,
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        queueDepth: session.queueDepth
-      });
-      await session.enqueuePrompt(body.prompt, attachments, {
-        sourceAdapterId,
-        responseAdapterId: body.responseAdapterId
-      }, turnId);
+      const sourceAdapterId = body.sourceAdapterId ?? "sse";
+      const userId = request.auth?.tokenId ?? "api";
+      const result = await deps.core.handleMessageInSession(
+        session,
+        { channelId: sourceAdapterId, userId, text: body.prompt, attachments },
+        { channelUser: { channelId: "sse", userId } },
+        { externalTurnId: body.turnId, responseAdapterId: body.responseAdapterId }
+      );
+      if (!result) {
+        throw new AuthError("MESSAGE_BLOCKED", "Message was blocked by a middleware plugin.", 403);
+      }
+      return { ok: true, sessionId, queueDepth: result.queueDepth, turnId: result.turnId };
+    }
+  );
+  app.get(
+    "/:sessionId/queue",
+    { preHandler: requireScopes("sessions:read") },
+    async (request) => {
+      const { sessionId: rawId } = SessionIdParamSchema.parse(request.params);
+      const sessionId = decodeURIComponent(rawId);
+      const session = await deps.core.getOrResumeSessionById(sessionId);
+      if (!session) {
+        throw new NotFoundError(
+          "SESSION_NOT_FOUND",
+          `Session "${sessionId}" not found`
+        );
+      }
       return {
-        ok: true,
-        sessionId,
-        queueDepth: session.queueDepth,
-        turnId
+        pending: session.queueItems,
+        processing: session.promptRunning,
+        queueDepth: session.queueDepth
       };
     }
   );
@@ -8995,7 +9831,6 @@ var init_sessions2 = __esm({
     init_error_handler();
     init_auth();
     init_attachment_utils();
-    init_events();
     init_sessions();
   }
 });
@@ -9180,7 +10015,7 @@ import { z as z4 } from "zod";
 import * as fs21 from "fs";
 import * as path24 from "path";
 import * as os5 from "os";
-import { randomBytes as randomBytes2 } from "crypto";
+import { randomBytes as randomBytes3 } from "crypto";
 import { EventEmitter } from "events";
 function expandHome2(p2) {
   if (p2.startsWith("~")) {
@@ -9310,7 +10145,7 @@ var init_config2 = __esm({
           log14.error({ errors: result.error.issues }, "Config validation failed, not saving");
           return;
         }
-        const tmpPath = this.configPath + `.tmp.${randomBytes2(4).toString("hex")}`;
+        const tmpPath = this.configPath + `.tmp.${randomBytes3(4).toString("hex")}`;
         fs21.writeFileSync(tmpPath, JSON.stringify(raw, null, 2), "utf-8");
         fs21.renameSync(tmpPath, this.configPath);
         this.config = result.data;
@@ -9879,8 +10714,8 @@ async function commandRoutes(app, deps) {
     const result = await deps.commandRegistry.execute(commandString, {
       raw: "",
       sessionId: body.sessionId ?? null,
-      channelId: "api",
-      userId: "api",
+      channelId: "sse",
+      userId: request.auth?.tokenId ?? "api",
       reply: async () => {
       }
     });
@@ -10040,11 +10875,23 @@ async function authRoutes(app, deps) {
   });
   app.get("/me", async (request) => {
     const { auth } = request;
+    const userId = auth.tokenId ? deps.tokenStore.getUserId(auth.tokenId) : void 0;
+    let displayName = null;
+    if (userId && deps.getIdentityService) {
+      const identityService = deps.getIdentityService();
+      if (identityService) {
+        const user = await identityService.getUser(userId);
+        displayName = user?.displayName ?? null;
+      }
+    }
     return {
       type: auth.type,
       tokenId: auth.tokenId,
       role: auth.role,
-      scopes: auth.scopes
+      scopes: auth.scopes,
+      userId: userId ?? null,
+      displayName,
+      claimed: !!userId
     };
   });
   app.post("/codes", {
@@ -10624,6 +11471,7 @@ function createApiServerPlugin() {
       const tokenStore = new TokenStore2(tokensFilePath);
       await tokenStore.load();
       tokenStoreRef = tokenStore;
+      ctx.registerService("token-store", tokenStore);
       const { createApiServer: createApiServer2 } = await Promise.resolve().then(() => (init_server(), server_exports));
       const { SSEManager: SSEManager2 } = await Promise.resolve().then(() => (init_sse_manager(), sse_manager_exports));
       const { StaticServer: StaticServer2 } = await Promise.resolve().then(() => (init_static_server(), static_server_exports));
@@ -10677,7 +11525,12 @@ function createApiServerPlugin() {
       server.registerPlugin("/api/v1/tunnel", async (app) => tunnelRoutes2(app, deps));
       server.registerPlugin("/api/v1/notify", async (app) => notifyRoutes2(app, deps));
       server.registerPlugin("/api/v1/commands", async (app) => commandRoutes2(app, deps));
-      server.registerPlugin("/api/v1/auth", async (app) => authRoutes2(app, { tokenStore, getJwtSecret: () => jwtSecret }));
+      server.registerPlugin("/api/v1/auth", async (app) => authRoutes2(app, {
+        tokenStore,
+        getJwtSecret: () => jwtSecret,
+        // Lazy resolver: identity plugin may not be loaded, so we fetch it on demand
+        getIdentityService: () => ctx.getService("identity") ?? void 0
+      }));
       server.registerPlugin("/api/v1/plugins", async (app) => pluginRoutes2(app, deps));
       const appConfig = core.configManager.get();
       const workspaceName = appConfig.instanceName ?? "Main";
@@ -10826,7 +11679,7 @@ var init_api_server = __esm({
 });
 
 // src/plugins/sse-adapter/connection-manager.ts
-import { randomBytes as randomBytes4 } from "crypto";
+import { randomBytes as randomBytes5 } from "crypto";
 var ConnectionManager;
 var init_connection_manager = __esm({
   "src/plugins/sse-adapter/connection-manager.ts"() {
@@ -10835,6 +11688,8 @@ var init_connection_manager = __esm({
       connections = /* @__PURE__ */ new Map();
       // Secondary index: sessionId → Set of connection IDs for O(1) broadcast targeting
       sessionIndex = /* @__PURE__ */ new Map();
+      // Secondary index: userId → Set of connection IDs for user-level event delivery
+      userIndex = /* @__PURE__ */ new Map();
       maxConnectionsPerSession;
       maxTotalConnections;
       constructor(opts) {
@@ -10857,7 +11712,7 @@ var init_connection_manager = __esm({
         if (sessionConns && sessionConns.size >= this.maxConnectionsPerSession) {
           throw new Error("Maximum connections per session reached");
         }
-        const id = `conn_${randomBytes4(8).toString("hex")}`;
+        const id = `conn_${randomBytes5(8).toString("hex")}`;
         const connection = { id, sessionId, tokenId, response, connectedAt: /* @__PURE__ */ new Date() };
         this.connections.set(id, connection);
         let sessionConnsSet = this.sessionIndex.get(sessionId);
@@ -10869,7 +11724,66 @@ var init_connection_manager = __esm({
         response.on("close", () => this.removeConnection(id));
         return connection;
       }
-      /** Remove a connection from both indexes. Called automatically on client disconnect. */
+      /**
+       * Registers a user-level SSE connection (not tied to a specific session).
+       * Used for notifications and system events delivered to a user.
+       *
+       * @throws if the global connection limit is reached.
+       */
+      addUserConnection(userId, tokenId, response) {
+        if (this.connections.size >= this.maxTotalConnections) {
+          throw new Error("Maximum total connections reached");
+        }
+        const id = `conn_${randomBytes5(8).toString("hex")}`;
+        const connection = {
+          id,
+          sessionId: "",
+          tokenId,
+          userId,
+          response,
+          connectedAt: /* @__PURE__ */ new Date()
+        };
+        this.connections.set(id, connection);
+        let userConns = this.userIndex.get(userId);
+        if (!userConns) {
+          userConns = /* @__PURE__ */ new Set();
+          this.userIndex.set(userId, userConns);
+        }
+        userConns.add(id);
+        response.on("close", () => this.removeConnection(id));
+        return connection;
+      }
+      /**
+       * Writes a serialized SSE event to all connections for a given user.
+       *
+       * Uses the same backpressure strategy as `broadcast`: flag on first overflow,
+       * forcibly close if still backpressured on the next write.
+       */
+      pushToUser(userId, serializedEvent) {
+        const connIds = this.userIndex.get(userId);
+        if (!connIds) return;
+        for (const connId of connIds) {
+          const conn = this.connections.get(connId);
+          if (!conn || conn.response.writableEnded) continue;
+          try {
+            const ok3 = conn.response.write(serializedEvent);
+            if (!ok3) {
+              if (conn.backpressured) {
+                conn.response.end();
+                this.removeConnection(conn.id);
+              } else {
+                conn.backpressured = true;
+                conn.response.once("drain", () => {
+                  conn.backpressured = false;
+                });
+              }
+            }
+          } catch {
+            this.removeConnection(conn.id);
+          }
+        }
+      }
+      /** Remove a connection from all indexes. Called automatically on client disconnect. */
       removeConnection(connectionId) {
         const conn = this.connections.get(connectionId);
         if (!conn) return;
@@ -10879,6 +11793,13 @@ var init_connection_manager = __esm({
           sessionConns.delete(connectionId);
           if (sessionConns.size === 0) this.sessionIndex.delete(conn.sessionId);
         }
+        if (conn.userId) {
+          const userConns = this.userIndex.get(conn.userId);
+          if (userConns) {
+            userConns.delete(connectionId);
+            if (userConns.size === 0) this.userIndex.delete(conn.userId);
+          }
+        }
       }
       /** Returns all active connections for a session. */
       getConnectionsBySession(sessionId) {
@@ -10938,6 +11859,7 @@ var init_connection_manager = __esm({
         }
         this.connections.clear();
         this.sessionIndex.clear();
+        this.userIndex.clear();
       }
     };
   }
@@ -11131,6 +12053,22 @@ var init_adapter = __esm({
           this.connectionManager.broadcast(notification.sessionId, serialized);
         }
       }
+      /**
+       * Delivers a push notification to a specific user's SSE connections.
+       *
+       * `platformId` is the userId for the SSE adapter — SSE has no concept of
+       * platform-specific user handles, so we use the internal userId directly.
+       */
+      async sendUserNotification(platformId, message, options) {
+        const serialized = `event: notification:text
+data: ${JSON.stringify({
+          text: message.text ?? message.summary ?? "",
+          ...options ?? {}
+        })}
+
+`;
+        this.connectionManager.pushToUser(platformId, serialized);
+      }
       /** SSE has no concept of threads — return sessionId as the threadId */
       async createSessionThread(sessionId, _name) {
         return sessionId;
@@ -11221,8 +12159,13 @@ async function sseRoutes(app, deps) {
         }
         attachments = await resolveAttachments(fileService, sessionId, body.attachments);
       }
-      await session.enqueuePrompt(body.prompt, attachments, { sourceAdapterId: "sse" });
-      return { ok: true, sessionId, queueDepth: session.queueDepth };
+      const userId = request.auth?.tokenId ?? "api";
+      const { turnId, queueDepth } = await deps.core.handleMessageInSession(
+        session,
+        { channelId: "sse", userId, text: body.prompt, attachments },
+        { channelUser: { channelId: "sse", userId } }
+      );
+      return { ok: true, sessionId, queueDepth, turnId };
     }
   );
   app.post(
@@ -11300,6 +12243,45 @@ async function sseRoutes(app, deps) {
       total: connections.length
     };
   });
+  app.get("/events", async (request, reply) => {
+    const auth = request.auth;
+    if (!auth?.tokenId) {
+      return reply.status(401).send({ error: "Unauthorized" });
+    }
+    const userId = deps.getUserId?.(auth.tokenId);
+    if (!userId) {
+      return reply.status(403).send({ error: "Identity not set up. Complete /identity/setup first." });
+    }
+    try {
+      deps.connectionManager.addUserConnection(userId, auth.tokenId, reply.raw);
+    } catch (err) {
+      return reply.status(503).send({ error: err.message });
+    }
+    reply.hijack();
+    const raw = reply.raw;
+    raw.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      "Connection": "keep-alive",
+      // Disable buffering in Nginx/Cloudflare so events arrive without delay
+      "X-Accel-Buffering": "no"
+    });
+    raw.write(`event: heartbeat
+data: ${JSON.stringify({ ts: Date.now() })}
+
+`);
+    const heartbeat = setInterval(() => {
+      if (raw.writableEnded) {
+        clearInterval(heartbeat);
+        return;
+      }
+      raw.write(`event: heartbeat
+data: ${JSON.stringify({ ts: Date.now() })}
+
+`);
+    }, 3e4);
+    raw.on("close", () => clearInterval(heartbeat));
+  });
 }
 var init_routes = __esm({
   "src/plugins/sse-adapter/routes.ts"() {
@@ -11353,6 +12335,7 @@ var init_sse_adapter = __esm({
         _connectionManager = connectionManager;
         ctx.registerService("adapter:sse", adapter);
         const commandRegistry = ctx.getService("command-registry");
+        const tokenStore = ctx.getService("token-store");
         ctx.on(BusEvent.SESSION_DELETED, (data) => {
           const { sessionId } = data;
           eventBuffer.cleanup(sessionId);
@@ -11366,7 +12349,8 @@ var init_sse_adapter = __esm({
             core,
             connectionManager,
             eventBuffer,
-            commandRegistry: commandRegistry ?? void 0
+            commandRegistry: commandRegistry ?? void 0,
+            getUserId: tokenStore ? (id) => tokenStore.getUserId(id) : void 0
           });
         }, { auth: true });
         ctx.log.info("SSE adapter registered");
@@ -17436,7 +18420,11 @@ var init_adapter2 = __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;
@@ -17560,10 +18548,19 @@ var init_adapter2 = __esm({
                   });
                 } catch {
                 }
-              } else if (response.type === "text" || response.type === "error") {
-                const text5 = response.type === "text" ? response.text : `\u274C ${response.message}`;
+              } else if (response.type === "text" || response.type === "error" || response.type === "adaptive") {
+                let text5;
+                let parseMode;
+                if (response.type === "adaptive") {
+                  const variant = response.variants?.["telegram"];
+                  text5 = variant?.text ?? response.fallback;
+                  parseMode = variant?.parse_mode;
+                } else {
+                  text5 = response.type === "text" ? response.text : `\u274C ${response.message}`;
+                  parseMode = "Markdown";
+                }
                 try {
-                  await ctx.editMessageText(text5, { parse_mode: "Markdown" });
+                  await ctx.editMessageText(text5, { ...parseMode && { parse_mode: parseMode } });
                 } catch {
                 }
               }
@@ -17653,12 +18650,16 @@ ${p2}` : p2;
         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((c3) => c3.command));
+        const pluginCommands = registryCommands.filter((c3) => c3.category === "plugin" && !staticNames.has(c3.name) && /^[a-z0-9_]+$/.test(c3.name)).map((c3) => ({ command: c3.name, description: c3.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"
@@ -17845,6 +18846,15 @@ OpenACP will automatically retry until this is resolved.`;
               message_thread_id: topicId
             });
             break;
+          case "adaptive": {
+            const variant = response.variants?.["telegram"];
+            const text5 = variant?.text ?? response.fallback;
+            await this.bot.api.sendMessage(chatId, text5, {
+              message_thread_id: topicId,
+              ...variant?.parse_mode && { parse_mode: variant.parse_mode }
+            });
+            break;
+          }
           case "error":
             await this.bot.api.sendMessage(
               chatId,
@@ -17953,12 +18963,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) => log29.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) => log29.error({ err }, "handleMessage error"));
         });
         this.bot.on("message:photo", async (ctx) => {
           const threadId = ctx.message.message_thread_id;
@@ -18922,6 +19945,7 @@ var init_core_plugins = __esm({
   "src/plugins/core-plugins.ts"() {
     "use strict";
     init_security();
+    init_identity();
     init_file_service2();
     init_context();
     init_speech();
@@ -18933,6 +19957,8 @@ var init_core_plugins = __esm({
     corePlugins = [
       // Service plugins (no adapter dependencies)
       security_default,
+      identity_default,
+      // Must boot after security (blocked users rejected before identity records are created)
       file_service_default,
       context_default,
       speech_default,
@@ -21162,16 +22188,16 @@ var init_prompt_queue = __esm({
        * immediately. Otherwise, it's buffered and the returned promise resolves
        * only after the prompt finishes processing.
        */
-      async enqueue(text5, attachments, routing, turnId) {
+      async enqueue(text5, userPrompt, attachments, routing, turnId, meta) {
         if (this.processing) {
           return new Promise((resolve9) => {
-            this.queue.push({ text: text5, attachments, routing, turnId, resolve: resolve9 });
+            this.queue.push({ text: text5, userPrompt, attachments, routing, turnId, meta, resolve: resolve9 });
           });
         }
-        await this.process(text5, attachments, routing, turnId);
+        await this.process(text5, userPrompt, attachments, routing, turnId, meta);
       }
       /** Run a single prompt through the processor, then drain the next queued item. */
-      async process(text5, attachments, routing, turnId) {
+      async process(text5, userPrompt, attachments, routing, turnId, meta) {
         this.processing = true;
         this.abortController = new AbortController();
         const { signal } = this.abortController;
@@ -21181,7 +22207,7 @@ var init_prompt_queue = __esm({
         });
         try {
           await Promise.race([
-            this.processor(text5, attachments, routing, turnId),
+            this.processor(text5, userPrompt, attachments, routing, turnId, meta),
             new Promise((_, reject) => {
               signal.addEventListener("abort", () => reject(new Error("Prompt aborted")), { once: true });
             })
@@ -21202,7 +22228,7 @@ var init_prompt_queue = __esm({
       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);
         }
       }
       /**
@@ -21224,6 +22250,13 @@ var init_prompt_queue = __esm({
       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
+        }));
+      }
     };
   }
 });
@@ -21309,17 +22342,31 @@ var init_permission_gate = __esm({
 
 // src/core/sessions/turn-context.ts
 import { nanoid as nanoid4 } 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 ?? nanoid4(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 ?? nanoid4(8),
+    sourceAdapterId,
+    responseAdapterId,
+    userPrompt,
+    finalPrompt,
+    attachments,
+    meta
+  };
+}
 function isSystemEvent(event) {
   return SYSTEM_EVENT_TYPES.has(event.type);
 }
@@ -21431,7 +22478,7 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
         this.log = createSessionLogger(this.id, moduleLog);
         this.log.info({ agentName: this.agentName }, "Session created");
         this.queue = new PromptQueue(
-          (text5, attachments, routing, turnId) => this.processPrompt(text5, attachments, routing, turnId),
+          (text5, userPrompt, attachments, routing, turnId, meta) => this.processPrompt(text5, userPrompt, attachments, routing, turnId, meta),
           (err) => {
             this.log.error({ err }, "Prompt execution failed");
             const message = err instanceof Error ? err.message : String(err);
@@ -21511,6 +22558,10 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
       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) {
@@ -21530,24 +22581,31 @@ Additionally, include a [TTS]...[/TTS] block with a spoken-friendly summary of y
        * 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(text5, attachments, routing, externalTurnId) {
+      async enqueuePrompt(text5, attachments, routing, externalTurnId, meta) {
         const turnId = externalTurnId ?? nanoid5(8);
+        const turnMeta = meta ?? { turnId };
+        const userPrompt = text5;
         if (this.middlewareChain) {
-          const payload = { text: text5, attachments, sessionId: this.id, sourceAdapterId: routing?.sourceAdapterId };
+          const payload = { text: text5, attachments, sessionId: this.id, sourceAdapterId: routing?.sourceAdapterId, meta: turnMeta };
           const result = await this.middlewareChain.execute(Hook.AGENT_BEFORE_PROMPT, payload, async (p2) => p2);
-          if (!result) return turnId;
+          if (!result) throw new Error("PROMPT_BLOCKED");
           text5 = result.text;
           attachments = result.attachments;
         }
-        await this.queue.enqueue(text5, attachments, routing, turnId);
+        await this.queue.enqueue(text5, userPrompt, attachments, routing, turnId, turnMeta);
         return turnId;
       }
-      async processPrompt(text5, attachments, routing, turnId) {
+      async processPrompt(text5, userPrompt, attachments, routing, turnId, meta) {
         if (this._status === "finished") return;
         this.activeTurnContext = createTurnContext(
           routing?.sourceAdapterId ?? this.channelId,
           routing?.responseAdapterId,
-          turnId
+          turnId,
+          userPrompt,
+          text5,
+          // finalPrompt (after middleware transformations)
+          attachments,
+          meta
         );
         this.emit(SessionEv.TURN_STARTED, this.activeTurnContext);
         this.promptCount++;
@@ -21582,6 +22640,13 @@ ${text5}`;
         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(() => {
@@ -21591,7 +22656,16 @@ ${text5}`;
           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 (p2) => p2).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 (p2) => p2).catch(() => {
           });
         }
         let stopReason = "end_turn";
@@ -21617,8 +22691,20 @@ ${text5}`;
           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 (p2) => p2).catch(() => {
+            this.middlewareChain.execute(Hook.TURN_END, { sessionId: this.id, stopReason, durationMs: Date.now() - promptStart, turnId: finalTurnId, meta }, async (p2) => p2).catch(() => {
+            });
+          }
+          if (this.middlewareChain) {
+            this.middlewareChain.execute(Hook.AGENT_AFTER_TURN, {
+              sessionId: this.id,
+              turnId: finalTurnId,
+              fullText: turnTextBuffer.join(""),
+              stopReason,
+              meta
+            }, async (p2) => p2).catch(() => {
             });
           }
           this.activeTurnContext = null;
@@ -22250,7 +23336,7 @@ var init_session_bridge = __esm({
           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) {
@@ -22303,14 +23389,16 @@ var init_session_bridge = __esm({
           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 });
@@ -22476,6 +23564,7 @@ var init_session_bridge = __esm({
         }
         this.deps.eventBus?.emit(BusEvent.AGENT_EVENT, {
           sessionId: this.session.id,
+          turnId: this.session.activeTurnContext?.turnId ?? "",
           event
         });
         return outgoing;
@@ -23315,8 +24404,7 @@ var init_session_factory = __esm({
           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
@@ -23390,6 +24478,7 @@ var init_session_factory = __esm({
           const failedSessionId = createParams.existingSessionId ?? `failed-${Date.now()}`;
           this.eventBus.emit(BusEvent.AGENT_EVENT, {
             sessionId: failedSessionId,
+            turnId: "",
             event: guidance
           });
           throw err;
@@ -23418,7 +24507,8 @@ var init_session_factory = __esm({
           this.eventBus.emit(BusEvent.SESSION_CREATED, {
             sessionId: session.id,
             agent: session.agentName,
-            status: session.status
+            status: session.status,
+            userId: createParams.userId
           });
         }
         return session;
@@ -23759,7 +24849,7 @@ var init_agent_switch_handler = __esm({
           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,
@@ -23822,7 +24912,7 @@ var init_agent_switch_handler = __esm({
             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,
@@ -23837,7 +24927,7 @@ var init_agent_switch_handler = __esm({
             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,
@@ -24663,11 +25753,55 @@ var init_plugin_storage = __esm({
       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() {
         fs45.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 (p2) => {
+            const full = p2 ? `${prefix}${p2}` : 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}`)
+        };
+      }
     };
   }
 });
@@ -24733,9 +25867,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 = {
@@ -24786,6 +25963,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, (p2) => p2);
+    },
+    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");
@@ -25669,6 +26866,7 @@ var init_core = __esm({
     init_error_tracker();
     init_log();
     init_events();
+    init_turn_context();
     log44 = createChildLogger({ module: "core" });
     OpenACPCore = class {
       configManager;
@@ -25945,7 +27143,7 @@ var init_core = __esm({
        *
        * If no session is found, the user is told to start one with /new.
        */
-      async handleMessage(message) {
+      async handleMessage(message, initialMeta) {
         log44.debug(
           {
             channelId: message.channelId,
@@ -25954,10 +27152,12 @@ var init_core = __esm({
           },
           "Incoming message"
         );
+        const turnId = nanoid6(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;
@@ -25992,9 +27192,6 @@ var init_core = __esm({
           }
           return;
         }
-        this.sessionManager.patchRecord(session.id, {
-          lastActiveAt: (/* @__PURE__ */ new Date()).toISOString()
-        });
         let text5 = message.text;
         if (this.assistantManager?.isAssistant(session.id)) {
           const pending = this.assistantManager.consumePendingSystemPrompt(message.channelId);
@@ -26007,23 +27204,85 @@ User message:
 ${text5}`;
           }
         }
-        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 = nanoid6(8);
-          this.eventBus.emit(BusEvent.MESSAGE_QUEUED, {
+        const enrichedMeta = message.meta ?? meta;
+        await this._dispatchToSession(session, text5, 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, text5, 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: text5,
+          sourceAdapterId: routing.sourceAdapterId,
+          attachments,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          queueDepth: session.queueDepth + 1,
+          sender: extractSender(meta)
+        });
+        session.enqueuePrompt(text5, attachments, routing, turnId, meta).catch((err) => {
+          const reason = err instanceof Error ? err.message : String(err);
+          log44.warn({ err, sessionId: session.id, turnId, reason }, "enqueuePrompt failed \u2014 emitting message:failed");
+          this.eventBus.emit(BusEvent.MESSAGE_FAILED, {
             sessionId: session.id,
             turnId,
-            text: text5,
-            sourceAdapterId,
-            attachments: message.attachments,
-            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-            queueDepth: session.queueDepth
+            reason
           });
-          await session.enqueuePrompt(text5, message.attachments, routing, turnId);
-        } else {
-          await session.enqueuePrompt(text5, 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 ?? nanoid6(8);
+        const meta = { turnId, ...initialMeta };
+        let text5 = message.text;
+        let { attachments } = message;
+        let enrichedMeta = meta;
+        if (this.lifecycleManager?.middlewareChain) {
+          const payload = {
+            channelId: message.channelId,
+            threadId: session.id,
+            userId: message.userId,
+            text: text5,
+            attachments,
+            meta
+          };
+          const result = await this.lifecycleManager.middlewareChain.execute(
+            Hook.MESSAGE_INCOMING,
+            payload,
+            async (p2) => p2
+          );
+          if (!result) return { turnId, queueDepth: session.queueDepth };
+          text5 = result.text;
+          attachments = result.attachments;
+          enrichedMeta = result.meta ?? meta;
         }
+        const routing = {
+          sourceAdapterId: message.channelId,
+          responseAdapterId: options?.responseAdapterId
+        };
+        await this._dispatchToSession(session, text5, attachments, routing, turnId, enrichedMeta);
+        return { turnId, queueDepth: session.queueDepth };
       }
       // --- Unified Session Creation Pipeline ---
       /**
@@ -26135,7 +27394,7 @@ ${text5}`;
             } 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, {
@@ -26147,6 +27406,18 @@ ${text5}`;
           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,
@@ -26584,7 +27855,7 @@ function registerSessionCommands(registry, _core) {
         await assistant.enqueuePrompt(prompt);
         return { type: "delegated" };
       }
-      return { type: "text", text: "Usage: /new <agent> <workspace>\nOr use the Assistant topic for guided setup." };
+      return { type: "text", text: "Usage: /new [agent] [workspace]\nOr use the Assistant topic for guided setup." };
     }
   });
   registry.register({
@@ -26656,7 +27927,7 @@ Prompts: ${session.promptCount}` };
   registry.register({
     name: "resume",
     description: "Resume a previous session",
-    usage: "<session-number>",
+    usage: "[session-number]",
     category: "system",
     handler: async (args2) => {
       const assistant = core.assistantManager?.get(args2.channelId);
@@ -26670,7 +27941,7 @@ Prompts: ${session.promptCount}` };
   registry.register({
     name: "handoff",
     description: "Hand off session to another agent",
-    usage: "<agent-name>",
+    usage: "[agent-name]",
     category: "system",
     handler: async (args2) => {
       if (!args2.sessionId) return { type: "text", text: "Use /handoff inside a session topic." };
@@ -26856,7 +28127,7 @@ function registerAgentCommands(registry, _core) {
   registry.register({
     name: "install",
     description: "Install an agent",
-    usage: "<agent-name>",
+    usage: "[agent-name]",
     category: "system",
     handler: async (args2) => {
       const agentName = args2.raw.trim();
@@ -26931,7 +28202,7 @@ function registerAdminCommands(registry, _core) {
   registry.register({
     name: "integrate",
     description: "Set up a new channel integration",
-    usage: "<channel>",
+    usage: "[channel]",
     category: "system",
     handler: async (args2) => {
       const channel = args2.raw.trim();
@@ -27334,7 +28605,7 @@ var init_plugin_field_registry = __esm({
 
 // src/core/setup/types.ts
 var ONBOARD_SECTION_OPTIONS, CHANNEL_META;
-var init_types = __esm({
+var init_types2 = __esm({
   "src/core/setup/types.ts"() {
     "use strict";
     ONBOARD_SECTION_OPTIONS = [
@@ -27843,7 +29114,7 @@ var CHANNEL_PLUGIN_NAME;
 var init_setup_channels = __esm({
   "src/core/setup/setup-channels.ts"() {
     "use strict";
-    init_types();
+    init_types2();
     init_helpers2();
     CHANNEL_PLUGIN_NAME = {
       discord: "@openacp/discord-adapter"
@@ -28501,7 +29772,7 @@ async function runReconfigure(configManager, settingsManager) {
 var init_wizard = __esm({
   "src/core/setup/wizard.ts"() {
     "use strict";
-    init_types();
+    init_types2();
     init_helpers2();
     init_setup_agents();
     init_setup_run_mode();
@@ -28516,8 +29787,8 @@ var init_wizard = __esm({
 });
 
 // src/core/setup/index.ts
-var setup_exports = {};
-__export(setup_exports, {
+var setup_exports2 = {};
+__export(setup_exports2, {
   detectAgents: () => detectAgents,
   printStartBanner: () => printStartBanner,
   runReconfigure: () => runReconfigure,
@@ -28529,7 +29800,7 @@ __export(setup_exports, {
   validateBotToken: () => validateBotToken,
   validateChatId: () => validateChatId
 });
-var init_setup = __esm({
+var init_setup2 = __esm({
   "src/core/setup/index.ts"() {
     "use strict";
     init_wizard();
@@ -28778,7 +30049,7 @@ async function startServer(opts) {
   const configManager = new ConfigManager(ctx.paths.config);
   const configExists = await configManager.exists();
   if (!configExists) {
-    const { runSetup: runSetup2 } = await Promise.resolve().then(() => (init_setup(), setup_exports));
+    const { runSetup: runSetup2 } = await Promise.resolve().then(() => (init_setup2(), setup_exports2));
     const shouldStart = await runSetup2(configManager, { settingsManager, pluginRegistry });
     if (!shouldStart) process.exit(0);
   }
@@ -28792,7 +30063,7 @@ async function startServer(opts) {
   }
   const isForegroundTTY = !!(process.stdout.isTTY && !process.env.NO_COLOR && config.runMode !== "daemon");
   if (isForegroundTTY) {
-    const { printStartBanner: printStartBanner2 } = await Promise.resolve().then(() => (init_setup(), setup_exports));
+    const { printStartBanner: printStartBanner2 } = await Promise.resolve().then(() => (init_setup2(), setup_exports2));
     await printStartBanner2();
   }
   let spinner4;
@@ -33307,10 +34578,10 @@ async function cmdOnboard(instanceRoot) {
   const pluginRegistry = new PluginRegistry2(REGISTRY_PATH);
   await pluginRegistry.load();
   if (await cm.exists()) {
-    const { runReconfigure: runReconfigure2 } = await Promise.resolve().then(() => (init_setup(), setup_exports));
+    const { runReconfigure: runReconfigure2 } = await Promise.resolve().then(() => (init_setup2(), setup_exports2));
     await runReconfigure2(cm, settingsManager);
   } else {
-    const { runSetup: runSetup2 } = await Promise.resolve().then(() => (init_setup(), setup_exports));
+    const { runSetup: runSetup2 } = await Promise.resolve().then(() => (init_setup2(), setup_exports2));
     await runSetup2(cm, { skipRunMode: true, settingsManager, pluginRegistry, instanceRoot: OPENACP_DIR });
   }
 }
@@ -33370,7 +34641,7 @@ async function cmdDefault(command2, instanceRoot) {
     const settingsManager = new SettingsManager2(pluginsDataDir);
     const pluginRegistry = new PluginRegistry2(registryPath);
     await pluginRegistry.load();
-    const { runSetup: runSetup2 } = await Promise.resolve().then(() => (init_setup(), setup_exports));
+    const { runSetup: runSetup2 } = await Promise.resolve().then(() => (init_setup2(), setup_exports2));
     const shouldStart = await runSetup2(cm, { settingsManager, pluginRegistry, instanceRoot: root });
     if (!shouldStart) process.exit(0);
   }