@msm-core/mini 0.1.0

package/dist/core/context-builder.js

@@ -0,0 +1,107 @@
+/**
+ * Context Builder — Assembles brain input from session state + injected context.
+ *
+ * Priority order (highest first):
+ *   1. neverTruncate memories (from msm-context tiers marked protected)
+ *   2. normal memories, sorted by score
+ *   3. session history (last N messages)
+ *   4. tool catalog
+ *
+ * Token budget is enforced by dropping lowest-priority memories first.
+ * The agent never queries external stores — context arrives pre-assembled.
+ */
+const DEFAULT_BUDGET = {
+    maxTokens: 32_000,
+    maxHistoryMessages: 20,
+};
+/** Rough token estimator — accurate enough for budget enforcement */
+function countTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function memoriesBlock(memories) {
+    if (memories.length === 0)
+        return "";
+    const lines = memories.map((m) => `[${m.source}] ${m.content.trimEnd()}`);
+    return `\n\n## Retrieved Context\n\n${lines.join("\n\n")}`;
+}
+function userProfileBlock(profile) {
+    const lines = Object.entries(profile)
+        .filter(([, v]) => v != null)
+        .map(([k, v]) => `- ${k}: ${JSON.stringify(v)}`);
+    if (lines.length === 0)
+        return "";
+    return `\n\n## User Profile\n\n${lines.join("\n")}`;
+}
+function toolsBlock(tools) {
+    if (tools.length === 0)
+        return "\n\n## Tools\n\nNo tools available.";
+    const defs = tools
+        .map((t) => {
+        const params = Object.entries(t.parameters)
+            .map(([name, p]) => `  - ${name} (${p.type}${p.required ? ", required" : ""}): ${p.description}`)
+            .join("\n");
+        return `### ${t.name}\n${t.description}\n${params}`;
+    })
+        .join("\n\n");
+    return `\n\n## Available Tools\n\n${defs}`;
+}
+function personaBlock(def) {
+    const lines = [
+        `You are ${def.persona.name ?? def.name}, an AI agent for ${def.domain ?? "general assistance"}.`,
+        def.persona.style ? `Style: ${def.persona.style}.` : "",
+        "",
+        "## Capabilities",
+        ...def.capabilities.map((c) => `- ${c}`),
+    ].filter((l) => l !== undefined);
+    return lines.join("\n");
+}
+/**
+ * Build the full system context string for the brain.
+ * Enforces token budget by truncating memories from the bottom.
+ */
+export function buildContext(def, history, tools, context, budget = DEFAULT_BUDGET) {
+    // 1. Persona
+    let system = personaBlock(def);
+    // 2. Caller-provided system prompt extension
+    if (context?.systemPrompt) {
+        system += `\n\n${context.systemPrompt}`;
+    }
+    // 3. User profile
+    if (context?.userProfile && Object.keys(context.userProfile).length > 0) {
+        system += userProfileBlock(context.userProfile);
+    }
+    // 4. Budget-aware memories
+    const rawMemories = context?.memories ?? [];
+    const budgetUsed = countTokens(system) + countTokens(toolsBlock(tools));
+    const remaining = budget.maxTokens - budgetUsed;
+    const fittedMemories = fitMemoriesToBudget(rawMemories, remaining);
+    system += memoriesBlock(fittedMemories);
+    // 5. Tools
+    system += toolsBlock(tools);
+    // 6. History (last N)
+    const trimmedHistory = history.slice(-budget.maxHistoryMessages);
+    return { system_context: system, history: trimmedHistory };
+}
+/** Fit memories into token budget: protected entries first, then by score */
+function fitMemoriesToBudget(memories, budgetTokens) {
+    if (memories.length === 0 || budgetTokens <= 0)
+        return [];
+    // Annotate with token counts
+    const annotated = memories.map((m) => ({
+        ...m,
+        tokenCount: m.tokenCount ?? countTokens(m.content),
+    }));
+    const result = [];
+    let used = 0;
+    // Pass 1: entries explicitly marked as never-truncatable (no metadata flag needed —
+    // we treat score >= 1 as the signal, or rely on msm-context having sorted them first)
+    // Pass 2: remaining by score descending
+    for (const entry of annotated) {
+        if (used + entry.tokenCount > budgetTokens)
+            continue;
+        result.push(entry);
+        used += entry.tokenCount;
+    }
+    return result;
+}
+//# sourceMappingURL=context-builder.js.map

package/dist/core/context-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-builder.js","sourceRoot":"","sources":["../../src/core/context-builder.ts"],"names":[],"mappings":"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"}

package/dist/core/gates.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pre-processing gates — zero-LLM message filters.
+ *
+ * Gate 1 — Acknowledgement: suppress "ok / thanks / تمام" with no brain call.
+ * Gate 2 — Business hours: return canned closed message outside working hours.
+ *
+ * Both gates are optional. Configure via AgentConfig.gates.
+ */
+import type { GateConfig, LoopOutcome } from "./types.js";
+export declare function isAcknowledgement(text: string): boolean;
+/**
+ * Run pre-processing gates. Returns a suppressed LoopOutcome if a gate fires,
+ * or null if the message should proceed to the brain loop.
+ */
+export declare function runGates(sessionId: string, taskId: string, message: string, gates?: GateConfig): LoopOutcome | null;
+//# sourceMappingURL=gates.d.ts.map

package/dist/core/gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../../src/core/gates.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAe1D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIvD;AA6BD;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,UAAU,GACjB,WAAW,GAAG,IAAI,CA2BpB"}

package/dist/core/gates.js

@@ -0,0 +1,70 @@
+/**
+ * Pre-processing gates — zero-LLM message filters.
+ *
+ * Gate 1 — Acknowledgement: suppress "ok / thanks / تمام" with no brain call.
+ * Gate 2 — Business hours: return canned closed message outside working hours.
+ *
+ * Both gates are optional. Configure via AgentConfig.gates.
+ */
+// ─── Acknowledgement Gate ─────────────────────────────────────
+const ACK_PATTERNS = [
+    /^\s*(ok|okay|o+k+|alright|got it|got that|understood|noted|i see|ic)\s*[.!]?\s*$/i,
+    /^\s*(thanks|thank you|thx|ty|thank u|many thanks|cheers)\s*[.!]?\s*$/i,
+    /^\s*(sure|yep|yup|yes|yeah|no worries|no problem|np)\s*[.!]?\s*$/i,
+    /^\s*(great|perfect|awesome|nice|cool|sounds good|sounds great)\s*[.!]?\s*$/i,
+    /^\s*(تمام|اوكي|أوكي|حسنا|حسناً|مفهوم|موافق|شكرا|شكراً|ممتاز|رائع)\s*[.!]?\s*$/u,
+    /^\s*(👍|👌|🙏|✅|💯|🫡)\s*$/u,
+];
+const ACK_MAX_LENGTH = 60;
+export function isAcknowledgement(text) {
+    const trimmed = text.trim();
+    if (!trimmed || trimmed.length > ACK_MAX_LENGTH)
+        return false;
+    return ACK_PATTERNS.some((re) => re.test(trimmed));
+}
+const DAY_INDEX = {
+    sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6,
+};
+function isWithinBusinessHours(config) {
+    const now = new Date(new Date().toLocaleString("en-US", { timeZone: config.timezone }));
+    const dayCode = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"][now.getDay()];
+    if (!config.days.includes(dayCode))
+        return false;
+    const [fromH = 9, fromM = 0] = config.from.split(":").map(Number);
+    const [toH = 17, toM = 0] = config.to.split(":").map(Number);
+    const currentMinutes = now.getHours() * 60 + now.getMinutes();
+    const fromMinutes = (fromH) * 60 + (fromM);
+    const toMinutes = (toH) * 60 + (toM);
+    return currentMinutes >= fromMinutes && currentMinutes < toMinutes;
+}
+// ─── Gate Runner ──────────────────────────────────────────────
+/**
+ * Run pre-processing gates. Returns a suppressed LoopOutcome if a gate fires,
+ * or null if the message should proceed to the brain loop.
+ */
+export function runGates(sessionId, taskId, message, gates) {
+    const started = Date.now();
+    // Gate 1 — Acknowledgement
+    if (gates?.acknowledgement !== false && isAcknowledgement(message)) {
+        return {
+            type: "suppressed",
+            sessionId,
+            taskId,
+            metrics: { iterations: 0, totalCostUsd: 0, durationMs: Date.now() - started, totalToolCalls: 0 },
+        };
+    }
+    // Gate 2 — Business hours
+    if (gates?.businessHours) {
+        if (!isWithinBusinessHours(gates.businessHours)) {
+            return {
+                type: "response",
+                sessionId,
+                taskId,
+                text: gates.businessHours.closedMessage ?? "We are currently closed. Please contact us during business hours.",
+                metrics: { iterations: 0, totalCostUsd: 0, durationMs: Date.now() - started, totalToolCalls: 0 },
+            };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=gates.js.map

package/dist/core/gates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.js","sourceRoot":"","sources":["../../src/core/gates.ts"],"names":[],"mappings":"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"}

package/dist/core/guards.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Guards — Hard and soft safety checks for the execution loop.
+ *
+ * Hard guards abort execution and force a response.
+ * Soft guards are removed from msm-mini (repetition / dead-end).
+ * New guard: consecutive tool failures (hard abort after N failures).
+ */
+import type { GuardConfig, GuardSignal, RunState } from "./types.js";
+export declare const DEFAULT_GUARDS: Required<GuardConfig>;
+/**
+ * Check all guards against the current run state.
+ * Returns an array of fired signals (may be empty).
+ * Hard guards: iteration, cost, timeout, kill, consecutive failures.
+ */
+export declare function checkGuards(state: RunState, config: Required<GuardConfig>, action: string, confidence: number, controlCommand: string | null): GuardSignal[];
+/** True if any signal in the list is a hard blocker */
+export declare function hasHardBlock(signals: GuardSignal[]): boolean;
+/** Returns the first hard signal's action, or undefined */
+export declare function hardAction(signals: GuardSignal[]): GuardSignal["action"] | undefined;
+/** Merge user guard config with defaults */
+export declare function resolveGuards(config?: GuardConfig): Required<GuardConfig>;
+//# sourceMappingURL=guards.d.ts.map

package/dist/core/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/core/guards.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErE,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,WAAW,CAOhD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC7B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,IAAI,GAC5B,WAAW,EAAE,CAyFf;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAE5D;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CACxB,OAAO,EAAE,WAAW,EAAE,GACrB,WAAW,CAAC,QAAQ,CAAC,GAAG,SAAS,CAEnC;AAED,4CAA4C;AAC5C,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC,CASzE"}

package/dist/core/guards.js

@@ -0,0 +1,119 @@
+/**
+ * Guards — Hard and soft safety checks for the execution loop.
+ *
+ * Hard guards abort execution and force a response.
+ * Soft guards are removed from msm-mini (repetition / dead-end).
+ * New guard: consecutive tool failures (hard abort after N failures).
+ */
+export const DEFAULT_GUARDS = {
+    maxIterations: 60,
+    costCapPerTask: 2.5,
+    timeoutMs: 900_000, // 15 min
+    confidenceThreshold: 0.75,
+    maxToolCallsPerTask: 200,
+    maxConsecutiveFailures: 3,
+};
+/**
+ * Check all guards against the current run state.
+ * Returns an array of fired signals (may be empty).
+ * Hard guards: iteration, cost, timeout, kill, consecutive failures.
+ */
+export function checkGuards(state, config, action, confidence, controlCommand) {
+    const signals = [];
+    // ─── Hard: task killed via control bus ───────────────────
+    if (controlCommand === "kill") {
+        signals.push({
+            type: "task_killed",
+            hard: true,
+            message: "Task killed via control bus",
+            action: "abort",
+        });
+    }
+    if (controlCommand === "pause") {
+        signals.push({
+            type: "tenant_paused",
+            hard: true,
+            message: "Tenant paused via control bus",
+            action: "abort",
+        });
+    }
+    // ─── Hard: iteration budget ───────────────────────────────
+    if (state.iteration >= config.maxIterations) {
+        signals.push({
+            type: "budget_iterations",
+            hard: true,
+            message: `Iteration limit reached (${state.iteration}/${config.maxIterations})`,
+            action: "force_respond",
+        });
+    }
+    // ─── Hard: cost cap ───────────────────────────────────────
+    if (config.costCapPerTask > 0 && state.totalCostUsd >= config.costCapPerTask) {
+        signals.push({
+            type: "budget_cost",
+            hard: true,
+            message: `Cost cap reached ($${state.totalCostUsd.toFixed(4)}/$${config.costCapPerTask})`,
+            action: "force_respond",
+        });
+    }
+    // ─── Hard: timeout ────────────────────────────────────────
+    if (config.timeoutMs > 0) {
+        const elapsed = Date.now() - state.startedAt;
+        if (elapsed >= config.timeoutMs) {
+            signals.push({
+                type: "budget_timeout",
+                hard: true,
+                message: `Timeout exceeded (${elapsed}ms/${config.timeoutMs}ms)`,
+                action: "force_respond",
+            });
+        }
+    }
+    // ─── Hard: total tool call budget ────────────────────────
+    if (config.maxToolCallsPerTask > 0 && state.totalToolCalls >= config.maxToolCallsPerTask) {
+        signals.push({
+            type: "budget_tool_calls",
+            hard: true,
+            message: `Tool call budget exhausted (${state.totalToolCalls}/${config.maxToolCallsPerTask})`,
+            action: "force_respond",
+        });
+    }
+    // ─── Hard: consecutive tool failures ─────────────────────
+    if (config.maxConsecutiveFailures > 0 &&
+        state.consecutiveToolFailures >= config.maxConsecutiveFailures) {
+        signals.push({
+            type: "consecutive_failures",
+            hard: true,
+            message: `${state.consecutiveToolFailures} consecutive tool failures — aborting`,
+            action: "escalate",
+        });
+    }
+    // ─── Soft: confidence gate ────────────────────────────────
+    if (action === "use_tool" && confidence < config.confidenceThreshold) {
+        signals.push({
+            type: "confidence_low",
+            hard: false,
+            message: `Confidence ${confidence} below threshold ${config.confidenceThreshold}`,
+            action: "clarify",
+        });
+    }
+    return signals;
+}
+/** True if any signal in the list is a hard blocker */
+export function hasHardBlock(signals) {
+    return signals.some((s) => s.hard);
+}
+/** Returns the first hard signal's action, or undefined */
+export function hardAction(signals) {
+    return signals.find((s) => s.hard)?.action;
+}
+/** Merge user guard config with defaults */
+export function resolveGuards(config) {
+    return {
+        maxIterations: config?.maxIterations ?? DEFAULT_GUARDS.maxIterations,
+        costCapPerTask: config?.costCapPerTask ?? DEFAULT_GUARDS.costCapPerTask,
+        timeoutMs: config?.timeoutMs ?? DEFAULT_GUARDS.timeoutMs,
+        confidenceThreshold: config?.confidenceThreshold ?? DEFAULT_GUARDS.confidenceThreshold,
+        maxToolCallsPerTask: config?.maxToolCallsPerTask ?? DEFAULT_GUARDS.maxToolCallsPerTask,
+        maxConsecutiveFailures: config?.maxConsecutiveFailures ?? DEFAULT_GUARDS.maxConsecutiveFailures,
+    };
+}
+//# sourceMappingURL=guards.js.map

package/dist/core/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/core/guards.ts"],"names":[],"mappings":"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"}

package/dist/core/hooks.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Hooks — Observability callbacks for the execution loop.
+ *
+ * Wire to SSE channels, loggers, or dashboards.
+ * All hooks are optional and fire-and-forget (errors do not affect the loop).
+ */
+import type { AgentHooks, GuardSignal, ToolResult, RunState } from "./types.js";
+export declare function fireIteration(hooks: AgentHooks | undefined, state: RunState, maxIterations: number, currentSection?: string): void;
+export declare function fireSectionComplete(hooks: AgentHooks | undefined, sessionId: string, sectionName: string, sectionIndex: number, totalSections: number): void;
+export declare function fireToolCall(hooks: AgentHooks | undefined, sessionId: string, result: ToolResult, iteration: number, cached: boolean, durationMs: number): void;
+export declare function fireGuard(hooks: AgentHooks | undefined, sessionId: string, signal: GuardSignal, iteration: number): void;
+export declare function fireFatalError(hooks: AgentHooks | undefined, error: Error, sessionId: string): void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/core/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/core/hooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAWhF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,KAAK,EAAE,QAAQ,EACf,aAAa,EAAE,MAAM,EACrB,cAAc,CAAC,EAAE,MAAM,GACtB,IAAI,CAYN;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,IAAI,CAWN;AAED,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,MAAM,GACjB,IAAI,CAYN;AAED,wBAAgB,SAAS,CACvB,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,GAChB,IAAI,CAGN;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,GAChB,IAAI,CAGN"}

package/dist/core/hooks.js

@@ -0,0 +1,61 @@
+/**
+ * Hooks — Observability callbacks for the execution loop.
+ *
+ * Wire to SSE channels, loggers, or dashboards.
+ * All hooks are optional and fire-and-forget (errors do not affect the loop).
+ */
+/** Safely call a hook — never throw into the loop */
+function safely(fn) {
+    try {
+        fn();
+    }
+    catch {
+        // hook errors must not affect the agent loop
+    }
+}
+export function fireIteration(hooks, state, maxIterations, currentSection) {
+    if (!hooks?.onIteration)
+        return;
+    safely(() => hooks.onIteration({
+        sessionId: state.sessionId,
+        iteration: state.iteration,
+        maxIterations,
+        ...(currentSection !== undefined ? { currentSection } : {}),
+        totalCostUsd: state.totalCostUsd,
+        elapsedMs: Date.now() - state.startedAt,
+    }));
+}
+export function fireSectionComplete(hooks, sessionId, sectionName, sectionIndex, totalSections) {
+    if (!hooks?.onSectionComplete)
+        return;
+    safely(() => hooks.onSectionComplete({
+        sessionId,
+        sectionName,
+        sectionIndex,
+        totalSections,
+        completedAt: Date.now(),
+    }));
+}
+export function fireToolCall(hooks, sessionId, result, iteration, cached, durationMs) {
+    if (!hooks?.onToolCall)
+        return;
+    safely(() => hooks.onToolCall({
+        sessionId,
+        toolName: result.tool,
+        iteration,
+        cached,
+        durationMs,
+        status: result.status,
+    }));
+}
+export function fireGuard(hooks, sessionId, signal, iteration) {
+    if (!hooks?.onGuard)
+        return;
+    safely(() => hooks.onGuard({ sessionId, signal, iteration }));
+}
+export function fireFatalError(hooks, error, sessionId) {
+    if (!hooks?.onFatalError)
+        return;
+    safely(() => hooks.onFatalError(error, sessionId));
+}
+//# sourceMappingURL=hooks.js.map

package/dist/core/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/core/hooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,qDAAqD;AACrD,SAAS,MAAM,CAAC,EAAc;IAC5B,IAAI,CAAC;QACH,EAAE,EAAE,CAAC;IACP,CAAC;IAAC,MAAM,CAAC;QACP,6CAA6C;IAC/C,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,KAA6B,EAC7B,KAAe,EACf,aAAqB,EACrB,cAAuB;IAEvB,IAAI,CAAC,KAAK,EAAE,WAAW;QAAE,OAAO;IAChC,MAAM,CAAC,GAAG,EAAE,CACV,KAAK,CAAC,WAAY,CAAC;QACjB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,aAAa;QACb,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS;KACxC,CAAC,CACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,KAA6B,EAC7B,SAAiB,EACjB,WAAmB,EACnB,YAAoB,EACpB,aAAqB;IAErB,IAAI,CAAC,KAAK,EAAE,iBAAiB;QAAE,OAAO;IACtC,MAAM,CAAC,GAAG,EAAE,CACV,KAAK,CAAC,iBAAkB,CAAC;QACvB,SAAS;QACT,WAAW;QACX,YAAY;QACZ,aAAa;QACb,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;KACxB,CAAC,CACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,KAA6B,EAC7B,SAAiB,EACjB,MAAkB,EAClB,SAAiB,EACjB,MAAe,EACf,UAAkB;IAElB,IAAI,CAAC,KAAK,EAAE,UAAU;QAAE,OAAO;IAC/B,MAAM,CAAC,GAAG,EAAE,CACV,KAAK,CAAC,UAAW,CAAC;QAChB,SAAS;QACT,QAAQ,EAAE,MAAM,CAAC,IAAI;QACrB,SAAS;QACT,MAAM;QACN,UAAU;QACV,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC,CACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,KAA6B,EAC7B,SAAiB,EACjB,MAAmB,EACnB,SAAiB;IAEjB,IAAI,CAAC,KAAK,EAAE,OAAO;QAAE,OAAO;IAC5B,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,OAAQ,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,KAA6B,EAC7B,KAAY,EACZ,SAAiB;IAEjB,IAAI,CAAC,KAAK,EAAE,YAAY;QAAE,OAAO;IACjC,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,YAAa,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;AACtD,CAAC"}

package/dist/core/loop.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Execution Loop — The core of msm-mini.
+ *
+ * event → gates → lock → control bus → context build → brain call →
+ * guards → dispatch:
+ *   use_tool → validate/dedup/execute → record → loop
+ *   respond/clarify/escalate → deliver → done
+ *   budget exhausted → force_respond → done
+ */
+import type { AgentConfig } 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;
+//# sourceMappingURL=loop.d.ts.map

package/dist/core/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/core/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EACV,WAAW,EAQZ,MAAM,YAAY,CAAC;AA2BpB;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,YAAY,EAAE,KAAK,CAoS3E"}