@declaw/sdk 1.1.13 → 1.2.1

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   CommandExitError: () => CommandExitError,
   CommandHandle: () => CommandHandle,
   Commands: () => Commands,
+  ConflictError: () => ConflictError,
   ConnectionConfig: () => ConnectionConfig,
   DEFAULT_MASK_PATTERNS: () => DEFAULT_MASK_PATTERNS,
   FileType: () => FileType,
@@ -45,6 +46,7 @@ __export(index_exports, {
   FilesystemEventType: () => FilesystemEventType,
   GitAuthError: () => GitAuthError,
   GitUpstreamError: () => GitUpstreamError,
+  Governance: () => Governance,
   InjectionAction: () => InjectionAction,
   InjectionSensitivity: () => InjectionSensitivity,
   InvalidArgumentError: () => InvalidArgumentError,
@@ -66,12 +68,16 @@ __export(index_exports, {
   TemplateError: () => TemplateError,
   TimeoutError: () => TimeoutError,
   TransformDirection: () => TransformDirection,
+  VolumeFiles: () => VolumeFiles,
+  VolumeLocks: () => VolumeLocks,
   Volumes: () => Volumes,
   WatchHandle: () => WatchHandle,
   applyTransformation: () => applyTransformation,
   codeSecurityConfigToJSON: () => codeSecurityConfigToJSON,
+  contentGateConfigToJSON: () => contentGateConfigToJSON,
   createAuditConfig: () => createAuditConfig,
   createCodeSecurityConfig: () => createCodeSecurityConfig,
+  createContentGateConfig: () => createContentGateConfig,
   createEnvSecurityConfig: () => createEnvSecurityConfig,
   createInjectionDefenseConfig: () => createInjectionDefenseConfig,
   createInvisibleTextConfig: () => createInvisibleTextConfig,
@@ -90,11 +96,17 @@ __export(index_exports, {
   parseBuildInfo: () => parseBuildInfo,
   parseCodeSecurityConfig: () => parseCodeSecurityConfig,
   parseCommandResult: () => parseCommandResult,
+  parseContentGateConfig: () => parseContentGateConfig,
   parseEntryInfo: () => parseEntryInfo,
   parseEnvSecurityConfig: () => parseEnvSecurityConfig,
+  parseFileEntry: () => parseFileEntry,
+  parseFileInfo: () => parseFileInfo,
   parseFilesystemEvent: () => parseFilesystemEvent,
+  parseGovernancePack: () => parseGovernancePack,
   parseInjectionDefenseConfig: () => parseInjectionDefenseConfig,
   parseInvisibleTextConfig: () => parseInvisibleTextConfig,
+  parseLockLease: () => parseLockLease,
+  parseLockStatus: () => parseLockStatus,
   parseNetworkPolicy: () => parseNetworkPolicy,
   parsePIIConfig: () => parsePIIConfig,
   parseProcessInfo: () => parseProcessInfo,
@@ -191,6 +203,12 @@ var NotEnoughSpaceError = class extends SandboxError {
     this.name = "NotEnoughSpaceError";
   }
 };
+var ConflictError = class extends SandboxError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "ConflictError";
+  }
+};
 var TemplateError = class extends SandboxError {
   constructor(message, opts) {
     super(message, opts);
@@ -236,6 +254,8 @@ var CommandExitError = class extends SandboxError {
 
 // src/api/client.ts
 var _dispatcherPromise;
+var _resolvedDispatcher;
+var _dispatcherResolved = false;
 function getDispatcher() {
   if (_dispatcherPromise) return _dispatcherPromise;
   _dispatcherPromise = (async () => {
@@ -260,7 +280,14 @@ function getDispatcher() {
         maxConcurrentStreams,
         keepAliveTimeout: 3e4,
         keepAliveMaxTimeout: 6e4,
-        pipelining: 1,
+        // NOTE: do NOT set `pipelining` here. undici applies it to H2 sessions
+        // too, where `pipelining: 1` caps each connection to ONE in-flight
+        // stream — silently defeating the H2 multiplexing that allowH2 enables.
+        // Omitted, H2 sessions default to unlimited concurrent streams (capped
+        // by maxConcurrentStreams) and H1.1 fallback defaults to 1 (safe, no
+        // head-of-line risk on non-idempotent POSTs). This is the single
+        // biggest burst-latency lever: with pipelining:1 a 100-concurrent burst
+        // queued ~36 requests behind the `connections` cap.
         allowH2: true,
         connect: { keepAlive: true, keepAliveInitialDelay: 5e3 }
       });
@@ -268,13 +295,21 @@ function getDispatcher() {
       return void 0;
     }
   })();
+  void _dispatcherPromise.then((d) => {
+    _resolvedDispatcher = d;
+    _dispatcherResolved = true;
+  });
   return _dispatcherPromise;
 }
+void getDispatcher();
 var STATUS_ERROR_MAP = {
+  400: InvalidArgumentError,
   401: AuthenticationError,
   403: AuthenticationError,
   404: NotFoundError,
   408: TimeoutError,
+  409: ConflictError,
+  413: NotEnoughSpaceError,
   422: InvalidArgumentError,
   507: NotEnoughSpaceError
 };
@@ -286,7 +321,7 @@ var ApiClient = class {
   constructor(config, opts) {
     this.config = config ?? new ConnectionConfig();
     this.maxRetries = opts?.maxRetries ?? 3;
-    this.retryDelay = opts?.retryDelay ?? 0.5;
+    this.retryDelay = opts?.retryDelay ?? 0.1;
     this.abortController = new AbortController();
   }
   /** Send a GET request and return parsed JSON. */
@@ -380,7 +415,7 @@ var ApiClient = class {
           signals.push(AbortSignal.timeout(timeoutMs));
         }
         const signal = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
-        const dispatcher = await getDispatcher();
+        const dispatcher = _dispatcherResolved ? _resolvedDispatcher : await getDispatcher();
         const fetchOpts = {
           method,
           headers,
@@ -933,6 +968,49 @@ function invisibleTextConfigToJSON(config) {
   return result;
 }
 
+// src/security/customPolicy.ts
+function parseCustomPolicyConfig(data) {
+  return {
+    enabled: data.enabled ?? false,
+    inlineRego: data.inline_rego ?? data.inlineRego,
+    inlineModules: data.inline_modules ?? data.inlineModules,
+    policyRef: data.policy_ref ?? data.policyRef,
+    defaultDeny: data.default_deny ?? data.defaultDeny ?? false
+  };
+}
+function customPolicyConfigToJSON(config) {
+  return {
+    enabled: config.enabled,
+    inline_rego: config.inlineRego,
+    inline_modules: config.inlineModules,
+    policy_ref: config.policyRef,
+    default_deny: config.defaultDeny
+  };
+}
+
+// src/security/contentGate.ts
+function createContentGateConfig(opts) {
+  return {
+    enabled: opts?.enabled ?? false,
+    domains: opts?.domains
+  };
+}
+function parseContentGateConfig(data) {
+  return {
+    enabled: data.enabled ?? false,
+    domains: data.domains
+  };
+}
+function contentGateConfigToJSON(config) {
+  const result = {
+    enabled: config.enabled
+  };
+  if (config.domains !== void 0) {
+    result.domains = config.domains;
+  }
+  return result;
+}
+
 // src/security/policy.ts
 function createSecurityPolicy(opts) {
   return {
@@ -944,12 +1022,16 @@ function createSecurityPolicy(opts) {
     envSecurity: opts?.envSecurity ?? createEnvSecurityConfig(),
     toxicity: opts?.toxicity,
     codeSecurity: opts?.codeSecurity,
-    invisibleText: opts?.invisibleText
+    invisibleText: opts?.invisibleText,
+    contentGate: opts?.contentGate,
+    customPolicy: opts?.customPolicy
   };
 }
 function parseSecurityPolicy(data) {
   const injDef = data.injection_defense ?? data.injectionDefense;
   const auditData = data.audit;
+  const customPolicyData = data.custom_policy ?? data.customPolicy;
+  const contentGateData = data.content_gate ?? data.contentGate;
   return {
     pii: data.pii ? parsePIIConfig(data.pii) : createPIIConfig(),
     injectionDefense: typeof injDef === "boolean" ? injDef : injDef ? parseInjectionDefenseConfig(injDef) : false,
@@ -959,7 +1041,9 @@ function parseSecurityPolicy(data) {
     envSecurity: data.env_security ?? data.envSecurity ? parseEnvSecurityConfig(data.env_security ?? data.envSecurity) : createEnvSecurityConfig(),
     toxicity: data.toxicity ? parseToxicityConfig(data.toxicity) : void 0,
     codeSecurity: data.code_security ?? data.codeSecurity ? parseCodeSecurityConfig(data.code_security ?? data.codeSecurity) : void 0,
-    invisibleText: data.invisible_text ?? data.invisibleText ? parseInvisibleTextConfig(data.invisible_text ?? data.invisibleText) : void 0
+    invisibleText: data.invisible_text ?? data.invisibleText ? parseInvisibleTextConfig(data.invisible_text ?? data.invisibleText) : void 0,
+    contentGate: contentGateData ? parseContentGateConfig(contentGateData) : void 0,
+    customPolicy: customPolicyData ? parseCustomPolicyConfig(customPolicyData) : void 0
   };
 }
 function securityPolicyToJSON(policy) {
@@ -1009,6 +1093,12 @@ function securityPolicyToJSON(policy) {
   if (policy.invisibleText) {
     result.invisible_text = invisibleTextConfigToJSON(policy.invisibleText);
   }
+  if (policy.contentGate) {
+    result.content_gate = contentGateConfigToJSON(policy.contentGate);
+  }
+  if (policy.customPolicy) {
+    result.custom_policy = customPolicyConfigToJSON(policy.customPolicy);
+  }
   return result;
 }
 function requiresTlsInterception(policy) {
@@ -2027,11 +2117,53 @@ function parseVolumeInfo(data) {
     sizeBytes: Number(data.size_bytes ?? 0),
     contentType: String(data.content_type ?? ""),
     metadata: data.metadata ?? {},
-    createdAt: String(data.created_at ?? "")
+    createdAt: String(data.created_at ?? ""),
+    backend: String(data.backend ?? ""),
+    quotaBytes: Number(data.quota_bytes ?? 0),
+    updatedAt: String(data.updated_at ?? "")
+  };
+}
+function parseFileEntry(data) {
+  return {
+    name: String(data.name ?? ""),
+    path: String(data.path ?? ""),
+    isDir: Boolean(data.is_dir ?? false),
+    size: Number(data.size ?? 0),
+    modTime: String(data.mod_time ?? ""),
+    mode: Number(data.mode ?? 0)
+  };
+}
+function parseFileInfo(data) {
+  return {
+    ...parseFileEntry(data),
+    version: String(data.version ?? "")
+  };
+}
+function parseLockLease(data) {
+  return {
+    token: String(data.token ?? ""),
+    ttlSeconds: Number(data.ttl_seconds ?? 0),
+    expiresAt: String(data.expires_at ?? "")
+  };
+}
+function parseLockStatus(data) {
+  return {
+    held: Boolean(data.held ?? false),
+    expiresInMs: Number(data.expires_in_ms ?? 0)
   };
 }
 function volumeAttachmentToJSON(att) {
-  return { volume_id: att.volumeId, mount_path: att.mountPath };
+  const out = {
+    volume_id: att.volumeId,
+    mount_path: att.mountPath
+  };
+  if (att.mode) {
+    out.mode = att.mode;
+  }
+  if (att.subpath) {
+    out.subpath = att.subpath;
+  }
+  return out;
 }
 
 // src/sandbox/sandbox.ts
@@ -2857,7 +2989,7 @@ var Template = class {
   }
 };
 
-// src/volumes/volumes.ts
+// src/volumes/files.ts
 var VALID_VOLUME_ID_RE = /^[a-zA-Z0-9_-]+$/;
 function assertValidVolumeId(id) {
   if (!id || !VALID_VOLUME_ID_RE.test(id)) {
@@ -2866,8 +2998,223 @@ function assertValidVolumeId(id) {
     );
   }
 }
+var VolumeFiles = class {
+  volumeId;
+  opts;
+  constructor(volumeId, opts) {
+    assertValidVolumeId(volumeId);
+    this.volumeId = volumeId;
+    this.opts = opts;
+  }
+  client() {
+    const config = new ConnectionConfig({
+      apiKey: this.opts?.apiKey,
+      domain: this.opts?.domain,
+      apiUrl: this.opts?.apiUrl,
+      requestTimeout: this.opts?.requestTimeout
+    });
+    return getSharedClient(config);
+  }
+  timeout() {
+    return this.opts?.requestTimeout;
+  }
+  /** Write raw bytes to `path`. Optionally conditional on `ifVersion` (CAS). */
+  async write(path, data, opts) {
+    if (!path) {
+      throw new InvalidArgumentError("path is required");
+    }
+    const params = { path };
+    if (opts?.ifVersion) {
+      params.if_version = opts.ifVersion;
+    }
+    const body = data instanceof Uint8Array ? data : new Uint8Array(data);
+    const resp = await this.client().put(`/volumes/${this.volumeId}/files/raw`, {
+      params,
+      body,
+      headers: { "Content-Type": "application/octet-stream" },
+      timeout: opts?.requestTimeout ?? this.timeout()
+    });
+    return String(resp.path ?? path);
+  }
+  /** Read raw bytes from `path`. */
+  async read(path) {
+    if (!path) {
+      throw new InvalidArgumentError("path is required");
+    }
+    return this.client().getBytes(`/volumes/${this.volumeId}/files/raw`, {
+      params: { path },
+      timeout: this.timeout()
+    });
+  }
+  /** List directory entries under `path`. */
+  async list(path) {
+    if (!path) {
+      throw new InvalidArgumentError("path is required");
+    }
+    const resp = await this.client().get(`/volumes/${this.volumeId}/files/list`, {
+      params: { path },
+      timeout: this.timeout()
+    });
+    const rows = resp.entries ?? [];
+    return rows.map(parseFileEntry);
+  }
+  /** Stat `path`, returning the entry plus the CAS `version` token. */
+  async info(path) {
+    if (!path) {
+      throw new InvalidArgumentError("path is required");
+    }
+    const resp = await this.client().get(`/volumes/${this.volumeId}/files/info`, {
+      params: { path },
+      timeout: this.timeout()
+    });
+    return parseFileInfo(resp);
+  }
+  /** Return whether `path` exists. */
+  async exists(path) {
+    if (!path) {
+      throw new InvalidArgumentError("path is required");
+    }
+    const resp = await this.client().get(`/volumes/${this.volumeId}/files/exists`, {
+      params: { path },
+      timeout: this.timeout()
+    });
+    return Boolean(resp.exists ?? false);
+  }
+  /** Remove `path`. Pass `{ recursive: true }` to remove a directory tree. */
+  async remove(path, opts) {
+    if (!path) {
+      throw new InvalidArgumentError("path is required");
+    }
+    const params = {
+      path,
+      recursive: opts?.recursive ? "true" : "false"
+    };
+    await this.client().delete(`/volumes/${this.volumeId}/files`, {
+      params,
+      timeout: opts?.requestTimeout ?? this.timeout()
+    });
+  }
+  /** Rename `oldPath` to `newPath`. */
+  async rename(oldPath, newPath) {
+    if (!oldPath || !newPath) {
+      throw new InvalidArgumentError("oldPath and newPath are required");
+    }
+    const resp = await this.client().patch(`/volumes/${this.volumeId}/files`, {
+      json: { old_path: oldPath, new_path: newPath },
+      timeout: this.timeout()
+    });
+    return {
+      oldPath: String(resp.old_path ?? oldPath),
+      newPath: String(resp.new_path ?? newPath)
+    };
+  }
+  /** Create a directory at `path`. */
+  async mkdir(path) {
+    if (!path) {
+      throw new InvalidArgumentError("path is required");
+    }
+    const resp = await this.client().post(`/volumes/${this.volumeId}/files/mkdir`, {
+      json: { path },
+      timeout: this.timeout()
+    });
+    return String(resp.path ?? path);
+  }
+};
+
+// src/volumes/locks.ts
+var VALID_VOLUME_ID_RE2 = /^[a-zA-Z0-9_-]+$/;
+function assertValidVolumeId2(id) {
+  if (!id || !VALID_VOLUME_ID_RE2.test(id)) {
+    throw new InvalidArgumentError(
+      `Invalid volume ID: "${id}". Must be alphanumeric with hyphens/underscores only.`
+    );
+  }
+}
+var VolumeLocks = class {
+  volumeId;
+  opts;
+  constructor(volumeId, opts) {
+    assertValidVolumeId2(volumeId);
+    this.volumeId = volumeId;
+    this.opts = opts;
+  }
+  client() {
+    const config = new ConnectionConfig({
+      apiKey: this.opts?.apiKey,
+      domain: this.opts?.domain,
+      apiUrl: this.opts?.apiUrl,
+      requestTimeout: this.opts?.requestTimeout
+    });
+    return getSharedClient(config);
+  }
+  timeout() {
+    return this.opts?.requestTimeout;
+  }
+  /** Acquire a lock on `path`. Throws ConflictError (409) if already held. */
+  async acquire(path, ttlSeconds) {
+    if (!path) {
+      throw new InvalidArgumentError("path is required");
+    }
+    const json = { path };
+    if (ttlSeconds !== void 0) {
+      json.ttl_seconds = ttlSeconds;
+    }
+    const resp = await this.client().post(`/volumes/${this.volumeId}/locks`, {
+      json,
+      timeout: this.timeout()
+    });
+    return parseLockLease(resp);
+  }
+  /** Release a lock on `path` held under `token`. Throws ConflictError (409) if not the holder. */
+  async release(path, token) {
+    if (!path || !token) {
+      throw new InvalidArgumentError("path and token are required");
+    }
+    const resp = await this.client().delete(`/volumes/${this.volumeId}/locks`, {
+      json: { path, token },
+      timeout: this.timeout()
+    });
+    return Boolean(resp.released ?? false);
+  }
+  /** Renew a lock on `path` held under `token`. Throws ConflictError (409) if not the holder. */
+  async renew(path, token, ttlSeconds) {
+    if (!path || !token) {
+      throw new InvalidArgumentError("path and token are required");
+    }
+    const json = { path, token };
+    if (ttlSeconds !== void 0) {
+      json.ttl_seconds = ttlSeconds;
+    }
+    const resp = await this.client().post(`/volumes/${this.volumeId}/locks/renew`, {
+      json,
+      timeout: this.timeout()
+    });
+    return { ...parseLockLease(resp), token };
+  }
+  /** Query whether `path` is currently locked. */
+  async status(path) {
+    if (!path) {
+      throw new InvalidArgumentError("path is required");
+    }
+    const resp = await this.client().get(`/volumes/${this.volumeId}/locks`, {
+      params: { path },
+      timeout: this.timeout()
+    });
+    return parseLockStatus(resp);
+  }
+};
+
+// src/volumes/volumes.ts
+var VALID_VOLUME_ID_RE3 = /^[a-zA-Z0-9_-]+$/;
+function assertValidVolumeId3(id) {
+  if (!id || !VALID_VOLUME_ID_RE3.test(id)) {
+    throw new InvalidArgumentError(
+      `Invalid volume ID: "${id}". Must be alphanumeric with hyphens/underscores only.`
+    );
+  }
+}
 var Volumes = class {
-  /** Create a volume by streaming a tarball to the server. */
+  /** Create a volume by streaming a tarball (gzip tar.gz) to the server. */
   static async create(name, data, opts) {
     if (!name) {
       throw new InvalidArgumentError("volume name is required");
@@ -2888,9 +3235,113 @@ var Volumes = class {
     });
     return parseVolumeInfo(resp);
   }
+  /**
+   * Capture the attached volume's mount path in `sandboxId` into a NEW volume.
+   *
+   * The source volume is left unchanged. If `name` is omitted the server names
+   * the new volume "<source-name>-commit". Returns the new VolumeInfo.
+   */
+  static async commit(sandboxId, volumeId, name, opts) {
+    if (!sandboxId || !VALID_VOLUME_ID_RE3.test(sandboxId)) {
+      throw new InvalidArgumentError(
+        `Invalid sandbox ID: "${sandboxId}". Must be alphanumeric with hyphens/underscores only.`
+      );
+    }
+    assertValidVolumeId3(volumeId);
+    const config = new ConnectionConfig({
+      apiKey: opts?.apiKey,
+      domain: opts?.domain,
+      apiUrl: opts?.apiUrl,
+      requestTimeout: opts?.requestTimeout
+    });
+    const client = getSharedClient(config);
+    const resp = await client.post(`/sandboxes/${sandboxId}/volumes/${volumeId}/commit`, {
+      params: name ? { name } : void 0,
+      timeout: opts?.requestTimeout
+    });
+    return parseVolumeInfo(resp);
+  }
+  /**
+   * Snapshot an arbitrary absolute in-sandbox `path` into a NEW volume.
+   *
+   * Unlike `commit` (which captures an already-attached volume's mount path),
+   * `snapshot` captures any path in the running sandbox. `name` defaults to
+   * "snapshot" on the server. Synthetic paths (/proc, /sys, /dev) are rejected.
+   */
+  static async snapshot(sandboxId, path, name, opts) {
+    if (!sandboxId || !VALID_VOLUME_ID_RE3.test(sandboxId)) {
+      throw new InvalidArgumentError(
+        `Invalid sandbox ID: "${sandboxId}". Must be alphanumeric with hyphens/underscores only.`
+      );
+    }
+    if (!path) {
+      throw new InvalidArgumentError("path is required");
+    }
+    const config = new ConnectionConfig({
+      apiKey: opts?.apiKey,
+      domain: opts?.domain,
+      apiUrl: opts?.apiUrl,
+      requestTimeout: opts?.requestTimeout
+    });
+    const client = getSharedClient(config);
+    const params = { path };
+    if (name) {
+      params.name = name;
+    }
+    const resp = await client.post(`/sandboxes/${sandboxId}/volumes/snapshot`, {
+      params,
+      timeout: opts?.requestTimeout
+    });
+    return parseVolumeInfo(resp);
+  }
+  /**
+   * Create an empty file-granular volume. Requires a file-granular backend
+   * (503 if not configured). Returns the new VolumeInfo.
+   */
+  static async empty(name, opts) {
+    if (!name) {
+      throw new InvalidArgumentError("volume name is required");
+    }
+    const config = new ConnectionConfig({
+      apiKey: opts?.apiKey,
+      domain: opts?.domain,
+      apiUrl: opts?.apiUrl,
+      requestTimeout: opts?.requestTimeout
+    });
+    const client = getSharedClient(config);
+    const resp = await client.post("/volumes/empty", {
+      params: { name },
+      timeout: opts?.requestTimeout
+    });
+    return parseVolumeInfo(resp);
+  }
+  /**
+   * Ingest a gzip tar.gz archive into a NEW file-granular volume. Requires a
+   * file-granular backend (503 if not configured). 413 on quota exceeded.
+   */
+  static async ingest(name, data, opts) {
+    if (!name) {
+      throw new InvalidArgumentError("volume name is required");
+    }
+    const config = new ConnectionConfig({
+      apiKey: opts?.apiKey,
+      domain: opts?.domain,
+      apiUrl: opts?.apiUrl,
+      requestTimeout: opts?.requestTimeout
+    });
+    const client = getSharedClient(config);
+    const body = data instanceof Uint8Array ? data : new Uint8Array(data);
+    const resp = await client.post("/volumes/ingest", {
+      params: { name },
+      body,
+      headers: { "Content-Type": opts?.contentType ?? "application/gzip" },
+      timeout: opts?.requestTimeout
+    });
+    return parseVolumeInfo(resp);
+  }
   /** Fetch metadata for a single volume. */
   static async get(volumeId, opts) {
-    assertValidVolumeId(volumeId);
+    assertValidVolumeId3(volumeId);
     const config = new ConnectionConfig({
       apiKey: opts?.apiKey,
       domain: opts?.domain,
@@ -2918,9 +3369,23 @@ var Volumes = class {
     const rows = resp.volumes ?? [];
     return rows.map(parseVolumeInfo);
   }
+  /** Download the volume's contents as raw bytes (the stored archive/blob). */
+  static async download(volumeId, opts) {
+    assertValidVolumeId3(volumeId);
+    const config = new ConnectionConfig({
+      apiKey: opts?.apiKey,
+      domain: opts?.domain,
+      apiUrl: opts?.apiUrl,
+      requestTimeout: opts?.requestTimeout
+    });
+    const client = getSharedClient(config);
+    return client.getBytes(`/volumes/${volumeId}/download`, {
+      timeout: opts?.requestTimeout
+    });
+  }
   /** Delete a volume and its blob. Idempotent on the wire. */
   static async delete(volumeId, opts) {
-    assertValidVolumeId(volumeId);
+    assertValidVolumeId3(volumeId);
     const config = new ConnectionConfig({
       apiKey: opts?.apiKey,
       domain: opts?.domain,
@@ -2930,6 +3395,100 @@ var Volumes = class {
     const client = getSharedClient(config);
     await client.delete(`/volumes/${volumeId}`, { timeout: opts?.requestTimeout });
   }
+  /**
+   * File-granular operations (read/write/list/info/exists/remove/rename/mkdir,
+   * plus CAS via `write(..., { ifVersion })`) on `volumeId`. File-granular
+   * volumes only.
+   */
+  static files(volumeId, opts) {
+    return new VolumeFiles(volumeId, opts);
+  }
+  /** Advisory locks (acquire/release/renew/status) over a (volume, path). */
+  static locks(volumeId, opts) {
+    return new VolumeLocks(volumeId, opts);
+  }
+};
+
+// src/governance/models.ts
+function parseGovernanceControl(data) {
+  return {
+    control: String(data.control ?? ""),
+    gate: String(data.gate ?? ""),
+    rule: String(data.rule ?? ""),
+    playbook: String(data.playbook ?? "")
+  };
+}
+function parseGovernanceAdvisory(data) {
+  return {
+    control: String(data.control ?? ""),
+    reason: String(data.reason ?? "")
+  };
+}
+function parseGovernancePack(data) {
+  const rawEnforces = data.enforces ?? [];
+  const rawAdvisory = data.advisory ?? [];
+  return {
+    name: String(data.name ?? ""),
+    version: String(data.version ?? ""),
+    framework: String(data.framework ?? ""),
+    description: String(data.description ?? ""),
+    gates: data.gates ?? [],
+    enforces: rawEnforces.map(parseGovernanceControl),
+    advisory: rawAdvisory.map(parseGovernanceAdvisory),
+    policyRef: String(data.policy_ref ?? data.policyRef ?? ""),
+    seeded: Boolean(data.seeded ?? false)
+  };
+}
+
+// src/governance/governance.ts
+var VALID_PACK_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+function assertValidPackName(name) {
+  if (!name || !VALID_PACK_NAME_RE.test(name)) {
+    throw new InvalidArgumentError(
+      `Invalid pack name: "${name}". Must be alphanumeric with hyphens/underscores only.`
+    );
+  }
+}
+var Governance = class {
+  /**
+   * List all available governance packs.
+   *
+   * Sends GET /governance/packs and returns the `packs` array.
+   */
+  static async listPacks(opts) {
+    const config = new ConnectionConfig({
+      apiKey: opts?.apiKey,
+      domain: opts?.domain,
+      apiUrl: opts?.apiUrl,
+      requestTimeout: opts?.requestTimeout
+    });
+    const client = getSharedClient(config);
+    const resp = await client.get("/governance/packs", {
+      timeout: opts?.requestTimeout
+    });
+    const rows = resp.packs ?? [];
+    return rows.map(parseGovernancePack);
+  }
+  /**
+   * Fetch a single governance pack by name.
+   *
+   * Sends GET /governance/packs/:name and returns the pack object.
+   * Throws InvalidArgumentError if the name contains unsafe characters.
+   */
+  static async getPack(name, opts) {
+    assertValidPackName(name);
+    const config = new ConnectionConfig({
+      apiKey: opts?.apiKey,
+      domain: opts?.domain,
+      apiUrl: opts?.apiUrl,
+      requestTimeout: opts?.requestTimeout
+    });
+    const client = getSharedClient(config);
+    const resp = await client.get(`/governance/packs/${name}`, {
+      timeout: opts?.requestTimeout
+    });
+    return parseGovernancePack(resp);
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -2940,6 +3499,7 @@ var Volumes = class {
   CommandExitError,
   CommandHandle,
   Commands,
+  ConflictError,
   ConnectionConfig,
   DEFAULT_MASK_PATTERNS,
   FileType,
@@ -2948,6 +3508,7 @@ var Volumes = class {
   FilesystemEventType,
   GitAuthError,
   GitUpstreamError,
+  Governance,
   InjectionAction,
   InjectionSensitivity,
   InvalidArgumentError,
@@ -2969,12 +3530,16 @@ var Volumes = class {
   TemplateError,
   TimeoutError,
   TransformDirection,
+  VolumeFiles,
+  VolumeLocks,
   Volumes,
   WatchHandle,
   applyTransformation,
   codeSecurityConfigToJSON,
+  contentGateConfigToJSON,
   createAuditConfig,
   createCodeSecurityConfig,
+  createContentGateConfig,
   createEnvSecurityConfig,
   createInjectionDefenseConfig,
   createInvisibleTextConfig,
@@ -2993,11 +3558,17 @@ var Volumes = class {
   parseBuildInfo,
   parseCodeSecurityConfig,
   parseCommandResult,
+  parseContentGateConfig,
   parseEntryInfo,
   parseEnvSecurityConfig,
+  parseFileEntry,
+  parseFileInfo,
   parseFilesystemEvent,
+  parseGovernancePack,
   parseInjectionDefenseConfig,
   parseInvisibleTextConfig,
+  parseLockLease,
+  parseLockStatus,
   parseNetworkPolicy,
   parsePIIConfig,
   parseProcessInfo,