@animalabs/agent-framework 0.28.0 → 0.30.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;
 }
 
@@ -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;
 }