@martian-engineering/lossless-claw 0.5.3 → 0.6.0

package/src/tools/lcm-expand-query-tool.ts

@@ -13,9 +13,11 @@ import {
   resolveRequesterConversationScopeId,
 } from "./lcm-expand-tool.delegation.js";
 import {
+  acquireExpansionConcurrencySlot,
   clearDelegatedExpansionContext,
   evaluateExpansionRecursionGuard,
   recordExpansionDelegationTelemetry,
+  releaseExpansionConcurrencySlot,
   resolveExpansionRequestId,
   resolveNextExpansionDepth,
   stampDelegatedExpansionContext,
@@ -531,34 +533,36 @@ export function createLcmExpandQueryTool(input: {
         });
       }
 
-      const conversationScope = await resolveLcmConversationScope({
-        lcm: input.lcm,
-        deps: input.deps,
-        sessionId: input.sessionId,
-        sessionKey: input.sessionKey,
-        params: p,
-      });
-      let scopedConversationId = conversationScope.conversationId;
-      if (
-        !conversationScope.allConversations &&
-        scopedConversationId == null &&
-        callerSessionKey
-      ) {
-        scopedConversationId = await resolveRequesterConversationScopeId({
-          deps: input.deps,
-          requesterSessionKey: callerSessionKey,
+      const originSessionKey = recursionCheck.originSessionKey || callerSessionKey || "main";
+
+      try {
+        const conversationScope = await resolveLcmConversationScope({
           lcm: input.lcm,
+          deps: input.deps,
+          sessionId: input.sessionId,
+          sessionKey: input.sessionKey,
+          params: p,
         });
-      }
+        let scopedConversationId = conversationScope.conversationId;
+        if (
+          !conversationScope.allConversations &&
+          scopedConversationId == null &&
+          callerSessionKey
+        ) {
+          scopedConversationId = await resolveRequesterConversationScopeId({
+            deps: input.deps,
+            requesterSessionKey: callerSessionKey,
+            lcm: input.lcm,
+          });
+        }
 
-      if (!conversationScope.allConversations && scopedConversationId == null) {
-        return jsonResult({
-          error:
-            "No LCM conversation found for this session. Provide conversationId or set allConversations=true.",
-        });
-      }
+        if (!conversationScope.allConversations && scopedConversationId == null) {
+          return jsonResult({
+            error:
+              "No LCM conversation found for this session. Provide conversationId or set allConversations=true.",
+          });
+        }
 
-      try {
         const candidates = await resolveSummaryCandidates({
           lcm: input.lcm,
           explicitSummaryIds,
@@ -608,11 +612,35 @@ export function createLcmExpandQueryTool(input: {
           });
         }
 
+        const concurrencyCheck = acquireExpansionConcurrencySlot({
+          originSessionKey,
+          requestId,
+        });
+        if (concurrencyCheck.blocked) {
+          recordExpansionDelegationTelemetry({
+            deps: input.deps,
+            component: "lcm_expand_query",
+            event: "block",
+            requestId,
+            sessionKey: callerSessionKey,
+            expansionDepth: recursionCheck.expansionDepth,
+            originSessionKey: concurrencyCheck.originSessionKey,
+            reason: concurrencyCheck.reason,
+          });
+          return jsonResult({
+            errorCode: concurrencyCheck.code,
+            error: concurrencyCheck.message,
+            requestId: concurrencyCheck.requestId,
+            expansionDepth: recursionCheck.expansionDepth,
+            originSessionKey: concurrencyCheck.originSessionKey,
+            reason: concurrencyCheck.reason,
+          });
+        }
+
         const requesterAgentId = input.deps.normalizeAgentId(
           input.deps.parseAgentSessionKey(callerSessionKey)?.agentId,
         );
         const childExpansionDepth = resolveNextExpansionDepth(callerSessionKey);
-        const originSessionKey = recursionCheck.originSessionKey || callerSessionKey || "main";
 
         const task = buildDelegatedExpandQueryTask({
           summaryIds,
@@ -787,6 +815,11 @@ export function createLcmExpandQueryTool(input: {
         return jsonResult({
           error: failure,
         });
+      } finally {
+        releaseExpansionConcurrencySlot({
+          originSessionKey,
+          requestId,
+        });
       }
     },
   };

package/src/tools/lcm-expansion-recursion-guard.ts

@@ -3,6 +3,7 @@ import { resolveDelegatedExpansionGrantId } from "../expansion-auth.js";
 import type { LcmDependencies } from "../types.js";
 
 export const EXPANSION_RECURSION_ERROR_CODE = "EXPANSION_RECURSION_BLOCKED";
+export const EXPANSION_CONCURRENCY_ERROR_CODE = "EXPANSION_CONCURRENCY_BLOCKED";
 const EXPANSION_DELEGATION_DEPTH_CAP = 1;
 
 type TelemetryEvent = "start" | "block" | "timeout" | "success";
@@ -23,6 +24,7 @@ export type DelegatedExpansionContext = {
 };
 
 export type ExpansionRecursionBlockReason = "depth_cap" | "idempotent_reentry";
+export type ExpansionConcurrencyBlockReason = "origin_session_in_flight";
 
 export type ExpansionRecursionGuardDecision =
   | {
@@ -41,8 +43,24 @@ export type ExpansionRecursionGuardDecision =
       originSessionKey: string;
     };
 
+export type ExpansionConcurrencyGuardDecision =
+  | {
+      blocked: false;
+      requestId: string;
+      originSessionKey: string;
+    }
+  | {
+      blocked: true;
+      code: typeof EXPANSION_CONCURRENCY_ERROR_CODE;
+      reason: ExpansionConcurrencyBlockReason;
+      message: string;
+      requestId: string;
+      originSessionKey: string;
+    };
+
 const delegatedContextBySessionKey = new Map<string, DelegatedExpansionContext>();
 const blockedRequestIdsBySessionKey = new Map<string, Set<string>>();
+const activeRequestIdByOriginSessionKey = new Map<string, string>();
 
 function normalizeSessionKey(sessionKey?: string): string {
   return typeof sessionKey === "string" ? sessionKey.trim() : "";
@@ -90,6 +108,14 @@ function buildExpansionRecursionRecoveryGuidance(originSessionKey: string): stri
   );
 }
 
+function buildExpansionConcurrencyRecoveryGuidance(originSessionKey: string): string {
+  return (
+    "Recovery: Wait for the active expansion to finish before retrying. " +
+    `If you need an immediate fallback, stay in the origin session (${originSessionKey}) ` +
+    "and use `lcm_grep` or `lcm_describe` instead."
+  );
+}
+
 /**
  * Create a stable request identifier for delegated expansion orchestration.
  */
@@ -213,6 +239,66 @@ export function evaluateExpansionRecursionGuard(params: {
   };
 }
 
+/**
+ * Acquire the single active delegated-expansion slot for an origin session.
+ * A second concurrent caller from the same origin session is blocked
+ * immediately so sub-agents do not deadlock on a shared lane.
+ */
+export function acquireExpansionConcurrencySlot(params: {
+  originSessionKey?: string;
+  requestId: string;
+}): ExpansionConcurrencyGuardDecision {
+  const originSessionKey = normalizeSessionKey(params.originSessionKey) || "main";
+  const requestId = params.requestId.trim();
+  const activeRequestId = activeRequestIdByOriginSessionKey.get(originSessionKey);
+
+  if (activeRequestId && activeRequestId !== requestId) {
+    return {
+      blocked: true,
+      code: EXPANSION_CONCURRENCY_ERROR_CODE,
+      reason: "origin_session_in_flight",
+      message:
+        `${EXPANSION_CONCURRENCY_ERROR_CODE}: Another lcm_expand_query delegation is already ` +
+        `in flight for origin session (${originSessionKey}; activeRequestId=${activeRequestId}). ` +
+        buildExpansionConcurrencyRecoveryGuidance(originSessionKey),
+      requestId,
+      originSessionKey,
+    };
+  }
+
+  if (!activeRequestId) {
+    activeRequestIdByOriginSessionKey.set(originSessionKey, requestId);
+  }
+
+  return {
+    blocked: false,
+    requestId,
+    originSessionKey,
+  };
+}
+
+/**
+ * Release the active delegated-expansion slot for an origin session.
+ */
+export function releaseExpansionConcurrencySlot(params: {
+  originSessionKey?: string;
+  requestId?: string;
+}): void {
+  const originSessionKey = normalizeSessionKey(params.originSessionKey);
+  if (!originSessionKey) {
+    return;
+  }
+  const activeRequestId = activeRequestIdByOriginSessionKey.get(originSessionKey);
+  if (!activeRequestId) {
+    return;
+  }
+  const requestId = params.requestId?.trim();
+  if (requestId && activeRequestId !== requestId) {
+    return;
+  }
+  activeRequestIdByOriginSessionKey.delete(originSessionKey);
+}
+
 /**
  * Emit structured delegated expansion telemetry with monotonic counters.
  */
@@ -279,6 +365,7 @@ export function getExpansionDelegationTelemetrySnapshotForTests(): Record<Teleme
 export function resetExpansionDelegationGuardForTests(): void {
   delegatedContextBySessionKey.clear();
   blockedRequestIdsBySessionKey.clear();
+  activeRequestIdByOriginSessionKey.clear();
   telemetryCounters.start = 0;
   telemetryCounters.block = 0;
   telemetryCounters.timeout = 0;