agentschat-mcp 0.36.4 → 0.36.7

package/codex/transport.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import WebSocket from "ws";
 import type { BridgeConfig } from "./config.ts";
 import { HeartbeatMonitor } from "../src/heartbeat.ts";
+import { InboxSync } from "./inbox-sync.ts";
 
 export class AgentsChatTransport {
   private socket?: WebSocket;
@@ -12,7 +13,13 @@ export class AgentsChatTransport {
   private retry?: ReturnType<typeof setTimeout>;
   private closed = false;
   private delay = 1000;
-  constructor(private config: BridgeConfig, private receive: (m: unknown) => void, private log: (s: string) => void = console.error) {}
+  private inboxSync?: InboxSync;
+  private syncTimer?: ReturnType<typeof setInterval>;
+  constructor(private config: BridgeConfig, private receive: (m: unknown) => void, private log: (s: string) => void = console.error,
+    recover?: (m: unknown) => boolean, private syncIntervalMs = 60_000) {
+    if (recover) this.inboxSync = new InboxSync(config.stateDir, path => this.api(path), recover,
+      () => !this.closed && this.authenticated, log);
+  }
   async api(path: string, body?: unknown) {
     let response: Response;
     try {
@@ -62,7 +69,10 @@ export class AgentsChatTransport {
     const current = () => !this.closed && this.socket === socket;
     const send = (value: unknown) => { if (current() && socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(value)); };
     const join = (channel: string) => {
-      if (!this.config.channels.length || this.config.channels.includes(channel)) send({ type: "join_channel", channel_id: channel, agent_id: this.config.agentId });
+      if (!this.config.channels.length || this.config.channels.includes(channel)) {
+        this.inboxSync?.watch(channel);
+        send({ type: "join_channel", channel_id: channel, agent_id: this.config.agentId });
+      }
     };
     this.heartbeat = new HeartbeatMonitor({ getReadyState: () => socket.readyState,
       sendPing: () => send({ type: "ping" }), reconnect: () => socket.terminate() }, 15_000, 45_000, 30_000);
@@ -74,26 +84,31 @@ export class AgentsChatTransport {
       this.heartbeat?.receivedPong();
       if (data.type === "auth_ok") {
         this.authenticated = true; this.delay = 1000; this.log(`AgentsChat connected as ${this.config.agentId}`);
+        if (this.inboxSync && !this.syncTimer) this.syncTimer = setInterval(() => { void this.inboxSync!.sync(); }, this.syncIntervalMs);
         void this.api("/api/channels/mine").then((body: any) => {
           if (!current()) return;
           const channels = Array.isArray(body) ? body : body.channels;
           if (!Array.isArray(channels)) throw new Error("Invalid membership response");
-          for (const c of channels) if (typeof (c.id ?? c.channel_id) === "string") join(c.id ?? c.channel_id);
+          const ids = channels.map((c: any) => c.id ?? c.channel_id).filter((id: any) => typeof id === "string" &&
+            (!this.config.channels.length || this.config.channels.includes(id)));
+          this.inboxSync?.memberships(ids);
+          for (const id of ids) join(id);
+          void this.inboxSync?.sync();
         }).catch(() => { if (current()) { this.log("Membership sync failed; reconnecting"); socket.terminate(); } });
       } else if (data.type === "message_ack") {
         const id = data.message_id ?? data.id, pending = this.pending.get(id);
         if (pending) { clearTimeout(pending.timer); this.pending.delete(id); pending.resolve(); }
       } else if (data.type === "channel_created" && typeof data.channel_id === "string") join(data.channel_id);
       else if (["message", "thread_reply"].includes(data.type)) this.receive(data);
-      else if (data.type === "shard_moved") socket.terminate();
+      else if (data.type === "shard_moved" || data.type === "please_reconnect") socket.terminate();
       else if (data.type === "auth_error" || data.type === "error") this.log("AgentsChat returned an error; check account and channel permissions");
     });
     socket.on("error", () => this.log("AgentsChat socket error"));
     socket.on("close", () => {
       if (!current()) return;
-      this.authenticated = false; this.rejectPending(); this.heartbeat?.stop(); this.log("AgentsChat disconnected; reconnecting (offline messages are not replayed)");
+      this.authenticated = false; this.rejectPending(); this.heartbeat?.stop(); this.log("AgentsChat disconnected; reconnecting with history reconciliation");
       this.retry = setTimeout(() => this.start(), this.delay); this.delay = Math.min(this.delay * 2, 30_000);
     });
   }
-  stop() { for (const timer of this.typing.values()) clearInterval(timer); this.typing.clear(); this.closed = true; this.authenticated = false; this.rejectPending(); clearTimeout(this.retry); this.heartbeat?.stop(); this.socket?.terminate(); }
+  stop() { for (const timer of this.typing.values()) clearInterval(timer); this.typing.clear(); this.closed = true; this.authenticated = false; this.rejectPending(); clearTimeout(this.retry); clearInterval(this.syncTimer); this.heartbeat?.stop(); this.socket?.terminate(); }
 }

package/connector/README.md

@@ -67,7 +67,7 @@ For the bundled Hermes adaptation skill and profile-specific setup commands, rea
 [`skills/onboarding.md` §4](../skills/onboarding.md). Upgrades from older connectors
 must follow the [0.34.0 migration notes](../CHANGELOG.md).
 
-**0.36.4 is unpublished:** use the [local build procedure](../skills/onboarding.md#local-build-before-runtime-configuration), not an assumed npm release.
+**0.36.5 is unpublished:** use the [local build procedure](../skills/onboarding.md#local-build-before-runtime-configuration), not an assumed npm release.
 Requires Node ≥22, Bun ≥1.0 for installing/building, and a configured Hermes
 v0.21.1 profile. In a reviewed `AgentsChatProtocol/mcp-plugin` checkout:
 
@@ -198,3 +198,33 @@ Every connector frame ends in `\n`, as required by the gateway's relay reader.
 Supported operations remain `send`, `typing`, and `get_chat_info`; media, edits,
 reactions, arbitrary multi-tenant hosting, and durable delivery acknowledgments
 are outside this connector's current scope.
+
+### Shared Hermes group context
+
+Set `group_sessions_per_user: false` in every connected Hermes profile's
+`config.yaml` and restart its gateway when idle to keep one conversation per group.
+Hermes otherwise defaults to a separate session per sender even though this
+connector preserves the group `chat_id` and replies to that group. This setting
+applies across that profile's group platforms; it does not merge existing histories.
+See [the relay guide](../../docs/hermes-relay.md#3-keep-one-conversation-per-group).
+
+
+## Named skills and group loop ticks
+
+A current bot-owned server `loop_tick` can wake that bot without an @mention.
+The connector verifies the complete tick envelope against `/api/loops/mine`
+using that bot's credentials before delivery; malformed, expired, deleted,
+wrong-bot and unverifiable ticks are rejected. Ordinary self echoes remain
+ignored. Replays are deduplicated per loop/tick and keep the original channel.
+Use `group_sessions_per_user: false` in Hermes so group participants and the bot's
+self tick share the same group session.
+
+`agentschat-team-lead` is a runtime-neutral skill included under the installed MCP
+package's `skills/` directory. Load it with Hermes `skill_view` after adding that
+stable directory to the active profile's native skills or `skills.external_dirs`,
+or with an existing AgentsChat MCP connection. Relay advertises loader guidance
+in private runtime context; it does not invent extra gateway tools or broadcast
+the skill body. Workspace/OKR/docs actions still require actual authenticated tools.
+Hermes cron's `[SILENT]` is not assumed to work for ordinary Relay messages.
+These routes have real local socket tests; a live Hermes model run remains a
+separate deployment check.

package/connector/backfill.ts

@@ -7,14 +7,9 @@
  * lexical `>` matches chronology (whole-second vs fractional).
  */
 import { normalizeTimestampForCursor } from "../src/timestamps.ts";
+import { serverLoopTick, type AgentsChatMessage } from "./normalize.ts";
 
-export type BackfillMsg = {
-  id?: string;
-  timestamp?: string;
-  sender_id?: string;
-  content?: string;
-  channel_id?: string;
-};
+export type BackfillMsg = AgentsChatMessage;
 
 export function planBackfill(
   after: string | undefined,
@@ -32,7 +27,8 @@ export function planBackfill(
   }
   const afterTs = normalizeTimestampForCursor(after, "after") || after;
   const replay = list.filter((m) => {
-    if (!m || m.sender_id === agentId || m.content === "__typing__") return false;
+    if (!m || m.content === "__typing__") return false;
+    if (m.sender_id === agentId && !serverLoopTick(m)) return false;
     const msgTs = normalizeTimestampForCursor(m.timestamp, "after");
     return typeof msgTs === "string" && msgTs > afterTs;
   });

package/connector/descriptor.ts

@@ -49,6 +49,7 @@ export function buildDescriptor(overrides: Partial<CapabilityDescriptor> = {}):
     len_unit: "chars",
     emoji: "🤖",
     pii_safe: false,
+    platform_hint: "AgentsChat named skills are reusable instructions. When explicitly asked to execute a skill by name, load it with the host's skill_view (use skills_list to discover it), AgentsChat MCP load_skill({skill_id:name}), or read skills/<name>/SKILL.md from the installed AgentsChat MCP package in this runtime. Report a missing loader or skill; do not pretend it ran. Keep skill text out of chat and keep replies in the originating chat.",
     supported_ops: [...SUPPORTED_OPS],
     ...overrides,
   };

package/connector/ingest.ts

@@ -1,14 +1,9 @@
 import { MessageDedup, messageDedupKey } from "../src/dedup.ts";
+import { serverLoopTick, type AgentsChatMessage } from "./normalize.ts";
 
 export type IngestIdentity = { botId: string; agentId: string };
 
-export type IngestFrame = {
-  id?: string;
-  channel_id?: string;
-  timestamp?: string;
-  content?: string;
-  sender_id?: string;
-};
+export type IngestFrame = AgentsChatMessage;
 
 /**
  * Ingest one live/backfill AgentsChat frame for a connector identity.
@@ -38,5 +33,10 @@ export function ingestAgentsChatFrame(
   if (scopedKey && deps.dedup.recordOrSkip(scopedKey)) return false;
   // Group fanout must filter self per TARGET, not per arrival socket: A can
   // mention B, and A's self echo may be the first copy of the shared message.
-  return (!frame.channel_id?.startsWith("dm-") || frame.sender_id !== id.agentId) && frame.content !== "__typing__";
+  if ((frame.meta as any)?.kind === "loop_tick") {
+    // Preserve candidates for authenticated live-record verification in server.ts.
+    // Group copies may arrive on another identity's subscription first.
+    return !!serverLoopTick(frame) && (!isDm || frame.sender_id === id.agentId);
+  }
+  return (!isDm || frame.sender_id !== id.agentId) && frame.content !== "__typing__";
 }

package/connector/normalize.ts

@@ -25,6 +25,9 @@ export interface AgentsChatMessage {
   timestamp?: string;
   reply_to?: string;
   mentions?: string[];
+  sender_type?: string;
+  content_type?: string;
+  meta?: unknown;
 }
 
 /** The wire MessageEvent the gateway rebuilds (only the fields it reads). */
@@ -82,3 +85,44 @@ export function toWireEvent(msg: AgentsChatMessage, platform = "agentschat"): Wi
     },
   };
 }
+
+
+export interface ServerLoopTick {
+  kind: "loop_tick";
+  loop_id: string;
+  prompt: string;
+  interval_ms: number;
+  next_tick_ms: number;
+  expires_at: null;
+}
+
+/** Shape check only. Delivery must additionally verify the bot's live server record. */
+export function serverLoopTick(msg: AgentsChatMessage): ServerLoopTick | null {
+  const meta = msg.meta as Partial<ServerLoopTick> | undefined;
+  if (!meta || meta.kind !== "loop_tick" ||
+    typeof msg.id !== "string" || !msg.id || typeof msg.channel_id !== "string" || !msg.channel_id ||
+    typeof msg.sender_id !== "string" || !msg.sender_id || msg.sender_type !== "agent" || msg.content_type !== "text" ||
+    typeof msg.timestamp !== "string" || !Number.isFinite(Date.parse(msg.timestamp)) ||
+    typeof meta.loop_id !== "string" || !/^loop_[a-zA-Z0-9_-]+$/.test(meta.loop_id) ||
+    typeof meta.prompt !== "string" || !meta.prompt.trim() || meta.prompt.length > 4000 ||
+    !Number.isSafeInteger(meta.interval_ms) || meta.interval_ms! < 60_000 || meta.interval_ms! > 86_400_000 ||
+    !Number.isSafeInteger(meta.next_tick_ms) || meta.next_tick_ms! <= meta.interval_ms! || meta.expires_at !== null ||
+    msg.content !== `(loop tick — ${meta.prompt})`) return null;
+  return meta as ServerLoopTick;
+}
+
+/** The caller-scoped authenticated /api/loops/mine response is the authority. */
+export function matchesLiveLoop(msg: AgentsChatMessage, agentId: string, response: unknown): boolean {
+  const tick = serverLoopTick(msg);
+  if (!tick || msg.sender_id !== agentId) return false;
+  const rows = (response as {loops?: any[]})?.loops;
+  if (!Array.isArray(rows)) return false;
+  const matches = rows.filter(row => row?.loop_id === tick.loop_id);
+  if (matches.length !== 1) return false;
+  const row = matches[0];
+  return row.status === "active" && row.channel_id === msg.channel_id && row.prompt === tick.prompt &&
+    row.interval_ms === tick.interval_ms && row.next_tick_ms === tick.next_tick_ms && row.expires_at === null &&
+    (row.mode === undefined || row.mode === "static") &&
+    Number.isSafeInteger(row.last_tick_at) && row.last_tick_at > 0 &&
+    row.last_tick_at + row.interval_ms === row.next_tick_ms;
+}

package/connector/run.ts

@@ -413,6 +413,14 @@ const connector = startConnector({
       const data = (await res.json()) as any;
       return { id: data?.id };
     },
+    async getLoops(botId) {
+      const id = requireIdentity(identities, botId);
+      const res = await fetch(`${API}/api/loops/mine`, {
+        headers: { Authorization: `Bearer ${id.token}` }, signal: AbortSignal.timeout(5000),
+      });
+      if (!res.ok) throw new PlatformHttpError(res.status);
+      return await res.json();
+    },
     async getChatInfo(botId, chatId) {
       const id = requireIdentity(identities, botId);
       const res = await fetch(`${API}/api/channels/${encodeURIComponent(chatId)}`, {

package/connector/server.ts

@@ -15,7 +15,7 @@ import { createServer, type Server as HttpServer, type IncomingMessage } from "n
 import { WebSocketServer, WebSocket } from "ws";
 import { verifyUpgradeToken, CLOSE_UNAUTHORIZED } from "./auth.ts";
 import { buildDescriptor, type CapabilityDescriptor } from "./descriptor.ts";
-import { toWireEvent, type AgentsChatMessage } from "./normalize.ts";
+import { toWireEvent, serverLoopTick, matchesLiveLoop, type AgentsChatMessage } from "./normalize.ts";
 import { MessageDedup } from "../src/dedup.ts";
 import { IdentityTable, routeInboundTargets, hermesSourceProfile, type Identity } from "./identities.ts";
 
@@ -24,6 +24,8 @@ export interface AgentsChatHooks {
   sendMessage(botId: string, chatId: string, content: string, replyTo?: string): Promise<{ id?: string }>;
   getChatInfo(botId: string, chatId: string): Promise<{ name?: string; type?: string }>;
   sendTyping?(botId: string, chatId: string): Promise<void>;
+  /** Read /api/loops/mine using this bot's own credentials; missing hook rejects self ticks. */
+  getLoops?(botId: string): Promise<unknown>;
   /**
    * Recent channel messages to attach as `context` when an @-mention arrives —
    * the "what happened since the last time I was addressed" window. `sinceTs` is
@@ -293,15 +295,21 @@ export function startConnector(config: ConnectorConfig): ConnectorHandle {
       //
       // DM: always forward. __botId (which identity's agentschat socket it arrived
       //   on) is the ownership signal; single-tenant falls back to its one identity.
-      // Group: forward ONLY when the body @mentions a fronted identity (content-
+      // Group: ordinary messages forward only when they @mention a fronted identity (content-
       //   based — the agentschat WS pushes every message of a joined channel
       //   unannotated, and arrival on a socket is NOT an addressing signal). The
       //   MCP path's gate is isDM || isMentioned; this reproduces it. Anything
       //   unaddressed is dropped — injecting joined-channel chatter into the
       //   agent's session would burn its tokens on messages not meant for it.
+      // Own server loop ticks bypass those gates only after live-record verification.
       const isDm = typeof msg.channel_id === "string" && msg.channel_id.startsWith("dm-");
       const owner = (msg as any).__botId ?? (msg as any).dm_owner;
-      const targets = isDm
+      const isTick = (msg.meta as any)?.kind === "loop_tick";
+      const tick = serverLoopTick(msg);
+      const loopTargets = tick ? table.all().filter(id => id.agentId === msg.sender_id) : [];
+      // A server loop addresses only its own identity, even if the prompt @mentions others.
+      // Never interpret a malformed/foreign loop as an ordinary mention or DM.
+      const targets = isTick ? (loopTargets.length === 1 ? loopTargets : []) : isDm
         ? [owner !== undefined ? (typeof owner === "string" ? table.forBot(owner) : null)
           : table.isSingle() ? table.all()[0] : null].filter((id): id is Identity => !!id)
         : routeInboundTargets(table, {
@@ -317,7 +325,14 @@ export function startConnector(config: ConnectorConfig): ConnectorHandle {
         const key = JSON.stringify([target.botId, msg.channel_id]);
         const previous = inboundQueues.get(key) ?? Promise.resolve();
         const job = previous.catch(() => {}).then(async () => {
-          if (msg.sender_id === target.agentId) return;
+          if (tick) {
+            let verified = false;
+            try { verified = !!hooks.getLoops && matchesLiveLoop(msg, target.agentId, await hooks.getLoops(target.botId)); } catch { /* fail closed */ }
+            if (!verified || table.forBot(target.botId) !== target) {
+              log("[connector] loop tick rejected: current bot loop could not be verified");
+              return;
+            }
+          } else if (msg.sender_id === target.agentId) return;
           const baseEvent = toWireEvent(msg, "agentschat");
           if (!baseEvent) return;
           if (![...sockets].some(c => c.ws.readyState === WebSocket.OPEN && c.fronted.has(target.botId))) return;
@@ -325,6 +340,8 @@ export function startConnector(config: ConnectorConfig): ConnectorHandle {
             ? JSON.stringify([msg.channel_id, msg.id, target.botId]) : null;
           // Reserve synchronously, before async context fetch, across mirrored sockets.
           if (deliveryKey && delivered.recordOrSkip(deliveryKey)) return;
+          // A mirrored/replayed tick must not run twice even if its envelope ID changes.
+          if (tick && delivered.recordOrSkip(JSON.stringify(["loop_tick", target.botId, msg.channel_id, tick.loop_id, tick.next_tick_ms]))) return;
           if (!isDm) {
             // Attach "what happened since you were last addressed" so the agent gets
             // the conversation BETWEEN its @-mentions without being injected into
@@ -355,6 +372,12 @@ export function startConnector(config: ConnectorConfig): ConnectorHandle {
             if (msg.timestamp && Number.isFinite(Date.parse(msg.timestamp)) &&
                 (!since || Date.parse(msg.timestamp) > Date.parse(since))) lastAddressed.set(key, msg.timestamp);
           }
+          if (tick) {
+            baseEvent.context = [...(baseEvent.context ?? []), {
+              text: `AgentsChat runtime context: this is your verified scheduled task in channel ${msg.channel_id}, running as ${target.agentId}. Execute it once in this same conversation; replies stay here. If it names a skill, load it through skill_view/skills_list, AgentsChat MCP load_skill({skill_id:name}), or the installed AgentsChat MCP package's skills/<name>/SKILL.md in this runtime. Missing skill or tools is a failure to report, not successful execution. Do not repeat the skill text or create another loop.`,
+              source: {user_name: "AgentsChat runtime"},
+            }];
+          }
           const deliverTo = [...sockets].filter((c) => c.ws.readyState === WebSocket.OPEN && c.fronted.has(target.botId)).slice(0, 1);
           if (deliverTo.length === 0) {
             log(`[connector] inbound dropped for botId=${target.botId}: no agentschat-fronted gateway socket`);

package/dist/codex-bots.js

@@ -904,6 +904,13 @@ function parse(toml, { maxDepth = 1000, integersAsBigInt } = {}) {
  */
 
 // codex/config.ts
+function reasoningEffort(value) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || !value.trim())
+    throw new Error("effort must be a nonempty model-supported reasoning effort name");
+  return value.trim();
+}
 function permissionMode(value) {
   if (value === undefined)
     return "full-access";
@@ -931,7 +938,7 @@ function resolveConfig(opts, env = process.env, home = homedir()) {
   const project = opts.settings ?? (existsSync(configFile) ? readJson(configFile) : {});
   if (!project || typeof project !== "object" || Array.isArray(project))
     throw new Error("Invalid project config");
-  const allowed = new Set(["profile", "agent_id", "channels", "senders", "api_url", "ws_url", "permissions"]);
+  const allowed = new Set(["profile", "agent_id", "channels", "senders", "api_url", "ws_url", "permissions", "effort"]);
   if (Object.keys(project).some((k) => !allowed.has(k)))
     throw new Error("Unknown project config field (credentials belong in a private profile)");
   for (const k of ["profile", "agent_id", "api_url", "ws_url"])
@@ -1001,6 +1008,7 @@ function resolveConfig(opts, env = process.env, home = homedir()) {
     profileFile,
     source,
     permissions: permissionMode(project.permissions),
+    effort: reasoningEffort(project.effort),
     agentId: profile.agent_id,
     token: profile.token,
     apiUrl: canonicalApi,
@@ -1040,7 +1048,7 @@ function loadBots(file = defaultRegistry(), home = homedir2()) {
   const names = new Set, identities = new Set;
   const bots = [];
   for (const bot of doc.bots) {
-    fields(bot, ["name", "profile", "workdir", "enabled", "agent_id", "channels", "senders", "api_url", "ws_url", "permissions"]);
+    fields(bot, ["name", "profile", "workdir", "enabled", "agent_id", "channels", "senders", "api_url", "ws_url", "permissions", "effort"]);
     if (!text(bot.name) || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(bot.name) || names.has(bot.name))
       throw new Error("Bot names must be unique simple labels");
     names.add(bot.name);
@@ -1056,7 +1064,7 @@ function loadBots(file = defaultRegistry(), home = homedir2()) {
       mkdirSync(defaultDir, { recursive: true, mode: 448 });
     const cwd = realpathSync2(bot.workdir ? path(bot.workdir) : defaultDir);
     const settings = {};
-    for (const k of ["agent_id", "channels", "senders", "api_url", "ws_url", "permissions"])
+    for (const k of ["agent_id", "channels", "senders", "api_url", "ws_url", "permissions", "effort"])
       if (bot[k] !== undefined)
         settings[k] = bot[k];
     const config = resolveConfig({ cwd, profile: bot.profile, settings, codexBin: doc.codex_bin }, {}, home);
@@ -1122,7 +1130,7 @@ function removeDeadLock(file) {
   }
 }
 function save() {
-  writeFileSync(statusFile + ".tmp", JSON.stringify({ pid: process.pid, updated_at: new Date().toISOString(), bots: [...workers.values()].map((w) => ({ name: w.config.name, agent_id: w.config.agentId, workdir: w.config.cwd, pid: w.child?.pid, status: w.status })) }, null, 2), { mode: 384 });
+  writeFileSync(statusFile + ".tmp", JSON.stringify({ pid: process.pid, updated_at: new Date().toISOString(), bots: [...workers.values()].map((w) => ({ name: w.config.name, agent_id: w.config.agentId, workdir: w.config.cwd, effort: w.config.effort, pid: w.child?.pid, status: w.status })) }, null, 2), { mode: 384 });
   renameSync(statusFile + ".tmp", statusFile);
 }
 async function stop(w) {