@animalabs/agent-framework 0.8.0 → 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;
 }
 
 // ============================================================================
@@ -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/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. */

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 5000 (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;
 

package/src/types/trace.ts

@@ -169,6 +169,19 @@ export type TraceEvent =
       agentStatus: string;
       result: unknown;
     })
+  | (TraceEventBase & {
+      /**
+       * A writable workspace existed but the oversized-result spill write
+       * failed (size cap, storeBlob failure, …) — the over-cap tail was NOT
+       * retained. Distinct from the no-workspace fallback, which is silent
+       * by design (nothing unexpected happened).
+       */
+      type: 'tool:spill_failed';
+      label: string;
+      path: string;
+      contentLength: number;
+      error: string;
+    })
 
   // Module lifecycle
   | (TraceEventBase & { type: 'module:added'; moduleName: string })
@@ -339,6 +352,15 @@ export type TraceEvent =
       /** True when a background reconnect loop will keep retrying. */
       willRetry: boolean;
     })
+  | (TraceEventBase & {
+      /** §17.6: the ONE normalized receipt per manifest change — closed
+       *  host-derived impact vocabulary, never a server-authored flag. */
+      type: 'mcpl:manifest-change-receipt';
+      serverId: string;
+      revision: string | null;
+      announcedDomains: string[];
+      impacts: Array<{ impact: string; subject: string; disposition: string }>;
+    })
   | (TraceEventBase & {
       type: 'mcpl:server-reconnected';
       serverId: string;