stitchkit 0.100.0 → 0.100.2

package/dist/entrypoints/files.js

@@ -1,6 +1,6 @@
 import {
   attemptExclusiveLock
-} from "../index-js7gqrb1.js";
+} from "../index-c6bxbsnc.js";
 import"../index-zjjyynm3.js";
 import {
   ManagedFileError,
@@ -47,6 +47,12 @@ function describeHolder(holder) {
   const machine = holder.machine === undefined ? "" : `, machine ${holder.machine}`;
   return `pid ${holder.pid} on ${holder.host}${machine} since ${holder.acquiredAt}`;
 }
+function describeEvidence(diagnosis) {
+  if (!diagnosis)
+    return "";
+  const identity = diagnosis.identity === undefined ? "" : `, identity ${diagnosis.identity}`;
+  return ` (${diagnosis.attribution}, liveness ${diagnosis.liveness}${identity})`;
+}
 function pause(ms, signal) {
   return new Promise((resolve) => {
     const done = () => {
@@ -94,7 +100,7 @@ async function withExclusiveLock(path, run, options = {}) {
     const remaining = deadline - performance.now();
     if (remaining <= 0) {
       const holder = attempt.diagnosis?.owner ?? null;
-      throw new ExclusiveLockError("LOCK_TIMEOUT", label, holder, `[stitchkit] the lock on "${label}" is held by ${describeHolder(holder)}; gave up after ${timeoutMs} ms`, { cause: attempt.error });
+      throw new ExclusiveLockError("LOCK_TIMEOUT", label, holder, `[stitchkit] the lock on "${label}" is held by ${describeHolder(holder)}${describeEvidence(attempt.diagnosis)}; gave up after ${timeoutMs} ms`, { cause: attempt.error });
     }
     await pause(Math.min(delay * (0.5 + Math.random() / 2), remaining), signal);
     delay = Math.min(delay * 2, MAX_RETRY_MS);

package/dist/entrypoints/index.js

@@ -32,6 +32,9 @@ import {
   RealtimeRequestRejectedError,
   RealtimeRequestTimeoutError
 } from "../index-dce5wxcq.js";
+import {
+  withDeadline
+} from "../index-b9aefrqd.js";
 import"../index-48ffdxgk.js";
 import {
   createContractFactory,
@@ -398,8 +401,8 @@ function createRetainedTopics() {
 }
 // src/browser/session.ts
 class SessionExpiredError extends Error {
-  constructor() {
-    super("The originating session is no longer active");
+  constructor(options) {
+    super("The originating session is no longer active", options);
     this.name = "SessionExpiredError";
   }
 }
@@ -446,7 +449,8 @@ function createSessionScope() {
             assertCurrent();
             return result;
           } catch (error) {
-            assertCurrent();
+            if (!current())
+              throw new SessionExpiredError({ cause: error });
             throw error;
           }
         },
@@ -500,7 +504,30 @@ function createSessionCredentials(config) {
   if (!Number.isInteger(timeout) || timeout < 1 || timeout > 3600000) {
     throw new RangeError("refreshTimeoutMs must be between 1 and 3600000");
   }
+  const storageTimeout = config.storageTimeoutMs ?? 30000;
+  if (!Number.isInteger(storageTimeout) || storageTimeout < 1 || storageTimeout > 3600000) {
+    throw new RangeError("storageTimeoutMs must be between 1 and 3600000");
+  }
   let state;
+  const bounded = async (work, wrote) => {
+    const outcome = await withDeadline(work, storageTimeout);
+    if (outcome.settled)
+      return;
+    work.then(() => {
+      if (state?.credentials !== wrote)
+        return restore();
+    }).catch(() => {
+      return;
+    });
+    throw new Error("Session storage did not answer within storageTimeoutMs");
+  };
+  const restore = () => serialize(async () => {
+    const current = state;
+    if (current)
+      await bounded(config.storage.write(current.operation.context, current.credentials), current.credentials);
+    else
+      await bounded(config.storage.clear(), undefined);
+  });
   let flight;
   const read = (operation) => {
     if (!config.scope.owns(operation) || state?.operation !== operation)
@@ -509,7 +536,7 @@ function createSessionCredentials(config) {
   };
   const write = (operation, credentials) => serialize(async () => {
     read(operation);
-    await config.storage.write(operation.context, credentials);
+    await bounded(config.storage.write(operation.context, credentials), credentials);
     operation.assertCurrent();
   });
   return {
@@ -526,7 +553,7 @@ function createSessionCredentials(config) {
       const generation = config.scope.generation;
       return serialize(async () => {
         if (config.scope.generation === generation)
-          await config.storage.clear();
+          await bounded(config.storage.clear(), undefined);
       });
     },
     read,
@@ -547,9 +574,9 @@ function createSessionCredentials(config) {
       const result = operation.run(async () => {
         const next = await Promise.race([config.refresh(credentials, signal), abortPromise]);
         read(operation);
+        state = { operation, credentials: next };
         await write(operation, next);
         read(operation);
-        state = { operation, credentials: next };
         return next;
       }).finally(() => {
         clearTimeout(timer);

package/dist/entrypoints/live.js

@@ -299,33 +299,37 @@ function createWatchClient(contract, config) {
   }
   function handleFor(action, args) {
     const mine = new Set;
-    let entry = entryFor({
+    const key = {
       service,
       action,
       digest: argumentsDigest(args),
       ...config.session && { instance: config.session.id }
-    }, args);
+    };
+    let entry;
     return {
       subscribe(listeners) {
         config.session?.assertCurrent();
-        if (entry.released)
-          entry = entryFor(entry.key, args);
-        if (entry.listeners.size >= maxListeners)
+        if (!entry || entry.released)
+          entry = entryFor(key, args);
+        const current = entry;
+        if (current.listeners.size >= maxListeners)
           throw new Error("Watch listener capacity exceeded");
         const registered = listeners;
         mine.add(registered);
-        entry.listeners.add(registered);
-        if (entry.hasValue)
-          registered.value(entry.value);
-        registered.state?.(entry.state);
-        openWatch(config, openTimeoutMs, entry);
+        current.listeners.add(registered);
+        if (current.hasValue)
+          registered.value(current.value);
+        registered.state?.(current.state);
+        openWatch(config, openTimeoutMs, current);
         return () => {
           mine.delete(registered);
-          entry.listeners.delete(registered);
-          releaseWatchClientEntry(entry);
+          current.listeners.delete(registered);
+          releaseWatchClientEntry(current);
         };
       },
       close() {
+        if (!entry)
+          return;
         for (const listener of mine)
           entry.listeners.delete(listener);
         mine.clear();

package/dist/entrypoints/node.js

@@ -8,7 +8,7 @@ import {
   createSocketIOServer,
   createUnixClientTransport,
   implementRegistry
-} from "../index-p3vsv1fb.js";
+} from "../index-hadmp193.js";
 import"../index-y91ry9h2.js";
 import {
   ShutdownOptionsSchema,

package/dist/entrypoints/server.js

@@ -19,14 +19,11 @@ import {
   sseRoute,
   streamingRoute,
   webSocketLane
-} from "../index-p3vsv1fb.js";
+} from "../index-hadmp193.js";
 import"../index-y91ry9h2.js";
 import {
   createFileStateStore
 } from "../index-tm88avnj.js";
-import {
-  withDeadline
-} from "../index-b9aefrqd.js";
 import {
   ShutdownOptionsSchema,
   ShutdownResultSchema,
@@ -36,6 +33,9 @@ import {
 } from "../index-3z73fh2c.js";
 import"../index-ndddxtyx.js";
 import"../index-dce5wxcq.js";
+import {
+  withDeadline
+} from "../index-b9aefrqd.js";
 import {
   inputIsQuery
 } from "../index-48ffdxgk.js";

package/dist/{index-s84he4v7.js → index-10x2hbx0.js}

@@ -7,7 +7,7 @@ import {
   createAgentRuntimeStore,
   isActiveRunState,
   replaceMessage
-} from "./index-0b1cnze2.js";
+} from "./index-vqr7f7v8.js";
 import {
   AgentRecoverablePageSchema,
   AgentStoreEventEnvelopeSchema,
@@ -202,6 +202,9 @@ var memoryEvents = {
       items,
       ...selected.length > items.length && last ? { nextSeq: last.seq + 1 } : {}
     });
+  },
+  async find(transaction, input) {
+    return (transaction.events.get(input.conversationId) ?? []).find((event) => event.eventId === input.eventId);
   }
 };
 function scanMemoryRecoverable(runs, input) {

package/dist/{index-js7gqrb1.js → index-c6bxbsnc.js}

@@ -108,7 +108,11 @@ async function readProcessInstance(pid, procRoot = "/proc") {
       readFile2(`${procRoot}/sys/kernel/random/boot_id`, "utf8"),
       readlink(`${procRoot}/self/ns/pid`),
       readFile2(`${procRoot}/self/status`, "utf8"),
-      readlink(`${procRoot}/self/ns/time`),
+      readlink(`${procRoot}/self/ns/time`).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+          return "";
+        throw error;
+      }),
       readFile2(`${procRoot}/self/stat`, "utf8"),
       readFile2(`${procRoot}/${pid}/stat`, "utf8")
     ]);

package/dist/{index-y9qn426m.js → index-eaysmdtq.js}

@@ -10,7 +10,7 @@ import {
   AgentStoredRunSchema,
   appendEventIn,
   createAgentRuntimeStore
-} from "./index-0b1cnze2.js";
+} from "./index-vqr7f7v8.js";
 import {
   AgentRecoverableDescriptorSchema,
   AgentRecoverablePageSchema,
@@ -528,6 +528,15 @@ var sqliteEvents = {
       items,
       ...hasMore && lastEvent ? { nextSeq: lastEvent.seq + 1 } : {}
     });
+  },
+  async find(transaction, input) {
+    const row = transaction.prepare(`
+        SELECT event_id, conversation_id, seq, schema_version, kind, occurred_at,
+          ignorable, payload
+        FROM stitchkit_agent_runtime_events
+        WHERE event_id = ? AND conversation_id = ?
+      `).get(input.eventId, input.conversationId);
+    return row === null || row === undefined ? undefined : parseEventRow(row);
   }
 };
 var sqliteArchive = {

package/dist/{index-xwhjjw2x.js → index-f4fx2tza.js}

@@ -714,7 +714,7 @@ var InvocationPayloadSchema = Base.extend({
 
 // src/agent-runtime/invocation-attempt.ts
 import { AsyncLocalStorage } from "node:async_hooks";
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { createHash as createHash2, randomUUID as randomUUID2 } from "node:crypto";
 import { wrapLanguageModel } from "ai";
 
 // src/agent-runtime/invocation-failure.ts
@@ -742,13 +742,18 @@ import {
 } from "node:crypto";
 import { z as z2 } from "zod";
 function invocationJson(value) {
+  const errors = new WeakSet;
   return z2.json().parse(JSON.parse(JSON.stringify(value, (_key, item) => {
     if (item instanceof Uint8Array)
       return { base64: Buffer.from(item).toString("base64") };
     if (item instanceof ArrayBuffer)
       return { base64: Buffer.from(item).toString("base64") };
-    if (item instanceof Error)
+    if (item instanceof Error) {
+      if (errors.has(item))
+        return { name: item.name, message: item.message };
+      errors.add(item);
       return { name: item.name, message: item.message, cause: item.cause };
+    }
     return item;
   })));
 }
@@ -760,6 +765,7 @@ function createInvocationPayloads(store, key, maxBytes) {
     throw new TypeError("Invocation payload key must contain 32 bytes");
   const encryptionKey = Uint8Array.from(key);
   return {
+    maxBytes,
     async write(identity, value) {
       const data = Buffer.from(serializeCanonicalJson(invocationJson(value)));
       if (data.byteLength > maxBytes)
@@ -771,7 +777,9 @@ function createInvocationPayloads(store, key, maxBytes) {
       cipher.setAAD(Buffer.from(JSON.stringify([identity.conversationId, identity.invocationId, artifactId])));
       const ciphertext = Buffer.concat([cipher.update(data), cipher.final()]);
       const { conversationId } = identity;
-      await store.appendEvent({
+      if (!store.appendEventOnce)
+        throw new TypeError("Invocation payloads require atomic store.appendEventOnce");
+      await store.appendEventOnce({
         conversationId,
         kind: "provider/payload",
         payload: {
@@ -783,7 +791,7 @@ function createInvocationPayloads(store, key, maxBytes) {
           tag: cipher.getAuthTag().toString("base64"),
           ciphertext: ciphertext.toString("base64")
         }
-      });
+      }, artifactId);
       return { artifactId, sha256 };
     },
     decrypt(conversationId, value) {
@@ -1067,8 +1075,11 @@ function wrapInvocationModel(writer, selected, step, model = selected.model) {
     }
     return context;
   });
-  const finish = async (context, status, payload, usage, response, providerMetadata) => invocationAudit(async () => {
-    const artifact = await writer.payloads.write(writer.identity, payload);
+  const finish = (...args) => recordResponse(...args).catch((error) => {
+    writer.receiptErrors.push(error);
+  });
+  const recordResponse = async (context, status, payload, usage, response, providerMetadata) => invocationAudit(async () => {
+    const artifact = await writer.payloads.write(writer.identity, boundedEvidence(payload, Math.floor(writer.payloads.maxBytes / 2)));
     await writer.append({
       ...writer.identity,
       type: "provider/response",
@@ -1126,13 +1137,12 @@ function wrapInvocationModel(writer, selected, step, model = selected.model) {
         let ended = false;
         let failed = false;
         let response;
-        const output = [];
-        let outputBytes = 0;
+        const evidence = streamEvidence(Math.floor(writer.payloads.maxBytes / 2));
         const end = async (status, value, usage, metadata) => {
           if (ended)
             return;
           ended = true;
-          await finish(context, status, { output, terminal: value }, usage, response, metadata);
+          await finish(context, status, evidence.payload(value), usage, response, metadata);
         };
         return {
           ...result,
@@ -1159,14 +1169,7 @@ function wrapInvocationModel(writer, selected, step, model = selected.model) {
               } else {
                 if (part.type === "error")
                   failed = true;
-                const json = invocationJson(part);
-                outputBytes += Buffer.byteLength(JSON.stringify(json));
-                if (outputBytes > 1048576) {
-                  await reader.cancel();
-                  await end("failed", { reason: "receipt-output-limit" });
-                  throw new RangeError("Invocation stream evidence exceeds 1 MiB");
-                }
-                output.push(json);
+                evidence.record(part);
               }
               controller.enqueue(part);
             },
@@ -1183,6 +1186,45 @@ function wrapInvocationModel(writer, selected, step, model = selected.model) {
     }
   });
 }
+function boundedEvidence(payload, limit) {
+  const serialized = JSON.stringify(invocationJson(payload));
+  const bytes = Buffer.byteLength(serialized);
+  if (bytes <= limit)
+    return payload;
+  return {
+    truncated: { bytes, sha256: createHash2("sha256").update(serialized).digest("hex") }
+  };
+}
+function streamEvidence(limit) {
+  const output = [];
+  const whole = createHash2("sha256");
+  let bytes = 0;
+  let parts = 0;
+  let truncated = false;
+  return {
+    record(part) {
+      const json = invocationJson(part);
+      const serialized = JSON.stringify(json);
+      whole.update(serialized).update(`
+`);
+      parts += 1;
+      const size = Buffer.byteLength(serialized);
+      if (!truncated && bytes + size > limit)
+        truncated = true;
+      if (truncated)
+        return;
+      bytes += size;
+      output.push(json);
+    },
+    payload(terminal) {
+      return {
+        output,
+        terminal,
+        ...truncated && { truncated: { parts, sha256: whole.digest("hex") } }
+      };
+    }
+  };
+}
 function reportedUsage(selected, value, providerMetadata) {
   const usage = {
     inputTokens: value?.inputTokens.total,
@@ -1240,6 +1282,13 @@ async function readInvocationRecords(store, input) {
   };
 }
 async function readInvocationPayload(store, payloads, input) {
+  const keyed = await store.findEventOnce?.({
+    conversationId: input.conversationId,
+    kind: "provider/payload",
+    key: input.artifactId
+  });
+  if (keyed)
+    return payloads.decrypt(input.conversationId, keyed.payload);
   let fromSeq;
   do {
     const page = await store.readEvents({
@@ -1268,6 +1317,30 @@ function beginAgentInvocation(ledger, store, input, context) {
     throw new TypeError("Agent and invocations must share the same store");
   return binding.start(input, context);
 }
+function withReceipt(result, writer) {
+  const [receiptError] = writer.receiptErrors;
+  return receiptError === undefined ? result : { ...result, receiptError };
+}
+async function generateWithFallback(models, writer, input, abortSignal) {
+  for (const [step, key] of input.models.entries()) {
+    abortSignal.throwIfAborted();
+    const selected = models.resolve(key);
+    try {
+      const result = await generateText({
+        model: wrapInvocationModel(writer, selected, step),
+        prompt: input.prompt,
+        ...input.settings,
+        maxRetries: 0,
+        abortSignal
+      });
+      return result.text;
+    } catch (error) {
+      if (!hasProviderOrigin(error) || abortSignal.aborted || step === input.models.length - 1)
+        throw error;
+    }
+  }
+  throw new Error("No completion model attempt available");
+}
 function createModelInvocationLedger(config) {
   const { store } = config;
   const appendOnce = store.appendEventOnce?.bind(store);
@@ -1315,6 +1388,7 @@ function createModelInvocationLedger(config) {
       process: executingProcess,
       payloads,
       onAttempt: config.onAttempt,
+      receiptErrors: [],
       async append(record) {
         const parsed = ModelInvocationRecordSchema.parse(record);
         await store.appendEvent({
@@ -1349,35 +1423,31 @@ function createModelInvocationLedger(config) {
         return { invocationId, outcome: "duplicate" };
       const deadline = AbortSignal.timeout(input.timeoutMs);
       const abortSignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
+      let text;
       try {
-        for (const [step, key] of input.models.entries()) {
-          abortSignal.throwIfAborted();
-          const selected = config.models.resolve(key);
-          try {
-            const result = await generateText({
-              model: wrapInvocationModel(writer, selected, step),
-              prompt: input.prompt,
-              ...input.settings,
-              maxRetries: 0,
-              abortSignal
-            });
-            await finish(writer, "succeeded");
-            return { invocationId, outcome: "succeeded", text: result.text };
-          } catch (error) {
-            if (!hasProviderOrigin(error) || abortSignal.aborted || step === input.models.length - 1)
-              throw error;
-          }
-        }
-        throw new Error("No completion model attempt available");
+        text = await generateWithFallback(config.models, writer, input, abortSignal);
       } catch (error) {
         const status = abortSignal.aborted ? "cancelled" : "failed";
-        const artifact = await payloads.write(writer.identity, { error });
-        await finish(writer, status, {
-          artifactId: artifact.artifactId,
-          payloadSha256: artifact.sha256
-        });
-        return { invocationId, outcome: status };
+        try {
+          const artifact = await payloads.write(writer.identity, { error });
+          await finish(writer, status, {
+            artifactId: artifact.artifactId,
+            payloadSha256: artifact.sha256
+          });
+        } catch (receiptError) {
+          writer.receiptErrors.push(receiptError);
+          await finish(writer, status).catch((error2) => {
+            writer.receiptErrors.push(error2);
+          });
+        }
+        return withReceipt({ invocationId, outcome: status }, writer);
+      }
+      try {
+        await finish(writer, "succeeded");
+      } catch (receiptError) {
+        writer.receiptErrors.push(receiptError);
       }
+      return withReceipt({ invocationId, outcome: "succeeded", text }, writer);
     },
     async read(rawInput, context) {
       const input = InvocationReadInputSchema.parse(rawInput);
@@ -2751,14 +2821,14 @@ async function* ownedProviderStream(input) {
 }
 
 // src/agent-runtime/run-provider-ledger.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 function withoutBinaryParts(message) {
   const reference = (value) => {
     if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
       const bytes = value instanceof ArrayBuffer ? new Uint8Array(value) : value;
       return {
         binary: true,
-        sha256: createHash2("sha256").update(bytes).digest("hex"),
+        sha256: createHash3("sha256").update(bytes).digest("hex"),
         bytes: bytes.byteLength
       };
     }
@@ -2813,7 +2883,7 @@ async function createRunProviderLedger(input) {
       const messageShas = [];
       for (const message of request.messages) {
         const body = canonicalAgentJson(JSON.parse(JSON.stringify(withoutBinaryParts(message))));
-        const sha256 = createHash2("sha256").update(body).digest("hex");
+        const sha256 = createHash3("sha256").update(body).digest("hex");
         messageShas.push(sha256);
         if (knownMessageShas.has(sha256))
           continue;
@@ -2824,8 +2894,8 @@ async function createRunProviderLedger(input) {
         });
         knownMessageShas.add(sha256);
       }
-      const instructionsSha256 = createHash2("sha256").update(typeof request.instructions === "string" ? request.instructions : canonicalAgentJson(JSON.parse(JSON.stringify(withoutBinaryParts(request.instructions))))).digest("hex");
-      const bodySha256 = createHash2("sha256").update(instructionsSha256).update(messageShas.join(",")).digest("hex");
+      const instructionsSha256 = createHash3("sha256").update(typeof request.instructions === "string" ? request.instructions : canonicalAgentJson(JSON.parse(JSON.stringify(withoutBinaryParts(request.instructions))))).digest("hex");
+      const bodySha256 = createHash3("sha256").update(instructionsSha256).update(messageShas.join(",")).digest("hex");
       await store.appendEvent({
         conversationId: state.run.conversationId,
         kind: "provider/request",
@@ -3596,7 +3666,7 @@ async function commitRunTerminal(execution) {
 }
 
 // src/agent-runtime/run-prompt-history.ts
-import { createHash as createHash3 } from "node:crypto";
+import { createHash as createHash4 } from "node:crypto";
 function snapshotForRunPrompt(snapshot, runId) {
   const runIndex = snapshot.runs.findIndex((candidate) => candidate.id === runId);
   if (runIndex < 0)
@@ -3615,7 +3685,7 @@ var USER_INSTRUCTION_SEED_KEY = "prompt.user-instructions";
 function seededInstructionMessage(input) {
   return AgentMessageSchema.parse({
     schemaVersion: 1,
-    id: createHash3("sha256").update(`${input.conversationId}\x00${input.seedKey}\x00${input.index}`).digest("hex"),
+    id: createHash4("sha256").update(`${input.conversationId}\x00${input.seedKey}\x00${input.index}`).digest("hex"),
     conversationId: input.conversationId,
     role: "user",
     status: "committed",

package/dist/{index-p3vsv1fb.js → index-hadmp193.js}

@@ -2365,11 +2365,20 @@ function bindRealtimeServer(contract, handle, options = {}) {
           onRejected: options.onRejected,
           logger: options.logger
         });
-        handler({
-          raw,
-          events,
-          to: (room) => outbound(raw.to(room))
-        });
+        const failed = (error) => {
+          try {
+            raw.disconnect(true);
+          } catch {}
+          if (options.logger)
+            options.logger.error("Realtime connection handler failed", { error });
+          else
+            console.error("[stitchkit] realtime connection handler failed", error);
+        };
+        try {
+          Promise.resolve(handler({ raw, events, to: (room) => outbound(raw.to(room)) })).catch(failed);
+        } catch (error) {
+          failed(error);
+        }
       };
       handle.io.on("connection", listener);
       return () => {

package/dist/{index-0b1cnze2.js → index-vqr7f7v8.js}

@@ -429,27 +429,38 @@ async function importConversation(driver, bytes) {
 
 // src/agent-runtime/store-event-once.ts
 import { createHash } from "node:crypto";
-function appendEventOnce(driver, input, key) {
-  const parsed = AppendAgentStoreEventSchema.parse(input);
+function eventOnceId(conversationId, kind, key) {
   if (!key)
     throw new TypeError("Event admission key must not be empty");
-  const eventId = createHash("sha256").update(JSON.stringify([parsed.conversationId, parsed.kind, key])).digest("hex");
+  return createHash("sha256").update(JSON.stringify([conversationId, kind, key])).digest("hex");
+}
+async function findEvent(driver, transaction, conversationId, eventId) {
+  if (driver.events.find)
+    return driver.events.find(transaction, { conversationId, eventId });
+  let fromSeq;
+  do {
+    const page = await driver.events.list(transaction, {
+      conversationId,
+      fromSeq,
+      limit: 1e4
+    });
+    const found = page.items.find((event) => event.eventId === eventId);
+    if (found)
+      return found;
+    fromSeq = page.nextSeq;
+  } while (fromSeq !== undefined);
+  return;
+}
+function appendEventOnce(driver, input, key) {
+  const parsed = AppendAgentStoreEventSchema.parse(input);
+  const eventId = eventOnceId(parsed.conversationId, parsed.kind, key);
   return driver.transaction(async (transaction) => {
     if (await driver.conversations?.isPurged(transaction, parsed.conversationId)) {
       throw new AgentConversationPurgedError;
     }
-    let fromSeq;
-    do {
-      const page = await driver.events.list(transaction, {
-        conversationId: parsed.conversationId,
-        fromSeq,
-        limit: 1e4
-      });
-      const previous = page.items.find((event2) => event2.eventId === eventId);
-      if (previous)
-        return { outcome: "duplicate", event: previous };
-      fromSeq = page.nextSeq;
-    } while (fromSeq !== undefined);
+    const previous = await findEvent(driver, transaction, parsed.conversationId, eventId);
+    if (previous)
+      return { outcome: "duplicate", event: previous };
     const event = await driver.events.append(transaction, {
       ...agentStoreEventDraft(parsed),
       eventId
@@ -457,6 +468,10 @@ function appendEventOnce(driver, input, key) {
     return { outcome: "applied", event };
   });
 }
+function findEventOnce(driver, input) {
+  const eventId = eventOnceId(input.conversationId, input.kind, input.key);
+  return driver.transaction((transaction) => findEvent(driver, transaction, input.conversationId, eventId), { access: "read" });
+}
 
 // src/agent-runtime/store-mutate.ts
 import { z as z4 } from "zod";
@@ -1011,6 +1026,7 @@ function createAgentRuntimeStore(driver) {
     loadRun: (input) => loadRun(driver, input),
     listActiveRuns: (conversationId) => listActiveRuns(driver, conversationId),
     appendEventOnce: (input, key) => appendEventOnce(driver, input, key),
+    findEventOnce: (input) => findEventOnce(driver, input),
     appendEvent: (input) => appendEvent(driver, input),
     readEvents: (input) => readEvents(driver, input),
     exportConversation: (conversationId) => exportConversation(driver, conversationId),