@animalabs/agent-framework 0.23.1 → 0.24.0

package/src/tune-out/coordinator.ts

@@ -37,6 +37,37 @@ const WAKE_COALESCE_MS = 2_000;
 /** How long after an end time whose cancel threw the cancel is tried again. */
 const EXPIRY_RETRY_MS = 60_000;
 
+/** Ends a backlog line cut to fit in one of the residents' messages. */
+const CUT_MARK = " [cut to fit; the whole message is in the channel's history]";
+
+/**
+ * tune_out's refusal of a channel already tuned out: its settings, then what
+ * its transport is now where the repeat tried to open it again (`transport`,
+ * from the framework's dispatch), then how to change the settings.
+ */
+export function alreadyTunedOutText(channelId: string, p: TuneOutParams, transport?: string): string {
+  // A duration so long its end is past what a Date can hold has no time to show.
+  const expires = p.expiresAtMs !== undefined ? new Date(p.expiresAtMs) : undefined;
+  const until = expires && Number.isFinite(expires.getTime())
+    ? `, until ${expires.toISOString().replace(/\.\d+Z$/, 'Z')}`
+    : '';
+  // A thrown error's words may end without a stop.
+  const now = transport === undefined ? '' : /[.!?]$/.test(transport) ? `${transport} ` : `${transport}. `;
+  return `Nothing changed${transport !== undefined ? ' in the tune-out' : ''}: ${JSON.stringify(channelId)} is already `
+    + `tuned out, with cadenceSeconds ${p.cadenceSeconds}, backlogCap ${p.backlogCap} and maxWakes ${p.maxWakes}${until}. `
+    + now
+    + 'To change those, cancel it first with tune_out mode "cancel", which delivers its backlog to you now, then call '
+    + 'tune_out again with the new settings.';
+}
+
+/** The first `length` code units of `text`, one fewer where the last would be
+ *  the first half of a surrogate pair. */
+function prefixOf(text: string, length: number): string {
+  const cut = text.slice(0, Math.max(0, length));
+  const last = cut.charCodeAt(cut.length - 1);
+  return last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut;
+}
+
 /** What a thrown value says, without throwing: an Error's message, or the
  *  value as text, which String() can't give for an object with no prototype. */
 function thrownReason(error: unknown): string {
@@ -63,6 +94,20 @@ export interface TuneOutFrameworkHooks {
   primaryName: () => string | null;
   /** Read the primary's stored messages (shared slot, unfiltered). */
   getStoredMessages: () => StoredMessage[];
+  /**
+   * Messages admitted for the primary but not yet in its store (deferred
+   * while a turn was alive), oldest first. A cancel reads them too, so a
+   * message held mid-turn is in the backlog it belongs to (#232 gap 7).
+   */
+  getDeferredMessages?: () => Array<Pick<StoredMessage, 'participant' | 'content' | 'metadata'>>;
+  /**
+   * The most characters of text every reader of the residents' shared slot
+   * is shown whole in one message: the smallest of their strategies'
+   * per-message caps (`maxMessageTokens`) at four characters a token, or
+   * undefined when none has such a cap. A cancel's dump is one message in
+   * that slot, so it holds as many backlog lines as fit.
+   */
+  residentMessageChars?: () => number | undefined;
   /** Current chronicle head sequence (window anchor for new epochs). */
   currentSequence: () => number;
   /** Move the subconscious window anchor (never forward past active epochs). */
@@ -178,7 +223,7 @@ export class TuneOutCoordinator {
     channelId: string,
     opts: { cadenceSeconds?: number; backlogCap?: number; maxWakes?: number; durationSeconds?: number },
     source: string,
-  ): { ok: true; params: TuneOutParams } | { ok: false; error: string } {
+  ): { ok: true; params: TuneOutParams } | { ok: false; error: string; alreadyTunedOut?: true } {
     if (!this.hooks.subconsciousName()) {
       return {
         ok: false,
@@ -197,21 +242,7 @@ export class TuneOutCoordinator {
       };
     }
     const current = this.channelRegistry.getTuneOutState(serverId, channelId);
-    if (current) {
-      const p = current.params;
-      // A duration so long its end is past what a Date can hold has no time to show.
-      const expires = p.expiresAtMs !== undefined ? new Date(p.expiresAtMs) : undefined;
-      const until = expires && Number.isFinite(expires.getTime())
-        ? `, until ${expires.toISOString().replace(/\.\d+Z$/, 'Z')}`
-        : '';
-      return {
-        ok: false,
-        error: `Nothing changed: ${JSON.stringify(channelId)} is already tuned out, with cadenceSeconds `
-          + `${p.cadenceSeconds}, backlogCap ${p.backlogCap} and maxWakes ${p.maxWakes}${until}. To change those, `
-          + 'cancel it first with tune_out mode "cancel", which delivers its backlog to you now, then call tune_out '
-          + 'again with the new settings.',
-      };
-    }
+    if (current) return { ok: false, error: alreadyTunedOutText(channelId, current.params), alreadyTunedOut: true };
     // A tool's input reaches here as the model wrote it, and the store can't
     // keep a NaN or an Infinity: its append would throw after the registry
     // had marked the channel tuned out. So each option is read as a number
@@ -302,35 +333,106 @@ export class TuneOutCoordinator {
     this.clearTimers(serverId, channelId);
     this.divertedSinceInvocation.delete(this.key(serverId, channelId));
 
-    // Backlog: every message stamped with this epoch, oldest first.
+    // Backlog: every message held under this epoch. The stored ones come in
+    // store order, then those still in the deferred queue (held mid-turn,
+    // not yet written), oldest first. That's arrival order, except when a
+    // held message stays queued while a later one is stored: a store write
+    // refused at a turn-start flush leaves it queued, and that turn's
+    // assembly can then store later coalesced messages directly.
     const epochId = ended.params.epochId;
-    const backlog = this.hooks.getStoredMessages().filter(
-      (m) => (m.metadata as { tuneOut?: { epochId?: string } } | undefined)?.tuneOut?.epochId === epochId,
-    );
-    const cap = ended.params.backlogCap;
-    const shown = cap > 0 ? backlog.slice(-cap) : [];
-    const truncated = backlog.length - shown.length;
-
-    const lines = shown.map((m) => {
-      const author = (m.metadata as { author?: { name?: string } } | undefined)?.author?.name ?? m.participant;
+    const ofEpoch = (m: Pick<StoredMessage, 'metadata'>): boolean =>
+      (m.metadata as { tuneOut?: { epochId?: string } } | undefined)?.tuneOut?.epochId === epochId;
+    const held = (this.hooks.getDeferredMessages?.() ?? []).filter(ofEpoch);
+    const backlog: Array<Pick<StoredMessage, 'participant' | 'content' | 'metadata'>> = [
+      ...this.hooks.getStoredMessages().filter(ofEpoch),
+      ...held,
+    ];
+    // Whole messages: a cap below one shows none, where slice(-0.5) would
+    // start at 0 and take them all.
+    const cap = Math.floor(ended.params.backlogCap);
+    const authorOf = (m: Pick<StoredMessage, 'participant' | 'metadata'>): string =>
+      (m.metadata as { author?: { name?: string } } | undefined)?.author?.name ?? m.participant;
+    const lineOf = (m: Pick<StoredMessage, 'participant' | 'content' | 'metadata'>): string => {
       const text = m.content
         .filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text')
         .map((b) => b.text)
         .join('\n');
-      return `${author}: ${text}`;
-    });
-    const attrs = [
-      `channel="${channelId}"`,
-      `messages=${backlog.length}`,
-      ...(truncated > 0 ? [`truncated=${truncated} (oldest; fetch_history covers the rest)`] : []),
+      return `${authorOf(m)}: ${text}`;
+    };
+    const lifecycle = `[Tune-out: ${channelId} cancelled — ${reason}, ${ended.wakeCount} wake${ended.wakeCount === 1 ? '' : 's'}]`;
+    const render = (lines: string[], truncated: number): string => {
+      const attrs = [
+        `channel="${channelId}"`,
+        `messages=${backlog.length}`,
+        ...(truncated > 0 ? [`truncated=${truncated} (oldest; fetch_history covers the rest)`] : []),
+      ];
+      return `${lifecycle}\n\n<tuned-out-backlog ${attrs.join(' ')}>\n${lines.join('\n')}\n</tuned-out-backlog>`;
+    };
+
+    // The dump is one message in the residents' shared slot, so each
+    // resident's strategy cuts it as it cuts any message past its per-message
+    // cap: context-manager's AutobiographicalStrategy (which connectome-host's
+    // FrontdeskStrategy extends) and WindowedPassthroughStrategy count a text
+    // block at a token per four characters, rounded up, and keep a message's
+    // first cap × 4 characters. Cut there, the dump would lose its newest
+    // lines, which would still count as shown. So it holds the newest lines
+    // that fit whole in the smallest such room, and those it leaves out, the
+    // oldest, count as truncated along with those above backlogCap, so the
+    // report is told of them. A newest message too long to fit alone is shown
+    // cut to the room left and marked, so the residents still get its head,
+    // as they would from a row of its own. When no line fits, whole or cut,
+    // the dump shows none; if the room is too small for even that, the
+    // residents' strategies cut its frame, the header and tags.
+    let shown = cap > 0 ? backlog.slice(-cap) : [];
+    let lines = shown.map(lineOf);
+    let newestCut = false;
+    const room = this.hooks.residentMessageChars?.();
+    if (room !== undefined && render(lines, backlog.length - shown.length).length > room) {
+      // The dump's length with no line, for the count that showing k lines
+      // leaves out: truncated= takes that count's digits, and goes at 0. With
+      // the newest k lines whole, the dump is that and the lines, with a
+      // newline between each two. While a message is left out, each line kept
+      // makes it longer, and they don't all fit, so the fit keeps lines from
+      // the newest while the next one fits.
+      const frameShowing = (k: number): number => render([], backlog.length - k).length;
+      let used = 0;
+      let kept = 0;
+      while (kept < lines.length) {
+        const next = used + lines[lines.length - 1 - kept]!.length + (kept > 0 ? 1 : 0);
+        if (frameShowing(kept + 1) + next > room) break;
+        used = next;
+        kept++;
+      }
+      // What of the newest line's text fits beside the frame and the mark. A
+      // cut shows some of it or none: a room under one character, or one
+      // that would split a surrogate pair, leaves the head empty.
+      const head = prefixOf(lines.at(-1) ?? '', room - frameShowing(1) - CUT_MARK.length);
+      if (kept === 0 && head !== '') {
+        lines = [head + CUT_MARK];
+        shown = shown.slice(-1);
+        newestCut = true;
+      } else {
+        lines = lines.slice(lines.length - kept);
+        shown = shown.slice(shown.length - kept);
+      }
+    }
+    const truncated = backlog.length - shown.length;
+    // The held messages the dump leaves out, the oldest of them. The
+    // subconscious's report covers what the dump leaves out, but its view
+    // holds stored rows only, so these go to it with its notice below. So does
+    // a held message the dump shows but can't give whole: one whose image or
+    // audio its text lines drop, or the newest, cut to fit.
+    const heldLeftOut = held.slice(0, Math.max(0, held.length - shown.length));
+    const heldForReport = [
+      ...heldLeftOut,
+      ...held.slice(heldLeftOut.length).filter((m) =>
+        m.content.some((b) => b.type !== 'text') || (newestCut && m === shown[0])),
     ];
-    const dump =
-      `<tuned-out-backlog ${attrs.join(' ')}>\n${lines.join('\n')}\n</tuned-out-backlog>`;
 
     // Host-framed system artifacts — never voiced as anyone.
     this.hooks.addMessage(
       'user',
-      [{ type: 'text', text: `[Tune-out: ${channelId} cancelled — ${reason}, ${ended.wakeCount} wake${ended.wakeCount === 1 ? '' : 's'}]\n\n${dump}` }],
+      [{ type: 'text', text: render(lines, truncated) }],
       { system: true, kind: 'tune-out-cancel', channelId, epochId },
     );
     // The subconscious's own words, under its own name, verbatim.
@@ -346,20 +448,39 @@ export class TuneOutCoordinator {
     if (primary) {
       this.hooks.requestInference(primary, `tune-out cancelled (${reason})`, 'tune-out');
     }
-    // The subconscious gets one cancel turn of its own (unless it initiated
-    // the cancel — its note already carries its words): the issue's cancel
-    // shape is dump + a report from the subconscious, and when the cap
-    // truncated the raw dump, its summary is what covers the tail.
-    if (source !== 'subconscious' && subName) {
+    // The subconscious gets one cancel turn of its own: the issue's cancel
+    // shape is dump + a report from the subconscious, and when the dump left
+    // messages out, its summary is what covers them. The held messages the
+    // dump can't give the resident whole follow the notice, each a row of its
+    // own with its own content, as its view can't have them until they're
+    // stored. A cancel the subconscious makes itself gets the notice and the
+    // turn when some do, since it wrote its note before it could see them,
+    // and when it wrote no note and the dump left any message out, since
+    // nothing else then covers it. Otherwise its note speaks for what it saw.
+    const selfCancel = source === 'subconscious';
+    if (subName && (!selfCancel || heldForReport.length > 0 || (!subconsciousNote && truncated > 0))) {
       const truncNote = truncated > 0
-        ? ` ${truncated} of ${backlog.length} diverted messages were above the cap and not delivered raw.`
+        ? ` ${truncated} of ${backlog.length} diverted messages, the oldest, weren't delivered raw to the resident.`
+        : '';
+      const heldNote = heldForReport.length > 0
+        ? ` Still held at the cancel, so your view may not have them yet: the ${heldForReport.length} message${heldForReport.length === 1 ? '' : 's'} after this one.`
         : '';
       this.hooks.addMessage(
         'user',
-        [{ type: 'text', text: `[Tune-out cancelled: ${channelId} — ${reason}.${truncNote}]` }],
+        [{ type: 'text', text: `[Tune-out cancelled: ${channelId} — ${reason}.${truncNote}${heldNote}]` }],
         { system: true, kind: 'tune-out-cancel-report', channelId },
         subName,
       );
+      // Each held message is a row of its own, so a per-message cap cuts each
+      // one on its own, its author's label included, not the batch's newest.
+      for (const m of heldForReport) {
+        this.hooks.addMessage(
+          'user',
+          [{ type: 'text', text: `${authorOf(m)}:` }, ...m.content],
+          { system: true, kind: 'tune-out-cancel-held', channelId },
+          subName,
+        );
+      }
       this.hooks.requestInference(subName, `tune-out cancelled: ${channelId}`, 'tune-out');
     }
     this.hooks.emitTrace({ type: 'tune-out:cancelled', serverId, channelId, epochId, reason, wakeCount: ended.wakeCount });

package/src/types/agent.ts

@@ -371,6 +371,10 @@ export interface InferenceRequest {
    *  all of them without materializing content, the turn has no cause left
    *  and does not run. */
   coalescingBatchSubjects?: string[];
+  /** Host-owned: this wake's sole cause is reading this deferred write, a
+   *  coalesced render placed in its agent's queue (wakeToRead). Once the
+   *  agent has read the write, or it was removed, the wake starts no turn. */
+  readsDeferredWrite?: string;
   agentName: string;
   reason: string;
   source: string;

package/src/types/events.ts

@@ -193,11 +193,32 @@ export interface ToolResult {
   /** Whether this was an error (for LLM) */
   isError?: boolean;
   /**
-   * An MCP tool's `structuredContent`: its machine-readable result, beside
-   * `data`, which is the content view. Present exactly when the server sent
-   * one, so `false`, `0` and `null` are values here, not absence. Programs
-   * read it (scripts get it in their result object); the model sees content,
-   * and sees this rendered as JSON only when the content carries no text.
+   * The dispatcher refused the call before it opened, RFC-007's refusal, so
+   * nothing ran and the call certainly had no effect. Only the dispatcher's
+   * path, the model's calls and a script's, sets it: the caller may not use
+   * the tool (allowedTools), a `skip_reply` wake was refused, the call's MCPL
+   * server is absent or still connecting, the host's policy for that server
+   * denies the tool, or a fork reached outside its channel. RFC-007's
+   * lifecycle refuses the call from the same place, so observers see no
+   * events for it. A check made after the call opened, such as a module's
+   * answer for a name it has no tool for or arguments that don't fit a
+   * schema, is a failure whose text says nothing was done, as is an MCPL
+   * request that couldn't be written. A programmatic call (`executeToolCall`,
+   * `ModuleContext.callTool`) opens no RFC-007 call, so it's never refused:
+   * the allowedTools check answers it with a failure saying the call didn't
+   * run, and the other checks it gets, such as the module registry's, answer
+   * as they do once a call has opened. A module's result never carries it. A script's call refused so reaches the script as an
+   * Error, where any other failure is a result with `isError`.
+   */
+  refused?: boolean;
+  /**
+   * The result's machine-readable form, beside `data`. Programs read it: a
+   * script gets it in its result object, and a host in the tool result
+   * event. The model never reads this field: it sees the value only where an
+   * MCP conversion put it in the content as JSON, which happens only when the
+   * server sent no text. An MCP tool's is its `structuredContent`, present
+   * exactly when the server sent one, so `false`, `0` and `null` are values
+   * here, not absence. Any other tool can set one too.
    */
   structured?: unknown;
   /**
@@ -237,15 +258,47 @@ export interface ToolCall {
    * The turn the call was made in, the same id as that turn's
    * `SpeechContext.turnId`. Set by the framework dispatch layer, beside
    * `callerAgentName`: a model's call carries the turn whose stream made it, a
-   * foreground script's inner call the turn of the code_execution call whose
-   * script is running when the call arrives, and a utility run its `utils`
-   * call's. A background script runs apart from any turn, so its calls carry
-   * none. Ids increase, so a later turn's is larger, and they're unique only
+   * script's call the turn of the code_execution call watching the script when
+   * the call reaches the host, and a utility run its `utils` call's. A script left
+   * running, which no call watches, runs apart from any turn, so its calls
+   * carry none. Ids increase, so a later turn's is larger, and they're unique only
    * within one run of the process. A call made with `executeToolCall` or a
    * module's `callTool` skips that layer and carries whatever turn its caller
    * put on the call, usually none.
    */
   callerTurnId?: number;
+  /**
+   * How long this call's result may be and still reach its caller whole,
+   * measured as the framework stores it: an error's text, or a success's data
+   * as JSON (a content array as its text). For a model's call it is the
+   * agent's inline cap, past which the framework spills the result to a
+   * workspace file and sends a preview. For a call from a running
+   * code_execution script it is the longest result that reaches the script
+   * whole whatever its characters, from the script's memory: the script
+   * takes an answer of up to a third of its memoryMaxBytes, in which a
+   * character of the result takes at most six bytes (a control character,
+   * escaped as `\u0000`), so the figure is that third, less the 80 bytes of a
+   * text answer's envelope, over six: 7,456,527 at the default 128 MiB. On
+   * Node, past about 1.5 GiB, the host's longest string bounds it instead.
+   * A result with a `structured` value reaches a script as its content's
+   * blocks as they are, beside that value as JSON, and the figure counts
+   * neither the value nor what the blocks carry past their text, such as each
+   * further block's keys or an image's data, so a tool that returns one
+   * leaves room for them; and a result nested past 2,000 levels, or whose parse
+   * needs more of the script's memory than is free, doesn't reach the script
+   * whatever its length. A result that doesn't reach it is answered
+   * ResultTooLarge, the call having taken effect. Nothing is cut or saved to
+   * a file. A tool that pages or budgets its answer can stay under it. The
+   * framework sets it on a model's, a script's and the operator's puppet's
+   * call to a module, a utility run through `utils` included. A call
+   * made in process with ModuleContext.callTool or executeToolCall carries
+   * what its caller put on it, as the puppet's does; the framework's own
+   * read_image tool passes a model's call to the workspace without it; and a
+   * utility run through `utils` carries what its `utils` call carried.
+   * Without it, a module holds its answer to a bound of its own, if any: the
+   * workspace's is the house default, 24,000.
+   */
+  resultMaxChars?: number;
 }
 
 // ============================================================================

package/src/types/framework.ts

@@ -31,66 +31,66 @@ export interface ProcessLoggingConfig {
  */
 /**
  * Client-side programmatic tool calling: a synthesized `code_execution` tool
- * that runs model-authored Python on the host, with every framework tool
- * injected as an async function. Mirrors the trained surface of Anthropic's
- * server-side PTC; inner tool results never enter the model context.
+ * that runs model-authored JavaScript in QuickJS compiled to WebAssembly, in a
+ * child process of its own per script, with the agent's tools as async
+ * functions. Mirrors the trained surface of Anthropic's server-side PTC;
+ * inner tool results never enter the model context.
  *
- * Robustness boundary, not a security sandbox (same doctrine as gate.js —
- * the agent already has broader host access through its tools).
+ * A script adds nothing to what its agent's tools allow, provided the host
+ * runtime's WebAssembly engine and the glue around it are right. It claims no
+ * containment beyond that: the child runs as the host's user, with an empty
+ * environment and no operating-system sandbox around it.
  */
 export interface CodeExecutionConfig {
   /** Master switch — only `true` synthesizes the tool. `create()` refuses a
    *  value that isn't a boolean, a quoted "false" included; `null` or leaving
    *  it out counts as off. */
   enabled: boolean;
-  /** Python interpreter to spawn (default: 'python3' from PATH). */
-  pythonPath?: string;
-  /**
-   * Per-inner-tool-call timeout; exceeding it raises TimeoutError inside the
-   * script (default 270_000 ms, mirroring the managed runtime's message).
-   */
+  /** How long a run or a wait waits for its script before it yields, unless
+   *  the agent asks otherwise with `yield_time_ms` (default 30_000 ms). */
+  yieldMs?: number;
+  /** The most an agent may ask a run or a wait to wait (default 600_000 ms).
+   *  At least `yieldMs`. */
+  maxYieldMs?: number;
+  /** A script's limit: a script still running this long after it started is
+   *  stopped, as "stopped at its limit" (default 86_400_000 ms, a day). */
+  scriptLifetimeMs?: number;
+  /** Scripts one agent may have running at once, yielded ones included
+   *  (default 3). */
+  maxRunningScripts?: number;
+  /** Script processes the host runs at once, every agent's together
+   *  (default 16). A run past it is refused at once, and nothing runs. */
+  maxScriptChildren?: number;
+  /** How long one of a script's tool calls may go unanswered before the
+   *  script is told it timed out; the tool may still take effect
+   *  (default 270_000 ms). */
   toolCallTimeoutMs?: number;
-  /** Whole-script deadline: cancel → grace → SIGKILL (default 600_000 ms). */
-  scriptTimeoutMs?: number;
-  /**
-   * Longest deadline an agent may ask for on one call with `time_limit_ms`
-   * (default: `scriptTimeoutMs`, so agents can only shorten it until this is
-   * raised). Longer requests are capped, and the result says so.
-   */
-  maxScriptTimeoutMs?: number;
-  /**
-   * Idle interpreter reclaim — script globals are lost after this much
-   * inactivity (default 300_000 ms, mirroring ~5-minute container reclaim).
-   * 0 disables reclaim.
-   */
-  idleReclaimMs?: number;
-  /** Max concurrent background (daemon) scripts per agent (default 3). */
-  maxBackgroundScripts?: number;
-  /** Background script lifetime ceiling, ms (default 86_400_000 = 24h). */
-  backgroundMaxLifetimeMs?: number;
   /** Minimum interval between wake_agent() deliveries, ms (default 60_000).
-   *  Early wakes are delayed, not dropped (backpressure inside the script). */
+   *  Early wakes are delayed, not dropped. */
   wakeMinIntervalMs?: number;
-  /** Max wake_agent() calls per background script (default 100); further
-   *  calls raise RuntimeError inside the script. */
+  /** Max wake_agent() calls per script (default 100); further calls are
+   *  refused in the script. */
   maxWakesPerScript?: number;
-  /** Variables for the python interpreter beyond the operating allowlist it
-   *  inherits (see CHILD_ENV_ALLOWLIST), such as PYTHONPATH. A recipe can
-   *  `${VAR}`-substitute them from .env. Other host variables aren't
-   *  inherited, which limits what model-authored code inherits, not what a
-   *  process running as the same user can read. The runner sets
-   *  PYTHONUNBUFFERED and PYTHONIOENCODING last, over any value given here,
-   *  since its protocol needs both. The interpreter's working directory is
-   *  its own runtime directory, so a relative path given here, as in
-   *  PYTHONPATH, resolves there: give absolute paths. */
-  env?: Record<string, string>;
-  /** The interpreter inherits the host's whole environment instead of the
-   *  allowlist: every host variable, provider keys included, reaches
-   *  model-authored code and every subprocess a script starts. Listing what
-   *  scripts need in `env` is the safer route. With code execution enabled,
-   *  `create()` refuses any value but true, false or null, which counts as
-   *  not set. */
-  inheritEnv?: boolean;
+  /**
+   * The WebAssembly memory's maximum for each script, its budget: a whole
+   * number of 64 KiB pages from 4 MiB to 2 GiB (default 128 MiB). A script's
+   * process stays within about its runtime's base plus 2.7 times this, plus
+   * what its calls take as they go out: up to about 200 MiB under Node and
+   * 410 MiB under Bun. The host holds at most about 6 times this, plus 653 MiB,
+   * plus 128 KiB for each wake maxWakesPerScript allows, for a script: about
+   * 1.4 GiB at the defaults.
+   * That's its 16 calls out at once, each with at most 4 MiB of JSON
+   * arguments, timed-out ones whose tools still run included, up to 16 more
+   * waiting as their text for those to end, up to 16 answers until the child
+   * takes them, each at most a third of this, the frame from the child being
+   * read, and its waiting wakes. A tool's
+   * own result, and the one serialization the bridge makes of it to check its
+   * size, are the tool's, beside this. Size a host by both. A call past the 16
+   * the script waits on waits in the script, in this memory. A tool result too large for
+   * it reaches the script as ResultTooLarge; how much fits depends on the
+   * result's shape (see `IsolateSettings.memoryMaxBytes`).
+   */
+  memoryMaxBytes?: number;
 }
 
 /** See `FrameworkConfig.providerHold`. */
@@ -127,9 +127,10 @@ export interface FrameworkConfig {
   storePath?: string;
 
   /**
-   * Branch-independent Discord awareness-marker outbox. Defaults to
+   * Branch-independent Discord awareness ledger. Defaults to
    * `<storePath>/recovery/discord-awareness-outbox.json`. Set explicitly when
-   * providing an app-owned `store` without `storePath`; omit to disable.
+   * providing an app-owned `store` without `storePath`; with neither, the
+   * framework has no ledger and refuses a marks choice.
    */
   discordAwarenessOutboxPath?: string;
 
@@ -227,7 +228,7 @@ export interface FrameworkConfig {
 
   /**
    * Client-side programmatic tool calling (`code_execution` tool). Omitted or
-   * `enabled: false` → tool absent, no python is ever spawned. At runtime,
+   * `enabled: false` → tool absent, and no script's process is ever started. At runtime,
    * untyped configs may also use `null` or `false` to omit this setting.
    * Other values that aren't objects are refused at `create()`.
    */
@@ -235,12 +236,12 @@ export interface FrameworkConfig {
 
   /**
    * Durable inline cap (chars) for tool results — successes AND errors — and
-   * background-script wake payloads. Content over the cap is written to a
+   * script wake payloads (wake_agent()). Content over the cap is written to a
    * workspace file under `tool-results/` (deterministic `<date>-<callId>.txt`
    * name, overwritten on collision, retained until the workspace owner
    * deletes it — never auto-GC'd) and replaced inline by a bounded preview
-   * plus the file reference; with no writable workspace the fallback is
-   * explicit plain truncation. Default 24000 (house-safe; issue #89). Must be
+   * plus the file reference; with no writable mount without an include, the
+   * fallback is explicit plain truncation. Default 24000 (house-safe; issue #89). Must be
    * >= 1000. A resident's own agent_settings value
    * `tool_result_inline_max_chars` (durable, persisted in framework state)
    * takes precedence over this for that agent; the EFFECTIVE cap for every
@@ -460,13 +461,16 @@ export interface InferenceLogEntry {
 }
 
 /**
- * Entry in the process log - records a processed event with all module responses.
+ * Entry in the process log - records a processed event with the module
+ * responses that applied.
  */
 export interface ProcessLogEntry {
   timestamp: number;
   /** The process event that was handled */
   processEvent: ProcessEvent;
-  /** Responses from all modules, or blob ID if large */
+  /** The modules' responses that applied, or blob ID if large. A response
+   *  refused for content context-manager won't store is left out; its stderr
+   *  line and process:response-refused trace name it. */
   responses: ModuleProcessResponse[] | { blobId: string };
 }
 
@@ -476,7 +480,7 @@ export interface ProcessLogEntry {
 export interface ProcessLogQuery {
   /** Filter by process event type */
   eventType?: string;
-  /** Filter by module name (modules that responded) */
+  /** Filter by module name (modules whose responses applied) */
   moduleName?: string;
   /** Max number of logs to return */
   limit?: number;