@stratusagent/core 0.11.3 → 0.11.5

package/dist/index.js

@@ -214,7 +214,19 @@ 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;
     }
@@ -577,6 +589,9 @@ const matchesGlobbedAllowlist = (name, allowlist, globSuffix) => allowlist.some(
     }
     return entry.endsWith(globSuffix) && name.startsWith(entry.slice(0, -1));
 });
+/** Every kind, in the order the tool description lists them. */
+export const MEMORY_ENTRY_KINDS = ['semantic', 'episodic', 'procedural', 'preference'];
+export const isMemoryEntryKind = (value) => typeof value === 'string' && MEMORY_ENTRY_KINDS.includes(value);
 /**
  * An entry's label as every consumer reads it: the recorded one, or
  * `unknown` when none was recorded. Never `agent` by default — see
@@ -595,12 +610,40 @@ export const MEMORY_ENTRY_MAX_BYTES = 4096;
  * several cap-size entries still fit (see `MEMORY_ENTRY_MAX_BYTES`).
  */
 export const MEMORY_READ_MAX_BYTES = 16384;
+/**
+ * The recall tool's name, defined here because the prompt's topic index
+ * tells the agent what to call — a block advertising a tool by a name the
+ * registry does not use would be a dead pointer. `@stratusagent/agents`
+ * builds the tool itself and re-exports this as `RECALL_TOOL_NAME`.
+ */
+export const MEMORY_RECALL_TOOL_NAME = 'memory.recall';
 /** Results a `search` returns when the caller names no limit. */
 export const MEMORY_RECALL_DEFAULT_LIMIT = 10;
 /** Ceiling a `search` limit is clamped to, whatever the caller asked for. */
 export const MEMORY_RECALL_MAX_LIMIT = 50;
-/** How many recent entries the runner injects into the system prompt. */
-export const MEMORY_INJECTION_LIMIT = 20;
+/**
+ * The pinned core's hard cap, in UTF-8 bytes of content. It **refuses
+ * rather than evicts**, on the same reasoning as the per-entry cap: a
+ * pinned set that silently drops its oldest member is a pin that does not
+ * mean anything.
+ */
+export const MEMORY_PINNED_MAX_BYTES = 2048;
+/**
+ * The topic index's budget, in UTF-8 bytes of rendered block. Roughly a
+ * thousand tokens: enough to tell the agent the shape of its own store,
+ * which is what turns `memory.recall` from a guess into a targeted read.
+ */
+export const MEMORY_INDEX_MAX_BYTES = 4096;
+/**
+ * The recency tail — deliberately smaller than the twenty entries that
+ * were the whole of injection before the pinned core and the topic index
+ * existed, so a cold store with nothing pinned and nothing indexed still
+ * behaves roughly as it did, and a warm one spends its budget on the two
+ * blocks that are correlated with what the agent knows.
+ */
+export const MEMORY_RECENCY_INJECTION_LIMIT = 8;
+/** Byte budget for the recency tail, applied like every other bounded read. */
+export const MEMORY_RECENCY_MAX_BYTES = 4096;
 const utf8Encoder = new TextEncoder();
 /** UTF-8 size of an entry's content — the unit both memory caps are stated in. */
 export const memoryContentByteLength = (content) => utf8Encoder.encode(content).length;
@@ -611,6 +654,32 @@ export const assertMemoryContentWithinCap = (content) => {
         throw new Error(`Memory entries are capped at ${MEMORY_ENTRY_MAX_BYTES} UTF-8 bytes and this fact is ${bytes}. Nothing was stored — remember a shorter fact instead.`);
     }
 };
+/**
+ * How many entities one fact may be filed under, and how much room their
+ * names get. `about` is model-written and would otherwise be the one
+ * unbounded field on an entry: the per-entry cap covers `content` alone, so
+ * without this a single `memory.remember` could write a megabyte of entity
+ * names into the record and into every store's search index. The prompt's
+ * topic block has its own budget and would survive it; the record would
+ * not, and the record is the thing that has to stay hand-editable.
+ *
+ * Small on purpose. A fact about a dozen things is a fact that has not been
+ * written down properly yet.
+ */
+export const MEMORY_ABOUT_MAX_KEYS = 12;
+export const MEMORY_ABOUT_MAX_BYTES = 512;
+/** Refuses, like the content cap, and for the same reason: a half-filed fact is worse than a refused one. */
+export const assertMemoryAboutWithinCap = (about) => {
+    if (about.length > MEMORY_ABOUT_MAX_KEYS) {
+        throw new Error(`A memory entry may name at most ${MEMORY_ABOUT_MAX_KEYS} entities in "about" and this one names ${about.length}. `
+            + 'Nothing was stored — file it under the few that matter, or remember it as more than one fact.');
+    }
+    const bytes = about.reduce((sum, key) => sum + memoryContentByteLength(key), 0);
+    if (bytes > MEMORY_ABOUT_MAX_BYTES) {
+        throw new Error(`The "about" keys of a memory entry are capped at ${MEMORY_ABOUT_MAX_BYTES} UTF-8 bytes and these are ${bytes}. `
+            + 'Nothing was stored — an entity name is a name, not a description.');
+    }
+};
 /**
  * The tokenizer both store implementations share: NFC-normalized,
  * case-folded, split on anything that is not a Unicode letter or digit.
@@ -620,18 +689,124 @@ export const assertMemoryContentWithinCap = (content) => {
  */
 export const tokenizeMemoryText = (text) => text.normalize('NFC').toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
 /**
- * Whether content matches a tokenized query: every query token must be
- * present as a whole token. A query that tokenized to nothing matches
- * nothing — recall with no searchable terms is a question that was not
- * asked, not a request for everything.
+ * An entry's `about` keys, cleaned the one way every consumer reads them:
+ * trimmed, empty ones dropped, duplicates collapsed case-insensitively
+ * with the first spelling kept. A hand-edited line whose `about` is not an
+ * array of strings contributes nothing rather than throwing — the record
+ * is the operator's to edit, and a bad key is not worth losing a fact over.
  */
-export const memoryQueryMatches = (content, queryTokens) => {
+export const memoryEntryAbout = (entry) => {
+    if (!Array.isArray(entry.about)) {
+        return [];
+    }
+    const seen = new Set();
+    const keys = [];
+    for (const raw of entry.about) {
+        if (typeof raw !== 'string') {
+            continue;
+        }
+        const key = raw.trim();
+        // Folded the way the tokenizer normalizes, so two spellings of one
+        // entity are one key here as they are one token to search.
+        const folded = key.normalize('NFC').toLowerCase();
+        if (key.length === 0 || seen.has(folded)) {
+            continue;
+        }
+        seen.add(folded);
+        keys.push(key);
+    }
+    return keys;
+};
+/**
+ * Everything about an entry a query is matched against: its content and its
+ * `about` keys, through the shared tokenizer.
+ *
+ * `about` participating is the point rather than an edge. An entry reading
+ * "it now uses Postgres" with `about: ["deploy pipeline"]` is listed under
+ * that topic in the prompt's index, and a store matching content alone
+ * would then miss the very query the listing invites — an alias in `about`
+ * against a pronoun in `content` is the case the field exists to serve.
+ * Written once here so the FTS `tokens` column and the in-memory filter
+ * cannot disagree about what a store holds.
+ */
+export const memoryEntryTokens = (entry) => [
+    ...tokenizeMemoryText(entry.content),
+    ...memoryEntryAbout(entry).flatMap(tokenizeMemoryText),
+];
+/**
+ * Whether an entry matches a tokenized query: every query token must be
+ * present as a whole token of its content or of one of its `about` keys. A
+ * query that tokenized to nothing matches nothing — recall with no
+ * searchable terms is a question that was not asked, not a request for
+ * everything.
+ */
+export const memoryQueryMatches = (entry, queryTokens) => {
     if (queryTokens.length === 0) {
         return false;
     }
-    const tokens = new Set(tokenizeMemoryText(content));
+    const tokens = new Set(memoryEntryTokens(entry));
     return queryTokens.every((token) => tokens.has(token));
 };
+// A bound that is not a parseable instant is no bound — a hand-edited line
+// reading `validUntil: "soon"` must not quietly retire the fact it is on.
+const validityInstant = (value) => {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? undefined : parsed;
+};
+/**
+ * One rule, both bounds: a fact holds from `validFrom` (inclusive) until
+ * `validUntil` (exclusive). Pure in the entry and the clock, so both store
+ * implementations compute the same answer from the record alone.
+ */
+export const memoryValidityAt = (entry, at) => {
+    const now = at.getTime();
+    const from = validityInstant(entry.validFrom);
+    if (from !== undefined && now < from) {
+        return 'not-yet-valid';
+    }
+    const until = validityInstant(entry.validUntil);
+    if (until !== undefined && now >= until) {
+        return 'expired';
+    }
+    return 'current';
+};
+/** Shorthand for the only status that is true now. */
+export const isMemoryEntryCurrent = (entry, at) => memoryValidityAt(entry, at) === 'current';
+/**
+ * The ids retired by supersession at a given instant, over one agent's
+ * un-tombstoned entries.
+ *
+ * An entry is retired exactly while a successor of it is *current*, which
+ * is the only reading that keeps supersession and validity from cancelling
+ * each other: a successor dated from next Monday retiring its predecessor
+ * today would leave neither fact available as true now — the old one
+ * retired, the new one excluded as not-yet-valid — so the agent forgets
+ * something it still believes and gains nothing for it.
+ *
+ * Two successors of the same entry both retire it, in either order, and
+ * both stay live. The invariant is the *retirement*, not a unique
+ * replacement: each successor is a fact the agent wrote, and retiring one
+ * to make the other unique would delete a write nobody asked to retract.
+ * Two live successors that disagree are a contradiction in content, which
+ * is the maintenance pass's job and not a storage race.
+ *
+ * Callers pass the agent's un-tombstoned entries, so forgetting a successor
+ * releases the entry it retired — a revision the agent took back leaves the
+ * fact it replaced standing, which is the recoverable direction in a store
+ * whose whole posture is that nothing is lost.
+ */
+export const supersededMemoryIdsAt = (entries, at) => {
+    const retired = new Set();
+    for (const entry of entries) {
+        if (typeof entry.supersedes === 'string' && entry.supersedes.length > 0 && isMemoryEntryCurrent(entry, at)) {
+            retired.add(entry.supersedes);
+        }
+    }
+    return retired;
+};
 /**
  * Recall order — newest first, ties on `createdAt` broken by entry id
  * ascending. The tie-break is not about frequency: without one, two
@@ -652,6 +827,8 @@ export const compareMemoryChronology = (a, b) => {
     }
     return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
 };
+export const MEMORY_RANKING_STRATEGIES = ['recency', 'relevance', 'hybrid'];
+export const isMemoryRankingStrategy = (value) => typeof value === 'string' && MEMORY_RANKING_STRATEGIES.includes(value);
 /** Clamp a caller-chosen search limit into the store's own bounds. */
 export const clampMemoryRecallLimit = (limit) => {
     if (limit === undefined || Number.isNaN(limit)) {
@@ -702,59 +879,395 @@ export const boundMemoryRead = (candidates, limit, maxBytes = MEMORY_READ_MAX_BY
  * presentation order are different things; conflating them is the bug this
  * helper exists so nobody writes three times.
  */
-export const boundMemoryList = (candidates, limit) => {
-    const bounded = boundMemoryRead(candidates, Math.max(1, Math.floor(limit)));
+export const boundMemoryList = (candidates, limit, maxBytes = MEMORY_READ_MAX_BYTES) => {
+    const bounded = boundMemoryRead(candidates, Math.max(1, Math.floor(limit)), maxBytes);
     bounded.entries.sort(compareMemoryChronology);
     return bounded;
 };
+/**
+ * The pinned set the record produces, and the rule both stores replay it
+ * by: **pins take effect in the order their records appear in the file,
+ * until the cap, and the remainder are recorded but inert.**
+ *
+ * The write path refusing an over-cap pin is the common case and stays the
+ * rule. This is for the race it cannot see: the CLI and the daemon build
+ * separate stores over the same file and coordinate by `O_APPEND` alone, so
+ * two processes pinning near the limit can both read the same total, both
+ * accept, and both append. Replay gives them one effective set instead of
+ * an injected slice that either overruns its budget or drops a pin by
+ * whichever order it happened to read.
+ *
+ * **Append order, not `(createdAt, id)`.** A timestamp is the wrong key for
+ * a budget: a pin written later with a skewed-earlier clock would sort
+ * ahead of a pin that is already effective and consume the budget out from
+ * under it, making an accepted pin inert after the fact and contradicting
+ * the refusal the cap promises. `O_APPEND` already supplies a total order
+ * no later writer can insert itself into. Recall ordering keeps its
+ * `(createdAt, id)` rule — presenting facts newest-first is about meaning,
+ * allocating a scarce budget is about arrival.
+ *
+ * Validity is deliberately *not* consulted here. The budget is a property
+ * of the record, so it must not change when a clock ticks past a
+ * `validUntil`; an out-of-window pin holds its place and is dropped from
+ * the rendered core by `selectMemoryInjection`, which is where "true now"
+ * is decided.
+ */
+export const applyMemoryPinBudget = (pinnedIds, contentBytesFor, maxBytes = MEMORY_PINNED_MAX_BYTES) => {
+    const effective = [];
+    const inert = [];
+    let bytes = 0;
+    for (const id of pinnedIds) {
+        const size = contentBytesFor(id);
+        if (size === undefined) {
+            // The entry is gone from the live set — forgotten, or never there.
+            // Its pin record stands in the file and costs nothing.
+            continue;
+        }
+        if (inert.length > 0 || bytes + size > maxBytes) {
+            // Once one pin overruns, everything behind it is inert too: "the
+            // remainder" is a prefix rule, so an effective set never depends on
+            // how large the *next* pin happens to be.
+            inert.push(id);
+            continue;
+        }
+        effective.push(id);
+        bytes += size;
+    }
+    return { effective, inert, bytes };
+};
+/**
+ * The topic index, built from `about` keys over the entries a store holds:
+ * not facts, but what the agent *knows about*. Counts and last-updated,
+ * ordered by count descending then name, so the block is stable across
+ * turns and the biggest topics survive the budget.
+ *
+ * Shared rather than per-store for the usual reason: two implementations
+ * building this differently would advertise different stores over the same
+ * record.
+ */
+export const collectMemoryTopics = (entries) => {
+    const topics = new Map();
+    for (const entry of entries) {
+        const trust = memoryEntryTrust(entry);
+        for (const key of memoryEntryAbout(entry)) {
+            // NFC before folding, the way `tokenizeMemoryText` normalizes: a
+            // composed and a decomposed `café` are one topic to search, and two
+            // topics here would render as duplicates with their counts split and
+            // spend the block's budget twice on the same thing.
+            const folded = key.normalize('NFC').toLowerCase();
+            const existing = topics.get(folded);
+            if (existing === undefined) {
+                topics.set(folded, { name: key, count: 1, lastUpdatedAt: entry.createdAt, trust });
+                continue;
+            }
+            existing.count += 1;
+            if (entry.createdAt > existing.lastUpdatedAt) {
+                existing.lastUpdatedAt = entry.createdAt;
+            }
+            existing.trust = leastTrusted(existing.trust, trust);
+        }
+    }
+    return [...topics.values()].sort((a, b) => b.count !== a.count ? b.count - a.count : a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+};
+/** Empty in all three blocks — what a host with no memory store injects. */
+export const emptyMemoryInjection = () => ({ pinned: [], topics: [], recent: [] });
+// The blank line between the intro and a region, and between regions.
+const TOPIC_BLOCK_SEPARATOR_BYTES = 2;
+/**
+ * Bound the three blocks against their budgets and keep them disjoint: a
+ * pinned fact already in context is not worth a second copy in the tail,
+ * and the tail is the block that shrinks, never the pinned core. The
+ * pinned set is never pushed out by volume — that is the whole reason it
+ * is a separate budget rather than a ranking bonus.
+ */
+export const selectMemoryInjection = (input) => {
+    const pinned = boundMemoryRead([...input.pinned], input.pinned.length, MEMORY_PINNED_MAX_BYTES)
+        .entries.sort(compareMemoryChronology);
+    const pinnedIds = new Set(pinned.map((entry) => entry.id));
+    const recent = boundMemoryList(input.recent.filter((entry) => !pinnedIds.has(entry.id)), MEMORY_RECENCY_INJECTION_LIMIT, MEMORY_RECENCY_MAX_BYTES).entries;
+    const topics = [];
+    // Measured as the block is *rendered*, not as the topics are stored:
+    // every control character expands six-for-one on the way out, and the
+    // intro and the per-trust region headings are part of what the prompt
+    // pays for. The scaffolding is reserved up front from the labels present
+    // in the whole candidate list, which can only over-reserve — selecting
+    // fewer topics never adds a region.
+    let scaffoldBytes = memoryContentByteLength(MEMORY_INDEX_INTRO) + TOPIC_BLOCK_SEPARATOR_BYTES;
+    for (const trust of new Set(input.topics.map((topic) => topic.trust))) {
+        scaffoldBytes += memoryContentByteLength(memoryRegionHeading(trust)) + TOPIC_BLOCK_SEPARATOR_BYTES;
+    }
+    let topicBytes = scaffoldBytes;
+    for (const topic of input.topics) {
+        const size = memoryContentByteLength(renderMemoryTopicLine(topic)) + 1;
+        // A line no selection could ever admit — an `about` key long enough to
+        // fill the block beside the scaffolding on its own, which import and a
+        // hand-edited record both allow — is skipped rather than allowed to end
+        // the scan, the same way `boundMemoryRead` skips an entry over its
+        // budget. Breaking on it would cost the whole topic index over one
+        // oversized name, and the index is what turns `memory.recall` from a
+        // guess into a targeted read.
+        if (scaffoldBytes + size > MEMORY_INDEX_MAX_BYTES) {
+            continue;
+        }
+        // Merely running out of room does end it, also like `boundMemoryRead`:
+        // the block stays the top of the ranking rather than whatever happened
+        // to pack into the remainder.
+        if (topicBytes + size > MEMORY_INDEX_MAX_BYTES) {
+            break;
+        }
+        topics.push(topic);
+        topicBytes += size;
+    }
+    return { pinned, topics, recent };
+};
+/**
+ * Read the three blocks out of a store. The policy — what counts as
+ * current, what the budgets are, which block a fact lands in — lives in
+ * `selectMemoryInjection` and the store's own `list`, so a store that
+ * implements none of the optional methods still injects a recency tail and
+ * nothing is special-cased at the call site.
+ */
+export const buildMemoryInjection = async (store, agentId) => {
+    const [pinned, topics, recent] = await Promise.all([
+        store.pinned ? store.pinned(agentId) : Promise.resolve([]),
+        store.topics ? store.topics(agentId) : Promise.resolve([]),
+        store.list(agentId, { limit: MEMORY_RECENCY_INJECTION_LIMIT }).then((result) => result.entries),
+    ]);
+    return selectMemoryInjection({ pinned, topics, recent });
+};
+/**
+ * The three blocks as a request may carry them: a bare array is the recency
+ * tail alone, which is what `memory` meant before pinning and the topic
+ * index existed and is still what a host building a request by hand may
+ * pass.
+ */
+export const asMemoryInjection = (memory) => {
+    if (memory === undefined) {
+        return emptyMemoryInjection();
+    }
+    return Array.isArray(memory)
+        ? { pinned: [], topics: [], recent: [...memory] }
+        : memory;
+};
+/** Every entry a turn injects, in the order they reach the prompt — what taints the session. */
+export const memoryInjectionEntries = (injection) => {
+    const blocks = asMemoryInjection(injection);
+    return [...blocks.pinned, ...blocks.recent];
+};
+/**
+ * The refusal an over-cap pin says, naming the cap. An operator who cannot
+ * see why a pin bounced will assume it worked, which is the failure the
+ * refuse-never-evict rule exists to avoid in the first place.
+ */
+export const pinnedCapRefusal = (heldBytes, wantedBytes) => `The pinned core is capped at ${MEMORY_PINNED_MAX_BYTES} UTF-8 bytes and holds ${heldBytes}; `
+    + `this entry needs ${wantedBytes}. Nothing was pinned and nothing was dropped — unpin something first.`;
+/**
+ * The other refusal, and the one a byte total cannot express: an inert pin
+ * already stands in the record.
+ *
+ * `applyMemoryPinBudget` is a **prefix** rule, so once one pin overruns the
+ * cap nothing recorded after it takes effect, whatever its size. A write
+ * path that tested only the effective byte total would therefore accept a
+ * small pin, append it, and report success for something `pinned` omits on
+ * the very next read — an eviction wearing the refusal's clothes, which is
+ * the one thing the cap promises cannot happen. The blocking id is named
+ * because it is the only thing the operator can act on: the effective set
+ * is under the cap and unpinning from *it* frees nothing.
+ */
+export const pinnedInertRefusal = (blockingId) => `The pinned core is a prefix of the pins in the order they were made, and the pin on ${blockingId} `
+    + `overran the ${MEMORY_PINNED_MAX_BYTES}-byte cap — nothing recorded after it takes effect. `
+    + `Nothing was pinned: unpin ${blockingId} first.`;
+/**
+ * The write-path half of the per-agent boundary, shared by every store: an
+ * id a new record names must resolve to a live entry the caller owns
+ * *before* anything is appended.
+ *
+ * This is a security requirement rather than input hygiene. A store's
+ * forgotten set is computed from the record without an agent filter, so a
+ * writer that skipped this would let agent A retire agent B's memory by
+ * naming its id — gone from B's `list`, its `search`, and its prompt, with
+ * B's own `forget` never called.
+ */
+export const assertSupersedableMemoryEntry = (live, entryId) => {
+    if (!live.some((entry) => entry.id === entryId)) {
+        throw new Error(`No live memory entry with id ${entryId} belongs to this agent, so nothing was superseded and nothing was stored. `
+            + 'memory.recall shows the ids you can supersede.');
+    }
+};
+/**
+ * An entry's optional fields as they are safe to read back from a record
+ * nobody validated — a hand-edited line, an imported file, a newer build's
+ * output. A field of the wrong shape is dropped rather than thrown over:
+ * the record is the operator's to edit, and a bad `about` is not worth
+ * losing a fact for. Written once so the file store's parser and the import
+ * path cannot disagree about what a line means.
+ */
+export const memoryEntryFields = (value) => {
+    const raw = value;
+    const about = memoryEntryAbout(value);
+    return {
+        ...(isMemoryEntryKind(raw.kind) ? { kind: raw.kind } : {}),
+        ...(about.length > 0 ? { about } : {}),
+        ...(typeof raw.validFrom === 'string' ? { validFrom: raw.validFrom } : {}),
+        ...(typeof raw.validUntil === 'string' ? { validUntil: raw.validUntil } : {}),
+        ...(typeof raw.supersedes === 'string' && raw.supersedes.length > 0 ? { supersedes: raw.supersedes } : {}),
+    };
+};
+/**
+ * One entry as an import should store it: re-keyed to the importing agent,
+ * optional fields validated, and `usage` dropped — usage is an observation
+ * about reading this install did, never something a file carries in.
+ */
+export const importableMemoryEntry = (entry, agentId) => ({
+    id: entry.id,
+    agentId,
+    content: entry.content,
+    createdAt: entry.createdAt,
+    ...memoryEntryFields(entry),
+    ...(entry.metadata ? { metadata: entry.metadata } : {}),
+    ...(isTrustLevel(entry.trust) ? { trust: entry.trust } : {}),
+    ...(entry.origin ? { origin: entry.origin } : {}),
+});
 export class InMemoryAgentMemoryStore {
     entries = new Map();
+    /**
+     * The pin lane, per agent, in append order — the same total order the
+     * file store gets from `O_APPEND`, and for the same reason: a budget is
+     * allocated by arrival, never by timestamp. A pin already held is not
+     * re-appended, so re-pinning cannot move an entry to the back.
+     */
+    pins = new Map();
+    /**
+     * Keyed by (agent, entry), never by entry alone: `importEntries`
+     * preserves ids while re-keying entries, so two agents legitimately hold
+     * the same id and one agent's reads must not move the other's counters.
+     */
+    usage = new Map();
+    /**
+     * Every id this store holds, minted or imported. `append` skips past the
+     * ones already taken, because an import that preserved `a:memory:1` and
+     * left the counter at zero would mint that id again — and two entries
+     * sharing an id are indistinguishable to tombstones, supersession, pins,
+     * and usage alike.
+     */
+    takenIds = new Set();
     counter = 0;
     now;
     // `now` is a test seam: the ordering tie-break only shows itself when two
-    // entries share a createdAt, which a real clock makes non-deterministic.
+    // entries share a createdAt, which a real clock makes non-deterministic —
+    // and so does anything asserting a validity window against a fixed date.
     constructor(options = {}) {
         this.now = options.now ?? (() => new Date());
     }
-    async append(agentId, content, metadata, provenance) {
+    async append(agentId, content, options = {}) {
         assertMemoryContentWithinCap(content);
-        this.counter += 1;
+        // Resolved against this agent's own live set before anything is
+        // recorded: the per-agent boundary is the access model the whole store
+        // rests on, and a successor naming a stranger's id would retire it.
+        if (options.supersedes !== undefined) {
+            assertSupersedableMemoryEntry(this.live(agentId, this.now()), options.supersedes);
+        }
+        const about = memoryEntryAbout(options);
+        assertMemoryAboutWithinCap(about);
+        let id;
+        do {
+            this.counter += 1;
+            id = `${agentId}:memory:${this.counter}`;
+        } while (this.takenIds.has(id));
+        this.takenIds.add(id);
         const entry = {
-            id: `${agentId}:memory:${this.counter}`,
+            id,
             agentId,
             content,
             createdAt: this.now().toISOString(),
-            ...(metadata ? { metadata } : {}),
-            ...(provenance ? { trust: provenance.trust } : {}),
-            ...(provenance?.origin ? { origin: provenance.origin } : {}),
+            ...(options.kind !== undefined ? { kind: options.kind } : {}),
+            ...(about.length > 0 ? { about } : {}),
+            ...(options.validFrom !== undefined ? { validFrom: options.validFrom } : {}),
+            ...(options.validUntil !== undefined ? { validUntil: options.validUntil } : {}),
+            ...(options.supersedes !== undefined ? { supersedes: options.supersedes } : {}),
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+            ...(options.provenance ? { trust: options.provenance.trust } : {}),
+            ...(options.provenance?.origin ? { origin: options.provenance.origin } : {}),
         };
         const existing = this.entries.get(agentId) ?? [];
         existing.push(entry);
         this.entries.set(agentId, existing);
         return { ...entry };
     }
-    live(agentId) {
-        return (this.entries.get(agentId) ?? [])
+    /** Not tombstoned and not superseded by a successor that is current at `at`. */
+    live(agentId, at) {
+        const kept = (this.entries.get(agentId) ?? [])
             .filter((entry) => entry.forgottenAt === undefined)
             .map(({ forgottenAt: _unused, ...entry }) => entry);
+        const superseded = supersededMemoryIdsAt(kept, at);
+        return kept.filter((entry) => !superseded.has(entry.id));
     }
     async list(agentId, options = {}) {
-        const live = this.live(agentId);
+        const at = this.now();
+        const live = options.validity === 'all'
+            ? this.live(agentId, at)
+            : this.live(agentId, at).filter((entry) => isMemoryEntryCurrent(entry, at));
         if (options.limit === undefined) {
             return { entries: live.sort(compareMemoryChronology), truncated: false };
         }
         return boundMemoryList(live, options.limit);
     }
-    async search(agentId, query, limit) {
+    async search(agentId, query, options = {}) {
         const tokens = tokenizeMemoryText(query);
+        // `recency` is the only ordering this store implements; a caller asking
+        // for another gets it, and is told so, rather than an error.
+        const strategy = 'recency';
         if (tokens.length === 0) {
-            return { entries: [], truncated: false };
+            return { entries: [], truncated: false, strategy };
+        }
+        const matches = this.live(agentId, this.now()).filter((entry) => memoryQueryMatches(entry, tokens));
+        const bounded = boundMemoryRead(matches, clampMemoryRecallLimit(options.limit));
+        // Counted, then reported, for the entries actually returned — usage is
+        // meant to say what reached a prompt, and only a `search` carries it:
+        // `list` reads the record, where these counters deliberately are not.
+        const counted = this.noteRecalled(agentId, bounded.entries);
+        return {
+            entries: bounded.entries.map((entry) => {
+                const usage = counted.get(entry.id);
+                return usage === undefined ? entry : { ...entry, usage };
+            }),
+            truncated: bounded.truncated,
+            strategy,
+        };
+    }
+    // Usage counters are an observation about reading, not a fact the agent
+    // learned: they live beside the record here the way they live in the file
+    // store's index, and nothing ranks or deletes on them yet.
+    usageKey(agentId, entryId) {
+        return `${agentId}\u0000${entryId}`;
+    }
+    noteRecalled(agentId, entries) {
+        const at = this.now().toISOString();
+        const counted = new Map();
+        for (const entry of entries) {
+            const key = this.usageKey(agentId, entry.id);
+            const previous = this.usage.get(key);
+            const usage = { recallCount: (previous?.recallCount ?? 0) + 1, lastRecalledAt: at };
+            this.usage.set(key, usage);
+            counted.set(entry.id, usage);
+        }
+        return counted;
+    }
+    /**
+     * The entry a mutation may touch: live, which means un-tombstoned *and*
+     * not superseded. Resolving against the raw array instead would let an
+     * agent forget a predecessor a current successor retired — and forgetting
+     * that successor is documented to release it, which a tombstone on the
+     * predecessor would then silently prevent.
+     */
+    mutable(agentId, entryId) {
+        if (!this.live(agentId, this.now()).some((entry) => entry.id === entryId)) {
+            return undefined;
         }
-        const matches = this.live(agentId).filter((entry) => memoryQueryMatches(entry.content, tokens));
-        return boundMemoryRead(matches, clampMemoryRecallLimit(limit));
+        return (this.entries.get(agentId) ?? []).find((candidate) => candidate.id === entryId && candidate.forgottenAt === undefined);
     }
     async forget(agentId, entryId) {
-        const entry = (this.entries.get(agentId) ?? []).find((candidate) => candidate.id === entryId && candidate.forgottenAt === undefined);
+        const entry = this.mutable(agentId, entryId);
         if (!entry) {
             return false;
         }
@@ -765,13 +1278,89 @@ export class InMemoryAgentMemoryStore {
         return (this.entries.get(agentId) ?? []).map((entry) => ({ ...entry })).sort(compareMemoryChronology);
     }
     async reassertTrust(agentId, entryId, trust) {
-        const entry = (this.entries.get(agentId) ?? []).find((candidate) => candidate.id === entryId && candidate.forgottenAt === undefined);
+        const entry = this.mutable(agentId, entryId);
         if (!entry) {
             return false;
         }
         entry.trust = trust;
         return true;
     }
+    /**
+     * Allocated over un-tombstoned entries, never the live view: the budget
+     * is a property of the record and must not move when a successor's
+     * window opens or a clock ticks. Sizing it from the live set would free a
+     * superseded pin's bytes, admit a later pin into the space, and make that
+     * later pin inert the moment the successor was forgotten.
+     */
+    pinBudget(agentId) {
+        const allocated = new Map((this.entries.get(agentId) ?? [])
+            .filter((entry) => entry.forgottenAt === undefined)
+            .map(({ forgottenAt: _unused, ...entry }) => [entry.id, entry]));
+        const budget = applyMemoryPinBudget(this.pins.get(agentId) ?? [], (id) => (allocated.has(id) ? memoryContentByteLength(allocated.get(id).content) : undefined));
+        return { effective: budget.effective, inert: budget.inert, bytes: budget.bytes, allocated };
+    }
+    async pin(agentId, entryId) {
+        const { effective, inert, bytes, allocated } = this.pinBudget(agentId);
+        // Pinnable means live; the budget above is a different question.
+        const entry = this.live(agentId, this.now()).find((candidate) => candidate.id === entryId);
+        if (!entry || !allocated.has(entryId)) {
+            throw new Error(`No live memory entry with id ${entryId} belongs to this agent — nothing was pinned.`);
+        }
+        if (effective.includes(entryId)) {
+            return { pinned: true, bytes };
+        }
+        if (inert[0] !== undefined) {
+            return { pinned: false, reason: pinnedInertRefusal(inert[0]), bytes };
+        }
+        const size = memoryContentByteLength(entry.content);
+        if (bytes + size > MEMORY_PINNED_MAX_BYTES) {
+            return { pinned: false, reason: pinnedCapRefusal(bytes, size), bytes };
+        }
+        this.pins.set(agentId, [...(this.pins.get(agentId) ?? []), entryId]);
+        return { pinned: true, bytes: bytes + size };
+    }
+    async unpin(agentId, entryId) {
+        const pins = this.pins.get(agentId) ?? [];
+        if (!pins.includes(entryId)) {
+            return false;
+        }
+        this.pins.set(agentId, pins.filter((id) => id !== entryId));
+        return true;
+    }
+    async pinned(agentId, options = {}) {
+        const at = this.now();
+        const { effective, allocated } = this.pinBudget(agentId);
+        const pins = effective.map((id) => allocated.get(id)).filter((entry) => entry !== undefined);
+        if (options.include === 'allocated') {
+            return pins.sort(compareMemoryChronology);
+        }
+        const live = new Set(this.live(agentId, at).map((entry) => entry.id));
+        return pins
+            .filter((entry) => live.has(entry.id) && isMemoryEntryCurrent(entry, at))
+            .sort(compareMemoryChronology);
+    }
+    async topics(agentId) {
+        const at = this.now();
+        return collectMemoryTopics(this.live(agentId, at).filter((entry) => isMemoryEntryCurrent(entry, at)));
+    }
+    async importEntries(agentId, entries) {
+        const existing = this.entries.get(agentId) ?? [];
+        const held = new Set(existing.map((entry) => entry.id));
+        const skipped = [];
+        let imported = 0;
+        for (const entry of entries) {
+            if (held.has(entry.id)) {
+                skipped.push(entry.id);
+                continue;
+            }
+            held.add(entry.id);
+            this.takenIds.add(entry.id);
+            existing.push({ ...importableMemoryEntry(entry, agentId) });
+            imported += 1;
+        }
+        this.entries.set(agentId, existing);
+        return { imported, skipped };
+    }
 }
 /**
  * The allowlist half of every `CredentialResolver`, so a second
@@ -860,6 +1449,16 @@ export const totalTokenUsage = (records) => {
     }
     return reported ? total : undefined;
 };
+/**
+ * The transcript a provider should send: the request's window when it has
+ * one, the whole session otherwise.
+ *
+ * One implementation because there is one rule, and because the wrong
+ * answer is silent — an adapter reading `session.messages` directly still
+ * works, it just ignores the floor and sends the request that was already
+ * refused.
+ */
+export const transcriptOf = (request) => request.messages ?? request.session.messages;
 /**
  * What a scrubbed subprocess inherits by name when its operator granted
  * nothing else — the replacement-environment treatment `tool-shell`
@@ -978,6 +1577,36 @@ export const promptWasDelivered = (error) => typeof error === 'object' && error
  * 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.';
+/**
+ * What the last turn of a message is told, once the message has used every
+ * tool turn `maxTurns` allows it.
+ *
+ * The alternative is what this replaced: the turn failed with "exceeded the
+ * maximum of 8 provider turns", every step it had taken sat in the
+ * transcript unsummarized, and the person got an error for work that had
+ * mostly succeeded. A limit on how far one message may run is a check-in
+ * point, not a failure, so the agent says where it got to and the next
+ * message carries on — the session keeps everything the turns did.
+ *
+ * Sent as the newest message of the request's window, never saved: it is
+ * the runtime speaking for one call, and a transcript that kept it would
+ * read to every later turn as something the person said.
+ */
+export const TURN_LIMIT_NOTE = 'You have used every step this message allows, so you cannot call any more tools on it. Reply now, in words: say what you did, what you found, and what is left. If the work is unfinished, end by saying that replying "continue" picks it up from here.';
+/** The wrap-up note as a message, for the request's window only. */
+const turnLimitNoteFor = (session) => ({
+    id: `${session.id}:turn-limit`,
+    role: 'user',
+    content: TURN_LIMIT_NOTE,
+    createdAt: new Date().toISOString(),
+});
+/**
+ * What a turn that could not wrap up fails with. Names the setting because
+ * the person reading it is the one who can raise it, and "exceeded the
+ * maximum" alone left them to find it in the docs.
+ */
+const turnLimitMessage = (maxTurns) => `Session exceeded the maximum of ${maxTurns} provider turns. `
+    + 'Raise maxTurns in ~/.stratus/config.json for agents that do long multi-step work, or reply to carry on from here.';
 /** Reads the checkpoint off a session, if it is parked. */
 export const readPendingApproval = (session) => {
     const raw = session.metadata?.[PENDING_APPROVAL_METADATA_KEY];
@@ -1052,6 +1681,174 @@ 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 memory store contributed by a plugin. Every `AgentMemoryStore` method
+ * takes the agent id, and that is what makes a contributed store
+ * per-agent-resolvable rather than process-global: a plugin that closed
+ * over one agent at setup would hand every agent the first agent's
+ * memories, the way a `tool-fs` that cached its roots would hand every
+ * agent the first agent's files.
+ */
+/**
+ * The revision of `AgentMemoryStore` a contributed store is built against.
+ *
+ * Bumped when the contract changes shape in a way a plugin compiled against
+ * the old one cannot satisfy — which it *silently* cannot, because the
+ * change that matters here is the shape of an argument rather than the
+ * number of them. A v1 store's `search(agentId, query, limit)` still
+ * accepts three arguments and still returns entries when the host hands it
+ * an options object; it just binds `{ limit: 10 }` where a number belonged,
+ * and answers with an unbounded read or none at all. No runtime check can
+ * tell the two apart from the function, so the plugin declares it.
+ *
+ * - **1** — `append(agentId, content, metadata?, provenance?)` and
+ *   `search(agentId, query, limit?)`, the shape before 29.
+ * - **2** — `append(agentId, content, options?)` and
+ *   `search(agentId, query, options?)`, plus the optional `pin`, `unpin`,
+ *   `pinned`, `topics`, and `importEntries`.
+ */
+export const MEMORY_STORE_CONTRACT_VERSION = 2;
+/**
+ * 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.
+ * Every optional method is forwarded only when the chosen store has it: a
+ * store that omitted one cannot do that thing, and this must not claim
+ * otherwise. The routed store declares them all, because which store
+ * serves an agent is not known until the call — so the honest answer for a
+ * store that lacks one is the same answer the seam's own default gives
+ * (nothing pinned, no topics, no re-assertion).
+ */
+export const createRoutedMemoryStore = (storeFor) => ({
+    append: (agentId, content, options) => storeFor(agentId).append(agentId, content, options),
+    list: (agentId, options) => storeFor(agentId).list(agentId, options),
+    search: (agentId, query, options) => storeFor(agentId).search(agentId, query, options),
+    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);
+    },
+    async pin(agentId, entryId) {
+        const store = storeFor(agentId);
+        if (!store.pin) {
+            return { pinned: false, reason: 'This memory store does not support pinning.', bytes: 0 };
+        }
+        return store.pin(agentId, entryId);
+    },
+    async unpin(agentId, entryId) {
+        const store = storeFor(agentId);
+        return store.unpin ? store.unpin(agentId, entryId) : false;
+    },
+    async pinned(agentId, options) {
+        const store = storeFor(agentId);
+        return store.pinned ? store.pinned(agentId, options) : [];
+    },
+    async topics(agentId) {
+        const store = storeFor(agentId);
+        return store.topics ? store.topics(agentId) : [];
+    },
+    async importEntries(agentId, entries) {
+        const store = storeFor(agentId);
+        if (!store.importEntries) {
+            throw new Error('This memory store cannot import entries.');
+        }
+        return store.importEntries(agentId, entries);
+    },
+});
 export class PluginRegistry {
     plugins = [];
     register(plugin) {
@@ -1356,26 +2153,26 @@ export const memoryRegionHeading = (trust) => {
     }
 };
 /**
- * The memory block, one region per trust label present, most trusted
- * first, entries in the order given within each.
- *
- * The invariant this enforces: nothing in the prompt derived from an entry
- * renders under a higher label than that entry carries. Stated over the
- * whole ordering rather than over `external` alone, because `unknown`
- * stopped being only a legacy artifact the moment an unauthorized sender's
- * 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';
@@ -1383,24 +2180,82 @@ export const escapeControlCharacters = (text) => text.replace(/[\u0000-\u001f\u0
         default: return `\\u${character.codePointAt(0).toString(16).padStart(4, '0')}`;
     }
 });
-export const renderMemorySection = (memory) => {
-    if (!memory || memory.length === 0) {
-        return undefined;
-    }
+/**
+ * A run of lines grouped one region per trust label present, most trusted
+ * first, in the order given within each.
+ *
+ * The invariant this enforces: nothing in the prompt derived from an entry
+ * renders under a higher label than that entry carries. Stated over the
+ * whole ordering rather than over `external` alone, because `unknown`
+ * stopped being only a legacy artifact the moment an unauthorized sender's
+ * message started producing it. An entry with no label renders in the
+ * `unknown` region — never as the agent's own conclusion. It applies to the
+ * topic index as much as to facts: an entity name an `external` entry
+ * supplied is still a stranger's words.
+ */
+const renderTrustRegions = (items, trustOf, lineOf) => {
     const regions = [];
     for (const trust of TRUST_LEVELS) {
-        const entries = memory.filter((entry) => memoryEntryTrust(entry) === trust);
-        if (entries.length === 0) {
+        const matching = items.filter((item) => trustOf(item) === trust);
+        if (matching.length === 0) {
             continue;
         }
-        // One line per fact, so the region a fact sits under is the region it
+        // One line per item, so the region a fact sits under is the region it
         // was filed under: a page's text that ends in a newline and a copy of
         // the operator's heading would otherwise open a forged trusted region
         // inside the external one.
-        const facts = entries.map((entry) => `- ${escapeControlCharacters(entry.content)}`).join('\n');
-        regions.push(`${memoryRegionHeading(trust)}\n${facts}`);
+        regions.push(`${memoryRegionHeading(trust)}\n${matching.map(lineOf).join('\n')}`);
+    }
+    return regions;
+};
+/** What the pinned core and the topic index say they are, before their regions. */
+const MEMORY_PINNED_INTRO = 'Kept in front of you on purpose — the facts you or your operator pinned:';
+const MEMORY_INDEX_INTRO = `What your long-term memory holds, by topic — a count and when each last changed, not the facts themselves. Use ${MEMORY_RECALL_TOOL_NAME} with a topic name to read them:`;
+const MEMORY_RECENT_INTRO = 'Recently remembered:';
+// Both the name and the date are escaped, because both come off an entry
+// and a hand-edited `createdAt` is as capable of carrying a newline as a
+// fact is — a topic line that opened a line of its own could forge the
+// heading of a more trusted region, which is the whole reason this block
+// renders one item per line.
+const renderMemoryTopicLine = (topic) => `- ${escapeControlCharacters(topic.name)} (${topic.count} fact${topic.count === 1 ? '' : 's'},`
+    + ` last ${escapeControlCharacters(topic.lastUpdatedAt.slice(0, 10))})`;
+/**
+ * The memory block: the pinned core, the topic index, and the recency tail,
+ * each grouped into trust regions, joined into **one** section.
+ *
+ * One section rather than three is a requirement rather than a formatting
+ * preference. An adapter that places the volatile section separately finds
+ * it with `parts.find((part) => part.kind === 'memory')` and strips it with
+ * the matching filter, so three sections sharing the kind would send the
+ * first to the tail and drop the other two from the request entirely —
+ * and three new kinds would leave them on the cached prefix, which is
+ * exactly what memory was moved off.
+ *
+ * A bare array is accepted and read as the recency tail alone: that is what
+ * `memory` meant before the three blocks existed, and a provider test or a
+ * host building a request by hand should not have to know about pinning.
+ */
+export const renderMemorySection = (memory) => {
+    if (memory === undefined) {
+        return undefined;
     }
-    return regions.join('\n\n');
+    const injection = asMemoryInjection(memory);
+    const blocks = [];
+    const fact = (entry) => `- ${escapeControlCharacters(entry.content)}`;
+    const push = (intro, regions) => {
+        if (regions.length > 0) {
+            blocks.push(`${intro}\n\n${regions.join('\n\n')}`);
+        }
+    };
+    push(MEMORY_PINNED_INTRO, renderTrustRegions(injection.pinned, memoryEntryTrust, fact));
+    push(MEMORY_INDEX_INTRO, renderTrustRegions(injection.topics, (topic) => topic.trust, renderMemoryTopicLine));
+    // The tail keeps the bare heading it has always had when it is the only
+    // block, so a cold store's prompt reads exactly as it did before.
+    if (injection.recent.length > 0) {
+        const regions = renderTrustRegions(injection.recent, memoryEntryTrust, fact);
+        blocks.push(blocks.length === 0 ? regions.join('\n\n') : `${MEMORY_RECENT_INTRO}\n\n${regions.join('\n\n')}`);
+    }
+    return blocks.length > 0 ? blocks.join('\n\n') : undefined;
 };
 /**
  * The skills block: one line per enabled skill — id, name, and the
@@ -1606,6 +2461,163 @@ const refuseUnaddressedImages = (input) => {
         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 by a provider when the request did not fit the model's context
+ * window — the transcript, not the answer, is what was too long.
+ *
+ * A distinct type because it is the one provider failure the kernel can do
+ * something about. Everything else a provider throws is final; this one
+ * says "the same request will never work, a shorter one might", and the
+ * runner answers by sending less history (see `raiseContextFloor`).
+ *
+ * Providers opt in. Recognising it means matching a vendor's own wording
+ * for a 400, which only the adapter can do — and a harness provider that
+ * manages its own context (`provider-claude-code`, `provider-codex`) has
+ * nothing to report, because the transcript it sends is not ours to
+ * shorten. A provider that never throws this behaves exactly as it did.
+ */
+export class ContextOverflowError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ContextOverflowError';
+    }
+}
+/**
+ * How many of a session's oldest messages are no longer sent to the
+ * provider.
+ *
+ * Durable, and **monotonic** like the trust label: a transcript only grows,
+ * so a floor that has had to rise once would have to rise again on the next
+ * turn, and re-discovering that costs a rejected request every time. Raised
+ * only by `raiseContextFloor`, never lowered — a conversation does not get
+ * shorter.
+ *
+ * It bounds what is *sent*, never what is stored. The transcript is the
+ * record of what happened and stays whole on disk; this is a window onto
+ * its tail. `stratus session rollover` is still the way to actually leave a
+ * conversation behind.
+ */
+export const CONTEXT_FLOOR_METADATA_KEY = 'contextFloor';
+/** The stored floor, or 0 for a session that has never overflowed. */
+export const contextFloorOf = (session) => {
+    const stored = session.metadata?.[CONTEXT_FLOOR_METADATA_KEY];
+    return typeof stored === 'number' && Number.isInteger(stored) && stored > 0 ? stored : 0;
+};
+/**
+ * The note that stands in for the messages a floor cut away, prefixed to
+ * the oldest message the model still sees.
+ *
+ * Said rather than done silently, for the reason every other cut in this
+ * codebase is announced: a model that cannot tell a conversation that
+ * started here from one that was trimmed will answer as though the earlier
+ * turns never happened, and confidently.
+ */
+export const droppedTurnsNote = (count) => `[${count} earlier message${count === 1 ? '' : 's'} in this conversation ${count === 1 ? 'is' : 'are'} not shown: `
+    + 'it grew past what fits in one request. Say so if you are asked about something from before this point, '
+    + 'rather than answering as though the conversation started here.]';
+/**
+ * The index of the first message at or after `from` that a request may
+ * begin with, or undefined when there is none.
+ *
+ * A window has to start on a `user` message: the wire format requires it,
+ * and more importantly a `tool` result whose `tool_use` was cut away is a
+ * request every provider rejects — which would turn one overflow into a
+ * permanent failure of a different kind. The runner only ever writes a
+ * user message at a turn boundary (`observe` refuses to splice one into a
+ * turn in flight, exactly so this holds), so a user message is always a
+ * safe cut and no pair is ever split.
+ */
+const nextTurnBoundary = (messages, from) => {
+    for (let index = Math.max(0, from); index < messages.length; index += 1) {
+        if (messages[index]?.role === 'user') {
+            return index;
+        }
+    }
+    return undefined;
+};
+/**
+ * The index of the LAST message at or after `from` that a request may begin
+ * with, or undefined when there is none — `nextTurnBoundary`'s counterpart,
+ * for narrowing as far as the transcript allows rather than to a midpoint
+ * that may have no boundary after it.
+ */
+const lastTurnBoundary = (messages, from) => {
+    for (let index = messages.length - 1; index >= Math.max(0, from); index -= 1) {
+        if (messages[index]?.role === 'user') {
+            return index;
+        }
+    }
+    return undefined;
+};
+/**
+ * The messages above `session`'s floor, with the
+ * note in place of what was cut. The session itself is untouched — the
+ * copy is shallow and deliberately shares `metadata`, because providers
+ * keep replay state there (the Anthropic raw-turn cache) and a turn that
+ * wrote into a copy would lose it.
+ *
+ * Returns the session unchanged when the floor is 0, so a conversation that
+ * has never overflowed is not copied on every turn.
+ */
+export const messagesWithinContextFloor = (session) => {
+    const floor = contextFloorOf(session);
+    if (floor <= 0 || floor >= session.messages.length) {
+        return session.messages;
+    }
+    const start = nextTurnBoundary(session.messages, floor);
+    if (start === undefined || start === 0) {
+        return session.messages;
+    }
+    const kept = session.messages.slice(start);
+    const first = kept[0];
+    // Prefixed onto the oldest surviving message rather than added as one of
+    // its own: an extra message would be a turn the transcript never had, and
+    // every count derived from the messages — ids, `latestTurnReply` — reads
+    // the stored list anyway.
+    //
+    // Messages rather than a shortened Session, and that is the whole point:
+    // `request.session` is persistable — the harness providers hand it to
+    // `executeHostedToolCall` and the fallback wrapper saves it — so a
+    // session-shaped view would be written back over the real transcript and
+    // lose everything below the floor for good.
+    return [{ ...first, content: `${droppedTurnsNote(start)}\n\n${first.content}` }, ...kept.slice(1)];
+};
+/**
+ * Raise the floor so the next attempt sends less, and report whether there
+ * was anything left to give up.
+ *
+ * Halves the remaining window each time rather than trimming a fixed
+ * amount: nothing here knows how many tokens a message is, and an overflow
+ * says only "too big", not "too big by this much" — so the cheap thing is
+ * to converge in a handful of attempts rather than to creep towards the
+ * answer one turn at a time, paying a rejected request for each step.
+ *
+ * Returns false when the window is already down to the newest turn. That is
+ * the floor's floor: a single turn that does not fit is a message larger
+ * than the model can read, and no amount of dropping history fixes it.
+ */
+export const raiseContextFloor = (session) => {
+    const floor = contextFloorOf(session);
+    const remaining = session.messages.length - floor;
+    if (remaining <= 1) {
+        return false;
+    }
+    const target = floor + Math.max(1, Math.floor(remaining / 2));
+    // The midpoint first, then the newest boundary there is. They differ when
+    // the turn in flight is more than half of what is left — many tool calls
+    // and results under one user message — and then nothing sits at or after
+    // the midpoint, while an earlier boundary above the floor still drops
+    // real history. Reporting "the newest turn is too large" without having
+    // tried the newest turn alone is the case this second look exists for.
+    const start = nextTurnBoundary(session.messages, target) ?? lastTurnBoundary(session.messages, floor + 1);
+    // Nothing above the floor: the tail is one turn and there is nothing
+    // further to drop.
+    if (start === undefined || start <= floor) {
+        return false;
+    }
+    session.metadata = { ...(session.metadata ?? {}), [CONTEXT_FLOOR_METADATA_KEY]: start };
+    return true;
+};
 /**
  * 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
@@ -1640,7 +2652,18 @@ const throwIfAborted = (signal) => {
         throw abortErrorFor(signal);
     }
 };
-const DEFAULT_MAX_TURNS = 8;
+/**
+ * Tool turns one message may take before it wraps up. The harness providers
+ * spend the same number as their own inner budget, so they import it rather
+ * than keep a copy.
+ *
+ * 8 until the wrap-up turn existed, and 8 was the whole budget for one Slack
+ * message: an agent with a shell spent it on a handful of commands and
+ * failed with nothing said. With a wrap-up turn the ceiling is where a long
+ * task checks in rather than where it dies, and 40 is enough for real
+ * multi-step work while still bounding what a runaway loop can spend.
+ */
+export const DEFAULT_MAX_TURNS = 40;
 export class AgentRunner {
     bus;
     store;
@@ -2010,8 +3033,16 @@ export class AgentRunner {
             // permitted turn buy the whole allowance again.
             for (let turn = resumeFrom?.turn ?? 1;; turn += 1) {
                 throwIfAborted(signal);
-                if (turn > this.maxTurns) {
-                    throw new Error(`Session exceeded the maximum of ${this.maxTurns} provider turns.`);
+                // One turn past the ceiling, and only one: the wrap-up, which may
+                // not call a tool, so a turn that reaches `maxTurns + 2` is a
+                // provider that ignored `toolChoice` and was already failed below.
+                const wrappingUp = turn > this.maxTurns;
+                // A recovered call is a tool turn too, so one parked past the
+                // ceiling — `maxTurns` lowered while it waited — is refused as it
+                // was before wrap-up existed, not run on the one call reserved for
+                // saying what happened.
+                if (turn > this.maxTurns + 1 || (wrappingUp && pendingEntry)) {
+                    throw new Error(turnLimitMessage(this.maxTurns));
                 }
                 if (pendingEntry) {
                     // The whole recovered queue — the parked call first, then the
@@ -2030,20 +3061,25 @@ export class AgentRunner {
                     await this.runToolCalls(session, recovered, signal, carriedParkedAt, turn);
                     continue;
                 }
-                // A bounded slice — the most recent entries, chronological — not the
-                // whole store. Everything older reaches the model through
-                // `memory.recall`; injecting it all is what gave the store a horizon
-                // measured in weeks.
+                // Three bounded blocks, not the whole store and not a recency slice
+                // either: the pinned core the agent keeps whatever the conversation
+                // is, a topic index telling it what it knows about, and a short
+                // tail. Everything else reaches the model through `memory.recall`,
+                // which the index exists to aim.
                 const memory = this.memory
-                    ? (await this.memory.list(session.agent.id, { limit: MEMORY_INJECTION_LIMIT })).entries
-                    : [];
+                    ? await buildMemoryInjection(this.memory, session.agent.id)
+                    : emptyMemoryInjection();
                 // What enters the context taints the session, not only what a tool
                 // returned: an `external` entry arriving here is a stranger's text
                 // in the prompt, and without this the store launders its own
                 // contents on the next restart — a fresh session reads the fact,
-                // restates it, remembers it, and the copy is `agent`.
-                if (memory.length > 0) {
-                    await this.taint(session, leastTrusted(...memory.map(memoryEntryTrust)), 'memory');
+                // restates it, remembers it, and the copy is `agent`. The topic
+                // index counts too — an entity name an `external` entry supplied is
+                // still a stranger's words reaching the prompt.
+                const injected = memoryInjectionEntries(memory);
+                const injectedTrust = leastTrusted(...injected.map(memoryEntryTrust), ...memory.topics.map((topic) => topic.trust));
+                if (injected.length > 0 || memory.topics.length > 0) {
+                    await this.taint(session, injectedTrust, 'memory');
                 }
                 // Deltas re-emit on the bus through a serial chain that is drained
                 // before the final provider.response goes out — a delta arriving
@@ -2058,32 +3094,110 @@ export class AgentRunner {
                 // makes underneath it. Allocated before the call because the sink
                 // fires during it.
                 const turnId = this.nextTurnId(session);
-                // Sink-reported usage is exclusive for the call. An adapter that
-                // reports its internal attempts through the sink has already counted
-                // the last one, and reading the response's field as well would bill
-                // that attempt twice.
-                let sinkReported = false;
-                const onUsage = (usage) => {
-                    sinkReported = true;
-                    this.recordUsage(session, turnId, usage);
-                };
-                const response = await this.options.provider.generate({
-                    session,
-                    ...(tools.length > 0 ? { tools } : {}),
-                    ...(memory.length > 0 ? { memory } : {}),
-                    ...(enabledSkills.length > 0 ? { skills: enabledSkills } : {}),
-                    ...(this.streaming ? { onDelta } : {}),
-                    onUsage,
-                    ...(signal ? { signal } : {}),
-                });
-                // Recorded before the abort check, deliberately: a turn cancelled
-                // between the response arriving and this loop noticing still spent
-                // those tokens, and the catch below saves the session.
-                if (!sinkReported && response.usage) {
-                    this.recordUsage(session, turnId, response.usage);
+                // Sending less history until it fits, rather than failing for good.
+                //
+                // A transcript that has outgrown the context window is the one
+                // provider rejection that repeats: the session is durable, so the
+                // next message replays the same too-long request and is refused
+                // the same way, and the conversation is dead under an id its
+                // channel still routes to. A Slack DM is one session for the life
+                // of the install, so "start a new one" is not available to the
+                // person typing into it.
+                //
+                // The floor is raised on the session and saved, so the next turn
+                // begins where this one ended up instead of paying a rejected
+                // request to rediscover it. `sessionWithinContextFloor` is what
+                // actually shortens the request; the provider only says that it
+                // did not fit.
+                let response;
+                for (;;) {
+                    const floored = messagesWithinContextFloor(session);
+                    // The note rides in the window only, so the session never holds
+                    // it; see `TURN_LIMIT_NOTE`.
+                    const window = wrappingUp ? [...floored, turnLimitNoteFor(session)] : floored;
+                    // Sink-reported usage is exclusive for the call: an adapter that
+                    // reports its internal attempts through the sink has already
+                    // counted the last one, and reading the response's field as well
+                    // would bill that attempt twice.
+                    //
+                    // Per ATTEMPT, not per turn, because the sink's exclusivity is
+                    // scoped to one `generate` (see `ProviderRequest.onUsage`) and a
+                    // retry below is another one. Shared across them, an overflowing
+                    // attempt that reported its billed tokens through the sink would
+                    // suppress the response field of the shorter attempt that then
+                    // succeeded — recording the call that failed and not the one that
+                    // answered. The turn id is deliberately not per attempt: one
+                    // Stratus turn, however many provider calls it took to fit.
+                    let sinkReported = false;
+                    const onUsage = (usage) => {
+                        sinkReported = true;
+                        this.recordUsage(session, turnId, usage);
+                    };
+                    try {
+                        response = await this.options.provider.generate({
+                            // The real session, always: providers persist it. The window
+                            // rides beside it.
+                            session,
+                            ...(window === floored && floored.length === session.messages.length ? {} : { messages: window }),
+                            ...(tools.length > 0 ? { tools } : {}),
+                            ...(wrappingUp && tools.length > 0 ? { toolChoice: 'none' } : {}),
+                            ...(injected.length > 0 || memory.topics.length > 0 ? { memory } : {}),
+                            ...(enabledSkills.length > 0 ? { skills: enabledSkills } : {}),
+                            ...(this.streaming ? { onDelta } : {}),
+                            onUsage,
+                            ...(signal ? { signal } : {}),
+                        });
+                        // Recorded before the abort check below, deliberately: a turn
+                        // cancelled between the response arriving and this loop
+                        // noticing still spent those tokens, and the catch that ends
+                        // the turn saves the session.
+                        if (!sinkReported && response.usage) {
+                            this.recordUsage(session, turnId, response.usage);
+                        }
+                        break;
+                    }
+                    catch (error) {
+                        // Not an overflow, or nothing left to drop: the turn fails, and
+                        // the message says which — a single turn too big for the model
+                        // is a different problem from a conversation that got long, and
+                        // the remedies do not overlap.
+                        if (!(error instanceof ContextOverflowError)) {
+                            throw error;
+                        }
+                        throwIfAborted(signal);
+                        const before = contextFloorOf(session);
+                        if (!raiseContextFloor(session)) {
+                            throw new Error(`${error.message} The newest turn on its own is already larger than this model can read, `
+                                + 'so dropping earlier messages cannot help: shorten the message, cut the tool output it '
+                                + 'carries, or move to a model with a bigger context window.');
+                        }
+                        // Durable before the retry, not after it. A daemon that dies
+                        // mid-recovery must not come back and replay the request that
+                        // was just refused; the floor is the one thing learned here and
+                        // it costs a rejected call to learn again.
+                        await this.store.save(session);
+                        // Whatever the abandoned attempt streamed has to be discarded,
+                        // or a renderer fuses the two answers — the same contract the
+                        // fallback wrapper's reset delta honours.
+                        if (this.streaming) {
+                            await onDelta({ type: 'reset', reason: 'retry' });
+                        }
+                        await this.bus.emit({
+                            type: 'session.context-trimmed',
+                            sessionId: session.id,
+                            droppedMessages: contextFloorOf(session) - before,
+                            floor: contextFloorOf(session),
+                        });
+                    }
                 }
                 throwIfAborted(signal);
                 await deltaChain;
+                // Checked before anything of the response is saved: a call made on
+                // the turn that may not make one is never run, and recording it
+                // would leave a call in the transcript with no result to answer it.
+                if (wrappingUp && response.parts.some((part) => part.type === 'tool-call')) {
+                    throw new Error(turnLimitMessage(this.maxTurns));
+                }
                 // Record and SAVE the entire response — text and every tool call —
                 // before anything else happens with it. Two consumers depend on
                 // that order: provider replay state (the Anthropic raw-turn cache)