@msm-core/mini 0.9.0 → 0.14.0

package/dist/definition/skills.js

@@ -0,0 +1,119 @@
+/**
+ * Skills — reusable instruction packs an agent loads, "files all the way down."
+ *
+ * Drop markdown into a folder and each file becomes part of the agent's
+ * definition, so the model gains that know-how with no rebuild and no code
+ * change. Two shapes are read, and they are the shapes Claude-style skill packs
+ * already use:
+ *
+ *   skills/
+ *     summarizing/SKILL.md      ← a folder pack
+ *     tone-of-voice.md          ← a single-file skill
+ *
+ * `loadSkills(dir)` returns ONE markdown block (`## Skills`), or `""` when
+ * there is nothing to load. **Composition stays with the host**: this module
+ * reads files and concatenates them; appending the block to a definition is the
+ * caller's line of code. The loop is not involved and does not know skills
+ * exist — `parseDefinition` has always *stripped* a `## Skills` section as
+ * "owned by the app layer", and that stays true.
+ *
+ * ── Lifted from `nisus/runtime/skills/loader.ts`, hardened where it mattered ──
+ *
+ * The pattern was right, so it was carried over rather than reinvented. Three
+ * things changed, each for a failure mode, and each pinned by a guard in
+ * `tests/skills.test.ts` — including a differential test against a verbatim
+ * transcription of the original, so any divergence beyond these is a bug:
+ *
+ *   1. **The order is deterministic.** The original iterated `readdirSync`
+ *      directly, and that order is filesystem- and platform-dependent (APFS
+ *      hands back roughly hash order; ext4 differs again). Two machines with
+ *      the same two skills therefore built two different definitions — the same
+ *      agent with two fingerprints, which is the enemy of replay
+ *      (`@msm-core/replay` fingerprints `system_context`) and of any diff a
+ *      human tries to read. Entries are now sorted by code unit before they are
+ *      read. **Not** `localeCompare`: that depends on ICU data and the ambient
+ *      locale, which would reintroduce exactly the nondeterminism being
+ *      removed.
+ *
+ *   2. **Diagnostics go to an injected port, never to `console`.** Same reason
+ *      as `@msm-core/mcp`'s `McpLogPort`: a library that prints is a library you
+ *      cannot embed. Absent a port, the loader is silent.
+ *
+ *   3. **An empty skill file contributes nothing instead of a bare separator.**
+ *      The original pushed `readFileSync(...).trim()` unconditionally, so an
+ *      empty (or whitespace-only) `.md` injected `"\n\n---\n\n\n\n---\n\n"`
+ *      into the text the model reads — a horizontal rule with no section under
+ *      it, mid-definition. It is now skipped, with a warning naming the file,
+ *      because a file someone left empty is a mistake worth hearing about.
+ *
+ * What deliberately did NOT change: a folder without a `SKILL.md` is skipped in
+ * silence (it is a plain folder, not a failure); a non-`.md` file is ignored;
+ * an entry that throws is reported and its siblings still load; and a folder
+ * pack and a single-file skill sitting side by side are BOTH read — the folder
+ * from its `SKILL.md`, the file from itself. That last one is the precedence
+ * rule, and it is a rule rather than an accident because a guard says so.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+/** The pack marker inside a skill folder. */
+const PACK_FILE = "SKILL.md";
+/** The heading the block is published under. */
+const BLOCK_HEADING = "## Skills";
+/** What sits between two skills inside the block. */
+const SEPARATOR = "\n\n---\n\n";
+/**
+ * Code-unit order: total, locale-independent, and identical on every platform.
+ * `Array.prototype.sort()`'s default is also code-unit order, but it gets there
+ * by stringifying — spelling it out states the intent that the guard tests.
+ */
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Read every skill under `dir` and return them as one markdown block, or `""`
+ * when the directory is missing, is not a directory, or holds no skills.
+ *
+ * Never throws for a skill it cannot read: the failure is reported on `log` and
+ * the remaining skills still load. A definition missing one section is worth
+ * more than an agent that will not start.
+ */
+export function loadSkills(dir, log = {}) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return "";
+    // Sorted BEFORE anything is read: the order of this array is the order of the
+    // block, and the block is part of what the model is asked.
+    const entries = [...readdirSync(dir)].sort(byCodeUnit);
+    const parts = [];
+    for (const entry of entries) {
+        const path = join(dir, entry);
+        let text;
+        try {
+            const stat = statSync(path);
+            if (stat.isDirectory()) {
+                const pack = join(path, PACK_FILE);
+                if (!existsSync(pack))
+                    continue; // a plain folder, not a skill pack
+                text = readFileSync(pack, "utf-8").trim();
+            }
+            else if (extname(entry).toLowerCase() === ".md") {
+                text = readFileSync(path, "utf-8").trim();
+            }
+            else {
+                continue; // not a skill in either shape
+            }
+        }
+        catch (err) {
+            log.warn?.(`[skills] failed to load ${entry}: ${err.message}`);
+            continue; // one unreadable skill must not cost the others
+        }
+        if (text === "") {
+            log.warn?.(`[skills] skipped empty "${entry}"`);
+            continue;
+        }
+        parts.push(text);
+        log.info?.(`[skills] loaded "${entry}"`);
+    }
+    if (parts.length === 0)
+        return "";
+    return `${BLOCK_HEADING}\n\n${parts.join(SEPARATOR)}`;
+}

package/dist/index.d.ts

@@ -15,10 +15,14 @@ export { createAnthropicBrain } from "./brain/anthropic.js";
 export { createOllamaBrain } from "./brain/ollama.js";
 export { buildBrain } from "./brain/factory.js";
 export { parseDefinition } from "./definition/parser.js";
+export { loadSkills } from "./definition/skills.js";
+export type { SkillsLogPort } from "./definition/skills.js";
 export { createDelegateTool, DELEGATE_TOOL_NAME } from "./tools/delegate.js";
 export type { DelegateTool, DelegateToolOptions } from "./tools/delegate.js";
-export type { Agent, AgentConfig, AgentEvent, AgentContext, AgentDefinition, AgentHooks, BeforeToolHookResult, Brain, BrainChunk, BrainOrchestration, BrainPayload, BrainRunInput, BrainToolCall, ChunkInfo, CompactionDecision, CompactionPort, DocumentState, GateConfig, GuardConfig, GuardSignal, GuardSignalType, IterationInfo, LoopOutcome, MemoryEntry, Message, OutcomeType, OutputValidation, OutputValidator, RedisConfig, RunState, SectionInfo, SessionMetadata, SessionStore, TenantContext, Tool, ToolCallInfo, ToolDefinition, ToolMeta, ToolParameter, ToolResult, } from "./core/types.js";
+export type { Agent, AgentConfig, AgentEvent, AgentContext, AgentDefinition, AgentHooks, BeforeToolHookResult, Brain, BrainChunk, BrainOrchestration, BrainPayload, BrainRunInput, BrainToolCall, ChunkInfo, CompactionDecision, CompactionPort, ControlBusPort, DedupPort, DocumentState, GateConfig, GuardConfig, GuardSignal, GuardSignalType, IterationInfo, LockHandle, LoopOutcome, MemoryEntry, Message, OutcomeType, OutputValidation, OutputValidator, RedisConfig, ResetAwareChunkHook, ResetAwareChunkSink, RunLockPort, RunState, SectionInfo, SessionMetadata, SessionStore, TenantContext, Tool, ToolCallInfo, ToolDefinition, ToolMeta, ToolParameter, ToolResult, } from "./core/types.js";
 export type { ContextBudget } from "./core/context-builder.js";
+export { acceptResets, isResetAware, acceptChunkResets, isResetAwareHook, } from "./core/types.js";
+export { respondingModel } from "./core/types.js";
 export { resolveGuards, DEFAULT_GUARDS } from "./core/guards.js";
 export { scoreOutcome } from "./quality/scorer.js";
 export type { QualityScore, QualityFlag } from "./quality/scorer.js";

package/dist/index.js

@@ -18,8 +18,36 @@ export { createOllamaBrain } from "./brain/ollama.js";
 export { buildBrain } from "./brain/factory.js";
 // ── Definition parser ───────────────────────────────────────────────────────
 export { parseDefinition } from "./definition/parser.js";
+// ── Skills (م١) — instruction packs read from disk, composed by the host ─────
+//
+// `loadSkills(dir)` returns one `## Skills` markdown block; appending it to a
+// definition is the composition root's line of code, not the loop's.
+export { loadSkills } from "./definition/skills.js";
 // ── Delegation (ر٢) — one agent asks another, as an ordinary tool ───────────
 export { createDelegateTool, DELEGATE_TOOL_NAME } from "./tools/delegate.js";
+// ── Streaming: opting in to a reset (ص٢/٢ · ص٣/٢) ───────────────────────────
+//
+// Two doors onto the same opt-in, one per altitude.
+//
+//   • A consumer that drives a brain DIRECTLY wraps its chunk sink in
+//     `acceptResets` (ص٢/٢) and stops losing the tail of a retried answer.
+//   • A consumer that runs an AGENT wraps its `AgentHooks.onChunk` in
+//     `acceptChunkResets` (ص٣/٢), and the loop declares to the brain on its
+//     behalf; `ChunkInfo.reset` then arrives on the first chunk of a retried
+//     attempt. This is the door most people want — `onChunk` is where an SSE
+//     channel is actually wired.
+//
+// Without a wrapper nothing changes anywhere: no reset is produced, and the
+// object delivered to `onChunk` keeps the exact three keys it has always had.
+export { acceptResets, isResetAware, acceptChunkResets, isResetAwareHook, } from "./core/types.js";
+// ── Who answered (س٦/٤) ─────────────────────────────────────────────────────
+//
+// The reading the four bundled brains use to fill `BrainPayload.model` from
+// their provider's reply — exported so a custom brain fills it the same way
+// instead of inventing a second reading that drifts. Hand it whatever the
+// provider returned; it yields `{ model }` when the reply named one and `{}`
+// when it did not, ready to spread into the payload.
+export { respondingModel } from "./core/types.js";
 // ── Guard utilities ─────────────────────────────────────────────────────────
 export { resolveGuards, DEFAULT_GUARDS } from "./core/guards.js";
 // ── Quality scorer ──────────────────────────────────────────────────────────

package/dist/tools/dedup.d.ts

@@ -5,12 +5,33 @@
  * Stored in Redis as: {prefix}:session:{id}:tools:dedup hash field
  * TTL: 5 minutes (configurable)
  */
-import type { ToolResult } from "../core/types.js";
+import type { DedupPort, ToolResult } from "../core/types.js";
 type RedisLike = {
     hget(key: string, field: string): Promise<string | null>;
     hset(key: string, field: string, value: string): Promise<unknown>;
     expire(key: string, seconds: number): Promise<unknown>;
 };
+/**
+ * The bundled Redis-backed `DedupPort` — the three functions below, behind the
+ * port the executor now takes.
+ *
+ * It adds nothing: `check`/`store` are `checkDedup`/`storeDedup` with the key
+ * built by `toolDedupKey` from the prefix this was constructed with, which is
+ * precisely what the executor used to do inline with a raw client. The class
+ * exists so that the executor talks to ONE thing whether the dedup came from a
+ * config or from Redis, and so the Redis path keeps its exact key shape and TTL
+ * behaviour while doing so.
+ *
+ * The prefix is the tenant-scoped one when the loop builds this
+ * (`{prefix}:{companyId}:{agentType}`); an injected port scopes itself.
+ */
+export declare class RedisToolDedup implements DedupPort {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: RedisLike, prefix: string);
+    check(sessionId: string, hash: string): Promise<ToolResult | null>;
+    store(sessionId: string, hash: string, result: ToolResult, ttlSeconds: number): Promise<void>;
+}
 export declare function toolDedupKey(prefix: string, sessionId: string): string;
 export declare function checkDedup(redis: RedisLike, dedupKey: string, hash: string): Promise<ToolResult | null>;
 export declare function storeDedup(redis: RedisLike, dedupKey: string, hash: string, result: ToolResult, ttlSeconds: number): Promise<void>;

package/dist/tools/dedup.js

@@ -6,6 +6,34 @@
  * TTL: 5 minutes (configurable)
  */
 import { createHash } from "node:crypto";
+/**
+ * The bundled Redis-backed `DedupPort` — the three functions below, behind the
+ * port the executor now takes.
+ *
+ * It adds nothing: `check`/`store` are `checkDedup`/`storeDedup` with the key
+ * built by `toolDedupKey` from the prefix this was constructed with, which is
+ * precisely what the executor used to do inline with a raw client. The class
+ * exists so that the executor talks to ONE thing whether the dedup came from a
+ * config or from Redis, and so the Redis path keeps its exact key shape and TTL
+ * behaviour while doing so.
+ *
+ * The prefix is the tenant-scoped one when the loop builds this
+ * (`{prefix}:{companyId}:{agentType}`); an injected port scopes itself.
+ */
+export class RedisToolDedup {
+    redis;
+    prefix;
+    constructor(redis, prefix) {
+        this.redis = redis;
+        this.prefix = prefix;
+    }
+    async check(sessionId, hash) {
+        return checkDedup(this.redis, toolDedupKey(this.prefix, sessionId), hash);
+    }
+    async store(sessionId, hash, result, ttlSeconds) {
+        await storeDedup(this.redis, toolDedupKey(this.prefix, sessionId), hash, result, ttlSeconds);
+    }
+}
 export function toolDedupKey(prefix, sessionId) {
     return `${prefix}:session:${sessionId}:tools:dedup`;
 }

package/dist/tools/executor.d.ts

@@ -10,26 +10,70 @@
  *   4. Execute — call tool.execute()
  *   5. Cache — store result in dedup hash
  */
-import type { Tool, ToolResult, ToolMeta, AgentHooks } from "../core/types.js";
+import type { Tool, ToolResult, ToolMeta, AgentHooks, DedupPort } from "../core/types.js";
 type RedisLike = {
     hget(key: string, field: string): Promise<string | null>;
     hset(key: string, field: string, value: string): Promise<unknown>;
     expire(key: string, seconds: number): Promise<unknown>;
     get(key: string): Promise<string | null>;
 };
-export interface ExecutorOptions {
+/**
+ * Where step 3's cache lives — a port, or a Redis client to build one from.
+ *
+ * A union rather than "a port and an optional client", so the compiler still
+ * insists on exactly one answer. The second arm is the call this function has
+ * always taken (`{ redis, redisPrefix, … }`) and it keeps working character for
+ * character; the loop passes the first, because since س٦ it resolves the dedup
+ * port itself — injected or Redis-backed — and hands one thing down.
+ */
+type DedupSource = {
+    dedup: DedupPort;
+    redis?: never;
+    redisPrefix?: never;
+} | {
+    dedup?: never;
     redis: RedisLike;
     redisPrefix: string;
+};
+export type ExecutorOptions = DedupSource & {
     dedupTtlSeconds: number;
     /** Optional hooks — only onBeforeTool is used at this layer */
     hooks?: Pick<AgentHooks, "onBeforeTool">;
-}
+};
 export interface ExecutionResult {
     result: ToolResult;
     cached: boolean;
     durationMs: number;
 }
 export declare function executeTool(tool: Tool, params: Record<string, unknown>, meta: ToolMeta, opts: ExecutorOptions): Promise<ExecutionResult>;
-/** Build a ToolDefinition list from app-provided Tool objects (for brain prompt) */
-export declare function toToolDefinitions(tools: Tool[]): import("../core/types.js").ToolDefinition[];
+/**
+ * Build a ToolDefinition list from app-provided Tool objects (for brain prompt).
+ *
+ * **The stamp travels (ر١/١).** `ToolDefinition` has declared `destructive` and
+ * `category` since before MCP existed and nothing ever filled them: a tool an
+ * operator stamped `destructive` at the composition root reached the model
+ * looking exactly like a read-only one. This was never a safety hole — the
+ * executor enforces `requiresApproval` above regardless of what the model was
+ * told — but a model that is never shown which of its tools change the world
+ * cannot be asked to be careful with them, and the two fields existed on the
+ * type precisely so that it could be.
+ *
+ * **Why the parameter widens instead of the body casting.** Mini's `Tool` does
+ * not declare the two fields; `McpTool` (ر١) and `DelegateTool` (ر٢) each add
+ * them to a plain `Tool`, and both reach here through `AgentConfig.tools:
+ * Tool[]` — on the object, off the type. Saying so in the signature keeps it
+ * honest: a plain `Tool[]` still satisfies it (both fields are optional), a
+ * stamped array is read with no `as` anywhere, and a caller who writes
+ * `destructive: "yes"` is told by the compiler instead of dropped in silence.
+ *
+ * **Absent stays absent.** The conditional spreads are not style: under
+ * `exactOptionalPropertyTypes` an unstamped tool must produce the object it
+ * produced yesterday, key for key. That is what keeps an unstamped run's
+ * `@msm-core/replay` fingerprint unmoved — only a tool that actually carries a
+ * stamp changes what the model is asked, and only its fingerprint moves.
+ */
+export declare function toToolDefinitions(tools: ReadonlyArray<Tool & {
+    destructive?: boolean;
+    category?: string;
+}>): import("../core/types.js").ToolDefinition[];
 export {};

package/dist/tools/executor.js

@@ -10,7 +10,7 @@
  *   4. Execute — call tool.execute()
  *   5. Cache — store result in dedup hash
  */
-import { hashToolCall, checkDedup, storeDedup, toolDedupKey } from "./dedup.js";
+import { hashToolCall, RedisToolDedup } from "./dedup.js";
 export async function executeTool(tool, params, meta, opts) {
     const start = Date.now();
     // Step 1: Validate required parameters
@@ -95,9 +95,15 @@ export async function executeTool(tool, params, meta, opts) {
     }
     // Step 3: Dedup check (keyed on the EFFECTIVE params, so edited-approval runs
     // are not served a cached result for the original params).
+    //
+    // The hash stays here and stays pure — it is not I/O and there is nothing to
+    // swap about it, so every implementation of the port dedups on exactly the
+    // same key the Redis one always did.
+    const dedup = opts.dedup
+        ? opts.dedup
+        : new RedisToolDedup(opts.redis, opts.redisPrefix);
     const hash = hashToolCall(tool.name, effectiveParams);
-    const dedupKey = toolDedupKey(opts.redisPrefix, meta.sessionId);
-    const cached = await checkDedup(opts.redis, dedupKey, hash);
+    const cached = await dedup.check(meta.sessionId, hash);
     if (cached) {
         return { result: cached, cached: true, durationMs: Date.now() - start };
     }
@@ -115,7 +121,7 @@ export async function executeTool(tool, params, meta, opts) {
     }
     // Step 5: Cache successful results only
     if (result.status === "ok") {
-        await storeDedup(opts.redis, dedupKey, hash, result, opts.dedupTtlSeconds);
+        await dedup.store(meta.sessionId, hash, result, opts.dedupTtlSeconds);
     }
     return { result, cached: false, durationMs: Date.now() - start };
 }
@@ -135,7 +141,32 @@ function validateParams(tool, params) {
     }
     return null;
 }
-/** Build a ToolDefinition list from app-provided Tool objects (for brain prompt) */
+/**
+ * Build a ToolDefinition list from app-provided Tool objects (for brain prompt).
+ *
+ * **The stamp travels (ر١/١).** `ToolDefinition` has declared `destructive` and
+ * `category` since before MCP existed and nothing ever filled them: a tool an
+ * operator stamped `destructive` at the composition root reached the model
+ * looking exactly like a read-only one. This was never a safety hole — the
+ * executor enforces `requiresApproval` above regardless of what the model was
+ * told — but a model that is never shown which of its tools change the world
+ * cannot be asked to be careful with them, and the two fields existed on the
+ * type precisely so that it could be.
+ *
+ * **Why the parameter widens instead of the body casting.** Mini's `Tool` does
+ * not declare the two fields; `McpTool` (ر١) and `DelegateTool` (ر٢) each add
+ * them to a plain `Tool`, and both reach here through `AgentConfig.tools:
+ * Tool[]` — on the object, off the type. Saying so in the signature keeps it
+ * honest: a plain `Tool[]` still satisfies it (both fields are optional), a
+ * stamped array is read with no `as` anywhere, and a caller who writes
+ * `destructive: "yes"` is told by the compiler instead of dropped in silence.
+ *
+ * **Absent stays absent.** The conditional spreads are not style: under
+ * `exactOptionalPropertyTypes` an unstamped tool must produce the object it
+ * produced yesterday, key for key. That is what keeps an unstamped run's
+ * `@msm-core/replay` fingerprint unmoved — only a tool that actually carries a
+ * stamp changes what the model is asked, and only its fingerprint moves.
+ */
 export function toToolDefinitions(tools) {
     return tools.map((t) => ({
         name: t.name,
@@ -144,5 +175,7 @@ export function toToolDefinitions(tools) {
         ...(t.requiresApproval !== undefined
             ? { requiresApproval: t.requiresApproval }
             : {}),
+        ...(t.destructive !== undefined ? { destructive: t.destructive } : {}),
+        ...(t.category !== undefined ? { category: t.category } : {}),
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msm-core/mini",
-  "version": "0.9.0",
+  "version": "0.14.0",
   "description": "Portable AI agent execution loop — brain-agnostic, zero embedded databases",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "ioredis": "^5.3.2",
-    "@msm-core/session": "^0.2.0"
+    "@msm-core/session": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -68,7 +68,8 @@
   "license": "UNLICENSED",
   "scripts": {
     "build": "tsc",
-    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "tsc -p tsconfig.test.json && vitest run",
     "test:watch": "vitest",
     "clean": "rm -rf dist"
   }