@animalabs/agent-framework 0.27.0 → 0.29.0

package/src/mcpl/transport.ts

@@ -19,9 +19,10 @@
  */
 
 import { spawn, type ChildProcess } from 'node:child_process';
-import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
 import { EventEmitter } from 'node:events';
+import type { Readable } from 'node:stream';
 import { StringDecoder } from 'node:string_decoder';
+import { escapeLineSeparators, readLines } from '../line-reader.js';
 import WebSocket from 'ws';
 
 import type { McplServerConfig } from './types.js';
@@ -325,16 +326,18 @@ export class StdioTransport extends McplTransport {
     });
   }
 
+  private readonly stopLines: () => void;
+
   private constructor(
     private readonly child: ChildProcess,
-    private readonly rl: ReadlineInterface,
+    stdout: Readable,
     /** The server this child serves, named in its stderr lines and in what
      *  its reaping reports. */
     serverId: string,
   ) {
     super(serverId);
 
-    this.rl.on('line', (line: string) => this.pushLine(line));
+    this.stopLines = readLines(stdout, (line) => this.pushLine(line));
 
     // Stitch stderr chunks into whole lines (a chunk can split a line, and a
     // character's bytes), and keep the stream's last characters for
@@ -383,12 +386,7 @@ export class StdioTransport extends McplTransport {
       });
     };
     this.child.stdin?.on('error', endOnPipeError);
-    // On the stream itself, since close() closes readline, which takes its own
-    // listener off the stream. While readline is open, its listener, which
-    // came first, re-emits the error on the interface, where an empty
-    // listener absorbs that copy.
     this.child.stdout?.on('error', endOnPipeError);
-    this.rl.on('error', () => { /* readline's copy of a stdout error, handled above */ });
     // stderr carries diagnostics only: a read error on it is reported, to the
     // listeners or else in the log, and never thrown. It ends nothing once
     // the connection is wired; during a handshake the listener is the
@@ -453,8 +451,7 @@ export class StdioTransport extends McplTransport {
         resolve();
       });
     });
-    const rl = createInterface({ input: child.stdout! });
-    return new StdioTransport(child, rl, config.id);
+    return new StdioTransport(child, child.stdout!, config.id);
   }
 
   writeLine(json: string): void {
@@ -462,7 +459,7 @@ export class StdioTransport extends McplTransport {
     // transport is ending it.
     if (this.pipeError) return;
     // stdin may be gone if the child died between the closed-check and here.
-    this.child.stdin?.write(json + '\n');
+    this.child.stdin?.write(escapeLineSeparators(json) + '\n');
   }
 
   private closing: Promise<void> | null = null;
@@ -492,7 +489,7 @@ export class StdioTransport extends McplTransport {
 
   private async reap(): Promise<void> {
     this.markClosed({ reason: 'closed by host' });
-    this.rl.close();
+    this.stopLines();
     await this.terminate();
   }
 
@@ -696,7 +693,7 @@ export class WebSocketTransport extends McplTransport {
 
   writeLine(json: string): void {
     if (this.ws.readyState === WebSocket.OPEN) {
-      this.ws.send(json);
+      this.ws.send(escapeLineSeparators(json));
     }
   }
 
@@ -830,7 +827,7 @@ const SERVER_CONFIG_BOOLEANS: Record<BooleanSetting, string> = {
   inheritEnv: 'true passes the server the host\'s whole environment, and false or leaving it out passes only the allowlisted and LC_* host variables',
   reconnect: 'true retries in the background when the server can\'t be reached or its connection drops, and false or leaving it out doesn\'t',
   allowHostCommands: 'true lets the server run the host\'s admin commands, such as undo, hide, unstick and quiesce, and false or leaving it out refuses them',
-  toolHints: 'true advertises MCPL tool hints (RFC-014), so the server\'s dynamic tools are announced in the conversation and called through toolsets--act, and false or leaving it out lists every tool as before',
+  toolHints: 'true advertises MCPL tool hints (RFC-014) to an MCPL server, so its dynamic tools are announced in the conversation and called through toolsets--act; leaving it out does the same wherever the name toolsets is free; false lists every tool as before and advertises none',
 };
 
 /**
@@ -849,6 +846,13 @@ export function assertServerConfigBooleans(config: McplServerConfig): void {
     if (setting === 'inheritEnv' && dialsNetwork(config)) continue;
     assertBooleanSetting(`MCPL server "${config.id}" ${setting}`, config[setting], whatTrueDoes);
   }
+  // Not a boolean, but read the same way: a value that isn't one of the
+  // three would otherwise be taken for the default.
+  const presentation = (config as { presentation?: unknown }).presentation;
+  if (presentation !== undefined && presentation !== null && presentation !== 'full' && presentation !== 'tab' && presentation !== 'closed-tab') {
+    const kind = typeof presentation === 'string' ? 'another string' : Array.isArray(presentation) ? 'a list' : typeof presentation;
+    throw new Error(`MCPL server "${config.id}" presentation must be "full", "tab" or "closed-tab" (or left out for full), not ${kind}`);
+  }
 }
 
 /**

package/src/mcpl/types.ts

@@ -193,8 +193,8 @@ export interface McplHostCapabilities {
   modelInfo?: boolean;
   featureSets?: boolean;
   channels?: boolean | McplChannelCapabilities;
-  /** RFC-014 §6.3: this host presents tool hints. Sent only to a server
-   *  whose config sets `toolHints: true`. */
+  /** RFC-014 §6.3: this host presents tool hints. Sent to every server
+   *  with hints (McplServerConfig.toolHints: on unless false). */
   toolHints?: boolean;
 }
 
@@ -384,7 +384,9 @@ export interface McplServerConfig {
    *
    * `disabledCapabilities` takes precedence on conflict. `version` and
    * `featureSets` are not maskable here — feature sets have their own
-   * enable/disable knobs above.
+   * enable/disable knobs above — and neither are RFC-014's `toolHints`,
+   * `toolsets` and `surface`, which a server's own `toolHints` config turns
+   * off.
    */
   enabledCapabilities?: string[];
 
@@ -506,18 +508,35 @@ export interface McplServerConfig {
   toolLifecycle?: import('./tool-lifecycle.js').ToolLifecycleConfig;
 
   /**
-   * MCPL RFC-014 (tool presence, toolsets and surfaces). Default false: the
-   * host advertises nothing and treats every tool as static, byte for byte as
-   * before. When true, the host advertises `experimental.mcpl.toolHints`, and
-   * honours hints only from a server that advertised `toolHints` too. Then
-   * the server's static tools stay in the tool list as before, and its
-   * dynamic tools (toolset tools, `mcpl/presence: "dynamic"`) leave it: they
-   * are announced in the conversation as they become visible and invisible,
-   * and called through the `toolsets` module's `toolsets--act`, opened with
-   * `toolsets--open`, inspected with `toolsets--look` and closed with
-   * `toolsets--close`. Only `true` turns it on, and null counts as not set.
+   * MCPL RFC-014 (tool presence, toolsets and surfaces). On unless set to
+   * `false`: the host advertises `experimental.mcpl.toolHints` and honours
+   * hints (through the `toolsets` meta-tools) only from a server that
+   * advertised `toolHints` too. Such a server's static tools stay in the tool
+   * list as before, and its dynamic tools (toolset tools, `mcpl/presence:
+   * "dynamic"`) leave it: they are announced in the conversation as they
+   * become visible and invisible, and called through `toolsets--act`, opened
+   * with `toolsets--open`, inspected with `toolsets--look` and closed with
+   * `toolsets--close`. A server that doesn't advertise `toolHints` lists every
+   * tool as before. `false` advertises nothing and treats every tool as
+   * static. Omitted and null are on unless a module given to `create()`
+   * holds the name `toolsets` (or a restart is moving a server to that
+   * prefix, which is refused); `true` with such a module is refused.
    */
   toolHints?: boolean;
+
+  /**
+   * How this server is presented to agents at first (the host's own
+   * toolsets, src/host-presentation.ts): `'full'` (the default) puts its
+   * tools in the tool list, as before; `'tab'` keeps it connected, its events
+   * still arriving, with none of its tools in the tool list until an agent
+   * opens its tab (`toolsets--open {server}`) and calls them through
+   * `toolsets--act`; `'closed-tab'` leaves it disconnected until an agent
+   * opens it. Each agent can switch it later (`toolsets--close {server}`,
+   * with `disconnect: true` for a closed tab; `toolsets--open {server,
+   * full: true}` back into the tool list), and that choice is kept across
+   * restarts beside the store, over this default.
+   */
+  presentation?: 'full' | 'tab' | 'closed-tab';
 }
 
 // ============================================================================

package/src/module-registry.ts

@@ -28,7 +28,7 @@ import { heldWriteId } from './held-writes.js';
 import type { Agent } from './agent.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, waitForShutdown } from './shutdown.js';
 import { logValue } from './mcpl/log-value.js';
-import { toolArgsProblems } from './tool-args.js';
+import { asCalled, markedInputRefusal, toolArgsProblems } from './tool-args.js';
 
 /** How the registry queues a module's event: its push names the module. A
  * `ProcessQueue` serves too, ignoring the name. */
@@ -282,8 +282,8 @@ export class ModuleRegistry {
   /**
    * All utilities from all modules, namespaced exactly like tools
    * (`module--name`). See Module.getUtilities — these are deliberately kept
-   * out of the model-facing tool list and surfaced through the framework's
-   * `utils` meta-tool; dispatch goes through the same handleToolCall.
+   * out of the model-facing tool list and presented in the host's built-in
+   * toolset; dispatch goes through the same handleToolCall.
    */
   getAllUtilities(): ToolDefinition[] {
     const utilities: ToolDefinition[] = [];
@@ -300,8 +300,8 @@ export class ModuleRegistry {
 
   /**
    * A module tool's call for a path that stores or sends its result: the
-   * model's dispatch, a script's inner call, the `utils` meta-tool for a
-   * model. The result is checked and read once, in its JSON form
+   * model's dispatch (a `toolsets--act` call of it included), a script's
+   * inner call. The result is checked and read once, in its JSON form
    * ({@link storableToolResult}).
    */
   async storableToolCall(call: ToolCall, options: { definition?: ToolDefinition } = {}): Promise<ToolResult> {
@@ -317,11 +317,16 @@ export class ModuleRegistry {
    * A call whose input isn't an object, or lacks a key the tool's schema
    * requires, is answered before the module runs, with an error result that
    * opens "Nothing was done:" and names what to send (toolArgsProblems).
-   * A caller that has already resolved the tool's definition, as the `utils`
-   * tool has a utility's, passes it as `definition`, and it's checked against
-   * that one.
+   * So is a call membrane marked `unparseableInput`, unless its text is JSON
+   * `null`, which reaches the module as a call with no arguments
+   * (markedInputRefusal).
+   * A caller that has already resolved the tool's definition passes it as
+   * `definition`, and it's checked against that one.
    */
-  async handleToolCall(call: ToolCall, options: { definition?: ToolDefinition } = {}): Promise<ToolResult> {
+  async handleToolCall(given: ToolCall, options: { definition?: ToolDefinition } = {}): Promise<ToolResult> {
+    const marked = markedInputRefusal(given);
+    if (marked !== undefined) return { success: false, error: marked, isError: true };
+    const call = asCalled(given);
     // Parse module--tool name
     const sepIndex = call.name.indexOf('--');
     if (sepIndex === -1) {

package/src/modules/api/index.ts

@@ -6,6 +6,7 @@
  */
 
 import { unknownToolMessage } from '../unknown-tool.js';
+import { outsideSenderName } from '../sender-name.js';
 import type {
   Module,
   ModuleContext,
@@ -62,12 +63,13 @@ export class ApiModule implements Module {
   }
 
   private handleMessage(event: ApiMessageEvent): EventResponse {
+    const carried = event.metadata?.author;
     const response: EventResponse = {
       addMessages: [
         {
-          participant: event.participant,
+          participant: outsideSenderName(event.participant, 'API'),
           content: [{ type: 'text', text: event.content }],
-          metadata: event.metadata,
+          metadata: { ...event.metadata, author: typeof carried === 'object' && carried !== null ? carried : { name: event.participant } },
         },
       ],
     };

package/src/modules/discord/index.ts

@@ -7,6 +7,8 @@
  * - Tools for explicit Discord operations (send, DM, react, etc.)
  */
 
+import { NOTICE_TAG } from '../../notice-tags.js';
+import { markedText, suppliedValue } from '../../supplied-text.js';
 import type { ContentBlock } from '@animalabs/membrane';
 import { continuesBody, type StoredMessage } from '@animalabs/context-manager';
 import type {
@@ -47,6 +49,7 @@ import type {
 import { formatZonedDateTime, resolveTimeZone } from '../../timezone.js';
 import { logValue } from '../../mcpl/log-value.js';
 import { unknownToolMessage } from '../unknown-tool.js';
+import { outsideSenderName } from '../sender-name.js';
 import { DiscordRefusal } from './refusal.js';
 
 // Re-export event types for consumers who want to handle them
@@ -119,10 +122,11 @@ const NOT_RUNNING = "Speech handling wasn't changed: the Discord module hasn't s
 /** What the agent reads for a text attachment whose contents couldn't be
  *  fetched: by an error, or by an answer that wasn't OK. */
 function attachmentNotFetched(filename: string): { type: 'text'; text: string } {
-  return {
-    type: 'text',
-    text: `[Attachment: ${filename} couldn't be fetched, so its text isn't in your context. If you need it, ask the sender in the channel to paste it.]`,
-  };
+  return { type: 'text', text: notFetchedText(suppliedValue(filename)) };
+}
+
+function notFetchedText(filename: string): string {
+  return `[${NOTICE_TAG.attachment}: ${filename} couldn't be fetched, so its text isn't in your context. If you need it, ask the sender in the channel to paste it.]`;
 }
 
 /**
@@ -165,7 +169,7 @@ function seconds(n: number): string {
 
 /** What a stored message reads when it has no text of its own and nothing the
  *  host added, so the agent still sees that a message was there. */
-const EMPTY_MESSAGE = '[Empty message]';
+const EMPTY_MESSAGE = `[${NOTICE_TAG.emptyMessage}]`;
 
 /**
  * Metadata on a stored Discord message whose first block is its own text,
@@ -184,6 +188,14 @@ function ownText(content: string): string {
   return content.trim() ? content : '';
 }
 
+function storedOwnText(content: string): string {
+  return markedText(ownText(content));
+}
+
+function holdsOwnText(text: string, own: string): boolean {
+  return text === own || text === markedText(own);
+}
+
 const isEmptyMarker = (block: ContentBlock): boolean => block.type === 'text' && block.text === EMPTY_MESSAGE;
 const isBlankText = (block: ContentBlock): boolean => block.type === 'text' && !block.text.trim();
 
@@ -198,7 +210,7 @@ function textFirst(text: string, after: ContentBlock[] = []): ContentBlock[] {
 /** A text-first row's content with `text` as the message's own text, in
  *  place of its first block, keeping what the host added after it. */
 function withOwnText(content: ContentBlock[], text: string): ContentBlock[] {
-  return textFirst(ownText(text), content.slice(1).filter((block) => !isEmptyMarker(block)));
+  return textFirst(storedOwnText(text), content.slice(1).filter((block) => !isEmptyMarker(block)));
 }
 
 /**
@@ -221,11 +233,11 @@ function contentForText(stored: StoredMessage, discordText: string): ContentBloc
   const text = ownText(discordText);
   const [first, ...rest] = stored.content;
   if (stored.metadata?.[TEXT_FIRST] === true) {
-    if (first?.type === 'text' && first.text === text) return null;
+    if (first?.type === 'text' && holdsOwnText(first.text, text)) return null;
     return withOwnText(stored.content, text);
   }
-  if (!text || (first?.type === 'text' && first.text === discordText)) return null;
-  return [{ type: 'text', text: discordText }, ...(first?.type === 'text' ? rest : stored.content).filter((block) => !isEmptyMarker(block))];
+  if (!text || (first?.type === 'text' && holdsOwnText(first.text, discordText))) return null;
+  return [{ type: 'text', text: markedText(discordText) }, ...(first?.type === 'text' ? rest : stored.content).filter((block) => !isEmptyMarker(block))];
 }
 
 /**
@@ -255,7 +267,7 @@ function needsRebuild(stored: StoredMessage, message: HistoryMessage): boolean {
   const [first, ...rest] = stored.content;
   if (!own && first?.type === 'text' && !isBlankText(first) && !isEmptyMarker(first)) return true;
   const expected = (own ? 1 : 0) + attachments;
-  const counted = own && first?.type === 'text' && first.text === own ? 1 + held(rest) : held(stored.content);
+  const counted = own && first?.type === 'text' && holdsOwnText(first.text, own) ? 1 + held(rest) : held(stored.content);
   return counted !== expected || (expected === 0 && !stored.content.some(isEmptyMarker));
 }
 
@@ -268,14 +280,14 @@ function needsRebuild(stored: StoredMessage, message: HistoryMessage): boolean {
 function holdsOtherText(stored: StoredMessage, message: HistoryMessage): boolean {
   const own = ownText(message.content);
   const [first, ...rest] = stored.content;
-  const others = own && first?.type === 'text' && first.text === own ? rest : stored.content;
+  const others = own && first?.type === 'text' && holdsOwnText(first.text, own) ? rest : stored.content;
   return others.some((block) => block.type === 'text' && !isBlankText(block) && !isEmptyMarker(block));
 }
 
 /** Whether a message's conversion holds, after the message's own text, the
  *  note for an attachment of its whose text wasn't fetched. */
 function holdsNotFetched(content: ContentBlock[], message: HistoryMessage): boolean {
-  const notes = new Set((message.attachments ?? []).map((attachment) => attachmentNotFetched(attachment.filename).text));
+  const notes = new Set((message.attachments ?? []).flatMap((attachment) => [attachmentNotFetched(attachment.filename).text, notFetchedText(attachment.filename)]));
   return content.slice(1).some((block) => block.type === 'text' && notes.has(block.text));
 }
 
@@ -302,9 +314,10 @@ function forGoneAttachment(block: ContentBlock, attachments: readonly DiscordAtt
   if (block.type !== 'text') return false;
   const { text } = block;
   const opening = text.startsWith('\n--- File: ') ? (filename: string) => `\n--- File: ${filename} ---\n`
-    : text.startsWith('[Attachment: ') ? (filename: string) => `[Attachment: ${filename} `
+    : text.startsWith(`[${NOTICE_TAG.attachment}: `) ? (filename: string) => `[${NOTICE_TAG.attachment}: ${filename} `
     : null;
-  return opening !== null && !attachments.some((attachment) => text.startsWith(opening(attachment.filename)));
+  return opening !== null && !attachments.some((attachment) =>
+    text.startsWith(opening(suppliedValue(attachment.filename))) || text.startsWith(opening(attachment.filename)));
 }
 
 /**
@@ -818,7 +831,7 @@ export class DiscordModule implements Module {
 
       // Built from the message and its attachments, or from its text alone
       // when an event carries no blocks; text first, as TEXT_FIRST marks.
-      const contentBlocks = msg.contentBlocks ?? textFirst(ownText(msg.content));
+      const contentBlocks = msg.contentBlocks ?? textFirst(storedOwnText(msg.content));
       this.noteLive(msg.discordMessageId);
 
       // A message a history sync wrote first, stored or held, keeps that row:
@@ -833,9 +846,10 @@ export class DiscordModule implements Module {
         ...(stored ? {} : {
           addMessages: [
             {
-              participant: msg.authorName,
+              participant: outsideSenderName(msg.authorName, 'Discord'),
               content: contentBlocks,
               metadata: {
+                author: { id: msg.authorId, name: msg.authorName },
                 external: { source: 'discord', id: msg.discordMessageId },
                 channelId: msg.channelId,
                 timestamp: msg.timestamp,
@@ -1144,14 +1158,12 @@ export class DiscordModule implements Module {
           // For bot's own messages (from previous sessions), use the agent name
           // This ensures continuity of conversation history
           const isBotMessage = discordMsg.authorId === this.state.botUserId;
-          const agentName = ctx.getAgents()[0]?.name;
-          const participantName = isBotMessage
-            ? (agentName ?? discordMsg.authorName)
-            : discordMsg.authorName;
+          const agentName = isBotMessage ? ctx.getAgents()[0]?.name : undefined;
           ctx.addMessage(
-            participantName,
+            agentName ?? outsideSenderName(discordMsg.authorName, 'Discord'),
             content,
             {
+              ...(agentName === undefined ? { author: { id: discordMsg.authorId, name: discordMsg.authorName } } : {}),
               external: { source: 'discord', id: discordMsg.id },
               channelId,
               timestamp: discordMsg.timestamp.getTime(),
@@ -1371,7 +1383,7 @@ export class DiscordModule implements Module {
       if (isTextFile && attachment.size >= TEXT_FILE_LIMIT_BYTES) {
         blocks.push({
           type: 'text',
-          text: `[Attachment: ${attachment.filename} (${attachment.size.toLocaleString('en-US')} bytes): this host reads text files under ${TEXT_FILE_LIMIT_BYTES.toLocaleString('en-US')} bytes into your context, so its text isn't here. If you need it, ask the sender to paste the part that matters.]`,
+          text: `[${NOTICE_TAG.attachment}: ${suppliedValue(attachment.filename)} (${attachment.size.toLocaleString('en-US')} bytes): this host reads text files under ${TEXT_FILE_LIMIT_BYTES.toLocaleString('en-US')} bytes into your context, so its text isn't here. If you need it, ask the sender to paste the part that matters.]`,
         });
         continue;
       }
@@ -1383,7 +1395,7 @@ export class DiscordModule implements Module {
             const textContent = await response.text();
             blocks.push({
               type: 'text',
-              text: `\n--- File: ${attachment.filename} ---\n${textContent}\n--- End of ${attachment.filename} ---\n`,
+              text: `\n--- File: ${suppliedValue(attachment.filename)} ---\n${markedText(textContent)}\n--- End of ${suppliedValue(attachment.filename)} ---\n`,
             });
           } else {
             // An answer whose body is never read holds its connection.
@@ -1401,11 +1413,11 @@ export class DiscordModule implements Module {
       // For unsupported attachments, add a note
       blocks.push({
         type: 'text',
-        text: `[Attachment: ${attachment.filename} (${contentType || 'unknown type'}): this host didn't read its contents in, so they aren't in your context. If you need them, ask the sender for them in a form you can read, such as pasted text.]`,
+        text: `[${NOTICE_TAG.attachment}: ${suppliedValue(attachment.filename)} (${contentType ? suppliedValue(contentType) : 'unknown type'}): this host didn't read its contents in, so they aren't in your context. If you need them, ask the sender for them in a form you can read, such as pasted text.]`,
       });
     }
 
-    return textFirst(ownText(message.content), blocks);
+    return textFirst(storedOwnText(message.content), blocks);
   }
 
   /**

package/src/modules/history/index.ts

@@ -535,7 +535,7 @@ export class HistoryModule implements Module {
     channelId?: string;
     n: number;
     side: 'newest' | 'oldest';
-  }): { messages: StoredMessage[]; more: boolean } {
+  }): { messages: StoredMessage[]; more: boolean; total?: number } {
     const cm = this.cm as ContextManager;
     const { fromMs, toMs, channelId, n, side } = opts;
     const newest = side === 'newest';
@@ -553,8 +553,8 @@ export class HistoryModule implements Module {
     const fetch = (f: number | undefined, t: number | undefined, limit: number, offset = 0) =>
       limit <= 0 ? [] : cm.queryMessagesByTimeAndChannel({ fromMs: f, toMs: t, channelId, limit, offset }).messages;
     const total = count(fromMs, toMs);
-    if (n === 0) return { messages: [], more: total > 0 };
-    if (total <= n) return { messages: dirSort(fetch(fromMs, toMs, total)), more: false };
+    if (n === 0) return { messages: [], more: total > 0, total };
+    if (total <= n) return { messages: dirSort(fetch(fromMs, toMs, total)), more: false, total };
 
     // The window is parameterised by its FAR bound `e`: [e, toMs] for the
     // newest side, [fromMs, e] for the oldest; its count is monotone in e.
@@ -580,7 +580,7 @@ export class HistoryModule implements Module {
     }
     const fetchCap = Math.max(4 * n, n + 1000);
     if (inCount <= fetchCap) {
-      return { messages: dirSort(fetch(...win(inside), inCount)).slice(0, n), more: true };
+      return { messages: dirSort(fetch(...win(inside), inCount)).slice(0, n), more: true, total };
     }
     // Overshoot: bisect the far bound. The empty side starts one past the
     // range's near end (newest: past toMs / any date; oldest: before lo).
@@ -595,7 +595,7 @@ export class HistoryModule implements Module {
         inside = mid;
         inCount = c;
         if (c <= fetchCap) {
-          return { messages: dirSort(fetch(...win(mid), c)).slice(0, n), more: true };
+          return { messages: dirSort(fetch(...win(mid), c)).slice(0, n), more: true, total };
         }
       }
     }
@@ -607,7 +607,7 @@ export class HistoryModule implements Module {
     const need = n - near.length;
     const ties = count(inside, inside);
     const edgeMs = fetch(inside, inside, need, newest ? Math.max(0, ties - need) : 0);
-    return { messages: dirSort([...near, ...edgeMs]).slice(0, n), more: true };
+    return { messages: dirSort([...near, ...edgeMs]).slice(0, n), more: true, total };
   }
 
   async start(ctx: ModuleContext): Promise<void> {
@@ -1150,7 +1150,8 @@ export class HistoryModule implements Module {
                   hint:
                     (pageFull
                       ? 'More matching messages exist. '
-                      : `Stopped after scanning ${scanned} messages of the window without reaching its end. `) +
+                      : `Stopped after scanning ${scanned} messages of the window without reaching its end` +
+                        (page.length === 0 ? ', so returning none is not a negative result for the window. ' : '. ')) +
                     `Continue by repeating this call with the same from/to/channelId/author plus ` +
                     `the fields of \`resume\` (windowOffset:${resume.windowOffset}, offset:${resume.offset}, afterId).`,
                 };
@@ -1373,6 +1374,7 @@ export class HistoryModule implements Module {
       !!skipRange && m.timestamp.getTime() === edgeMs && m.sequence >= skipRange[0] && m.sequence <= skipRange[1];
     let windowMessages: StoredMessage[];
     let truncated: boolean;
+    let unscanned: number | undefined;
     {
       // Over-fetch by the number of messages at the edge millisecond (the
       // only ones that can be skipped), then drop the skipped ones.
@@ -1381,6 +1383,7 @@ export class HistoryModule implements Module {
       const pool = skipRange ? w.messages.filter((m) => !isSkipped(m)) : w.messages;
       truncated = w.more || pool.length > maxScan;
       windowMessages = pool.slice(0, maxScan);
+      if (w.total !== undefined) unscanned = w.total - (w.messages.length - pool.length) - windowMessages.length;
     }
     const candidatePoolSize = windowMessages.length;
     const candidates = authorFilter ? windowMessages.filter(authorFilter) : windowMessages;
@@ -1394,7 +1397,7 @@ export class HistoryModule implements Module {
     // the pool was never looked at) or the pool itself was truncated. The
     // timestamp is the continuation point — from: (oldest) / to: (newest).
     // Boundary is inclusive, so a message at exactly that instant may repeat.
-    const resumeInfo = (scanned: number): Record<string, unknown> => {
+    const resumeInfo = (scanned: number, matched: number): Record<string, unknown> => {
       const stoppedEarly = scanned < candidates.length;
       if (!stoppedEarly && !truncated) return {};
       // Stopped at limit: the last candidate actually looked at. Scanned the
@@ -1432,9 +1435,16 @@ export class HistoryModule implements Module {
         hint:
           (stoppedEarly
             ? 'Stopped at limit; more candidates remain. '
-            : `Only the ${order} ${candidatePoolSize} messages of this range were scanned (maxScan). `) +
+            : matched === 0
+              ? `No match among the ${order} ${candidatePoolSize} ${candidatePoolSize === 1 ? 'message' : 'messages'} ` +
+                'scanned (maxScan); ' +
+                (unscanned === undefined
+                  ? 'the rest of this range was not searched'
+                  : `${unscanned} more in this range ${unscanned === 1 ? 'was' : 'were'} not searched`) +
+                ', so this is not a negative result for the range. '
+              : `Only the ${order} ${candidatePoolSize} messages of this range were scanned (maxScan). `) +
           `Continue by repeating the call with the fields of \`resume\` (${bound}:"${at}" and skipSequences), ` +
-          'or raise limit/maxScan, or narrow with channelId/author/dates.',
+          `or raise limit/maxScan, or narrow with ${[channelId === undefined ? 'channelId' : null, stoppedEarly && input.author === undefined ? 'author' : null, 'dates'].filter((w) => w !== null).join('/')}.`,
       };
     };
 
@@ -1449,7 +1459,7 @@ export class HistoryModule implements Module {
       // on a deadline. See search-regex-worker.ts's header for the full
       // rationale.
       const { matches, scanned } = await this.searchWithRegexWorker(candidates, query, flags, limit);
-      return { success: true, data: { scanned, ...poolInfo, truncated, ...resumeInfo(scanned), matches } };
+      return { success: true, data: { scanned, ...poolInfo, truncated, ...resumeInfo(scanned, matches.length), matches } };
     }
 
     // Plain substring search (String.prototype.indexOf) is inherently
@@ -1481,7 +1491,7 @@ export class HistoryModule implements Module {
 
     return {
       success: true,
-      data: { scanned, ...poolInfo, truncated, ...resumeInfo(scanned), matches },
+      data: { scanned, ...poolInfo, truncated, ...resumeInfo(scanned, matches.length), matches },
     };
   }
 
@@ -2578,9 +2588,11 @@ function inTextUnits(text: string, hit: MatchHit): MatchHit {
 // author filtering
 // ============================================================================
 
-/** metadata.author as written by MCPL channel ingestion ({id, name}). Every
- *  incoming channel message is stored with participant "user" — the real
- *  author lives only here. */
+/** metadata.author as MCPL channel ingestion and DiscordModule write it
+ *  ({id, name}), and ApiModule ({name}, or the author object an api:message
+ *  event carries). Their participant is "user", or the sender's name marked
+ *  with its source unless it's the generic "user", so the plain author
+ *  name is read here. */
 function authorOf(msg: StoredMessage): { id?: string; name?: string } | undefined {
   const a = (msg.metadata as { author?: unknown } | undefined)?.author;
   if (!a || typeof a !== 'object') return undefined;
@@ -2647,9 +2659,9 @@ function toAuthorSet(spec: AuthorSpec | undefined, field: string): Set<string> |
 
 /**
  * Predicate for `author`/`excludeAuthor`, or null when neither is given.
- * A message's identities are its metadata.author name and id plus its
- * stored participant — the last is what identifies the agent's own turns
- * (and anything else ingested without author metadata). Exact match after
+ * A message's identities are its metadata.author name and id when it has
+ * one, and otherwise its stored participant, which is what identifies the
+ * agent's own turns (and anything else ingested without author metadata). Exact match after
  * normalization, never substring: "ann" must not pull in "joanne".
  */
 function buildAuthorFilter(include: AuthorSpec | undefined, exclude: AuthorSpec | undefined): ((m: StoredMessage) => boolean) | null {

package/src/modules/sender-name.ts

@@ -0,0 +1,9 @@
+/** The participant a module stores for a sender's name from outside the
+ *  framework: on one line, and marked with its source, so it isn't an
+ *  agent's name unless a host names an agent in that form. The generic
+ *  `user` stays as given, since context-manager places injections by the
+ *  last message whose participant is `user`, in any capitalization. */
+export function outsideSenderName(name: string, source: string): string {
+  const line = name.replace(/[\p{Cc}\u2028\u2029]+/gu, ' ');
+  return line.toLowerCase() === 'user' ? line : `${line} (${source})`;
+}