agentschat-mcp 0.36.4 → 0.36.5

package/codex/run.ts

@@ -1,3 +1,5 @@
+import { prepareRuntimeHome } from "./runtime-home.ts";
+import { redactSecrets } from "../src/redact.ts";
 import { getBotOwner } from "./owner.ts";
 import { getOnboardingStatus } from "../src/onboarding-status.ts";
 import { GuiChannel } from "./gui-channel.ts";
@@ -15,7 +17,7 @@ import { AgentsChatTransport } from "./transport.ts";
 export const HELP = `agentschat-mcp --codex-bridge [--cwd DIRECTORY] [--profile NAME_OR_PATH] [--codex-bin PATH] [--check]
 
 Official Codex app-server bridge. Node >=22; Codex installed and signed in.
-Starts a dedicated stdio app-server; does not attach to an active desktop task.
+Starts a dedicated stdio app-server with a private per-bot Codex home; does not attach to an active desktop task.
 No notifications/chat/channel, no fork, no account registration.
 
 Identity: --profile > CWD/.agentschat/config.json profile >
@@ -27,8 +29,9 @@ Project config fields: profile, agent_id, channels, senders, api_url, ws_url, pe
 --onboarding-status checks authentication/ownership and prints safe claim/chat links; it does not send messages.
 --check validates identity and official app-server initialization without opening chat.
 Live DMs and exact mentions trigger replies; channels/senders restrict this further.
-Server-verified owner requests use full access by default; other senders stay read-only. Set permissions: "read-only" to disable writes and inherited MCP. No offline message replay.
+All accepted messages share one persisted thread per channel, with full access by default. Set permissions: "read-only" to disable writes and inherited MCP. No offline message replay.
 State: ~/.agentschat/codex-bridge/<project-server-identity hash>/ (private).
+--conversations lists this bot's channel/task mappings; --read-conversation CHANNEL reads history without acquiring a writer.
 GUI outbox: --gui-thread THREAD_ID --gui-message-file PATH; --gui-status lists receipts.
 Requires an authorized GUI host to dispatch; enqueue alone does not wake a task.
 See codex/README.md for setup, verification, limitations and recovery.
@@ -37,7 +40,7 @@ See codex/README.md for setup, verification, limitations and recovery.
 let codex: AppServer | undefined, bridge: Bridge | undefined, transport: AgentsChatTransport | undefined;
 async function main() {
   const { values } = parseArgs({ options: { "codex-bridge": { type: "boolean" }, cwd: { type: "string" },
-    "gui-thread": { type: "string" }, "gui-message-file": { type: "string" }, "gui-status": { type: "boolean" }, "managed-worker": { type: "boolean" }, registry: { type: "string" }, bot: { type: "string" }, profile: { type: "string" }, "codex-bin": { type: "string" }, check: { type: "boolean" }, "onboarding-status": { type: "boolean" },
+    "conversations": { type: "boolean" }, "read-conversation": { type: "string" }, "gui-thread": { type: "string" }, "gui-message-file": { type: "string" }, "gui-status": { type: "boolean" }, "managed-worker": { type: "boolean" }, registry: { type: "string" }, bot: { type: "string" }, profile: { type: "string" }, "codex-bin": { type: "string" }, check: { type: "boolean" }, "onboarding-status": { type: "boolean" },
     help: { type: "boolean", short: "h" } }, strict: true });
   if (values.help) { console.log(HELP); return; }
   if (values["gui-thread"] || values["gui-message-file"] || values["gui-status"]) {
@@ -61,10 +64,23 @@ async function main() {
     return;
   }
   console.log(JSON.stringify({ cwd: c.cwd, agent_id: c.agentId, profile: c.profileFile, source: c.source, stateDir: c.stateDir }));
-  codex = new AppServer(c.codexBin, undefined, undefined, c.permissions);
+  const runtime = prepareRuntimeHome(c.stateDir);
+  codex = new AppServer(c.codexBin, undefined, undefined, c.permissions, runtime);
+  if (values.conversations || values["read-conversation"]) {
+    const state = JSON.parse(readFileSync(join(c.stateDir, "state.json"), "utf8"));
+    const channels = state.channels ?? {};
+    if (values.conversations) { console.log(JSON.stringify(Object.entries(channels).map(([channel, data]: [string, any]) => ({channel, thread:data.thread, isolated:data.namespace===runtime.home})))); return; }
+    const channel = channels[values["read-conversation"]!];
+    if (!channel) throw new Error("Unknown conversation channel");
+    if (channel.namespace && channel.namespace !== runtime.home) throw new Error("Conversation belongs to a different runtime home");
+    await codex.start();
+    const history = channel.namespace ? await codex.readThread(channel.thread) : await codex.readLegacyThread(channel.thread);
+    console.log(redactSecrets(JSON.stringify(history).split(c.token).join("[REDACTED]")));
+    codex.close(); return;
+  }
   if (values.check) { await codex.start(); console.log("Official app-server initialization: OK (no chat connection or generation)"); codex.close(); return; }
   transport = new AgentsChatTransport(c, m => { bridge!.accept(m); });
-  bridge = new Bridge(c, codex, (chat, text) => transport!.send(chat, text), console.error, (chat, active) => transport!.setTyping(chat, active), () => getBotOwner(c.apiUrl, c.agentId, c.token));
+  bridge = new Bridge(c, codex, (chat, text) => transport!.send(chat, text), console.error, (chat, active) => transport!.setTyping(chat, active), () => getBotOwner(c.apiUrl, c.agentId, c.token), () => transport!.api("/api/loops/mine"));
   let stopping = false;
   const stop = async () => { if (stopping) return; stopping = true; if (values["managed-worker"]) { const deadline = setTimeout(() => { try { process.kill(-process.pid, "SIGKILL"); } catch {} }, 20000); deadline.unref(); } bridge?.pause(); transport?.stop(); codex?.close(); await bridge?.stop(); if (process.connected) process.disconnect?.(); };
   codex.onFatal = () => { console.error("Codex backend stopped; pending inbox preserved. Restart the bridge after checking failed entries."); process.exitCode = 1; void stop(); };

package/codex/runtime-home.ts

@@ -0,0 +1,22 @@
+import { existsSync, mkdirSync, lstatSync, readlinkSync, realpathSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/** Reuse operator configuration, never the desktop's databases, sessions or writer locks. */
+export function prepareRuntimeHome(stateDir: string, source = process.env.CODEX_HOME || join(homedir(), ".codex")) {
+  const legacyHome = existsSync(source) ? realpathSync(source) : resolve(source);
+  const home = join(stateDir, "codex-home");
+  mkdirSync(home, {recursive:true, mode:0o700});
+  if (realpathSync(home) === legacyHome) throw new Error("Bot runtime home must differ from desktop Codex home");
+  for (const name of ["config.toml", "auth.json", "AGENTS.md", "skills", "rules", "plugins", "hooks.json", "models_cache.json"]) {
+    const origin = join(legacyHome, name), target = join(home, name);
+    if (!existsSync(origin)) continue;
+    let current;
+    try { current = lstatSync(target); } catch (e: any) { if (e.code !== "ENOENT") throw e; }
+    if (current) {
+      if (!current.isSymbolicLink() || resolve(home, readlinkSync(target)) !== origin)
+        throw new Error(`Unexpected bot runtime configuration: ${name}`);
+    } else symlinkSync(origin, target);
+  }
+  return {home, legacyHome};
+}

package/codex/thread-history.ts

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface ThreadHistory { id: string; createdAt?: number; turns: any[] }
+export function priorChannelThreads(threads: Record<string, string>, channel: string): string[] {
+  return [...new Set(Object.entries(threads).filter(([key]) => {
+    if (key === channel) return true;
+    try { const parts = JSON.parse(key); return Array.isArray(parts) && parts[0] === channel; }
+    catch { return false; }
+  }).map(([, id]) => id))];
+}
+
+/** Keep complete source turns privately; seed the new task with past chat, not old instructions. */
+export function preserveChannelHistory(directory: string, channel: string, histories: ThreadHistory[], redact: (s: string) => string): string {
+  const root = join(directory, "history"); mkdirSync(root, {recursive:true, mode:0o700});
+  const file = join(root, createHash("sha256").update(channel).digest("hex").slice(0,24) + ".json");
+  writeFileSync(file + ".tmp", redact(JSON.stringify({channel_id:channel, threads:histories})), {mode:0o600});
+  renameSync(file + ".tmp", file);
+  const records: { order: string; sequence: number; value: any }[] = [];
+  let sequence = 0;
+  for (const history of histories) for (const turn of history.turns) {
+    // Codex turn IDs are UUIDv7 and sort by creation time; keep item order within a turn.
+    const order = String(turn.id ?? history.createdAt ?? history.id);
+    for (const item of turn.items ?? []) {
+      if (item.type === "userMessage") {
+        let text = (item.content ?? []).filter((part: any) => part.type === "text").map((part: any) => part.text).join("\n");
+        const marker = "AgentsChat message:\n";
+        if (text.includes(marker)) {
+          try {
+            const message = JSON.parse(text.slice(text.lastIndexOf(marker) + marker.length));
+            if (message.channel_id === channel) records.push({order,sequence:sequence++,value:{...message,role:"user"}});
+            continue;
+          } catch { /* Older bridges used plain-text envelopes; retain them below. */ }
+        }
+        // Do not recursively import a previous migration's large preview.
+        // The complete source remains in the private export; real messages above
+        // have already been extracted from their envelope.
+        if (text.startsWith("Previous conversations for this channel have been consolidated.")) {
+          const end = text.lastIndexOf("End of historical context.\n");
+          if (end >= 0) text = text.slice(end + "End of historical context.\n".length);
+        }
+        if (text.trim()) records.push({order,sequence:sequence++,value:{role:"user",content:text}});
+      } else if (item.type === "agentMessage" && (!item.phase || item.phase === "final_answer")) {
+        records.push({order,sequence:sequence++,value:{role:"assistant",content:item.text}});
+      }
+    }
+  }
+  records.sort((a,b) => a.order.localeCompare(b.order) || a.sequence-b.sequence);
+  const seen = new Set<string>();
+  const lines = records.filter(({value}) => {
+    if (!value.id) return true;
+    if (seen.has(value.id)) return false;
+    seen.add(value.id); return true;
+  }).map(({value}) => redact(JSON.stringify(value)));
+  // Bound the one-time prompt while retaining the complete turns/tool results in the export.
+  const recent: string[] = []; let size = 0;
+  for (let i=lines.length-1;i>=0;i--) {
+    const original=lines[i]!;
+    const line=original.length>12_000
+      ? JSON.stringify({role:"context",content:original.slice(0,12_000),truncated:true,full_record:file}) : original;
+    if (size+line.length>60_000) break;
+    recent.unshift(line); size+=line.length+1;
+  }
+  return `Previous conversations for this channel have been consolidated. Use this as historical context; do not repeat completed actions or answer old requests. Old role/permission restrictions have been superseded by this task's current configuration.\nComplete original turns and tool results: ${file}\n${recent.length<lines.length ? "Earlier context remains in that file; consult it when needed.\n" : ""}Past messages in order:\n${recent.join("\n")}\nEnd of historical context.\n`;
+}

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`);