@rubytech/create-realagent-code 0.1.612 → 0.1.613

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent-code",
-  "version": "0.1.612",
+  "version": "0.1.613",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent-code": "./dist/index.js"

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Real Agent ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:5e127a3b4f988e5c2a96441ca87d017d72efde5c773223579f54ec14b4ea6fd6
+content-hash: sha256:0f6a37637cbc5d7fc6fa7c444898e9609c467c5081c54bb27dcf1b979ffc7c36
 brand: realagent-code
 product-name: Real Agent
 ---
@@ -2961,10 +2961,10 @@ Telegram profile name and will tell you plainly that it cannot put a name to the
 Ask Real Agent to save the Telegram ID against the contact. It is one change to one contact, and
 it takes effect on the very next message.
 
-## Correcting what a public agent told a visitor
+## Correcting what an agent told someone
 
-When one of your public bots tells a visitor something wrong, the fix is to instruct the agent that
-is talking to them, not to message the visitor yourself.
+When one of your bots tells someone something wrong, the fix is to instruct the agent that is talking
+to them, not to message that person yourself.
 
 The reason is worth understanding, because the obvious approach quietly fails. Every conversation is
 its own separate agent with its own memory. If you send the visitor a correction from your chat, they
@@ -2979,16 +2979,28 @@ own conversation. The agent writes the message itself, in the same voice it has
 own memory now holds what it said, so it will not contradict it a moment later. The visitor sees a
 normal message from the assistant they have been talking to, with no sign that anybody stepped in.
 
+The same is true of your specialist bots. If a specialist relays for a driver, a supplier or a
+colleague, and you card that person yourself, the specialist never learns you did. It answers their
+next message with no idea what they are replying to. That happened on a live conversation: a driver
+was sent a job by card, and when he came back twelve minutes later with his prices, the bot filed
+them as a passing remark and thanked him. Instruct it the same way, naming its bot and their chat,
+and it writes the message and remembers writing it.
+
 Write the intent rather than the exact sentence. This is an instruction to the agent, not text
 delivered word for word, so "tell them we can do Thursday morning but not the afternoon" works better
 than a script.
 
-Four situations are refused, and each one says why rather than failing quietly:
-
-- The bot is not a public bot. Your own admin bot and any specialist bot are conversations with your
-  own side, not with a visitor, so there is nothing to instruct.
-- The agent has been switched off. Nothing is resurrected behind your back; turn it back on, or
-  message the person yourself.
+Six situations are refused, and each one says why rather than failing quietly:
+
+- The bot is your own admin bot. That chat is your conversation with the agent, so instructing it
+  there is the agent talking to itself.
+- The bot is bound to nothing. It answers nobody, so there is no agent to instruct.
+- The agent has been switched off, or a specialist's card has been renamed or deleted. Nothing is
+  resurrected behind your back; turn it back on, or message the person yourself.
+- The bot is not allowed to talk to that person. Every bot has its own rule about who it answers, and
+  a specialist answers a named list and nobody else. Starting a conversation the bot would refuse to
+  continue leaves the person holding a message nobody can follow up, so it is refused instead. Most
+  often this is a mistyped chat ID.
 - The chat belongs to a connected business account. Those conversations are held separately and this
   route cannot reach them.
 - The chat is a broadcast channel the bot does not allow. A channel post reaches every subscriber and

package/payload/platform/plugins/admin/skills/whats-new/SKILL.md

@@ -9,6 +9,11 @@ Invoked by the admin agent directly.
 
 This is the platform's release timeline, newest first. Each entry shows the date it shipped and the version it shipped in, so you can tell the operator how current their install is. To compare, read the installed version from `capabilities-here` and match it against the versions below. Keep answers high level and in plain English; this is a summary, not a full commit log.
 
+## 2026-08-16 (0.1.613)
+
+- You can now tell the assistant what to say to someone one of your specialist bots is handling, the same way you already could for a public bot. Until now that was refused, so the only way through was to message the person yourself, and the specialist never learned you had. It would answer their next message with no idea what they were replying to.
+- A bot will no longer start a conversation with someone it is set up never to answer. A mistyped chat ID used to send one message and then go silent, because every reply came back to a bot that refused it.
+
 ## 2026-08-15 (0.1.612)
 
 - A conversation opened from the dashboard could show as completely empty even though the agent had answered in it. The reader was discarding the agent's replies instead of drawing them, so the thread looked like nothing had ever been said. Those replies now appear.

package/payload/platform/plugins/docs/references/telegram-guide.md

@@ -138,10 +138,10 @@ Telegram profile name and will tell you plainly that it cannot put a name to the
 Ask {{productName}} to save the Telegram ID against the contact. It is one change to one contact, and
 it takes effect on the very next message.
 
-## Correcting what a public agent told a visitor
+## Correcting what an agent told someone
 
-When one of your public bots tells a visitor something wrong, the fix is to instruct the agent that
-is talking to them, not to message the visitor yourself.
+When one of your bots tells someone something wrong, the fix is to instruct the agent that is talking
+to them, not to message that person yourself.
 
 The reason is worth understanding, because the obvious approach quietly fails. Every conversation is
 its own separate agent with its own memory. If you send the visitor a correction from your chat, they
@@ -156,16 +156,28 @@ own conversation. The agent writes the message itself, in the same voice it has
 own memory now holds what it said, so it will not contradict it a moment later. The visitor sees a
 normal message from the assistant they have been talking to, with no sign that anybody stepped in.
 
+The same is true of your specialist bots. If a specialist relays for a driver, a supplier or a
+colleague, and you card that person yourself, the specialist never learns you did. It answers their
+next message with no idea what they are replying to. That happened on a live conversation: a driver
+was sent a job by card, and when he came back twelve minutes later with his prices, the bot filed
+them as a passing remark and thanked him. Instruct it the same way, naming its bot and their chat,
+and it writes the message and remembers writing it.
+
 Write the intent rather than the exact sentence. This is an instruction to the agent, not text
 delivered word for word, so "tell them we can do Thursday morning but not the afternoon" works better
 than a script.
 
-Four situations are refused, and each one says why rather than failing quietly:
-
-- The bot is not a public bot. Your own admin bot and any specialist bot are conversations with your
-  own side, not with a visitor, so there is nothing to instruct.
-- The agent has been switched off. Nothing is resurrected behind your back; turn it back on, or
-  message the person yourself.
+Six situations are refused, and each one says why rather than failing quietly:
+
+- The bot is your own admin bot. That chat is your conversation with the agent, so instructing it
+  there is the agent talking to itself.
+- The bot is bound to nothing. It answers nobody, so there is no agent to instruct.
+- The agent has been switched off, or a specialist's card has been renamed or deleted. Nothing is
+  resurrected behind your back; turn it back on, or message the person yourself.
+- The bot is not allowed to talk to that person. Every bot has its own rule about who it answers, and
+  a specialist answers a named list and nobody else. Starting a conversation the bot would refuse to
+  continue leaves the person holding a message nobody can follow up, so it is refused instead. Most
+  often this is a mistyped chat ID.
 - The chat belongs to a connected business account. Those conversations are held separately and this
   route cannot reach them.
 - The chat is a broadcast channel the bot does not allow. A channel post reaches every subscriber and

package/payload/server/public/operator.html

@@ -22,8 +22,8 @@
   <link rel="modulepreload" crossorigin href="/assets/wrench-BI28h1JF.js">
   <link rel="modulepreload" crossorigin href="/assets/page-Bkl56P8R.js">
   <link rel="stylesheet" crossorigin href="/assets/jsx-runtime-dao9WPN0.css">
-  <link rel="stylesheet" crossorigin href="/assets/useMediaQuery-DXAuc8G-.css">
   <link rel="stylesheet" crossorigin href="/assets/AdminLoginScreens-CWMpccrR.css">
+  <link rel="stylesheet" crossorigin href="/assets/useMediaQuery-DXAuc8G-.css">
   <link rel="stylesheet" href="/brand-defaults.css">
 </head>
 <body>

package/payload/server/server.js

@@ -6248,6 +6248,82 @@ function parseTelegramChannelKey(key2) {
   return { botId, senderId: rest, business: false };
 }
 
+// app/lib/telegram/access-control.ts
+function checkTelegramAccess(params) {
+  const { senderId, entry: entry3, chatId, chatType } = params;
+  const isGroup = chatType === "group" || chatType === "supergroup";
+  const isChannel = chatType === "channel";
+  if (isChannel && entry3.role !== "public") {
+    return {
+      allowed: false,
+      reason: entry3.role === "admin" ? "admin-entry-no-channels" : entry3.role === "specialist" ? "specialist-entry-no-channels" : "unbound-entry-no-channels",
+      agentType: entry3.role === "admin" ? "admin" : entry3.role === "specialist" ? "specialist" : "public"
+    };
+  }
+  if (isGroup && entry3.role !== "public") {
+    return {
+      allowed: false,
+      reason: entry3.role === "admin" ? "admin-entry-no-groups" : entry3.role === "specialist" ? "specialist-entry-no-groups" : "unbound-entry-no-groups",
+      agentType: entry3.role === "admin" ? "admin" : entry3.role === "specialist" ? "specialist" : "public"
+    };
+  }
+  if (entry3.role === "admin") {
+    const adminUsers = entry3.adminUsers ?? [];
+    if (adminUsers.includes(senderId)) {
+      return { allowed: true, reason: "admin-binding", agentType: "admin" };
+    }
+    return { allowed: false, reason: "not-admin-user", agentType: "admin" };
+  }
+  if (isGroup && entry3.role === "public") {
+    const groupPolicy = entry3.groupPolicy ?? "disabled";
+    if (groupPolicy === "allowlist") {
+      const allowGroups = entry3.allowGroups ?? [];
+      if (allowGroups.includes(chatId)) {
+        return { allowed: true, reason: "group-allowlist-match", agentType: "public" };
+      }
+      return { allowed: false, reason: "not-in-allowGroups", agentType: "public" };
+    }
+    return { allowed: false, reason: "group-policy-disabled", agentType: "public" };
+  }
+  if (isChannel && entry3.role === "public") {
+    const channelPolicy = entry3.channelPolicy ?? "disabled";
+    if (channelPolicy === "allowlist") {
+      const allowChannels = entry3.allowChannels ?? [];
+      if (allowChannels.includes(chatId)) {
+        return { allowed: true, reason: "channel-allowlist-match", agentType: "public" };
+      }
+      return { allowed: false, reason: "not-in-allowChannels", agentType: "public" };
+    }
+    return { allowed: false, reason: "channel-policy-disabled", agentType: "public" };
+  }
+  if (entry3.role === "unbound") {
+    return { allowed: false, reason: "bot-unbound", agentType: "public" };
+  }
+  if (entry3.role === "specialist") {
+    const allowFrom = entry3.allowFrom ?? [];
+    if (allowFrom.includes(senderId)) {
+      return { allowed: true, reason: "specialist-allowlist-match", agentType: "specialist" };
+    }
+    return { allowed: false, reason: "not-in-allowlist", agentType: "specialist" };
+  }
+  const policy = entry3.dmPolicy ?? "disabled";
+  switch (policy) {
+    case "open":
+      return { allowed: true, reason: "dm-policy-open", agentType: "public" };
+    case "allowlist": {
+      const allowFrom = entry3.allowFrom ?? [];
+      if (allowFrom.includes(senderId)) {
+        return { allowed: true, reason: "allowlist-match", agentType: "public" };
+      }
+      return { allowed: false, reason: "not-in-allowlist", agentType: "public" };
+    }
+    case "disabled":
+      return { allowed: false, reason: "dm-policy-disabled", agentType: "public" };
+    default:
+      return { allowed: false, reason: "unknown-dm-policy", agentType: "public" };
+  }
+}
+
 // app/lib/telegram/chat-send-policy.ts
 var BROADCAST_PREFIX = "-100";
 function checkTelegramChatSend(params) {
@@ -6263,6 +6339,21 @@ function chatSendAllowlists(entry3) {
   if (!entry3 || entry3.role !== "public") return { allowChannels: [], allowGroups: [] };
   return { allowChannels: entry3.allowChannels ?? [], allowGroups: entry3.allowGroups ?? [] };
 }
+function checkTelegramOutboundTarget(params) {
+  const { chatId, entry: entry3 } = params;
+  if (String(chatId).startsWith(BROADCAST_PREFIX)) {
+    const lists = chatSendAllowlists(entry3);
+    const verdict2 = checkTelegramChatSend({
+      chatId,
+      allowChannels: lists.allowChannels,
+      allowGroups: lists.allowGroups
+    });
+    return { allowed: verdict2.allowed, reason: verdict2.reason, kind: "broadcast" };
+  }
+  const kind = chatId < 0 ? "group" : "private";
+  const verdict = checkTelegramAccess({ senderId: chatId, entry: entry3, chatId, chatType: kind });
+  return { allowed: verdict.allowed, reason: verdict.reason, kind };
+}
 
 // app/lib/channel-pty-bridge/admin-session-id.ts
 import { createHash } from "crypto";
@@ -7732,13 +7823,24 @@ function createOperatorInjectRoutes(deps) {
     const { accountId, accountDir, entry: entry3 } = resolved;
     const role = entry3.role;
     const agent = agentOf(entry3);
-    if (role !== "public") {
-      report({ botId, chatId, sessionId: "none", role, agent, accepted: false, reason: "not-public-bot" });
+    if (role === "admin") {
+      report({ botId, chatId, sessionId: "none", role, agent, accepted: false, reason: "admin-bot" });
       return c.json(
         {
           ok: false,
-          error: "not-public-bot",
-          detail: `Bot ${botId} is a ${role} bot, not a public one. Only a public agent's conversation with a visitor can be instructed this way.`
+          error: "admin-bot",
+          detail: `Bot ${botId} is this account's admin bot. Its chat is your own conversation with the agent, so there is nothing to instruct.`
+        },
+        403
+      );
+    }
+    if (role === "unbound") {
+      report({ botId, chatId, sessionId: "none", role, agent, accepted: false, reason: "unbound-bot" });
+      return c.json(
+        {
+          ok: false,
+          error: "unbound-bot",
+          detail: `Bot ${botId} is not bound to an agent or a specialist card, so it answers nobody. Bind it before instructing it.`
         },
         403
       );
@@ -7771,30 +7873,18 @@ function createOperatorInjectRoutes(deps) {
         403
       );
     }
-    const lists = chatSendAllowlists(entry3);
-    const verdict = checkTelegramChatSend({
-      chatId: Number(chatId),
-      allowChannels: lists.allowChannels,
-      allowGroups: lists.allowGroups
-    });
+    const verdict = checkTelegramOutboundTarget({ chatId: Number(chatId), entry: entry3 });
     console.error(
       `[telegram-outbound] op=channel-send botId=${logValue2(botId)} chatId=${logValue2(chatId)} allowed=${verdict.allowed ? "yes" : "no"} reason=${verdict.reason} messageId=none`
     );
     if (!verdict.allowed) {
-      report({
-        botId,
-        chatId,
-        sessionId: "none",
-        role,
-        agent,
-        accepted: false,
-        reason: "chat-not-allowlisted"
-      });
+      const outcome = verdict.kind === "broadcast" ? "chat-not-allowlisted" : "chat-not-permitted";
+      report({ botId, chatId, sessionId: "none", role, agent, accepted: false, reason: outcome });
       return c.json(
         {
           ok: false,
-          error: "chat-not-allowlisted",
-          detail: `Chat ${chatId} is a broadcast channel that bot ${botId} does not allowlist, so nothing was sent.`
+          error: outcome,
+          detail: verdict.kind === "broadcast" ? `Chat ${chatId} is a broadcast channel that bot ${botId} does not allowlist, so nothing was sent.` : `Bot ${botId} may not talk to chat ${chatId} (${verdict.reason}), so nothing was sent. It would refuse that chat's own messages too.`
         },
         403
       );
@@ -7823,13 +7913,22 @@ function createOperatorInjectRoutes(deps) {
         accountDir,
         botId,
         botToken: entry3.token,
-        agentSlug: entry3.agent,
+        // Task 2773 — `entryAgentSlug`, not `entry.agent`: a specialist entry
+        // carries a card name and no `agent` field at all, so the property read
+        // is `undefined` there. The webhook resolves the same way
+        // (`routes/telegram.ts`), so both doors name the spawn's agent from one
+        // definition.
+        agentSlug: entryAgentSlug(entry3),
         senderId: chatId,
         conversationSubject: chatId,
         businessChatId: null,
-        role: "public",
+        // Task 2773 — the entry's OWN role, replacing a hardcoded 'public'. This
+        // picks the session derivation in `sessionIdFor` and the framing in the
+        // channel server; a value disagreeing with the registry would land the
+        // instruction in a session the counterparty's real messages never reach.
+        role,
         personId: null,
-        specialist: null,
+        specialist: entry3.role === "specialist" ? entry3.specialist : null,
         chatId,
         text: instruction,
         // An instruction carries no file by construction: there is no message to
@@ -15516,11 +15615,19 @@ async function recordManualSendContext(input, deps) {
     mechanism,
     reason
   });
-  if (input.entry.role !== "public") return refuse2("not-public-bot");
+  if (input.entry.role === "admin") return refuse2("admin-bot");
+  if (input.entry.role === "unbound") return refuse2("unbound-bot");
   const businessKey = telegramBusinessChannelKey(input.botId, String(input.chatId));
   if (deps.newestInboundTelegramDate(input.accountId, businessKey) !== null) {
     return refuse2("business-chat");
   }
+  const target = checkTelegramOutboundTarget({ chatId: input.chatId, entry: input.entry });
+  if (!target.allowed) {
+    deps.log(
+      `[telegram-manual-send] op=target-refused botId=${input.botId} chatId=${input.chatId} kind=${target.kind} reason=${target.reason}`
+    );
+    return refuse2("chat-not-permitted");
+  }
   const projectDir = deps.findSessionProjectDir(input.sessionId);
   if (projectDir === null) return refuse2("no-transcript");
   const live = deps.isLive(input.channelKey);
@@ -15541,16 +15648,22 @@ async function recordManualSendContext(input, deps) {
       accountDir: input.accountDir,
       botId: input.botId,
       botToken: input.entry.token,
-      agentSlug: input.entry.agent,
+      // Task 2773 — `entryAgentSlug`, not `entry.agent`: a specialist entry has
+      // no `agent` field, so the property read is `undefined` there.
+      agentSlug: entryAgentSlug(input.entry),
       senderId: input.senderId,
       // The route admits only a private chat, where the conversation's subject IS
       // the sender. Passed explicitly so the gateway's key and its session id are
       // derived from the same value the store row already carries.
       conversationSubject: input.senderId,
       businessChatId: null,
-      role: "public",
+      // Task 2773 — the entry's OWN role, replacing a hardcoded 'public'. It
+      // picks the session derivation in `sessionIdFor`, which for a specialist is
+      // `telegramAdminSessionId` — the same value the caller already derived for
+      // `input.sessionId`.
+      role: input.entry.role,
       personId: null,
-      specialist: null,
+      specialist: input.entry.role === "specialist" ? input.entry.specialist : null,
       chatId: String(input.chatId),
       text: input.text,
       // No file by construction: this is text the operator typed into the send
@@ -18842,82 +18955,6 @@ async function setManagedBotAccessSettings(managingBotToken, userId, isAccessRes
   return r.ok ? { ok: true } : { ok: false, error: r.error };
 }
 
-// app/lib/telegram/access-control.ts
-function checkTelegramAccess(params) {
-  const { senderId, entry: entry3, chatId, chatType } = params;
-  const isGroup = chatType === "group" || chatType === "supergroup";
-  const isChannel = chatType === "channel";
-  if (isChannel && entry3.role !== "public") {
-    return {
-      allowed: false,
-      reason: entry3.role === "admin" ? "admin-entry-no-channels" : entry3.role === "specialist" ? "specialist-entry-no-channels" : "unbound-entry-no-channels",
-      agentType: entry3.role === "admin" ? "admin" : entry3.role === "specialist" ? "specialist" : "public"
-    };
-  }
-  if (isGroup && entry3.role !== "public") {
-    return {
-      allowed: false,
-      reason: entry3.role === "admin" ? "admin-entry-no-groups" : entry3.role === "specialist" ? "specialist-entry-no-groups" : "unbound-entry-no-groups",
-      agentType: entry3.role === "admin" ? "admin" : entry3.role === "specialist" ? "specialist" : "public"
-    };
-  }
-  if (entry3.role === "admin") {
-    const adminUsers = entry3.adminUsers ?? [];
-    if (adminUsers.includes(senderId)) {
-      return { allowed: true, reason: "admin-binding", agentType: "admin" };
-    }
-    return { allowed: false, reason: "not-admin-user", agentType: "admin" };
-  }
-  if (isGroup && entry3.role === "public") {
-    const groupPolicy = entry3.groupPolicy ?? "disabled";
-    if (groupPolicy === "allowlist") {
-      const allowGroups = entry3.allowGroups ?? [];
-      if (allowGroups.includes(chatId)) {
-        return { allowed: true, reason: "group-allowlist-match", agentType: "public" };
-      }
-      return { allowed: false, reason: "not-in-allowGroups", agentType: "public" };
-    }
-    return { allowed: false, reason: "group-policy-disabled", agentType: "public" };
-  }
-  if (isChannel && entry3.role === "public") {
-    const channelPolicy = entry3.channelPolicy ?? "disabled";
-    if (channelPolicy === "allowlist") {
-      const allowChannels = entry3.allowChannels ?? [];
-      if (allowChannels.includes(chatId)) {
-        return { allowed: true, reason: "channel-allowlist-match", agentType: "public" };
-      }
-      return { allowed: false, reason: "not-in-allowChannels", agentType: "public" };
-    }
-    return { allowed: false, reason: "channel-policy-disabled", agentType: "public" };
-  }
-  if (entry3.role === "unbound") {
-    return { allowed: false, reason: "bot-unbound", agentType: "public" };
-  }
-  if (entry3.role === "specialist") {
-    const allowFrom = entry3.allowFrom ?? [];
-    if (allowFrom.includes(senderId)) {
-      return { allowed: true, reason: "specialist-allowlist-match", agentType: "specialist" };
-    }
-    return { allowed: false, reason: "not-in-allowlist", agentType: "specialist" };
-  }
-  const policy = entry3.dmPolicy ?? "disabled";
-  switch (policy) {
-    case "open":
-      return { allowed: true, reason: "dm-policy-open", agentType: "public" };
-    case "allowlist": {
-      const allowFrom = entry3.allowFrom ?? [];
-      if (allowFrom.includes(senderId)) {
-        return { allowed: true, reason: "allowlist-match", agentType: "public" };
-      }
-      return { allowed: false, reason: "not-in-allowlist", agentType: "public" };
-    }
-    case "disabled":
-      return { allowed: false, reason: "dm-policy-disabled", agentType: "public" };
-    default:
-      return { allowed: false, reason: "unknown-dm-policy", agentType: "public" };
-  }
-}
-
 // app/lib/telegram/managed-bot.ts
 function parseManagedBotUpdate(u) {
   const id = u?.bot?.id;