@animalabs/agent-framework 0.22.3 → 0.23.0

package/src/modules/discord/refusal.ts

@@ -0,0 +1,13 @@
+/**
+ * A refusal the Discord module gives the agent as worded: Discord refused the
+ * request, its target can't take it, or a lookup before the tool's change (a
+ * send, an edit, a deletion, a reaction or a thread) stopped on an unexpected
+ * error, so the tool did nothing, and the message says why and what to do
+ * instead. A thread a send asked for and didn't get isn't one: the send
+ * returns why as words, since its message is out.
+ * Anything else a tool throws is an unexpected error, which the module words
+ * itself (DiscordModule.handleToolCall).
+ */
+export class DiscordRefusal extends Error {
+  override readonly name = 'DiscordRefusal';
+}

package/src/modules/discord/types.ts

@@ -375,6 +375,10 @@ export interface DiscordEditEvent {
   type: 'discord:edit';
   discordMessageId: string;
   newContent: string;
+  /** The message's attachments as the edit left them, when the client knows
+   *  them: a stored row whose text comes first drops the blocks of those it
+   *  no longer has. */
+  attachments?: DiscordAttachment[];
   [key: string]: unknown;
 }
 
@@ -412,10 +416,12 @@ export interface DiscordClientInterface {
 
   /**
    * Send a message to a channel, and start the thread `createThread` asks
-   * for when the channel can hold threads; in one that can't, such as a DM,
-   * no thread is started and nothing says so. When this resolves, the
-   * message was sent. `threadFailure`, when there is one, is why the thread
-   * it tried to start wasn't.
+   * for when the channel can hold threads. When this resolves, the message
+   * was sent. `threadFailure`, when there is one, is why the thread it tried
+   * to start wasn't, which the send reports as its error; `note`, when there
+   * is one, is something the agent should know of a send that succeeded,
+   * such as a thread its channel can't hold. DiscordJsClient words both for
+   * the agent.
    */
   sendMessage(
     channelId: string,
@@ -424,10 +430,10 @@ export interface DiscordClientInterface {
       replyTo?: string;
       createThread?: { name: string };
     }
-  ): Promise<{ messageId: string; threadFailure?: string }>;
+  ): Promise<{ messageId: string; threadFailure?: string; note?: string }>;
 
-  /** Send a DM to a user */
-  sendDM(userId: string, content: string): Promise<{ messageId: string }>;
+  /** Send a DM to a user. `channelId`, when the client gives it, is the direct message channel's id, which history reads. */
+  sendDM(userId: string, content: string): Promise<{ messageId: string; channelId?: string }>;
 
   /** Fetch a message's text content */
   fetchMessage(channelId: string, messageId: string): Promise<string>;
@@ -467,8 +473,10 @@ export interface DiscordClientInterface {
   /** Register message handler */
   onMessage(handler: (message: DiscordMessageData) => void): void;
 
-  /** Register message edit handler */
-  onMessageEdit(handler: (messageId: string, newContent: string) => void): void;
+  /** Register message edit handler. A client that knows the edited
+   *  message's attachments passes them third; one that passes two arguments
+   *  leaves a stored row's attachment blocks as they are. */
+  onMessageEdit(handler: (messageId: string, newContent: string, attachments?: DiscordAttachment[]) => void): void;
 
   /** Register message delete handler */
   onMessageDelete(handler: (messageId: string) => void): void;

package/src/modules/health/index.ts

@@ -26,6 +26,7 @@ import type { EventResponse, ProcessState } from '../../types/module.js';
 import type { AgentFramework } from '../../framework.js';
 import { formatZonedDateTime, resolveTimeZone } from '../../timezone.js';
 import { safeSlice } from '../../safe-slice.js';
+import { unknownToolMessage } from '../unknown-tool.js';
 
 export interface HealthModuleConfig {
   /** IANA zone for timestamps returned by the snapshot tool. */
@@ -127,7 +128,7 @@ export class HealthModule implements Module {
 
   async handleToolCall(call: ToolCall): Promise<ToolResult> {
     if (call.name !== 'snapshot') {
-      return { success: false, isError: true, error: `Unknown tool: ${call.name}` };
+      return { success: false, isError: true, error: unknownToolMessage(this.name, call.name, this.getTools()) };
     }
     const input = (call.input ?? {}) as SnapshotInput;
     const lookback = input.lookback ?? this.config.defaultLookback;
@@ -156,8 +157,11 @@ export class HealthModule implements Module {
     includeSubagents: boolean,
   ): Record<string, unknown> {
     if (!this.framework || !this.store) {
+      // The host's mistake, named for whoever runs it; the agent reads what
+      // it can do about it, which is nothing.
+      console.error('[health] snapshot asked for before the host bound the module: call bind(framework, store) before tool dispatch');
       throw new Error(
-        'HealthModule not bound — host must call bind(framework, store) before tool dispatch.',
+        "The health snapshot isn't available: this host hasn't finished setting up the health module, so nothing was read. Calling it again won't change that; ask whoever runs this host.",
       );
     }
 

package/src/modules/index.ts

@@ -30,7 +30,7 @@ export type {
   SyncInput,
 } from './workspace/index.js';
 
-export { DiscordModule, DiscordJsClient } from './discord/index.js';
+export { DiscordModule, DiscordJsClient, DiscordRefusal } from './discord/index.js';
 export type { DiscordJsClientConfig } from './discord/index.js';
 export type {
   DiscordModuleConfig,

package/src/modules/workspace/disk-agreement.ts

@@ -181,6 +181,12 @@ export class DiskAgreement {
    * place owes none (recordWalk).
    */
   private unsynced = false;
+  /**
+   * Whether memory holds a whole state: false until a rebuild first runs to
+   * its end. A rebuild fills a new map and swaps it in only at its end, so
+   * one that throws partway leaves whatever whole state came before it.
+   */
+  private whole = false;
   /** Whether this host observes file modes (not on Windows): where it doesn't, no record it writes claims one. */
   private readonly modesObserved: () => boolean;
 
@@ -206,8 +212,10 @@ export class DiskAgreement {
    * recorded (the store may hold it where this process can't read it back),
    * and a decision from stale P can record what reopening contradicts, such
    * as a conflict that stays after the right evidence is back. So until the
-   * store is reopened, no evidence is read, written or checkpointed, and
-   * every pass and tool call that needs it fails.
+   * store is reopened, no evidence is read (but for rootIdentityForRead's
+   * one exception), written or checkpointed, and every pass and tool call
+   * that needs it fails. The same holds, the exception included, when the
+   * open's rebuild threw: there is no whole evidence to read.
    */
   ensureReconciled(): void {
     if (this.journal.needsReopen) {
@@ -216,6 +224,12 @@ export class DiskAgreement {
         'an append to its journal failed inside the store, and the evidence may lack what it recorded',
       );
     }
+    if (!this.whole) {
+      throw new Error(
+        'Disk-agreement evidence is unavailable until the store is reopened, as at the next start: ' +
+        'reading it back from the store failed',
+      );
+    }
     if (this.journal.needsReconcile) this.rebuild();
   }
 
@@ -253,16 +267,24 @@ export class DiskAgreement {
       const mount = replayed.get(entry.mount);
       if (mount) apply(mount, entry);
     }
-    this.mounts.clear();
+    // Filled apart and swapped in at the end, so an append that throws here
+    // leaves memory as it was, whole, rather than with the mounts after it
+    // missing. Nothing reaches that today: only an open with a moved mount
+    // appends here, the workspace opens each agreement once, and after the
+    // open a rebuild finds every mount's record and appends none.
+    const rebuilt = new Map<string, MountEvidence>();
     for (const { name, root } of this.configured) {
       const found = replayed.get(name);
       if (found && sameRootPath(found.root, root)) {
-        this.mounts.set(name, found);
+        rebuilt.set(name, found);
       } else {
-        this.mounts.set(name, { root, paths: new Map(), walks: new Map() });
+        rebuilt.set(name, { root, paths: new Map(), walks: new Map() });
         this.journal.append({ t: 'mount', mount: name, root });
       }
     }
+    this.mounts.clear();
+    for (const [name, mount] of rebuilt) this.mounts.set(name, mount);
+    this.whole = true;
   }
 
   /** The identity of the root this mount's evidence was gathered under, once any was. */
@@ -271,6 +293,25 @@ export class DiskAgreement {
     return this.mounts.get(mount)?.identity;
   }
 
+  /**
+   * The identity a disk read checks the mount's root against: the one in
+   * memory once memory is whole, in every state of the journal, and an error
+   * until then. It is the last identity whose append succeeded, since write()
+   * appends before it applies, and no reconcile can change it, since root
+   * entries are written without a sync; were one made durable, its failed
+   * sync would leave the identity from before it: an old one, which refuses
+   * the new root, or none, as for a mount with no recorded identity. This
+   * is the one exception to ensureReconciled's "no evidence is read": the
+   * layer stops reading so that a decision from stale evidence can't record
+   * what reopening contradicts, and a read records nothing. Refusing reads
+   * instead would stop every host read of the workspace's disk until a
+   * restart.
+   */
+  rootIdentityForRead(mount: string): RootIdentity | undefined {
+    if (!this.whole) this.ensureReconciled(); // throws: there's no whole state to read
+    return this.mounts.get(mount)?.identity;
+  }
+
   /**
    * Record the root's identity just before the first evidence a mount gains:
    * the caller saw it as the root while gathering that evidence. A no-op once

package/src/modules/workspace/effects.ts

@@ -24,7 +24,8 @@
  * Node has no openat, so a create, mkdir or unlink still resolves its path by
  * name after the parent was checked: a parent replaced concurrently in that
  * window can redirect that one operation, leaving an empty file or directory
- * outside the mount or unlinking a same-named file there. Nor is there an
+ * outside the mount or in a nested mount's directory, or unlinking a
+ * same-named file there. Nor is there an
  * unlink bound to an inode: an unlink checks the entry's identity again just
  * before it, and a file replaced at its path after that check is the one
  * unlinked. Content writes stay bound to the descriptor verified before
@@ -53,7 +54,9 @@ import {
   errno,
   checkDir,
   checkRoot,
+  leadsInto,
   nameOf,
+  nestedAtReal,
   parentOf,
 } from './observe.js';
 
@@ -273,7 +276,7 @@ export async function writeContained(
   let stage = 'write the file';
   try {
     const created = touched;
-    await checkOpened(view, rootReal, root, parent, target, handle, expect, noFollow, touched);
+    await checkOpened(view, rootReal, rel, root, parent, target, handle, expect, noFollow, touched);
     touched = true;
     // The mode the bytes are written at, and the one the file ends with.
     let before: number | undefined;
@@ -369,14 +372,16 @@ export async function writeContained(
  * Before an effect on an opened file: a regular file, and — unless forced —
  * still holding what was decided on. The hash reads the whole file, so it
  * comes first, and the checks of where the file is follow it: canonically
- * inside the mount, the one this path names (and not a symlink, where the
- * mount follows none and the open couldn't refuse one), with no other names,
- * in the directory still at its path beneath the root still at its own; and
- * nothing wrote it while those ran.
+ * inside the mount and in no nested mount's directory (nestedAtReal), the
+ * one this path names (and not a symlink, where the mount follows none and
+ * the open couldn't refuse one), with no other names, in the directory still
+ * at its path beneath the root still at its own; and nothing wrote it while
+ * those ran.
  */
 async function checkOpened(
   view: MountView,
   rootReal: string,
+  rel: string,
   root: CheckedDir,
   parent: CheckedDir,
   target: string,
@@ -391,6 +396,8 @@ async function checkOpened(
   const real = await realpath(target).catch(() => null);
   if (real === null) throw new EffectFailed(CHANGED, touched);
   if (!contained(rootReal, real)) throw new EffectFailed(view.followSymlinks ? 'a symlink that leaves the mount' : OUTSIDE_PARENT, touched);
+  const holder = nestedAtReal(real, view.nested);
+  if (holder) throw new EffectFailed(leadsInto(view.name, rel, holder), touched);
   const named = await stat(real, { bigint: true }).catch(() => null);
   if (named === null || named.dev !== info.dev || named.ino !== info.ino) throw new EffectFailed(CHANGED, touched);
   if (!view.followSymlinks) {
@@ -459,7 +466,7 @@ export async function chmodContained(
   let touched = false;
   let stage = 'set the file\'s mode';
   try {
-    await checkOpened(view, rootReal, root, parent, target, handle, expect, noFollow, false);
+    await checkOpened(view, rootReal, rel, root, parent, target, handle, expect, noFollow, false);
     const current = Number((await handle.stat({ bigint: true })).mode & 0o777n);
     if (from !== undefined && current !== from) throw new EffectFailed(MODE_CHANGED, false);
     const narrowing = (current & ~mode & 0o777) !== 0;
@@ -525,6 +532,10 @@ export async function unlinkContained(view: MountView, rootReal: string, rel: st
     if (!view.followSymlinks) throw new EffectFailed(NOT_FOLLOWED, false);
     const real = await realpath(target).catch(() => null);
     if (real === null || !contained(rootReal, real)) throw new EffectFailed('a symlink that leaves the mount', false);
+    // One leading into a nested mount's directory is that mount's: the link
+    // and the file it leads to are left as they are.
+    const holder = nestedAtReal(real, view.nested);
+    if (holder) throw new EffectFailed(leadsInto(view.name, rel, holder), false);
     const through = await stat(real, { bigint: true }).catch(() => null);
     if (through === null) throw new EffectFailed(CHANGED, false);
     // A followed link stands for the file it leads to, so it's removed only