agl 40.5.1 → 41.0.0

package/ts/classes.controllereventdelivery.ts

@@ -0,0 +1,289 @@
+import type { IControllerEvent } from '../ts_interfaces/interfaces.js';
+
+/** One authenticated browser connection that receives controller events. */
+export interface IControllerEventViewer {
+  peerId: string;
+  /** Sends one event; resolves on the browser's acknowledgement, rejects on its timeout or a closed connection. */
+  send(eventArg: IControllerEvent): Promise<void>;
+}
+
+export interface IControllerEventDeliveryLimits {
+  /** Events one viewer may have waiting before its queue collapses into a resync. */
+  events: number;
+  /** Serialized bytes one viewer may have waiting before its queue collapses into a resync. */
+  bytes: number;
+  /** The largest live message delta a merge in a viewer's queue may produce. */
+  mergedDeltaBytes: number;
+}
+
+export interface IControllerEventDeliveryOptions {
+  /** The connections that receive events now; read once per batch of pushed events. */
+  viewers(): Promise<IControllerEventViewer[]>;
+  /** Events with one key carry the same state, so in a collapsed queue the newest replaces the older ones. */
+  eventKey(eventArg: IControllerEvent): string;
+  /** Merges a contiguous live message delta into the delta queued just before it, or refuses with `undefined`. */
+  mergeDelta(previousArg: IControllerEvent, eventArg: IControllerEvent): IControllerEvent | undefined;
+  limits: IControllerEventDeliveryLimits;
+}
+
+interface IQueuedControllerEvent {
+  event: IControllerEvent;
+  /** `JSON.stringify(event)` bytes; for a merged delta the sum of its parts, never less than its size. */
+  bytes: number;
+}
+
+interface IViewerQueue {
+  viewer: IControllerEventViewer;
+  /** Waiting events in send order. Normal keys are a sequence; a collapsed queue keys by state. */
+  events: Map<string, IQueuedControllerEvent>;
+  /** The key of the newest waiting event while the queue is not collapsed: where a delta may merge. */
+  tailKey?: string;
+  bytes: number;
+  /** Set when the queue overflowed and until it drains: events then replace older ones of their state. */
+  collapsed: boolean;
+  sending?: Promise<void>;
+  removed: boolean;
+  /** How many times this queue collapsed. */
+  collapses: number;
+}
+
+interface IPendingFanOut {
+  item: IQueuedControllerEvent;
+  delivered: () => void;
+}
+
+const isLiveEvent = (eventArg: IControllerEvent): boolean => Boolean(
+  eventArg.toolExecution
+  || eventArg.reasoningUpdate
+  || eventArg.reasoningDelta
+  || eventArg.textUpdate
+  || eventArg.textDelta,
+);
+
+/** The live stream content in one event, which only a delta's own successor or a re-read can replace. */
+const isMessageDelta = (eventArg: IControllerEvent): boolean => Boolean(eventArg.reasoningDelta || eventArg.textDelta);
+
+/**
+ * Delivers controller events to every viewer through its own bounded, ordered queue, so a viewer that acknowledges
+ * slowly or never delays only itself. Each viewer has at most one event in flight and receives events in push order.
+ *
+ * A viewer whose queue passes its limits is resynchronized alone, with the existing Flex queue's collapse rules:
+ * the queue keeps the newest event of each state key (statuses, barriers, feed and ticket revisions, settings),
+ * drops live tool, reasoning and text content, and ends with `sessions.changed` for each harness whose live content
+ * it dropped, which makes the browser re-read the conversations and the open session (live snapshots included).
+ * The viewer's own revision checks catch any delta that no longer fits. Should a collapsed queue still hold more
+ * than its event limit, each session's states fold into their harness's `sessions.changed` too, so what remains is
+ * one event per harness and per project or global state. The queue stays collapsed until it drains.
+ */
+export class ControllerEventDelivery {
+  private readonly queues = new Map<string, IViewerQueue>();
+  private readonly fanOutQueue: IPendingFanOut[] = [];
+  private fanOutTask?: Promise<void>;
+  private sequence = 0;
+  private generation = 0;
+
+  constructor(private readonly options: IControllerEventDeliveryOptions) {}
+
+  /**
+   * Queues one event for every current viewer, in push order. Resolves once each viewer's queue holds it; it never
+   * waits for an acknowledgement.
+   */
+  public push(eventArg: IControllerEvent): Promise<void> {
+    const item: IQueuedControllerEvent = {
+      event: eventArg,
+      bytes: Buffer.byteLength(JSON.stringify(eventArg), 'utf8'),
+    };
+    return new Promise<void>((resolve) => {
+      this.fanOutQueue.push({ item, delivered: resolve });
+      this.startFanOut();
+    });
+  }
+
+  /** The events waiting for one viewer, in send order (the one in flight excluded). */
+  public waiting(peerIdArg: string): IControllerEvent[] {
+    return [...(this.queues.get(peerIdArg)?.events.values() ?? [])].map((itemArg) => itemArg.event);
+  }
+
+  /** How many times the queue of a connected viewer collapsed into a resync. */
+  public collapseCount(peerIdArg: string): number {
+    return this.queues.get(peerIdArg)?.collapses ?? 0;
+  }
+
+  /** Drops every waiting event and waits for the sends in flight; later pushes start fresh queues. */
+  public async stop(): Promise<void> {
+    this.generation += 1;
+    const sending: Promise<void>[] = [];
+    for (const queue of this.queues.values()) {
+      queue.removed = true;
+      queue.events.clear();
+      queue.bytes = 0;
+      if (queue.sending) sending.push(queue.sending);
+    }
+    this.queues.clear();
+    if (this.fanOutTask) sending.push(this.fanOutTask);
+    await Promise.allSettled(sending);
+  }
+
+  private startFanOut(): void {
+    if (this.fanOutTask) return;
+    const task = this.fanOut().finally(() => {
+      if (this.fanOutTask === task) this.fanOutTask = undefined;
+      if (this.fanOutQueue.length > 0) this.startFanOut();
+    });
+    this.fanOutTask = task;
+  }
+
+  private async fanOut(): Promise<void> {
+    while (this.fanOutQueue.length > 0) {
+      const batch = this.fanOutQueue.splice(0);
+      const generation = this.generation;
+      let viewers: IControllerEventViewer[] = [];
+      try {
+        viewers = await this.options.viewers();
+      } catch {
+        // No viewer can be named now; the events reach none, as a push without connections.
+      }
+      if (generation === this.generation) {
+        const current = new Set(viewers.map((viewerArg) => viewerArg.peerId));
+        for (const [peerId, queue] of this.queues) {
+          if (current.has(peerId)) continue;
+          queue.removed = true;
+          queue.events.clear();
+          queue.bytes = 0;
+          this.queues.delete(peerId);
+        }
+        for (const viewer of viewers) {
+          let queue = this.queues.get(viewer.peerId);
+          if (!queue) {
+            queue = { viewer, events: new Map(), bytes: 0, collapsed: false, removed: false, collapses: 0 };
+            this.queues.set(viewer.peerId, queue);
+          }
+          queue.viewer = viewer;
+          for (const pending of batch) this.enqueue(queue, pending.item);
+          this.startSending(queue);
+        }
+      }
+      for (const pending of batch) pending.delivered();
+    }
+  }
+
+  private enqueue(queueArg: IViewerQueue, itemArg: IQueuedControllerEvent): void {
+    if (queueArg.collapsed) {
+      this.absorb(queueArg, itemArg);
+      return;
+    }
+    if (isMessageDelta(itemArg.event) && queueArg.tailKey !== undefined) {
+      const tailKey = queueArg.tailKey;
+      const tail = queueArg.events.get(tailKey);
+      if (
+        tail !== undefined
+        && isMessageDelta(tail.event)
+        && tail.bytes + itemArg.bytes <= this.options.limits.mergedDeltaBytes
+      ) {
+        const merged = this.options.mergeDelta(tail.event, itemArg.event);
+        if (merged) {
+          queueArg.events.set(tailKey, { event: merged, bytes: tail.bytes + itemArg.bytes });
+          queueArg.bytes += itemArg.bytes;
+          if (queueArg.bytes > this.options.limits.bytes) this.collapse(queueArg);
+          return;
+        }
+      }
+    }
+    if (
+      queueArg.events.size + 1 > this.options.limits.events
+      || queueArg.bytes + itemArg.bytes > this.options.limits.bytes
+    ) {
+      this.collapse(queueArg);
+      this.absorb(queueArg, itemArg);
+      return;
+    }
+    this.sequence += 1;
+    queueArg.tailKey = `#${this.sequence}`;
+    queueArg.events.set(queueArg.tailKey, itemArg);
+    queueArg.bytes += itemArg.bytes;
+  }
+
+  private collapse(queueArg: IViewerQueue): void {
+    const dropped = [...queueArg.events.values()];
+    queueArg.events.clear();
+    queueArg.tailKey = undefined;
+    queueArg.bytes = 0;
+    queueArg.collapsed = true;
+    queueArg.collapses += 1;
+    for (const item of dropped) this.absorb(queueArg, item);
+  }
+
+  /** Adds an event to a collapsed queue: the newest of its state, or a resync of its harness for live content. */
+  private absorb(queueArg: IViewerQueue, itemArg: IQueuedControllerEvent): void {
+    if (isLiveEvent(itemArg.event)) {
+      this.resyncHarness(queueArg, itemArg.event);
+    } else {
+      this.place(queueArg, `state\0${this.options.eventKey(itemArg.event)}`, itemArg);
+    }
+    if (queueArg.events.size > this.options.limits.events) this.foldSessions(queueArg);
+  }
+
+  /**
+   * A collapsed queue that still holds more states than its limit keeps only what is not about one session: each
+   * session's states become their harness's `sessions.changed`, whose re-read covers the open session and the list.
+   */
+  private foldSessions(queueArg: IViewerQueue): void {
+    for (const [key, item] of [...queueArg.events]) {
+      if (!key.startsWith('state\0') || item.event.sessionId === undefined) continue;
+      queueArg.events.delete(key);
+      queueArg.bytes -= item.bytes;
+      this.resyncHarness(queueArg, item.event);
+    }
+  }
+
+  private resyncHarness(queueArg: IViewerQueue, eventArg: IControllerEvent): void {
+    const harnessId = eventArg.harnessId;
+    const event: IControllerEvent = {
+      type: 'sessions.changed',
+      ...(harnessId === undefined ? {} : { harnessId }),
+      timestamp: eventArg.timestamp,
+    };
+    this.place(
+      queueArg,
+      `resync\0${harnessId ?? ''}`,
+      { event, bytes: Buffer.byteLength(JSON.stringify(event), 'utf8') },
+    );
+  }
+
+  /** Puts an event last under its key, replacing an older one with that key. */
+  private place(queueArg: IViewerQueue, keyArg: string, itemArg: IQueuedControllerEvent): void {
+    const replaced = queueArg.events.get(keyArg);
+    if (replaced) {
+      queueArg.events.delete(keyArg);
+      queueArg.bytes -= replaced.bytes;
+    }
+    queueArg.events.set(keyArg, itemArg);
+    queueArg.bytes += itemArg.bytes;
+  }
+
+  private startSending(queueArg: IViewerQueue): void {
+    if (queueArg.sending || queueArg.events.size === 0) return;
+    const task = this.send(queueArg).finally(() => {
+      if (queueArg.sending === task) queueArg.sending = undefined;
+      if (!queueArg.removed && queueArg.events.size > 0) this.startSending(queueArg);
+    });
+    queueArg.sending = task;
+  }
+
+  private async send(queueArg: IViewerQueue): Promise<void> {
+    while (!queueArg.removed) {
+      const next = queueArg.events.entries().next().value as [string, IQueuedControllerEvent] | undefined;
+      if (!next) return;
+      queueArg.events.delete(next[0]);
+      queueArg.bytes -= next[1].bytes;
+      if (queueArg.tailKey === next[0]) queueArg.tailKey = undefined;
+      if (queueArg.events.size === 0) queueArg.collapsed = false;
+      try {
+        await queueArg.viewer.send(next[1].event);
+      } catch {
+        // As before: a viewer that does not acknowledge in time misses nothing it already received, and a closed
+        // connection leaves the viewer set at the next push.
+      }
+    }
+  }
+}

package/ts/classes.flexmodels.public.ts

@@ -727,6 +727,16 @@ export class FlexPublicHeadModel extends plugins.nosqldb.SmartDataDbDoc<
   name: 'flex_public_session_scope_purge',
   key: { controllerId: 1, scopeId: 1, id: 1 },
 })
+/**
+ * One session's records in a scope: a reader finds the record a publication lists for a session
+ * among that session's versions, never among every session's records. Created by the startup
+ * init of the models (`initFlexPublicModels`, the projection reader's `init`), outside any
+ * transaction. An older AGL leaves the index it does not declare alone.
+ */
+@plugins.nosqldb.compoundIndex({
+  name: 'flex_public_session_lookup',
+  key: { controllerId: 1, scopeId: 1, 'session.sessionId': 1 },
+})
 @plugins.nosqldb.managed({ collectionName: flexPublicSessionsCollectionName })
 export class FlexPublicSessionRecordModel extends plugins.nosqldb.SmartDataDbDoc<
   FlexPublicSessionRecordModel,

package/ts/classes.flexprojectionreader.ts

@@ -414,9 +414,7 @@ export class FlexProjectionReader {
     signalArg?: AbortSignal,
   ): Promise<TFlexSession> {
     const selection = await this.selectCandidate(scopeIdArg, undefined, signalArg);
-    const records = await this.loadSessionRecords(selection, signalArg);
-    const record = records.find((entry) => entry.session.sessionId === sessionIdArg);
-    if (!record) throw new FlexProjectionNotFoundError();
+    const record = await this.loadSessionRecord(selection, sessionIdArg, signalArg);
     return JSON.parse(JSON.stringify(record.session)) as TFlexSession;
   }
 
@@ -627,6 +625,35 @@ export class FlexProjectionReader {
     }).sort(compareNewestSession);
   }
 
+  /**
+   * The record the selected publication lists for one session: looked up through the session
+   * index among the records the publication lists, so it reads that session's records only, and
+   * proven against its manifest.
+   */
+  private async loadSessionRecord(
+    selectionArg: IFlexCandidateSelection,
+    sessionIdArg: string,
+    signalArg?: AbortSignal,
+  ): Promise<IFlexPublicSessionRecordDocument> {
+    const sessionRecords = selectionArg.manifest.sessionRecords;
+    const models = await this.models.publicSessions.getOffsetPage({
+      controllerId: this.controllerId,
+      scopeId: selectionArg.head.storageKey,
+      'session.sessionId': sessionIdArg,
+      id: { $in: sessionRecords.map((record) => record.id) },
+    }, this.pageOptions(2, signalArg));
+    // A publication lists one record per session.
+    if (models.length > 1) throw new FlexProjectionFormatError();
+    const [model] = models;
+    if (!model) throw new FlexProjectionNotFoundError();
+    const document = projectSessionRecord(model);
+    assertFlexPublicSessionRecordDocument(document);
+    const manifest = sessionRecords.find((record) => record.id === document.id);
+    if (!manifest || document.session.sessionId !== sessionIdArg) throw new FlexProjectionFormatError();
+    verifyRecordManifest(document, manifest);
+    return document;
+  }
+
   /**
    * The transcript the selected publication names for a session, proven by its id; a session
    * without messages has none.

package/ts/classes.flexservice.ts

@@ -73,7 +73,7 @@ import {
   readOnlyFlexRequestMethods,
   type IFlexDriverResolution,
 } from './interfaces.flexipc.js';
-import { composeDriverSystem, driverToolDefinitions } from './driver/functions.drivertools.js';
+import { driverNotesContext, driverToolDefinitions } from './driver/functions.drivertools.js';
 import { flexClaudePoolConnectionId, parseFlexAuthorityConnectionId } from '../ts_interfaces/functions.authorityscope.js';
 import { createFailureReference, describeFailure } from './functions.failuredescription.js';
 import { resolveConfiguredFlexMcpServers } from './configuration/functions.flexmcp.js';
@@ -92,6 +92,13 @@ type TFlexAuthorityAccessTarget = { scopeId: string } | { purpose: TFlexInstalla
 type TFlexDelegatedRunAdmissionProviderContext =
   plugins.flexharness.IFlexDelegatedRunAdmissionContext<IFlexProjectScope>;
 
+/**
+ * The driver's cache setting on Anthropic: one-hour breakpoints. The controller keeps the driver's cache warm for an
+ * hour after its board last changed (`fleet.driver.keepCacheWarm`), and FlexHarness times its warm turns by the TTL a
+ * call wrote, so an idle hour costs one warm turn instead of one every four minutes. Other providers keep their
+ * default: the ChatGPT backend caches in memory and takes no retention.
+ */
+const flexDriverAnthropicCache: plugins.flexharness.TFlexAgentCacheSetting = { retention: '1h' };
 const flexFailureStatusTimeoutMs = 1_000;
 
 export const flexHarnessTimeoutPolicy = Object.freeze({
@@ -359,6 +366,7 @@ const projectSerializedMethods: ReadonlySet<TFlexRequestMethod> = new Set([
   'session.reversion.info',
   'slash.list',
   'message.page',
+  'message.metadata.page',
   'message.get',
   'prompt.start',
   'prompt.continue',
@@ -403,6 +411,7 @@ const projectScopedMethods: ReadonlySet<TFlexRequestMethod> = new Set([
   'slash.list',
   'slash.execute',
   'message.page',
+  'message.metadata.page',
   'message.get',
   'prompt.start',
   'prompt.continue',
@@ -1403,6 +1412,16 @@ export class FlexService {
           }),
         };
       }
+      case 'message.metadata.page': {
+        const payload = payloadArg as IFlexRequestMap['message.metadata.page']['request'];
+        return {
+          result: await harness.listMessageMetadataPage(payload.scopeId, payload.sessionId, {
+            ...(payload.limit !== undefined ? { limit: payload.limit } : {}),
+            ...(payload.before !== undefined ? { before: payload.before } : {}),
+            ...(payload.includeUndone === undefined ? {} : { includeUndone: payload.includeUndone }),
+          }),
+        };
+      }
       case 'message.get': {
         const payload = payloadArg as IFlexRequestMap['message.get']['request'];
         return {
@@ -2340,11 +2359,18 @@ export class FlexService {
   private async resolveConfiguredRunModel(
     contextArg: Readonly<plugins.flexharness.IFlexModelResolverContext<IFlexProjectScope>>,
   ): Promise<TFlexResolvedModel> {
-    const resolved = await this.resolveModel(
+    const model = await this.resolveModel(
       contextArg.scopeId, contextArg.signal, contextArg.modelHint, contextArg, contextArg.sessionId,
     );
     const driver = await this.resolveDriver(contextArg);
-    const driverSystem = driver ? composeDriverSystem(driver.instructions, driver.notes) : undefined;
+    // The driver's system prompt holds its stable instructions only; its notes are a pinned
+    // context, so a notes update never rewrites the cached prefix.
+    const resolved: TFlexResolvedModel = driver ? {
+      ...model,
+      ...(model.identity.provider === 'anthropic' ? { cache: flexDriverAnthropicCache } : {}),
+      pinnedContext: driverNotesContext(driver.notes, driver.notesRevision),
+    } : model;
+    const driverSystem = driver?.instructions.trim();
     const key = this.configurationSessionKey(contextArg);
     const projection = this.configuredSessions.get(key);
     if (!projection) {
@@ -2363,7 +2389,8 @@ export class FlexService {
 
   /**
    * The controller says whether a root run belongs to the host's driver session, with the driver's
-   * instructions and notes. A run reads them once, so its system prompt stays stable while it runs.
+   * instructions and its notes with their scratchpad revision. A run reads them once, so its system
+   * prompt and pinned notes stay stable while it runs.
    */
   private resolveDriver(contextArg: Readonly<{
     scopeId: string;
@@ -4114,7 +4141,8 @@ export class FlexService {
         baseTextUtf8Bytes: eventArg.baseTextUtf8Bytes,
         textUtf8Bytes: eventArg.textUtf8Bytes,
       });
-      this.queueSessionChange(eventArg.scopeId, eventArg.sessionId, eventArg);
+      // Content progress travels only as the delta: the part's start and completion, and the
+      // run's lifecycle, carry the session change (updated time, preview, status).
       return;
     }
     if (