@moxxy/sdk 0.15.0 → 0.15.2

package/src/mode/abort-backoff.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from 'vitest';
+import { nextBackoffMs, sleepWithAbort } from './abort-backoff.js';
+
+describe('nextBackoffMs', () => {
+  it('grows exponentially from baseMs (1-based attempt)', () => {
+    expect(nextBackoffMs(1, 500)).toBe(500);
+    expect(nextBackoffMs(2, 500)).toBe(1000);
+    expect(nextBackoffMs(3, 500)).toBe(2000);
+    expect(nextBackoffMs(4, 500)).toBe(4000);
+  });
+
+  it('treats attempt <= 1 as baseMs', () => {
+    expect(nextBackoffMs(0, 500)).toBe(500);
+    expect(nextBackoffMs(-3, 500)).toBe(500);
+  });
+
+  it('caps at maxMs (default 30_000)', () => {
+    expect(nextBackoffMs(20, 500)).toBe(30_000);
+    expect(nextBackoffMs(20, 500, 5_000)).toBe(5_000);
+  });
+});
+
+describe('sleepWithAbort', () => {
+  it('resolves after the delay', async () => {
+    vi.useFakeTimers();
+    try {
+      const p = sleepWithAbort(1000);
+      vi.advanceTimersByTime(1000);
+      await expect(p).resolves.toBeUndefined();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('rejects immediately when the signal is already aborted', async () => {
+    const ac = new AbortController();
+    ac.abort();
+    await expect(sleepWithAbort(1000, ac.signal)).rejects.toBeDefined();
+  });
+
+  it('rejects on abort mid-sleep and leaves no abort listener leaked', async () => {
+    const ac = new AbortController();
+    const add = vi.spyOn(ac.signal, 'addEventListener');
+    const p = sleepWithAbort(10_000, ac.signal);
+    ac.abort();
+    await expect(p).rejects.toBeDefined();
+    // The once-listener is consumed by the abort; nothing keeps it attached.
+    expect(add).toHaveBeenCalledTimes(1);
+  });
+
+  it('removes the abort listener when it resolves normally (no leak)', async () => {
+    vi.useFakeTimers();
+    try {
+      const ac = new AbortController();
+      const remove = vi.spyOn(ac.signal, 'removeEventListener');
+      const p = sleepWithAbort(50, ac.signal);
+      vi.advanceTimersByTime(50);
+      await p;
+      expect(remove).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/mode/abort-backoff.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared retry primitives for loop strategies (mode-default / mode-goal).
+ *
+ * Both modes back off between retryable provider failures with an identical
+ * exponential schedule and an abort-aware sleep. The logic was duplicated in
+ * each mode's loop; these are the single source of truth they now import.
+ */
+
+/**
+ * Sleep `ms` milliseconds, settling early if `signal` aborts. Rejects with the
+ * signal's abort reason (an `AbortError`-style `DOMException` when none) on
+ * abort so a back-off never silently outlives a cancelled turn, and crucially
+ * NEVER leaks the abort listener or the timer in any settle path (resolve,
+ * reject, or already-aborted) — a leaked listener on a long-lived signal
+ * accumulates across a turn's many retries.
+ */
+export function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    let onAbort: (() => void) | undefined;
+    const timer = setTimeout(() => {
+      if (signal && onAbort) signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, Math.max(0, ms));
+    if (signal) {
+      onAbort = (): void => {
+        clearTimeout(timer);
+        reject(abortReason(signal));
+      };
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+}
+
+function abortReason(signal: AbortSignal): unknown {
+  // Prefer the caller-supplied reason; fall back to a standard AbortError.
+  const reason = (signal as { reason?: unknown }).reason;
+  if (reason !== undefined) return reason;
+  return new DOMException('The operation was aborted', 'AbortError');
+}
+
+/**
+ * Exponential back-off for a 1-based retry `attempt`: `baseMs * 2^(attempt-1)`,
+ * clamped to `[baseMs, maxMs]` (default cap 30_000ms). `attempt <= 1` yields
+ * `baseMs`. Matches the schedule both modes used before extraction.
+ */
+export function nextBackoffMs(attempt: number, baseMs: number, maxMs = 30_000): number {
+  const exp = Math.max(0, Math.floor(attempt) - 1);
+  return Math.min(maxMs, baseMs * 2 ** exp);
+}

package/src/mode/collect-stream.ts

@@ -19,6 +19,24 @@ export interface CollectedToolUse {
   readonly input: unknown;
 }
 
+/** Sum two usage frames so multi-`message_end` responses don't undercount. */
+function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
+  const cacheRead =
+    a.cacheReadTokens !== undefined || b.cacheReadTokens !== undefined
+      ? (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0)
+      : undefined;
+  const cacheCreation =
+    a.cacheCreationTokens !== undefined || b.cacheCreationTokens !== undefined
+      ? (a.cacheCreationTokens ?? 0) + (b.cacheCreationTokens ?? 0)
+      : undefined;
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    ...(cacheRead !== undefined ? { cacheReadTokens: cacheRead } : {}),
+    ...(cacheCreation !== undefined ? { cacheCreationTokens: cacheCreation } : {}),
+  };
+}
+
 export interface StreamResult {
   readonly text: string;
   readonly toolUses: ReadonlyArray<CollectedToolUse>;
@@ -123,9 +141,12 @@ export async function collectProviderStream(
   };
   const transformed = await ctx.hooks.dispatchBeforeProviderCall(req, {
     sessionId: ctx.sessionId,
-    cwd: '',
+    // Thread the session's real cwd/env (mirrored on ModeContext) so path-based
+    // policy/security `onBeforeProviderCall` hooks see the true per-session
+    // values rather than blank placeholders — matching the dispatchToolCall path.
+    cwd: ctx.cwd,
     log: ctx.log,
-    env: {},
+    env: ctx.env,
     turnId: ctx.turnId,
     iteration: opts.iteration ?? 0,
   });
@@ -181,7 +202,11 @@ export async function collectProviderStream(
         }
         case 'message_end': {
           stopReason = event.stopReason;
-          if (event.usage) usage = event.usage;
+          // Accumulate across frames: a provider that splits a response into
+          // multiple message segments (or emits an interim then a final usage)
+          // must not have its token counts clobbered to only the last frame —
+          // that would undercount input/output/cache tokens for billing.
+          if (event.usage) usage = usage ? addUsage(usage, event.usage) : event.usage;
           break;
         }
         case 'error': {
@@ -214,10 +239,15 @@ export async function collectProviderStream(
       }
     }
   } catch (err) {
-    error = {
-      message: err instanceof Error ? err.message : String(err),
-      retryable: false,
-    };
+    // A stream-level `error` event is the more authoritative classification —
+    // don't let a subsequent iterator throw downgrade its `retryable: true` to
+    // false (which would stop the turn loop from retrying a transient failure).
+    if (!error) {
+      error = {
+        message: err instanceof Error ? err.message : String(err),
+        retryable: false,
+      };
+    }
   }
 
   const finalToolUses: CollectedToolUse[] = [];

package/src/mode/project-messages.test.ts

@@ -1,12 +1,26 @@
 import { describe, expect, it } from 'vitest';
-import { projectUserPrompt, resolvedCallIdSet } from './project-messages.js';
+import { projectMessagesFromLog, projectUserPrompt, resolvedCallIdSet } from './project-messages.js';
 import { computeElisionState } from '../elision-state.js';
 import { asEventId, asSessionId, asTurnId } from '../ids.js';
-import type { MoxxyEvent, UserPromptEvent } from '../events.js';
+import type { EventLogReader } from '../log.js';
+import type { MoxxyEvent, MoxxyEventOfType, MoxxyEventType, UserPromptEvent } from '../events.js';
+import type { TurnId } from '../ids.js';
 
 const sid = asSessionId('s1');
 const t1 = asTurnId('t1');
 
+function reader(events: ReadonlyArray<MoxxyEvent>): EventLogReader {
+  return {
+    length: events.length,
+    at: (seq) => events[seq],
+    slice: (from = 0, to = events.length) => events.slice(from, to),
+    ofType: <T extends MoxxyEventType>(type: T): ReadonlyArray<MoxxyEventOfType<T>> =>
+      events.filter((e): e is MoxxyEventOfType<T> => e.type === type),
+    byTurn: (turnId: TurnId) => events.filter((e) => e.turnId === turnId),
+    toJSON: () => events,
+  };
+}
+
 // No-elision state — computeElisionState returns the empty/inactive state when
 // the log has no elision events, which is the only state these pure sub-steps
 // branch on for a fresh (non-stubbed) prompt.
@@ -119,3 +133,51 @@ describe('resolvedCallIdSet', () => {
     expect(set.has('later')).toBe(true);
   });
 });
+
+describe('projectMessagesFromLog tool_result stringify hardening', () => {
+  function logWith(output: unknown): MoxxyEvent[] {
+    return [
+      event(0, { type: 'user_prompt', turnId: t1, source: 'user', text: 'go' }),
+      event(1, {
+        type: 'tool_call_requested',
+        turnId: t1,
+        source: 'model',
+        callId: 'c1',
+        name: 'weird',
+        input: {},
+      }),
+      event(2, { type: 'tool_result', turnId: t1, source: 'tool', callId: 'c1', ok: true, output }),
+    ];
+  }
+
+  function toolResultText(events: MoxxyEvent[]): string {
+    const msgs = projectMessagesFromLog({ log: reader(events) });
+    const tr = msgs.find((m) => m.role === 'tool_result');
+    const block = tr?.content[0];
+    return block && block.type === 'tool_result' ? (block.content as string) : '';
+  }
+
+  it('does not throw on a circular tool_result output (would permanently wedge the turn)', () => {
+    const circular: Record<string, unknown> = { a: 1 };
+    circular.self = circular;
+    const events = logWith(circular);
+    expect(() => projectMessagesFromLog({ log: reader(events) })).not.toThrow();
+    // Re-projecting the same append-only log must also never throw.
+    expect(() => projectMessagesFromLog({ log: reader(events) })).not.toThrow();
+    expect(typeof toolResultText(events)).toBe('string');
+  });
+
+  it('does not throw on a BigInt-bearing tool_result output', () => {
+    const events = logWith({ n: 10n });
+    expect(() => projectMessagesFromLog({ log: reader(events) })).not.toThrow();
+    expect(typeof toolResultText(events)).toBe('string');
+  });
+
+  it('still serializes a plain object output as JSON', () => {
+    expect(toolResultText(logWith({ ok: true }))).toBe('{"ok":true}');
+  });
+
+  it('passes a string output through verbatim', () => {
+    expect(toolResultText(logWith('plain text'))).toBe('plain text');
+  });
+});

package/src/mode/project-messages.ts

@@ -13,6 +13,50 @@ import {
 } from '../elision-state.js';
 import { isToolDisplayResult } from '../tool-display.js';
 
+/**
+ * Stringify an arbitrary tool output for the model-facing tool_result text.
+ * `tool_result.output` is `unknown` and comes straight from whatever a tool
+ * returned, so it can be circular or contain a BigInt — either of which makes
+ * `JSON.stringify` THROW. Because projection runs on every request over the
+ * append-only log, an unguarded throw here permanently wedges the session
+ * (every subsequent re-projection re-throws). Mirrors the try/catch guard the
+ * sibling sizing paths (`safeJsonLen`, `toolResultBytes`) already use.
+ */
+function safeStringifyOutput(output: unknown): string {
+  if (typeof output === 'string') return output;
+  try {
+    return JSON.stringify(output ?? '');
+  } catch {
+    try {
+      return String(output ?? '');
+    } catch {
+      return '[unserializable tool output]';
+    }
+  }
+}
+
+/**
+ * An image ContentBlock extracted from an image-shaped tool output. A tool can
+ * return either `{ mediaType, base64 }` (the desktop screenshot/clipboard shape)
+ * or the provider-native `{ type:'image', mediaType, data }` — both normalize to
+ * the same provider `image` block so the model SEES the pixels instead of a
+ * stringified blob of base64.
+ */
+function imageBlockFromOutput(output: unknown): Extract<ContentBlock, { type: 'image' }> | null {
+  if (typeof output !== 'object' || output === null) return null;
+  const o = output as { type?: unknown; mediaType?: unknown; base64?: unknown; data?: unknown };
+  if (typeof o.mediaType !== 'string') return null;
+  // `{ mediaType, base64 }` (raw shape) or `{ type:'image', mediaType, data }`.
+  const data =
+    typeof o.base64 === 'string'
+      ? o.base64
+      : o.type === 'image' && typeof o.data === 'string'
+        ? o.data
+        : null;
+  if (data === null) return null;
+  return { type: 'image', mediaType: o.mediaType, data };
+}
+
 /** Appended to the system prompt while elision is active (see projection). */
 export const ELISION_SYSTEM_NOTE =
   'Context note: to stay within budget, older turns may appear as stubs like ' +
@@ -439,6 +483,10 @@ export function projectMessages(
         // Stub bulky old tool output to a recall-able marker (decision shared
         // with estimateContextTokens via toolResultStubbed).
         let text: string;
+        // An image-shaped output (a screenshot/clipboard grab) is carried as a
+        // provider `image` block so the model SEES the pixels — only when the
+        // result isn't stubbed (elided) or an error and the call succeeded.
+        let image: Extract<ContentBlock, { type: 'image' }> | null = null;
         if (toolResultStubbed(e, el)) {
           const recalled = el.recalledCallIds.has(e.callId) || el.recalledSeqs.has(e.seq);
           text = toolResultStub(e.callId, toolResultBytes(e.output), recalled);
@@ -448,13 +496,18 @@ export function projectMessages(
           // Rich result (e.g. a file diff): the model only needs the short
           // `forModel` summary — the structured `display` is for channels.
           text = e.output.forModel;
+        } else if (e.ok && (image = imageBlockFromOutput(e.output))) {
+          // Short marker satisfies the tool_use→tool_result pairing; the image
+          // block (appended below) carries the actual pixels.
+          text = '[image returned by tool — see attached image]';
         } else {
-          text = typeof e.output === 'string' ? e.output : JSON.stringify(e.output ?? '');
+          text = safeStringifyOutput(e.output);
         }
-        messages.push({
-          role: 'tool_result',
-          content: [{ type: 'tool_result', toolUseId: e.callId, content: text, isError: !e.ok }],
-        });
+        const content: ContentBlock[] = [
+          { type: 'tool_result', toolUseId: e.callId, content: text, isError: !e.ok },
+        ];
+        if (image) content.push(image);
+        messages.push({ role: 'tool_result', content });
         recordStable(e.seq);
         break;
       }

package/src/mode/stable-hash.ts

@@ -2,19 +2,79 @@
  * 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.
+ *
+ * MUST be total: the input is a tool call's `input`, typed `unknown` and coming
+ * straight from whatever the provider deserialized (it can carry a BigInt, a
+ * circular reference, or a deeply nested structure). This hashes in the HOT
+ * tool-dispatch path (`detector.record` in tool-dispatch.ts), where an
+ * unhandled throw or a stack-overflow from unbounded recursion would crash the
+ * whole turn. So every leaf is serialized defensively, cycles are detected and
+ * collapsed to a stable marker, and recursion is depth-bounded.
  */
 export function stableHash(input: unknown): string {
-  return canonicalize(input);
+  try {
+    return canonicalize(input, new WeakSet(), 0);
+  } catch {
+    // Last-ditch guard: an exotic value (e.g. a Proxy whose ownKeys/get trap
+    // throws, or a getter that throws) could still surface a throw out of the
+    // recursive walk. Never let it escape into the hot tool-dispatch path —
+    // collapse to a stable opaque marker. Two such inputs hash equal, which at
+    // worst makes the stuck detector slightly more eager, never crashes.
+    return '"[unhashable]"';
+  }
+}
+
+// Bound recursion so a hostile/pathologically-nested input can't blow the stack
+// (the JS engine throws RangeError well before this, and a tool input that deep
+// is already degenerate for stuck-detection purposes — treat it as opaque).
+const MAX_DEPTH = 100;
+
+/** Serialize a primitive leaf without ever throwing (BigInt/symbol/etc.). */
+function leaf(value: unknown): string {
+  switch (typeof value) {
+    case 'string':
+      return JSON.stringify(value);
+    case 'number':
+      // JSON.stringify(NaN|±Infinity) is 'null'; keep that, but use a stable
+      // distinct token so two different non-finite values don't collide.
+      return Number.isFinite(value) ? String(value) : `#${String(value)}`;
+    case 'boolean':
+      return value ? 'true' : 'false';
+    case 'bigint':
+      // JSON.stringify THROWS on a BigInt — serialize it ourselves, tagged so a
+      // bigint and the equal-valued number never collide.
+      return `${value.toString()}n`;
+    case 'symbol':
+      return `@${String(value)}`;
+    case 'function':
+      return '"[fn]"';
+    default:
+      return 'null';
+  }
 }
 
-function canonicalize(value: unknown): string {
+function canonicalize(value: unknown, seen: WeakSet<object>, depth: number): 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(',') + ']';
+  if (typeof value !== 'object') return leaf(value);
+  // Cycle guard: a circular reference would recurse forever → stack overflow.
+  if (seen.has(value)) return '"[circular]"';
+  if (depth >= MAX_DEPTH) return '"[deep]"';
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return '[' + value.map((v) => canonicalize(v, seen, depth + 1)).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, seen, depth + 1)).join(',') +
+      '}'
+    );
+  } finally {
+    // Allow the same object to appear in sibling positions (DAG, not a cycle)
+    // without being flagged circular — only ancestors are forbidden.
+    seen.delete(value);
   }
-  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-helpers.ts

@@ -25,6 +25,7 @@ export {
   type StreamResult,
 } from './mode/collect-stream.js';
 export { runSingleShotTurn } from './mode/single-shot.js';
+export { sleepWithAbort, nextBackoffMs } from './mode/abort-backoff.js';
 export {
   createStuckLoopDetector,
   type StuckLoopDetector,

package/src/mode.test.ts

@@ -17,4 +17,22 @@ describe('migrateModeName', () => {
     expect(migrateModeName('some-future-mode')).toBe('some-future-mode');
     expect(migrateModeName('')).toBe('');
   });
+
+  it('never leaks an inherited Object.prototype member for a polluting name', () => {
+    // `name` is externally-sourced; a bare object index would resolve these to
+    // truthy Functions and break the `string` contract. Each must pass through
+    // as its own identity string instead.
+    for (const polluting of [
+      'toString',
+      'valueOf',
+      'constructor',
+      'hasOwnProperty',
+      'isPrototypeOf',
+      '__proto__',
+    ]) {
+      const result = migrateModeName(polluting);
+      expect(typeof result).toBe('string');
+      expect(result).toBe(polluting);
+    }
+  });
 });

package/src/mode.ts

@@ -219,5 +219,11 @@ const LEGACY_MODE_NAMES: Readonly<Record<string, string>> = {
 
 /** Map a possibly-legacy mode name to its current name (identity if unknown). */
 export function migrateModeName(name: string): string {
-  return LEGACY_MODE_NAMES[name] ?? name;
+  // Own-property check: `name` is externally-sourced (config / preferences /
+  // setMode RPC). A bare `LEGACY_MODE_NAMES[name]` index would resolve inherited
+  // Object.prototype members (`toString`, `constructor`, `__proto__`, …) — all
+  // truthy Functions, so `?? name` would NOT fall through and the function would
+  // return a Function, breaking its `string` contract and shadowing a mode
+  // legitimately named `toString`.
+  return Object.hasOwn(LEGACY_MODE_NAMES, name) ? LEGACY_MODE_NAMES[name]! : name;
 }

package/src/provider-utils.test.ts

@@ -81,4 +81,14 @@ describe('zodToJsonSchema', () => {
     expect(out).toHaveProperty('type', 'object');
     expect(out).toHaveProperty('properties');
   });
+
+  it('bounds recursion on a deeply nested schema instead of overflowing the stack', () => {
+    // Build a pathologically deep array nesting; the converter must degrade to
+    // the permissive {} past its depth cap rather than blow the call stack.
+    let schema: z.ZodTypeAny = z.string();
+    for (let i = 0; i < 500; i++) schema = z.array(schema);
+    expect(() => zodToJsonSchema(schema)).not.toThrow();
+    const out = zodToJsonSchema(schema);
+    expect(out).toBeDefined();
+  });
 });

package/src/provider-utils.ts

@@ -72,7 +72,16 @@ export function toFriendlyError(
  * (`shape`, `type`) which aren't part of zod's public typed surface but are
  * stable enough across versions to rely on for this best-effort path.
  */
-export function zodToJsonSchema(schema: unknown): unknown {
+/**
+ * Max recursion depth for {@link zodToJsonSchema}. A legitimately deep finite
+ * schema (or a pathological/adversarial tool definition) recurses one frame per
+ * level; past this cap we degrade to the permissive `{}` schema instead of
+ * blowing the call stack and taking down provider request construction.
+ */
+const MAX_SCHEMA_DEPTH = 32;
+
+export function zodToJsonSchema(schema: unknown, depth = 0): unknown {
+  if (depth > MAX_SCHEMA_DEPTH) return {};
   const s = schema as { _def?: { typeName?: string }; toJSON?: () => unknown };
   // Only honor a pre-serialized schema's `toJSON` for NON-zod objects (a plain
   // JSON-schema object passed through). A real zod schema (has `_def`) MUST go
@@ -89,7 +98,7 @@ export function zodToJsonSchema(schema: unknown): unknown {
   // Codex's /responses validator reject ("object schema missing properties").
   if (typeName === 'ZodEffects') {
     const inner = (def as unknown as { schema: unknown }).schema;
-    return zodToJsonSchema(inner);
+    return zodToJsonSchema(inner, depth + 1);
   }
   // ZodOptional / ZodNullable / ZodDefault / ZodBranded / ZodReadonly all
   // wrap an inner schema we want to unwrap for JSON-schema purposes.
@@ -101,7 +110,7 @@ export function zodToJsonSchema(schema: unknown): unknown {
     typeName === 'ZodReadonly'
   ) {
     const inner = (def as unknown as { innerType: unknown }).innerType;
-    return zodToJsonSchema(inner);
+    return zodToJsonSchema(inner, depth + 1);
   }
   // `.and(other)` produces a ZodIntersection. The standard JSON-schema
   // representation is `allOf`, but strict validators (Codex again) want
@@ -110,8 +119,8 @@ export function zodToJsonSchema(schema: unknown): unknown {
   // and required lists into one object. Fall back to `allOf` otherwise.
   if (typeName === 'ZodIntersection') {
     const intersection = def as unknown as { left: unknown; right: unknown };
-    const left = zodToJsonSchema(intersection.left) as Record<string, unknown>;
-    const right = zodToJsonSchema(intersection.right) as Record<string, unknown>;
+    const left = zodToJsonSchema(intersection.left, depth + 1) as Record<string, unknown>;
+    const right = zodToJsonSchema(intersection.right, depth + 1) as Record<string, unknown>;
     if (
       left &&
       right &&
@@ -139,7 +148,7 @@ export function zodToJsonSchema(schema: unknown): unknown {
     const properties: Record<string, unknown> = {};
     const required: string[] = [];
     for (const [key, value] of Object.entries(shape)) {
-      properties[key] = zodToJsonSchema(value);
+      properties[key] = zodToJsonSchema(value, depth + 1);
       const isOptional = (value as { isOptional?: () => boolean }).isOptional?.();
       if (!isOptional) required.push(key);
     }
@@ -166,11 +175,11 @@ export function zodToJsonSchema(schema: unknown): unknown {
   }
   if (typeName === 'ZodUnion' || typeName === 'ZodDiscriminatedUnion') {
     const options = (def as unknown as { options: ReadonlyArray<unknown> }).options;
-    return { anyOf: options.map((o) => zodToJsonSchema(o)) };
+    return { anyOf: options.map((o) => zodToJsonSchema(o, depth + 1)) };
   }
   if (typeName === 'ZodArray') {
     // ZodArray._def.type is the element schema.
-    const items = zodToJsonSchema((def as unknown as { type: unknown }).type);
+    const items = zodToJsonSchema((def as unknown as { type: unknown }).type, depth + 1);
     return { type: 'array', items };
   }
   if (typeName === 'ZodRecord') {
@@ -178,18 +187,18 @@ export function zodToJsonSchema(schema: unknown): unknown {
     // one schema. Carry the value schema through `additionalProperties` rather
     // than discarding it to the permissive fallback below.
     const valueType = (def as unknown as { valueType: unknown }).valueType;
-    return { type: 'object', additionalProperties: zodToJsonSchema(valueType) };
+    return { type: 'object', additionalProperties: zodToJsonSchema(valueType, depth + 1) };
   }
   if (typeName === 'ZodTuple') {
     // ZodTuple._def.items is the ordered element schemas; `rest` (if set) is the
     // variadic tail. Emit a fixed-position `items` array + an `additionalItems`
     // schema for the rest, mirroring JSON-schema's positional-tuple form.
     const tupleDef = def as unknown as { items: ReadonlyArray<unknown>; rest?: unknown };
-    const items = tupleDef.items.map((i) => zodToJsonSchema(i));
+    const items = tupleDef.items.map((i) => zodToJsonSchema(i, depth + 1));
     return {
       type: 'array',
       items,
-      ...(tupleDef.rest != null ? { additionalItems: zodToJsonSchema(tupleDef.rest) } : {}),
+      ...(tupleDef.rest != null ? { additionalItems: zodToJsonSchema(tupleDef.rest, depth + 1) } : {}),
     };
   }
   if (typeName === 'ZodAny' || typeName === 'ZodUnknown') {

package/src/requirements.ts

@@ -13,16 +13,28 @@ export type RequirementKind =
 
 export type RequirementState = 'registered' | 'active' | 'ready';
 
-export interface MoxxyRequirement {
-  readonly kind: RequirementKind;
+/** Fields common to every requirement kind. */
+interface RequirementBase {
   readonly name: string;
   readonly state?: RequirementState;
-  readonly version?: string;
   readonly optional?: boolean;
   readonly reason?: string;
   readonly hint?: string;
 }
 
+/**
+ * A declared dependency a plugin/config can require be present (and optionally
+ * active/ready). It is a discriminated union on `kind`: `version` is ONLY valid
+ * on the `plugin` kind, because that is the sole kind whose target resolves a
+ * version (see core's `RequirementRegistry.targetInfo`). A `version` on any
+ * other kind would compare against an always-undefined target version and
+ * report a permanent spurious `version_mismatch`, so the type forbids it at
+ * compile time rather than letting it silently slip through.
+ */
+export type MoxxyRequirement =
+  | (RequirementBase & { readonly kind: 'plugin'; readonly version?: string })
+  | (RequirementBase & { readonly kind: Exclude<RequirementKind, 'plugin'> });
+
 export interface RequirementIssue {
   readonly requirement: MoxxyRequirement;
   readonly code: 'missing' | 'inactive' | 'not_ready' | 'version_mismatch';