@martian-engineering/lossless-claw 0.1.4 → 0.1.6

package/src/tools/lcm-describe-tool.ts

@@ -1,5 +1,9 @@
 import { Type } from "@sinclair/typebox";
 import type { LcmContextEngine } from "../engine.js";
+import {
+  getRuntimeExpansionAuthManager,
+  resolveDelegatedExpansionGrantId,
+} from "../expansion-auth.js";
 import type { LcmDependencies } from "../types.js";
 import type { AnyAgentTool } from "./common.js";
 import { jsonResult } from "./common.js";
@@ -21,8 +25,25 @@ const LcmDescribeSchema = Type.Object({
         "Set true to explicitly allow lookups across all conversations. Ignored when conversationId is provided.",
     }),
   ),
+  tokenCap: Type.Optional(
+    Type.Number({
+      description: "Optional budget cap used for subtree manifest budget-fit annotations.",
+      minimum: 1,
+    }),
+  ),
 });
 
+function normalizeRequestedTokenCap(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  return Math.max(1, Math.trunc(value));
+}
+
+function formatIso(value: Date | null | undefined): string {
+  return value instanceof Date ? value.toISOString() : "-";
+}
+
 export function createLcmDescribeTool(input: {
   deps: LcmDependencies;
   lcm: LcmContextEngine;
@@ -77,33 +98,99 @@ export function createLcmDescribeTool(input: {
 
       if (result.type === "summary" && result.summary) {
         const s = result.summary;
+        const requestedTokenCap = normalizeRequestedTokenCap((params as Record<string, unknown>).tokenCap);
+        const sessionKey =
+          (typeof input.sessionKey === "string" ? input.sessionKey : input.sessionId)?.trim() ?? "";
+        const delegatedGrantId = input.deps.isSubagentSessionKey(sessionKey)
+          ? (resolveDelegatedExpansionGrantId(sessionKey) ?? "")
+          : "";
+        const delegatedRemainingBudget =
+          delegatedGrantId !== ""
+            ? getRuntimeExpansionAuthManager().getRemainingTokenBudget(delegatedGrantId)
+            : null;
+        const defaultTokenCap = Math.max(1, Math.trunc(input.deps.config.maxExpandTokens));
+        const resolvedTokenCap = (() => {
+          const base =
+            requestedTokenCap ??
+            (typeof delegatedRemainingBudget === "number" ? delegatedRemainingBudget : defaultTokenCap);
+          if (typeof delegatedRemainingBudget === "number") {
+            return Math.max(0, Math.min(base, delegatedRemainingBudget));
+          }
+          return Math.max(1, base);
+        })();
+
+        const manifestNodes = s.subtree.map((node) => {
+          const summariesOnlyCost = Math.max(0, node.tokenCount + node.descendantTokenCount);
+          const withMessagesCost = Math.max(0, summariesOnlyCost + node.sourceMessageTokenCount);
+          return {
+            summaryId: node.summaryId,
+            parentSummaryId: node.parentSummaryId,
+            depthFromRoot: node.depthFromRoot,
+            depth: node.depth,
+            kind: node.kind,
+            tokenCount: node.tokenCount,
+            descendantCount: node.descendantCount,
+            descendantTokenCount: node.descendantTokenCount,
+            sourceMessageTokenCount: node.sourceMessageTokenCount,
+            childCount: node.childCount,
+            earliestAt: node.earliestAt,
+            latestAt: node.latestAt,
+            path: node.path,
+            costs: {
+              summariesOnly: summariesOnlyCost,
+              withMessages: withMessagesCost,
+            },
+            budgetFit: {
+              summariesOnly: summariesOnlyCost <= resolvedTokenCap,
+              withMessages: withMessagesCost <= resolvedTokenCap,
+            },
+          };
+        });
+
         const lines: string[] = [];
-        lines.push(`## LCM Summary: ${id}`);
-        lines.push("");
-        lines.push(`**Conversation:** ${s.conversationId}`);
-        lines.push(`**Kind:** ${s.kind}`);
-        lines.push(`**Tokens:** ~${s.tokenCount.toLocaleString()}`);
-        lines.push(`**Created:** ${s.createdAt.toISOString()}`);
+        lines.push(`LCM_SUMMARY ${id}`);
+        lines.push(
+          `meta conv=${s.conversationId} kind=${s.kind} depth=${s.depth} tok=${s.tokenCount} ` +
+            `descTok=${s.descendantTokenCount} srcTok=${s.sourceMessageTokenCount} ` +
+            `desc=${s.descendantCount} range=${formatIso(s.earliestAt)}..${formatIso(s.latestAt)} ` +
+            `budgetCap=${resolvedTokenCap}`,
+        );
         if (s.parentIds.length > 0) {
-          lines.push(`**Parents:** ${s.parentIds.join(", ")}`);
+          lines.push(`parents ${s.parentIds.join(" ")}`);
         }
         if (s.childIds.length > 0) {
-          lines.push(`**Children:** ${s.childIds.join(", ")}`);
-        }
-        if (s.messageIds.length > 0) {
-          lines.push(`**Messages:** ${s.messageIds.length} linked`);
+          lines.push(`children ${s.childIds.join(" ")}`);
         }
-        if (s.fileIds.length > 0) {
-          lines.push(`**Files:** ${s.fileIds.join(", ")}`);
+        lines.push("manifest");
+        for (const node of manifestNodes) {
+          lines.push(
+            `d${node.depthFromRoot} ${node.summaryId} k=${node.kind} tok=${node.tokenCount} ` +
+              `descTok=${node.descendantTokenCount} srcTok=${node.sourceMessageTokenCount} ` +
+              `desc=${node.descendantCount} child=${node.childCount} ` +
+              `range=${formatIso(node.earliestAt)}..${formatIso(node.latestAt)} ` +
+              `cost[s=${node.costs.summariesOnly},m=${node.costs.withMessages}] ` +
+              `budget[s=${node.budgetFit.summariesOnly ? "in" : "over"},` +
+              `m=${node.budgetFit.withMessages ? "in" : "over"}]`,
+          );
         }
-        lines.push("");
-        lines.push("## Content");
-        lines.push("");
+        lines.push("content");
         lines.push(s.content);
 
         return {
           content: [{ type: "text", text: lines.join("\n") }],
-          details: result,
+          details: {
+            ...result,
+            manifest: {
+              tokenCap: resolvedTokenCap,
+              budgetSource:
+                requestedTokenCap != null
+                  ? "request"
+                  : typeof delegatedRemainingBudget === "number"
+                    ? "delegated_grant_remaining"
+                    : "config_default",
+              nodes: manifestNodes,
+            },
+          },
         };
       }
 

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

@@ -12,6 +12,14 @@ import {
   normalizeSummaryIds,
   resolveRequesterConversationScopeId,
 } from "./lcm-expand-tool.delegation.js";
+import {
+  clearDelegatedExpansionContext,
+  evaluateExpansionRecursionGuard,
+  recordExpansionDelegationTelemetry,
+  resolveExpansionRequestId,
+  resolveNextExpansionDepth,
+  stampDelegatedExpansionContext,
+} from "./lcm-expansion-recursion-guard.js";
 
 const DELEGATED_WAIT_TIMEOUT_MS = 120_000;
 const GATEWAY_TIMEOUT_MS = 10_000;
@@ -50,6 +58,13 @@ const LcmExpandQuerySchema = Type.Object({
       minimum: 1,
     }),
   ),
+  tokenCap: Type.Optional(
+    Type.Number({
+      description:
+        "Expansion retrieval token budget across all delegated lcm_expand calls for this query.",
+      minimum: 1,
+    }),
+  ),
 });
 
 type ExpandQueryReply = {
@@ -71,23 +86,40 @@ type SummaryCandidate = {
 function buildDelegatedExpandQueryTask(params: {
   summaryIds: string[];
   conversationId: number;
+  query?: string;
   prompt: string;
   maxTokens: number;
+  tokenCap: number;
+  requestId: string;
+  expansionDepth: number;
+  originSessionKey: string;
 }) {
-  const payload = {
-    summaryIds: params.summaryIds,
-    conversationId: params.conversationId,
-    includeMessages: false,
-  };
+  const seedSummaryIds = params.summaryIds.length > 0 ? params.summaryIds.join(", ") : "(none)";
   return [
-    "Run LCM expansion, then answer the user's prompt from the expanded context.",
+    "You are an autonomous LCM retrieval navigator. Plan and execute retrieval before answering.",
+    "",
+    "Available tools: lcm_describe, lcm_expand, lcm_grep",
+    `Conversation scope: ${params.conversationId}`,
+    `Expansion token budget (total across this run): ${params.tokenCap}`,
+    `Seed summary IDs: ${seedSummaryIds}`,
+    params.query ? `Routing query: ${params.query}` : undefined,
     "",
-    "Step 1: Call `lcm_expand` using exactly this JSON payload:",
-    JSON.stringify(payload, null, 2),
+    "Strategy:",
+    "1. Start with `lcm_describe` on seed summaries to inspect subtree manifests and branch costs.",
+    "2. If additional candidates are needed, use `lcm_grep` scoped to summaries.",
+    "3. Select branches that fit remaining budget; prefer high-signal paths first.",
+    "4. Call `lcm_expand` selectively (do not expand everything blindly).",
+    "5. Keep includeMessages=false by default; use includeMessages=true only for specific leaf evidence.",
+    `6. Stay within ${params.tokenCap} total expansion tokens across all lcm_expand calls.`,
     "",
-    "Step 2: Use the `lcm_expand` result as source context and answer this prompt:",
+    "User prompt to answer:",
     params.prompt,
     "",
+    "Delegated expansion metadata (for tracing):",
+    `- requestId: ${params.requestId}`,
+    `- expansionDepth: ${params.expansionDepth}`,
+    `- originSessionKey: ${params.originSessionKey}`,
+    "",
     "Return ONLY JSON with this shape:",
     "{",
     '  "answer": "string",',
@@ -98,10 +130,13 @@ function buildDelegatedExpandQueryTask(params: {
     "}",
     "",
     "Rules:",
+    "- In delegated context, call `lcm_expand` directly for source retrieval.",
+    "- DO NOT call `lcm_expand_query` from this delegated session.",
+    "- Synthesize the final answer from retrieved evidence, not assumptions.",
     `- Keep answer concise and focused (target <= ${params.maxTokens} tokens).`,
     "- citedIds must be unique summary IDs.",
     "- expandedSummaryCount should reflect how many summaries were expanded/used.",
-    "- totalSourceTokens should be the estimated source token volume from expansion.",
+    "- totalSourceTokens should estimate total tokens consumed from expansion calls.",
     "- truncated should indicate whether source expansion appears truncated.",
   ].join("\n");
 }
@@ -281,6 +316,11 @@ export function createLcmExpandQueryTool(input: {
         typeof requestedMaxTokens === "number" && Number.isFinite(requestedMaxTokens)
           ? Math.max(1, requestedMaxTokens)
           : DEFAULT_MAX_ANSWER_TOKENS;
+      const requestedTokenCap = typeof p.tokenCap === "number" ? Math.trunc(p.tokenCap) : undefined;
+      const expansionTokenCap =
+        typeof requestedTokenCap === "number" && Number.isFinite(requestedTokenCap)
+          ? Math.max(1, requestedTokenCap)
+          : Math.max(1, Math.trunc(input.deps.config.maxExpandTokens));
 
       if (!prompt) {
         return jsonResult({
@@ -294,11 +334,46 @@ export function createLcmExpandQueryTool(input: {
         });
       }
 
-      const requesterSessionKey =
+      const callerSessionKey =
         (typeof input.requesterSessionKey === "string"
           ? input.requesterSessionKey
           : input.sessionId
         )?.trim() ?? "";
+      const requestId = resolveExpansionRequestId(callerSessionKey);
+      const recursionCheck = evaluateExpansionRecursionGuard({
+        sessionKey: callerSessionKey,
+        requestId,
+      });
+      recordExpansionDelegationTelemetry({
+        deps: input.deps,
+        component: "lcm_expand_query",
+        event: "start",
+        requestId,
+        sessionKey: callerSessionKey,
+        expansionDepth: recursionCheck.expansionDepth,
+        originSessionKey: recursionCheck.originSessionKey,
+      });
+      if (recursionCheck.blocked) {
+        recordExpansionDelegationTelemetry({
+          deps: input.deps,
+          component: "lcm_expand_query",
+          event: "block",
+          requestId,
+          sessionKey: callerSessionKey,
+          expansionDepth: recursionCheck.expansionDepth,
+          originSessionKey: recursionCheck.originSessionKey,
+          reason: recursionCheck.reason,
+        });
+        return jsonResult({
+          errorCode: recursionCheck.code,
+          error: recursionCheck.message,
+          requestId: recursionCheck.requestId,
+          expansionDepth: recursionCheck.expansionDepth,
+          originSessionKey: recursionCheck.originSessionKey,
+          reason: recursionCheck.reason,
+        });
+      }
+
       const conversationScope = await resolveLcmConversationScope({
         lcm: input.lcm,
         deps: input.deps,
@@ -310,11 +385,11 @@ export function createLcmExpandQueryTool(input: {
       if (
         !conversationScope.allConversations &&
         scopedConversationId == null &&
-        requesterSessionKey
+        callerSessionKey
       ) {
         scopedConversationId = await resolveRequesterConversationScopeId({
           deps: input.deps,
-          requesterSessionKey,
+          requesterSessionKey: callerSessionKey,
           lcm: input.lcm,
         });
       }
@@ -371,24 +446,38 @@ export function createLcmExpandQueryTool(input: {
         }
 
         const requesterAgentId = input.deps.normalizeAgentId(
-          input.deps.parseAgentSessionKey(requesterSessionKey)?.agentId,
+          input.deps.parseAgentSessionKey(callerSessionKey)?.agentId,
         );
         childSessionKey = `agent:${requesterAgentId}:subagent:${crypto.randomUUID()}`;
+        const childExpansionDepth = resolveNextExpansionDepth(callerSessionKey);
+        const originSessionKey = recursionCheck.originSessionKey || callerSessionKey || "main";
 
         createDelegatedExpansionGrant({
           delegatedSessionKey: childSessionKey,
-          issuerSessionId: requesterSessionKey || "main",
+          issuerSessionId: callerSessionKey || "main",
           allowedConversationIds: [sourceConversationId],
-          tokenCap: input.deps.config.maxExpandTokens,
+          tokenCap: expansionTokenCap,
           ttlMs: DELEGATED_WAIT_TIMEOUT_MS + 30_000,
         });
+        stampDelegatedExpansionContext({
+          sessionKey: childSessionKey,
+          requestId,
+          expansionDepth: childExpansionDepth,
+          originSessionKey,
+          stampedBy: "lcm_expand_query",
+        });
         grantCreated = true;
 
         const task = buildDelegatedExpandQueryTask({
           summaryIds,
           conversationId: sourceConversationId,
+          query: query || undefined,
           prompt,
           maxTokens,
+          tokenCap: expansionTokenCap,
+          requestId,
+          expansionDepth: childExpansionDepth,
+          originSessionKey,
         });
 
         const childIdem = crypto.randomUUID();
@@ -426,6 +515,16 @@ export function createLcmExpandQueryTool(input: {
         })) as { status?: string; error?: string };
         const status = typeof wait?.status === "string" ? wait.status : "error";
         if (status === "timeout") {
+          recordExpansionDelegationTelemetry({
+            deps: input.deps,
+            component: "lcm_expand_query",
+            event: "timeout",
+            requestId,
+            sessionKey: callerSessionKey,
+            expansionDepth: childExpansionDepth,
+            originSessionKey,
+            runId,
+          });
           return jsonResult({
             error: "lcm_expand_query timed out waiting for delegated expansion (120s).",
           });
@@ -448,6 +547,16 @@ export function createLcmExpandQueryTool(input: {
           Array.isArray(replyPayload.messages) ? replyPayload.messages : [],
         );
         const parsed = parseDelegatedExpandQueryReply(reply, summaryIds.length);
+        recordExpansionDelegationTelemetry({
+          deps: input.deps,
+          component: "lcm_expand_query",
+          event: "success",
+          requestId,
+          sessionKey: callerSessionKey,
+          expansionDepth: childExpansionDepth,
+          originSessionKey,
+          runId,
+        });
 
         return jsonResult({
           answer: parsed.answer,
@@ -476,6 +585,9 @@ export function createLcmExpandQueryTool(input: {
         if (grantCreated && childSessionKey) {
           revokeDelegatedExpansionGrantForSession(childSessionKey, { removeBinding: true });
         }
+        if (childSessionKey) {
+          clearDelegatedExpansionContext(childSessionKey);
+        }
       }
     },
   };

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

@@ -5,6 +5,13 @@ import {
   revokeDelegatedExpansionGrantForSession,
 } from "../expansion-auth.js";
 import type { LcmDependencies } from "../types.js";
+import {
+  clearDelegatedExpansionContext,
+  evaluateExpansionRecursionGuard,
+  recordExpansionDelegationTelemetry,
+  resolveExpansionRequestId,
+  stampDelegatedExpansionContext,
+} from "./lcm-expansion-recursion-guard.js";
 
 const MAX_GATEWAY_TIMEOUT_MS = 2_147_483_647;
 
@@ -156,6 +163,9 @@ function buildDelegatedExpansionTask(params: {
   includeMessages: boolean;
   pass: number;
   query?: string;
+  requestId: string;
+  expansionDepth: number;
+  originSessionKey: string;
 }) {
   const payload: {
     summaryIds: string[];
@@ -180,6 +190,11 @@ function buildDelegatedExpansionTask(params: {
     "Call `lcm_expand` using exactly this JSON payload:",
     JSON.stringify(payload, null, 2),
     "",
+    "Delegated expansion metadata (for tracing):",
+    `- requestId: ${params.requestId}`,
+    `- expansionDepth: ${params.expansionDepth}`,
+    `- originSessionKey: ${params.originSessionKey}`,
+    "",
     "Then return ONLY JSON with this shape:",
     "{",
     '  "summary": "string concise findings",',
@@ -190,7 +205,10 @@ function buildDelegatedExpansionTask(params: {
     "}",
     "",
     "Rules:",
+    "- In delegated context, use `lcm_expand` directly for retrieval.",
+    "- DO NOT call `lcm_expand_query` from this delegated session.",
     "- Keep summary concise and factual.",
+    "- Synthesize findings from the `lcm_expand` result before returning.",
     "- citedIds/followUpSummaryIds must contain unique summary IDs only.",
     "- If no follow-up is needed, return an empty followUpSummaryIds array.",
   ]
@@ -240,6 +258,7 @@ async function runDelegatedExpansionPass(params: {
     | "buildSubagentSystemPrompt"
     | "readLatestAssistantReply"
     | "agentLaneSubagent"
+    | "log"
   >;
   requesterSessionKey: string;
   conversationId: number;
@@ -249,6 +268,9 @@ async function runDelegatedExpansionPass(params: {
   includeMessages: boolean;
   query?: string;
   pass: number;
+  requestId: string;
+  parentExpansionDepth: number;
+  originSessionKey: string;
 }): Promise<DelegatedExpansionPassResult> {
   const requesterAgentId = params.deps.normalizeAgentId(
     params.deps.parseAgentSessionKey(params.requesterSessionKey)?.agentId,
@@ -260,8 +282,16 @@ async function runDelegatedExpansionPass(params: {
     delegatedSessionKey: childSessionKey,
     issuerSessionId: params.requesterSessionKey,
     allowedConversationIds: [params.conversationId],
+    tokenCap: params.tokenCap,
     ttlMs: MAX_GATEWAY_TIMEOUT_MS,
   });
+  stampDelegatedExpansionContext({
+    sessionKey: childSessionKey,
+    requestId: params.requestId,
+    expansionDepth: params.parentExpansionDepth + 1,
+    originSessionKey: params.originSessionKey,
+    stampedBy: "runDelegatedExpansionLoop",
+  });
 
   try {
     const message = buildDelegatedExpansionTask({
@@ -272,6 +302,9 @@ async function runDelegatedExpansionPass(params: {
       includeMessages: params.includeMessages,
       pass: params.pass,
       query: params.query,
+      requestId: params.requestId,
+      expansionDepth: params.parentExpansionDepth + 1,
+      originSessionKey: params.originSessionKey,
     });
     const response = (await params.deps.callGateway({
       method: "agent",
@@ -374,6 +407,7 @@ async function runDelegatedExpansionPass(params: {
       // Cleanup is best-effort.
     }
     revokeDelegatedExpansionGrantForSession(childSessionKey, { removeBinding: true });
+    clearDelegatedExpansionContext(childSessionKey);
   }
 }
 
@@ -386,6 +420,7 @@ export async function runDelegatedExpansionLoop(params: {
     | "buildSubagentSystemPrompt"
     | "readLatestAssistantReply"
     | "agentLaneSubagent"
+    | "log"
   >;
   requesterSessionKey: string;
   conversationId: number;
@@ -394,7 +429,44 @@ export async function runDelegatedExpansionLoop(params: {
   tokenCap?: number;
   includeMessages: boolean;
   query?: string;
+  requestId?: string;
 }): Promise<DelegatedExpansionLoopResult> {
+  const requestId = params.requestId?.trim() || resolveExpansionRequestId(params.requesterSessionKey);
+  const recursionCheck = evaluateExpansionRecursionGuard({
+    sessionKey: params.requesterSessionKey,
+    requestId,
+  });
+  recordExpansionDelegationTelemetry({
+    deps: params.deps,
+    component: "runDelegatedExpansionLoop",
+    event: "start",
+    requestId,
+    sessionKey: params.requesterSessionKey,
+    expansionDepth: recursionCheck.expansionDepth,
+    originSessionKey: recursionCheck.originSessionKey,
+  });
+  if (recursionCheck.blocked) {
+    recordExpansionDelegationTelemetry({
+      deps: params.deps,
+      component: "runDelegatedExpansionLoop",
+      event: "block",
+      requestId,
+      sessionKey: params.requesterSessionKey,
+      expansionDepth: recursionCheck.expansionDepth,
+      originSessionKey: recursionCheck.originSessionKey,
+      reason: recursionCheck.reason,
+    });
+    return {
+      status: "error",
+      passes: [],
+      citedIds: [],
+      totalTokens: 0,
+      truncated: true,
+      text: "Delegated expansion blocked by recursion guard.",
+      error: recursionCheck.message,
+    };
+  }
+
   const passes: DelegatedExpansionPassResult[] = [];
   const visited = new Set<string>();
   const cited = new Set<string>();
@@ -415,10 +487,25 @@ export async function runDelegatedExpansionLoop(params: {
       includeMessages: params.includeMessages,
       query: params.query,
       pass,
+      requestId,
+      parentExpansionDepth: recursionCheck.expansionDepth,
+      originSessionKey: recursionCheck.originSessionKey,
     });
     passes.push(result);
 
     if (result.status !== "ok") {
+      if (result.status === "timeout") {
+        recordExpansionDelegationTelemetry({
+          deps: params.deps,
+          component: "runDelegatedExpansionLoop",
+          event: "timeout",
+          requestId,
+          sessionKey: params.requesterSessionKey,
+          expansionDepth: recursionCheck.expansionDepth,
+          originSessionKey: recursionCheck.originSessionKey,
+          runId: result.runId,
+        });
+      }
       const okPasses = passes.filter((entry) => entry.status === "ok");
       for (const okPass of okPasses) {
         for (const summaryId of okPass.citedIds) {
@@ -449,6 +536,15 @@ export async function runDelegatedExpansionLoop(params: {
     pass += 1;
   }
 
+  recordExpansionDelegationTelemetry({
+    deps: params.deps,
+    component: "runDelegatedExpansionLoop",
+    event: "success",
+    requestId,
+    sessionKey: params.requesterSessionKey,
+    expansionDepth: recursionCheck.expansionDepth,
+    originSessionKey: recursionCheck.originSessionKey,
+  });
   return {
     status: "ok",
     passes,