@vellumai/assistant 0.6.4 → 0.6.6

package/node_modules/@vellumai/ces-contracts/src/trust-rules.ts

@@ -4,6 +4,22 @@
  * These are extracted from `assistant/src/permissions/types.ts` and
  * `assistant/src/permissions/trust-store.ts` so that both packages can
  * reference a single canonical definition.
+ *
+ * Tools are grouped into "families" based on how their permission candidates
+ * are constructed and matched:
+ *
+ * - **Scoped**: tools whose candidates include a filesystem path and obey
+ *   directory-boundary scope constraints (`file_read`, `file_write`,
+ *   `file_edit`, `host_file_read`, `host_file_write`, `host_file_edit`,
+ *   `bash`, `host_bash`).
+ * - **URL**: tools whose candidates include a URL (`web_fetch`,
+ *   `network_request`).
+ * - **Managed skill**: tools that manage first-party skill packages
+ *   (`scaffold_managed_skill`, `delete_managed_skill`).
+ * - **Skill load**: the `skill_load` tool, which uses a distinct candidate
+ *   namespace (`skill_load:selector` or `skill_load_dynamic:selector`).
+ * - **Generic**: everything else (computer-use tools, UI surface tools,
+ *   recall, skill_execute, etc.).
  */
 
 // ---------------------------------------------------------------------------
@@ -14,19 +30,349 @@
 export type TrustDecision = "allow" | "deny" | "ask";
 
 // ---------------------------------------------------------------------------
-// Trust rule
+// Tool family constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Tools whose permission candidates are scoped to a filesystem path and obey
+ * directory-boundary scope constraints.
+ */
+export const SCOPED_TOOLS = [
+  "file_read",
+  "file_write",
+  "file_edit",
+  "host_file_read",
+  "host_file_write",
+  "host_file_edit",
+  "bash",
+  "host_bash",
+] as const;
+
+/**
+ * Tools whose permission candidates include a URL.
+ */
+export const URL_TOOLS = ["web_fetch", "network_request"] as const;
+
+/**
+ * Tools that manage first-party skill packages (scaffold/delete).
+ */
+export const MANAGED_SKILL_TOOLS = [
+  "scaffold_managed_skill",
+  "delete_managed_skill",
+] as const;
+
+/**
+ * The skill_load tool name. Separated from the array constants because
+ * skill_load is a singleton, not a family with multiple members.
+ */
+export const SKILL_LOAD_TOOL = "skill_load" as const;
+
+/** Set for O(1) lookups when classifying tool names. */
+const SCOPED_TOOLS_SET: ReadonlySet<string> = new Set(SCOPED_TOOLS);
+const URL_TOOLS_SET: ReadonlySet<string> = new Set(URL_TOOLS);
+const MANAGED_SKILL_TOOLS_SET: ReadonlySet<string> = new Set(
+  MANAGED_SKILL_TOOLS,
+);
+
+// ---------------------------------------------------------------------------
+// Trust rule — base and family-specific variants
 // ---------------------------------------------------------------------------
 
-export interface TrustRule {
+/** Fields shared by all trust rule variants. */
+export interface TrustRuleBase {
   id: string;
   tool: string;
   pattern: string;
-  scope: string;
   decision: TrustDecision;
   priority: number;
   createdAt: number;
+  /**
+   * Set when a user explicitly modifies a default trust rule.
+   * When present, `backfillDefaults()` will not overwrite the rule
+   * with updated template values on upgrade — preserving the user's
+   * customization.
+   */
+  userModifiedAt?: number;
+}
+
+/**
+ * A trust rule for a scoped tool (filesystem-path-based candidates).
+ *
+ * Scoped rules may carry `executionTarget` to constrain matching to a
+ * specific execution environment.
+ */
+export interface ScopedTrustRule extends TrustRuleBase {
+  tool: (typeof SCOPED_TOOLS)[number];
+  scope: string;
   executionTarget?: string;
-  allowHighRisk?: boolean;
+}
+
+/**
+ * A trust rule for a URL-based tool.
+ *
+ * URL rules do not use `executionTarget`.
+ */
+export interface UrlTrustRule extends TrustRuleBase {
+  tool: (typeof URL_TOOLS)[number];
+}
+
+/**
+ * A trust rule for a managed-skill tool (scaffold/delete).
+ */
+export interface ManagedSkillTrustRule extends TrustRuleBase {
+  tool: (typeof MANAGED_SKILL_TOOLS)[number];
+}
+
+/**
+ * A trust rule for the `skill_load` tool.
+ */
+export interface SkillLoadTrustRule extends TrustRuleBase {
+  tool: typeof SKILL_LOAD_TOOL;
+}
+
+/**
+ * A trust rule for any tool that doesn't belong to a known family.
+ *
+ * Generic rules preserve `executionTarget` for backward compatibility —
+ * existing rules for unknown/new tools may carry this field.
+ * Scope is intentionally absent: new tools that need scope must be explicitly
+ * added to `SCOPED_TOOLS` and use `ScopedTrustRule`.
+ */
+export interface GenericTrustRule extends TrustRuleBase {
+  tool: string;
+  executionTarget?: string;
+}
+
+/**
+ * Discriminated union of all trust rule families.
+ *
+ * The union is discriminated on the `tool` field: known tool names narrow to
+ * the corresponding family variant, while unknown tool names fall through to
+ * `GenericTrustRule`.
+ *
+ * For backward compatibility, `TrustRule` remains the single type that all
+ * existing code uses. The family-specific interfaces exist so that new code
+ * can narrow the type when it knows the tool family.
+ */
+export type TrustRule =
+  | ScopedTrustRule
+  | UrlTrustRule
+  | ManagedSkillTrustRule
+  | SkillLoadTrustRule
+  | GenericTrustRule;
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+/** Narrow a TrustRule to a ScopedTrustRule. */
+export function isScopedRule(rule: TrustRule): rule is ScopedTrustRule {
+  return SCOPED_TOOLS_SET.has(rule.tool);
+}
+
+/** Narrow a TrustRule to a UrlTrustRule. */
+export function isUrlRule(rule: TrustRule): rule is UrlTrustRule {
+  return URL_TOOLS_SET.has(rule.tool);
+}
+
+/** Narrow a TrustRule to a ManagedSkillTrustRule. */
+export function isManagedSkillRule(
+  rule: TrustRule,
+): rule is ManagedSkillTrustRule {
+  return MANAGED_SKILL_TOOLS_SET.has(rule.tool);
+}
+
+/** Narrow a TrustRule to a SkillLoadTrustRule. */
+export function isSkillLoadRule(rule: TrustRule): rule is SkillLoadTrustRule {
+  return rule.tool === SKILL_LOAD_TOOL;
+}
+
+// ---------------------------------------------------------------------------
+// Scope helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the effective scope for any trust rule. Only scoped rules carry a
+ * `scope` field; all other rule families return `"everywhere"`.
+ */
+export function ruleScope(rule: TrustRule): string {
+  if (isScopedRule(rule)) {
+    return rule.scope;
+  }
+  return "everywhere";
+}
+
+// ---------------------------------------------------------------------------
+// Canonical parse / normalize
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of parsing a raw trust rule object. Includes the normalized rule
+ * and a flag indicating whether any normalization occurred (so callers can
+ * trigger a re-save of the trust file).
+ */
+export interface ParsedTrustRule {
+  rule: TrustRule;
+  /** True if any fields were stripped or modified during normalization. */
+  normalized: boolean;
+}
+
+/**
+ * Parse and normalize a raw trust rule object into a canonical `TrustRule`.
+ *
+ * Normalization strips fields that are invalid for the rule's tool family:
+ * - URL rules: `executionTarget` and `scope` are stripped.
+ * - Managed skill rules: `executionTarget` and `scope` are stripped.
+ * - Skill load rules: `executionTarget` and `scope` are stripped.
+ * - Scoped rules: `scope` is preserved (defaulting to `"everywhere"`),
+ *   `executionTarget` is preserved when valid.
+ * - Generic (unknown) rules: `scope` is stripped (new tools that need scope
+ *   must be added to `SCOPED_TOOLS`); `executionTarget` is preserved for
+ *   forward compatibility.
+ * - All families: `allowHighRisk` is stripped (replaced by runtime
+ *   determination in checker.ts). Old trust.json files with `allowHighRisk`
+ *   are normalized on load.
+ */
+export function parseTrustRule(raw: Record<string, unknown>): ParsedTrustRule {
+  let normalized = false;
+
+  // Extract base fields with coercion for safety — mark normalized whenever
+  // a field is coerced to its default so callers know to re-save.
+  const id = typeof raw.id === "string" ? raw.id : ((normalized = true), "");
+  const tool =
+    typeof raw.tool === "string" ? raw.tool : ((normalized = true), "");
+  const pattern =
+    typeof raw.pattern === "string" ? raw.pattern : ((normalized = true), "");
+  const decision = isValidDecision(raw.decision)
+    ? raw.decision
+    : ((normalized = true), "ask" as const);
+  const priority =
+    typeof raw.priority === "number" ? raw.priority : ((normalized = true), 100);
+  const createdAt =
+    typeof raw.createdAt === "number"
+      ? raw.createdAt
+      : ((normalized = true), 0);
+  const userModifiedAt =
+    typeof raw.userModifiedAt === "number" ? raw.userModifiedAt : undefined;
+
+  // Build the base rule — scope is NOT included here; it is added only by
+  // the scoped and generic branches below.
+  const base: TrustRuleBase = {
+    id,
+    tool,
+    pattern,
+    decision,
+    priority,
+    createdAt,
+    ...(userModifiedAt != null ? { userModifiedAt } : {}),
+  };
+
+  // Determine the family and strip invalid fields
+  if (URL_TOOLS_SET.has(tool)) {
+    // URL rules must not carry executionTarget or scope.
+    if (raw.executionTarget !== undefined) {
+      normalized = true;
+    }
+    if (typeof raw.scope === "string" && raw.scope !== "everywhere") {
+      normalized = true;
+    }
+    // allowHighRisk is stripped (replaced by runtime determination).
+    if (raw.allowHighRisk !== undefined) {
+      normalized = true;
+    }
+    const rule: UrlTrustRule = { ...base, tool: tool as UrlTrustRule["tool"] };
+    return { rule, normalized };
+  }
+
+  if (MANAGED_SKILL_TOOLS_SET.has(tool)) {
+    // Managed skill rules must not carry executionTarget or scope.
+    if (raw.executionTarget !== undefined) {
+      normalized = true;
+    }
+    if (typeof raw.scope === "string" && raw.scope !== "everywhere") {
+      normalized = true;
+    }
+    // allowHighRisk is stripped (replaced by runtime determination).
+    if (raw.allowHighRisk !== undefined) {
+      normalized = true;
+    }
+    const rule: ManagedSkillTrustRule = {
+      ...base,
+      tool: tool as ManagedSkillTrustRule["tool"],
+    };
+    return { rule, normalized };
+  }
+
+  if (tool === SKILL_LOAD_TOOL) {
+    // Skill-load rules must not carry executionTarget or scope.
+    if (raw.executionTarget !== undefined) {
+      normalized = true;
+    }
+    if (typeof raw.scope === "string" && raw.scope !== "everywhere") {
+      normalized = true;
+    }
+    // allowHighRisk is stripped (replaced by runtime determination).
+    if (raw.allowHighRisk !== undefined) {
+      normalized = true;
+    }
+    const rule: SkillLoadTrustRule = { ...base, tool: SKILL_LOAD_TOOL };
+    return { rule, normalized };
+  }
+
+  if (SCOPED_TOOLS_SET.has(tool)) {
+    // Scoped rules include scope (defaulting to "everywhere") and preserve
+    // executionTarget.
+    const scope =
+      typeof raw.scope === "string"
+        ? raw.scope
+        : ((normalized = true), "everywhere");
+    const rule: ScopedTrustRule = {
+      ...base,
+      tool: tool as ScopedTrustRule["tool"],
+      scope,
+    };
+    if (
+      typeof raw.executionTarget === "string" &&
+      raw.executionTarget.length > 0
+    ) {
+      rule.executionTarget = raw.executionTarget;
+    } else if (raw.executionTarget !== undefined && raw.executionTarget !== "") {
+      normalized = true;
+    }
+    // allowHighRisk is stripped (replaced by runtime determination).
+    if (raw.allowHighRisk !== undefined) {
+      normalized = true;
+    }
+    return { rule, normalized };
+  }
+
+  // Generic (unknown) tool — strip scope (new tools that need scope must be
+  // added to SCOPED_TOOLS explicitly), preserve executionTarget for forward compat.
+  const rule: GenericTrustRule = { ...base };
+  if (
+    typeof raw.scope === "string" &&
+    raw.scope !== "" &&
+    raw.scope !== "everywhere"
+  ) {
+    normalized = true;
+  }
+  if (
+    typeof raw.executionTarget === "string" &&
+    raw.executionTarget.length > 0
+  ) {
+    rule.executionTarget = raw.executionTarget;
+  } else if (raw.executionTarget !== undefined && raw.executionTarget !== "") {
+    normalized = true;
+  }
+  // allowHighRisk is stripped (replaced by runtime determination).
+  if (raw.allowHighRisk !== undefined) {
+    normalized = true;
+  }
+  return { rule, normalized };
+}
+
+function isValidDecision(value: unknown): value is TrustDecision {
+  return value === "allow" || value === "deny" || value === "ask";
 }
 
 // ---------------------------------------------------------------------------
@@ -40,3 +386,51 @@ export interface TrustFileData {
   /** Set to true when the user explicitly accepts the starter approval bundle. */
   starterBundleAccepted?: boolean;
 }
+
+/**
+ * Result of parsing a raw trust file. Includes the parsed data and a flag
+ * indicating whether any rules were normalized.
+ */
+export interface ParsedTrustFileData {
+  data: TrustFileData;
+  /** True if any rules were normalized during parsing. */
+  normalized: boolean;
+}
+
+/**
+ * Parse and normalize a raw trust file object.
+ *
+ * Each rule in the `rules` array is run through `parseTrustRule` for
+ * family-aware normalization. The `normalized` flag in the result is true
+ * if *any* rule was modified, signaling the caller that a re-save is warranted.
+ */
+export function parseTrustFileData(
+  raw: Record<string, unknown>,
+): ParsedTrustFileData {
+  const version = typeof raw.version === "number" ? raw.version : 0;
+  const starterBundleAccepted =
+    raw.starterBundleAccepted === true ? true : undefined;
+  const rawRules = Array.isArray(raw.rules) ? raw.rules : [];
+
+  let anyNormalized = false;
+  const rules: TrustRule[] = [];
+
+  for (const rawRule of rawRules) {
+    if (rawRule == null || typeof rawRule !== "object" || Array.isArray(rawRule)) {
+      anyNormalized = true;
+      continue;
+    }
+    const { rule, normalized } = parseTrustRule(
+      rawRule as Record<string, unknown>,
+    );
+    if (normalized) anyNormalized = true;
+    rules.push(rule);
+  }
+
+  const data: TrustFileData = { version, rules };
+  if (starterBundleAccepted) {
+    data.starterBundleAccepted = true;
+  }
+
+  return { data, normalized: anyNormalized };
+}

package/node_modules/@vellumai/credential-storage/bun.lock

@@ -5,8 +5,8 @@
     "": {
       "name": "@vellumai/credential-storage",
       "devDependencies": {
-        "@types/bun": "^1.2.4",
-        "typescript": "^5.7.3",
+        "@types/bun": "1.3.10",
+        "typescript": "5.9.3",
       },
     },
   },

package/node_modules/@vellumai/credential-storage/package.json

@@ -12,7 +12,7 @@
     "test": "bun test src/"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.4",
-    "typescript": "^5.7.3"
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
   }
 }

package/node_modules/@vellumai/credential-storage/src/oauth-runtime.ts

@@ -89,6 +89,8 @@ export interface RefreshBreakerState {
   consecutiveFailures: number;
   openedAt: number;
   cooldownMs: number;
+  /** Whether the breaker tripped due to a credential error (vs transient). */
+  isCredentialError: boolean;
 }
 
 /**
@@ -128,18 +130,34 @@ export class RefreshCircuitBreaker {
     this.breakers.delete(key);
   }
 
-  /** Record a failed refresh attempt, potentially opening the breaker. */
-  recordFailure(key: string): void {
+  /**
+   * Record a failed refresh attempt, potentially opening the breaker.
+   *
+   * @param isCredential - When true, the failure is a credential error
+   *   (revoked token, invalid client) that no amount of retrying will fix.
+   *   Only credential errors count toward opening the circuit breaker.
+   *   Transient errors (network timeouts, 5xx) are silently ignored here —
+   *   they do not trip the breaker and are not recorded. Upstream retry logic
+   *   in refreshOAuth2Token handles transient failures with exponential backoff.
+   */
+  recordFailure(key: string, isCredential = true): void {
+    if (!isCredential) {
+      // Transient failures should not trip the breaker. The retry logic in
+      // refreshOAuth2Token handles transient errors with its own backoff.
+      return;
+    }
     const state = this.breakers.get(key);
     if (!state) {
       this.breakers.set(key, {
         consecutiveFailures: 1,
         openedAt: 0,
         cooldownMs: INITIAL_COOLDOWN_MS,
+        isCredentialError: true,
       });
       return;
     }
     state.consecutiveFailures++;
+    state.isCredentialError = true;
     if (state.consecutiveFailures >= REFRESH_FAILURE_THRESHOLD) {
       // Only escalate cooldown on the exact failure that trips the breaker.
       // Concurrent in-flight failures that arrive after the threshold is

package/node_modules/@vellumai/egress-proxy/bun.lock

@@ -5,8 +5,8 @@
     "": {
       "name": "@vellumai/egress-proxy",
       "devDependencies": {
-        "@types/bun": "^1.2.4",
-        "typescript": "^5.7.3",
+        "@types/bun": "1.3.10",
+        "typescript": "5.9.3",
       },
     },
   },

package/node_modules/@vellumai/egress-proxy/package.json

@@ -12,7 +12,7 @@
     "test": "bun test src/"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.4",
-    "typescript": "^5.7.3"
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
   }
 }

package/node_modules/@vellumai/egress-proxy/src/types.ts

@@ -197,12 +197,19 @@ export type PolicyDecision =
 /**
  * Callback invoked by the proxy HTTP forwarder for each outbound request.
  * Returns injected headers on allow, or `null` to block the request.
+ *
+ * `method` and `requestHeaders` are populated for plain-HTTP proxied
+ * requests (absolute-URL form). For HTTPS CONNECT tunnels the proxy has
+ * not yet terminated TLS and cannot see HTTP-level details, so these are
+ * left undefined.
  */
 export type PolicyCallback = (
   hostname: string,
   port: number | null,
   path: string,
   scheme: "http" | "https",
+  method?: string,
+  requestHeaders?: Record<string, string | string[] | undefined>,
 ) => Promise<Record<string, string> | null>;
 
 /**
@@ -216,6 +223,18 @@ export interface ProxyApprovalRequest {
     | PolicyDecisionAskUnauthenticated;
   /** The proxy session ID that originated the request. */
   sessionId: ProxySessionId;
+  /**
+   * HTTP method of the incoming request, when available. Undefined for HTTPS
+   * CONNECT tunnels — at CONNECT time the proxy has not terminated TLS so
+   * no HTTP-level information is visible.
+   */
+  method?: string;
+  /**
+   * Curated subset of request headers, when available. Only non-sensitive
+   * headers are surfaced (content-type, content-length, user-agent, accept).
+   * Undefined for HTTPS CONNECT tunnels.
+   */
+  requestHeaders?: Record<string, string>;
 }
 
 /**