@animalabs/agent-framework 0.7.4 → 0.9.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;
 }
 
 // ============================================================================
@@ -198,6 +213,26 @@ export interface McplServerConfig {
    */
   token?: string;
 
+  /**
+   * Lazily resolves the connection credential at EVERY dial — first connect
+   * and each background reconnect — overriding `token` when it returns a
+   * value (null/throw falls back to `token`). Host-attached plumbing, never
+   * serialized: the point is that credentials stay out of the agent's
+   * context entirely (the agent asks for access by name; the host fetches
+   * something fresh each redial, which also makes short-lived credentials
+   * viable where a static `token` forced long ones).
+   */
+  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[];
 
@@ -222,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>;
 
@@ -341,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.
@@ -545,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[];
 }
 
 /**
@@ -618,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
 // ============================================================================
@@ -850,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 }>;
 }
 
 /**
@@ -1022,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;
 }
 
 // ============================================================================
@@ -1055,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',
@@ -1066,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/module-registry.ts

@@ -75,6 +75,15 @@ export class ModuleRegistry {
   private pushEventFn: (event: ProcessEvent) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
   private callToolFn: (call: ToolCall) => Promise<ToolResult>;
+  /** Framework ops-alert channel, surfaced to modules via
+   *  ModuleContext.notifyOps. Readonly-public so ModuleContextImpl can
+   *  delegate without another positional constructor parameter. */
+  readonly notifyOpsFn?: (
+    kind: string,
+    agentName: string,
+    message: string,
+    data?: Record<string, unknown>,
+  ) => void;
 
   constructor(
     store: JsStore,
@@ -89,6 +98,7 @@ export class ModuleRegistry {
       pushEvent: (event: ProcessEvent) => void;
       onTrace: (listener: TraceEventListener) => () => void;
       callTool: (call: ToolCall) => Promise<ToolResult>;
+      notifyOps?: (kind: string, agentName: string, message: string, data?: Record<string, unknown>) => void;
     }
   ) {
     this.store = store;
@@ -102,6 +112,7 @@ export class ModuleRegistry {
     this.pushEventFn = options.pushEvent;
     this.onTraceFn = options.onTrace;
     this.callToolFn = options.callTool;
+    this.notifyOpsFn = options.notifyOps;
   }
 
   /**
@@ -230,6 +241,25 @@ export class ModuleRegistry {
     return tools;
   }
 
+  /**
+   * All utilities from all modules, namespaced exactly like tools
+   * (`module--name`). See Module.getUtilities — these are deliberately kept
+   * out of the model-facing tool list and surfaced through the framework's
+   * `utils` meta-tool; dispatch goes through the same handleToolCall.
+   */
+  getAllUtilities(): ToolDefinition[] {
+    const utilities: ToolDefinition[] = [];
+    for (const module of this.modules.values()) {
+      for (const util of module.getUtilities?.() ?? []) {
+        utilities.push({
+          ...util,
+          name: `${module.name}--${util.name}`,
+        });
+      }
+    }
+    return utilities;
+  }
+
   /**
    * Handle a tool call by routing to the appropriate module.
    */
@@ -556,6 +586,10 @@ class ModuleContextImpl implements ModuleContext {
     return this.callToolFn(call);
   }
 
+  notifyOps(kind: string, agentName: string, message: string, data?: Record<string, unknown>): void {
+    this.registry.notifyOpsFn?.(kind, agentName, message, data);
+  }
+
   addMessage(
     participant: string,
     content: ContentBlock[],

package/src/modules/workspace/index.ts

@@ -34,7 +34,7 @@ import type {
 } from './types.js';
 import { WORKSPACE_FS_EVENT_TYPES, opToEventType } from './types.js';
 import { MountWatcher, type FsChange } from './watcher.js';
-import { syncFromFs, materializeToFs, hashContent, DEFAULT_MAX_FILE_SIZE, type ConflictInfo } from './sync.js';
+import { syncFromFs, materializeToFs, hashContent, isBinary, DEFAULT_MAX_FILE_SIZE, type ConflictInfo } from './sync.js';
 
 export type {
   WorkspaceConfig,
@@ -525,6 +525,11 @@ export class WorkspaceModule implements Module {
   private config: WorkspaceConfig;
   private mounts = new Map<string, MountState>();
   private watchers = new Map<string, MountWatcher>();
+  /** Persisted state decoded in start(), held until mounts exist to apply it
+   *  to — in the Host ordering start() runs before initStore() creates the
+   *  mounts, so restoration must be second-callback-safe like watcher
+   *  startup already is (issue #72). Cleared after application. */
+  private savedState: WorkspaceModuleState | null = null;
 
   constructor(config: WorkspaceConfig) {
     // Detect overlapping mount paths: if mount A contains mount B,
@@ -593,32 +598,47 @@ export class WorkspaceModule implements Module {
       this.mounts.set(mount.name, mountState);
     }
 
+    this.applySavedState();
     this.ensureRunning();
   }
 
   async start(ctx: ModuleContext): Promise<void> {
     this.ctx = ctx;
 
-    // Restore persisted state if restarting
+    // Decode persisted state if restarting; application waits until mounts
+    // exist (see applySavedState) — in the Host ordering they don't yet.
     if (ctx.isRestart) {
-      const saved = ctx.getState<WorkspaceModuleState>();
-      if (saved) {
-        for (const [name, meta] of Object.entries(saved.mounts)) {
-          const mount = this.mounts.get(name);
-          if (mount) {
-            mount.lastMaterializedSeq = meta.lastMaterializedSeq;
-            mount.lastMaterializedBranchId = meta.lastMaterializedBranchId ?? null;
-            // watcherReadyAt intentionally not restored — each session must
-            // observe its own watcher attach, otherwise a stale timestamp
-            // would hide a new-session attach failure.
-          }
-        }
-      }
+      this.savedState = ctx.getState<WorkspaceModuleState>() ?? null;
     }
 
+    this.applySavedState();
     this.ensureRunning();
   }
 
+  /**
+   * Apply persisted per-mount state once both halves of the lifecycle have
+   * happened. Like watcher startup, either callback may fire second, so both
+   * start() and initStore() call this; it runs to effect exactly once — the
+   * saved payload is cleared after application so stale persisted values can
+   * never overwrite newer runtime state (e.g. a materialization that already
+   * happened this session).
+   */
+  private applySavedState(): void {
+    if (!this.savedState || this.mounts.size === 0) return;
+
+    for (const [name, meta] of Object.entries(this.savedState.mounts)) {
+      const mount = this.mounts.get(name);
+      if (mount) {
+        mount.lastMaterializedSeq = meta.lastMaterializedSeq;
+        mount.lastMaterializedBranchId = meta.lastMaterializedBranchId ?? null;
+        // watcherReadyAt intentionally not restored — each session must
+        // observe its own watcher attach, otherwise a stale timestamp
+        // would hide a new-session attach failure.
+      }
+    }
+    this.savedState = null;
+  }
+
   /**
    * Start chokidar watchers and emit workspace:mounted events.
    * Idempotent: safe to call from both start() and initStore(), fires once
@@ -725,6 +745,15 @@ export class WorkspaceModule implements Module {
     this.ctx = null;
   }
 
+  /** Mount names + modes, for peer callers (framework spill/journal paths)
+   *  that need a writable mount without reaching into private state. */
+  getMounts(): Array<{ name: string; mode: 'read-write' | 'read-only' }> {
+    return [...this.mounts.values()].map((m) => ({
+      name: m.config.name,
+      mode: m.config.mode === 'read-only' ? 'read-only' : 'read-write',
+    }));
+  }
+
   // ==========================================================================
   // Tool Definitions
   // ==========================================================================
@@ -1308,6 +1337,11 @@ export class WorkspaceModule implements Module {
       if (!fileStat.isFile() || fileStat.size > maxSize) return;
 
       const buffer = await readFile(absolutePath);
+      // Binaries are never synced into the tree (mirrors syncFromFs): the old
+      // utf-8 round-trip here silently replaced non-UTF-8 bytes with U+FFFD,
+      // permanently mangling images in the blob store. Binary reads are served
+      // straight from disk (readImageFromFilesystem / read_image fallback).
+      if (isBinary(buffer)) return;
       const content = buffer.toString('utf-8');
       const blobHash = store.storeBlob(Buffer.from(content, 'utf-8'), 'text/plain');
 

package/src/modules/workspace/sync.ts

@@ -40,7 +40,7 @@ export function hashContent(content: string | Buffer): string {
 /**
  * Check if content appears to be binary.
  */
-function isBinary(buffer: Buffer): boolean {
+export function isBinary(buffer: Buffer): boolean {
   // Check for null bytes in first 8KB
   const check = buffer.subarray(0, 8192);
   for (let i = 0; i < check.length; i++) {

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,26 @@
 
 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 temporary per-agent lift from
+ * agent_settings `tool_result_inline_max_chars`.
+ */
+export const DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS = 5000;
+
 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. */