@msm-core/mini 0.5.1 → 0.8.0

package/dist/core/loop.d.ts

@@ -7,9 +7,51 @@
  *   respond/clarify/escalate → deliver → done
  *   budget exhausted → force_respond → done
  */
-import type { AgentConfig } from "./types.js";
+import type { AgentConfig, Brain, CompactionPort } from "./types.js";
 /**
  * Create a stateful agent from config.
  * Returns an Agent object — call .handle() on every incoming event.
  */
 export declare function createAgent(config: AgentConfig): import("./types.js").Agent;
+/** Tuning for `createBrainCompactor`. Every field has a working default. */
+export interface BrainCompactorOptions {
+    /**
+     * Compact once the derived conversation is LONGER than this many messages.
+     * Defaults to the budget the loop passes in — i.e. compact exactly when the
+     * trim would otherwise start dropping the head, which is the moment the
+     * silent loss begins.
+     */
+    threshold?: number;
+    /** Trailing turns to leave verbatim. Default 2 — the current exchange and the one before it. */
+    keepTurns?: number;
+    /** The system context for the summarising call. */
+    systemContext?: string;
+    /** The instruction placed above the transcript. */
+    instruction?: string;
+}
+/**
+ * A `CompactionPort` that summarises with an injected `Brain`.
+ *
+ * **A reference implementation, not a requirement.** The port is the contract;
+ * this is one way to satisfy it, and a consumer with a cheaper model, a local
+ * one, or a rule-based summariser wires up its own and the loop cannot tell.
+ *
+ * It opens no connection of its own. The summary is an ordinary `brain.run`
+ * call on a brain the caller built and injected — the same covenant as every
+ * other port in this package: nothing here knows the network.
+ *
+ * Two deliberate refusals:
+ *
+ *   - It does not use the agent's own tools, history or system context. A
+ *     summariser that could call tools is a second agent with no budget and no
+ *     guards.
+ *   - It does not swallow a provider failure. An empty answer is a decision
+ *     ("nothing to compact"); a thrown error is a broken compactor, and a
+ *     compactor that has been quietly failing is a session quietly losing its
+ *     head — the failure ض١ exists to end.
+ *
+ * The rendering is deterministic and reuses `toWireMessage`, so the summariser
+ * reads a tool round-trip exactly as the agent's own model reads it (س٤'s wire
+ * contract), and the same conversation always produces the same prompt.
+ */
+export declare function createBrainCompactor(brain: Brain, opts?: BrainCompactorOptions): CompactionPort;