@animalabs/agent-framework 0.28.0 → 0.29.0

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;
 }
 
@@ -508,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

@@ -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> {
@@ -320,9 +320,8 @@ export class ModuleRegistry {
    * 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, as the `utils`
-   * tool has a utility's, passes it as `definition`, and it's checked against
-   * that one.
+   * A caller that has already resolved the tool's definition passes it as
+   * `definition`, and it's checked against that one.
    */
   async handleToolCall(given: ToolCall, options: { definition?: ToolDefinition } = {}): Promise<ToolResult> {
     const marked = markedInputRefusal(given);

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

@@ -2588,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;
@@ -2657,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})`;
+}

package/src/modules/workspace/answers.ts

@@ -81,6 +81,18 @@ export function errnoWayOn(code: string | undefined, otherwise = 'Calling again
   return otherwise;
 }
 
+export function errnoClause(code: string | undefined, again: string, then: string): string {
+  const lasting = `${again} won't change that; `;
+  if (code === 'ENAMETOOLONG') return `${lasting}a shorter name would get past it`;
+  const fix = hostFix(code);
+  if (fix !== undefined) {
+    return code !== undefined && PASSING.has(code)
+      ? `${again} may get past it; if it fails the same way, whoever runs this host can ${fix}`
+      : `${lasting}whoever runs this host can ${fix}, and ${then}`;
+  }
+  return `${again} checks it afresh; if the same reason comes back, whoever runs this host can fix it on disk`;
+}
+
 const OS_ERRNO = new Map<number, string>();
 for (const [name, number] of Object.entries(constants.errno)) if (!OS_ERRNO.has(number)) OS_ERRNO.set(number, name);
 
@@ -100,9 +112,15 @@ export function changesFiles(tool: string): boolean {
   return CHANGING.has(tool);
 }
 
-export const ROOT_RECHECK = "Calling again may work; if it fails the same way, whoever runs this host can check the mount's directory and its path.";
+export const UNFOLLOWED_STEP = 'whoever runs this host can set followSymlinks: true on this mount if it leads inside the mount, mount what it leads to, or a directory that holds it, if it leads outside, or remove it if it leads nowhere';
+
+export const MOUNT_IT = 'whoever runs this host can mount it, or a directory that holds it';
+
+export const OUTSIDE_STEP = `nothing done through this mount reaches what it leads to, and ${MOUNT_IT}`;
 
-export const ROOT_UNCHECKED = "Calling again won't change that while the mount's directory is gone from its path, and checks it afresh otherwise; whoever runs this host can check the directory and its path.";
+export const RESOLVED_OUTSIDE_STEP = 'nothing done through this mount reaches where it resolves, and whoever runs this host can mount that place';
+
+export const ROOT_RECHECK = "Calling again may work; if it fails the same way, whoever runs this host can check the mount's directory and its path.";
 
 export const AWAITS_REOPEN = "The workspace can't check its files against disk until its store is reopened, so calling again won't change that; whoever runs this host can reopen it with a restart.";
 

package/src/modules/workspace/direct-write.ts

@@ -56,7 +56,7 @@ import type { BigIntStats } from 'node:fs';
 import { lstat, open, realpath } from 'node:fs/promises';
 import { relative, sep } from 'node:path';
 import { refusedLanding } from './effects.js';
-import { ROOT_RECHECK, errnoWayOn, errnoWords, onlyTheHost, systemWords } from './answers.js';
+import { OUTSIDE_STEP, RESOLVED_OUTSIDE_STEP, ROOT_RECHECK, UNFOLLOWED_STEP, errnoWayOn, errnoWords, onlyTheHost, systemWords } from './answers.js';
 import {
   type CheckedDir,
   type MountView,
@@ -135,7 +135,7 @@ export class WriteRefused extends Error {
 
 const AFRESH = 'Calling again checks it afresh.';
 
-const NAME_ITS_OWN = "Calling again won't change that; if you know the file it leads to, name that file by its own path.";
+const NAME_ITS_OWN = `Calling again won't change that; ${UNFOLLOWED_STEP}.`;
 
 function rootWayOn(code: string | undefined): string {
   return code === 'ENOENT' || code === 'ENOTDIR' ? onlyTheHost("put the mount's directory back at its path") : errnoWayOn(code, ROOT_RECHECK, true);
@@ -145,7 +145,8 @@ function refusedWayOn(reason: string, code?: string, hostsName = false): string
   if (reason === ROOT_UNAVAILABLE) return rootWayOn(code);
   if (code !== undefined) return errnoWayOn(code, undefined, hostsName);
   if (reason === NOT_FOLLOWED) return NAME_ITS_OWN;
-  if (reason === OUTSIDE_PARENT || reason === LEAVES_MOUNT) return "Calling again won't change that; the workspace writes only inside its mounts.";
+  if (reason === LEAVES_MOUNT) return `Calling again won't change that; ${OUTSIDE_STEP}.`;
+  if (reason === OUTSIDE_PARENT) return `Calling again won't change that; ${RESOLVED_OUTSIDE_STEP}.`;
   if (reason === NOT_A_DIRECTORY) return "Calling again won't change that while something other than a directory stands where the path needs one; another path, or removing what stands there, would.";
   return null;
 }