@vellumai/cli 0.11.6 → 0.11.7-staging.2

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/trust-rules.ts

@@ -0,0 +1,116 @@
+/**
+ * Trust rule types shared between the assistant daemon and the gateway.
+ *
+ * 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`,
+ *   `host_file_transfer`, `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.).
+ */
+
+// ---------------------------------------------------------------------------
+// Trust decision
+// ---------------------------------------------------------------------------
+
+/** The possible decisions a trust rule can make. */
+export type TrustDecision = "allow" | "deny" | "ask";
+
+// ---------------------------------------------------------------------------
+// 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",
+  "host_file_transfer",
+  "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,
+);
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+/** Returns true when the rule's tool belongs to the scoped-tool family. */
+export function isScopedRule(rule: { tool: string }): boolean {
+  return SCOPED_TOOLS_SET.has(rule.tool);
+}
+
+/** Returns true when the rule's tool belongs to the URL-tool family. */
+export function isUrlRule(rule: { tool: string }): boolean {
+  return URL_TOOLS_SET.has(rule.tool);
+}
+
+/** Returns true when the rule's tool belongs to the managed-skill-tool family. */
+export function isManagedSkillRule(rule: { tool: string }): boolean {
+  return MANAGED_SKILL_TOOLS_SET.has(rule.tool);
+}
+
+/** Returns true when the rule's tool is the skill_load tool. */
+export function isSkillLoadRule(rule: { tool: string }): boolean {
+  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: { tool: string; scope?: string }): string {
+  if (isScopedRule(rule)) {
+    return rule.scope ?? "everywhere";
+  }
+  return "everywhere";
+}
+

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/twilio-ingress.ts

@@ -0,0 +1,73 @@
+import { normalizePublicBaseUrl } from "./ingress.js";
+
+export const TWILIO_VOICE_WEBHOOK_PATH = "/webhooks/twilio/voice";
+export const TWILIO_STATUS_WEBHOOK_PATH = "/webhooks/twilio/status";
+export const TWILIO_MEDIA_STREAM_WEBHOOK_PATH = "/webhooks/twilio/media-stream";
+
+/**
+ * Sentinel placeholder embedded in TwiML by the assistant where the real
+ * public base URL should go. The gateway replaces `wss://__VELLUM_PUBLIC_BASE_URL__/…`
+ * with the actual public URL (from Velay registration, config, or the
+ * `X-Vellum-Ingress-URL` header) before returning TwiML to Twilio.
+ *
+ * The placeholder uses `https://` so that `buildTwilioMediaStreamUrl` can
+ * apply the standard `http→ws` scheme conversion, producing
+ * `wss://__VELLUM_PUBLIC_BASE_URL__/…` in the output.
+ */
+export const TWILIO_PUBLIC_BASE_URL_PLACEHOLDER =
+  "https://__VELLUM_PUBLIC_BASE_URL__";
+
+/**
+ * The WebSocket-scheme form of the placeholder that appears in TwiML after
+ * the `http→ws` scheme conversion applied by the URL builders.
+ */
+export const TWILIO_PUBLIC_BASE_WSS_PLACEHOLDER =
+  "wss://__VELLUM_PUBLIC_BASE_URL__";
+
+export { normalizePublicBaseUrl } from "./ingress.js";
+
+export type TwilioPhoneNumberWebhookUrls = {
+  statusCallbackUrl: string;
+  voiceUrl: string;
+};
+
+export function resolveTwilioPublicBaseUrl(
+  ingress: { publicBaseUrl?: unknown } | undefined,
+  fallbackPublicBaseUrl?: unknown,
+): string | undefined {
+  const publicBaseUrl = normalizePublicBaseUrl(ingress?.publicBaseUrl);
+  if (publicBaseUrl) return publicBaseUrl;
+
+  return normalizePublicBaseUrl(fallbackPublicBaseUrl);
+}
+
+export function buildTwilioVoiceWebhookUrl(
+  baseUrl: string,
+  callSessionId?: string,
+): string {
+  if (callSessionId) {
+    return `${baseUrl}${TWILIO_VOICE_WEBHOOK_PATH}?callSessionId=${callSessionId}`;
+  }
+  return `${baseUrl}${TWILIO_VOICE_WEBHOOK_PATH}`;
+}
+
+export function buildTwilioStatusWebhookUrl(baseUrl: string): string {
+  return `${baseUrl}${TWILIO_STATUS_WEBHOOK_PATH}`;
+}
+
+export function buildTwilioMediaStreamUrl(baseUrl: string): string {
+  return `${toTwilioWebSocketBaseUrl(baseUrl)}${TWILIO_MEDIA_STREAM_WEBHOOK_PATH}`;
+}
+
+export function buildTwilioPhoneNumberWebhookUrls(
+  baseUrl: string,
+): TwilioPhoneNumberWebhookUrls {
+  return {
+    statusCallbackUrl: buildTwilioStatusWebhookUrl(baseUrl),
+    voiceUrl: buildTwilioVoiceWebhookUrl(baseUrl),
+  };
+}
+
+function toTwilioWebSocketBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/^http(s?)/, "ws$1");
+}

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/url-normalization.ts

@@ -0,0 +1,107 @@
+/**
+ * Canonical URL normalization for web tool inputs, shared by the gateway's
+ * risk classifiers and the daemon's URL safety checks.
+ *
+ * A URL a model passes to `web_fetch` / `network_request` reaches more than
+ * one consumer, and they must agree on what counts as the same target: the
+ * gateway builds the trust-rule ladder from it, and anything that later
+ * compares a URL to a saved rule has to fold the same spellings together. Two
+ * normalizations would mean two answers, so it lives here rather than in
+ * either process.
+ *
+ * Data-only in spirit: no imports, no config, no I/O.
+ */
+
+/** Whether a bare `host:port` (or `[v6]:port`) shorthand was written. */
+export function looksLikeHostPortShorthand(value: string): boolean {
+  if (/^\[[0-9a-fA-F:.%]+\]:\d+(?:[/?#]|$)/.test(value)) {
+    return true;
+  }
+  return /^[^/?#@\s:]+:\d+(?:[/?#]|$)/.test(value);
+}
+
+/** Whether the input is a path, query, or fragment rather than a URL. */
+export function looksLikePathOnlyInput(value: string): boolean {
+  return (
+    value.startsWith("/") ||
+    value.startsWith("./") ||
+    value.startsWith("../") ||
+    value.startsWith("?") ||
+    value.startsWith("#")
+  );
+}
+
+/**
+ * Strip the parts of a URL that must not affect a trust decision, and fold
+ * the encodings that would otherwise let one URL wear two spellings.
+ *
+ * Percent-escaped path segments are decoded (`/%70rivate` and `/private` are
+ * one path, so a path-scoped rule cannot be bypassed by escaping), a trailing
+ * root dot is dropped from the hostname, and fragment and userinfo are
+ * removed: the fragment never reaches the server, and credentials in the
+ * authority must never end up in a saved rule.
+ */
+export function canonicalizeWebUrl(parsed: URL): URL {
+  parsed.hash = "";
+  parsed.username = "";
+  parsed.password = "";
+
+  try {
+    parsed.pathname = decodeURI(parsed.pathname);
+  } catch {
+    // Keep the URL parser's canonical form when decoding fails.
+  }
+
+  if (parsed.hostname.endsWith(".")) {
+    parsed.hostname = parsed.hostname.replace(/\.+$/, "");
+  }
+
+  return parsed;
+}
+
+/**
+ * Parse and canonicalize a web tool's `url` input, or `null` when it is not a
+ * URL this system will fetch.
+ *
+ * Accepts `https://host/path`, `http://…`, bare `host/path`, and `host:port`
+ * shorthand. Rejects path-only input and any other scheme (`file:`, `data:`,
+ * `javascript:`), so a non-http target can never acquire a web trust rule.
+ */
+export function normalizeWebUrl(rawUrl: string): URL | null {
+  const trimmed = rawUrl.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  if (looksLikeHostPortShorthand(trimmed)) {
+    try {
+      return canonicalizeWebUrl(new URL(`https://${trimmed}`));
+    } catch {
+      return null;
+    }
+  }
+
+  try {
+    const parsed = new URL(trimmed);
+    if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+      return canonicalizeWebUrl(parsed);
+    }
+    return null;
+  } catch {
+    // Not an absolute URL; fall through to the shorthand forms.
+  }
+
+  if (looksLikePathOnlyInput(trimmed)) {
+    return null;
+  }
+
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed)) {
+    return null;
+  }
+
+  try {
+    return canonicalizeWebUrl(new URL(`https://${trimmed}`));
+  } catch {
+    return null;
+  }
+}

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/node_modules/@vellumai/local-mode/package.json

@@ -13,7 +13,9 @@
     "test": "bun test src/"
   },
   "dependencies": {
-    "@vellumai/environments": "file:../environments",
+    "@vellumai/avatar-manifest": "workspace:*",
+    "@vellumai/environments": "workspace:*",
+    "@vellumai/service-contracts": "workspace:*",
     "nanoid": "5.1.7",
     "zod": "4.3.6"
   },

package/node_modules/@vellumai/local-mode/src/__tests__/guardian-token.test.ts

@@ -9,6 +9,8 @@ import {
   parseGuardianRefreshCliFailure,
   PAIRED_GUARDIAN_TARGET_MISMATCH_ERROR,
   PAIRED_GUARDIAN_TOKEN_HOST_ONLY_ERROR,
+  isConfidentialRefreshUrl,
+  isLoopbackUrl,
   saveGuardianToken,
   type GuardianTokenData,
 } from "../guardian-token";
@@ -241,3 +243,46 @@ describe("parseGuardianRefreshCliFailure", () => {
     });
   });
 });
+
+describe("isConfidentialRefreshUrl", () => {
+  test.each([
+    ["https://gw.example.com", "https reaches it encrypted"],
+    ["http://localhost:7830", "exact localhost stays on this machine"],
+    ["http://127.0.0.5:7830", "127/8 stays on this machine"],
+    ["http://[::1]:7830", "IPv6 loopback stays on this machine"],
+    ["http://localhost.:7830", "an absolute localhost name is the same host"],
+    ["http://0.0.0.0:7830", "a wildcard bind dials a local listener"],
+  ])("%s is confidential (%s)", (url) => {
+    expect(isConfidentialRefreshUrl(url)).toBe(true);
+  });
+
+  test.each([
+    ["http://gw.example.com", "plaintext to a public host"],
+    ["http://10.0.0.5:7830", "plaintext to a private address"],
+    ["not a url", "an unparseable value"],
+  ])("%s is not confidential (%s)", (url) => {
+    expect(isConfidentialRefreshUrl(url)).toBe(false);
+  });
+
+  test("a reserved .localhost name is refused plaintext", () => {
+    // RFC 6761 says a resolver should map the whole `.localhost` namespace to
+    // loopback; glibc does not by default, so this name can answer with any
+    // address. Treating it as confidential would put a long-lived, replayable
+    // refresh token on the wire in plaintext to whatever answered.
+    for (const url of [
+      "http://evil.localhost:8080",
+      "http://evil.localhost.:8080",
+      "http://a.b.localhost",
+    ]) {
+      expect(isConfidentialRefreshUrl(url)).toBe(false);
+      // The pairing side still refuses it as loopback: a name that might be
+      // local is refused by the guards that refuse loopback and denied by the
+      // guards that reward it.
+      expect(isLoopbackUrl(url)).toBe(true);
+    }
+  });
+
+  test("https to a .localhost name is confidential on the protocol alone", () => {
+    expect(isConfidentialRefreshUrl("https://evil.localhost:8443")).toBe(true);
+  });
+});

package/node_modules/@vellumai/local-mode/src/__tests__/package-boundary.test.ts

@@ -2,13 +2,17 @@
  * Package boundary tests for @vellumai/local-mode.
  *
  * This package is the shared local-assistant host surface. It sits one layer
- * above @vellumai/environments (its only allowed @vellumai dependency) and
- * uses node builtins for filesystem, child-process, and network work.
+ * above @vellumai/environments, @vellumai/service-contracts, and the
+ * source-only @vellumai/avatar-manifest (its only allowed @vellumai
+ * dependencies) and uses node builtins for filesystem, child-process, and
+ * network work.
  *
  * Enforces that the package:
- * 1. Imports only node builtins, its own relative modules, `@vellumai/environments`,
- *    `zod` (the lockfile contract's schema library), and `nanoid` (pair's
- *    fallback local-id generator); nothing else.
+ * 1. Imports only node builtins, its own relative modules,
+ *    `@vellumai/environments`, `@vellumai/service-contracts` (the pairing wire
+ *    contracts), `@vellumai/avatar-manifest`, `zod` (the lockfile contract's
+ *    schema library), and `nanoid` (pair's fallback local-id generator);
+ *    nothing else.
  * 2. Declares exactly those runtime dependencies.
  * 3. Is marked `private`.
  */
@@ -20,7 +24,13 @@ import { join, resolve } from "node:path";
 const PACKAGE_ROOT = resolve(import.meta.dirname, "../..");
 const SRC_DIR = join(PACKAGE_ROOT, "src");
 
-const ALLOWED_PACKAGES = new Set(["@vellumai/environments", "zod", "nanoid"]);
+const ALLOWED_PACKAGES = new Set([
+  "@vellumai/environments",
+  "@vellumai/service-contracts",
+  "@vellumai/avatar-manifest",
+  "zod",
+  "nanoid",
+]);
 
 function collectSourceFiles(dir: string): string[] {
   const files: string[] = [];
@@ -45,17 +55,21 @@ function collectSourceFiles(dir: string): string[] {
  * Matches the module specifier of any `import ... from "<spec>"` /
  * `export ... from "<spec>"` / `require("<spec>")` statement.
  */
-const IMPORT_SPEC = /(?:from|require\s*\(\s*)["']([^"']+)["']/g;
+const IMPORT_SPEC = /(?:from\s+|require\s*\(\s*)["']([^"']+)["']/g;
 
 /**
  * A specifier is forbidden when it is neither relative, a node builtin, nor
- * one of the explicitly allowed `@vellumai/*` packages.
+ * an entry point of one of the explicitly allowed packages.
  */
 function isForbiddenSpecifier(spec: string): boolean {
   if (spec.startsWith(".") || spec.startsWith("/")) return false;
   if (spec.startsWith("node:")) return false;
-  if (ALLOWED_PACKAGES.has(spec)) return false;
-  return true;
+  // A subpath export ("pkg/entry") is allowed exactly when its package is.
+  const segments = spec.split("/");
+  const packageName = spec.startsWith("@")
+    ? segments.slice(0, 2).join("/")
+    : segments[0]!;
+  return !ALLOWED_PACKAGES.has(packageName);
 }
 
 describe("package boundary", () => {
@@ -65,7 +79,7 @@ describe("package boundary", () => {
     expect(sourceFiles.length).toBeGreaterThan(0);
   });
 
-  test("imports only node builtins, relative modules, and @vellumai/environments", () => {
+  test("imports only node builtins, relative modules, and its allowed packages", () => {
     const violations: string[] = [];
 
     for (const file of sourceFiles) {
@@ -86,8 +100,10 @@ describe("package boundary", () => {
         `Found ${violations.length} forbidden import(s) in @vellumai/local-mode:\n` +
           violations.map((v) => `  - ${v}`).join("\n") +
           "\n\n@vellumai/local-mode may import only node builtins, its own\n" +
-          "relative modules, and @vellumai/environments. Any other dependency\n" +
-          "would break bundler hosts that inline this source-only package.",
+          "relative modules, @vellumai/environments, and\n" +
+          "@vellumai/service-contracts, and @vellumai/avatar-manifest. Any\n" +
+          "other dependency would break bundler hosts that inline this\n" +
+          "source-only package.",
       );
     }
   });
@@ -98,7 +114,9 @@ describe("package boundary", () => {
     );
     expect(pkg.private).toBe(true);
     expect(pkg.dependencies ?? {}).toEqual({
-      "@vellumai/environments": "file:../environments",
+      "@vellumai/avatar-manifest": "workspace:*",
+      "@vellumai/environments": "workspace:*",
+      "@vellumai/service-contracts": "workspace:*",
       nanoid: "5.1.7",
       zod: "4.3.6",
     });