stitchkit 0.104.2 → 0.105.1

package/dist/{index-f330qqyg.js → index-5c26631f.js}

@@ -1,6 +1,13 @@
 import {
   raceAbort
-} from "./index-mbnnw3f2.js";
+} from "./index-b0kddvzw.js";
+import {
+  MAX_TIMER_MS,
+  sleep
+} from "./index-eemvahkc.js";
+import {
+  assertPositiveSafeInteger
+} from "./index-0s4xebbg.js";
 
 // src/process/contract.ts
 import { z } from "zod";
@@ -12,6 +19,24 @@ var NativeCommandSettlementSchema = z.discriminatedUnion("kind", [
   }),
   z.object({ kind: z.literal("error"), cause: z.unknown() })
 ]);
+var COMMAND_CLEANUP_TIMEOUT_MS = 2000;
+var MAX_COMMAND_STOP_GRACE_MS = 3600000;
+var NativeCommandStopPolicySchema = z.strictObject({
+  target: z.enum(["group", "leader"]),
+  signal: z.enum(["SIGTERM", "SIGINT", "SIGHUP", "SIGQUIT", "SIGUSR1", "SIGUSR2"]).default("SIGTERM"),
+  graceMs: z.number().int().nonnegative().max(MAX_COMMAND_STOP_GRACE_MS),
+  killOn: z.custom((v) => v instanceof AbortSignal).optional()
+});
+var REMOVED_NATIVE_COMMAND_OPTIONS = {
+  killGraceMs: "stop: { target: 'group', graceMs } (removed in 0.105.0)"
+};
+function unknownOptionMessage(keys) {
+  return keys.map((key) => {
+    const name = String(key);
+    const replacement = Object.hasOwn(REMOVED_NATIVE_COMMAND_OPTIONS, name) ? REMOVED_NATIVE_COMMAND_OPTIONS[name] : undefined;
+    return replacement === undefined ? `Unknown runNativeCommand option ${name}` : `Unknown runNativeCommand option ${name}; use ${replacement}`;
+  }).join("; ");
+}
 var NativeCommandOptionsSchema = z.strictObject({
   executable: z.string().min(1),
   args: z.array(z.string()).default([]),
@@ -19,29 +44,47 @@ var NativeCommandOptionsSchema = z.strictObject({
   env: z.record(z.string(), z.string()).optional(),
   envPolicy: z.enum(["declared-only", "ambient"]).default("declared-only"),
   signal: z.custom((v) => v instanceof AbortSignal).optional(),
-  timeoutMs: z.number().int().positive().max(2147483647).optional(),
+  timeoutMs: z.number().int().positive().max(MAX_TIMER_MS).optional(),
   maxOutputBytes: z.number().int().positive().optional(),
   capture: z.boolean().default(false),
   stdin: z.custom((v) => v instanceof Uint8Array).optional(),
   maxStdinBytes: z.number().int().positive().default(1024 * 1024),
   onOutput: z.custom((v) => typeof v === "function").optional(),
   onLeaderSettled: z.custom((v) => typeof v === "function").optional(),
-  killGraceMs: z.number().int().nonnegative().max(1e4).default(100),
-  cleanupTimeoutMs: z.number().int().positive().max(30000).default(2000)
-}).superRefine((input, ctx) => {
+  stop: NativeCommandStopPolicySchema.default({
+    target: "group",
+    signal: "SIGTERM",
+    graceMs: 100
+  }),
+  descendants: z.enum(["terminate-after-leader", "leave"]).default("terminate-after-leader"),
+  cleanupTimeoutMs: z.number().int().positive().max(30000).default(COMMAND_CLEANUP_TIMEOUT_MS)
+}, {
+  error: (issue) => issue.code === "unrecognized_keys" ? unknownOptionMessage(issue.keys) : undefined
+}).check((ctx) => {
+  const input = ctx.value;
   if (!input.signal && input.timeoutMs === undefined)
-    ctx.addIssue({ code: "custom", message: "Declare a caller signal or a finite timeout" });
+    ctx.issues.push({
+      code: "custom",
+      input: ctx.value,
+      message: "Declare a caller signal or a finite timeout"
+    });
   if (input.capture && input.maxOutputBytes === undefined)
-    ctx.addIssue({
+    ctx.issues.push({
       code: "custom",
+      input: ctx.value,
       message: "Capture requires a finite combined output budget"
     });
   if (input.stdin && input.stdin.byteLength > input.maxStdinBytes)
-    ctx.addIssue({ code: "custom", message: "stdin exceeds maxStdinBytes" });
+    ctx.issues.push({
+      code: "custom",
+      input: ctx.value,
+      message: "stdin exceeds maxStdinBytes"
+    });
 });
 var NativeCommandResultSchema = z.object({
   exitCode: z.number().int().nullable(),
   signal: z.string().nullable(),
+  descendantsStopped: z.boolean(),
   stdout: z.instanceof(Uint8Array),
   stderr: z.instanceof(Uint8Array)
 });
@@ -62,8 +105,7 @@ class NativeCommandError2 extends Error {
 
 // src/process/group.ts
 function createCommandDeadline(timeoutMs, reason) {
-  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0)
-    throw new RangeError("Command deadline must be a positive safe integer");
+  assertPositiveSafeInteger("Command deadline", timeoutMs, RangeError);
   const controller = new AbortController;
   const deadline = performance.now() + timeoutMs;
   let timer;
@@ -72,7 +114,7 @@ function createCommandDeadline(timeoutMs, reason) {
     if (remaining <= 0)
       controller.abort(reason);
     else
-      timer = setTimeout(schedule, Math.min(remaining, 2147483647));
+      timer = setTimeout(schedule, Math.min(remaining, MAX_TIMER_MS));
   };
   schedule();
   return {
@@ -86,14 +128,19 @@ function createCommandDeadline(timeoutMs, reason) {
 function deniedOnDarwin(error) {
   return process.platform === "darwin" && error instanceof Error && "code" in error && error.code === "EPERM";
 }
+function isErrno(error, code) {
+  return error instanceof Error && "code" in error && error.code === code;
+}
 function signalGroup(pid, signal) {
   if (pid === undefined)
-    return;
+    return false;
   try {
     process.kill(-pid, signal);
+    return true;
   } catch (error) {
-    if (!(error instanceof Error && ("code" in error) && error.code === "ESRCH"))
-      throw error;
+    if (isErrno(error, "ESRCH"))
+      return false;
+    throw error;
   }
 }
 function exists(pid) {
@@ -103,7 +150,7 @@ function exists(pid) {
     process.kill(-pid, 0);
     return true;
   } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ESRCH")
+    if (isErrno(error, "ESRCH"))
       return false;
     if (deniedOnDarwin(error))
       return true;
@@ -113,8 +160,7 @@ function exists(pid) {
 async function signalUntilSettled(pid, signal, deadline) {
   for (;; ) {
     try {
-      signalGroup(pid, signal);
-      return;
+      return signalGroup(pid, signal);
     } catch (error) {
       if (!deniedOnDarwin(error) || performance.now() >= deadline)
         throw error;
@@ -122,17 +168,51 @@ async function signalUntilSettled(pid, signal, deadline) {
     }
   }
 }
-async function stopCommandGroup(pid, graceMs, cleanupTimeoutMs = 2000, force = false) {
-  const deadline = performance.now() + graceMs + cleanupTimeoutMs;
-  if (force) {
+async function stopCommandGroup(stop) {
+  const { pid, policy } = stop;
+  const deadline = performance.now() + policy.graceMs + stop.cleanupTimeoutMs;
+  if (stop.force || policy.killOn?.aborted)
+    return signalUntilSettled(pid, "SIGKILL", deadline);
+  if (!await signalUntilSettled(pid, policy.signal, deadline))
+    return false;
+  const until = performance.now() + policy.graceMs;
+  let interval = 10;
+  let present = exists(pid);
+  while (present && !policy.killOn?.aborted && performance.now() < until) {
+    await sleep(Math.min(interval, until - performance.now()), policy.killOn).catch(() => {
+      return;
+    });
+    interval = Math.min(interval * 2, 250);
+    present = exists(pid);
+  }
+  if (present)
     await signalUntilSettled(pid, "SIGKILL", deadline);
-    return;
+  return true;
+}
+async function stopCommandLeader(stop) {
+  const { pid, policy, leader } = stop;
+  const deadline = performance.now() + policy.graceMs + stop.cleanupTimeoutMs;
+  const running = () => leader.exitCode === null && leader.signalCode === null;
+  let signalled = false;
+  if (!stop.force && !policy.killOn?.aborted && pid !== undefined && running()) {
+    try {
+      process.kill(pid, policy.signal);
+      signalled = true;
+    } catch (error) {
+      if (!isErrno(error, "ESRCH"))
+        throw error;
+    }
+    const grace = new AbortController;
+    const end = () => grace.abort();
+    policy.killOn?.addEventListener("abort", end, { once: true });
+    stop.leaderExit.then(end, end);
+    await sleep(policy.graceMs, grace.signal).catch(() => {
+      return;
+    });
+    policy.killOn?.removeEventListener("abort", end);
+    grace.abort();
   }
-  await signalUntilSettled(pid, "SIGTERM", deadline);
-  const until = performance.now() + graceMs;
-  while (performance.now() < until && exists(pid))
-    await new Promise((resolve) => setTimeout(resolve, Math.min(10, until - performance.now())));
-  await signalUntilSettled(pid, "SIGKILL", deadline);
+  return await signalUntilSettled(pid, "SIGKILL", deadline) || signalled;
 }
 function commandCleanupError(cause) {
   return new NativeCommandError2("COMMAND_CLEANUP", "Command cleanup did not complete", {
@@ -146,18 +226,26 @@ function waitForCommandClose(closed, timeoutMs) {
 
 // src/process/cleanup.ts
 async function cleanupNativeCommand(input) {
+  const signalled = Promise.resolve().then(input.signal);
+  const teardown = () => input.transport?.destroy();
+  const destroyed = signalled.then(teardown, teardown);
+  const awaitRelease = async () => {
+    if (!input.transport)
+      return;
+    try {
+      await waitForCommandClose(input.transport.released, input.timeoutMs);
+    } catch (cause) {
+      throw new Error(`Command handles remained open: ${[...input.transport.pendingHandles].join(", ")}`, { cause });
+    }
+  };
+  const released = signalled.then(awaitRelease, () => {
+    return;
+  });
   const cleanup = await Promise.allSettled([
     input.settle(input.event ?? { kind: "error", cause: input.error }),
-    Promise.resolve().then(() => input.transport?.destroy()),
-    Promise.resolve().then(input.signal).then(async () => {
-      if (!input.transport)
-        return;
-      try {
-        await waitForCommandClose(input.transport.released, input.timeoutMs);
-      } catch (cause) {
-        throw new Error(`Command handles remained open: ${[...input.transport.pendingHandles].join(", ")}`, { cause });
-      }
-    })
+    destroyed,
+    signalled,
+    released
   ]);
   const failures = cleanup.flatMap((item) => item.status === "rejected" && item.reason !== input.error ? [item.reason] : []);
   if (failures.length)
@@ -165,6 +253,11 @@ async function cleanupNativeCommand(input) {
 }
 
 // src/process/command-lifetime.ts
+class CommandStopped extends DOMException {
+  constructor() {
+    super("Command stopped", "AbortError");
+  }
+}
 function createCommandLifetime(input) {
   const acceptSettlement = (error) => {
     if (error instanceof NativeCommandError2 && error.code === "COMMAND_CLEANUP")
@@ -198,7 +291,7 @@ function createCommandLifetime(input) {
     },
     async stop() {
       if (!input.finished())
-        input.controller.abort(new DOMException("Command stopped", "AbortError"));
+        input.controller.abort(new CommandStopped);
       await input.result.then(() => {
         return;
       }, acceptSettlement);
@@ -329,13 +422,13 @@ function createCommandTransport(child) {
 function nativeCommandBudgets(options, driver) {
   const cleanupTimeoutMs = driver?.cleanupTimeoutMs ?? options.cleanupTimeoutMs;
   const timeoutMs = driver?.timeoutMs ?? options.timeoutMs;
-  for (const [name, value] of [
+  const budgets = [
     ["cleanup", cleanupTimeoutMs],
     ["execution", timeoutMs],
     ["close", driver?.closeTimeoutMs]
-  ])
-    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0))
-      throw new RangeError(`Command ${name} deadline must be a positive safe integer`);
+  ];
+  for (const [name, value] of budgets)
+    assertPositiveSafeInteger(`Command ${name} deadline`, value, RangeError);
   return { cleanupTimeoutMs, timeoutMs };
 }
 var owners = new WeakMap;
@@ -414,7 +507,14 @@ function outputStream(source, closed, maxBufferedBytes) {
     }
   };
 }
-function launchNativeCommand(options, driver, onSpawn, onFailure, onInputFailure, onAcquired) {
+function launchNativeCommand({
+  options,
+  driver,
+  onSpawn,
+  onFailure,
+  onInputFailure,
+  onAcquired
+}) {
   let native;
   const launch = driver?.launch;
   if (!launch)
@@ -518,10 +618,48 @@ async function failedCommandStart(cause, cleanup) {
   throw error;
 }
 
+// src/process/terminate.ts
+function signalCommandChild(child, input) {
+  if (input.group && ownsCommandGroup(child)) {
+    const stop = {
+      pid: child.pid,
+      policy: input.policy,
+      cleanupTimeoutMs: input.cleanupTimeoutMs,
+      force: input.force
+    };
+    return input.policy.target === "leader" ? stopCommandLeader({ ...stop, leader: child, leaderExit: input.leaderExit }) : stopCommandGroup(stop);
+  }
+  return Promise.resolve().then(() => {
+    if (child.exitCode !== null || child.signalCode !== null)
+      return false;
+    if (!child.kill("SIGKILL"))
+      throw new Error("Command leader termination was refused");
+    return true;
+  });
+}
+async function terminateOwnedGroup(child, closed, cleanupTimeoutMs) {
+  try {
+    await signalCommandChild(child, {
+      group: true,
+      policy: { target: "group", signal: "SIGTERM", graceMs: 0 },
+      leaderExit: closed,
+      cleanupTimeoutMs,
+      force: true
+    });
+    await waitForCommandClose(closed, cleanupTimeoutMs);
+  } catch (cause) {
+    for (const pipe of [child.stdin, child.stdout, child.stderr])
+      pipe.destroy();
+    throw commandCleanupError(cause);
+  }
+}
+
 // src/process/command-owner.ts
 function startNativeCommand(input, onSpawn, driver) {
   const options = NativeCommandOptionsSchema.parse(input);
   options.signal?.throwIfAborted();
+  const { killOn } = options.stop;
+  killOn?.throwIfAborted();
   if (process.platform === "win32" && driver?.group !== false)
     throw new NativeCommandError2("COMMAND_UNAVAILABLE", "POSIX process groups are required");
   const { cleanupTimeoutMs, timeoutMs } = nativeCommandBudgets(options, driver);
@@ -530,6 +668,12 @@ function startNativeCommand(input, onSpawn, driver) {
   options.signal?.addEventListener("abort", abort, { once: true });
   if (options.signal?.aborted)
     abort();
+  const kill = () => controller.abort(killOn?.reason);
+  killOn?.addEventListener("abort", kill, { once: true });
+  const release = () => {
+    options.signal?.removeEventListener("abort", abort);
+    killOn?.removeEventListener("abort", kill);
+  };
   const deadline = timeoutMs === undefined ? undefined : createCommandDeadline(timeoutMs, new NativeCommandError2("COMMAND_LIMIT", "Command deadline exceeded", {
     reason: "deadline"
   }));
@@ -549,13 +693,15 @@ function startNativeCommand(input, onSpawn, driver) {
     return;
   });
   const signalOwned = (force = driver?.force) => {
-    const child = acquired?.child;
-    if (!child)
-      return Promise.resolve();
-    return driver?.group === false || !ownsCommandGroup(child) ? Promise.resolve().then(() => {
-      if (child.exitCode === null && child.signalCode === null && !child.kill("SIGKILL"))
-        throw new Error("Command leader termination was refused");
-    }) : stopCommandGroup(child.pid, options.killGraceMs, cleanupTimeoutMs, force);
+    if (!acquired)
+      return Promise.resolve(false);
+    return signalCommandChild(acquired.child, {
+      group: driver?.group !== false,
+      policy: options.stop,
+      leaderExit: acquired.leader,
+      cleanupTimeoutMs,
+      force: force === true
+    });
   };
   const owner = createCommandLifetime({
     result,
@@ -567,19 +713,26 @@ function startNativeCommand(input, onSpawn, driver) {
   let spawnFailure;
   let launched;
   try {
-    launched = launchNativeCommand(options, driver, onSpawn, (error) => {
-      spawnFailure = new NativeCommandError2("COMMAND_UNAVAILABLE", "Command could not start", {
-        cause: error
-      });
-      controller.abort(spawnFailure);
-    }, (error) => controller.abort(error), (transport) => {
-      acquired = transport;
-      registerNativeCommandOwner(transport.child, owner);
+    launched = launchNativeCommand({
+      options,
+      driver,
+      onSpawn,
+      onFailure: (error) => {
+        spawnFailure = new NativeCommandError2("COMMAND_UNAVAILABLE", "Command could not start", {
+          cause: error
+        });
+        controller.abort(spawnFailure);
+      },
+      onInputFailure: (error) => controller.abort(error),
+      onAcquired: (transport) => {
+        acquired = transport;
+        registerNativeCommandOwner(transport.child, owner);
+      }
     });
   } catch (cause) {
     deadline?.cancel();
     deadline?.signal.removeEventListener("abort", expired);
-    options.signal?.removeEventListener("abort", abort);
+    release();
     controller.abort(cause);
     failedCommandStart(cause, (error) => cleanupNativeCommand({
       error,
@@ -598,7 +751,8 @@ function startNativeCommand(input, onSpawn, driver) {
   const cancelCloseDeadline = createLeaderCloseDeadline(leader, driver?.closeTimeoutMs, controller);
   const drain = async (stream, channel, captured) => {
     for await (const chunk of stream) {
-      controller.signal.throwIfAborted();
+      if (controller.signal.aborted)
+        continue;
       if (!(chunk instanceof Uint8Array))
         throw new TypeError("Expected binary command output");
       total += chunk.byteLength;
@@ -609,10 +763,28 @@ function startNativeCommand(input, onSpawn, driver) {
       if (options.capture)
         captured.push(Uint8Array.from(chunk));
       if (options.onOutput)
-        await raceAbort(Promise.resolve().then(() => {
-          controller.signal.throwIfAborted();
-          return options.onOutput?.(chunk, channel, controller.signal);
-        }), controller.signal);
+        try {
+          await raceAbort(Promise.resolve().then(() => {
+            controller.signal.throwIfAborted();
+            return options.onOutput?.(chunk, channel, controller.signal);
+          }), controller.signal);
+        } catch (error) {
+          if (!controller.signal.aborted || error !== controller.signal.reason)
+            throw error;
+        }
+    }
+  };
+  let descendantsStopped = false;
+  const settleLeader = async (event) => {
+    await settle(event);
+    if (controller.signal.aborted)
+      return;
+    if (options.descendants !== "terminate-after-leader" || event.kind !== "exit")
+      return;
+    try {
+      descendantsStopped = await signalOwned();
+    } catch (cause) {
+      throw commandCleanupError(cause);
     }
   };
   const run = (async () => {
@@ -622,11 +794,16 @@ function startNativeCommand(input, onSpawn, driver) {
         drain(output, "stdout", stdout),
         drain(errorOutput, "stderr", stderr)
       ]);
-      await raceAbort(Promise.all([drains, leader.then(settle)]), controller.signal);
+      await raceAbort(Promise.all([drains, leader.then(settleLeader)]), controller.signal);
       const status = await raceAbort(closed, controller.signal);
       if (spawnFailure !== undefined)
         throw spawnFailure;
-      return { ...status, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr) };
+      return {
+        ...status,
+        descendantsStopped,
+        stdout: Buffer.concat(stdout),
+        stderr: Buffer.concat(stderr)
+      };
     } catch (error) {
       controller.abort(error);
       await cleanupNativeCommand({
@@ -642,7 +819,7 @@ function startNativeCommand(input, onSpawn, driver) {
       cancelCloseDeadline();
       deadline?.cancel();
       deadline?.signal.removeEventListener("abort", expired);
-      options.signal?.removeEventListener("abort", abort);
+      release();
       controller.abort(new Error("Command completed"));
     }
   })();
@@ -650,4 +827,4 @@ function startNativeCommand(input, onSpawn, driver) {
   return owner;
 }
 
-export { NativeCommandError2, stopCommandGroup, spawnOwnedCommand, ownsCommandGroup, nativeCommandOwner, startNativeCommand };
+export { COMMAND_CLEANUP_TIMEOUT_MS, NativeCommandError2, CommandStopped, spawnOwnedCommand, nativeCommandOwner, terminateOwnedGroup, startNativeCommand };

package/dist/{index-adhgd4pe.js → index-5p55xreg.js}

@@ -2,7 +2,7 @@ import {
   AgentStoreEventEnvelopeSchema2,
   AgentStoreEventPageSchema2,
   AgentRecoverablePageSchema2
-} from "./index-r5hsgkz5.js";
+} from "./index-0gs4ymfj.js";
 import {
   AgentRecordIdSchema2,
   AgentMessageSchema2
@@ -16,7 +16,7 @@ import {
   isActiveRunState,
   replaceMessage,
   createAgentRuntimeStore2
-} from "./index-ssmd41kh.js";
+} from "./index-d2h99n7d.js";
 
 // src/agent-runtime/store-memory.ts
 import { z } from "zod";

package/dist/index-5w6t91ze.js

@@ -0,0 +1,47 @@
+import {
+  jsonDataRefusal
+} from "./index-m6w6jtda.js";
+import {
+  serializeCanonicalJson
+} from "./index-zsvzhjtk.js";
+
+// src/primitives/canonical-json.ts
+import { z } from "zod";
+var CanonicalJsonOptionsSchema = z.strictObject({
+  maxDepth: z.number().int().min(0).max(100).default(100),
+  maxNodes: z.number().int().positive().default(1e5),
+  maxBytes: z.number().int().positive().default(1024 * 1024)
+});
+var MESSAGES = {
+  cycle: "Value contains a cycle",
+  "negative-zero": "Value contains -0, which JSON cannot carry",
+  depth: "Value is nested deeper than maxDepth",
+  nodes: "Value has more nodes than maxNodes",
+  bytes: "Value is longer than maxBytes in UTF-8",
+  "not-json": "Expected bounded plain JSON: dense arrays, finite numbers, plain objects, no accessors"
+};
+
+class CanonicalJsonError2 extends TypeError {
+  reason;
+  constructor(reason) {
+    super(MESSAGES[reason]);
+    this.reason = reason;
+    this.name = "CanonicalJsonError";
+  }
+}
+function canonicalJson2(value, options = {}) {
+  return serialize(value, options, false);
+}
+function canonicalZodJson(value, options = {}) {
+  return serialize(value, options, true);
+}
+function serialize(value, options, zodJson) {
+  const limits = CanonicalJsonOptionsSchema.parse(options);
+  const snapshot = {};
+  const refusal = jsonDataRefusal(value, { ...limits, omitObjectUndefined: true, zodJson }, snapshot);
+  if (refusal !== undefined)
+    throw new CanonicalJsonError2(refusal);
+  return serializeCanonicalJson(snapshot.value);
+}
+
+export { CanonicalJsonError2, canonicalJson2, canonicalZodJson };

package/dist/{index-9pw0a51a.js → index-6yxhe58g.js}

@@ -34,6 +34,28 @@ function acceptsRawString(schema) {
   }
   return false;
 }
+function arrayMembers(schema) {
+  if (schema instanceof z.ZodArray)
+    return [schema];
+  if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable || schema instanceof z.ZodDefault) {
+    return arrayMembers(schema.unwrap());
+  }
+  if (schema instanceof z.ZodUnion) {
+    return schema.def.options.flatMap((option) => arrayMembers(option));
+  }
+  return [];
+}
+function writtenAsList(text, schema) {
+  if (!text.trimStart().startsWith("["))
+    return false;
+  let parsed;
+  try {
+    parsed = safeJsonParse(text);
+  } catch {
+    return false;
+  }
+  return Array.isArray(parsed) && arrayMembers(schema).some((m) => m.safeParse(parsed).success);
+}
 function matchingVariant(union, value) {
   const disc = union.def.discriminator;
   const tag = value[disc];
@@ -48,16 +70,27 @@ function matchingVariant(union, value) {
   }
   return;
 }
-function coerceValue(value, schema) {
+function coerceValue(value, schema, path) {
   if (!schema)
     return value;
   if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable || schema instanceof z.ZodDefault) {
-    return coerceValue(value, schema.unwrap());
+    return coerceValue(value, schema.unwrap(), path);
   }
   let current = value;
   if (typeof current === "string" && needsJsonCoercion(schema)) {
-    if (acceptsRawString(schema))
+    if (acceptsRawString(schema)) {
+      if (writtenAsList(current, schema)) {
+        throw new z.ZodError([
+          {
+            code: "custom",
+            path: [...path],
+            message: `${path.join(".")} is a list written as text — pass the array itself, not JSON written as text`,
+            input: current
+          }
+        ]);
+      }
       return current;
+    }
     try {
       current = safeJsonParse(current);
     } catch {
@@ -68,21 +101,21 @@ function coerceValue(value, schema) {
     const shape = schema.shape;
     const out = {};
     for (const [key, item] of Object.entries(current)) {
-      out[key] = coerceValue(item, shape[key]);
+      out[key] = coerceValue(item, shape[key], [...path, key]);
     }
     return out;
   }
   if (schema instanceof z.ZodArray && Array.isArray(current)) {
-    return current.map((item) => coerceValue(item, schema.element));
+    return current.map((item, index) => coerceValue(item, schema.element, [...path, index]));
   }
   if (schema instanceof z.ZodDiscriminatedUnion && isRecord(current)) {
     const variant = matchingVariant(schema, current);
-    return variant ? coerceValue(current, variant) : current;
+    return variant ? coerceValue(current, variant, path) : current;
   }
   return current;
 }
 function coerceJsonArgs2(args, schema) {
-  const coerced = coerceValue(args, schema);
+  const coerced = coerceValue(args, schema, []);
   return isRecord(coerced) ? coerced : args;
 }