@stratusagent/core 0.11.4 → 0.11.6

package/dist/index.d.ts

@@ -672,15 +672,75 @@ export interface ToolDescriptor {
     /** Carried so providers hosting their own loop can see it too. */
     risk?: ToolRisk;
 }
+/**
+ * What sort of thing a fact is. One flat bucket is why a long-lived store
+ * goes noisy: these have different useful lifetimes and different injection
+ * value, and no policy can tell them apart from prose.
+ *
+ * - `semantic` — a fact about the world.
+ * - `episodic` — a thing that happened.
+ * - `procedural` — how something is done.
+ * - `preference` — how the people it works with want things.
+ */
+export type MemoryEntryKind = 'semantic' | 'episodic' | 'procedural' | 'preference';
+/** Every kind, in the order the tool description lists them. */
+export declare const MEMORY_ENTRY_KINDS: readonly ["semantic", "episodic", "procedural", "preference"];
+export declare const isMemoryEntryKind: (value: unknown) => value is MemoryEntryKind;
 /**
  * One remembered fact. Memory is keyed by agent, never by session or
  * channel, so an agent carries the same knowledge everywhere it appears.
+ *
+ * Everything past the first four fields is optional and additive, and that
+ * is a promise rather than an accident: a JSONL line carrying only `id`,
+ * `agentId`, `content`, and `createdAt` still loads, is still recallable,
+ * and still reaches the prompt. A richer shape is the thing most likely to
+ * break the hand-edit promise, so nothing here may ever become required.
  */
 export interface MemoryEntry {
     id: string;
     agentId: string;
     content: string;
     createdAt: string;
+    /** What sort of fact this is — see `MemoryEntryKind`. Absent means nobody said. */
+    kind?: MemoryEntryKind;
+    /**
+     * The entities this fact concerns, as the writer named them. This is what
+     * turns "everything I know about the deploy pipeline" into a lookup rather
+     * than a guess at query terms, and it is what the prompt's topic index is
+     * built from.
+     *
+     * It also *participates in matching*, in every store: an index block that
+     * advertised a topic the search could not find would invite exactly the
+     * query it then missed. `memoryEntryTokens` is where that is written once.
+     */
+    about?: string[];
+    /**
+     * When the fact starts and stops being true — validity time, a different
+     * axis from `createdAt`, which is transaction time. Conflating the two is
+     * why assistants confidently report where someone used to work.
+     *
+     * Both bounds are ISO-8601 instants; `validUntil` is the moment the fact
+     * stops holding, exclusive. Outside the window an entry leaves what is
+     * true now — the pinned core, the topic index, the recency tail — and
+     * stays findable by `search`, marked. That is one rule for both bounds:
+     * a `validFrom` in the future is the same error running the other way,
+     * and an entry that is not true *yet* reaching the prompt would be
+     * presented as true now.
+     */
+    validFrom?: string;
+    validUntil?: string;
+    /**
+     * The id of the entry this one replaces. The successor carries the
+     * retirement itself — one appended record, never a tombstone plus an
+     * entry, because the store's only atomicity is one `O_APPEND` record and
+     * stopping between two of them loses a fact.
+     *
+     * The retirement is scoped to *this* entry's validity window: a successor
+     * dated from next Monday leaves its predecessor standing until then, and
+     * an already-expired successor displaces nothing. See
+     * `supersededMemoryIdsAt`.
+     */
+    supersedes?: string;
     metadata?: JsonObject;
     /**
      * Where the fact came from — the least trusted thing the writing session
@@ -699,6 +759,21 @@ export interface MemoryEntry {
      * reading the store, and travels with the entry as ordinary data.
      */
     origin?: MemoryOrigin;
+    /**
+     * How often this entry has been read back, and when last — **derived, and
+     * never part of the record**. These are observations about *reading*, not
+     * facts the agent learned, so they live in whatever index a store keeps
+     * and a store that keeps none simply omits them. The consequence is exact
+     * and is the documented one: deleting the index loses your usage
+     * statistics, never your memories. Ranking may read them; nothing
+     * deletes on them.
+     */
+    usage?: MemoryUsage;
+}
+/** See `MemoryEntry.usage`. Counted by the store on each `search` that returns the entry. */
+export interface MemoryUsage {
+    recallCount: number;
+    lastRecalledAt: string;
 }
 export interface MemoryOrigin {
     sessionId?: string;
@@ -737,16 +812,60 @@ export declare const MEMORY_ENTRY_MAX_BYTES = 4096;
  * several cap-size entries still fit (see `MEMORY_ENTRY_MAX_BYTES`).
  */
 export declare 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 declare const MEMORY_RECALL_TOOL_NAME = "memory.recall";
 /** Results a `search` returns when the caller names no limit. */
 export declare const MEMORY_RECALL_DEFAULT_LIMIT = 10;
 /** Ceiling a `search` limit is clamped to, whatever the caller asked for. */
 export declare const MEMORY_RECALL_MAX_LIMIT = 50;
-/** How many recent entries the runner injects into the system prompt. */
-export declare 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 declare 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 declare 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 declare const MEMORY_RECENCY_INJECTION_LIMIT = 8;
+/** Byte budget for the recency tail, applied like every other bounded read. */
+export declare const MEMORY_RECENCY_MAX_BYTES = 4096;
 /** UTF-8 size of an entry's content — the unit both memory caps are stated in. */
 export declare const memoryContentByteLength: (content: string) => number;
 /** Refuses (never truncates) content over the per-entry cap: a half-stored fact is worse than a refused one. */
 export declare const assertMemoryContentWithinCap: (content: string) => void;
+/**
+ * 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 declare const MEMORY_ABOUT_MAX_KEYS = 12;
+export declare 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 declare const assertMemoryAboutWithinCap: (about: readonly string[]) => void;
 /**
  * The tokenizer both store implementations share: NFC-normalized,
  * case-folded, split on anything that is not a Unicode letter or digit.
@@ -756,12 +875,72 @@ export declare const assertMemoryContentWithinCap: (content: string) => void;
  */
 export declare const tokenizeMemoryText: (text: string) => string[];
 /**
- * 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 declare const memoryEntryAbout: (entry: Pick<MemoryEntry, "about">) => string[];
+/**
+ * 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 declare const memoryEntryTokens: (entry: Pick<MemoryEntry, "content" | "about">) => string[];
+/**
+ * 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 declare const memoryQueryMatches: (content: string, queryTokens: readonly string[]) => boolean;
+export declare const memoryQueryMatches: (entry: Pick<MemoryEntry, "content" | "about">, queryTokens: readonly string[]) => boolean;
+/**
+ * Where an entry sits relative to its validity window at a given instant.
+ * `current` is the only status that is true *now*; both others leave the
+ * injected slice and stay findable by `search`, marked.
+ */
+export type MemoryValidity = 'current' | 'not-yet-valid' | 'expired';
+/**
+ * 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 declare const memoryValidityAt: (entry: Pick<MemoryEntry, "validFrom" | "validUntil">, at: Date) => MemoryValidity;
+/** Shorthand for the only status that is true now. */
+export declare const isMemoryEntryCurrent: (entry: Pick<MemoryEntry, "validFrom" | "validUntil">, at: Date) => boolean;
+/**
+ * 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 declare const supersededMemoryIdsAt: (entries: readonly MemoryEntry[], at: Date) => Set<string>;
 /**
  * Recall order — newest first, ties on `createdAt` broken by entry id
  * ascending. The tie-break is not about frequency: without one, two
@@ -772,10 +951,30 @@ export declare const memoryQueryMatches: (content: string, queryTokens: readonly
 export declare const compareMemoryRecallOrder: (a: MemoryEntry, b: MemoryEntry) => number;
 /** Chronological order (oldest first), same tie-break — how a bounded `list` presents its slice. */
 export declare const compareMemoryChronology: (a: MemoryEntry, b: MemoryEntry) => number;
+/**
+ * How a read orders what it found. Named in the request and reported in the
+ * result, rather than frozen in the contract.
+ *
+ * `recency` is mandatory, is the default, and is what the parity tests
+ * assert. `relevance` and `hybrid` are optional: a store that lacks the one
+ * asked for **serves `recency` and says so** rather than erroring, so two
+ * implementations stay honest about ordering without memory being frozen at
+ * clock order forever — and an embeddings-backed store behind a plugin seam
+ * becomes an additive capability rather than a contract break.
+ */
+export type MemoryRankingStrategy = 'recency' | 'relevance' | 'hybrid';
+export declare const MEMORY_RANKING_STRATEGIES: readonly ["recency", "relevance", "hybrid"];
+export declare const isMemoryRankingStrategy: (value: unknown) => value is MemoryRankingStrategy;
 export interface MemoryReadResult {
     entries: MemoryEntry[];
     /** True when live entries beyond these existed — the entry limit or the byte budget bound, whichever bit first. */
     truncated: boolean;
+    /**
+     * The ordering the store actually applied. Present on a `search`, where
+     * the caller may have asked for one the store does not implement; absent
+     * on `list`, which is chronological by definition.
+     */
+    strategy?: MemoryRankingStrategy;
 }
 export interface MemoryListOptions {
     /**
@@ -786,6 +985,53 @@ export interface MemoryListOptions {
      * feed a model always pass a bound.
      */
     limit?: number;
+    /**
+     * Which entries count as live for this read. `current` — the default,
+     * and what "what is true now" means — drops entries outside their
+     * validity window; `all` keeps them, for the operator views that exist
+     * to show an expired fact *as* expired. Superseded and forgotten entries
+     * are out of both: those are retirements, not calendar questions.
+     */
+    validity?: 'current' | 'all';
+}
+/** Which pins a read wants — see `AgentMemoryStore.pinned`. */
+export interface MemoryPinnedOptions {
+    /**
+     * `current`, the default, is the pinned core as the prompt carries it:
+     * live and true now. `allocated` is everything **holding budget** —
+     * superseded and out-of-window pins included — which is a different
+     * question and the one an operator, or a caller re-allocating a merged
+     * budget, actually has. A pin nothing admits exists is one nobody can
+     * unpin, and it is exactly what makes a later pin refuse.
+     */
+    include?: 'current' | 'allocated';
+}
+export interface MemorySearchOptions {
+    /** Clamped by `clampMemoryRecallLimit`; the store bounds it either way. */
+    limit?: number;
+    /** The ordering asked for. See `MemoryRankingStrategy` — an unsupported one is served as `recency`. */
+    strategy?: MemoryRankingStrategy;
+}
+/**
+ * What a writer says about a new entry beyond its text. Every field is
+ * optional, and an `append` that passes none writes exactly the four-field
+ * line an older build would have written.
+ */
+export interface MemoryAppendOptions {
+    metadata?: JsonObject;
+    provenance?: MemoryProvenance;
+    kind?: MemoryEntryKind;
+    about?: string[];
+    validFrom?: string;
+    validUntil?: string;
+    /**
+     * The entry this one replaces. The store resolves it against the
+     * caller's **own** live entries before anything is appended and throws
+     * otherwise: the record lane is shared across agents, and a writer that
+     * skipped the check would let one agent retire another's memory by
+     * naming its id.
+     */
+    supersedes?: string;
 }
 /** Clamp a caller-chosen search limit into the store's own bounds. */
 export declare const clampMemoryRecallLimit: (limit?: number) => number;
@@ -803,7 +1049,130 @@ export declare const boundMemoryRead: (candidates: readonly MemoryEntry[], limit
  * presentation order are different things; conflating them is the bug this
  * helper exists so nobody writes three times.
  */
-export declare const boundMemoryList: (candidates: readonly MemoryEntry[], limit: number) => MemoryReadResult;
+export declare const boundMemoryList: (candidates: readonly MemoryEntry[], limit: number, maxBytes?: number) => MemoryReadResult;
+/**
+ * What the pin write path decides, and the sentence it says when it
+ * refuses. Split out because the refusal has to name the cap — an operator
+ * who cannot see why a pin bounced will assume it worked.
+ */
+export interface MemoryPinOutcome {
+    pinned: boolean;
+    /** Present when `pinned` is false: what happened, as a full sentence. */
+    reason?: string;
+    /** Content bytes the effective pinned set holds after this call. */
+    bytes: number;
+}
+/**
+ * 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 declare const applyMemoryPinBudget: (pinnedIds: readonly string[], contentBytesFor: (id: string) => number | undefined, maxBytes?: number) => {
+    effective: string[];
+    inert: string[];
+    bytes: number;
+};
+/** One line of the prompt's topic index: what the agent knows about, and how much. */
+export interface MemoryTopic {
+    /** The `about` key, in the spelling the first entry to use it wrote. */
+    name: string;
+    count: number;
+    /** The newest `createdAt` among the entries filed under it. */
+    lastUpdatedAt: string;
+    /**
+     * The least trusted label among those entries. The topic index is a view
+     * derived from entries, so it renders under the labelling invariant like
+     * every other one: an entity name an `external` entry supplied must not
+     * appear under the heading for the agent's own conclusions.
+     */
+    trust: TrustLevel;
+}
+/**
+ * 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 declare const collectMemoryTopics: (entries: readonly MemoryEntry[]) => MemoryTopic[];
+/**
+ * The three bounded blocks a turn injects, in place of the one recency
+ * slice memory used to send.
+ *
+ * They are three blocks *within* one `memory` section, never three sections
+ * of their own — an adapter that places the volatile section separately
+ * finds it by kind, so siblings sharing the kind would move one and drop
+ * the rest of the request on the floor.
+ */
+export interface MemoryInjection {
+    /**
+     * Always present when anything is pinned, hard-capped at
+     * `MEMORY_PINNED_MAX_BYTES`. This is what makes an agent still know the
+     * basics after a year with no search at all.
+     */
+    pinned: MemoryEntry[];
+    /** What the agent knows about — the block that turns `memory.recall` from a guess into a targeted read. */
+    topics: MemoryTopic[];
+    /** The recency tail, so a cold store with nothing pinned behaves as it did before. */
+    recent: MemoryEntry[];
+}
+/** Empty in all three blocks — what a host with no memory store injects. */
+export declare const emptyMemoryInjection: () => MemoryInjection;
+/**
+ * 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 declare const selectMemoryInjection: (input: {
+    pinned: readonly MemoryEntry[];
+    topics: readonly MemoryTopic[];
+    recent: readonly MemoryEntry[];
+}) => MemoryInjection;
+/**
+ * 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 declare const buildMemoryInjection: (store: AgentMemoryStore, agentId: string) => Promise<MemoryInjection>;
+/**
+ * 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 declare const asMemoryInjection: (memory: readonly MemoryEntry[] | MemoryInjection | undefined) => MemoryInjection;
+/** Every entry a turn injects, in the order they reach the prompt — what taints the session. */
+export declare const memoryInjectionEntries: (injection: readonly MemoryEntry[] | MemoryInjection | undefined) => MemoryEntry[];
 /**
  * Durable, searchable memory an agent writes and reads deliberately. The
  * per-agent key is the access boundary — every method takes the agent id the
@@ -823,19 +1192,30 @@ export declare const boundMemoryList: (candidates: readonly MemoryEntry[], limit
  *   `MEMORY_READ_MAX_BYTES` when a limit is in play; `forget` tombstones
  *   rather than deletes, and `audit` is where tombstoned entries remain
  *   visible to an operator.
+ * - An entry is **not live** when a tombstone retires it or a *current*
+ *   successor supersedes it (`supersededMemoryIdsAt`). An entry outside its
+ *   validity window is a different thing: still live, out of `list` by
+ *   default because it is not true now, and still found by `search` — where
+ *   the caller reads its status with `memoryValidityAt`.
  */
 export interface AgentMemoryStore {
     /**
      * Refuses content over `MEMORY_ENTRY_MAX_BYTES` rather than truncating it.
-     * `provenance` is what the writer knows about where the fact came from;
-     * an append without one stores an entry that reads as `unknown`, which
-     * is the honest label for a writer that did not say.
+     * `options.provenance` is what the writer knows about where the fact came
+     * from; an append without one stores an entry that reads as `unknown`,
+     * which is the honest label for a writer that did not say. Throws when
+     * `options.supersedes` names an id that is not a live entry of this agent.
      */
-    append(agentId: string, content: string, metadata?: JsonObject, provenance?: MemoryProvenance): Promise<MemoryEntry>;
-    /** Live entries, oldest first. See `MemoryListOptions` for the bounded form. */
+    append(agentId: string, content: string, options?: MemoryAppendOptions): Promise<MemoryEntry>;
+    /** Live entries, oldest first. See `MemoryListOptions` for the bounded and the out-of-window forms. */
     list(agentId: string, options?: MemoryListOptions): Promise<MemoryReadResult>;
-    /** Live entries matching the literal query, newest first, bounded. */
-    search(agentId: string, query: string, limit?: number): Promise<MemoryReadResult>;
+    /**
+     * Live entries matching the literal query, newest first, bounded —
+     * entries outside their validity window included, because keeping an
+     * expired fact findable is the point of separating validity from
+     * supersession. Matching covers content and `about` keys alike.
+     */
+    search(agentId: string, query: string, options?: MemorySearchOptions): Promise<MemoryReadResult>;
     /** Tombstones a live entry. False when no live entry of this agent has that id. */
     forget(agentId: string, entryId: string): Promise<boolean>;
     /** The operator's audit read: every entry, tombstoned included, oldest first. */
@@ -852,21 +1232,160 @@ export interface AgentMemoryStore {
      * operator has no way out of `unknown` but rewriting the record.
      */
     reassertTrust?(agentId: string, entryId: string, trust: TrustLevel): Promise<boolean>;
+    /**
+     * Pin a live entry into the core the prompt always carries. Refuses over
+     * `MEMORY_PINNED_MAX_BYTES` naming the cap, and **never evicts**: a
+     * pinned set that silently drops its oldest member is a pin that does not
+     * mean anything. Like `supersedes`, it resolves the id against the
+     * caller's own live entries before recording anything.
+     *
+     * Optional: a host whose store omits it gets no pinned core — injection
+     * falls back to the topic index and the recency tail, which is what
+     * memory did before pinning existed.
+     */
+    pin?(agentId: string, entryId: string): Promise<MemoryPinOutcome>;
+    /** Undo a pin. False when this agent has no effective pin on that id. */
+    unpin?(agentId: string, entryId: string): Promise<boolean>;
+    /**
+     * The effective pinned set, oldest first — see `applyMemoryPinBudget` for
+     * what "effective" means, and `MemoryPinnedOptions` for the out-of-window
+     * ones that hold budget without reaching the prompt.
+     */
+    pinned?(agentId: string, options?: MemoryPinnedOptions): Promise<MemoryEntry[]>;
+    /**
+     * What the agent knows *about*, from the `about` keys of everything true
+     * now. Built with `collectMemoryTopics` so no two stores can advertise
+     * the same record differently.
+     *
+     * Optional: a host whose store omits it gets no topic index, and its
+     * agent is back to guessing query terms.
+     */
+    topics?(agentId: string): Promise<MemoryTopic[]>;
+    /**
+     * Append entries verbatim — ids, timestamps, kinds, validity and all —
+     * under this agent's key. The operator's import path and the eval
+     * harness's corpus loader; no tool reaches it, because an agent able to
+     * choose its own entry ids could name one another record already refers
+     * to.
+     *
+     * Entries whose id the agent already holds are skipped rather than
+     * duplicated, so a re-run of an import is a no-op rather than a second
+     * copy of everything.
+     */
+    importEntries?(agentId: string, entries: readonly MemoryEntry[]): Promise<MemoryImportResult>;
 }
+/** What an import did: what landed, and what was already there. */
+export interface MemoryImportResult {
+    imported: number;
+    /** Ids skipped because this agent already holds an entry with that id. */
+    skipped: string[];
+}
+/**
+ * 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 declare const pinnedCapRefusal: (heldBytes: number, wantedBytes: number) => string;
+/**
+ * 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 declare const pinnedInertRefusal: (blockingId: string) => string;
+/**
+ * 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 declare const assertSupersedableMemoryEntry: (live: readonly MemoryEntry[], entryId: string) => void;
+/**
+ * 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 declare const memoryEntryFields: (value: Pick<MemoryEntry, "kind" | "about" | "validFrom" | "validUntil" | "supersedes">) => Pick<MemoryEntry, "kind" | "about" | "validFrom" | "validUntil" | "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 declare const importableMemoryEntry: (entry: MemoryEntry, agentId: string) => MemoryEntry;
 export declare class InMemoryAgentMemoryStore implements AgentMemoryStore {
     private entries;
+    /**
+     * 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.
+     */
+    private pins;
+    /**
+     * 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.
+     */
+    private usage;
+    /**
+     * 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.
+     */
+    private takenIds;
     private counter;
     private readonly now;
     constructor(options?: {
         now?: () => Date;
     });
-    append(agentId: string, content: string, metadata?: JsonObject, provenance?: MemoryProvenance): Promise<MemoryEntry>;
+    append(agentId: string, content: string, options?: MemoryAppendOptions): Promise<MemoryEntry>;
+    /** Not tombstoned and not superseded by a successor that is current at `at`. */
     private live;
     list(agentId: string, options?: MemoryListOptions): Promise<MemoryReadResult>;
-    search(agentId: string, query: string, limit?: number): Promise<MemoryReadResult>;
+    search(agentId: string, query: string, options?: MemorySearchOptions): Promise<MemoryReadResult>;
+    private usageKey;
+    private noteRecalled;
+    /**
+     * 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.
+     */
+    private mutable;
     forget(agentId: string, entryId: string): Promise<boolean>;
     audit(agentId: string): Promise<MemoryAuditEntry[]>;
     reassertTrust(agentId: string, entryId: string, trust: TrustLevel): Promise<boolean>;
+    /**
+     * 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.
+     */
+    private pinBudget;
+    pin(agentId: string, entryId: string): Promise<MemoryPinOutcome>;
+    unpin(agentId: string, entryId: string): Promise<boolean>;
+    pinned(agentId: string, options?: MemoryPinnedOptions): Promise<MemoryEntry[]>;
+    topics(agentId: string): Promise<MemoryTopic[]>;
+    importEntries(agentId: string, entries: readonly MemoryEntry[]): Promise<MemoryImportResult>;
 }
 /**
  * Resolves named credentials for an agent. Implementations must enforce the
@@ -981,10 +1500,51 @@ export declare const uncachedInputTokens: (total: number, ...cached: Array<numbe
  */
 export declare const totalTokenUsage: (records: readonly TokenUsage[]) => TokenUsage | undefined;
 export interface ProviderRequest {
+    /**
+     * The live session. **Persistable**: a provider that saves it, or hands
+     * it to `executeHostedToolCall`, is writing the real conversation — so
+     * this is always the whole session, never a view. Read the transcript
+     * through `transcriptOf(request)` instead of from here.
+     */
     session: Session;
+    /**
+     * The transcript to send, when it is not the whole of `session.messages`
+     * — the tail left by the session's context floor, with a note in place
+     * of what was cut.
+     *
+     * Separate from `session` because the two are used for different things
+     * and only one of them may be written back. The harness providers pass
+     * `request.session` to `executeHostedToolCall`, which appends tool
+     * records and saves; the fallback wrapper persists `request.session` to
+     * make its switch durable. Handing either a shortened *session* would
+     * write the window over the stored transcript and lose everything below
+     * the floor, permanently.
+     *
+     * Absent means "all of them", so an adapter that ignores this field
+     * behaves exactly as it did — which is right for a harness provider,
+     * since it manages its own context and the window is not its to apply.
+     */
+    messages?: readonly Message[];
     tools?: ToolDescriptor[];
-    /** Agent-scoped long-term memory, newest last. */
-    memory?: MemoryEntry[];
+    /**
+     * `none` asks for an answer in words: the tools stay declared, because
+     * the history holds calls to them and an API that is sent tool calls
+     * with no tools to match refuses the request, but the model may not
+     * call one. Sent on the turn that wraps up a message which has used its
+     * `maxTurns` (see `TURN_LIMIT_NOTE`).
+     *
+     * Optional to honour. A provider that ignores it sends a request the
+     * model may still answer with a call, and the runner then fails the turn
+     * the way it did before wrap-up existed, rather than run the call.
+     */
+    toolChoice?: 'none';
+    /**
+     * Agent-scoped long-term memory as the turn injects it: the pinned core,
+     * the topic index, and the recency tail. A bare array is the tail alone —
+     * what `memory` meant before the three blocks existed, and still what a
+     * host building a request by hand may pass.
+     */
+    memory?: MemoryEntry[] | MemoryInjection;
     /**
      * The skills enabled for this agent — descriptors only, one prompt line
      * each. Bodies never travel here; they arrive through `skill.read` when
@@ -1039,6 +1599,16 @@ export interface ProviderRequest {
      */
     signal?: AbortSignal;
 }
+/**
+ * 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 declare const transcriptOf: (request: Pick<ProviderRequest, "session" | "messages">) => readonly Message[];
 export interface ProviderResponse {
     parts: ProviderPart[];
     /**
@@ -1334,6 +1904,22 @@ export interface PromptTextOptions {
  * followed more often than one read an hour ago.
  */
 export declare 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 \u2014 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 declare 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.";
 /** Reads the checkpoint off a session, if it is parked. */
 export declare const readPendingApproval: (session: Session) => PendingApprovalRecord | undefined;
 /**
@@ -1514,6 +2100,23 @@ export type StratusEvent = {
     sessionId: string;
     trust: TrustLevel;
     source: string;
+}
+/**
+ * The conversation outgrew the model's context window, so its oldest
+ * messages are no longer sent. `droppedMessages` is what this trim gave
+ * up; `floor` is the total now held back.
+ *
+ * Counts only — no content, for the same reason `session.tainted` names
+ * only its source: this is what the daemon log records, and the log is a
+ * trace, not a second transcript. Worth an event at all because it is
+ * otherwise invisible: the answers stay plausible while the agent
+ * quietly stops being able to remember the start of the conversation.
+ */
+ | {
+    type: 'session.context-trimmed';
+    sessionId: string;
+    droppedMessages: number;
+    floor: number;
 };
 export type EventHandler = (event: StratusEvent) => void | Promise<void>;
 export interface EventBusOptions {
@@ -1652,9 +2255,35 @@ export interface ChannelContribution {
  * 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 declare const MEMORY_STORE_CONTRACT_VERSION = 2;
 export interface MemoryStoreContribution {
     name: string;
     store: AgentMemoryStore;
+    /**
+     * Must be `MEMORY_STORE_CONTRACT_VERSION`. A store declaring an older
+     * revision — or none, which is what a plugin built before this field
+     * existed produces — is refused at registration rather than routed
+     * traffic it will mishandle without saying so.
+     */
+    contract: typeof MEMORY_STORE_CONTRACT_VERSION;
 }
 /** An executor contributed by a plugin, selectable by name in a trusted config. */
 export interface ExecutorContribution {
@@ -1709,8 +2338,12 @@ export declare class ChannelRegistry {
  * 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.
+ * 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 declare const createRoutedMemoryStore: (storeFor: (agentId: string) => AgentMemoryStore) => AgentMemoryStore;
 /** The handle a plugin registers providers through. Manifest-bound; see `@stratusagent/plugins`. */
@@ -1737,6 +2370,57 @@ export interface ChannelRegistrationHandle {
      */
     transportSecrets(kind: string): Promise<ChannelTransportSecrets>;
 }
+/**
+ * Where each agent's files go, answered by the host.
+ *
+ * A seam rather than a path in a config block because the layout is this
+ * repository's to own: the workspace is `~/.stratus/agents/<id>/workspace`
+ * today and was `~/.stratus/workspaces/<id>` before it, and every plugin
+ * that joined the agent id onto a root held a copy of that shape. Five of
+ * them did, and all five had to change when it moved — which is the cost
+ * the `workspaceRoot` key was introduced to avoid and did not.
+ *
+ * Asked per call, from `session.agent.id`, for the same reason credentials
+ * are: the answer is the *calling* agent's, and one captured at setup is
+ * the first agent's forever.
+ */
+export interface AgentWorkspaces {
+    /**
+     * Where this agent's files go. Resolution only: nothing is created and
+     * nothing can fail that would not fail for a bad id, so a caller that
+     * merely needs to *name* the path — the provenance ledger looking for a
+     * file that may not exist — can ask without consequence.
+     */
+    forAgent(agentId: string): string;
+    /**
+     * The same path, created and with its permissions settled, for a caller
+     * about to write.
+     *
+     * The host does this rather than the plugin because the workspace sits
+     * inside the agent's state directory, beside its sessions, memories and
+     * grants — so the recursive `mkdir` a file-producing plugin would
+     * otherwise reach for makes a *state* directory under the process umask.
+     * A plugin has no way to know that; the host that chose the layout does.
+     * Callers may still create subdirectories under what they are handed.
+     *
+     * Separate from {@link forAgent} because it can fail, and what fails
+     * with it should be only what needed the directory. A read that wanted
+     * a path, a navigation that writes nothing, a tool result that turned
+     * out to be text — none of those should stop because a directory they
+     * were never going to use could not be made.
+     */
+    prepare(agentId: string): string;
+    /**
+     * Every agent workspace the host can currently name, for the guards that
+     * have to recognise *any* agent's file rather than the caller's — the
+     * filesystem provenance ledger is the one that does.
+     *
+     * Paths, not a promise that each exists: a caller canonicalizes and
+     * tolerates what is missing. Re-read rather than cached, so an agent
+     * added under a running daemon is visible to the next call.
+     */
+    all(): Promise<readonly string[]>;
+}
 export interface MemoryRegistrationHandle {
     register(contribution: MemoryStoreContribution): void;
 }
@@ -1774,6 +2458,19 @@ export interface PluginContext {
     channels?: ChannelRegistrationHandle;
     memory?: MemoryRegistrationHandle;
     executors?: ExecutorRegistrationHandle;
+    /**
+     * Where this plugin may write files, per agent. See {@link AgentWorkspaces}.
+     *
+     * A host that omits it leaves every plugin that produces a file with
+     * nowhere the host has chosen to put it. Such a plugin falls back to the
+     * `workspaceRoot` config key — the documented root it joins the agent id
+     * onto — and, given neither, must fail the call naming what is missing,
+     * the way `browser.screenshot` does. Never a directory of its own
+     * choosing: a file an agent was told it produced has to be somewhere the
+     * operator can find, and a turn that cannot store its output must not
+     * read as though it did.
+     */
+    workspaces?: AgentWorkspaces;
     /**
      * The host's log, for what a plugin has to say after `setup` returns —
      * a server that dropped, a reconnect that failed. The daemon's is the
@@ -1986,17 +2683,6 @@ export declare const renderPersonaSection: (agent: Pick<AgentDefinition, "name"
  * reads a stranger's sentence as a stranger's.
  */
 export declare const memoryRegionHeading: (trust: TrustLevel) => string;
-/**
- * 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
@@ -2017,7 +2703,23 @@ export declare const BIDI_CONTROL_CHARACTERS = "\\u061c\\u200e\\u200f\\u202a-\\u
  * shown is still what is stored.
  */
 export declare const escapeControlCharacters: (text: string) => string;
-export declare const renderMemorySection: (memory: readonly MemoryEntry[] | undefined) => string | undefined;
+/**
+ * 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 declare const renderMemorySection: (memory: readonly MemoryEntry[] | MemoryInjection | undefined) => string | undefined;
 /**
  * The skills block: one line per enabled skill — id, name, and the
  * description routing runs on. This is the whole point of the step: the
@@ -2025,6 +2727,18 @@ export declare const renderMemorySection: (memory: readonly MemoryEntry[] | unde
  * here may ever include a body.
  */
 export declare const renderSkillsSection: (skills: readonly SkillDescriptor[] | undefined) => string | undefined;
+/**
+ * Where the conversation is happening, for a session a channel started.
+ *
+ * A channel adapter records itself as `metadata.channel` on the sessions it
+ * dispatches (`slack` today). Without this the agent could not tell: an
+ * agent with no Slack tool, asked about an attachment in a Slack DM, told
+ * the person it had "no Slack connection at all" and argued the point.
+ * Rendered from the session rather than handed in per turn so sessions
+ * opened before this existed get it too. The name must look like a channel
+ * id, since it is interpolated into the prompt.
+ */
+export declare const renderChannelSection: (session: Pick<Session, "metadata">) => string | undefined;
 export interface SystemPromptOptions {
     /** Host-level preamble, rendered before the agent's own persona. */
     preamble?: string;
@@ -2035,12 +2749,12 @@ export interface SystemPromptOptions {
  * Which part of what an agent is told a section is.
  *
  * The distinction a caller actually needs is stable versus volatile:
- * `preamble`, `persona`, and `skills` are byte-identical across every turn of
+ * `preamble`, `replies`, `persona`, `channel`, and `skills` are byte-identical across every turn of
  * an agent's life, while `memory` is rewritten whenever the agent remembers
  * anything. A provider that caches its request prefix has to place those two
  * groups differently, and it cannot tell them apart from rendered strings.
  */
-export type SystemPromptSectionKind = 'preamble' | 'persona' | 'memory' | 'skills';
+export type SystemPromptSectionKind = 'preamble' | 'replies' | 'persona' | 'channel' | 'memory' | 'skills';
 export interface SystemPromptSection {
     kind: SystemPromptSectionKind;
     text: string;
@@ -2209,6 +2923,78 @@ export interface ObserveInput {
      */
     metadata?: JsonObject;
 }
+/**
+ * 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 declare class ContextOverflowError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare const CONTEXT_FLOOR_METADATA_KEY = "contextFloor";
+/** The stored floor, or 0 for a session that has never overflowed. */
+export declare const contextFloorOf: (session: Pick<Session, "metadata">) => number;
+/**
+ * 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 declare const droppedTurnsNote: (count: number) => string;
+/**
+ * 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 declare const messagesWithinContextFloor: (session: Session) => readonly Message[];
+/**
+ * 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 declare const raiseContextFloor: (session: Session) => boolean;
 /**
  * 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
@@ -2272,6 +3058,18 @@ export interface AgentRunnerOptions {
      */
     streaming?: boolean;
 }
+/**
+ * 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 declare const DEFAULT_MAX_TURNS = 40;
 export declare class AgentRunner {
     readonly bus: EventBus;
     readonly store: SessionStore;