@animalabs/agent-framework 0.23.1 → 0.24.0

package/README.md

@@ -181,15 +181,24 @@ agent-framework-recover \
 
 The specified Discord message is the last message the agent will still see;
 everything after it is left on the old branch. The command scans in bounded
-windows, never compiles message content, activates
-the new Chronicle branch, and writes only Discord `{serverId, channelId,
-messageId}` metadata to
-`<store>/recovery/discord-awareness-outbox.json`. When the host and that
-agent's `discord-mcpl` bot reconnect, each addressable discarded message is
-marked with 💤. Delivery state is recorded per message: retryable failures
-remain queued, permanent deleted/inaccessible-message failures remain in the
-audit ledger without blocking later markers. Portal and other non-Discord
-records are ignored.
+windows, never compiles message content, and activates the new Chronicle
+branch. By default the recovery is local to the resident: nothing is posted to
+Discord. To let the people involved see that the agent no longer has their
+messages, choose awareness marks explicitly with `--marks addressed` (removed
+messages that mentioned or replied to the bot, and DMs) or `--marks all`
+(every removed Discord message). The output counts what will be marked and
+what stays unmarked, and `--dry-run` shows exactly which addresses each choice
+covers. Only `{serverId, channelId, messageId}` metadata is written, to the
+awareness ledger, `<store>/recovery/discord-awareness-outbox.json`, and the
+marks are delivered when the host and that agent's `discord-mcpl` bot next
+connect (see
+[Live surgery and Discord awareness marks](#live-surgery-and-discord-awareness-marks)).
+If the branch is made but the marks can't be recorded, the output's `markers`
+says so and the branch stands. The live controls described below list, cancel
+and retract marks; with the host stopped there are none, so a chosen batch is
+stopped by starting the host and cancelling it, and a few of its marks may go
+out first.
+Portal and other non-Discord records are ignored.
 
 When the safe point is an assistant/tool-side record rather than a Discord
 message, use its exact ContextManager message ID:
@@ -222,7 +231,7 @@ agent-framework-recover \
 `--suppress-range <first>..<last>` suppresses the inclusive context interval
 between two Discord messages, including intervening agent/tool entries. These
 removals exist only on the recovery branch; the source branch remains intact.
-Suppressed Discord messages are queued for the same 💤 awareness marker.
+Suppressed Discord messages follow the same `--marks` choice.
 Selections that split a sharded body group or a tool-use/tool-result exchange
 are rejected. The suppression plan is journaled before the branch switch; if
 the recovery process is interrupted between interval removals, framework
@@ -232,22 +241,7 @@ For old stores whose messages lack `metadata.serverId`, supply
 normal agent host must be stopped while this command has the Chronicle store
 open.
 
-The marker sidecar is a retained operation ledger, not a delete-on-success
-queue. Switching back to the source branch queues removal of the bot's marker;
-returning to the recovery branch queues it again. Initial MCPL events remain
-buffered until the ledger has been reconciled. Startup, reconnect, runtime
-list-change, and online undo use one framework-global generation: every MCPL
-data plane waits while the control planes remain live for registration and
-marker service. A connection whose policy exchange is in flight, after a
-connect or a reconnect, keeps both planes closed until the exchange settles,
-since its traffic is admitted against the grant the exchange establishes.
-Awareness marker calls also have a mandatory deadline that is
-independent of `requestTimeoutMs` (including when that value is `0`); configure
-it with `discordAwarenessDeadlineMs` (default 10000ms, clamped to 50..60000ms).
-Configure the online marker with `discordAwarenessEmoji`; the offline CLI
-accepts `--emoji`.
-
-For stdio MCPL children, the framework defaults `DISCORD_SUPPRESSED_REACTIONS_BASELINE` to the reactions it places: its refusal markers, the Discord adapter's default awareness marker, the configured awareness marker, and every retained outbox emoji. This covers later removals and replays after a configuration change. Suppression is by emoji, so members' own reactions with those emoji stop reaching the agent too. The default is derived at each spawn of a child (its first connect, each automatic reconnect, a restart), so the next child spawned gets the markers retained since the last spawn. When the awareness ledger exists but can't be read, a runtime connect reads it first and refuses before anything is registered or spawned (a startup connect, whose routing is staged beforehand, before anything spawns), and a restart refuses before it stops the running child. An automatic reconnect of a child that takes the default fails and retries rather than spawn it without the default. A value with tokens in the server's env (case-insensitive on Windows), or one intentionally inherited with `inheritEnv: true`, takes precedence, and the framework logs that it replaces the default. A value with no tokens, as discord-mcpl's parser reads them, counts as unset, since the adapter would read it as suppression off. The parser splits on commas and keeps a token only when its normalizer leaves something of it, after stripping U+FE0F, trimming, and stripping one leading and one trailing colon: so a blank value, commas alone, `:`, `::` or a lone U+FE0F (say from `${A},${B}` or `:${NAME}:` with the variables empty) has no tokens. The adapter's filters file and legacy operator env still take precedence over this variable, and they are where an operator turns suppression off.
+For stdio MCPL children, the framework defaults `DISCORD_SUPPRESSED_REACTIONS_BASELINE` to the reactions it places: its refusal markers, the Discord adapter's default awareness marker, the configured awareness marker, and every retained outbox emoji. This covers later removals and replays after a configuration change. Suppression is by emoji, so members' own reactions with those emoji stop reaching the agent too. The default is derived at each spawn of a child (its first connect, each automatic reconnect, a restart), so the next child spawned gets the markers retained since the last spawn. The ledger is read once and held, and read from its file again only after a write to it failed. When it can't be read, a runtime connect of a child that takes the default refuses before anything is registered or spawned (a startup connect, whose routing is staged beforehand, before anything spawns), and a restart of one refuses before it stops the running child; a child with a baseline of its own, and a WebSocket server, connect and restart whatever the ledger's state. An automatic reconnect of a child that takes the default fails and retries rather than spawn it without the default. A value with tokens in the server's env (case-insensitive on Windows), or one intentionally inherited with `inheritEnv: true`, takes precedence, and the framework logs that it replaces the default. A value with no tokens, as discord-mcpl's parser reads them, counts as unset, since the adapter would read it as suppression off. The parser splits on commas and keeps a token only when its normalizer leaves something of it, after stripping U+FE0F, trimming, and stripping one leading and one trailing colon: so a blank value, commas alone, `:`, `::` or a lone U+FE0F (say from `${A},${B}` or `:${NAME}:` with the variables empty) has no tokens. The adapter's filters file and legacy operator env still take precedence over this variable, and they are where an operator turns suppression off.
 
 `framework.getPlacedReactionBaseline()` returns a fresh snapshot of that default for other embeddings, including separately managed WebSocket adapters. It returns suppression tokens, with a custom emoji as its bare ID, not marker payloads for adding, removing or replaying a reaction. An unreadable awareness ledger throws instead of producing a partial snapshot. Hosts that previously supplied a refusal-only default must stop supplying it to adopt this framework-derived default; an explicit operator choice should remain intact.
 
@@ -312,7 +306,7 @@ configuration chooses the family, and nothing is probed:
 
 | Configuration | Family | Transport |
 |---|---|---|
-| `url: 'ws://…'` / `'wss://…'` | MCPL (MCP `2024-11-05`) | WebSocket |
+| `url: 'ws://…'` / `'wss://…'` | MCPL (MCP `2024-11-05`) | WebSocket (`token` / `accessProvider` as `?token=`, or as bearer with `tokenTransport: 'header'`) |
 | `url: 'http://…'` / `'https://…'` | modern MCP | Streamable HTTP (`token` / `accessProvider` as bearer) |
 | `command` | MCPL | stdio |
 | `command` + `protocol: 'modern'` | modern MCP | stdio |
@@ -329,6 +323,21 @@ configuration chooses the family, and nothing is probed:
 A configuration with both `command` and `url` needs `transport` to say which
 one is used; without it, it is refused rather than silently ignoring one.
 
+A WebSocket server's credential, its `token` or what its `accessProvider`
+returns for a dial, goes as a `token` query parameter by default
+(`tokenTransport: 'query'`). With `tokenTransport: 'header'` it goes as an
+`Authorization: Bearer` header on the upgrade instead, with no query
+parameter, so it stays out of the url and of the access logs that record it;
+the provider still runs at every dial and reconnect. Switch a server to
+`'header'` once it reads the header. A header carries a credential as
+configured only if it is printable ASCII with no space at either end, so
+header mode refuses any other, without quoting it: a static `token` when the
+server is added, and an access provider's at the dial. `tokenTransport` is
+refused on an http(s):// server, which always sends the header, and on a
+stdio server; `'header'` is refused with a url that carries a `token`
+parameter or userinfo of its own, since whenever the Bearer header carries a
+credential it replaces the userinfo's Basic one.
+
 A modern server's tools get the same prefix, `enabledTools`/`disabledTools`,
 class overrides and dispatch as an MCPL server's, and `listMcplServers()`
 shows its `family`, `protocolVersion` and `transport`. Its config differs in
@@ -368,7 +377,7 @@ revisions the server says it supports ("none listed" for an empty list), or its
 and when the list includes `2026-07-28` it says to configure the server with
 `protocol: 'modern'` (stdio) or reach it over http(s).
 
-Server and transport text the framework records has the server's configured credentials replaced, in both engines. That covers connection traces, console lines, stderr traces, ops alerts, and a tool call's failure as its caller, the model and the `tool:failed` trace get it. The credentials are those the configuration holds and those its dials sent: from the url as each dial sends it (a WebSocket dial sets the token in the query, which writes the whole query again, form-encoded, and an access provider's token can be in it), credential-like path segments and query names, credential-shaped or credential-named query values, and a WebSocket url's userinfo, in their encoded and decoded forms, replaced wherever they occur; every non-empty query parameter as its whole `name=value`, where no letter or digit adjoins it; the static `token`, and each token an access provider handed a dial, the newest sixteen, raw and url-encoded; and a stdio server's `env` values whose names have a part ending in a credential word, such as `GITHUB_TOKEN`, `PGPASSWORD` or `SESSION_COOKIE`, raw and url-encoded. A stdio server's command-line arguments aren't derived. Standalone strings shorter than eight characters stay unchanged because they may be ordinary words; short query values are still removed with their parameter names. Treat a submitted configuration as immutable while the server uses it: apply changes with `restartMcplServer(id, newConfig)`. Secrets neither the configuration holds nor a dial sent remain outside this filtering. JSON-RPC tool answers, and the error a host's own connect raises, pass through as sent.
+Server and transport text the framework records has the server's configured credentials replaced, in both engines. That covers connection traces, console lines, stderr traces, ops alerts, and a tool call's failure as its caller, the model and the `tool:failed` trace get it. The credentials are those the configuration holds and those its dials sent: from the url as each dial sends it (a WebSocket dial sets the token in the query, which writes the whole query again, form-encoded, and an access provider's token can be in it; with `tokenTransport: 'header'` it sets none), credential-like path segments and query names, credential-shaped or credential-named query values, and a WebSocket url's userinfo, in their encoded and decoded forms, replaced wherever they occur; every non-empty query parameter as its whole `name=value`, where no letter or digit adjoins it; the static `token`, and each token an access provider handed a dial, the newest sixteen, raw and url-encoded; and a stdio server's `env` values whose names have a part ending in a credential word, such as `GITHUB_TOKEN`, `PGPASSWORD` or `SESSION_COOKIE`, raw and url-encoded. A stdio server's command and arguments aren't derived. Standalone strings shorter than eight characters stay unchanged because they may be ordinary words; short query values are still removed with their parameter names. Treat a submitted configuration as immutable while the server uses it: apply changes with `restartMcplServer(id, newConfig)`. Secrets neither the configuration holds nor a dial sent remain outside this filtering. A JSON-RPC tool answer's result passes through as sent. No error a host's own call gets, whether thrown, rejected with or in an error answer's data, carries a credential this filtering replaces, whoever wrote its words: a server's words are redacted, then bounded, where an error is built from them, the strings in an error answer's data are redacted, and an error a library raised, such as a failed modern connect's, is handed on as its name and its redacted words alone. A stdio child that couldn't be started is refused with Node's words redacted, stopping before Node's quote of a value it refused at once, and a cause that keeps Node's error's name, those words and its `code`. With a configuration that can't be read, the server's words and data are withheld. A failed handshake's `stderrTail` is the end of the server's stderr, with every credential of up to 14,336 characters that reaches into it replaced whole. A number in an error answer's data is matched as JavaScript reads it, so one with more significant digits than a double holds has lost its last digits before it's matched. A close's or a cleanup's failure carries the transports' own words, a child's pid, its server's id and the wait it was given. A connection's events are inputs to the framework's records, which redact them.
 
 #### Feature sets
 
@@ -393,22 +402,31 @@ The host advertises `eventCoalescing` (both lanes, deferred rendering,
 channel-scoped pushes, a one-hour retry window). A server may add
 `coalesce: { key }` to a `push/event` or a `channels/incoming` message so that a
 later occurrence of the same subject **replaces** the earlier one while it is
-still unread, and **appends** once a model has seen it; `retract: true`
-withdraws unread content and appends the supplied deletion notice only when
-some version was read (or history is unknown). `initial: true` on a create lets
-the host know the subject's history is complete, so a create → edit → delete
-that nobody read leaves no trace. `deferred: true` (push only) holds a batch of
-notices outside context and asks the server for the content with `push/render`
-when a turn is assembled.
+still unread, and **appends** once it has been read (both defined below);
+`retract: true` withdraws unread content and appends the supplied deletion
+notice only when some version was read (or history is unknown). `initial: true`
+on a create lets the host know the subject's history is complete, so a create →
+edit → delete that nobody read leaves no trace. `deferred: true` (push only)
+holds a batch of notices outside context and asks the server for the content
+with `push/render` when a turn is assembled. Each render describes what changed
+since the one before it, so neither a later render nor a notice replaces an
+earlier render the model hasn't read: the newer render lands after it, and a
+retraction or a later plain occurrence withdraws the unread renders, newest
+first.
 
 Plain content stays in context and is delivered on arrival through the ordinary
 channel/push path; the host only remembers where it landed. "Unread" means:
-above the agent's consumed watermark (advanced at every compile of a model
-request), on the current branch, not a sharded message, and not folded into a
-summary by compression. On any doubt — restart, branch switch, eviction — the
-host appends, as it does today. There is no per-subject cap: a busy channel's
-unread backlog is simply its unread backlog. Receipts and subject history are
-kept in the `mcpl/coalescing` state (retry window 1 h); audit lines are
+above the agent's consumed watermark (set when the agent is created, and
+advanced at every compile of a request it sends, which a preview isn't, and at
+a tool boundary that injects messages into a stream declaring it carries them,
+as membrane's native path does from 0.6.0), on the current branch, not a
+sharded message, and not folded into a summary by compression. A message
+injected at a tool boundary whose stream doesn't say whether it carries
+injections, as no membrane 0.5.x stream does, stays unread though the model
+may have seen it. On any doubt — restart, branch switch, eviction — the host
+appends, as it does today. There is no per-subject cap: a busy channel's unread
+backlog is simply its unread backlog. Receipts and subject history are kept in
+the `mcpl/coalescing` state (retry window 1 h); audit lines are
 `mcpl:coalescing` trace events.
 
 #### Per-channel conversation routing (deprecated)
@@ -474,6 +492,158 @@ stated wait with `release-provider-wait` (`agentName`, optional `model`), as
 optional shared secret (`ApiServerConfig.adminToken`, sent as `x-admin-token`)
 for deployments that front the port with a proxy.
 
+### Live surgery and Discord awareness marks
+
+`rollbackToMessage(agent, { messageId })` forks the agent's context at a
+message and switches to the fork; `suppressMessages(agent, { messageIds })`
+forks at the head and removes the chosen messages on the fork. The source
+branch stays intact either way. Removing Discord messages from an agent's
+context is local to that agent unless the operator also chooses to mark them:
+
+```typescript
+const preview = framework.previewSurgeryMarks('cairn', { rollbackTo: messageId });
+// preview.scopes.addressed / .all: count, per-channel counts and refs
+const result = await framework.rollbackToMessage('cairn', {
+  messageId,
+  marks: { scope: 'addressed', refs: preview.scopes.addressed.refs },
+});
+// result.markers: { status: 'none' | 'queued' | 'not-scheduled', ... }
+```
+
+- **`marks`** is `'none'` (the default), or `{ scope: 'addressed' | 'all', refs? }`.
+  `addressed` covers messages tagged `chat:addressed` (mentions, replies to
+  the bot, DMs). Passing a preview's `refs` binds the choice to exactly that
+  set: messages that arrive before the surgery applies are removed locally but
+  never marked. Any other value is refused (`invalid`), never guessed. The
+  choice is recorded in the operator log.
+- **The surgery returns once marks are scheduled**, never after Discord has
+  accepted them. `result.markers` says whether they were scheduled (`queued`
+  with a count and batch id), not chosen or not in scope (`none`), or not to
+  be delivered because recording the batch as active failed after the body
+  change (`not-scheduled`, whose `error` says why, and whether the batch was
+  retired or stays prepared for a start to retire). Every receipt also counts the removed messages left
+  unmarked. Marker bookkeeping never fails or undoes an applied rollback or
+  suppression; a batch that can't be recorded before the body change stops
+  the surgery before anything changes (`failed`).
+- **Delivery runs in the background** and never holds MCPL traffic or turns.
+  MCPL's own hold stays: a connection whose policy exchange is in flight,
+  after a connect or a reconnect, keeps both planes closed until the
+  exchange settles, since its traffic is admitted against the grant the
+  exchange establishes. A route that is not connected keeps its work queued
+  until it connects.
+  Each reaction call has a mandatory deadline independent of
+  `requestTimeoutMs` (including `0`): `discordAwarenessDeadlineMs` (default
+  10000ms, clamped to 50..60000ms). The emoji is `discordAwarenessEmoji`
+  (offline: `--emoji`). Nothing more is sent for a mark after three
+  unconfirmed attempts at it (Discord refused it, or no answer came and so
+  it may have landed, one left on the wire when the host stopped included;
+  an attempt refused before it left the host doesn't count), or after a
+  refusal no retry can change (the message, channel or emoji is gone, access
+  is missing, or the message takes no more reactions); a pass that gives up
+  on marks raises one `discord-awareness-delivery` ops alert, and so does a
+  start whose reconciliation gives up on any. A JSON-RPC error answer, which
+  may come after the server acted, counts as unanswered, unless it is such a
+  refusal. A mark whose request failed in a way a retry could change is sent
+  again by the next delivery pass: after a surgery, a retract, a start, a
+  connect or reconnect of its route, a tools-list change, or an operator's
+  sync, and a trigger that meets a pass already running has that pass try
+  it once more before it ends.
+- **Marks are one-shot.** Switching branches, a turn undo, a redo and
+  restarts never request a mark or a removal of their own: what goes out is what a surgery
+  (the marks chosen for it) or a retract recorded, and a start's delivery
+  sends what of that hasn't gone out. The ledger is a table with one entry
+  per reaction (route, channel, message and emoji): what the acts that still
+  stand want of it, whether Discord is owed a request for that, and what
+  Discord last answered. It is a JSON file outside Chronicle,
+  `<store>/recovery/discord-awareness-outbox.json` (or
+  `discordAwarenessOutboxPath`), so it survives rollbacks, branch deletion
+  and a killed process. Each request is written ahead before it leaves, and
+  the next one is chosen from the ledger as it is then, so a cancel takes
+  effect even while an earlier request is on the wire. A request written and
+  never answered is kept as one that may land, whatever Discord answers
+  later. Between opposite wishes for one reaction, the later act wins: a
+  surgery's marks carry the moment of its choice, even when activation comes
+  later, so a retract made in between prevails, and cancelling it revives
+  nothing. A write goes to a temporary file renamed over the ledger, synced
+  with its directory and that directory's parent, as the framework's own
+  recovery files are: one that fails leaves the ledger as it was, and a
+  directory that can't be synced after the rename raises the `recovery-sync`
+  ops alert while the write stands. A write that activates, completes or
+  retires a batch syncs the store first, so it never outlives the change it
+  certifies. A ledger that can't be read, or holds a version this build
+  doesn't read, stops a start. A running host holds the ledger in memory and
+  reads the file again only after a write failed; while it then can't be
+  read, nothing is sent, the delivery alert says so, and the controls
+  refuse.
+- **A start never activates a surgery's marks.** A batch an interrupted
+  surgery left prepared is retired at the next start, none of its marks
+  sent. One that had marks to apply raises a `discord-awareness-not-scheduled` ops alert that names the
+  surgery, its agent and its branches, and the redo that applies the marks:
+  run the surgery again from the source onto a new branch name, choosing
+  marks again, if the source still has every message the surgery removed (a
+  `hide` there, or the source's deletion, changes that). A batch doesn't say
+  which surgery made it, so the alert names an offline recovery beside a
+  rollback or a suppression. One with none to apply (none chosen, or its marks cancelled) is
+  only logged. An interrupted suppression's removals are still finished, at
+  the first start on its branch, and its batch is retired then. Until then
+  a start on any branch with that name would apply those removals there.
+- **Operator controls,** each that changes the ledger recorded in the
+  operator log (a list or a preview records nothing); once `stop()`
+  has begun, cancel and retract refuse, like every operator entry
+  point:
+  - `listDiscordAwareness()` lists batches and retract requests, each with
+    its reactions counted by state (`queued`, `sending`, `present`,
+    `absent`, `unknown`, `failed` or `untouched`) and how many may still land;
+  - `cancelDiscordAwareness(batch | retractRequest)` stops a batch's marks or
+    a retract's removals from being sent or sent again, and never removes or
+    undoes anything. Its receipt counts what it stopped before any request
+    went out (`cancelled`), what Discord last confirmed as the act wanted
+    (`confirmed`), and the act's reactions with a request on the wire or one
+    never answered, any of which may still land (`mayStillLand`);
+  - `retractDiscordAwareness(batch | 'all')` queues removal of this bot's
+    reaction, through each address's configured MCPL route, for every message
+    of the batch (or of every batch that isn't retired, whether prepared or
+    active, and every reaction the ledger holds), whatever was answered
+    before: removing an absent reaction does nothing. As the latest act on
+    those reactions, it replaces the adds owed there and any an earlier
+    choice would owe later (a prepared batch's activation); cancelling it
+    never revives them. Its receipt counts the reactions on which an add may
+    still land, on the wire or never answered (an unanswered removal can't
+    bring a mark back).
+
+  Both are async. A request the ledger won't carry out (an unknown batch or
+  retract request) is refused as `invalid`; a failure to read or write the
+  ledger is `failed`. A framework with neither `storePath` nor
+  `discordAwarenessOutboxPath` has no ledger: it refuses a marks choice as
+  `invalid`, and so do its controls.
+- **Over `host/command`** (servers granted `allowHostCommands`): an `undo` by
+  messages takes `marks: 'none' | 'addressed' | 'all'` (default `none`; any
+  other value is refused) and returns `markers`. It holds the store like
+  every surgery, so it is refused while any agent sharing the store is
+  mid-turn. `hide` and an `undo` by turns place no marks, and refuse a
+  `marks` choice other than `none`. The `marks` verb takes `action: 'list'
+  | 'cancel' | 'retract'` with a `target` (a batch id; for cancel also a
+  retract request id; for retract also `all`).
+
+The ledger is version 3. A version 2 ledger, agent-framework 0.22.x's at the
+same path, is rewritten as version 3 in place by its first write: at a start,
+or an offline recovery. Each of its batches keeps how many of its messages
+0.22.x's last attempt saw a mark added to (`legacyAdded` in the list), never
+as a claim about what is on Discord. The work 0.22.x had still to do is never
+sent, since nobody chose it: a batch it never activated is retired (a
+suppression whose body may be pending, once a start on its branch finishes
+the body), and pending adds and removals are dropped. A batch it activated
+stays active, its body taken as finished, as 0.22.x took it. The rewrite names
+each batch that had such work, with how many adds and removals, on stderr
+wherever it runs, and in a `discord-awareness-import-unsent` ops alert at the
+host's start that made it. A batch 0.22.x never activated placed no marks; a
+retract of a batch takes off the mark of its emoji from each of its messages,
+whichever batch placed it. 0.22.x reads only versions 1 and 2, and its start
+stops on a version 3 file: to go back to 0.22.x, move the file aside first,
+and 0.22.x then starts with no marks history. A version 1 ledger, which only
+an unreleased commit wrote, is refused until it is moved away, and its error
+says what that gives up.
+
 ## Observability
 
 Subscribe to trace events for logging, UI updates, or debugging:
@@ -517,4 +687,4 @@ npm test           # Run tests
 npm run typecheck  # Type-check without emitting
 ```
 
-Requires Node.js >= 20. Chronicle requires a Rust toolchain for native module compilation (`npm run build` in the chronicle directory).
+Requires Node.js >= 22.12. Chronicle requires a Rust toolchain for native module compilation (`npm run build` in the chronicle directory).

package/dist/src/agent.d.ts

@@ -351,29 +351,80 @@ export declare class Agent {
     /** Settle a converging budget once the window is prepared; true if it settled. */
     private settleRuntimeSettingsTransition;
     /**
-     * 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;
-    /** 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;
+    /**
+     * 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;
     getConsumedWatermark(): {
         branch: string;
         sequence: number;
     } | null;
+    getShownWatermark(): {
+        branch: string;
+        sequence: number;
+    } | null;
     /** 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;
+    /** 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;
+    /** 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;
     /**
      * A finished compile's watermark, taken before it awaited. Within a branch
      * 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;
     /** The watermark a successful compile will establish (taken before, applied after). */

package/dist/src/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/src/agent.js

@@ -794,33 +794,91 @@ export class Agent {
         return true;
     }
     /**
-     * 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.
      */
     consumedWatermark = 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. */
     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.
+     */
+    shownWatermark = null;
     getConsumedWatermark() {
         return this.consumedWatermark;
     }
+    getShownWatermark() {
+        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() {
         // 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() {
+        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. */
+    unshowFailedCompile(watermark, before) {
+        if (watermark && this.shownWatermark === watermark)
+            this.shownWatermark = before;
     }
     /**
      * A finished compile's watermark, taken before it awaited. Within a branch
      * 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).
      */
     applyCompileWatermark(watermark, marksBefore) {
         const current = this.consumedWatermark;
@@ -861,8 +919,18 @@ 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;
+        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;
@@ -899,8 +967,20 @@ 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);
-        const result = budget || opts?.dryRun ? await compile() : await this.compileAtLiveBudget(compile);
+        let result;
+        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;