@moxxy/sdk 0.1.2 → 0.1.3

package/src/fs-utils.ts

@@ -0,0 +1,55 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export interface WriteFileAtomicOptions {
+  /** Mode for the final file, e.g. `0o600` for secrets. Enforced past umask. */
+  readonly mode?: number;
+  /** Encoding when `data` is a string. Defaults to `'utf8'`. Ignored for bytes. */
+  readonly encoding?: BufferEncoding;
+}
+
+/**
+ * Crash-atomic file write: write a unique sibling temp file, then `rename` it
+ * over the target. POSIX `rename` is atomic on the same filesystem, so a crash
+ * (or full disk) mid-write leaves the previous file intact rather than a
+ * truncated one. The temp name carries pid + a random UUID so concurrent
+ * writers to the same target never collide on the temp path.
+ *
+ * This is the single home for the framework's "persist atomically" invariant —
+ * every file-state writer (vault, memory, permissions, sessions, the Write/Edit
+ * tools) should call this instead of hand-rolling tmp+rename or writing in place.
+ */
+export async function writeFileAtomic(
+  target: string,
+  data: string | Uint8Array,
+  opts: WriteFileAtomicOptions = {},
+): Promise<void> {
+  await mkdir(dirname(target), { recursive: true });
+  const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, data, { encoding: opts.encoding ?? 'utf8' });
+    // chmod explicitly: writeFile's mode option is masked by umask, but a
+    // 0o600 secret file must be exactly 0o600 regardless of the host umask.
+    if (opts.mode != null) await chmod(tmp, opts.mode);
+    await rename(tmp, target);
+  } catch (err) {
+    await rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * The moxxy home directory: `$MOXXY_HOME` when set, else `~/.moxxy`. Single
+ * source of truth so the env override is honored uniformly — previously half
+ * the plugins inlined `~/.moxxy` and ignored `MOXXY_HOME`.
+ */
+export function moxxyHome(): string {
+  return process.env.MOXXY_HOME ?? join(homedir(), '.moxxy');
+}
+
+/** Join path segments under {@link moxxyHome}. */
+export function moxxyPath(...segments: string[]): string {
+  return join(moxxyHome(), ...segments);
+}

package/src/http-utils.test.ts

@@ -0,0 +1,36 @@
+import type { IncomingMessage } from 'node:http';
+import { Readable } from 'node:stream';
+import { describe, expect, it } from 'vitest';
+import { bearerTokenMatches, readRequestBody } from './http-utils.js';
+
+function fakeReq(body: string | Buffer): IncomingMessage {
+  return Readable.from([Buffer.from(body)]) as unknown as IncomingMessage;
+}
+
+describe('bearerTokenMatches', () => {
+  it('matches an identical token', () => {
+    expect(bearerTokenMatches('s3cret', 's3cret')).toBe(true);
+  });
+  it('rejects a different token of equal length', () => {
+    expect(bearerTokenMatches('aaaaaa', 'bbbbbb')).toBe(false);
+  });
+  it('rejects a length mismatch without throwing', () => {
+    expect(bearerTokenMatches('short', 'longer-token')).toBe(false);
+  });
+  it('rejects empty/missing presented tokens', () => {
+    expect(bearerTokenMatches(undefined, 'x')).toBe(false);
+    expect(bearerTokenMatches(null, 'x')).toBe(false);
+    expect(bearerTokenMatches('', 'x')).toBe(false);
+  });
+});
+
+describe('readRequestBody', () => {
+  it('reads the full body', async () => {
+    const buf = await readRequestBody(fakeReq('hello world'), 1024);
+    expect(buf.toString('utf8')).toBe('hello world');
+  });
+
+  it('rejects when the body exceeds maxBytes', async () => {
+    await expect(readRequestBody(fakeReq('x'.repeat(100)), 10)).rejects.toThrow(/exceeds 10 bytes/);
+  });
+});

package/src/http-utils.ts

@@ -0,0 +1,40 @@
+import { timingSafeEqual } from 'node:crypto';
+import type { IncomingMessage } from 'node:http';
+
+/**
+ * Read a request body into a Buffer, rejecting (and destroying the socket) once
+ * `maxBytes` is exceeded. Bounds in-memory buffering so a malicious or runaway
+ * client can't exhaust the host's memory. Shared by every HTTP channel/listener.
+ */
+export async function readRequestBody(req: IncomingMessage, maxBytes: number): Promise<Buffer> {
+  return new Promise<Buffer>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > maxBytes) {
+        reject(new Error(`request body exceeds ${maxBytes} bytes`));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Constant-time comparison of a presented bearer token against the expected
+ * value. A length mismatch returns false WITHOUT calling `timingSafeEqual`
+ * (which throws on unequal lengths and would leak the length); equal-length
+ * inputs are compared in constant time so an attacker can't recover the token
+ * byte-by-byte via response timing.
+ */
+export function bearerTokenMatches(presented: string | undefined | null, expected: string): boolean {
+  if (!presented) return false;
+  const a = Buffer.from(presented);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}

package/src/index.ts

@@ -47,6 +47,12 @@ export type {
   ToolInfo,
   SkillInfo,
   CommandInfo,
+  CredentialResolver,
+  McpAdminView,
+  McpServerStatusView,
+  WorkflowsView,
+  WorkflowSummaryView,
+  WorkflowRunView,
 } from './session-like.js';
 
 export type {
@@ -135,7 +141,22 @@ export type {
 } from './view-renderer.js';
 export { VIEW_PRIMITIVES, VIEW_COMPONENTS, DEFAULT_VIEW_TAGS } from './view-renderer.js';
 export type { TunnelProviderDef, TunnelHandle, TunnelOpenOptions } from './tunnel.js';
-export { isRetryableError, toFriendlyError, zodToJsonSchema, type StopReason } from './provider-utils.js';
+export { isRetryableError, toFriendlyError, zodToJsonSchema, estimateTextTokens, type StopReason } from './provider-utils.js';
+export { writeFileAtomic, moxxyHome, moxxyPath, type WriteFileAtomicOptions } from './fs-utils.js';
+export { createMutex, type Mutex } from './mutex.js';
+export { readRequestBody, bearerTokenMatches } from './http-utils.js';
+export {
+  autoAllowResolver,
+  denyByDefaultResolver,
+  createCallbackResolver,
+  createAllowListResolver,
+  createDeferredPermissionResolver,
+  evaluateToolRule,
+  type CallbackResolverOptions,
+  type PermissionPromptHandler,
+  type DeferredPermissionResolver,
+  type DeferredPermissionResolverOptions,
+} from './resolvers.js';
 export {
   MoxxyError,
   classifyHttpStatus,
@@ -145,18 +166,27 @@ export {
 } from './errors.js';
 export {
   collectProviderStream,
+  runSingleShotTurn,
   projectMessagesFromLog,
   projectMessages,
   buildSystemPromptWithSkills,
+  createStuckLoopDetector,
+  stableHash,
   type CollectedToolUse,
   type StreamResult,
   type ProjectMessagesOptions,
   type ProjectedMessages,
+  type StuckLoopDetector,
+  type StuckSignal,
 } from './mode-helpers.js';
 export { dispatchToolCall } from './tool-dispatch.js';
 
 export type { TokenBudget, CompactContext, CompactorDef } from './compactor.js';
-export { estimateContextTokens, runCompactionIfNeeded } from './compactor-helpers.js';
+export {
+  estimateContextTokens,
+  runCompactionIfNeeded,
+  isContextOverflowError,
+} from './compactor-helpers.js';
 export {
   runElisionIfNeeded,
   resolveElisionSettings,
@@ -192,6 +222,23 @@ export {
 
 export type { Skill, SkillDef, SkillFrontmatter, SkillScope, SkillSchedule } from './skill.js';
 
+export type {
+  Workflow,
+  WorkflowStep,
+  WorkflowTrigger,
+  WorkflowStepErrorMode,
+  WorkflowInputSpec,
+  WorkflowDelivery,
+  WorkflowToolRunner,
+  WorkflowLookup,
+  WorkflowEventSubtype,
+  WorkflowRunDeps,
+  WorkflowStepStatus,
+  WorkflowStepResult,
+  WorkflowRunResult,
+  WorkflowExecutorDef,
+} from './workflow.js';
+
 export type { AgentDef } from './agent.js';
 
 export type {
@@ -245,7 +292,7 @@ export type {
   ChannelSubcommandContext,
   ChannelCommandArgs,
 } from './channel.js';
-export type { EmbeddingProvider } from './embedding.js';
+export type { EmbeddingProvider, EmbedderDef } from './embedding.js';
 export { CachedEmbeddingProvider } from './embedding-cache.js';
 
 export type {
@@ -281,8 +328,10 @@ export {
   definePermission,
   defineSkill,
   defineTranscriber,
+  defineEmbedder,
   defineCommand,
   defineAgent,
+  defineWorkflowExecutor,
 } from './define.js';
 
 export {
@@ -301,4 +350,10 @@ export {
   type InstallTarget,
 } from './install-hints.js';
 
+export {
+  checkTranscriberReady,
+  pickFirstAvailableTranscriber,
+  resolveTranscriber,
+} from './voice.js';
+
 export { z } from 'zod';

package/src/mode-helpers.ts

@@ -12,6 +12,9 @@ import {
   toolResultStubbed,
 } from './elision-state.js';
 import { applyLazyTools } from './tool-gating.js';
+import { runCompactionIfNeeded } from './compactor-helpers.js';
+import { runElisionIfNeeded } from './elision-helpers.js';
+import { usageEventFields } from './token-accounting.js';
 
 /**
  * Shared bits used by every loop strategy: a typed tool-use struct and a
@@ -481,3 +484,169 @@ export async function collectProviderStream(
   }
   return { text, toolUses: finalToolUses, stopReason, error, ...(usage ? { usage } : {}) };
 }
+
+/**
+ * Run a single-shot (no-tools) provider turn — the shape every planner /
+ * synthesis phase shares. Runs context management (compaction + elision),
+ * emits the `provider_request` bookend, streams the response with tools
+ * disabled, then emits either an `error` event (returning `null`) or the
+ * `provider_response` bookend (returning the collected text).
+ *
+ * Replaces the ~40-line block each mode phase used to inline; centralizing it
+ * keeps event emission uniform and means a fix here (e.g. always running
+ * elision) lands for every loop strategy at once.
+ */
+export async function runSingleShotTurn(
+  ctx: ModeContext,
+  messages: ReadonlyArray<ProviderMessage>,
+  opts: { maxTokens?: number } = {},
+): Promise<string | null> {
+  await runCompactionIfNeeded(ctx);
+  await runElisionIfNeeded(ctx);
+
+  await ctx.emit({
+    type: 'provider_request',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    provider: ctx.provider.name,
+    model: ctx.model,
+  });
+
+  const { text, usage, error } = await collectProviderStream(ctx, messages, {
+    includeTools: false,
+    ...(opts.maxTokens !== undefined ? { maxTokens: opts.maxTokens } : {}),
+  });
+  if (error) {
+    await ctx.emit({
+      type: 'error',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      kind: error.retryable ? 'retryable' : 'fatal',
+      message: error.message,
+    });
+    return null;
+  }
+
+  await ctx.emit({
+    type: 'provider_response',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    provider: ctx.provider.name,
+    model: ctx.model,
+    ...usageEventFields(usage),
+  });
+
+  return text;
+}
+
+/**
+ * Sliding-window detector for "model keeps making the same tool call".
+ *
+ * When the same `(toolName, input)` pair appears `repeatThreshold` times in
+ * the last `windowSize` calls, the model is almost certainly stuck — polling a
+ * tool that returns the same thing, mis-handling an error, etc. Bail early
+ * instead of burning through the iteration cap.
+ *
+ * Shared across every loop strategy so detection is uniform — previously each
+ * mode re-rolled this, and one copy used a non-canonical `JSON.stringify`
+ * signature that silently missed key-reordered repeats.
+ */
+export interface StuckSignal {
+  /** True when the loop guard should trip. */
+  readonly stuck: boolean;
+  /** Repeat count behind the trip — for the error message. */
+  readonly count: number;
+  /**
+   * `exact` = the same (tool, full-input) repeated `repeatThreshold` times.
+   * `near`  = the same (tool, identity arg — url / file_path / command / …)
+   *           repeated `nearThreshold` times while only volatile args (maxBytes,
+   *           timeoutMs) varied. Catches the "refetch the same URL with a bigger
+   *           maxBytes over and over" loop the exact check sails past.
+   */
+  readonly kind: 'exact' | 'near';
+}
+
+export interface StuckLoopDetector {
+  readonly windowSize: number;
+  readonly repeatThreshold: number;
+  /** Record the call and report whether the loop guard should trip. */
+  record(toolName: string, input: unknown): StuckSignal;
+}
+
+/** Identity arguments that pin "the same target" across volatile-arg variation,
+ *  best-first. The first present string field wins. */
+const IDENTITY_ARG_KEYS = ['url', 'file_path', 'path', 'command', 'cmd', 'query', 'pattern'];
+
+function identityArg(input: unknown): string | null {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const o = input as Record<string, unknown>;
+  for (const k of IDENTITY_ARG_KEYS) {
+    const v = o[k];
+    if (typeof v === 'string' && v.trim().length > 0) return `${k}=${v}`;
+  }
+  return null;
+}
+
+export function createStuckLoopDetector(
+  opts: {
+    windowSize?: number;
+    repeatThreshold?: number;
+    nearWindowSize?: number;
+    nearThreshold?: number;
+  } = {},
+): StuckLoopDetector {
+  const windowSize = opts.windowSize ?? 8;
+  const repeatThreshold = opts.repeatThreshold ?? 3;
+  // Near-dups need a higher count + a wider window (they're spread out across a
+  // burst of other calls), and tolerate a couple of legit "bigger refetch" tries.
+  const nearWindowSize = opts.nearWindowSize ?? Math.max(windowSize * 2, 16);
+  const nearThreshold = opts.nearThreshold ?? Math.max(repeatThreshold + 2, 5);
+  const recent: string[] = [];
+  const recentNear: string[] = [];
+  return {
+    windowSize,
+    repeatThreshold,
+    record(toolName, input): StuckSignal {
+      const key = `${toolName}|${stableHash(input)}`;
+      recent.push(key);
+      if (recent.length > windowSize) recent.shift();
+      const exactCount = recent.filter((k) => k === key).length;
+      if (exactCount >= repeatThreshold) return { stuck: true, count: exactCount, kind: 'exact' };
+
+      let nearCount = 0;
+      const id = identityArg(input);
+      if (id !== null) {
+        const nearKey = `${toolName}|${id}`;
+        recentNear.push(nearKey);
+        if (recentNear.length > nearWindowSize) recentNear.shift();
+        nearCount = recentNear.filter((k) => k === nearKey).length;
+        if (nearCount >= nearThreshold) return { stuck: true, count: nearCount, kind: 'near' };
+      }
+      return { stuck: false, count: Math.max(exactCount, nearCount), kind: 'exact' };
+    },
+  };
+}
+
+/**
+ * Stable, key-order-canonical hash of a tool call's input, so `{a:1,b:2}` and
+ * `{b:2,a:1}` produce the same key. Use for any "have I seen this call before"
+ * comparison — a raw `JSON.stringify` is NOT order-stable.
+ */
+export function stableHash(input: unknown): string {
+  return canonicalize(input);
+}
+
+function canonicalize(value: unknown): string {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalize).join(',') + ']';
+  }
+  const entries = Object.entries(value as Record<string, unknown>).sort(
+    ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0),
+  );
+  return '{' + entries.map(([k, v]) => JSON.stringify(k) + ':' + canonicalize(v)).join(',') + '}';
+}

package/src/mode.ts

@@ -88,6 +88,14 @@ export interface ModeContext {
    * Absent in synthetic test contexts that don't model a full Session.
    */
   readonly subagents?: SubagentSpawner;
+  /**
+   * Request the session switch its active mode AFTER this turn fully drains.
+   * Used by terminal workflow modes (BMAD finishing its last phase) to hand
+   * control back to a normal mode so the next message isn't trapped in the
+   * workflow. The switch is applied post-turn by the runner; an unknown /
+   * unregistered mode name is ignored. Absent in synthetic test contexts.
+   */
+  readonly requestModeSwitch?: (modeName: string) => void;
   emit(event: EmittedEvent): Promise<MoxxyEvent>;
 }
 

package/src/mutex.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { createMutex } from './mutex.js';
+
+const tick = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe('createMutex', () => {
+  it('serializes overlapping runs (no interleave)', async () => {
+    const mutex = createMutex();
+    const order: string[] = [];
+    const slow = mutex.run(async () => {
+      order.push('a:start');
+      await tick(20);
+      order.push('a:end');
+    });
+    const fast = mutex.run(async () => {
+      order.push('b:start');
+      await tick(1);
+      order.push('b:end');
+    });
+    await Promise.all([slow, fast]);
+    expect(order).toEqual(['a:start', 'a:end', 'b:start', 'b:end']);
+  });
+
+  it('returns the callback result', async () => {
+    const mutex = createMutex();
+    await expect(mutex.run(() => 42)).resolves.toBe(42);
+    await expect(mutex.run(async () => 'x')).resolves.toBe('x');
+  });
+
+  it('keeps the lock alive after a rejection', async () => {
+    const mutex = createMutex();
+    await expect(mutex.run(() => Promise.reject(new Error('boom')))).rejects.toThrow('boom');
+    // Next run must still execute — the chain isn't poisoned.
+    await expect(mutex.run(() => 'recovered')).resolves.toBe('recovered');
+  });
+});

package/src/mutex.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-instance write mutex: a promise chain that serializes async mutators so
+ * two overlapping read-modify-write cycles can't both read the same snapshot
+ * and clobber each other.
+ *
+ * The single home for the framework's "serialize file-state mutators"
+ * invariant. Stores (vault, memory, permissions, scheduler, webhooks, …) hold
+ * one `Mutex` instance and run every mutation through {@link Mutex.run}.
+ */
+export interface Mutex {
+  /** Run `fn` after all previously-queued runs settle. */
+  run<T>(fn: () => Promise<T> | T): Promise<T>;
+}
+
+export function createMutex(): Mutex {
+  let chain: Promise<unknown> = Promise.resolve();
+  return {
+    run<T>(fn: () => Promise<T> | T): Promise<T> {
+      // `.then(fn, fn)` runs `fn` whether the previous run resolved or
+      // rejected, so one failed mutation doesn't deadlock the queue.
+      const next = chain.then(fn as () => T, fn as () => T);
+      // Keep the chain alive across rejections — never let a rejected link
+      // permanently poison the lock.
+      chain = next.then(
+        () => undefined,
+        () => undefined,
+      );
+      return next;
+    },
+  };
+}

package/src/plugin.ts

@@ -3,6 +3,8 @@ import type { CacheStrategyDef } from './cache-strategy.js';
 import type { ChannelDef } from './channel.js';
 import type { CommandDef } from './command.js';
 import type { CompactorDef } from './compactor.js';
+import type { EmbedderDef } from './embedding.js';
+import type { Isolator } from './isolation.js';
 import type { LifecycleHooks } from './hooks.js';
 import type { ModeDef } from './mode.js';
 import type { ProviderDef } from './provider.js';
@@ -11,8 +13,9 @@ import type { ToolDef } from './tool.js';
 import type { TranscriberDef } from './transcriber.js';
 import type { ViewRendererDef } from './view-renderer.js';
 import type { TunnelProviderDef } from './tunnel.js';
+import type { WorkflowExecutorDef } from './workflow.js';
 
-export type PluginKind = 'tools' | 'provider' | 'mode' | 'compactor' | 'cache-strategy' | 'view-renderer' | 'tunnel-provider' | 'mcp' | 'cli' | 'channel' | 'hooks' | 'agent' | 'command' | 'transcriber';
+export type PluginKind = 'tools' | 'provider' | 'mode' | 'compactor' | 'cache-strategy' | 'view-renderer' | 'tunnel-provider' | 'mcp' | 'cli' | 'channel' | 'hooks' | 'agent' | 'command' | 'transcriber' | 'embedder' | 'isolator' | 'workflow-executor';
 
 export interface PluginSpec {
   readonly name: string;
@@ -47,6 +50,22 @@ export interface PluginSpec {
    * the active provider does not advertise `supportsAudio`.
    */
   readonly transcribers?: ReadonlyArray<TranscriberDef>;
+  /**
+   * Text-embedding backends contributed by the plugin. Selected by name via
+   * `session.embedders.setActive(name, config)`; @moxxy/plugin-memory uses the
+   * active embedder for semantic recall. `createClient` is lazy so a discovered
+   * embedder plugin never pulls its (often heavy) runtime in until selected.
+   */
+  readonly embedders?: ReadonlyArray<EmbedderDef>;
+  /**
+   * Capability isolators contributed by the plugin (worker_threads, subprocess,
+   * wasm, …). Registered into the active security layer's `IsolatorRegistry`
+   * and selected by name via `security.isolator` config. Registration alone is
+   * inert — a contributed isolator is NEVER auto-activated as the sandbox
+   * boundary; the user must opt in by name (so a rogue plugin can't silently
+   * weaken isolation).
+   */
+  readonly isolators?: ReadonlyArray<Isolator>;
   /**
    * Typed subagent kinds the plugin contributes. Each becomes
    * dispatchable as `dispatch_agent({ agentType: <name>, ... })`.
@@ -64,6 +83,13 @@ export interface PluginSpec {
    * pickers, raw-mode toggles) inside the channel itself.
    */
   readonly commands?: ReadonlyArray<CommandDef>;
+  /**
+   * Workflow-execution strategies contributed by the plugin. One is active per
+   * session (selected via `session.workflowExecutors.setActive(name)`); the
+   * active executor runs a workflow DAG. `@moxxy/plugin-workflows` ships the
+   * default `dag` executor.
+   */
+  readonly workflowExecutors?: ReadonlyArray<WorkflowExecutorDef>;
   readonly hooks?: LifecycleHooks;
   readonly skillsDir?: string;
 }

package/src/provider-utils.ts

@@ -8,6 +8,15 @@ import { classifyNetworkError } from './errors.js';
 /** Canonical stop reasons emitted on `message_end` events. */
 export type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'error';
 
+/**
+ * Rough token estimate for a blob of text: ~4 chars per token. The shared
+ * fallback for a provider's `countTokens` when no native tokenizer is wired —
+ * previously each provider hardcoded `Math.ceil(text.length / 4)` independently.
+ */
+export function estimateTextTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
 /**
  * Heuristic: should a provider request retry on this error? Used by stream
  * modes to attach a `retryable: boolean` flag to the `error` event so callers

package/src/resolvers.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { evaluateToolRule } from './resolvers.js';
+import type { PendingToolCall, PermissionRule } from './permission.js';
+
+function call(name: string, input: unknown = {}): PendingToolCall {
+  return { callId: 'c1', name, input } as unknown as PendingToolCall;
+}
+
+describe('evaluateToolRule', () => {
+  it('returns null when the tool declares no rule (defer to resolver)', () => {
+    expect(evaluateToolRule(undefined, call('reload_skills'))).toBeNull();
+  });
+
+  it('allows a tool that declares action allow', () => {
+    const rule: PermissionRule = { action: 'allow' };
+    expect(evaluateToolRule(rule, call('reload_skills'))).toEqual({
+      mode: 'allow',
+      reason: 'tool-declared allow',
+    });
+  });
+
+  it('denies a tool that declares action deny', () => {
+    const rule: PermissionRule = { action: 'deny', reason: 'nope' };
+    expect(evaluateToolRule(rule, call('danger'))).toEqual({ mode: 'deny', reason: 'nope' });
+  });
+
+  it('defers (null) for action prompt so the interactive resolver decides', () => {
+    expect(evaluateToolRule({ action: 'prompt' }, call('self_update_verify'))).toBeNull();
+  });
+
+  it('only applies when the name pattern matches', () => {
+    const rule: PermissionRule = { action: 'allow', pattern: { name: 'reload_skills' } };
+    expect(evaluateToolRule(rule, call('reload_skills'))).not.toBeNull();
+    expect(evaluateToolRule(rule, call('other_tool'))).toBeNull();
+  });
+
+  it('matches on inputMatches (string + RegExp)', () => {
+    const rule: PermissionRule = {
+      action: 'allow',
+      pattern: { inputMatches: { path: /^\/tmp\// } },
+    };
+    expect(evaluateToolRule(rule, call('write', { path: '/tmp/ok.txt' }))).not.toBeNull();
+    expect(evaluateToolRule(rule, call('write', { path: '/etc/passwd' }))).toBeNull();
+  });
+});