@animalabs/agent-framework 0.31.0 → 0.33.0

package/src/dendrite/registry.ts

@@ -16,8 +16,11 @@ import type {
   AgentRecord,
   AgentRef,
   AgentSpec,
+  ContextInheritance,
   EndOutcome,
   HeldMail,
+  MessageSlotRef,
+  ObserveEdge,
   RegistrySnapshot,
 } from './types.js';
 
@@ -76,6 +79,123 @@ function clone<T>(value: T): T {
   return value === undefined ? value : (JSON.parse(JSON.stringify(value)) as T);
 }
 
+/** AgentRegistry.register's options (see there). */
+export interface RegisterOptions {
+  resume?: boolean;
+  after?: number;
+  declaredWith?: readonly AgentName[];
+}
+
+/** The residents' shared un-namespaced slot, on the host's current branch. */
+export const RESIDENTS_SLOT: Readonly<MessageSlotRef> = Object.freeze({ namespace: null });
+
+/** Whether two refs name one slot: the same namespace on the same branch. */
+export function sameSlot(a: MessageSlotRef | undefined, b: MessageSlotRef | undefined): boolean {
+  return !!a && !!b && a.namespace === b.namespace && a.branch === b.branch;
+}
+
+/**
+ * The slot an observe edge reads. An edge that names a slot reads that
+ * namespace on the host's current branch. One that names an agent and no
+ * slot reads that agent's own slot, wherever it is (a shared fork's is on its
+ * own branch), as `ownSlotOf` looks it up: undefined where the lookup doesn't
+ * know the agent, or none is given. The registry's `observedSlotOf` passes its
+ * records. An edge that names neither reads the residents' shared slot.
+ */
+export function observedSlot(
+  edge: ObserveEdge,
+  ownSlotOf?: (agent: AgentName) => MessageSlotRef | undefined,
+): MessageSlotRef | undefined {
+  if (edge.slot !== undefined) return { namespace: edge.slot };
+  if (edge.agent === undefined) return { namespace: null };
+  const own = ownSlotOf?.(edge.agent);
+  return own ? { namespace: own.namespace, ...(own.branch !== undefined ? { branch: own.branch } : {}) } : undefined;
+}
+
+/**
+ * The slot a shared derivation's own rows are stored in: the parent's
+ * message slot, as context-manager's derivation record names it, on the
+ * child's own branch. Undefined for any other inheritance, or one whose
+ * record doesn't say.
+ */
+function derivedSlot(inherit: ContextInheritance | undefined): MessageSlotRef | undefined {
+  if (inherit?.mode !== 'shared' || typeof inherit.ownBranch !== 'string') return undefined;
+  const slots = (inherit.derivation as { slots?: { messageNamespace?: unknown } } | undefined)?.slots;
+  const namespace = slots?.messageNamespace;
+  if (namespace !== null && typeof namespace !== 'string') return undefined;
+  return { namespace, branch: inherit.ownBranch };
+}
+
+/**
+ * The own slot a spec or record declares, or, where it declares none (one
+ * written before `ownSlot` existed), the slot it meant: the shared slot for
+ * one that reads that slot with no observe edge on it, which is how a
+ * resident was declared; a shared derivation's slot; else the isolated slot
+ * of its namespace. A subconscious declared its reading of the shared slot
+ * as an observe edge from the start (subconsciousSpec), so it reads as
+ * isolated, as it was opened. An edge on the shared slot here is one with
+ * no `slot`, whatever agent it names: when the flag was all there was, such
+ * an edge read the shared slot, and that is how withOwnSlot restores it, so
+ * a spec reads as the same record does when it is restored.
+ */
+function resolveOwnSlot(declared: {
+  ownSlot?: MessageSlotRef;
+  readsSharedSlot?: boolean;
+  observes?: ObserveEdge[];
+  inherit?: ContextInheritance;
+  namespace?: string;
+}): MessageSlotRef | undefined {
+  const own = declared.ownSlot;
+  if (own) return { namespace: own.namespace, ...(own.branch !== undefined ? { branch: own.branch } : {}) };
+  const derived = derivedSlot(declared.inherit);
+  if (derived) return derived;
+  if (declared.readsSharedSlot === true && !(declared.observes ?? []).some((edge) => edge.slot === undefined)) {
+    return { namespace: null };
+  }
+  return typeof declared.namespace === 'string' ? { namespace: declared.namespace } : undefined;
+}
+
+/** What a record's deprecated `readsSharedSlot` says: it owns the residents' slot or observes it. */
+function readsResidentsSlot(
+  ownSlot: MessageSlotRef | undefined,
+  observes: ObserveEdge[],
+  ownSlotOf: (agent: AgentName) => MessageSlotRef | undefined,
+): boolean {
+  return sameSlot(ownSlot, RESIDENTS_SLOT) || observes.some((edge) => sameSlot(observedSlot(edge, ownSlotOf), RESIDENTS_SLOT));
+}
+
+/**
+ * A restored record with its own slot: one written before `ownSlot` existed
+ * gets the slot its `readsSharedSlot`, observe edges, inheritance and
+ * namespace meant (resolveOwnSlot). Its `readsSharedSlot` is kept as written.
+ *
+ * Its observe edges are read as that code read them too: an edge with no
+ * `slot` read the residents' shared slot, whatever agent it named, so one
+ * naming an agent is restored without the name, an edge on the shared slot
+ * (which names neither), rather than one on that agent's own slot, which is
+ * what such an edge reads since own slots. A host that wants the agent's
+ * slot read declares the edge again (`{ agent }` in a spec now reads it).
+ */
+function withOwnSlot(record: AgentRecord): AgentRecord {
+  if (record.ownSlot !== undefined) return record;
+  const observes = record.relationships?.observes;
+  if (Array.isArray(observes)) {
+    record.relationships.observes = observes.map((edge) => {
+      if (edge.slot !== undefined || edge.agent === undefined) return edge;
+      const { agent: _named, ...onShared } = edge;
+      return onShared;
+    });
+  }
+  const ownSlot = resolveOwnSlot({
+    readsSharedSlot: record.readsSharedSlot,
+    observes: record.relationships?.observes,
+    inherit: record.inherit,
+    namespace: record.namespace,
+  });
+  if (ownSlot) record.ownSlot = ownSlot;
+  return record;
+}
+
 export class AgentRegistry {
   private readonly live = new Map<AgentName, AgentRecord>();
   /** Ended records, oldest first. */
@@ -128,19 +248,25 @@ export class AgentRegistry {
    * spawner's orphan, as if it had been live when the spawner ended.
    * `after` is the incarnation a resumption continues from: the new one is
    * past it, since the counter of a name that aged out of memory isn't kept.
+   * `declaredWith` names the agents declared with this one, such as a
+   * configuration's residents, which register one after another: an observe
+   * edge may name one of them before it is registered (two residents may
+   * observe each other). The edge reads that agent's slot once it is.
    */
-  register(spec: AgentSpec, options: { resume?: boolean; after?: number } = {}): AgentRecord {
+  register(spec: AgentSpec, options: RegisterOptions = {}): AgentRecord {
     return this.requested(() => this.registerUnguarded(spec, options));
   }
 
-  private registerUnguarded(spec: AgentSpec, options: { resume?: boolean; after?: number } = {}): AgentRecord {
-    this.validate(spec, options.resume === true);
+  private registerUnguarded(spec: AgentSpec, options: RegisterOptions = {}): AgentRecord {
+    this.validate(spec, options.resume === true, options.declaredWith ?? []);
     const previous = this.awaiting.get(spec.name);
     this.awaiting.delete(spec.name);
 
     const incarnation = Math.max(this.incarnations.get(spec.name) ?? 0, options.after ?? 0) + 1;
     this.incarnations.set(spec.name, incarnation);
 
+    const observes = (spec.observes ?? []).map((edge) => ({ ...edge }));
+    const ownSlot = resolveOwnSlot({ ...spec, observes });
     const record: AgentRecord = {
       name: spec.name,
       kind: spec.kind,
@@ -152,7 +278,7 @@ export class AgentRegistry {
       onParentEnd: spec.onParentEnd ?? 'orphan',
       relationships: {
         ...(spec.spawnedBy ? { spawnedBy: spec.spawnedBy } : {}),
-        observes: (spec.observes ?? []).map((edge) => ({ ...edge })),
+        observes,
         // Explicit message paths accumulate over an identity's life.
         messagePeers: previous ? [...previous.relationships.messagePeers] : [],
         ...(spec.resultTo ? { resultTo: { ...spec.resultTo } } : {}),
@@ -161,7 +287,10 @@ export class AgentRegistry {
       ...(spec.selfParticipants?.length ? { selfParticipants: [...spec.selfParticipants] } : {}),
       ...(spec.presentAs ? { presentAs: spec.presentAs } : {}),
       ...(spec.homeChannel ? { homeChannel: { serverId: spec.homeChannel.serverId, channelId: spec.homeChannel.channelId } } : {}),
-      readsSharedSlot: spec.readsSharedSlot ?? false,
+      ...(ownSlot ? { ownSlot } : {}),
+      // Kept for readers of the record from before the split: derived from
+      // it, and again as agents register (refreshReadsSharedSlot).
+      readsSharedSlot: readsResidentsSlot(ownSlot, observes, (name) => this.recordedSlotOf(name)),
       ...(spec.namespace ? { namespace: spec.namespace } : {}),
       ...(spec.metadata ? { metadata: clone(spec.metadata) } : {}),
       createdAt: previous?.createdAt ?? this.now(),
@@ -181,11 +310,22 @@ export class AgentRegistry {
       };
     }
     this.live.set(spec.name, record);
+    // The deprecated flag of each live record, the new one's included, as
+    // the slots it names read now: an edge on an agent declared with it
+    // (declaredWith) reads that agent's slot only once it is registered.
+    this.refreshReadsSharedSlot();
     this.persist();
     return record;
   }
 
-  private validate(spec: AgentSpec, resume = false): void {
+  /** Each live record's deprecated `readsSharedSlot`, derived again from its own slot and edges (readsResidentsSlot). */
+  private refreshReadsSharedSlot(): void {
+    for (const record of this.live.values()) {
+      record.readsSharedSlot = readsResidentsSlot(record.ownSlot, record.relationships.observes, (name) => this.recordedSlotOf(name));
+    }
+  }
+
+  private validate(spec: AgentSpec, resume = false, declaredWith: readonly AgentName[] = []): void {
     const fail = (problem: string): never => {
       throw new AgentSpecError(spec.name || '(unnamed)', problem);
     };
@@ -233,7 +373,7 @@ export class AgentRegistry {
       fail(`context source "${spec.inherit.from}" is not a registered agent`);
     }
     for (const edge of spec.observes ?? []) {
-      if (edge.agent !== undefined && !this.live.has(edge.agent)) {
+      if (edge.agent !== undefined && !this.live.has(edge.agent) && !declaredWith.includes(edge.agent)) {
         fail(`observed agent "${edge.agent}" is not a registered agent`);
       }
     }
@@ -265,7 +405,9 @@ export class AgentRegistry {
     for (const { ended } of this.interruptedPending.values()) {
       if (ended.name === name && (!newest || ended.incarnation > newest.incarnation)) newest = ended;
     }
-    return newest ?? this.findEnded?.(name);
+    if (newest) return newest;
+    const logged = this.findEnded?.(name);
+    return logged && withOwnSlot(clone(logged));
   }
 
   /** Flat list of agents — the discovery surface. Ended ones on request. */
@@ -322,15 +464,65 @@ export class AgentRegistry {
     return this.live.get(name)?.roles.ownsProviderScheduling === true;
   }
 
-  /** Agents reading the residents' shared message slot. */
+  /**
+   * Agents reading the residents' shared message slot.
+   *
+   * @deprecated Use `readersOf(RESIDENTS_SLOT)`, or `slotOwners` and
+   * `observersOf` where owning and observing differ.
+   */
   sharedSlotReaders(): AgentName[] {
     return this.namesWhere((r) => r.readsSharedSlot);
   }
 
+  /** @deprecated Use `ownSlotOf` and `observersOf`. */
   readsSharedSlot(name: AgentName): boolean {
     return this.live.get(name)?.readsSharedSlot === true;
   }
 
+  /** The slot a live agent's own rows are stored in, if it names one. */
+  ownSlotOf(name: AgentName): MessageSlotRef | undefined {
+    const slot = this.live.get(name)?.ownSlot;
+    return slot ? { ...slot } : undefined;
+  }
+
+  /** Live agents whose own rows are stored in `slot`, in registration order. */
+  slotOwners(slot: MessageSlotRef): AgentName[] {
+    return this.namesWhere((r) => sameSlot(r.ownSlot, slot));
+  }
+
+  /**
+   * The slot an observe edge reads (observedSlot): an edge that names an
+   * agent and no slot reads that agent's own slot, as its record names it,
+   * the live one, else the one awaiting re-declaration, else its newest
+   * ended one, so an edge on an agent that ended still reads the slot it
+   * read. Undefined for an agent the registry doesn't know.
+   */
+  observedSlotOf(edge: ObserveEdge): MessageSlotRef | undefined {
+    return observedSlot(edge, (name) => this.recordedSlotOf(name));
+  }
+
+  /**
+   * Live agents that read `slot` through an observe edge, in registration
+   * order. With `held`, only those whose edge shows held (policy-diverted)
+   * traffic.
+   */
+  observersOf(slot: MessageSlotRef, options: { held?: boolean } = {}): AgentName[] {
+    return this.namesWhere((r) => r.relationships.observes.some(
+      (edge) => sameSlot(this.observedSlotOf(edge), slot) && (!options.held || edge.includeHeld === true),
+    ));
+  }
+
+  /** Every live agent that reads `slot`, as its own or through an observe edge, in registration order. */
+  readersOf(slot: MessageSlotRef): AgentName[] {
+    return this.namesWhere((r) => sameSlot(r.ownSlot, slot)
+      || r.relationships.observes.some((edge) => sameSlot(this.observedSlotOf(edge), slot)));
+  }
+
+  /** The own slot an agent's record names: live, else awaiting re-declaration, else its newest ended record. */
+  private recordedSlotOf(name: AgentName): MessageSlotRef | undefined {
+    return (this.live.get(name) ?? this.awaiting.get(name) ?? this.inspect(name))?.ownSlot;
+  }
+
   /** The channel an agent is bound to, if it has one. */
   homeChannel(name: AgentName): AgentRecord['homeChannel'] {
     return this.live.get(name)?.homeChannel;
@@ -598,7 +790,7 @@ export class AgentRegistry {
   restore(snapshot: RegistrySnapshot | null | undefined, endedHistory: AgentRecord[] = []): RestoreOutcome {
     const interrupted: AgentRecord[] = [];
     for (const raw of endedHistory.slice(-this.endedRetention)) {
-      if (raw && typeof raw === 'object' && raw.ended) this.ended.push(clone(raw));
+      if (raw && typeof raw === 'object' && raw.ended) this.ended.push(withOwnSlot(clone(raw)));
     }
     if (!snapshot) return { interrupted };
     if (snapshot.version !== 1) {
@@ -623,7 +815,7 @@ export class AgentRegistry {
     const endedKeys = new Set(this.ended.map((record) => `${record.name}#${record.incarnation}`));
     let dropped = false;
     for (const raw of snapshot.records) {
-      const record = clone(raw);
+      const record = withOwnSlot(clone(raw));
       if (record.ended) continue; // history lives in the ended log
       if (record.lifetime.kind === 'persistent') {
         this.awaiting.set(record.name, record);
@@ -649,12 +841,17 @@ export class AgentRegistry {
    * the newest `endedRetention`. An end whose write fails is reported and
    * stays pending, so the snapshot still lists it and a later settlement (the
    * next boot's) writes it; a failed snapshot write is reported too.
+   * `unsettled` names jobs the host couldn't tell of yet, or whose notices
+   * for the primary it couldn't pass on (by name and incarnation): they stay
+   * pending, as such a failed end does.
    * @internal For the framework's boot, once the interrupted jobs'
    * recipients are told; not a host API.
    */
-  settleInterrupted(): void {
+  settleInterrupted(unsettled: ReadonlyArray<Pick<AgentRecord, 'name' | 'incarnation'>> = []): void {
     if (this.interruptedPending.size === 0) return;
+    const kept = new Set(unsettled.map((record) => `${record.name}#${record.incarnation}`));
     for (const [key, { ended }] of [...this.interruptedPending]) {
+      if (kept.has(key)) continue;
       try {
         this.appendEndedFn?.(clone(ended));
       } catch (error) {

package/src/dendrite/types.ts

@@ -122,14 +122,57 @@ export interface ResultRoute {
   as: 'message' | 'tool-result';
 }
 
-/** Read access to another slot, merged into this agent's view. */
+/**
+ * A message slot: where an agent's rows are stored, or a slot another agent
+ * reads. `namespace` null is the residents' shared un-namespaced slot; a
+ * string is the isolated slot of that namespace. `branch` is set for a
+ * derived agent, whose slot is its parent's slot on a Chronicle branch of
+ * its own; without it the slot is the one on the host's current branch,
+ * where residents and the agents beside them write. Two refs name one slot
+ * when both fields are equal (sameSlot).
+ */
+export interface MessageSlotRef {
+  namespace: string | null;
+  branch?: string;
+}
+
+/**
+ * Read access to a slot that isn't the agent's own, merged into its view:
+ * the relationship a watcher has with the slot it watches (the subconscious
+ * with the residents' slot). The slot read is the one `slot` names, else the
+ * own slot of the agent `agent` names, else the residents' shared slot (the
+ * registry's `observedSlotOf`).
+ */
 export interface ObserveEdge {
-  /** The agent whose slot is read, when the slot belongs to one. */
+  /**
+   * The agent whose slot is read. With no `slot`, the edge reads that
+   * agent's own slot (its `ownSlot`), on whatever branch that slot is, not
+   * the residents' shared slot. Where that slot is the observer's own too (a
+   * resident observing another, AgentConfig.observes), the edge shows the
+   * observer that agent's own rows there, and no other agent's. It must be
+   * registered when the edge is, or declared with it
+   * (AgentRegistry.register's `declaredWith`).
+   */
   agent?: AgentName;
-  /** Message-slot namespace; undefined = the shared un-namespaced slot. */
+  /**
+   * Message-slot namespace, on the host's current branch. Undefined: the
+   * own slot of the agent `agent` names, or the shared un-namespaced slot
+   * when it names none.
+   */
   slot?: string;
-  /** Only messages at or after this sequence. */
+  /**
+   * Only messages at or after this sequence.
+   *
+   * @deprecated A sequence is a coordinate of one branch's record, not of
+   * what an agent was shown; use `fromMessageId`. Nothing reads either yet.
+   */
   fromSequence?: number;
+  /**
+   * Only messages from this one on, by message id, which names one row on
+   * every branch and in every agent's presentation order (#291). Not read
+   * yet: an edge that sets it shows the rows one without it shows.
+   */
+  fromMessageId?: string;
   /** Whether held (policy-diverted) traffic in that slot is visible. */
   includeHeld?: boolean;
 }
@@ -163,7 +206,15 @@ export interface ContextInheritance {
    *   (requires store support; refused when unavailable).
    */
   mode: 'copy' | 'shared';
-  /** The parent checkpoint (sequence on the parent's branch). Filled at creation. */
+  /**
+   * The parent checkpoint: a sequence on the parent's branch. Filled at
+   * creation, from the derived context (its derivation's checkpoint). One a
+   * host sets, for a resume or a derive from an earlier state, is a
+   * presentation boundary (#291), such as `currentSequence()` read after a
+   * presentation into the parent's window, not a row's own sequence: a row
+   * enters the window at a write after its own, so a cut at its own
+   * sequence holds the row in the child's record and not in its window.
+   */
   atSequence?: number;
   /** The parent branch the checkpoint is on. Filled at creation. */
   branch?: string;
@@ -213,9 +264,10 @@ export interface AgentSpec {
   kind: AgentKind;
   /**
    * The model the agent runs on — "whose weights", next to `inherit.from`
-   * for "whose context". Together they are what a consent decision about a
-   * derived agent is made on. Filled by the framework from the agent's
-   * configuration.
+   * for "whose context". Both are on the `dendrite:agent-created` trace and
+   * in the spec a host's `dendrite.beforeDerive` decides on, which the
+   * framework gives no meaning of its own. Filled by the framework from the
+   * agent's configuration.
    */
   model?: string;
   roles: AgentRoles;
@@ -242,9 +294,27 @@ export interface AgentSpec {
    * registry's `ChannelRef`).
    */
   homeChannel?: { serverId: string; channelId: string };
+  /**
+   * The slot this agent's own rows are stored in: the residents' shared
+   * slot for a resident, its own namespace's slot for an isolated agent, the
+   * parent's slot on its own branch for a shared fork. The resident and
+   * subconscious presets set it (the others leave it to the reading below),
+   * and the framework fills it for the agents it derives or creates from
+   * how it opens their context. Absent, the registry reads it as an older
+   * spec meant it: a shared derivation's slot; the shared slot when
+   * `readsSharedSlot` is set and no observe edge without a `slot` explains
+   * it (one naming an agent reads as on the shared slot here);
+   * else the isolated slot of `namespace`. A slot it reads without owning
+   * it is an observe edge (`observes`).
+   */
+  ownSlot?: MessageSlotRef;
   /**
    * Whether the agent reads the residents' shared un-namespaced message
    * slot (as its own slot or through an observe edge).
+   *
+   * @deprecated One flag for two relationships: owning the shared slot and
+   * observing it. Use `ownSlot` and `observes`. Still read for a spec that
+   * sets no `ownSlot` (see there).
    */
   readsSharedSlot?: boolean;
   /** Chronicle namespace owning this agent's context. */
@@ -315,6 +385,20 @@ export interface AgentRecord {
    * as a wake that names a channel without its server is.
    */
   homeChannel?: { serverId: string; channelId: string } | string;
+  /**
+   * The slot the agent's own rows are stored in (see AgentSpec.ownSlot). A
+   * record written before the field existed has it filled at restore from
+   * what the record says. Absent only for an agent whose spec named neither
+   * a slot nor a namespace.
+   */
+  ownSlot?: MessageSlotRef;
+  /**
+   * Whether the agent reads the residents' shared slot, as its own slot or
+   * through an observe edge: derived from `ownSlot` and `relationships.observes`
+   * at each registration of the record (a restored one included), not once.
+   *
+   * @deprecated Use `ownSlot` and `relationships.observes`.
+   */
   readsSharedSlot: boolean;
   namespace?: string;
   metadata?: Record<string, unknown>;

package/src/foreign-rounds.ts

@@ -0,0 +1,199 @@
+/**
+ * Another agent's rounds as an agent that watches its slot is sent them
+ * (#291, answer 13).
+ *
+ * An agent reads another agent's rounds through an observe edge (decision
+ * 1), as the persistent subconscious watches the residents' slot, and an
+ * agent derived or forked from such a watcher inherits them, sent in its
+ * mode. A co-resident's rows stored before audience stamps, which a window
+ * written down from the record keeps, reach an agent that observes no one
+ * too: they go out as stored there, as earlier releases sent them. An agent
+ * sent others' rounds as a transcript is sent those as one, read by their
+ * participant.
+ * Those rounds are stored as the other agent's: its signed thinking, its
+ * tool calls and their results. None of that is valid as the watcher's own.
+ * A provider takes tool blocks only in their own pairing, in the turns of
+ * the agent that made the call, and a thinking block's signature binds it
+ * to the prefix the other agent was sent. Sent raw in a user turn, the
+ * blocks are refused, or moved into the watcher's assistant turns, where
+ * they read as calls the watcher made.
+ *
+ * So by default the watcher is sent them as a transcript, a line per block:
+ * a call as the tool's name and its input in brief, a result as the tool's
+ * name and its outcome in brief, and no thinking at all. Text, images and
+ * the rest go as stored. The signature forbids sending a thinking block as
+ * part of another prefix, not its text: leaving the text out is this
+ * transcript's choice. A host can have the rounds sent as stored instead
+ * (PersistentReaderConfig.foreignRounds `'raw'`, as 0.30.0 sent them). The rule is one function of the stored row, applied the same
+ * way to a compile's messages and to a row a tool boundary injects, so what
+ * the watcher's window holds and what its requests carried stay one thing.
+ *
+ * The watcher's own rows go as stored: its rounds (its own participant's
+ * messages), and the results of its own calls, which are stored under
+ * another participant (`user`) and are told by the call they answer: the
+ * nearest call before the result with its id, since a provider (or a mock)
+ * that numbers calls per response gives two agents' calls the same id.
+ */
+import type { ContentBlock, NormalizedMessage } from '@animalabs/membrane';
+import { NOTICE_TAG } from './notice-tags.js';
+import { cutToFit, markedTexts, oneLine } from './supplied-text.js';
+
+/** How long one transcript line's call or outcome runs before it is cut. */
+const BRIEF_CHARS = 160;
+
+/** A piece of a transcript line's call or outcome, and whether the other
+ *  agent supplied it (a call's input, a result's text) or the framework
+ *  wrote it (a placeholder naming a result block's kind). */
+interface Piece {
+  text: string;
+  supplied: boolean;
+}
+
+/** `text` on one line: each line break the framework counts as one
+ *  (oneLine), and each other run of whitespace, as one space. */
+function flat(text: string): string {
+  return oneLine(text).replace(/\s+/g, ' ').trim();
+}
+
+/** A tool result's content as pieces: its text, and its other blocks named
+ *  by kind, in placeholders that are the framework's own. */
+function resultPieces(content: string | ContentBlock[]): Piece[] {
+  if (typeof content === 'string') return [{ text: content, supplied: true }];
+  return content.map((b) => (b.type === 'text'
+    ? { text: (b as { text: string }).text, supplied: true }
+    : { text: `[${b.type}]`, supplied: false }));
+}
+
+/** A call's input as a piece: its JSON, or what the model sent when that
+ *  wasn't an object. */
+function callPiece(block: Extract<ContentBlock, { type: 'tool_use' }>): Piece {
+  if (block.unparseableInput !== undefined) return { text: block.unparseableInput, supplied: true };
+  try {
+    return { text: JSON.stringify(block.input ?? {}) ?? '', supplied: true };
+  } catch {
+    return { text: '', supplied: true };
+  }
+}
+
+/**
+ * A transcript line: the framework's bracket around the tool's name, which
+ * the other agent's call supplied, the framework's words for what happened
+ * (`words[0]` before a call or outcome, `words[1]` when there is none), and
+ * the call or outcome in brief. What the line holds is supplied text
+ * (#852): set inside the framework's bracket here, where a tool block's own
+ * content isn't, an opening of one of the framework's notices is marked
+ * wherever it forms, read across the whole line (markedTexts): inside a
+ * piece, across a result's blocks, or where the name meets the bracket or
+ * the framework's words. Those words and the placeholders aren't marked.
+ * Each piece goes on one line first (flat), and the call or outcome is cut
+ * to BRIEF_CHARS with an ellipsis, at a whole character, never parting a
+ * mark from its bracket (cutToFit).
+ */
+function transcriptLine(name: string, words: readonly [string, string], body: readonly Piece[]): string {
+  const pieces = body.map((p) => ({ ...p, text: flat(p.text) })).filter((p) => p.text.length > 0);
+  const word = pieces.length > 0 ? words[0] : words[1];
+  const marked = markedTexts(['[', oneLine(name), word, ...pieces.map((p) => p.text)], [true, true, false, ...pieces.map((p) => p.supplied)]);
+  const said = marked.slice(3).join(' ');
+  return `${marked.slice(0, 3).join('')}${said.length > BRIEF_CHARS ? `${cutToFit(said, BRIEF_CHARS - 1)}…` : said}]`;
+}
+
+/** Where a row with nothing left to send stands, so the transcript keeps a row for each stored one. */
+const NOTHING_SAID = `[${NOTICE_TAG.noText}]`;
+
+/**
+ * One stored row of another agent's as the watcher is sent it: thinking
+ * dropped, each call and each result a line of text, a text block's
+ * provider-native item (`rawItem`) dropped with it, everything else as it is.
+ * `ownCalls` are the watcher's own calls, whose results it is sent as they
+ * are; `callNames` names the calls the row's results answer, where the
+ * result doesn't name its tool itself. A row left with nothing says so in
+ * a line, rather than going empty.
+ */
+export function foreignRowAsSent(
+  content: readonly ContentBlock[],
+  context: { ownCalls?: { has(id: string): boolean }; callNames?: { get(id: string): string | undefined } } = {},
+): ContentBlock[] {
+  let changed = false;
+  const out: ContentBlock[] = [];
+  for (const block of content) {
+    switch (block.type) {
+      case 'thinking':
+      case 'redacted_thinking':
+        changed = true;
+        break;
+      case 'tool_use': {
+        changed = true;
+        out.push({ type: 'text', text: transcriptLine(block.name, [' called: ', ' called: '], [callPiece(block)]) });
+        break;
+      }
+      case 'tool_result': {
+        if (context.ownCalls?.has(block.toolUseId)) {
+          out.push(block);
+          break;
+        }
+        changed = true;
+        const name = block.toolName ?? context.callNames?.get(block.toolUseId) ?? 'a tool';
+        const word = block.isError ? ' failed' : ' returned';
+        out.push({ type: 'text', text: transcriptLine(name, [`${word}: `, word], resultPieces(block.content)) });
+        break;
+      }
+      case 'text': {
+        if ((block as { rawItem?: unknown }).rawItem === undefined) {
+          out.push(block);
+          break;
+        }
+        changed = true;
+        if (block.text.length > 0) out.push({ type: 'text', text: block.text });
+        break;
+      }
+      default:
+        out.push(block);
+    }
+  }
+  if (!changed) return content as ContentBlock[];
+  return out.length > 0 ? out : [{ type: 'text', text: NOTHING_SAID }];
+}
+
+/**
+ * A request's messages as an agent that watches another's slot is sent them:
+ * each message whose participant isn't the agent's own (`isOwn`) through
+ * foreignRowAsSent, with the results of the agent's own calls kept, and
+ * each result named by the call it answers. A result answers the nearest
+ * call before it with its id, read in one pass in order, so another
+ * agent's result whose id an own call of the watcher's also has, before or
+ * after it, is still transcribed. A call answers one result: a result after
+ * the one that answered it, in the same message or a later one, names no
+ * call (another agent's, whose call the request doesn't carry), and is
+ * transcribed. A message nothing changes is the same object, and so is the
+ * array when none changes.
+ */
+export function transcribeForeignRounds(
+  messages: readonly NormalizedMessage[],
+  isOwn: (participant: string) => boolean,
+): NormalizedMessage[] {
+  const latest = new Map<string, { own: boolean; name: string }>();
+  // The watcher's own call is answered by the first result read for it,
+  // block by block: that result takes its entry, so a second result for it
+  // in the same message names no call.
+  const ownCalls = {
+    has: (id: string) => {
+      if (latest.get(id)?.own !== true) return false;
+      latest.delete(id);
+      return true;
+    },
+  };
+  const callNames = { get: (id: string) => latest.get(id)?.name };
+  let changed = false;
+  const out = messages.map((m) => {
+    const own = isOwn(m.participant);
+    for (const b of m.content) if (b.type === 'tool_use') latest.set(b.id, { own, name: b.name });
+    const content = own ? m.content : foreignRowAsSent(m.content, { ownCalls, callNames });
+    // A call answers one result: a later result with its id (another
+    // agent's, whose call the request doesn't carry) answers no call here.
+    for (const b of m.content) if (b.type === 'tool_result') latest.delete(b.toolUseId);
+    if (content === m.content) return m;
+    changed = true;
+    return { ...m, content };
+  });
+  return changed ? out : messages as NormalizedMessage[];
+}