@cuylabs/agent-core 0.9.0 → 0.11.0

package/dist/chunk-V4RFNEET.js

@@ -0,0 +1,563 @@
+import {
+  describeApprovalOperation,
+  extractApprovalPatterns,
+  matchApprovalPattern,
+  resolveCapability
+} from "./chunk-FII65CN7.js";
+
+// src/safety/risk.ts
+var DEFAULT_TOOL_RISKS = {
+  read: "safe",
+  read_file: "safe",
+  grep: "safe",
+  glob: "safe",
+  list_dir: "safe",
+  plan: "safe",
+  invoke_agent: "safe",
+  wait_agent: "safe",
+  close_agent: "safe",
+  skill: "safe",
+  skill_resource: "safe",
+  write: "moderate",
+  write_file: "moderate",
+  edit: "moderate",
+  edit_file: "moderate",
+  create_file: "moderate",
+  bash: "dangerous",
+  shell: "dangerous",
+  delete_file: "dangerous",
+  remove: "dangerous"
+};
+function getToolRisk(tool, customRisks, declaredRisk) {
+  if (customRisks?.[tool]) {
+    return customRisks[tool];
+  }
+  if (declaredRisk) {
+    return declaredRisk;
+  }
+  if (DEFAULT_TOOL_RISKS[tool]) {
+    return DEFAULT_TOOL_RISKS[tool];
+  }
+  return "moderate";
+}
+
+// src/safety/policy.ts
+var DEFAULT_CASCADE_POLICY = {
+  remember: "matching-pending",
+  deny: "matching-pending"
+};
+var DEFAULT_REMEMBER_SCOPE = "session";
+function createConditionalApprovalRule(rule, when) {
+  return {
+    ...rule,
+    when
+  };
+}
+function allApprovalConditions(...conditions) {
+  return (context) => conditions.every((condition) => condition(context));
+}
+function anyApprovalConditions(...conditions) {
+  return (context) => conditions.some((condition) => condition(context));
+}
+function matchApprovalSessions(...sessionIds) {
+  const allowed = new Set(sessionIds.map((sessionId) => sessionId.trim()).filter(Boolean));
+  return (context) => allowed.has(context.sessionId);
+}
+function matchApprovalRisks(...risks) {
+  const allowed = new Set(risks);
+  return (context) => allowed.has(context.risk);
+}
+function getPathValue(input, path) {
+  const segments = path.split(".").map((segment) => segment.trim()).filter(Boolean);
+  let current = input;
+  for (const segment of segments) {
+    if (!current || typeof current !== "object" || !(segment in current)) {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+function matchApprovalArgValue(path, predicate) {
+  return (context) => predicate(getPathValue(context.args, path), context);
+}
+function matchApprovalNumericArg(path, thresholds) {
+  return matchApprovalArgValue(path, (value) => {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+      return false;
+    }
+    if (thresholds.gt !== void 0 && !(value > thresholds.gt)) {
+      return false;
+    }
+    if (thresholds.gte !== void 0 && !(value >= thresholds.gte)) {
+      return false;
+    }
+    if (thresholds.lt !== void 0 && !(value < thresholds.lt)) {
+      return false;
+    }
+    if (thresholds.lte !== void 0 && !(value <= thresholds.lte)) {
+      return false;
+    }
+    return true;
+  });
+}
+function matchApprovalStringPrefixes(path, ...prefixes) {
+  const normalized = prefixes.map((prefix) => prefix.trim()).filter(Boolean);
+  return matchApprovalArgValue(path, (value) => {
+    if (typeof value !== "string") {
+      return false;
+    }
+    const lower = value.toLowerCase();
+    return normalized.some((prefix) => lower.startsWith(prefix.toLowerCase()));
+  });
+}
+function normalizeApprovalCascadePolicy(input) {
+  return {
+    remember: input?.remember ?? DEFAULT_CASCADE_POLICY.remember,
+    deny: input?.deny ?? DEFAULT_CASCADE_POLICY.deny
+  };
+}
+function normalizeRememberScopes(scopes) {
+  const allowed = /* @__PURE__ */ new Set(["session", "project", "user"]);
+  const normalized = (scopes ?? [DEFAULT_REMEMBER_SCOPE]).filter(
+    (scope) => allowed.has(scope)
+  );
+  return normalized.length > 0 ? [...new Set(normalized)] : [DEFAULT_REMEMBER_SCOPE];
+}
+function selectRememberScope(decision, request, fallback = DEFAULT_REMEMBER_SCOPE) {
+  const allowed = normalizeRememberScopes(
+    request.rememberScopes ?? [request.defaultRememberScope ?? fallback]
+  );
+  const requested = decision.rememberScope ?? request.defaultRememberScope ?? fallback;
+  return allowed.includes(requested) ? requested : allowed[0] ?? fallback;
+}
+function createRememberedApprovalRules(request, source = request.defaultRememberScope ?? DEFAULT_REMEMBER_SCOPE) {
+  const scopeCondition = source === "session" ? matchApprovalSessions(request.sessionId) : void 0;
+  return [...new Set(request.patterns)].map((pattern) => ({
+    pattern,
+    tool: request.tool,
+    action: "allow",
+    source,
+    ...scopeCondition ? { when: scopeCondition } : {}
+  }));
+}
+function requestsSharePatterns(left, right) {
+  return left.some(
+    (leftPattern) => right.some(
+      (rightPattern) => matchApprovalPattern(leftPattern, rightPattern) || matchApprovalPattern(rightPattern, leftPattern)
+    )
+  );
+}
+function approvalRequestsOverlap(left, right) {
+  if (left.sessionId !== right.sessionId) {
+    return false;
+  }
+  if (left.tool !== right.tool) {
+    return false;
+  }
+  return requestsSharePatterns(left.patterns, right.patterns);
+}
+function shouldCascadeApprovalDecision(resolved, candidate, decision) {
+  if (resolved.id === candidate.id) {
+    return false;
+  }
+  const cascade = normalizeApprovalCascadePolicy(resolved.cascade);
+  const mode = decision.action === "remember" ? cascade.remember : decision.action === "deny" ? cascade.deny : "none";
+  if (mode === "none") {
+    return false;
+  }
+  return approvalRequestsOverlap(resolved, candidate);
+}
+function formatApprovalDeniedReason(tool, detail) {
+  const trimmed = detail?.trim();
+  return trimmed ? `Approval denied for ${tool}: ${trimmed}` : `Tool call denied: ${tool}`;
+}
+function createApprovalCorrection(tool, detail) {
+  const reason = formatApprovalDeniedReason(tool, detail);
+  const trimmed = detail?.trim();
+  return {
+    kind: "approval-denied",
+    tool,
+    reason,
+    ...trimmed ? { feedback: trimmed } : {}
+  };
+}
+function buildApprovalRuleContext(sessionId, tool, args, risk, patternExtractor) {
+  return {
+    sessionId,
+    tool,
+    args,
+    risk,
+    patterns: patternExtractor ? patternExtractor(args) : extractApprovalPatterns(tool, args)
+  };
+}
+
+// src/safety/errors.ts
+var ApprovalDeniedError = class extends Error {
+  constructor(tool, args, detail) {
+    super(formatApprovalDeniedReason(tool, detail));
+    this.tool = tool;
+    this.args = args;
+    this.name = "ApprovalDeniedError";
+    this.feedback = detail;
+  }
+  feedback;
+};
+var ApprovalTimeoutError = class extends Error {
+  constructor(tool, timeoutMs) {
+    super(`Approval timeout after ${timeoutMs}ms for: ${tool}`);
+    this.tool = tool;
+    this.timeoutMs = timeoutMs;
+    this.name = "ApprovalTimeoutError";
+  }
+};
+
+// src/safety/handler.ts
+var SOURCE_PRIORITY = {
+  user: 0,
+  project: 1,
+  session: 2,
+  cli: 3
+};
+function findMatchingRule(rules, context) {
+  let best;
+  let bestPriority = -1;
+  for (const rule of rules) {
+    const toolMatches = rule.tool === "*" || matchApprovalPattern(rule.tool, context.tool);
+    const patternMatches = context.patterns.some(
+      (pattern) => matchApprovalPattern(rule.pattern, pattern)
+    );
+    const conditionMatches = rule.when ? rule.when(context) : true;
+    if (!toolMatches || !patternMatches || !conditionMatches) continue;
+    const sourcePriority = rule.source ? SOURCE_PRIORITY[rule.source] : SOURCE_PRIORITY.session;
+    const denyBoost = rule.action === "deny" ? 0.5 : 0;
+    const priority = sourcePriority + denyBoost;
+    if (priority > bestPriority) {
+      best = rule;
+      bestPriority = priority;
+    }
+  }
+  return best;
+}
+function normalizeApprovalDecision(value) {
+  if (typeof value === "string") {
+    return { action: value };
+  }
+  return value;
+}
+function createApprovalHandler(config = {}) {
+  const {
+    defaultAction = "ask",
+    timeout = 5 * 60 * 1e3,
+    onRequest,
+    rememberScope = "session",
+    allowedRememberScopes = ["session"],
+    cascade
+  } = config;
+  let requestCounter = 0;
+  const initialRuleCount = config.rules?.length ?? 0;
+  const rules = [...config.rules ?? []];
+  const activeRequests = /* @__PURE__ */ new Set();
+  async function request(sessionId, tool, args, customRisks, capabilities, patternExtractor, extraRules = []) {
+    const evaluation = evaluate(
+      sessionId,
+      tool,
+      args,
+      customRisks,
+      capabilities,
+      patternExtractor,
+      extraRules
+    );
+    switch (evaluation.action) {
+      case "allow":
+        return;
+      case "deny":
+        throw new ApprovalDeniedError(tool, args, evaluation.reason);
+      case "request":
+        break;
+    }
+    if (!onRequest) {
+      if (defaultAction === "allow") {
+        return;
+      }
+      if (defaultAction === "deny") {
+        throw new ApprovalDeniedError(tool, args);
+      }
+      throw new ApprovalDeniedError(tool, args, "No approval handler configured");
+    }
+    const ac = new AbortController();
+    activeRequests.add(ac);
+    let timeoutId;
+    try {
+      const resolution = normalizeApprovalDecision(await Promise.race([
+        onRequest(evaluation.request),
+        new Promise((_, reject) => {
+          timeoutId = setTimeout(() => {
+            reject(new ApprovalTimeoutError(tool, timeout));
+          }, timeout);
+          ac.signal.addEventListener("abort", () => {
+            clearTimeout(timeoutId);
+            reject(new Error("Cancelled"));
+          }, { once: true });
+        })
+      ]));
+      switch (resolution.action) {
+        case "allow":
+          return;
+        case "deny":
+          throw new ApprovalDeniedError(tool, args, resolution.feedback);
+        case "remember": {
+          const scope = selectRememberScope(
+            resolution,
+            evaluation.request,
+            rememberScope
+          );
+          rules.push(
+            ...createRememberedApprovalRules(evaluation.request, scope)
+          );
+          return;
+        }
+      }
+    } finally {
+      clearTimeout(timeoutId);
+      activeRequests.delete(ac);
+    }
+  }
+  function evaluate(sessionId, tool, args, customRisks, capabilities, patternExtractor, extraRules = []) {
+    if (resolveCapability(capabilities?.readOnly, args, false)) {
+      return { action: "allow" };
+    }
+    const risk = getToolRisk(tool, customRisks, capabilities?.riskLevel);
+    const ruleContext = buildApprovalRuleContext(
+      sessionId,
+      tool,
+      args,
+      risk,
+      patternExtractor
+    );
+    const patterns = ruleContext.patterns;
+    const matchingRule = findMatchingRule(
+      [...extraRules, ...rules],
+      ruleContext
+    );
+    if (matchingRule) {
+      if (matchingRule.action === "allow") {
+        return { action: "allow" };
+      }
+      return {
+        action: "deny",
+        reason: matchingRule.reason ?? `Denied by rule: ${matchingRule.pattern}`
+      };
+    }
+    if (risk === "safe" && defaultAction !== "deny") {
+      return { action: "allow" };
+    }
+    if (defaultAction === "allow") {
+      return { action: "allow" };
+    }
+    if (defaultAction === "deny") {
+      return {
+        action: "deny",
+        reason: formatApprovalDeniedReason(tool)
+      };
+    }
+    const id = `approval-${++requestCounter}-${Date.now()}`;
+    const requestData = {
+      id,
+      sessionId,
+      tool,
+      args,
+      description: describeApprovalOperation(tool, args),
+      risk,
+      patterns,
+      rememberScopes: normalizeRememberScopes(allowedRememberScopes),
+      defaultRememberScope: rememberScope,
+      cascade: normalizeApprovalCascadePolicy(cascade),
+      timestamp: Date.now()
+    };
+    return { action: "request", request: requestData };
+  }
+  function cancelAll(_reason) {
+    for (const ac of activeRequests) {
+      ac.abort();
+    }
+    activeRequests.clear();
+  }
+  function addRule(rule) {
+    rules.push(rule);
+  }
+  function getRules() {
+    return rules;
+  }
+  function clearSessionRules() {
+    rules.splice(initialRuleCount);
+  }
+  function clearBySource(source) {
+    for (let i = rules.length - 1; i >= 0; i--) {
+      if (rules[i].source === source) {
+        rules.splice(i, 1);
+      }
+    }
+  }
+  return {
+    evaluate,
+    request,
+    cancelAll,
+    addRule,
+    getRules,
+    clearSessionRules,
+    clearBySource
+  };
+}
+
+// src/safety/presets.ts
+function withOverrides(defaultAction, options = {}) {
+  return {
+    defaultAction,
+    ...options.onRequest ? { onRequest: options.onRequest } : {},
+    ...options.rules ? { rules: [...options.rules] } : {},
+    ...options.timeout !== void 0 ? { timeout: options.timeout } : {},
+    ...options.rememberScope ? { rememberScope: options.rememberScope } : {},
+    ...options.allowedRememberScopes ? { allowedRememberScopes: [...options.allowedRememberScopes] } : {},
+    ...options.cascade ? { cascade: { ...options.cascade } } : {}
+  };
+}
+function createInteractiveApprovalPolicy(options = {}) {
+  return withOverrides("ask", options);
+}
+function createHeadlessDenyApprovalPolicy(options = {}) {
+  return withOverrides("deny", options);
+}
+function createDangerouslyAllowAllApprovalPolicy(options = {}) {
+  return withOverrides("allow", options);
+}
+function createRiskTierApprovalPolicy(options = {}) {
+  const {
+    safe = "allow",
+    moderate = "ask",
+    dangerous = "ask",
+    source = "user",
+    rules = [],
+    ...rest
+  } = options;
+  const generatedRules = [];
+  for (const [risk, action] of [
+    ["safe", safe],
+    ["moderate", moderate],
+    ["dangerous", dangerous]
+  ]) {
+    if (action === "ask") {
+      continue;
+    }
+    generatedRules.push(
+      createConditionalApprovalRule(
+        {
+          pattern: "*",
+          tool: "*",
+          action,
+          source
+        },
+        matchApprovalRisks(risk)
+      )
+    );
+  }
+  return withOverrides("ask", {
+    ...rest,
+    rules: [...generatedRules, ...rules]
+  });
+}
+function createTrustedSessionApprovalPolicy(options) {
+  const {
+    sessionIds,
+    tools = ["*"],
+    patterns = ["*"],
+    risks = ["moderate", "dangerous"],
+    source = "user",
+    rules = [],
+    ...rest
+  } = options;
+  const generatedRules = [];
+  for (const tool of tools) {
+    for (const pattern of patterns) {
+      generatedRules.push(
+        createConditionalApprovalRule(
+          {
+            pattern,
+            tool,
+            action: "allow",
+            source
+          },
+          (context) => matchApprovalSessions(...sessionIds)(context) && matchApprovalRisks(...risks)(context)
+        )
+      );
+    }
+  }
+  return withOverrides("ask", {
+    ...rest,
+    rules: [...generatedRules, ...rules]
+  });
+}
+function createThresholdApprovalRule(options) {
+  const {
+    tool,
+    pattern = "*",
+    action,
+    argPath,
+    source,
+    reason,
+    ...thresholds
+  } = options;
+  return createConditionalApprovalRule(
+    {
+      pattern,
+      tool,
+      action,
+      ...source ? { source } : {},
+      ...reason ? { reason } : {}
+    },
+    matchApprovalNumericArg(argPath, thresholds)
+  );
+}
+function createApprovalPolicyPreset(name, options = {}) {
+  switch (name) {
+    case "interactive":
+      return createInteractiveApprovalPolicy(options);
+    case "headless-deny":
+      return createHeadlessDenyApprovalPolicy(options);
+    case "dangerously-allow-all":
+      return createDangerouslyAllowAllApprovalPolicy(options);
+    case "risk-tier":
+      return createRiskTierApprovalPolicy(options);
+  }
+}
+
+export {
+  getToolRisk,
+  createConditionalApprovalRule,
+  allApprovalConditions,
+  anyApprovalConditions,
+  matchApprovalSessions,
+  matchApprovalRisks,
+  matchApprovalArgValue,
+  matchApprovalNumericArg,
+  matchApprovalStringPrefixes,
+  normalizeApprovalCascadePolicy,
+  normalizeRememberScopes,
+  selectRememberScope,
+  createRememberedApprovalRules,
+  approvalRequestsOverlap,
+  shouldCascadeApprovalDecision,
+  formatApprovalDeniedReason,
+  createApprovalCorrection,
+  buildApprovalRuleContext,
+  ApprovalDeniedError,
+  ApprovalTimeoutError,
+  createApprovalHandler,
+  createInteractiveApprovalPolicy,
+  createHeadlessDenyApprovalPolicy,
+  createDangerouslyAllowAllApprovalPolicy,
+  createRiskTierApprovalPolicy,
+  createTrustedSessionApprovalPolicy,
+  createThresholdApprovalRule,
+  createApprovalPolicyPreset
+};