@msm-core/mini 0.8.0 → 0.14.0

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.8.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"
   }