@stratusagent/core 0.11.2 → 0.11.4

package/dist/index.js

@@ -1,6 +1,232 @@
+/**
+ * The image formats a model request may carry. The list is the Messages
+ * API's, and it is exported so a channel deciding which of a message's
+ * attachments to fetch asks this rather than keeping its own copy — a
+ * format the API rejects is one the channel should never have downloaded.
+ */
+export const IMAGE_ATTACHMENT_MEDIA_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
+export const isImageAttachmentMediaType = (value) => typeof value === 'string' && IMAGE_ATTACHMENT_MEDIA_TYPES.includes(value);
+/**
+ * The largest image a message may carry, in decoded bytes. The Messages
+ * API refuses anything over 5 MB per image, and a session is one JSON row
+ * that every later turn re-reads — an image is stored with the message it
+ * arrived on, so the cap is also what keeps a transcript readable.
+ */
+export const IMAGE_ATTACHMENT_MAX_BYTES = 5 * 1024 * 1024;
+/**
+ * The most image bytes one message may carry in total, decoded. The
+ * Messages API caps a request body at 32 MiB, and base64 costs a third
+ * again — so five images each just under the per-image cap pass one by one
+ * and still fail the turn together. 20 MiB decoded is 26.7 MiB encoded,
+ * leaving room for the text around it.
+ */
+export const IMAGE_ATTACHMENTS_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+/**
+ * The most images one request may carry, whatever they weigh. The Messages
+ * API accepts 100 per request, but past 20 it also shrinks what each may
+ * measure to 2000 pixels a side — and an image was accepted at up to
+ * `IMAGE_ATTACHMENT_MAX_DIMENSION` when it arrived. Twenty is the count at
+ * which every image already stored is still one the API takes.
+ */
+export const IMAGE_ATTACHMENTS_MAX_REPLAY_COUNT = 20;
+/**
+ * The most an image may measure on either side, in pixels. The Messages
+ * API refuses anything larger, and a large flat PNG compresses far below
+ * the byte cap — so bytes alone would let an image in that fails the turn
+ * it arrives on and, once stored, every turn after.
+ */
+export const IMAGE_ATTACHMENT_MAX_DIMENSION = 8000;
+/**
+ * An image's pixel size, read from its header without decoding it, or
+ * nothing when the bytes do not carry the header and trailer their media
+ * type promises — which a caller should treat as "not an image it can
+ * send". The trailer is what catches a download cut short: a PNG ends in
+ * IEND, a JPEG in an end-of-image marker, a GIF in a trailer byte, and a
+ * RIFF container declares its own length. It is not a decode — bytes that
+ * open and close correctly can still be refused by a model API, and a
+ * provider handles that when it happens (see `omitImage`) — but it is
+ * everything that can be checked without an image library, which core
+ * does not carry. One reader for the four accepted formats, so a channel
+ * deciding whether to keep a download asks this rather than trusting the
+ * uploader's metadata.
+ */
+export const imageDimensions = (bytes, mediaType) => {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const ascii = (at, length) => String.fromCharCode(...bytes.subarray(at, at + length));
+    const last = bytes.length;
+    switch (mediaType) {
+        case 'image/png': {
+            if (bytes.length < 36 || ascii(1, 3) !== 'PNG' || ascii(12, 4) !== 'IHDR' || ascii(last - 8, 4) !== 'IEND') {
+                return undefined;
+            }
+            return { width: view.getUint32(16), height: view.getUint32(20) };
+        }
+        case 'image/gif': {
+            if (bytes.length < 11 || ascii(0, 4) !== 'GIF8' || bytes[last - 1] !== 0x3b) {
+                return undefined;
+            }
+            return { width: view.getUint16(6, true), height: view.getUint16(8, true) };
+        }
+        case 'image/webp': {
+            if (bytes.length < 30 || ascii(0, 4) !== 'RIFF' || ascii(8, 4) !== 'WEBP' || view.getUint32(4, true) !== last - 8) {
+                return undefined;
+            }
+            // Three container layouts, each keeping its size somewhere different.
+            const chunk = ascii(12, 4);
+            if (chunk === 'VP8 ') {
+                return { width: view.getUint16(26, true) & 0x3fff, height: view.getUint16(28, true) & 0x3fff };
+            }
+            if (chunk === 'VP8L') {
+                const [b0, b1, b2, b3] = [bytes[21], bytes[22], bytes[23], bytes[24]];
+                return {
+                    width: 1 + (((b1 & 0x3f) << 8) | b0),
+                    height: 1 + (((b3 & 0x0f) << 10) | (b2 << 2) | ((b1 & 0xc0) >> 6)),
+                };
+            }
+            if (chunk === 'VP8X') {
+                return {
+                    width: 1 + (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16)),
+                    height: 1 + (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16)),
+                };
+            }
+            return undefined;
+        }
+        case 'image/jpeg': {
+            if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8 || bytes[last - 2] !== 0xff || bytes[last - 1] !== 0xd9) {
+                return undefined;
+            }
+            // Walk the segments to the first start-of-frame, which carries the size.
+            let at = 2;
+            while (at + 9 <= bytes.length) {
+                if (bytes[at] !== 0xff) {
+                    return undefined;
+                }
+                const marker = bytes[at + 1];
+                if (marker === 0xff) {
+                    at += 1;
+                    continue;
+                }
+                const startOfFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+                if (startOfFrame) {
+                    return { height: view.getUint16(at + 5), width: view.getUint16(at + 7) };
+                }
+                const standalone = marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8);
+                at += standalone ? 2 : 2 + view.getUint16(at + 2);
+            }
+            return undefined;
+        }
+        default:
+            return undefined;
+    }
+};
+/** Decoded size of a base64 string, without decoding it. */
+const base64DecodedBytes = (data) => Math.floor((data.length * 3) / 4) - (data.endsWith('==') ? 2 : data.endsWith('=') ? 1 : 0);
+/**
+ * Which of a transcript's images still travel on a request. Every image a
+ * session ever received is stored with its message and replayed on every
+ * later turn, so a per-message budget alone is not one: two messages that
+ * each fit would together exceed the request limit on the turn after. The
+ * budget — bytes and a count, both API limits — is spent newest first,
+ * within a message as well as across them: the latest message always
+ * arrives whole, because a channel already holds one message to this same
+ * budget, and once an image does not fit, nothing older does either, so
+ * what the model sees is a contiguous recent window rather than a
+ * scatter. A provider
+ * that sends image bytes asks this and sends a note in place of the rest;
+ * the transcript itself is never trimmed.
+ *
+ * Membership is by identity: the set holds the very objects on the
+ * messages, so a provider walking them asks `has(image)`.
+ */
+export const imagesWithinReplayBudget = (messages, budget = {}) => {
+    const kept = new Set();
+    let remaining = budget.bytes ?? IMAGE_ATTACHMENTS_MAX_TOTAL_BYTES;
+    const count = budget.count ?? IMAGE_ATTACHMENTS_MAX_REPLAY_COUNT;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const images = messages[index]?.images;
+        if (images === undefined) {
+            continue;
+        }
+        for (let position = images.length - 1; position >= 0; position -= 1) {
+            const image = images[position];
+            // Nothing left to send, and nothing to charge: an omitted image is
+            // always older than every kept one, so skipping it keeps the window
+            // contiguous.
+            if (image.omitted === true) {
+                continue;
+            }
+            const bytes = base64DecodedBytes(image.data);
+            if (bytes > remaining || kept.size >= count) {
+                return kept;
+            }
+            remaining -= bytes;
+            kept.add(image);
+        }
+    }
+    return kept;
+};
+/**
+ * Lets go of the bytes of every image outside the replay window, in
+ * place, keeping its name and the fact that it was there. The runner calls
+ * this as it stores a turn: the replay budget bounds what a provider
+ * sends, but a session is one JSON row that every turn re-reads and
+ * re-writes whole, and without this every image a thread ever received
+ * would stay in it — so anyone who can post to a channel could grow a row
+ * by the whole budget per message, forever. What the model can be shown is
+ * exactly what is kept, so nothing the trim removes could have been sent.
+ * Returns how many images it emptied.
+ */
+export const omitImagesOutsideReplayBudget = (messages, budget = {}) => {
+    const kept = imagesWithinReplayBudget(messages, budget);
+    let omitted = 0;
+    for (const message of messages) {
+        for (const image of message.images ?? []) {
+            if (image.omitted === true || kept.has(image)) {
+                continue;
+            }
+            omitImage(image);
+            omitted += 1;
+        }
+    }
+    return omitted;
+};
+/**
+ * Lets go of one image's bytes in place, keeping the record that it was
+ * there. Besides the replay window, this is what a provider does to an
+ * image the model API refused: the header checks a channel runs are not a
+ * decode, so a file that opens and closes correctly can still be rejected
+ * — and because an image is stored before the provider is called, a
+ * rejection left alone would replay on every later turn of the session.
+ * Emptied in place on the session's own object, so the runner's next save
+ * carries it and the turn goes on with a note in the image's place.
+ */
+export const omitImage = (image) => {
+    image.data = '';
+    image.omitted = true;
+};
+/**
+ * What stands in for an image `imagesWithinReplayBudget` left out — one
+ * wording, so every provider tells the model the same thing about the
+ * same gap.
+ */
+export const droppedImageNote = (image) => `[An image attached here${image.name !== undefined ? ` (${image.name})` : ''} is no longer sent: this conversation's images have passed what one request can carry, and only the most recent are kept.]`;
+export const LISTENS_MODES = ['mentions', 'thread', 'judge'];
+export const isListensMode = (value) => typeof value === 'string' && LISTENS_MODES.includes(value);
 export class AgentRegistry {
     agents = new Map();
+    /**
+     * `*` in a `delegates` list means any agent on the roster, so an agent
+     * with that id could never be granted alone — `delegates: ['*']` would
+     * open the whole roster to reach it. The soul loader refuses the id;
+     * this refuses it for a definition built in code, since the wildcard's
+     * meaning is decided here, where the roster lives, and not by which
+     * path put the agent on it.
+     */
     register(agent) {
+        if (agent.id === '*') {
+            throw new Error('Invalid agent id: "*". * is the delegates wildcard (delegates: [\'*\'] means any agent on the roster), '
+                + 'so no agent may have it as an id — give this agent another id.');
+        }
         this.agents.set(agent.id, agent);
         return agent;
     }
@@ -64,6 +290,37 @@ export const leastTrusted = (...levels) => {
     }
     return lowest;
 };
+/**
+ * The paths a tool result refers to as files for a channel to deliver: an
+ * ok result whose object output carries `file: string` or `files:
+ * string[]`. The one reading of that convention, shared by the channel
+ * that uploads them and the gateway that counts a turn which produced one
+ * as having said something — a chart in the thread is the last thing said
+ * as surely as a sentence is.
+ */
+export const filePathsOf = (result) => {
+    if (!result.ok) {
+        return [];
+    }
+    const output = result.output;
+    if (typeof output !== 'object' || output === null || Array.isArray(output)) {
+        return [];
+    }
+    const paths = [];
+    const single = output.file;
+    if (typeof single === 'string' && single.length > 0) {
+        paths.push(single);
+    }
+    const many = output.files;
+    if (Array.isArray(many)) {
+        for (const entry of many) {
+            if (typeof entry === 'string' && entry.length > 0) {
+                paths.push(entry);
+            }
+        }
+    }
+    return paths;
+};
 export const DEFAULT_TOOL_RISK = 'gated';
 /** The declared risk, or the fail-closed default for a tool that omits it. */
 export const resolveToolRisk = (tool) => tool?.risk ?? DEFAULT_TOOL_RISK;
@@ -146,6 +403,23 @@ const originForSession = (tool, session) => {
  * is a second answer to "what may this agent do".
  */
 export const matchesToolAllowlist = (toolName, allowlist) => matchesGlobbedAllowlist(toolName, allowlist, '.*');
+/**
+ * Whether an allowlist entry and a declared namespace select any of the
+ * same tools — true when either sits under the other.
+ *
+ * Namespaces nest, so both shapes are real: `mcp.linear.*` sits under a
+ * declared `mcp.*`, and a granted `mcp.*` covers everything a narrower
+ * declared `mcp.linear.*` will register. Both arguments are passed where a
+ * tool name goes on purpose — entry and namespace are the same dotted-prefix
+ * glob, so this is the reading the allowlists already use rather than a
+ * second one.
+ *
+ * Exported because the dead-entry check is no longer the only caller:
+ * `stratus plugins` answers which agents a namespace reaches before any of
+ * its tools exist, and a second hand-rolled overlap would drift from this
+ * one immediately.
+ */
+export const toolScopesOverlap = (entry, namespace) => matchesToolAllowlist(entry, [namespace]) || matchesToolAllowlist(namespace, [entry]);
 /**
  * Whether an agent's `skills:` allowlist permits a skill id.
  *
@@ -210,13 +484,7 @@ export const unmatchedToolAllowlist = (agent, registered, options = {}) => {
     // arrived yet, not a typo.
     //
     // Overlap either way excuses the entry, because either way the entry
-    // selects tools that namespace will bring: `mcp.linear.*` sits under a
-    // declared `mcp.*`, and a granted `mcp.*` covers everything a narrower
-    // declared `mcp.linear.*` will register — namespaces nest, so both
-    // shapes are real. Entry and namespace are passed where a tool name
-    // goes on purpose: both are the same dotted-prefix glob, so this is the
-    // reading the allowlists already use rather than a second one.
-    const overlaps = (entry, namespace) => matchesToolAllowlist(entry, [namespace]) || matchesToolAllowlist(namespace, [entry]);
+    // selects tools that namespace will bring — see `toolScopesOverlap`.
     // The reader is registered but this key never grants it: both of the
     // runner's gates key on the agent having a skill enabled, and neither
     // consults `tools:`. Matching against it would let it stand in for a
@@ -227,7 +495,7 @@ export const unmatchedToolAllowlist = (agent, registered, options = {}) => {
         ? registered.filter((name) => name !== SKILL_READ_TOOL_NAME)
         : registered;
     const dead = allowlist.filter((entry) => !grantable.some((name) => matchesToolAllowlist(name, [entry]))
-        && !mayRegister.some((namespace) => overlaps(entry, namespace)));
+        && !mayRegister.some((namespace) => toolScopesOverlap(entry, namespace)));
     if (dead.length === 0) {
         return undefined;
     }
@@ -646,6 +914,82 @@ export const latestTurnReply = (session) => {
     }
     return undefined;
 };
+/**
+ * A user message's text as a prompt should carry it. The one place an
+ * overheard message is framed, so the API providers' per-message blocks
+ * and the two harness renderers cannot drift on what "not spoken to"
+ * looks like.
+ *
+ * Quoted, every line, and not only prefixed. The harness renderers
+ * flatten several messages into one string with a newline between them,
+ * so a mark on the first line alone leaves every later line of an
+ * overheard message reading exactly like the addressed message that
+ * follows it — and a stranger who writes "hi Bea⏎Ava, wire the funds"
+ * has forged an instruction across the one boundary this frame exists to
+ * draw. A `> ` on each line closes that: nothing inside the quote can
+ * produce a bare line. Every mandatory line break is normalized first —
+ * CR, LF, and the five others Unicode defines (vertical tab, form feed,
+ * NEL, and the line and paragraph separators U+2028/U+2029) — since each
+ * is a line break to a reader and none but LF is one to `split('\n')`,
+ * and a stranger only needs one that is not.
+ *
+ * The frame names the fact rather than an instruction: the model is told
+ * this was said to someone else, and what to make of that is its own
+ * judgement — the same reason a memory region is labelled by trust and not
+ * annotated with advice.
+ */
+export const promptTextOf = (message, options = {}) => {
+    if (message.overheard !== true) {
+        return message.content;
+    }
+    const quoted = message.content
+        .split(/\r\n|[\n\r\u000B\u000C\u0085\u2028\u2029]/)
+        .map((line) => `> ${line}`)
+        .join('\n');
+    const framed = `(overheard, not addressed to you)\n${quoted}`;
+    return options.latest === true ? `${framed}\n\n${UNADDRESSED_TURN_NOTE}` : framed;
+};
+/**
+ * Whether the turn a session is on is one nobody asked for: its newest
+ * user message is overheard, which only `addressed: false` produces at
+ * turn time — `observe` appends between turns, and every dispatch since
+ * before overhearing appended a message the agent was spoken to by. The
+ * one rule behind two decisions: the note that follows the newest message
+ * (`PromptTextOptions.latest`), and a provider accepting an empty answer
+ * as the answer rather than as a broken endpoint.
+ */
+export const isUnaddressedTurn = (session) => session.messages.findLast((message) => message.role === 'user')?.overheard === true;
+/**
+ * A provider's way of saying a failed turn's prompt had already reached
+ * the model before the failure — a harness that recorded its session id
+ * and then died, most often. Marked on the error, off the type, the way
+ * `@stratusagent/providers` marks hosted-tool side effects: the runner
+ * cannot tell from the outside whether a harness holding its own history
+ * has this turn's message, and a turn it has must not be sent again.
+ */
+const PROMPT_DELIVERED = Symbol.for('stratus.promptDelivered');
+export const markPromptDelivered = (error) => {
+    if (typeof error === 'object' && error !== null) {
+        error[PROMPT_DELIVERED] = true;
+    }
+    return error;
+};
+export const promptWasDelivered = (error) => typeof error === 'object' && error !== null
+    && error[PROMPT_DELIVERED] === true;
+/**
+ * What a turn nobody asked for is told, after the message it ends on.
+ *
+ * The load-bearing sentence of reading the room, and the one that cannot
+ * be specified into correctness: a model asked "should you answer?" says
+ * yes far more often than a person would, so the note leans on silence
+ * hard, names the few things worth breaking it for, and says what an
+ * answer must not be — an acknowledgement is the interruption it exists
+ * to prevent. In the message and not the system prompt, because it has
+ * to reach a harness that holds its own history and takes only the newest
+ * message, and because a rule read next to the thing it applies to is
+ * followed more often than one read an hour ago.
+ */
+export const UNADDRESSED_TURN_NOTE = 'Nobody said that to you, and nobody is waiting on you. Reply only if you have something these people would want from you and do not have — an answer to a question left open, a correction to something wrong, a thing you were asked to watch for. Otherwise reply with nothing at all: no acknowledgement, no summary, no offer to help. Saying nothing is usually the right answer here.';
 /** Reads the checkpoint off a session, if it is parked. */
 export const readPendingApproval = (session) => {
     const raw = session.metadata?.[PENDING_APPROVAL_METADATA_KEY];
@@ -720,6 +1064,117 @@ export class InMemorySessionStore {
             .map((session) => session.id);
     }
 }
+// ---- contribution kinds a plugin registers besides tools ------------------
+/**
+ * The providers the host builds itself. Here, in the dependency-free
+ * package, because two packages that never import each other need the one
+ * list: `@stratusagent/state` resolves a selection against it, and
+ * `@stratusagent/plugins` refuses a manifest that declares one of these as
+ * a provider of its own — `provider: anthropic` in a soul has to keep
+ * meaning the first-party adapter, and a plugin that could shadow it would
+ * be a plugin that could receive every key the operator stored for it.
+ */
+export const BUILTIN_PROVIDER_NAMES = ['demo', 'openai', 'anthropic', 'codex'];
+/**
+ * The names a trusted config's `executor` and `memoryStore` keys mean the
+ * built-ins by — the local child-process executor and the file store —
+ * and so the names a plugin may not register: the host's selection
+ * special-cases them and would never look a contribution up under them.
+ * Here for the same reason the provider list is: the manifest parser and
+ * the selection logic live in packages that never import each other.
+ */
+export const BUILTIN_EXECUTOR_NAME = 'local';
+export const BUILTIN_MEMORY_STORE_NAME = 'file';
+/**
+ * A name-keyed registry for one contribution kind — the counterpart of
+ * `ToolRegistry` for providers, memory stores, and executors. Like it, a
+ * bare `Map.set`: it keeps no provenance and refuses nothing, and a plugin
+ * never touches one directly. The manifest-bound view in
+ * `@stratusagent/plugins` is what refuses an undeclared name or a
+ * collision; this is where a whole plugin's contributions land once it has
+ * loaded.
+ */
+export class ContributionRegistry {
+    entries = new Map();
+    register(name, value) {
+        this.entries.set(name, value);
+    }
+    get(name) {
+        return this.entries.get(name);
+    }
+    has(name) {
+        return this.entries.has(name);
+    }
+    names() {
+        return [...this.entries.keys()];
+    }
+    list() {
+        return [...this.entries.values()];
+    }
+}
+/** The (agent, kind) key a channel registration claims. */
+export const channelClaimKey = (kind, agentId) => `${kind}:${agentId}`;
+/**
+ * The registry for contributed channels. Keyed by (agent, kind) rather than
+ * by name, because that is what collides — see `ChannelContribution` — and
+ * listed as adapters, because that is what a host starts. Same discipline
+ * as the other registries: no refusal here, the view refuses.
+ */
+export class ChannelRegistry {
+    contributions = [];
+    /** Undefined marks a claim the host made for an adapter it wired itself. */
+    claims = new Map();
+    register(contribution) {
+        this.contributions.push(contribution);
+        for (const agentId of contribution.agents) {
+            this.claims.set(channelClaimKey(contribution.adapter.name, agentId), contribution);
+        }
+    }
+    /**
+     * Claim (agent, kind) pairs the host carries itself, so a plugin
+     * registering the same kind for the same agent collides with the host's
+     * adapter exactly as it would with another plugin's — two adapters on
+     * one agent's Slack would each answer every message.
+     */
+    claim(kind, agentIds) {
+        for (const agentId of agentIds) {
+            if (!this.claims.has(channelClaimKey(kind, agentId))) {
+                this.claims.set(channelClaimKey(kind, agentId), undefined);
+            }
+        }
+    }
+    /** Whether some adapter — the host's or a plugin's — already carries this agent on this kind. */
+    claimed(kind, agentId) {
+        return this.claims.has(channelClaimKey(kind, agentId));
+    }
+    list() {
+        return [...this.contributions];
+    }
+}
+/**
+ * A memory store that resolves which store serves an agent **per call**.
+ *
+ * The seam a host selects a contributed store through. The runner and the
+ * memory tools are built before any plugin has loaded, so the store they
+ * hold has to be one that can change its mind — and an agent-by-agent
+ * answer is what keeps a contributed store from being process-global.
+ * `reassertTrust` is forwarded only when the chosen store has it: a store
+ * that omitted it cannot be re-asserted, and this must not claim otherwise.
+ */
+export const createRoutedMemoryStore = (storeFor) => ({
+    append: (agentId, content, metadata, provenance) => storeFor(agentId).append(agentId, content, metadata, provenance),
+    list: (agentId, options) => storeFor(agentId).list(agentId, options),
+    search: (agentId, query, limit) => storeFor(agentId).search(agentId, query, limit),
+    forget: (agentId, entryId) => storeFor(agentId).forget(agentId, entryId),
+    audit: (agentId) => storeFor(agentId).audit(agentId),
+    async reassertTrust(agentId, entryId, trust) {
+        const store = storeFor(agentId);
+        if (!store.reassertTrust) {
+            return false;
+        }
+        return store.reassertTrust(agentId, entryId, trust);
+    },
+});
 export class PluginRegistry {
     plugins = [];
     register(plugin) {
@@ -1034,16 +1489,27 @@ export const memoryRegionHeading = (trust) => {
  * message started producing it. An entry with no label renders in the
  * `unknown` region — never as the agent's own conclusion.
  */
+/**
+ * Unicode's `Bidi_Control` property as a character-class fragment: the
+ * marks, the Arabic letter mark, the embeddings and overrides, and the
+ * isolates. Exported so every escaper spells out the same set — text that
+ * reads one way to a person and another to the model is the same trick
+ * whether it arrives in a memory entry, a Slack name, or a tool description.
+ */
+export const BIDI_CONTROL_CHARACTERS = '\\u061c\\u200e\\u200f\\u202a-\\u202e\\u2066-\\u2069';
+const CONTROL_CHARACTERS = new RegExp(`[\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029${BIDI_CONTROL_CHARACTERS}]`, 'g');
 /**
  * `text` on one line, every control character spelled out the way JSON
- * does (`\n`, `\u001b`), C1 controls and the Unicode line separators
- * included. The memory block and `stratus memory list` both frame an entry
- * by its line — `- ` under a region heading, an indent under an id — and a
- * fact holding a newline could otherwise start a line of its own that reads
- * as a heading, the trusted region's heading among them. Escaped rather
- * than dropped, so what is shown is still what is stored.
- */
-export const escapeControlCharacters = (text) => text.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, (character) => {
+ * does (`\n`, `\u001b`), C1 controls, the Unicode line separators and
+ * the bidi controls included. The memory block and `stratus memory list`
+ * both frame an entry by its line — `- ` under a region heading, an indent
+ * under an id — and a fact holding a newline could otherwise start a line
+ * of its own that reads as a heading, the trusted region's heading among
+ * them; a right-to-left override would make the line read differently to
+ * a person than to the model. Escaped rather than dropped, so what is
+ * shown is still what is stored.
+ */
+export const escapeControlCharacters = (text) => text.replace(CONTROL_CHARACTERS, (character) => {
     switch (character) {
         case '\n': return '\\n';
         case '\r': return '\\r';
@@ -1258,6 +1724,22 @@ export class AllowAllApprovalPolicy {
         return true;
     }
 }
+/**
+ * The `images` field of a user message, or nothing: a message that carried
+ * none has no field, so a transcript written before images existed and one
+ * written after read the same.
+ */
+const userImages = (images) => images !== undefined && images.length > 0 ? { images } : {};
+/**
+ * See `RunInput.addressed`: an image reaches the model as pixels, before
+ * and outside the text that frames what was said as somebody else's, so
+ * a turn nobody asked for takes none.
+ */
+const refuseUnaddressedImages = (input) => {
+    if (input.addressed === false && input.images !== undefined && input.images.length > 0) {
+        throw new Error('A turn nobody asked for cannot carry images: an image enters the prompt ahead of the frame that marks the message as somebody else\'s. Name the attachment in the message instead.');
+    }
+};
 /**
  * Thrown when a run is stopped by its abort signal. The session ends up
  * `failed` with this error's message as `lastError`, so an aborted turn is
@@ -1306,10 +1788,12 @@ export class AgentRunner {
     maxTurns;
     streaming;
     options;
+    imageReplayBudget;
     constructor(options) {
         this.options = options;
         this.bus = options.bus ?? new EventBus();
         this.store = options.store ?? new InMemorySessionStore();
+        this.imageReplayBudget = options.imageReplayBudget;
         this.tools = options.tools ?? new ToolRegistry();
         this.executor = options.executor ?? new DefaultExecutor();
         this.approvals = options.approvals ?? new AllowAllApprovalPolicy();
@@ -1332,23 +1816,28 @@ export class AgentRunner {
         await this.plugins.loadAll({ bus: this.bus, tools: this.tools });
     }
     async run(input) {
+        refuseUnaddressedImages(input);
         // The sender's trust is the turn's, not the session's: it is read here
         // and kept out of the persisted metadata, where a later reader would
         // take the first sender's label for every turn that follows.
         const { [SENDER_TRUST_METADATA_KEY]: _sender, ...persisted } = input.metadata ?? {};
         const senderTrust = senderTrustOf(input.metadata);
+        // The first stored turn is held to the window like every later one:
+        // a one-shot session is a row too.
+        const opening = {
+            id: `${input.sessionId}:user:1`,
+            role: 'user',
+            content: input.userMessage,
+            createdAt: new Date().toISOString(),
+            ...userImages(input.images),
+            ...(input.addressed === false ? { overheard: true } : {}),
+        };
+        omitImagesOutsideReplayBudget([opening], this.imageReplayBudget);
         const sessionInput = {
             id: input.sessionId,
             agent: input.agent,
             status: 'running',
-            messages: [
-                {
-                    id: `${input.sessionId}:user:1`,
-                    role: 'user',
-                    content: input.userMessage,
-                    createdAt: new Date().toISOString(),
-                },
-            ],
+            messages: [opening],
             // Labelled from the first write, whatever the dispatching surface
             // put in `metadata` under this key: the label is the runner's to
             // write, and a fresh session starts at the top of the lattice lowered
@@ -1399,6 +1888,7 @@ export class AgentRunner {
         }
     }
     async resume(input) {
+        refuseUnaddressedImages(input);
         const session = await this.store.get(input.sessionId);
         if (!session) {
             throw new Error(`Session not found: ${input.sessionId}`);
@@ -1428,7 +1918,15 @@ export class AgentRunner {
             role: 'user',
             content: input.userMessage,
             createdAt: new Date().toISOString(),
+            ...userImages(input.images),
+            // Marked like a message `observe` appended, because it is one: the
+            // difference is only that a turn runs on it, and every renderer
+            // frames it from the same mark.
+            ...(input.addressed === false ? { overheard: true } : {}),
         });
+        // Before the save below: the row that carries this turn is the row
+        // that stops carrying the pixels nothing can send any more.
+        omitImagesOutsideReplayBudget(session.messages, this.imageReplayBudget);
         // The sender is evaluated on EVERY turn, from this turn's metadata: a
         // thread keys one session for everyone in it, and an unauthorized
         // member's message lowers the session to `unknown` and leaves it there
@@ -1444,6 +1942,48 @@ export class AgentRunner {
         await this.bus.emit({ type: 'session.updated', sessionId: working.id, status: working.status });
         return this.executeTurns(working, input.signal);
     }
+    /**
+     * A message reaching the session with no turn run on it: something said
+     * in a conversation the agent is in, to somebody else. Appended and
+     * saved, so the next turn the agent does take has it in hand; no
+     * provider call, no reply, no status change, and its own event rather
+     * than `session.updated`, since nothing is running.
+     *
+     * Refused while a turn is in flight. A parked turn's transcript ends in
+     * a tool call awaiting its result, and a user message spliced in ahead
+     * of that result is a wire-format violation on the API path — the one
+     * shape `reconcileInterruptedToolCalls` exists to repair, and repairing
+     * it here would close a call a human is still deciding on. A host that
+     * serializes writes per session (the gateway's chain) only ever sees
+     * this for a turn parked across a restart, and says so rather than
+     * dropping the message silently.
+     */
+    async observe(input) {
+        const session = await this.store.get(input.sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${input.sessionId}`);
+        }
+        if (session.status === 'running' || session.status === 'pending_approval') {
+            throw new Error(`Session ${input.sessionId} has a turn in flight (${session.status}); a message cannot be overheard into it until the turn has finished.`);
+        }
+        session.messages.push({
+            id: `${session.id}:user:${session.messages.length + 1}`,
+            role: 'user',
+            content: input.message,
+            createdAt: new Date().toISOString(),
+            overheard: true,
+        });
+        // The speaker is judged like any sender: their words are in the
+        // transcript from here on, whether or not they were talking to the
+        // agent — which is exactly the case the label exists for.
+        await this.labelLegacySession(session);
+        await this.taint(session, senderTrustOf(input.metadata), 'sender');
+        await this.store.save(session);
+        const stored = await this.store.get(session.id);
+        const working = stored ?? session;
+        await this.bus.emit({ type: 'session.observed', sessionId: working.id, agentId: working.agent.id });
+        return working;
+    }
     /**
      * Appends a synthetic failed result directly after every tool call that
      * has none — the durable trace of a turn interrupted between the call's
@@ -1707,6 +2247,23 @@ export class AgentRunner {
                         toolCalls: [part.call],
                     });
                 }
+                if (response.parts.length === 0) {
+                    // Silence, recorded. Only a turn nobody asked for ends this way —
+                    // every provider refuses an empty answer on one somebody did —
+                    // and the decision has to leave a mark: a harness holding its own
+                    // history is sent every user message since the agent last spoke
+                    // (`latestUserMessagePrompt`), and without an assistant message
+                    // here the message this turn already judged would go again on
+                    // the next one, and again on the one after that. Empty text is
+                    // no reply (`latestTurnReply`) and no speaking (`lastSpokeAt`);
+                    // it is the boundary of a turn that happened.
+                    session.messages.push({
+                        id: `${session.id}:assistant:${session.messages.length + 1}`,
+                        role: 'assistant',
+                        content: '',
+                        createdAt: new Date().toISOString(),
+                    });
+                }
                 const sawToolCall = calls.length > 0;
                 await this.store.save(session);
                 await this.bus.emit({ type: 'provider.response', sessionId: session.id, parts: response.parts });
@@ -1754,6 +2311,26 @@ export class AgentRunner {
                     : caught)
                 : caught;
             const lastError = error instanceof Error ? error.message : String(error);
+            // Read off what the provider threw, not the normalized error: an
+            // abort replaces it with a fresh `RunAbortedError`, and a harness
+            // cancelled mid-turn — the watchdog's doing, most often — has the
+            // prompt just the same.
+            if (promptWasDelivered(caught) && isUnaddressedTurn(session)) {
+                // A turn nobody asked for whose prompt the harness took before it
+                // failed: the boundary goes in as if it had ended in silence, or
+                // `latestUserMessagePrompt` would send the harness this message
+                // again next time — the same double send the empty-answer
+                // boundary above closes, on the failure path. Only for such a
+                // turn: an addressed one that failed is retried by its sender
+                // with a new message, which is then the newest and the only one
+                // sent, as it always was.
+                session.messages.push({
+                    id: `${session.id}:assistant:${session.messages.length + 1}`,
+                    role: 'assistant',
+                    content: '',
+                    createdAt: new Date().toISOString(),
+                });
+            }
             session.status = 'failed';
             session.lastError = lastError;
             await this.store.save(session);