@animalabs/agent-framework 0.23.2 → 0.24.0

package/src/agent.ts

@@ -924,28 +924,89 @@ export class Agent {
   }
 
   /**
-   * RFC-006 consumed watermark: the newest stored message at the last compile
-   * of a model request, or at the last tool boundary that injected messages
-   * into a live one, per branch. Everything above it has never been in a
-   * request and may still be replaced or withdrawn in place by its sender.
+   * RFC-006 consumed watermark, per branch: the newest stored message as of
+   * the latest of the agent's creation, a committing compile that returns,
+   * and a tool boundary that injected messages into a live stream declaring
+   * it carries them (`supportsInjectedMessages` true: membrane's native
+   * path, from membrane 0.6.0). A compile counts from when it takes its
+   * value, before it awaits, so one that began before a boundary's mark
+   * doesn't roll the mark back (applyCompileWatermark), and a dry run, such
+   * as previewActivation's, doesn't move it. Each move takes the store's
+   * head, a scalar, so it also covers stored messages the agent wasn't
+   * given, such as another slot's.
+   *
+   * A message above it may still be replaced or withdrawn in place by its
+   * sender, though it may already have been in one of the agent's requests.
+   * A live stream carries each round's own content and results, which it
+   * stores at its tool boundaries, into its next request. It can also carry
+   * the messages injected at a boundary whose stream didn't say whether it
+   * carries injections, as no membrane 0.5.x stream does: its native path
+   * carries them and its XML path drops them, and either way they stay
+   * above it.
    */
   private consumedWatermark: { branch: string; sequence: number } | null = null;
-  /** Counts marks: a compile writes its watermark back only if no mark was
-   *  made while it ran (a tool boundary's, or another compile's). */
+  /** Counts marks (markContextConsumed's and applyCompileWatermark's), so a
+   *  compile that finishes can tell whether one was made while it ran. */
   private watermarkMarks = 0;
+  /**
+   * The newest stored message a compile or a tool boundary may have put in
+   * front of the agent, per branch. It moves where the consumed watermark
+   * does, and sooner: when a committing compile takes its value, before it
+   * awaits, and at every tool boundary that injects, whether or not the
+   * stream says it carries injected messages. A message above it may still
+   * have been shown, though: for one, a live stream carries each round's own
+   * content and results, stored at a boundary that injected nothing, into its
+   * next request. A compile that throws assembled nothing, and gives its move
+   * back where it can (unshowFailedCompile). A scalar counts a prefix, so a
+   * message stored below it without having been shown counts as shown, which
+   * errs toward a marker.
+   */
+  private shownWatermark: { branch: string; sequence: number } | null = null;
 
   getConsumedWatermark(): { branch: string; sequence: number } | null {
     return this.consumedWatermark;
   }
 
+  getShownWatermark(): { branch: string; sequence: number } | null {
+    return this.shownWatermark;
+  }
+
   /** Mark everything currently stored as consumed (the agent's creation, at
-   *  boot or later, and a tool boundary that injected messages into the live
-   *  stream). */
+   *  boot or later, and a tool boundary that injected messages into a live
+   *  stream declaring it carries them; see consumedWatermark). */
   markContextConsumed(): void {
     // Tolerates partial context-manager doubles (tests build Agents over
-    // stubs): without a watermark nothing is ever treated as unread.
+    // stubs). Without a watermark, a reader that looks for one takes its own
+    // side: the coalescer counts the message as read, and the framework's
+    // deferredWriteReadOrGone and unreadNoticesForPrimary count it as unread.
     this.consumedWatermark = this.pendingWatermark();
     this.watermarkMarks++;
+    this.shownWatermark = this.consumedWatermark;
+  }
+
+  /** Mark everything currently stored as possibly shown (a tool boundary
+   *  that injected messages, whatever its stream says it carries). Without
+   *  a watermark the coalescer counts a message as shown, as it counts one
+   *  read without a consumed watermark. */
+  markContextShown(): void {
+    this.shownWatermark = this.pendingWatermark();
+  }
+
+  /** A committing compile that threw assembled nothing, so its own move of
+   *  the shown watermark goes back, unless a boundary or another compile has
+   *  moved the watermark since. It goes back to the watermark as the compile
+   *  found it, which can be another compile's claim that has failed as well.
+   *  Of two overlapping committing compiles, if the first to start throws
+   *  first, it gives nothing back (the second's claim is current), and if
+   *  the second then throws, it restores the first's failed claim. Messages
+   *  up to that claim then count as shown, although no request held those
+   *  above the watermark the first compile found, which errs toward a marker
+   *  until the next compile or boundary moves the watermark. */
+  private unshowFailedCompile(
+    watermark: { branch: string; sequence: number } | null,
+    before: { branch: string; sequence: number } | null,
+  ): void {
+    if (watermark && this.shownWatermark === watermark) this.shownWatermark = before;
   }
 
   /**
@@ -953,7 +1014,9 @@ export class Agent {
    * the watermark only advances: if a mark was made while the compile ran,
    * the compile's (older) one is applied only where it is later on that
    * mark's branch, so a boundary's mark is never rolled back by a compile
-   * that started before it (a preview during a live turn).
+   * that started before it (a committing compile, such as compileContext's,
+   * run during a live turn; a dry run, such as previewActivation's, never
+   * reaches here).
    */
   private applyCompileWatermark(watermark: { branch: string; sequence: number }, marksBefore: number): void {
     const current = this.consumedWatermark;
@@ -993,8 +1056,16 @@ export class Agent {
     // fails assembled nothing, so the watermark moves only on success.
     const watermark = this.pendingWatermark();
     const marksBefore = this.watermarkMarks;
+    const shownBefore = this.shownWatermark;
+    if (watermark) this.shownWatermark = watermark;
     const compile = () => this.contextManager.compile(this.compileBudget(budget));
-    const result = budget ? await compile() : await this.compileAtLiveBudget(compile);
+    let result: CompileResult;
+    try {
+      result = budget ? await compile() : await this.compileAtLiveBudget(compile);
+    } catch (error) {
+      this.unshowFailedCompile(watermark, shownBefore);
+      throw error;
+    }
     if (watermark) this.applyCompileWatermark(watermark, marksBefore);
     return result;
   }
@@ -1035,8 +1106,18 @@ export class Agent {
     // any compile before it selects.
     const watermark = opts?.dryRun ? null : this.pendingWatermark();
     const marksBefore = this.watermarkMarks;
+    // Shown from the compile's start: what it assembles is in front of the
+    // agent before the consumed watermark moves, once it returns.
+    const shownBefore = this.shownWatermark;
+    if (watermark) this.shownWatermark = watermark;
     const compile = () => this.contextManager.compile(this.compileBudget(budget), injections, opts as never);
-    const result = budget || opts?.dryRun ? await compile() : await this.compileAtLiveBudget(compile);
+    let result: CompileResult;
+    try {
+      result = budget || opts?.dryRun ? await compile() : await this.compileAtLiveBudget(compile);
+    } catch (error) {
+      this.unshowFailedCompile(watermark, shownBefore);
+      throw error;
+    }
     if (watermark) this.applyCompileWatermark(watermark, marksBefore);
     return result;
   }

package/src/api/server.ts

@@ -489,6 +489,12 @@ export class ApiServer {
     if (!params.participant || !params.content) {
       throw new Error('participant and content are required');
     }
+    // ApiModule stores the message as one text block, which context-manager
+    // refuses unless its text is a string, so content that isn't text is
+    // refused here, where the caller hears it, rather than at dispatch.
+    if (typeof params.content !== 'string') {
+      throw new Error('content must be text');
+    }
 
     // Push api:message event for the ApiModule to handle
     this.framework.pushEvent({
@@ -587,14 +593,14 @@ export class ApiServer {
 
     const from = this.currentBranch;
 
-    // The framework switches the store, starts the delivery of its Discord
-    // awareness marks behind the data-plane gate, and re-materializes the
-    // config mount. It refuses during a live turn or once stop() has begun,
-    // and stop() waits for one already running. It moves the store once any
-    // maintenance already running has finished, so the move can come after
-    // this call returns. The event names this switch's own move, from the
-    // branch read here to the one it was asked for: another switch can move
-    // the store again before this one continues.
+    // The framework switches the store and re-materializes the config mount;
+    // a branch switch adds or removes no Discord awareness marks. It refuses
+    // during a live turn or once stop() has begun, and stop() waits for one
+    // already running. It moves the store once any maintenance already
+    // running has finished, so the move can come after this call returns.
+    // The event names this switch's own move, from the branch read here to
+    // the one it was asked for: another switch can move the store again
+    // before this one continues.
     let switched = false;
     try {
       await this.framework.switchBranch(params.name);
@@ -647,8 +653,6 @@ export class ApiServer {
     const result = this.framework.undoLastTurn(params.agentName);
 
     if (result.undone) {
-      // Marks follow behind the data-plane gate; the undo doesn't wait for Discord.
-      this.framework.startDiscordAwarenessDelivery('undo', params.agentName);
       this.broadcast('branch:switched', {
         from: result.fromBranch,
         to: result.toBranch,
@@ -667,8 +671,6 @@ export class ApiServer {
     const result = this.framework.redo(params.agentName);
 
     if (result.redone) {
-      // Marks follow behind the data-plane gate; the redo doesn't wait for Discord.
-      this.framework.startDiscordAwarenessDelivery('redo', params.agentName);
       this.broadcast('branch:switched', {
         from: result.fromBranch,
         to: result.toBranch,