@animalabs/agent-framework 0.8.0 → 0.10.0

package/src/mcpl/types.ts

@@ -99,22 +99,32 @@ export interface McplResourceContent {
  * Parsed from the server's `initialize` response.
  */
 export interface McplCapabilities {
-  /** MCPL protocol version (e.g., "0.4") */
+  /** MCPL protocol version (e.g., "0.5") */
   version: string;
 
+  /** §17.2 canonical content digest; absent = manifest fixed at initialize. */
+  revision?: string;
+
   /** Server supports push/event */
   pushEvents?: boolean;
 
-  /** Context hook capabilities */
+  /**
+   * Context hooks — §5.1 recursive shape. Boolean `true` at any level is
+   * shorthand for every leaf beneath it. `afterInference` is REMOVED in
+   * 0.5.0 (replaced by metadata-only inference/lifecycle, §10.5).
+   */
   contextHooks?: {
-    beforeInference?: boolean;
-    afterInference?: boolean | { blocking: boolean };
+    beforeInference?: boolean | {
+      observe?: boolean;
+      inject?: { system?: boolean; beforeUser?: boolean; afterUser?: boolean };
+    };
   };
 
-  /** Server-initiated inference capabilities */
-  inferenceRequest?: {
-    streaming?: boolean;
-  };
+  /** Server-initiated inference. `true` = the capability with no refinements. */
+  inferenceRequest?: boolean | { streaming?: boolean };
+
+  /** Server consumes inference/lifecycle notifications (§10.5). */
+  inferenceLifecycle?: boolean;
 
   /** Server supports model/info requests */
   modelInfo?: boolean;
@@ -122,8 +132,8 @@ export interface McplCapabilities {
   /** Declared feature sets (keyed by feature set name) */
   featureSets?: Record<string, FeatureSetDeclaration>;
 
-  /** Channel capabilities */
-  channels?: McplChannelCapabilities;
+  /** Channel capabilities — §14.1 object of leaves, or `true` for all. */
+  channels?: boolean | McplChannelCapabilities;
 }
 
 /**
@@ -134,23 +144,28 @@ export interface McplHostCapabilities {
   version: string;
   pushEvents?: boolean;
   contextHooks?: {
-    beforeInference?: boolean;
-    afterInference?: boolean | { blocking: boolean };
-  };
-  inferenceRequest?: {
-    streaming?: boolean;
+    beforeInference?: boolean | {
+      observe?: boolean;
+      inject?: { system?: boolean; beforeUser?: boolean; afterUser?: boolean };
+    };
   };
+  inferenceRequest?: boolean | { streaming?: boolean };
+  inferenceLifecycle?: boolean;
+  modelInfo?: boolean;
   featureSets?: boolean;
-  channels?: McplChannelCapabilities;
+  channels?: boolean | McplChannelCapabilities;
 }
 
-/** Channel-specific capability flags. */
+/** Channel capability leaves (§14.1). `observe` was the pre-0.5 name for
+ *  what split into `incoming` — removed, not aliased. */
 export interface McplChannelCapabilities {
   register?: boolean;
-  publish?: boolean;
-  observe?: boolean;
   lifecycle?: boolean;
+  publish?: boolean;
+  incoming?: boolean;
   streaming?: boolean;
+  acknowledge?: boolean;
+  typing?: boolean;
 }
 
 // ============================================================================
@@ -209,6 +224,15 @@ export interface McplServerConfig {
    */
   accessProvider?: () => Promise<string | null>;
 
+  /**
+   * Host-owned authority for the `host/command` admin surface (undo / hide /
+   * unstick). DEFAULT FALSE: no §6.2 capability path exists for it, and the
+   * grant cannot confer it — only this config, decided by the operator, can
+   * (PR #79 review blocker 9). The one legitimate fleet user is
+   * discord-mcpl's slash-command relay.
+   */
+  allowHostCommands?: boolean;
+
   /** Feature sets to enable on connect */
   enabledFeatureSets?: string[];
 
@@ -233,6 +257,37 @@ export interface McplServerConfig {
    */
   disabledTools?: string[];
 
+  /**
+   * Capability allow-list: dotted paths as the server advertises them in its
+   * initialize response (`pushEvents`, `contextHooks.beforeInference`,
+   * `contextHooks.afterInference`, `inferenceRequest`, `modelInfo`,
+   * `channels`, `channels.streaming`, …). `*` matches one dot-segment
+   * (feature-set pattern rules), and a pattern matching a parent
+   * (`contextHooks`) covers every flag beneath it.
+   *
+   * If set, only advertised capabilities matching at least one pattern
+   * survive the handshake; everything else behaves as if the server had
+   * never advertised it. This is the host-side gate on hook fan-out: a
+   * server whose `contextHooks.afterInference` is masked never receives
+   * turn text, no matter what it self-advertises. Masked server-initiated
+   * capabilities (`pushEvents`, `inferenceRequest`, whole-`channels`) are
+   * also enforced inbound — the connection rejects those methods with
+   * CAPABILITY_DISABLED (-32002).
+   *
+   * `disabledCapabilities` takes precedence on conflict. `version` and
+   * `featureSets` are not maskable here — feature sets have their own
+   * enable/disable knobs above.
+   */
+  enabledCapabilities?: string[];
+
+  /**
+   * Capability deny-list (same paths and wildcard syntax as
+   * enabledCapabilities). Wins over enabledCapabilities on conflict.
+   * `disabledCapabilities: ['contextHooks.*']` is the one-line "this server
+   * gets no hook visibility" switch.
+   */
+  disabledCapabilities?: string[];
+
   /** Scope configurations per feature set */
   scopes?: Record<string, ScopeConfig>;
 
@@ -352,16 +407,51 @@ export interface FeatureSetDeclaration {
  * Spec Section 6.7.
  */
 export interface FeatureSetsUpdateParams {
-  /** Feature sets to enable */
+  /**
+   * The effective capability grant (§5.4) — the sole normative allowlist.
+   * Full §6.2 paths. Absence of a path is denial. In the Request form an
+   * absent FIELD is a grant of nothing (§5.3 as pinned 2026-08-02), never
+   * "no change".
+   */
+  effectiveCapabilities?: string[];
+
+  /** Advertised-but-denied paths. Diagnostic only (§5.4) — MUST NOT
+   *  participate in any authorization decision on either side. */
+  deniedCapabilities?: string[];
+
+  /** Feature sets to enable. Absent = no constraint (derivation governs);
+   *  present = allowlist (§5.3 as pinned). */
   enabled?: string[];
 
   /** Feature sets to disable */
   disabled?: string[];
-
-  /** Scope configurations per feature set */
-  scopes?: Record<string, ScopeConfig>;
 }
 
+/**
+ * featureSets/update result — the degradation receipt (§6.7). Consequence
+ * testimony, never policy authority: the host MUST NOT widen any grant in
+ * response to anything in here.
+ */
+export type FeatureSetsUpdateResult =
+  | {
+      accepted: true;
+      /** Omitted when nothing degraded (§6.7). */
+      mode?: 'degraded';
+      unavailableFeatures?: Array<{
+        featureSet: string;
+        missingCapabilities: string[];
+        effect: string;
+      }>;
+      notes?: string[];
+    }
+  | {
+      accepted: false;
+      /** REQUIRED on refusal (§6.7): the server names which applies. */
+      fallback: 'mcp-only' | 'close';
+      missingCapabilities?: string[];
+      reason?: string;
+    };
+
 /**
  * featureSets/changed params (Server → Host, Notification).
  * Spec Section 6.7.
@@ -556,18 +646,48 @@ export interface PushEventResult {
  * Distinct from membrane's ModelInfo which tracks requested vs actual model.
  * Spec Section 10.1.
  */
+/**
+ * inference/lifecycle params (Host → Server, Notification). SPEC §10.5.
+ *
+ * BEST-EFFORT: the host attempts exactly one terminal phase per `started`
+ * on every exit path it controls, but an unacknowledged Notification cannot
+ * guarantee delivery — consumers MUST dedupe by inferenceId and MUST retain
+ * a safety timeout. Carries no content: `modifiedResponse` and the blocking
+ * hook form are gone with context/afterInference.
+ */
+export interface InferenceLifecycleParams {
+  inferenceId: string;
+  conversationId: string;
+  turnIndex: number;
+  phase: 'started' | 'completed' | 'aborted' | 'failed';
+}
+
+/** mcpl/manifestChanged params (Server → Host, Notification). §17.3. */
+export interface ManifestChangedParams {
+  /** §17.2 canonical content digest. Untrusted; equality-only. */
+  revision: string;
+  /** Subset of the three §17.1 domains. A hint the host MAY ignore. */
+  domains: Array<'capabilities' | 'featureSets' | 'tagOntology'>;
+}
+
 export interface McplModelInfo {
   /** Model identifier (e.g., "claude-opus-4-5-20251101") */
   id: string;
 
-  /** Model vendor (e.g., "anthropic") */
-  vendor: string;
+  /** Model vendor (e.g., "anthropic"). Omitted when the host has no
+   *  truthful source — never fabricated. */
+  vendor?: string;
 
-  /** Context window size in tokens */
-  contextWindow: number;
+  /** Context window size in tokens. Omitted when unknown (a numeric field
+   *  cannot express "unknown", and a fabricated 200000 was false for
+   *  residents configured at 300k/600k — PR #79 review). The §12.2
+   *  model/info RESULT requires it, which is why this host does not
+   *  advertise modelInfo; hook params carry honesty-over-completeness. */
+  contextWindow?: number;
 
-  /** Model capabilities (e.g., ["vision", "tools"]) */
-  capabilities: string[];
+  /** Model capabilities (e.g., ["vision", "tools"]). Omitted when the
+   *  host has no truthful source. */
+  capabilities?: string[];
 }
 
 /**
@@ -629,53 +749,6 @@ export interface BeforeInferenceResult {
   contextInjections: McplContextInjection[];
 }
 
-/**
- * context/afterInference params (Host → Server, Request or Notification).
- * Spec Section 10.5.
- */
-export interface AfterInferenceParams {
-  /** Inference identifier (matches beforeInference) */
-  inferenceId: string;
-
-  /** Persistent across turns */
-  conversationId: string;
-
-  /** 0-indexed turn number */
-  turnIndex: number;
-
-  /** Original user input */
-  userMessage: string | null;
-
-  /** Generated assistant response */
-  assistantMessage: string;
-
-  /** Model metadata */
-  model: McplModelInfo;
-
-  /** Token usage */
-  usage: {
-    inputTokens: number;
-    outputTokens: number;
-    cacheCreationTokens?: number;
-    cacheReadTokens?: number;
-  };
-}
-
-/**
- * context/afterInference result (Server → Host, only for blocking hooks).
- * Spec Section 10.5.
- */
-export interface AfterInferenceResult {
-  /** Feature set that provided this response */
-  featureSet: string;
-
-  /** Modified response text (replaces assistantMessage if present) */
-  modifiedResponse?: string;
-
-  /** Arbitrary metadata */
-  metadata?: Record<string, unknown>;
-}
-
 // ============================================================================
 // Section 11 — Server-Initiated Inference
 // ============================================================================
@@ -861,7 +934,14 @@ export interface ChannelsRegisterParams {
  * channels/register result (Host → Server).
  */
 export interface ChannelsRegisterResult {
+  /** Legacy pre-0.5 field: ids accepted. Kept for un-migrated servers. */
   registered: string[];
+  /**
+   * §14.5 itemized results — one entry per SUBMITTED descriptor. 0.5
+   * servers key off this: a missing verdict is not a verdict, and a result
+   * without `results` is read by strict servers as accepting nothing.
+   */
+  results: Array<{ id: string; accepted: boolean; reason?: string }>;
 }
 
 /**
@@ -1033,6 +1113,8 @@ export interface ChannelIncomingMessageResult {
   messageId: string;
   accepted: boolean;
   conversationId?: string;
+  /** §14.5: why a message was rejected (e.g. unknown/unregistered channel). */
+  reason?: string;
 }
 
 // ============================================================================
@@ -1066,9 +1148,13 @@ export const McplMethod = {
   // Push events (Server → Host)
   PushEvent: 'push/event',
 
-  // Context hooks (Host → Server)
+  // Context hooks (Host → Server). context/afterInference is gone with the
+  // rest of its surface: removed from the spec in 0.5.0 (§10.5, replaced by
+  // inference/lifecycle), never sent by the runtime, and not part of the
+  // package's public API. Pre-0.5 SERVERS' wire handlers for it are their
+  // own compatibility surface, retired on the fleet-on-0.5 evidence
+  // schedule, not here.
   BeforeInference: 'context/beforeInference',
-  AfterInference: 'context/afterInference',
 
   // Server-initiated inference (Server → Host / Host → Server)
   InferenceRequest: 'inference/request',
@@ -1077,6 +1163,18 @@ export const McplMethod = {
   // Model info (Server → Host)
   ModelInfo: 'model/info',
 
+  // Inference lifecycle (Host → Server, Notification) — §10.5, replaces
+  // context/afterInference. Metadata only; BEST-EFFORT delivery.
+  InferenceLifecycle: 'inference/lifecycle',
+
+  // Server manifest changes (§17). manifestChanged is S→H Notification —
+  // an opaque revision plus changed domains, NO payload, deliberately
+  // ungated (§17.3: gating it would silence exactly the servers whose
+  // grants just narrowed). manifest is H→S Request returning the complete
+  // current experimental.mcpl object, never a delta.
+  ManifestChanged: 'mcpl/manifestChanged',
+  Manifest: 'mcpl/manifest',
+
   // Feature sets
   FeatureSetsUpdate: 'featureSets/update',
   FeatureSetsChanged: 'featureSets/changed',

package/src/modules/workspace/index.ts

@@ -1080,6 +1080,47 @@ export class WorkspaceModule implements Module {
     return { data: blob };
   }
 
+  /**
+   * Read a file's raw bytes straight from the mount's filesystem, bypassing
+   * the Chronicle tree.
+   *
+   * For material that is *passing through* rather than being kept: an upload,
+   * a render being shipped somewhere, a file handed to a service. The store
+   * path (`readBinary`) is append-only, so reading through it means every
+   * byte is retained forever and the mount's `maxFileSize` guard applies —
+   * correct for the resident's memory, wrong for egress, where paying a
+   * permanent cost to send something once is the wrong trade.
+   *
+   * Same mount boundary and traversal guard as every other path here: only
+   * declared mounts, nothing above their root. Deliberately does NOT sync,
+   * register, or hash anything — it reads and returns.
+   */
+  async readBinaryFromDisk(
+    mountPrefixedPath: string,
+    opts: { maxBytes?: number } = {},
+  ): Promise<{ data: Buffer; absolutePath: string } | { error: string }> {
+    let mount: MountState;
+    let relativePath: string;
+    try {
+      ({ mount, relativePath } = this.parsePath(mountPrefixedPath));
+    } catch (error) {
+      return { error: error instanceof Error ? error.message : String(error) };
+    }
+    const absolutePath = resolve(mount.config.path, relativePath);
+    try {
+      const info = await stat(absolutePath);
+      if (!info.isFile()) return { error: `Not a file: ${mountPrefixedPath}` };
+      if (opts.maxBytes !== undefined && info.size > opts.maxBytes) {
+        return { error: `File too large: ${info.size} > ${opts.maxBytes} bytes` };
+      }
+      return { data: await readFile(absolutePath), absolutePath };
+    } catch (error) {
+      const code = (error as { code?: string }).code;
+      if (code === 'ENOENT') return { error: `File not found on disk: ${mountPrefixedPath}` };
+      return { error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
   /**
    * Parse a mount-prefixed path into (mountName, relativePath).
    */
@@ -1919,6 +1960,7 @@ export class WorkspaceModule implements Module {
   private async handleSync(input: SyncInput): Promise<ToolResult> {
     const store = this.getStore();
     const allResults: Array<{ mount: string; synced: string[]; conflicts: ConflictInfo[] }> = [];
+    const allSkipped: Array<{ mount: string; path: string; reason: string }> = [];
 
     let mountsToSync: Array<{ name: string; mount: MountState }>;
     if (input.mount) {
@@ -1951,6 +1993,11 @@ export class WorkspaceModule implements Module {
         });
         this.emitFsEvents(name, result.synced, result.conflicts);
       }
+      // Skips were previously computed and dropped, so "nothing synced" and
+      // "your file was refused" looked identical from the outside. Say which.
+      for (const s of result.skipped) {
+        allSkipped.push({ mount: name, path: s.path, reason: s.reason });
+      }
     }
 
     return {
@@ -1959,6 +2006,7 @@ export class WorkspaceModule implements Module {
         results: allResults,
         totalSynced: allResults.reduce((sum, r) => sum + r.synced.length, 0),
         totalConflicts: allResults.reduce((sum, r) => sum + r.conflicts.length, 0),
+        ...(allSkipped.length > 0 ? { skipped: allSkipped } : {}),
       },
     };
   }

package/src/modules/workspace/sync.ts

@@ -40,6 +40,13 @@ export function hashContent(content: string | Buffer): string {
 /**
  * Check if content appears to be binary.
  */
+export interface SkippedFile {
+  /** Relative path of the file that was not synced */
+  path: string;
+  /** Why, in words the resident can act on */
+  reason: string;
+}
+
 export function isBinary(buffer: Buffer): boolean {
   // Check for null bytes in first 8KB
   const check = buffer.subarray(0, 8192);
@@ -68,8 +75,11 @@ export interface SyncResult {
   synced: SyncedPath[];
   /** Paths that conflicted (both agent and user modified) — filesystem wins */
   conflicts: ConflictInfo[];
-  /** Paths that were skipped (binary, too large, etc.) */
-  skipped: string[];
+  /** Paths that were skipped, each with the reason — a silently skipped file
+   *  is indistinguishable from one that synced cleanly, which is how a
+   *  resident ends up believing a file is in their workspace when it never
+   *  arrived. */
+  skipped: SkippedFile[];
 }
 
 /**
@@ -93,7 +103,7 @@ export async function syncFromFs(
   for (const relativePath of filesToSync) {
     const absolutePath = safePath(mount.config.path, relativePath);
     if (!absolutePath) {
-      result.skipped.push(relativePath);
+      result.skipped.push({ path: relativePath, reason: 'path resolves outside the mount' });
       continue;
     }
 
@@ -113,13 +123,23 @@ export async function syncFromFs(
       const fileStat = await stat(absolutePath);
       if (!fileStat.isFile()) continue;
       if (fileStat.size > maxSize) {
-        result.skipped.push(relativePath);
+        result.skipped.push({
+          path: relativePath,
+          reason: `too large: ${fileStat.size} bytes > maxFileSize ${maxSize}`,
+        });
         continue;
       }
 
       const buffer = await readFile(absolutePath);
       if (isBinary(buffer)) {
-        result.skipped.push(relativePath);
+        // Disk -> store sync is text-only, at ANY size: the tree stores text
+        // blobs. Binary that must live in the store has to be written through
+        // writeBinary; binary that is only passing through should be read with
+        // readBinaryFromDisk instead of synced at all.
+        result.skipped.push({
+          path: relativePath,
+          reason: 'binary file — disk sync stores text only (read it from disk, or write it via a binary-aware tool)',
+        });
         continue;
       }
 
@@ -159,8 +179,11 @@ export async function syncFromFs(
 
       store.treeSet(mount.treeStateId, relativePath, entry);
       result.synced.push({ path: relativePath, op: existing ? 'modified' : 'created' });
-    } catch {
-      result.skipped.push(relativePath);
+    } catch (error) {
+      result.skipped.push({
+        path: relativePath,
+        reason: error instanceof Error ? error.message : String(error),
+      });
     }
   }
 

package/src/refusal-reactions.ts

@@ -0,0 +1,37 @@
+/**
+ * Refusal-reaction markers — the single source of truth for the emoji the
+ * framework places on a message when inference is refused (see
+ * AgentFramework.reactToRefusal), exported so host composition can derive
+ * a protective suppression baseline from the exact set the framework emits.
+ *
+ * These annotations are placed by the framework on the resident's account
+ * and must never re-enter a resident's context as reaction events — that is
+ * the self-amplifying loop behind the 8/3 Mythos incident. The Discord
+ * adapter suppresses them when its operator config or the host-injected
+ * `DISCORD_SUPPRESSED_REACTIONS_BASELINE` names them; keeping the emitted
+ * set and the exported baseline as one constant is what makes drift between
+ * "what we stamp" and "what we suppress" structurally impossible, rather
+ * than a promise kept in two files.
+ */
+
+/** Refusal category → Discord reaction emoji. Unknown categories get the
+ *  fallback marker. */
+export const REFUSAL_REACTIONS: Readonly<Record<string, string>> = {
+  bio: '☣️',
+  chem: '🧪',
+  nuclear: '☢️',
+  cyber: '💻',
+  reasoning_extraction: '🧠',
+};
+
+/** Marker used when the refusal category has no dedicated emoji. */
+export const REFUSAL_REACTION_FALLBACK = '🛑';
+
+/** Every marker the framework can emit — the category map plus the
+ *  fallback, deduplicated, in stable declaration order. This IS the
+ *  protective baseline: host composition serializes it (comma-joined) into
+ *  `DISCORD_SUPPRESSED_REACTIONS_BASELINE` for adapters that render
+ *  reactions. */
+export const REFUSAL_REACTION_BASELINE: readonly string[] = [
+  ...new Set([...Object.values(REFUSAL_REACTIONS), REFUSAL_REACTION_FALLBACK]),
+];

package/src/tool-result-history.ts

@@ -16,14 +16,36 @@
 
 import { safeSlice } from './safe-slice.js';
 
+/**
+ * House-safe default inline cap (chars) for tool results, error results, and
+ * background-script wake payloads (issue #89: a resident should never eat a
+ * 42k blob they didn't ask for). Durable per-residence value comes from
+ * `FrameworkConfig.toolResultInlineMaxChars`; a per-agent value from
+ * agent_settings `tool_result_inline_max_chars`.
+ *
+ * Raised 5000 → 24000 (2026-08-07) on production evidence rather than taste.
+ * The first residence to actually run the 5000 default spilled 48 results in
+ * 23h, 71% of them ordinary shell output from source review — `git diff`, test
+ * runs, `sed -n '450,590p'`-style excerpts, which routinely land at 5–15k. A
+ * 5000-char cap is tuned for conversation and turns every file read into a
+ * spill round-trip for a resident doing code work. Measured on that corpus:
+ * 20000 keeps 76% inline, 24000 keeps 88%, 32000 only reaches 90% — 24000 is
+ * the elbow. Genuinely large payloads (full histories, channel registries,
+ * broad greps) still spill, which is the point.
+ */
+export const DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS = 24000;
+
 export function toolResultDataToHistoryString(data: unknown, maxChars?: number): string {
   const fromArray = tryHistoryStringFromContentArray(data);
   const str = fromArray ?? JSON.stringify(data);
-  if (maxChars && str.length > maxChars) {
-    return safeSlice(str, 0, maxChars)
-      + '\n\n[truncated — original was ' + str.length + ' chars]';
-  }
-  return str;
+  return maxChars ? truncateForHistory(str, maxChars) : str;
+}
+
+/** Bounded copy of an arbitrary string with the standard truncation notice. */
+export function truncateForHistory(str: string, maxChars: number): string {
+  if (str.length <= maxChars) return str;
+  return safeSlice(str, 0, maxChars)
+    + '\n\n[truncated — original was ' + str.length + ' chars]';
 }
 
 /**

package/src/types/agent.ts

@@ -48,6 +48,17 @@ export interface AgentConfig {
    *  restarts with recompiled (compressed) context. Default: 150000. */
   maxStreamTokens?: number;
 
+  /**
+   * The model's PHYSICAL context window (provider hard cap, e.g. 200000).
+   * When set, the framework projects each continuation round's real size
+   * (cache-inclusive input of the prior round + the blocks about to be
+   * appended + reserve for response) and restarts the stream through a fresh
+   * compile instead of dispatching a request the provider will 400
+   * (issue #92: a legal compile can walk past the physical window mid-turn).
+   * Unset → no projection; only the maxStreamTokens restart applies.
+   */
+  physicalWindowTokens?: number;
+
   /** Per-agent context compile budget (input tokens). When unset, the
    *  ContextManager's built-in default (100k) applies. */
   contextBudgetTokens?: number;
@@ -122,6 +133,31 @@ export interface AgentConfig {
    * a poison turn. Default: off (a refusal just surfaces a marker + reaction).
    */
   refusalHandling?: {
+    /**
+     * Same-model retries on a content-policy refusal, performed by MEMBRANE
+     * at the provider seam (passed through as `refusalRetries`). Default 0.
+     *
+     * Near the classifier's threshold a refusal is probabilistic rather than a
+     * property of the payload: identical bytes pass and refuse minutes apart
+     * (mythos, 2026-07-27 replay reps). So the first response is to ask again
+     * — no context surgery, no fallback model. Membrane replays the SAME
+     * request immediately and cache-warm, so only the discarded output tokens
+     * are real spend.
+     *
+     * Retrying in the framework instead was tried and removed: a requeue
+     * recompiles, so the attempts are correlated rather than fresh draws, and
+     * it cannot tell a streaming consumer to drop the abandoned attempt.
+     * Membrane announces each retry with a `retrying` stream event, which
+     * driveStream handles by discarding what was streamed.
+     *
+     * Retries are spent before the framework sees the refusal at all, so the
+     * escalation order is: membrane retries -> autoRewind (if on) -> the
+     * refusal reaction, which therefore means "the border is close" rather
+     * than firing on every near-threshold flip.
+     *
+     * Native tool mode only — see the XML-mode warning in Membrane.
+     */
+    retries?: number;
     /** Auto-rewind the triggering turn on refusal and retry. Default false. */
     autoRewind?: boolean;
     /** Max consecutive rewinds before giving up a turn. Default 3. */
@@ -141,8 +177,11 @@ export interface AgentConfig {
    *   (`>>#channel` / `>>@person` / `>>skip_reply`); unprefixed prose is never
    *   delivered — it bounces to a clipboard for a cheap prefixed resend.
    *   See docs/explicit-prose-routing.md.
+   * - 'hybrid': unprefixed prose keeps locus routing; `>>>destination` routes
+   *   that publication envelope through the same authorized resolver.
+   *   See docs/hybrid-prose-routing.md.
    */
-  proseRouting?: 'locus' | 'explicit';
+  proseRouting?: 'locus' | 'explicit' | 'hybrid';
 }
 
 /** The intentionally small set of agent settings that may change in-process. */

package/src/types/framework.ts

@@ -138,6 +138,23 @@ export interface FrameworkConfig {
    */
   codeExecution?: CodeExecutionConfig;
 
+  /**
+   * Durable inline cap (chars) for tool results — successes AND errors — and
+   * background-script wake payloads. Content over the cap is written to a
+   * workspace file under `tool-results/` (deterministic `<date>-<callId>.txt`
+   * name, overwritten on collision, retained until the workspace owner
+   * deletes it — never auto-GC'd) and replaced inline by a bounded preview
+   * plus the file reference; with no writable workspace the fallback is
+   * explicit plain truncation. Default 24000 (house-safe; issue #89). Must be
+   * >= 1000. A resident's own agent_settings value
+   * `tool_result_inline_max_chars` (durable, persisted in framework state)
+   * takes precedence over this for that agent; the EFFECTIVE cap for every
+   * source is min(desired, strategy bound) — desired values above the
+   * strategy-derived bound (maxMessageTokens * 4) are hard-clamped to it,
+   * with the clamp reported via agent_settings get.
+   */
+  toolResultInlineMaxChars?: number;
+
   /** Inference routing policy for server-initiated inference (optional). */
   inferenceRouting?: InferenceRoutingPolicy;