@jonathangu/openclawbrain 0.3.0

package/src/expansion-auth.ts

@@ -0,0 +1,351 @@
+import type { ExpansionOrchestrator, ExpansionRequest, ExpansionResult } from "./expansion.js";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type ExpansionGrant = {
+  /** Unique grant ID */
+  grantId: string;
+  /** Session ID that issued the grant */
+  issuerSessionId: string;
+  /** Conversation IDs the grantee is allowed to traverse */
+  allowedConversationIds: number[];
+  /** Specific summary IDs the grantee is allowed to expand (if empty, all within conversation are allowed) */
+  allowedSummaryIds: string[];
+  /** Maximum traversal depth */
+  maxDepth: number;
+  /** Maximum tokens the grantee can retrieve */
+  tokenCap: number;
+  /** When the grant expires */
+  expiresAt: Date;
+  /** Whether this grant has been revoked */
+  revoked: boolean;
+  /** Creation timestamp */
+  createdAt: Date;
+};
+
+export type CreateGrantInput = {
+  issuerSessionId: string;
+  allowedConversationIds: number[];
+  allowedSummaryIds?: string[];
+  maxDepth?: number;
+  tokenCap?: number;
+  /** TTL in milliseconds (default: 5 minutes) */
+  ttlMs?: number;
+};
+
+export type CreateDelegatedExpansionGrantInput = CreateGrantInput & {
+  delegatedSessionKey: string;
+};
+
+export type ValidationResult = {
+  valid: boolean;
+  reason?: string;
+};
+
+export type AuthorizedExpansionOrchestrator = {
+  expand(grantId: string, request: ExpansionRequest): Promise<ExpansionResult>;
+};
+
+// ── Defaults ─────────────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_DEPTH = 3;
+const DEFAULT_TOKEN_CAP = 4000;
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+// ── ExpansionAuthManager ─────────────────────────────────────────────────────
+
+export class ExpansionAuthManager {
+  private grants: Map<string, ExpansionGrant> = new Map();
+  private consumedTokensByGrantId: Map<string, number> = new Map();
+
+  /**
+   * Create a new expansion grant with the given parameters.
+   * Generates a unique grant ID and applies defaults for optional fields.
+   */
+  createGrant(input: CreateGrantInput): ExpansionGrant {
+    const grantId = "grant_" + crypto.randomUUID().slice(0, 12);
+    const now = new Date();
+    const ttlMs = input.ttlMs ?? DEFAULT_TTL_MS;
+
+    const grant: ExpansionGrant = {
+      grantId,
+      issuerSessionId: input.issuerSessionId,
+      allowedConversationIds: input.allowedConversationIds,
+      allowedSummaryIds: input.allowedSummaryIds ?? [],
+      maxDepth: input.maxDepth ?? DEFAULT_MAX_DEPTH,
+      tokenCap: input.tokenCap ?? DEFAULT_TOKEN_CAP,
+      expiresAt: new Date(now.getTime() + ttlMs),
+      revoked: false,
+      createdAt: now,
+    };
+
+    this.grants.set(grantId, grant);
+    this.consumedTokensByGrantId.set(grantId, 0);
+    return grant;
+  }
+
+  /**
+   * Retrieve a grant by ID. Returns null if the grant does not exist,
+   * has been revoked, or has expired.
+   */
+  getGrant(grantId: string): ExpansionGrant | null {
+    const grant = this.grants.get(grantId);
+    if (!grant) {
+      return null;
+    }
+    if (grant.revoked) {
+      return null;
+    }
+    if (grant.expiresAt.getTime() <= Date.now()) {
+      return null;
+    }
+    return grant;
+  }
+
+  /**
+   * Revoke a grant, preventing any further use.
+   * Returns true if the grant was found and revoked, false if not found.
+   */
+  revokeGrant(grantId: string): boolean {
+    const grant = this.grants.get(grantId);
+    if (!grant) {
+      return false;
+    }
+    grant.revoked = true;
+    return true;
+  }
+
+  /**
+   * Resolve remaining token budget for an active grant.
+   */
+  getRemainingTokenBudget(grantId: string): number | null {
+    const grant = this.getGrant(grantId);
+    if (!grant) {
+      return null;
+    }
+    const consumed = Math.max(0, this.consumedTokensByGrantId.get(grantId) ?? 0);
+    return Math.max(0, Math.floor(grant.tokenCap) - consumed);
+  }
+
+  /**
+   * Consume token budget for a grant, clamped to the grant token cap.
+   */
+  consumeTokenBudget(grantId: string, consumedTokens: number): number | null {
+    const grant = this.getGrant(grantId);
+    if (!grant) {
+      return null;
+    }
+    const safeConsumed =
+      typeof consumedTokens === "number" && Number.isFinite(consumedTokens)
+        ? Math.max(0, Math.floor(consumedTokens))
+        : 0;
+    const previous = Math.max(0, this.consumedTokensByGrantId.get(grantId) ?? 0);
+    const next = Math.min(Math.max(1, Math.floor(grant.tokenCap)), previous + safeConsumed);
+    this.consumedTokensByGrantId.set(grantId, next);
+    return Math.max(0, Math.floor(grant.tokenCap) - next);
+  }
+
+  /**
+   * Validate an expansion request against a grant.
+   * Checks existence, expiry, revocation, conversation scope, and summary scope.
+   */
+  validateExpansion(
+    grantId: string,
+    request: {
+      conversationId: number;
+      summaryIds: string[];
+      depth: number;
+      tokenCap: number;
+    },
+  ): ValidationResult {
+    const grant = this.grants.get(grantId);
+
+    // 1. Grant must exist
+    if (!grant) {
+      return { valid: false, reason: "Grant not found" };
+    }
+
+    // 2. Grant must not be revoked
+    if (grant.revoked) {
+      return { valid: false, reason: "Grant has been revoked" };
+    }
+
+    // 3. Grant must not be expired
+    if (grant.expiresAt.getTime() <= Date.now()) {
+      return { valid: false, reason: "Grant has expired" };
+    }
+
+    // 4. Conversation ID must be in the allowed set
+    if (!grant.allowedConversationIds.includes(request.conversationId)) {
+      return {
+        valid: false,
+        reason: `Conversation ${request.conversationId} is not in the allowed set`,
+      };
+    }
+
+    // 5. If allowedSummaryIds is non-empty, all requested summaryIds must be allowed
+    if (grant.allowedSummaryIds.length > 0) {
+      const allowedSet = new Set(grant.allowedSummaryIds);
+      const unauthorized = request.summaryIds.filter((id) => !allowedSet.has(id));
+      if (unauthorized.length > 0) {
+        return {
+          valid: false,
+          reason: `Summary IDs not authorized: ${unauthorized.join(", ")}`,
+        };
+      }
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Remove all expired and revoked grants from the store.
+   * Returns the number of grants removed.
+   */
+  cleanup(): number {
+    const now = Date.now();
+    let removed = 0;
+
+    for (const [grantId, grant] of this.grants) {
+      if (grant.revoked || grant.expiresAt.getTime() <= now) {
+        this.grants.delete(grantId);
+        this.consumedTokensByGrantId.delete(grantId);
+        removed++;
+      }
+    }
+
+    return removed;
+  }
+}
+
+const runtimeExpansionAuthManager = new ExpansionAuthManager();
+const delegatedSessionGrantIds = new Map<string, string>();
+
+/**
+ * Return the singleton auth manager used by runtime delegated expansion flows.
+ */
+export function getRuntimeExpansionAuthManager(): ExpansionAuthManager {
+  return runtimeExpansionAuthManager;
+}
+
+/**
+ * Create a delegated expansion grant and bind it to the child session key.
+ */
+export function createDelegatedExpansionGrant(
+  input: CreateDelegatedExpansionGrantInput,
+): ExpansionGrant {
+  const delegatedSessionKey = input.delegatedSessionKey.trim();
+  if (!delegatedSessionKey) {
+    throw new Error("delegatedSessionKey is required for delegated expansion grants");
+  }
+
+  const grant = runtimeExpansionAuthManager.createGrant({
+    issuerSessionId: input.issuerSessionId,
+    allowedConversationIds: input.allowedConversationIds,
+    allowedSummaryIds: input.allowedSummaryIds,
+    maxDepth: input.maxDepth,
+    tokenCap: input.tokenCap,
+    ttlMs: input.ttlMs,
+  });
+  delegatedSessionGrantIds.set(delegatedSessionKey, grant.grantId);
+  return grant;
+}
+
+/**
+ * Resolve the delegated expansion grant id bound to a session key.
+ */
+export function resolveDelegatedExpansionGrantId(sessionKey: string): string | null {
+  const key = sessionKey.trim();
+  if (!key) {
+    return null;
+  }
+  return delegatedSessionGrantIds.get(key) ?? null;
+}
+
+/**
+ * Revoke the delegated grant bound to a session key.
+ * Optionally remove the binding after revocation.
+ */
+export function revokeDelegatedExpansionGrantForSession(
+  sessionKey: string,
+  opts?: { removeBinding?: boolean },
+): boolean {
+  const key = sessionKey.trim();
+  if (!key) {
+    return false;
+  }
+  const grantId = delegatedSessionGrantIds.get(key);
+  if (!grantId) {
+    return false;
+  }
+  const didRevoke = runtimeExpansionAuthManager.revokeGrant(grantId);
+  if (opts?.removeBinding) {
+    delegatedSessionGrantIds.delete(key);
+  }
+  return didRevoke;
+}
+
+/**
+ * Remove delegated grant binding for a session key without revoking.
+ */
+export function removeDelegatedExpansionGrantForSession(sessionKey: string): boolean {
+  const key = sessionKey.trim();
+  if (!key) {
+    return false;
+  }
+  return delegatedSessionGrantIds.delete(key);
+}
+
+/**
+ * Test-only reset helper for delegated runtime grants.
+ */
+export function resetDelegatedExpansionGrantsForTests(): void {
+  delegatedSessionGrantIds.clear();
+}
+
+// ── Authorized wrapper ───────────────────────────────────────────────────────
+
+/**
+ * Create a thin authorization wrapper around an ExpansionOrchestrator.
+ * The wrapper validates the grant before delegating to the underlying
+ * orchestrator.
+ */
+export function wrapWithAuth(
+  orchestrator: ExpansionOrchestrator,
+  authManager: ExpansionAuthManager,
+): AuthorizedExpansionOrchestrator {
+  return {
+    async expand(grantId: string, request: ExpansionRequest): Promise<ExpansionResult> {
+      const validation = authManager.validateExpansion(grantId, {
+        conversationId: request.conversationId,
+        summaryIds: request.summaryIds,
+        depth: request.maxDepth ?? DEFAULT_MAX_DEPTH,
+        tokenCap: request.tokenCap ?? DEFAULT_TOKEN_CAP,
+      });
+
+      if (!validation.valid) {
+        throw new Error(`Expansion authorization failed: ${validation.reason}`);
+      }
+
+      const remainingBudget = authManager.getRemainingTokenBudget(grantId);
+      if (remainingBudget == null) {
+        throw new Error("Expansion authorization failed: Grant not found");
+      }
+      if (remainingBudget <= 0) {
+        throw new Error("Expansion authorization failed: Grant token budget exhausted");
+      }
+
+      const requestedTokenCap =
+        typeof request.tokenCap === "number" && Number.isFinite(request.tokenCap)
+          ? Math.max(1, Math.trunc(request.tokenCap))
+          : remainingBudget;
+      const effectiveTokenCap = Math.max(1, Math.min(requestedTokenCap, remainingBudget));
+      const result = await orchestrator.expand({
+        ...request,
+        tokenCap: effectiveTokenCap,
+      });
+      authManager.consumeTokenBudget(grantId, result.totalTokens);
+      return result;
+    },
+  };
+}

package/src/expansion-policy.ts

@@ -0,0 +1,303 @@
+export type LcmExpansionRoutingIntent = "query_probe" | "explicit_expand";
+
+export type LcmExpansionRoutingAction = "answer_directly" | "expand_shallow" | "delegate_traversal";
+
+export type LcmExpansionTokenRiskLevel = "low" | "moderate" | "high";
+
+export type LcmExpansionRoutingInput = {
+  intent: LcmExpansionRoutingIntent;
+  query?: string;
+  requestedMaxDepth?: number;
+  candidateSummaryCount: number;
+  tokenCap: number;
+  includeMessages?: boolean;
+};
+
+export type LcmExpansionRoutingDecision = {
+  action: LcmExpansionRoutingAction;
+  normalizedMaxDepth: number;
+  candidateSummaryCount: number;
+  estimatedTokens: number;
+  tokenCap: number;
+  tokenRiskRatio: number;
+  tokenRiskLevel: LcmExpansionTokenRiskLevel;
+  indicators: {
+    broadTimeRange: boolean;
+    multiHopRetrieval: boolean;
+  };
+  triggers: {
+    directByNoCandidates: boolean;
+    directByLowComplexityProbe: boolean;
+    delegateByDepth: boolean;
+    delegateByCandidateCount: boolean;
+    delegateByTokenRisk: boolean;
+    delegateByBroadTimeRangeAndMultiHop: boolean;
+  };
+  reasons: string[];
+};
+
+export const EXPANSION_ROUTING_THRESHOLDS = {
+  defaultDepth: 3,
+  minDepth: 1,
+  maxDepth: 10,
+  directMaxDepth: 2,
+  directMaxCandidates: 1,
+  moderateTokenRiskRatio: 0.35,
+  highTokenRiskRatio: 0.7,
+  baseTokensPerSummary: 220,
+  includeMessagesTokenMultiplier: 1.9,
+  perDepthTokenGrowth: 0.65,
+  broadTimeRangeTokenMultiplier: 1.35,
+  multiHopTokenMultiplier: 1.25,
+  multiHopDepthThreshold: 3,
+  multiHopCandidateThreshold: 5,
+} as const;
+
+const BROAD_TIME_RANGE_PATTERNS = [
+  /\b(last|past)\s+(month|months|quarter|quarters|year|years)\b/i,
+  /\b(over|across|throughout)\s+(time|months|quarters|years)\b/i,
+  /\b(timeline|chronology|history|long[-\s]?term)\b/i,
+  /\bbetween\s+[^.]{0,40}\s+and\s+[^.]{0,40}\b/i,
+];
+
+const MULTI_HOP_QUERY_PATTERNS = [
+  /\b(root\s+cause|causal\s+chain|chain\s+of\s+events)\b/i,
+  /\b(multi[-\s]?hop|multi[-\s]?step|cross[-\s]?summary)\b/i,
+  /\bhow\s+did\b.+\blead\s+to\b/i,
+];
+
+/** Normalize a requested depth to a deterministic bounded value. */
+function normalizeDepth(requestedMaxDepth?: number): number {
+  if (typeof requestedMaxDepth !== "number" || !Number.isFinite(requestedMaxDepth)) {
+    return EXPANSION_ROUTING_THRESHOLDS.defaultDepth;
+  }
+  const rounded = Math.trunc(requestedMaxDepth);
+  return Math.max(
+    EXPANSION_ROUTING_THRESHOLDS.minDepth,
+    Math.min(EXPANSION_ROUTING_THRESHOLDS.maxDepth, rounded),
+  );
+}
+
+/** Normalize token cap to a positive bounded value for risk computation. */
+function normalizeTokenCap(tokenCap: number): number {
+  if (!Number.isFinite(tokenCap)) {
+    return Number.MAX_SAFE_INTEGER;
+  }
+  return Math.max(1, Math.trunc(tokenCap));
+}
+
+/**
+ * Detect broad time-range intent from the user query.
+ *
+ * This is a deterministic text heuristic used by orchestration policy only;
+ * it does not perform retrieval.
+ */
+export function detectBroadTimeRangeIndicator(query?: string): boolean {
+  if (!query) {
+    return false;
+  }
+  const trimmed = query.trim();
+  if (!trimmed) {
+    return false;
+  }
+
+  if (BROAD_TIME_RANGE_PATTERNS.some((pattern) => pattern.test(trimmed))) {
+    return true;
+  }
+
+  const years = Array.from(trimmed.matchAll(/\b(?:19|20)\d{2}\b/g), (match) => Number(match[0]));
+  if (years.length < 2) {
+    return false;
+  }
+
+  const earliest = Math.min(...years);
+  const latest = Math.max(...years);
+  return latest - earliest >= 2;
+}
+
+/**
+ * Detect whether traversal likely requires multi-hop expansion.
+ *
+ * Multi-hop is inferred from depth, breadth, and explicit language in the query.
+ */
+export function detectMultiHopIndicator(input: {
+  query?: string;
+  requestedMaxDepth?: number;
+  candidateSummaryCount: number;
+}): boolean {
+  const normalizedMaxDepth = normalizeDepth(input.requestedMaxDepth);
+  const candidateSummaryCount = Math.max(0, Math.trunc(input.candidateSummaryCount));
+
+  if (normalizedMaxDepth >= EXPANSION_ROUTING_THRESHOLDS.multiHopDepthThreshold) {
+    return true;
+  }
+  if (candidateSummaryCount >= EXPANSION_ROUTING_THRESHOLDS.multiHopCandidateThreshold) {
+    return true;
+  }
+  if (!input.query) {
+    return false;
+  }
+
+  const trimmed = input.query.trim();
+  if (!trimmed) {
+    return false;
+  }
+  return MULTI_HOP_QUERY_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+
+/**
+ * Estimate expansion token volume from traversal characteristics.
+ *
+ * This deterministic estimate intentionally over-approximates near deep/broad
+ * traversals so delegation triggers before hitting hard runtime caps.
+ */
+export function estimateExpansionTokens(input: {
+  requestedMaxDepth?: number;
+  candidateSummaryCount: number;
+  includeMessages?: boolean;
+  broadTimeRangeIndicator?: boolean;
+  multiHopIndicator?: boolean;
+}): number {
+  const normalizedMaxDepth = normalizeDepth(input.requestedMaxDepth);
+  const candidateSummaryCount = Math.max(0, Math.trunc(input.candidateSummaryCount));
+  if (candidateSummaryCount === 0) {
+    return 0;
+  }
+
+  const includeMessagesMultiplier = input.includeMessages
+    ? EXPANSION_ROUTING_THRESHOLDS.includeMessagesTokenMultiplier
+    : 1;
+  const depthMultiplier =
+    1 + (normalizedMaxDepth - 1) * EXPANSION_ROUTING_THRESHOLDS.perDepthTokenGrowth;
+  const timeRangeMultiplier = input.broadTimeRangeIndicator
+    ? EXPANSION_ROUTING_THRESHOLDS.broadTimeRangeTokenMultiplier
+    : 1;
+  const multiHopMultiplier = input.multiHopIndicator
+    ? EXPANSION_ROUTING_THRESHOLDS.multiHopTokenMultiplier
+    : 1;
+
+  const perSummaryEstimate =
+    EXPANSION_ROUTING_THRESHOLDS.baseTokensPerSummary *
+    includeMessagesMultiplier *
+    depthMultiplier *
+    timeRangeMultiplier *
+    multiHopMultiplier;
+
+  return Math.max(0, Math.ceil(perSummaryEstimate * candidateSummaryCount));
+}
+
+/** Classify token risk level relative to a provided cap. */
+export function classifyExpansionTokenRisk(input: { estimatedTokens: number; tokenCap: number }): {
+  ratio: number;
+  level: LcmExpansionTokenRiskLevel;
+} {
+  const estimatedTokens = Math.max(0, Math.trunc(input.estimatedTokens));
+  const tokenCap = normalizeTokenCap(input.tokenCap);
+  const ratio = estimatedTokens / tokenCap;
+
+  if (ratio >= EXPANSION_ROUTING_THRESHOLDS.highTokenRiskRatio) {
+    return { ratio, level: "high" };
+  }
+  if (ratio >= EXPANSION_ROUTING_THRESHOLDS.moderateTokenRiskRatio) {
+    return { ratio, level: "moderate" };
+  }
+  return { ratio, level: "low" };
+}
+
+/**
+ * Decide deterministic route-vs-delegate policy for LCM expansion orchestration.
+ *
+ * The decision matrix supports three outcomes:
+ * - answer directly (skip expansion)
+ * - do shallow/direct expansion
+ * - delegate deep traversal to a sub-agent
+ */
+export function decideLcmExpansionRouting(
+  input: LcmExpansionRoutingInput,
+): LcmExpansionRoutingDecision {
+  const normalizedMaxDepth = normalizeDepth(input.requestedMaxDepth);
+  const candidateSummaryCount = Math.max(0, Math.trunc(input.candidateSummaryCount));
+  const tokenCap = normalizeTokenCap(input.tokenCap);
+  const broadTimeRange = detectBroadTimeRangeIndicator(input.query);
+  const multiHopRetrieval = detectMultiHopIndicator({
+    query: input.query,
+    requestedMaxDepth: normalizedMaxDepth,
+    candidateSummaryCount,
+  });
+  const estimatedTokens = estimateExpansionTokens({
+    requestedMaxDepth: normalizedMaxDepth,
+    candidateSummaryCount,
+    includeMessages: input.includeMessages,
+    broadTimeRangeIndicator: broadTimeRange,
+    multiHopIndicator: multiHopRetrieval,
+  });
+  const tokenRisk = classifyExpansionTokenRisk({ estimatedTokens, tokenCap });
+
+  const directByNoCandidates = candidateSummaryCount === 0;
+  const directByLowComplexityProbe =
+    input.intent === "query_probe" &&
+    !directByNoCandidates &&
+    normalizedMaxDepth <= EXPANSION_ROUTING_THRESHOLDS.directMaxDepth &&
+    candidateSummaryCount <= EXPANSION_ROUTING_THRESHOLDS.directMaxCandidates &&
+    tokenRisk.level === "low" &&
+    !broadTimeRange &&
+    !multiHopRetrieval;
+
+  const delegateByDepth = false;
+  const delegateByCandidateCount = false;
+  const delegateByTokenRisk = tokenRisk.level === "high";
+  const delegateByBroadTimeRangeAndMultiHop = broadTimeRange && multiHopRetrieval;
+
+  const shouldDirect = directByNoCandidates || directByLowComplexityProbe;
+  const shouldDelegate =
+    !shouldDirect && (delegateByTokenRisk || delegateByBroadTimeRangeAndMultiHop);
+
+  const action: LcmExpansionRoutingAction = shouldDirect
+    ? "answer_directly"
+    : shouldDelegate
+      ? "delegate_traversal"
+      : "expand_shallow";
+
+  const reasons: string[] = [];
+  if (directByNoCandidates) {
+    reasons.push("No candidate summary IDs are available.");
+  }
+  if (directByLowComplexityProbe) {
+    reasons.push("Query probe is low complexity and below retrieval-risk thresholds.");
+  }
+  if (delegateByTokenRisk) {
+    reasons.push(
+      `Estimated token risk ratio ${tokenRisk.ratio.toFixed(2)} meets delegate threshold ` +
+        `${EXPANSION_ROUTING_THRESHOLDS.highTokenRiskRatio.toFixed(2)}.`,
+    );
+  }
+  if (delegateByBroadTimeRangeAndMultiHop) {
+    reasons.push("Broad time-range request combined with multi-hop retrieval indicators.");
+  }
+  if (action === "expand_shallow") {
+    reasons.push("Complexity is bounded; use direct/shallow expansion.");
+  }
+
+  return {
+    action,
+    normalizedMaxDepth,
+    candidateSummaryCount,
+    estimatedTokens,
+    tokenCap,
+    tokenRiskRatio: tokenRisk.ratio,
+    tokenRiskLevel: tokenRisk.level,
+    indicators: {
+      broadTimeRange,
+      multiHopRetrieval,
+    },
+    triggers: {
+      directByNoCandidates,
+      directByLowComplexityProbe,
+      delegateByDepth,
+      delegateByCandidateCount,
+      delegateByTokenRisk,
+      delegateByBroadTimeRangeAndMultiHop,
+    },
+    reasons,
+  };
+}