@sentry/junior 0.144.0 → 0.145.0

package/dist/{chunk-PELZ2ZSY.js → chunk-HISR3DTV.js}

@@ -1,6 +1,6 @@
 import {
   appendAndEnqueueInboundMessage
-} from "./chunk-HD6BHR25.js";
+} from "./chunk-HLOUZC5C.js";
 import {
   ConversationTurnLifecycleService
 } from "./chunk-Q6QZTTLS.js";
@@ -12,36 +12,31 @@ import {
   agentBindingSchema,
   agentInvocationSchema,
   createAgentInvocationSchema
-} from "./chunk-DVO5VKYQ.js";
+} from "./chunk-B46ZMVOV.js";
 import {
   TurnInputCommitLostError,
   coerceThreadArtifactsState,
-  failAgentTurnSessionRecord,
-  getAgentTurnSessionRecord,
+  failTurnRecord,
   getAssistantReplyText,
   getConversationTurnBoundaryError,
   getPersistedSandboxState,
   getPersistedThreadState,
   getTerminalAssistantMessages,
+  getTurnRecord,
   isTurnInputCommitLostError,
   openConversationProjection,
-  persistCompletedSessionRecord,
   persistThreadStateById,
-  persistYieldSessionRecord
-} from "./chunk-BEGGFVFR.js";
+  saveTurnCheckpoint
+} from "./chunk-ZIAMN2UW.js";
 import {
   getConversationEventStore,
   getConversationStore,
   getSqlExecutor
-} from "./chunk-SBZP2J5Q.js";
+} from "./chunk-2UH3JI64.js";
 import {
   juniorAgentBindings,
   juniorAgentInvocations
-} from "./chunk-HNO2E5WB.js";
-import {
-  botConfig,
-  modelIdForProfile
-} from "./chunk-3GU4PWA3.js";
+} from "./chunk-27TEJTZO.js";
 
 // src/chat/agent-invocations/work.ts
 import { z } from "zod";
@@ -399,23 +394,34 @@ async function persistTerminalLifecycle(invocation) {
     });
   }
 }
-async function projectTerminalSession(invocation) {
-  const session = await getAgentTurnSessionRecord(
+async function projectTerminalTurn(invocation) {
+  let turn = await getTurnRecord(
     invocation.childConversationId,
     getAgentInvocationTurnId(invocation.invocationId)
   );
-  if (!session) {
+  if (!turn) {
     return void 0;
   }
-  if (session.state === "awaiting_resume" || session.state === "running") {
+  if (turn.state === "running") {
+    turn = await failTurnRecord({
+      conversationId: turn.conversationId,
+      expectedVersion: turn.version,
+      turnId: turn.turnId,
+      errorMessage: "Agent invocation lost its worker before it could pause"
+    });
+    if (!turn) {
+      return void 0;
+    }
+  }
+  if (turn.state === "paused") {
     return void 0;
   }
-  const result = getTerminalAssistantMessages(session.piMessages).map(getAssistantReplyText).filter((text) => text !== void 0).join("\n\n");
-  const failed = session.state !== "completed" || Boolean(session.errorMessage);
+  const result = getTerminalAssistantMessages(turn.piMessages).map(getAssistantReplyText).filter((text) => text !== void 0).join("\n\n");
+  const failed = turn.state !== "completed" || Boolean(turn.errorMessage);
   return await completeAgentInvocation({
     invocationId: invocation.invocationId,
     ...failed ? {
-      errorMessage: session.errorMessage ?? "Agent invocation failed",
+      errorMessage: turn.errorMessage ?? "Agent invocation failed",
       status: "failed"
     } : {
       result,
@@ -423,40 +429,6 @@ async function projectTerminalSession(invocation) {
     }
   });
 }
-async function recoverRunningSession(invocation) {
-  const session = await getAgentTurnSessionRecord(
-    invocation.childConversationId,
-    getAgentInvocationTurnId(invocation.invocationId)
-  );
-  if (!session || session.state !== "running") {
-    return;
-  }
-  const projection = await openConversationProjection({
-    conversationId: invocation.childConversationId
-  });
-  const parked = await persistYieldSessionRecord({
-    conversationId: invocation.childConversationId,
-    currentSliceId: session.sliceId,
-    errorMessage: "Recovered running agent invocation after worker loss",
-    messages: session.piMessages,
-    modelId: modelIdForProfile(botConfig, projection.modelProfile),
-    // Execution actor and reasoning live on the parent invocation, not Redis.
-    actor: invocation.actor,
-    reasoningLevel: invocation.reasoningLevel,
-    sessionId: session.sessionId,
-    surface: session.surface
-  });
-  if (!parked) {
-    await failAgentTurnSessionRecord({
-      conversationId: invocation.childConversationId,
-      expectedVersion: session.version,
-      sessionId: session.sessionId,
-      errorMessage: `Running agent invocation had no resumable boundary for ${invocation.invocationId}`
-    });
-    return;
-  }
-  await markAgentInvocationAwaitingResume(invocation.invocationId);
-}
 function blockingInvocationError(error) {
   const cause = getConversationTurnBoundaryError(error)?.cause ?? error;
   return cause instanceof AuthorizationFlowDisabledError || cause instanceof PluginCredentialFailureError ? cause : void 0;
@@ -508,8 +480,7 @@ function createAgentInvocationWorker(options) {
         await acknowledge();
         return { status: "completed" };
       }
-      await recoverRunningSession(invocation);
-      const projected = await projectTerminalSession(invocation);
+      const projected = await projectTerminalTurn(invocation);
       if (projected && isTerminalAgentInvocation(projected)) {
         await persistTerminalLifecycle(projected);
         await acknowledge();
@@ -653,17 +624,18 @@ function createAgentInvocationWorker(options) {
       sandboxRef: result.sandboxRef ?? sandboxRef
     });
     if (result.piMessages?.length) {
-      await persistCompletedSessionRecord({
+      await saveTurnCheckpoint({
+        mode: "completed",
         conversationId: invocation.childConversationId,
-        currentDurationMs: result.diagnostics.durationMs,
-        currentUsage: result.diagnostics.usage,
+        turnId,
+        durationMs: result.diagnostics.durationMs,
+        usage: result.diagnostics.usage,
         destination: invocation.destination,
         destinationVisibility: invocation.destinationVisibility,
         ...failed ? {
           errorMessage: result.diagnostics.errorMessage ?? "Agent invocation failed"
         } : {},
-        sessionId: turnId,
-        allMessages: result.piMessages,
+        messages: result.piMessages,
         modelId: result.diagnostics.modelId,
         actor: invocation.actor,
         reasoningLevel: result.diagnostics.reasoningLevel,

package/dist/{chunk-HD6BHR25.js → chunk-HLOUZC5C.js}

@@ -1,3 +1,6 @@
+import {
+  CONVERSATION_QUEUE_SCHEMA_VERSION
+} from "./chunk-JAL3CH4G.js";
 import {
   JUNIOR_THREAD_STATE_TTL_MS
 } from "./chunk-3Y47VMHV.js";
@@ -5,14 +8,14 @@ import {
   getConversationStore,
   parseDestination,
   sameDestination
-} from "./chunk-SBZP2J5Q.js";
+} from "./chunk-2UH3JI64.js";
 import {
   getDefaultRedisStateAdapterFor,
   getStateAdapter
-} from "./chunk-UDQMY6RS.js";
+} from "./chunk-QUG4JSZK.js";
 import {
   getChatConfig
-} from "./chunk-3GU4PWA3.js";
+} from "./chunk-XFKIRN3Q.js";
 import {
   parseStoredSlackActor
 } from "./chunk-HZF5P5UN.js";
@@ -20,13 +23,13 @@ import {
   isRecord,
   toOptionalNumber,
   toOptionalString
-} from "./chunk-RIFJUJSI.js";
+} from "./chunk-2LWPFSB4.js";
 
 // src/chat/task-execution/state.ts
 import { randomUUID } from "crypto";
 import { destinationSchema } from "@sentry/junior-plugin-api";
 import { z } from "zod";
-var CONVERSATION_PREFIX = "junior:conversation";
+var CONVERSATION_PREFIX = "junior:conversation:v2";
 var CONVERSATION_SCHEMA_VERSION = 2;
 var CONVERSATION_ACTIVITY_INDEX_MAX_LENGTH = 1e4;
 var CONVERSATION_INDEX_LOCK_TTL_MS = 1e4;
@@ -133,17 +136,16 @@ function normalizeSource(value) {
   return parsed.success ? parsed.data : void 0;
 }
 function normalizeExecutionStatus(value) {
-  if (value === "awaiting_resume" || value === "failed" || value === "idle" || value === "pending" || value === "running") {
+  if (value === "paused") {
+    return value;
+  }
+  if (value === "failed" || value === "idle" || value === "pending" || value === "running") {
     return value;
   }
   return void 0;
 }
-function normalizeMessage(value, schemaVersion) {
-  const candidate = schemaVersion === 1 && isRecord(value) && value.delivery === void 0 ? {
-    ...value,
-    delivery: "defer"
-  } : value;
-  const parsed = inboundMessageSchema.safeParse(candidate);
+function normalizeMessage(value) {
+  const parsed = inboundMessageSchema.safeParse(value);
   return parsed.success ? parsed.data : void 0;
 }
 function isFinalAttempt(message) {
@@ -170,7 +172,7 @@ function normalizeLease(value) {
     expiresAtMs
   };
 }
-function normalizeExecution(conversationId, value, schemaVersion) {
+function normalizeExecution(conversationId, value) {
   if (!isRecord(value)) {
     return void 0;
   }
@@ -181,7 +183,7 @@ function normalizeExecution(conversationId, value, schemaVersion) {
   const pendingMessages2 = [];
   if (Array.isArray(value.pendingMessages)) {
     for (const rawMessage of value.pendingMessages) {
-      const message = normalizeMessage(rawMessage, schemaVersion);
+      const message = normalizeMessage(rawMessage);
       if (!message || message.conversationId !== conversationId) {
         return void 0;
       }
@@ -215,19 +217,14 @@ function normalizeExecution(conversationId, value, schemaVersion) {
   };
 }
 function normalizeConversation(conversationId, value) {
-  if (!isRecord(value) || value.schemaVersion !== 1 && value.schemaVersion !== CONVERSATION_SCHEMA_VERSION) {
+  if (!isRecord(value) || value.schemaVersion !== CONVERSATION_SCHEMA_VERSION) {
     return void 0;
   }
-  const schemaVersion = value.schemaVersion;
   const storedConversationId = toOptionalString(value.conversationId);
   const createdAtMs = toOptionalNumber(value.createdAtMs);
   const lastActivityAtMs = toOptionalNumber(value.lastActivityAtMs);
   const updatedAtMs = toOptionalNumber(value.updatedAtMs);
-  const execution = normalizeExecution(
-    conversationId,
-    value.execution,
-    schemaVersion
-  );
+  const execution = normalizeExecution(conversationId, value.execution);
   const destination = value.destination === void 0 ? void 0 : parseDestination(value.destination);
   if (storedConversationId !== conversationId || typeof createdAtMs !== "number" || typeof lastActivityAtMs !== "number" || typeof updatedAtMs !== "number" || !execution || value.destination !== void 0 && !destination) {
     return void 0;
@@ -705,7 +702,7 @@ async function appendInboundMessage(args) {
         );
         return { status: "duplicate" };
       }
-      const status = current.execution.lease && current.execution.status === "running" ? "running" : current.execution.lease ? "awaiting_resume" : "pending";
+      const status = current.execution.lease && current.execution.status === "running" ? "running" : current.execution.lease ? "paused" : "pending";
       const next = {
         ...current,
         destination: current.destination ?? args.message.destination,
@@ -752,7 +749,7 @@ async function requestConversationWork(args) {
       destination: args.destination,
       nowMs
     });
-    const status = current.execution.lease ? "awaiting_resume" : "pending";
+    const status = current.execution.lease ? "paused" : "pending";
     await writeConversation(
       state,
       lock,
@@ -845,7 +842,7 @@ async function startConversationWork(args) {
         {
           ...current.execution,
           lease,
-          status: current.execution.status === "awaiting_resume" ? "awaiting_resume" : "running",
+          status: current.execution.status === "paused" ? "paused" : "running",
           runId: current.execution.runId ?? randomUUID(),
           lastEnqueuedAtMs: void 0,
           retryCount: startsNewRun ? 0 : current.execution.retryCount
@@ -984,7 +981,7 @@ async function ackMessages(args) {
     return true;
   });
 }
-async function requestConversationContinuation(args) {
+async function requestAnotherSlice(args) {
   const nowMs = args.nowMs ?? now();
   return await withConversationMutation(args, async (state, lock) => {
     const current = await readConversation(state, args.conversationId);
@@ -1003,7 +1000,7 @@ async function requestConversationContinuation(args) {
         current,
         {
           ...current.execution,
-          status: "awaiting_resume"
+          status: "paused"
         },
         nowMs
       )
@@ -1015,7 +1012,7 @@ async function beginConversationResume(args) {
   const nowMs = args.nowMs ?? now();
   return await withConversationMutation(args, async (state, lock) => {
     const current = await readConversation(state, args.conversationId);
-    if (!current || current.execution.lease?.token !== args.leaseToken || current.execution.status !== "awaiting_resume") {
+    if (!current || current.execution.lease?.token !== args.leaseToken || current.execution.status !== "paused") {
       return false;
     }
     await writeConversation(
@@ -1077,7 +1074,7 @@ async function recordConversationRetry(args) {
           retryCount: count,
           pendingMessages: stopped ? [] : current.execution.pendingMessages,
           runId: stopped ? void 0 : current.execution.runId,
-          status: stopped ? "failed" : "awaiting_resume"
+          status: stopped ? "failed" : "paused"
         },
         nowMs
       )
@@ -1093,7 +1090,7 @@ async function completeConversationWork(args) {
       return "lost_lease";
     }
     const hasPending = pendingMessages(current).length > 0;
-    const needsRun = current.execution.status === "awaiting_resume";
+    const needsRun = current.execution.status === "paused";
     const runnable = needsRun || hasPending;
     await writeConversation(
       state,
@@ -1103,7 +1100,7 @@ async function completeConversationWork(args) {
         {
           ...current.execution,
           lease: void 0,
-          status: needsRun ? "awaiting_resume" : hasPending ? "pending" : "idle",
+          status: needsRun ? "paused" : hasPending ? "pending" : "idle",
           lastProgressAtMs: args.madeProgress === false ? current.execution.lastProgressAtMs : nowMs,
           retryCount: runnable || args.madeProgress === false ? current.execution.retryCount : 0,
           runId: runnable ? current.execution.runId : void 0
@@ -1230,7 +1227,7 @@ async function clearExpiredConversationLease(args) {
           retryCount,
           pendingMessages: stopped ? [] : current.execution.pendingMessages,
           runId: stopped ? void 0 : current.execution.runId,
-          status: stopped ? "failed" : "awaiting_resume"
+          status: stopped ? "failed" : "paused"
         },
         nowMs
       )
@@ -1331,6 +1328,7 @@ async function ensureConversationWake(args) {
   }
   const queueResult = await args.queue.send(
     {
+      schemaVersion: CONVERSATION_QUEUE_SCHEMA_VERSION,
       conversationId: args.conversationId
     },
     {
@@ -1447,8 +1445,8 @@ async function ackMessages2(args) {
   await recordExecutionMetadata(args);
   return result;
 }
-async function requestConversationContinuation2(args) {
-  const result = await requestConversationContinuation(args);
+async function requestAnotherSlice2(args) {
+  const result = await requestAnotherSlice(args);
   await recordExecutionMetadata(args);
   return result;
 }
@@ -1511,7 +1509,7 @@ export {
   checkInConversationWork2 as checkInConversationWork,
   drainConversationMailbox2 as drainConversationMailbox,
   ackMessages2 as ackMessages,
-  requestConversationContinuation2 as requestConversationContinuation,
+  requestAnotherSlice2 as requestAnotherSlice,
   beginConversationResume2 as beginConversationResume,
   releaseConversationWork2 as releaseConversationWork,
   completeConversationWork2 as completeConversationWork,

package/dist/{chunk-BBCWYXHB.js → chunk-I47UGQPJ.js}

@@ -1,30 +1,30 @@
 import {
   resolveBaseUrl
-} from "./chunk-KQBXT5B7.js";
+} from "./chunk-FUBRJA5F.js";
 import {
   createPluginLogger,
   getPlugins
-} from "./chunk-44RJWAND.js";
+} from "./chunk-ZIMRGFYL.js";
 import {
   getDb,
   parseDestination
-} from "./chunk-SBZP2J5Q.js";
+} from "./chunk-2UH3JI64.js";
 import {
   sleep
 } from "./chunk-EM225ITJ.js";
 import {
   acquireActiveLock,
   getStateAdapter
-} from "./chunk-UDQMY6RS.js";
+} from "./chunk-QUG4JSZK.js";
 import {
   pluginCatalogRuntime
-} from "./chunk-ZF3N3JD6.js";
+} from "./chunk-SIN3MXH6.js";
 import {
   fetchWithBoundedOAuthErrorBodies
-} from "./chunk-A67GZN73.js";
+} from "./chunk-CD2XFGYQ.js";
 import {
   isRecord
-} from "./chunk-RIFJUJSI.js";
+} from "./chunk-2LWPFSB4.js";
 
 // src/chat/capabilities/router.ts
 var ProviderCredentialRouter = class {

package/dist/{chunk-IUFM5JWV.js → chunk-JAL3CH4G.js}

@@ -1,6 +1,8 @@
 // src/chat/task-execution/queue.ts
 import { z } from "zod";
+var CONVERSATION_QUEUE_SCHEMA_VERSION = 2;
 var conversationQueueMessageSchema = z.object({
+  schemaVersion: z.literal(CONVERSATION_QUEUE_SCHEMA_VERSION),
   conversationId: z.string().trim().min(1)
 }).strict();
 var ConversationQueueMessageRejectedError = class extends Error {
@@ -18,6 +20,7 @@ function isConversationQueueMessageRejectedError(error) {
 }
 
 export {
+  CONVERSATION_QUEUE_SCHEMA_VERSION,
   conversationQueueMessageSchema,
   ConversationQueueMessageRejectedError,
   isConversationQueueMessageRejectedError

package/dist/{chunk-E7HCWOHG.js → chunk-JLMVCNXL.js}

@@ -88,7 +88,8 @@ var conversationAuxiliaryCostsSchema = z2.object({
 var conversationSourceTaskSchema = z2.object({
   id: z2.string().min(1).optional(),
   kind: z2.enum(["scheduled", "event"]),
-  label: z2.string().min(1).optional()
+  label: z2.string().min(1).optional(),
+  title: z2.string().min(1).optional()
 }).strict().superRefine((value, context) => {
   if (Boolean(value.id) !== Boolean(value.label)) {
     context.addIssue({

package/dist/{chunk-STFCL3K4.js → chunk-JTGS3ZZE.js}

@@ -1,6 +1,6 @@
 import {
   logWarn
-} from "./chunk-RIFJUJSI.js";
+} from "./chunk-2LWPFSB4.js";
 
 // src/chat/conversation-privacy.ts
 import { AsyncLocalStorage } from "async_hooks";

package/dist/{chunk-GKA74DRA.js → chunk-LVVSIMBB.js}

@@ -1,6 +1,6 @@
 import {
   createAndEnqueueAgentInvocation
-} from "./chunk-PELZ2ZSY.js";
+} from "./chunk-HISR3DTV.js";
 import {
   actorFromRouting,
   toolInvocationDestination

package/dist/{chunk-SHEEZSLY.js → chunk-PJ4NMVQB.js}

@@ -3,10 +3,10 @@ import {
 } from "./chunk-UTL3MHPC.js";
 import {
   parseSlackThreadId
-} from "./chunk-PKH6762I.js";
+} from "./chunk-DXEQAIUV.js";
 import {
   normalizeSlackConversationId
-} from "./chunk-QE3TICD4.js";
+} from "./chunk-TZRXYWRE.js";
 
 // src/handlers/health.ts
 function readHealthReport() {

package/dist/{chunk-W7JFV5SB.js → chunk-QJBDABQA.js}

@@ -1,6 +1,6 @@
 import {
   recordTaskExecution
-} from "./chunk-WSOLZJJS.js";
+} from "./chunk-EIX2LQ6L.js";
 import {
   pluginTaskId,
   pluginTaskParamsSchema,
@@ -10,14 +10,14 @@ import {
   calculateContextCompactionTargetTokens,
   estimateTextTokens,
   getConversationContextCompactionTriggerTokens
-} from "./chunk-CNTWB2SM.js";
+} from "./chunk-VTDMB7XX.js";
 import {
   buildDeterministicTurnId,
   clearPendingAuth,
   coerceThreadConversationState,
-  getAgentTurnSessionRecord,
   getPersistedThreadState,
   getPiMessageRole,
+  getTurnRecord,
   hydrateConversationMessages,
   instructionTextForProjection,
   isToolResultError,
@@ -28,14 +28,14 @@ import {
   normalizeToolNameFromResult,
   persistThreadStateById,
   stripRuntimeTurnContext
-} from "./chunk-BEGGFVFR.js";
+} from "./chunk-ZIAMN2UW.js";
 import {
   JUNIOR_THREAD_STATE_TTL_MS
 } from "./chunk-3Y47VMHV.js";
 import {
   fallbackShortTitle,
   generateShortTitle
-} from "./chunk-54JMYQYS.js";
+} from "./chunk-ZYAJMESY.js";
 import {
   createPluginConversationEvents,
   createPluginEmbedder,
@@ -43,15 +43,15 @@ import {
   createPluginModel,
   createPluginState,
   getPlugins
-} from "./chunk-44RJWAND.js";
+} from "./chunk-ZIMRGFYL.js";
 import {
   getConversationStore,
   getDb,
   sameActorIdentity
-} from "./chunk-SBZP2J5Q.js";
+} from "./chunk-2UH3JI64.js";
 import {
   getStateAdapter
-} from "./chunk-UDQMY6RS.js";
+} from "./chunk-QUG4JSZK.js";
 import {
   ProviderError,
   botConfig,
@@ -59,7 +59,7 @@ import {
   findProviderError,
   getProviderErrorAttributes,
   getProviderErrorUserMessage
-} from "./chunk-3GU4PWA3.js";
+} from "./chunk-XFKIRN3Q.js";
 import {
   credentialSubjectSchema
 } from "./chunk-RUIXF3YQ.js";
@@ -70,7 +70,7 @@ import {
   buildTurnFailureResponse,
   logWarn,
   setSpanAttributes
-} from "./chunk-RIFJUJSI.js";
+} from "./chunk-2LWPFSB4.js";
 
 // src/chat/services/conversation-memory.ts
 var CONTEXT_MIN_LIVE_MESSAGES = 12;
@@ -410,7 +410,7 @@ import {
 
 // src/chat/services/turn-session-routing.ts
 async function resolveTurnSessionRouting(args) {
-  const conversationStore = args.conversationStore ?? (await import("./db-EFLHTBU6.js")).getConversationStore();
+  const conversationStore = args.conversationStore ?? (await import("./db-62PW6LM3.js")).getConversationStore();
   const conversation = await conversationStore.get({
     conversationId: args.conversationId
   });
@@ -998,10 +998,7 @@ async function withPluginTaskLock(taskId, callback) {
   }
 }
 async function loadPluginRun(params) {
-  const record = await getAgentTurnSessionRecord(
-    params.conversationId,
-    params.sessionId
-  );
+  const record = await getTurnRecord(params.conversationId, params.sessionId);
   if (!record) {
     throw new Error("Completed plugin task session record is unavailable");
   }
@@ -1033,7 +1030,7 @@ async function loadPluginRun(params) {
     // stripped transcript, so it reflects every committed instruction actor.
     actors: record.actors,
     ...runActor ? { actor: runActor } : {},
-    runId: record.sessionId,
+    runId: record.turnId,
     source: routing.source,
     transcript: [...contextEntries, ...runEntries]
   });
@@ -1085,7 +1082,7 @@ async function scheduleSessionCompletedPluginTasks(params, options = {}) {
   if (taskRegistrations.length === 0) {
     return;
   }
-  const record = await getAgentTurnSessionRecord(
+  const record = await getTurnRecord(
     coreParams.conversationId,
     coreParams.sessionId
   );

package/dist/{chunk-UDQMY6RS.js → chunk-QUG4JSZK.js}

@@ -1,16 +1,54 @@
 import {
   getChatConfig
-} from "./chunk-3GU4PWA3.js";
+} from "./chunk-XFKIRN3Q.js";
 
 // src/chat/state/adapter.ts
 import { createMemoryState } from "@chat-adapter/state-memory";
 import { createRedisState } from "@chat-adapter/state-redis";
 
 // src/chat/state/locks.ts
+import { setTimeout as sleep } from "timers/promises";
 var ACTIVE_LOCK_TTL_MS = 9e4;
+var MUTATION_LOCK_TTL_MS = 1e4;
 async function acquireActiveLock(state, threadId) {
   return await state.acquireLock(threadId, ACTIVE_LOCK_TTL_MS);
 }
+async function withLock(state, key, run, options = {}) {
+  const startedAtMs = Date.now();
+  let lock;
+  while (true) {
+    lock = await state.acquireLock(key, options.ttlMs ?? ACTIVE_LOCK_TTL_MS);
+    if (lock) break;
+    if (Date.now() - startedAtMs >= (options.waitMs ?? 0)) {
+      return { acquired: false };
+    }
+    await sleep(options.retryMs ?? 25, void 0, { ref: false });
+  }
+  const ttlMs = options.ttlMs ?? ACTIVE_LOCK_TTL_MS;
+  const heartbeat = options.keepAlive ? setInterval(
+    () => {
+      void state.extendLock(lock, ttlMs);
+    },
+    Math.max(1, Math.floor(ttlMs / 3))
+  ) : void 0;
+  heartbeat?.unref();
+  try {
+    return { acquired: true, value: await run(lock) };
+  } finally {
+    if (heartbeat) clearInterval(heartbeat);
+    await state.releaseLock(lock);
+  }
+}
+async function fenceLock(state, lock, ttlMs = MUTATION_LOCK_TTL_MS) {
+  if (!await state.extendLock(lock, ttlMs)) {
+    throw new Error(
+      `Lock ownership was lost before write for ${lock.threadId}`
+    );
+  }
+}
+async function withActiveLock(state, key, run) {
+  return await withLock(state, key, run);
+}
 
 // src/chat/state/adapter.ts
 var ACTIVE_LOCK_HEARTBEAT_MS = 3e4;
@@ -272,7 +310,11 @@ async function disconnectStateAdapter() {
 }
 
 export {
+  MUTATION_LOCK_TTL_MS,
   acquireActiveLock,
+  withLock,
+  fenceLock,
+  withActiveLock,
   getDefaultRedisStateAdapterFor,
   getStateAdapter,
   disconnectStateAdapter