@animalabs/agent-framework 0.23.3 → 0.24.1

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`. */
@@ -117,9 +117,10 @@ export interface FrameworkConfig {
   subconscious?: import('../tune-out/tools.js').SubconsciousConfig;
 
   /**
-   * IANA zone used only when rendering wall-clock times for the agent.
-   * Stored/protocol timestamps remain epoch/UTC. Defaults to AGENT_TIMEZONE,
-   * then the process zone.
+   * IANA zone of the agent's wall clock: it renders wall-clock times for the
+   * agent, and it sets where clock rows' boundaries fall (AgentConfig.clock,
+   * counted from local midnight here). Stored/protocol timestamps remain
+   * epoch/UTC. Defaults to AGENT_TIMEZONE, then the process zone.
    */
   timeZone?: string;
 
@@ -127,9 +128,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 +229,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,18 +237,20 @@ 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
    * source is min(desired, strategy bound) — desired values above the
    * strategy-derived bound (maxMessageTokens * 4) are hard-clamped to it,
-   * with the clamp reported via agent_settings get.
+   * with the clamp reported via agent_settings get. For an ordinary resident
+   * the bound is the smallest among the agents that read the shared slot,
+   * reported as clamped by `reader-bound` when another reader's sets it.
    */
   toolResultInlineMaxChars?: number;
 
@@ -460,13 +464,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 +483,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;

package/src/types/module.ts

@@ -27,7 +27,8 @@ export interface MessageQuery {
 
 /**
  * A message as a module context's reads answer it: a stored row, or a row
- * for a write the framework holds (`held`).
+ * for a write the framework holds (`held`). Either is marked
+ * `heldFromResidents` when a tune-out holds it from the residents.
  */
 export type ModuleMessage = StoredMessage & {
   /**
@@ -39,9 +40,31 @@ export type ModuleMessage = StoredMessage & {
    * and `timestamp` are provisional: the sequence comes after every stored
    * row's, the timestamp is when the framework held the write (for a write
    * an older release held, when its queue was read back), and both change
-   * when it lands. Absent on a stored row.
+   * when it lands. A held write whose earlier write may already be stored
+   * is looked up first, and answered as the stored row it is when the store
+   * holds it. Absent on a stored row.
    */
   held?: true;
+  /**
+   * True on a message a tune-out holds from the residents: one that arrived
+   * in a tuned-out channel, stamped `metadata.tuneOut` as it came in. The
+   * store keeps it, but no resident is shown the row itself: no resident's
+   * compiled view includes it, during the tune-out or after it, and a tool
+   * boundary of a turn alive when it arrived stores it without injecting it
+   * into the live turn. The subconscious reads it. Its text can still reach
+   * a resident in rows of their own, which aren't marked, such as the
+   * cancel's `<tuned-out-backlog>` row, with the text of the tune-out's newest
+   * messages, up to `backlogCap` of them and as many as fit in one of the
+   * residents' messages, the stored ones first and then those still held;
+   * what the subconscious says of it, in its report or its note; and the
+   * result of a tool that reads history on request, such as a
+   * channel's `fetch_history` or the history module's `extract`. A module
+   * that builds on what the residents see, such as one choosing from the
+   * recent conversation, leaves a marked row out, and one that matches
+   * what's stored, such as a sync's dedupe, keeps it. A held write (`held`)
+   * is marked too when it carries the stamp. Absent on every other row.
+   */
+  heldFromResidents?: true;
 };
 
 /**
@@ -290,13 +313,17 @@ export interface ModuleContext {
 
   /**
    * Edit a message, by its id or a held write's handle. A held write is
-   * stored with the new content.
+   * stored with the new content. One whose earlier write may already be
+   * stored, where the store can't be searched to tell, throws with nothing
+   * changed.
    */
   editMessage(id: MessageId, content: ContentBlock[]): void;
 
   /**
    * Remove a message, by its id or a held write's handle. A held write is
-   * dropped, so the agent never reads it.
+   * dropped, so the agent never reads it. One whose earlier write may
+   * already be stored, where the store can't be searched to tell, throws
+   * with nothing changed.
    */
   removeMessage(id: MessageId): void;
 
@@ -312,7 +339,9 @@ export interface ModuleContext {
   findMessageByExternalId(source: string, externalId: string): MessageId | null;
 
   /**
-   * Get a message by its id or a held write's handle.
+   * Get a message by its id or a held write's handle, marked
+   * `heldFromResidents` when a tune-out holds it from the residents
+   * (ModuleMessage).
    */
   getMessage(id: MessageId): ModuleMessage | null;
 
@@ -322,7 +351,9 @@ export interface ModuleContext {
    * The rows of writes the framework holds come after the stored rows, as
    * the newest, or before them in a reversed query, marked `held`
    * (ModuleMessage). Those the last process held show once create() has
-   * restored them, after every module's start() (addMessage).
+   * restored them, after every module's start() (addMessage). A message a
+   * tune-out holds from the residents is among the rows, marked
+   * `heldFromResidents` (ModuleMessage).
    */
   queryMessages(filter: MessageQuery): MessageQueryResult;
 
@@ -571,8 +602,9 @@ export interface SpeechContext {
 
   /**
    * The turn this speech ends: the same id as `ToolCall.callerTurnId` on the
-   * calls made in it (its model's calls and its foreground scripts' inner
-   * calls), kept across the turn's streams (a context-budget restart or a
+   * calls made in it (its model's calls, and a script's calls that reach the
+   * host while a code_execution call of the turn watches the script), kept across the
+   * turn's streams (a context-budget restart or a
    * retry), and larger for the agent's next turn. Unique only within one run
    * of the process.
    */

package/src/types/trace.ts

@@ -33,9 +33,23 @@ export type TraceEvent =
   | (TraceEventBase & {
       type: 'process:completed';
       processEvent: ProcessEvent;
+      /** The modules' responses that applied: one refused for malformed
+       *  content is left out, and named by process:response-refused. */
       responses: ModuleProcessResponse[];
       durationMs: number;
     })
+  /** A module's process response held content context-manager won't store,
+   *  in a message it adds or an edit it makes, and was refused whole before
+   *  any response to the event applied. `where` names the first such message
+   *  or edit in the response, such as `addMessages[1]`, and `places` is
+   *  malformedContentPlaces' answer for it. */
+  | (TraceEventBase & {
+      type: 'process:response-refused';
+      moduleName: string;
+      eventType: string;
+      where: string;
+      places: string[];
+    })
 
   // Inference lifecycle
   | (TraceEventBase & {
@@ -124,9 +138,15 @@ export type TraceEvent =
       blockType: 'text' | 'thinking' | 'tool_call' | 'tool_result';
       /** 0-indexed block position in the current assistant turn. */
       blockIndex: number;
-      /** The channel this stream shows typing in: the turn's locus as the
-       *  stream started (see inference:started), or in explicit mode the
-       *  channel the start's wake came from. */
+      /** The channel this stream shows typing in, the conversation the turn
+       *  is attending. Locus and hybrid mode: the turn's locus, which an
+       *  addressed re-pin or the agent's own `channel_open` can move between
+       *  rounds, so it can change within one stream; the indicator and these
+       *  traces follow it from the next round on, at the model's first
+       *  content in it or its retry after a refusal, and a tool result the
+       *  boundary reports carries the channel of the round it answers. In
+       *  hybrid mode a `>>>` envelope can send the text itself elsewhere.
+       *  Explicit mode: the channel the start's wake came from. */
       channelId?: string;
     })
   | (TraceEventBase & {
@@ -141,9 +161,15 @@ export type TraceEvent =
       phase: 'block_start' | 'block_complete';
       blockType: 'text' | 'thinking' | 'tool_call' | 'tool_result';
       blockIndex: number;
-      /** The channel this stream shows typing in: the turn's locus as the
-       *  stream started (see inference:started), or in explicit mode the
-       *  channel the start's wake came from. */
+      /** The channel this stream shows typing in, the conversation the turn
+       *  is attending. Locus and hybrid mode: the turn's locus, which an
+       *  addressed re-pin or the agent's own `channel_open` can move between
+       *  rounds, so it can change within one stream; the indicator and these
+       *  traces follow it from the next round on, at the model's first
+       *  content in it or its retry after a refusal, and a tool result the
+       *  boundary reports carries the channel of the round it answers. In
+       *  hybrid mode a `>>>` envelope can send the text itself elsewhere.
+       *  Explicit mode: the channel the start's wake came from. */
       channelId?: string;
     })
   | (TraceEventBase & {
@@ -173,6 +199,66 @@ export type TraceEvent =
       type: 'inference:turn_ended';
       agentName: string;
     })
+  | (TraceEventBase & {
+      /**
+       * Prose that delivery published, sent once the publish succeeds: the
+       * outgoing stream's chunk (MCPL Spec 14.3 `channels/outgoing/chunk`),
+       * emitted whether or not the channel's server takes the stream. It
+       * carries only what was published, so a consumer that speaks or shows
+       * it, such as a voice relay, never gets text that delivery withholds (a
+       * `skip_reply`, a silencing send, a private `think`, a hold, a bounce,
+       * a draft) or a publish the server didn't confirm (`delivered: true`):
+       * one refused before sending, one that threw, timed out or got an
+       * error answer, one the server reported undelivered
+       * (`delivered: false`), and one whose reply leaves `delivered` out.
+       * `inference:tokens` stays the model's text as it is written (held, as
+       * before, while a tool-result guard's batch is pending). A later
+       * publish to the same destination, a server and its channel, by the
+       * same stream opens with a paragraph break (`\n\n`), so a
+       * destination's chunks joined in `index` order are its text, its
+       * messages kept apart.
+       * `mcpl:speech-routed` also reports speech publishes, with no stream
+       * id, index or end, each once delivered: deliverSpeech's, the `sleep`
+       * tool's announcement among them, and a subconscious's
+       * `speak_in_channel`'s. A relay that voices the agent's prose takes
+       * this trace, with `inference:published_complete`, and not
+       * `mcpl:speech-routed` as well, and takes each message's id from its
+       * `messageId` to edit what it voiced.
+       */
+      type: 'inference:published';
+      agentName: string;
+      /** The server the prose is published to, and its channel there: two
+       *  servers' channels with the same id are two destinations. */
+      serverId: string;
+      channelId: string;
+      /** The stream's id, shared with its `channels/outgoing/*` notifications. */
+      inferenceId: string;
+      /** Increases by one per chunk of the stream, across its channels. */
+      index: number;
+      text: string;
+      /** The id the channel's server returned for this chunk's publish
+       *  (`ChannelsPublishResult.messageId`); absent when it returned none.
+       *  Each chunk is one publish, so each carries its own. */
+      messageId?: string;
+    })
+  | (TraceEventBase & {
+      /**
+       * A stream's end for one destination it published to, a server and
+       * its channel, emitted on every exit path once the stream has ended
+       * and its deliveries have run, or, when the host stops, before its
+       * connections close: `text` is everything its `inference:published`
+       * chunks carried there by then, and none follows it. Like those
+       * chunks, it's emitted whether or not that server takes the stream,
+       * or registers the channel still; the MCPL
+       * `channels/outgoing/complete` goes to the server only when it does.
+       */
+      type: 'inference:published_complete';
+      agentName: string;
+      serverId: string;
+      channelId: string;
+      inferenceId: string;
+      text: string;
+    })
 
   // Tool lifecycle
   | (TraceEventBase & {
@@ -216,10 +302,11 @@ export type TraceEvent =
     })
   | (TraceEventBase & {
       /**
-       * A writable workspace existed but the oversized-result spill write
-       * failed (size cap, storeBlob failure, …) — the over-cap tail was NOT
+       * The workspace had a writable mount without an include, where spills
+       * go, but the oversized-result spill write failed (size cap, storeBlob failure, …) — the over-cap tail was NOT
        * retained. Distinct from the no-workspace fallback, which is silent
-       * by design (nothing unexpected happened).
+       * by design (nothing unexpected happened), whether the setup has no
+       * writable mount or every writable mount has an include, as configured.
        */
       type: 'tool:spill_failed';
       label: string;
@@ -302,6 +389,18 @@ export type TraceEvent =
       field?: string;
       detail?: string;
     })
+  /** MCPL content that context-manager won't store, because it doesn't
+   *  match ContentBlock, reached the store/wake site and was refused there:
+   *  no row, no wake. `places` is malformedContentPlaces' answer for it. */
+  | (TraceEventBase & {
+      type: 'mcpl:malformed-content-refused';
+      lane: 'push' | 'channel';
+      serverId: string;
+      places: string[];
+      eventId?: string;
+      channelId?: string;
+      messageId?: string;
+    })
   /** MCPL content with nothing model-visible reached the store/wake site
    *  (module-emitted or coalescer-delivered) and was dropped: no row, no wake. */
   | (TraceEventBase & {
@@ -442,13 +541,16 @@ export type TraceEvent =
     })
 
   // Host-owned speech routing (ChannelRegistry.routeSpeech). One trace per
-  // delivered prose segment. `text` is the segment verbatim — the same content
+  // delivered prose segment, and one per publish the subconscious's
+  // speak_in_channel delivers (ChannelRegistry.publishForAgent): that one's
+  // conversationId is the speaking agent's name, and it carries no
+  // messageId. `text` is the segment verbatim — the same content
   // already on the bus chunk-by-chunk via inference:tokens, and mcpl:* traces
   // are 'ops'-scoped on the webui wire — and `messageId` is the surface's id
-  // for the posted message (when the MCPL server reports one). Together they
-  // give external taps the (channelId, messageId, text) tuple needed to edit
-  // a just-posted message, e.g. a TTS interruption truncating a reply to the
-  // words actually voiced.
+  // for the posted message (on routeSpeech's traces, when the MCPL server
+  // reports one). Together they give external taps the (channelId,
+  // messageId, text) tuple needed to edit a just-posted message, e.g. a TTS
+  // interruption truncating a reply to the words actually voiced.
   | (TraceEventBase & {
       type: 'mcpl:speech-routed';
       /** Agent / conversation whose speech was routed. */
@@ -459,7 +561,8 @@ export type TraceEvent =
       textLen: number;
       /** The routed prose segment, verbatim. */
       text: string;
-      /** Surface message id (e.g. Discord message id), when reported. */
+      /** Surface message id (e.g. Discord message id), when reported, on
+       *  routeSpeech's traces. speak_in_channel's carry none. */
       messageId?: string;
     })
   | (TraceEventBase & {
@@ -473,6 +576,9 @@ export type TraceEvent =
       /** `failed`: nothing was posted; `unknown`: the request was dispatched
        *  and no valid receipt came back, so it may have been. */
       outcome?: 'failed' | 'unknown';
+      /** The connector error's structured data, bounded (connectorText),
+       *  when it sent some: it may say what a multi-part send posted. */
+      detail?: string;
     })
 
   // Admin puppet: an operator executed a tool AS an agent and stored the

package/src/usage/types.ts

@@ -3,13 +3,29 @@ export interface SessionUsage {
   outputTokens: number;
   cacheCreationTokens: number;
   cacheReadTokens: number;
+  /** The summed estimated cost of the inferences counted here that membrane
+   *  priced, in one currency. An inference it couldn't price adds nothing, so
+   *  this is a lower bound when any were unpriced. Absent when none was
+   *  priced, and from the moment costs in two currencies meet here, since the
+   *  two can't be summed, which `mixedCurrencies` records. */
   estimatedCost?: { total: number; currency: string };
+  /** Set once inferences priced in two currencies have been counted here:
+   *  `estimatedCost` stays absent from then on, since the two can't be
+   *  summed and a later cost alone isn't this tally's. Stored and restored
+   *  with it, and carried into the shared ephemeral entry when stored
+   *  entries fold into it. */
+  mixedCurrencies?: true;
 }
 
 export interface AgentUsage {
   agentName: string;
   usage: SessionUsage;
   inferenceCount: number;
+  /** Set on the one entry that holds every ephemeral agent's usage together
+   *  (agentName EPHEMERAL_USAGE_NAME), apart from any agent of that name. Each
+   *  ephemeral agent runs under a new name, so an entry per name would grow
+   *  the record by one for every run, for good. */
+  ephemeral?: true;
 }
 
 export interface SessionUsageSnapshot {