@mengruo/dsh-vision-toolkit 0.1.4 → 0.1.6-beta.0

package/src/config.ts

@@ -77,6 +77,12 @@ export interface VisionProviderConfig {
   anthropicThinking?: 'omit' | 'disabled' | 'adaptive'
   /** Outbound User-Agent for provider requests and connection tests. */
   userAgent?: string
+  /** Whether to request a streamed (SSE) completion instead of one JSON response (default false). */
+  stream?: boolean
+  /** Whether to upload images to object storage and send the model a URL instead of base64 (default false). */
+  uploadViaUrl?: boolean
+  /** OpenAI-compatible video understanding (default false); Anthropic providers ignore this placeholder flag. */
+  videoSupport?: boolean
   /** t1: per-request hedge threshold in seconds. A single request exceeding t1 keeps running while the next provider starts in parallel. */
   t1Seconds?: number
   /** t2: per-provider cumulative cutoff in seconds. Total accumulated request time reaching t2 terminates the provider. */
@@ -106,6 +112,12 @@ export interface VisionToolkitConfig {
     anthropicThinking?: 'omit' | 'disabled' | 'adaptive'
     /** Outbound User-Agent for provider requests and connection tests. */
     userAgent?: string
+    /** Whether to request a streamed (SSE) completion instead of one JSON response (default false). */
+    stream?: boolean
+    /** Whether to upload images to object storage and send the model a URL instead of base64 (default false). */
+    uploadViaUrl?: boolean
+    /** OpenAI-compatible video understanding (default false); Anthropic providers ignore this placeholder flag. */
+    videoSupport?: boolean
   }
   /** Ordered online vision providers; array order is the failover priority. */
   providers?: VisionProviderConfig[]
@@ -123,6 +135,21 @@ export interface VisionToolkitConfig {
   maxImagePixels?: number
   /** Default per-model in-flight request cap inherited by providers that do not set their own. */
   concurrency?: number
+  /**
+   * Optional S3-compatible object storage used by the URL image-transfer path.
+   * `endpoint`, `bucket`, and `credential` are required to enable URL transfer;
+   * `publicBase` is optional and falls back to presigned URLs when unset.
+   */
+  objectStorage?: {
+    /** S3-compatible API endpoint (e.g. R2, MinIO, Tencent COS). */
+    endpoint?: string
+    /** Bucket name. */
+    bucket?: string
+    /** DSH Credential reference holding "accessKeyId:secretAccessKey". */
+    credential?: string
+    /** Public base URL (custom domain / r2.dev); when unset, presigned URLs are used. */
+    publicBase?: string
+  }
   runtime?: {
     /** `managed` uses the packaged snapshot and isolated venv; `external` uses a clean pinned checkout. */
     mode?: 'managed' | 'external'
@@ -171,6 +198,21 @@ export interface VisionToolkitConfig {
      */
     hidden?: boolean
   }
+  /**
+   * Per-group tool visibility, applied when each Agent's visual tool set is
+   * materialized (a session-head snapshot: an already-active Agent keeps its
+   * activation-time set; a change only affects the next Agent's tool set).
+   * Tools are grouped into three buckets; a bucket that is off contributes none
+   * of its tools to an Agent's visible surface.
+   */
+  toolVisibility?: {
+    /** Local-processing tools (no on-line fan-out, no concurrency charge). Default true. */
+    local?: boolean
+    /** On-line image tools plus the concurrency/status probe. Default true. */
+    online?: boolean
+    /** Video-understanding tool (experimental). Default false. */
+    video?: boolean
+  }
 }
 
 /** Configuration schema with the documented P0 defaults. */
@@ -182,6 +224,9 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
     protocol: z.union(['openai', 'anthropic'] as const).default('openai'),
     anthropicThinking: z.union(['omit', 'disabled', 'adaptive'] as const).default('omit'),
     userAgent: z.string().default(DEFAULT_VISION_USER_AGENT),
+    stream: z.boolean().default(false),
+    uploadViaUrl: z.boolean().default(false),
+    videoSupport: z.boolean().default(false),
   }),
   providers: z.array(z.object({
     name: z.string(),
@@ -193,6 +238,9 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
     protocol: z.union(['openai', 'anthropic'] as const).default('openai'),
     anthropicThinking: z.union(['omit', 'disabled', 'adaptive'] as const).default('omit'),
     userAgent: z.string(),
+    stream: z.boolean().default(false),
+    uploadViaUrl: z.boolean().default(false),
+    videoSupport: z.boolean().default(false),
     t1Seconds: z.number(),
     t2Seconds: z.number(),
     maxImageBytes: z.number(),
@@ -207,6 +255,12 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
   maxImageBytes: z.number().default(4194304),
   maxImagePixels: z.number().default(20000000),
   concurrency: z.number().default(4),
+  objectStorage: z.object({
+    endpoint: z.string().default(''),
+    bucket: z.string().default(''),
+    credential: z.string().default(''),
+    publicBase: z.string().default(''),
+  }),
   runtime: z.object({
     mode: z.union(['managed', 'external'] as const).default('managed'),
     agentVisionToolkitPath: z.string(),
@@ -221,6 +275,11 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
     autoSwitch: z.boolean().default(true),
     hidden: z.boolean().default(true),
   }),
+  toolVisibility: z.object({
+    local: z.boolean().default(true),
+    online: z.boolean().default(true),
+    video: z.boolean().default(false),
+  }),
 })
 
 /** One resolved online vision provider, with every default materialized. */
@@ -235,6 +294,9 @@ export interface ResolvedProvider {
   protocol: 'openai' | 'anthropic'
   anthropicThinking: 'omit' | 'disabled' | 'adaptive'
   userAgent: string
+  stream: boolean
+  uploadViaUrl: boolean
+  videoSupport: boolean
   t1Seconds: number
   t2Seconds: number
   maxImageBytes: number
@@ -252,6 +314,9 @@ export interface ResolvedVisionToolkitConfig {
     protocol: 'openai' | 'anthropic'
     anthropicThinking: 'omit' | 'disabled' | 'adaptive'
     userAgent: string
+    stream: boolean
+    uploadViaUrl: boolean
+    videoSupport: boolean
   }
   /** Ordered failover pool; array order is the priority, highest first. */
   providers: ResolvedProvider[]
@@ -262,6 +327,12 @@ export interface ResolvedVisionToolkitConfig {
   maxImageBytes: number
   maxImagePixels: number
   concurrency: number
+  objectStorage: {
+    endpoint: string
+    bucket: string
+    credential?: CredentialRef
+    publicBase?: string
+  }
   runtime: {
     mode: 'managed' | 'external'
     agentVisionToolkitPath?: string
@@ -276,6 +347,11 @@ export interface ResolvedVisionToolkitConfig {
     autoSwitch: boolean
     hidden: boolean
   }
+  toolVisibility: {
+    local: boolean
+    online: boolean
+    video: boolean
+  }
 }
 
 const MAX_TIMEOUT_SECONDS = 600
@@ -366,6 +442,9 @@ function resolveProvider(
   if (userAgent.length === 0) {
     throw new VisionToolkitError('config', `${label}.userAgent must not be empty`)
   }
+  const stream = input.stream === true
+  const uploadViaUrl = input.uploadViaUrl === true
+  const videoSupport = input.videoSupport === true
   const t1Seconds = input.t1Seconds ?? 90
   if (!Number.isInteger(t1Seconds) || t1Seconds < 1 || t1Seconds > MAX_TIMEOUT_SECONDS) {
     throw new VisionToolkitError('config', `${label}.t1Seconds must be an integer between 1 and ${MAX_TIMEOUT_SECONDS}`)
@@ -402,6 +481,9 @@ function resolveProvider(
     protocol,
     anthropicThinking,
     userAgent,
+    stream,
+    uploadViaUrl,
+    videoSupport,
     t1Seconds,
     t2Seconds,
     maxImageBytes,
@@ -472,10 +554,24 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
     .map(dir => dir.trim())
     .filter(dir => dir.length > 0 && dir !== storageDir))]
   const allowedDirs = (config.allowedDirs ?? []).map(dir => dir.trim()).filter(dir => dir.length > 0)
+  const objectStorageInput = config.objectStorage ?? {}
+  const objectStorageEndpoint = objectStorageInput.endpoint?.trim() ?? ''
+  const objectStorageBucket = objectStorageInput.bucket?.trim() ?? ''
+  const objectStoragePublicBase = objectStorageInput.publicBase?.trim()
+  let objectStorageCredential: CredentialRef | undefined
+  const objectStorageCredentialSource = objectStorageInput.credential?.trim()
+  if (objectStorageCredentialSource !== undefined && objectStorageCredentialSource.length > 0) {
+    try {
+      objectStorageCredential = credentialRef(objectStorageCredentialSource)
+    } catch (error) {
+      throw new VisionToolkitError('config', `objectStorage.credential "${objectStorageCredentialSource}" is not a valid credential reference`, { cause: error })
+    }
+  }
   const imageInputVariants = config.imageInputVariants ?? {}
   const variantProviders = (imageInputVariants.providers ?? [])
     .map(provider => provider.trim())
     .filter(provider => provider.length > 0)
+  const toolVisibility = config.toolVisibility ?? {}
   const providerDefaults: ProviderDefaults = { maxImageBytes, maxImagePixels, concurrency }
   const configuredProviders = config.providers ?? []
   if (configuredProviders.length > MAX_PROVIDERS) {
@@ -494,6 +590,9 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
       protocol: primary.protocol,
       anthropicThinking: primary.anthropicThinking,
       userAgent: primary.userAgent,
+      stream: primary.stream,
+      uploadViaUrl: primary.uploadViaUrl,
+      videoSupport: primary.videoSupport,
     },
     providers,
     language,
@@ -503,6 +602,12 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
     maxImageBytes,
     maxImagePixels,
     concurrency,
+    objectStorage: {
+      endpoint: objectStorageEndpoint,
+      bucket: objectStorageBucket,
+      ...(objectStorageCredential === undefined ? {} : { credential: objectStorageCredential }),
+      ...(objectStoragePublicBase === undefined || objectStoragePublicBase.length === 0 ? {} : { publicBase: objectStoragePublicBase }),
+    },
     runtime: {
       mode,
       ...(toolkitPath !== undefined ? { agentVisionToolkitPath: toolkitPath } : {}),
@@ -517,6 +622,11 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
       autoSwitch: imageInputVariants.autoSwitch ?? true,
       hidden: imageInputVariants.hidden ?? true,
     },
+    toolVisibility: {
+      local: toolVisibility.local ?? true,
+      online: toolVisibility.online ?? true,
+      video: toolVisibility.video ?? false,
+    },
   }
 }
 

package/src/exposure.ts

@@ -12,7 +12,7 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { defineTool, type ToolDefinition } from '@deepseek-ai/dsh-tools'
 import type { Context } from '@deepseek-ai/cordis'
 import { VISION_SKILLS_CONTENT, VISION_SKILLS_NAME } from './skill.ts'
-import { VISION_TOOL_NAMES } from './tools.ts'
+import { VISION_TOOL_NAMES, type ToolVisibility } from './tools.ts'
 
 /** Small bootstrap tool retained only until the current Agent gains visual tools. */
 export const VISION_TOOLKIT_ACTIVATE = 'vision_toolkit_activate'
@@ -139,17 +139,21 @@ export class VisionToolExposure {
 
   /**
    * @param ctx - Plugin context with Tool and Agent registries.
-   * @param createTools - Fresh definitions bound to the current runtime generation.
+   * @param createTools - Fresh definitions bound to the current runtime
+   *   generation, filtered by a tool-visibility snapshot.
+   * @param resolveVisibility - Live resolver for the current tool-visibility
+   *   snapshot; read once per activation (a session-head snapshot).
    */
   constructor(
     private readonly ctx: Context,
-    private readonly createTools: () => ToolDefinition[],
+    private readonly createTools: (snapshot: ToolVisibility) => ToolDefinition[],
+    private readonly resolveVisibility: () => ToolVisibility = () => ({ local: true, online: true, video: false }),
   ) {
     this.activationTool = defineTool({
       name: VISION_TOOLKIT_ACTIVATE,
-      description: `Activate the independent Vision Toolkit execution tools for this Agent: ${Object.values(VISION_TOOL_NAMES).join(', ')}. `
-        + `Loading the ${VISION_SKILLS_NAME} Skill normally activates them automatically; call this once when the visual tools are still absent, then use them for image understanding, OCR, UI detection, and related tasks. `
-        + 'It is safe to call before the Skill is loaded, and this activation tool disappears after success.',
+      description: `Report and (re)mount the Vision Toolkit execution tools for this Agent: the currently visible subset of ${Object.values(VISION_TOOL_NAMES).join(', ')} plus optional video understanding. `
+        + `The visual tool set is normally mounted automatically when the ${VISION_SKILLS_NAME} Skill loads; call this ONLY when the user explicitly asks you to refresh or reload the current session's vision tools, or to list which vision tools are currently available. `
+        + 'It restores the tool set to the latest Settings snapshot and returns the tool names actually mounted.',
       parameters: {},
       output: {
         schema: {
@@ -166,9 +170,12 @@ export class VisionToolExposure {
         if (exec.agent === undefined) {
           throw new Error(`${VISION_TOOLKIT_ACTIVATE}: an Agent Session is required`)
         }
-        return Promise.resolve(this.activate(exec.agent))
+        // An already-active Agent is reloaded (re-reads the latest Settings
+        // snapshot) rather than returning the stale set, so the tool genuinely
+        // refreshes the visible tool list on an explicit user request.
+        return Promise.resolve(this.reload(exec.agent))
       },
-      presentCall: () => ({ card: 'generic', title: 'Activate vision tools', kind: 'execute' }),
+      presentCall: () => ({ card: 'generic', title: 'Refresh or list vision tools', kind: 'execute' }),
     })
   }
 
@@ -222,7 +229,7 @@ export class VisionToolExposure {
     if (state === undefined) throw new Error(`dsh-vision-toolkit: Agent ${String(agent.id)} has no exposure state`)
     if (state.active) return { activated: false, tools: [...state.toolNames] }
 
-    const definitions = this.createTools()
+    const definitions = this.createTools(this.resolveVisibility())
     const toolDisposers: Array<() => void> = []
     try {
       for (const definition of definitions) toolDisposers.push(agent.ctx.tools.register(definition))
@@ -241,6 +248,24 @@ export class VisionToolExposure {
     return { activated: true, tools: [...state.toolNames] }
   }
 
+  /**
+   * Explicit refresh/reload from the bootstrap tool. An inactive Agent is
+   * mounted; an active Agent is torn down and re-mounted from the *current*
+   * Settings snapshot, so the returned tool list reflects the latest
+   * `toolVisibility` instead of the stale activation-time set.
+   */
+  private reload(agent: Agent): VisionToolkitActivationResult {
+    this.attach(agent)
+    const state = this.states.get(agent)
+    if (state === undefined) return { activated: false, tools: [] }
+    if (!state.active) return this.activate(agent)
+    // Dispose the current tool generation (including the hide-restriction on
+    // the bootstrap gauntlet) and rebuild from the fresh snapshot.
+    this.disposeState(state)
+    this.states.set(agent, { active: false, toolDisposers: [], toolNames: [] })
+    return this.activate(agent)
+  }
+
   /** Whether the session is attached to the live SessionStore (production). */
   private isLiveSession(session: Session): boolean {
     return this.ctx.sessions.get(session.id) === session

package/src/index.ts

@@ -83,11 +83,16 @@ export async function apply(ctx: Context, config: VisionToolkitConfig = {}): Pro
 
   const ensureOperational = (): void => {
     if (!manager.ready || operationalDisposers !== undefined) return
-    const exposure = new VisionToolExposure(ctx, () => createVisionTools(
-      () => manager.current(),
-      value => artifacts.presentationMeta(value),
-      lifecycle.signal,
-    ))
+    const exposure = new VisionToolExposure(
+      ctx,
+      (visibility) => createVisionTools(
+        () => manager.current(),
+        value => artifacts.presentationMeta(value),
+        lifecycle.signal,
+        visibility,
+      ),
+      () => manager.currentConfig().toolVisibility,
+    )
     let activationTool: (() => void) | undefined
     let exposureDisposer: (() => void) | undefined
     let skill: (() => void) | undefined

package/src/object-storage.ts

@@ -0,0 +1,174 @@
+/**
+ * Minimal S3-compatible object storage bridge used by the URL image-transfer
+ * path. It uploads one image, resolves a model-reachable URL (a configured
+ * public base URL or a temporary presigned URL), and deletes the object after
+ * the vision operation settles. It also provides the Settings "test storage"
+ * probe (upload → head → delete).
+ * @module dsh-vision-toolkit/object-storage
+ */
+
+import { createHash, randomUUID } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+  type S3ClientConfig,
+} from '@aws-sdk/client-s3'
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+import { VisionToolkitError } from './errors.ts'
+
+/** Fully resolved object-storage connection settings (secrets already filled). */
+export interface ObjectStorageSettings {
+  endpoint: string
+  bucket: string
+  accessKeyId: string
+  secretAccessKey: string
+  publicBase?: string
+}
+
+/** Whether the required connection fields are present enough to attempt a request. */
+export function isObjectStorageConfigured(settings: ObjectStorageSettings): boolean {
+  return settings.endpoint.length > 0
+    && settings.bucket.length > 0
+    && settings.accessKeyId.length > 0
+    && settings.secretAccessKey.length > 0
+}
+
+/** Stable object-key prefix so every upload lives under one deletable namespace. */
+const OBJECT_KEY_PREFIX = 'dsh-vision-toolkit'
+
+function encodeKey(key: string): string {
+  return key.split('/').map(encodeURIComponent).join('/')
+}
+
+function clientFor(settings: ObjectStorageSettings): S3Client {
+  const config: S3ClientConfig = {
+    region: 'auto',
+    forcePathStyle: true,
+    credentials: {
+      accessKeyId: settings.accessKeyId,
+      secretAccessKey: settings.secretAccessKey,
+    },
+  }
+  if (settings.endpoint.length > 0) config.endpoint = settings.endpoint
+  return new S3Client(config)
+}
+
+function publicError(error: unknown): string {
+  if (error instanceof Error) return error.message
+  return String(error)
+}
+
+/**
+ * One upload's worth of bookkeeping: the object key and the URL handed to the
+ * model. The key is returned to the runtime so it can delete the object after
+ * the operation settles.
+ */
+export interface UploadedObject {
+  key: string
+  url: string
+}
+
+/** A small S3-compatible object store bound to one bucket and credential. */
+export class ObjectStorageClient {
+  private client?: S3Client
+
+  constructor(private readonly settings: ObjectStorageSettings) {}
+
+  private requireClient(): S3Client {
+    if (this.client === undefined) this.client = clientFor(this.settings)
+    return this.client
+  }
+
+  /** Upload one local image file and resolve its model-reachable URL. */
+  async uploadImage(localPath: string, contentType: string): Promise<UploadedObject> {
+    const body = await readFile(localPath)
+    const digest = createHash('sha256').update(body).digest('hex').slice(0, 12)
+    const name = basename(localPath).replace(/[^A-Za-z0-9._-]/g, '_')
+    const key = `${OBJECT_KEY_PREFIX}/${randomUUID()}-${digest}-${name}`
+    try {
+      await this.requireClient().send(new PutObjectCommand({
+        Bucket: this.settings.bucket,
+        Key: key,
+        Body: body,
+        ContentType: contentType,
+      }))
+    } catch (error) {
+      throw new VisionToolkitError('service', `object storage upload failed: ${publicError(error)}`, { cause: error })
+    }
+    return { key, url: await this.urlFor(key) }
+  }
+
+  /** Resolve the model-reachable URL: public base URL when set, else presigned. */
+  async urlFor(key: string): Promise<string> {
+    if (this.settings.publicBase !== undefined && this.settings.publicBase.length > 0) {
+      return `${this.settings.publicBase}/${encodeKey(key)}`
+    }
+    try {
+      return await getSignedUrl(
+        this.requireClient(),
+        new GetObjectCommand({ Bucket: this.settings.bucket, Key: key }),
+        { expiresIn: 3600 },
+      )
+    } catch (error) {
+      throw new VisionToolkitError('service', `object storage presign failed: ${publicError(error)}`, { cause: error })
+    }
+  }
+
+  /** Delete one uploaded object; failures are logged, never fatal to the call. */
+  async deleteObject(key: string): Promise<void> {
+    try {
+      await this.requireClient().send(new DeleteObjectCommand({
+        Bucket: this.settings.bucket,
+        Key: key,
+      }))
+    } catch {
+      // Best-effort cleanup: a failed delete must not mask the vision result.
+    }
+  }
+
+  /** Settings "test storage" probe: upload a tiny object, head it, then delete it. */
+  async test(): Promise<{ detail: string }> {
+    if (!isObjectStorageConfigured(this.settings)) {
+      throw new VisionToolkitError('config', 'object storage is not fully configured (endpoint, bucket, access key id, and secret access key are required)')
+    }
+    const key = `${OBJECT_KEY_PREFIX}/.connection-test-${randomUUID()}`
+    const marker = `dsh-vision-toolkit object storage test ${Date.now()}`
+    try {
+      await this.requireClient().send(new PutObjectCommand({
+        Bucket: this.settings.bucket,
+        Key: key,
+        Body: marker,
+        ContentType: 'text/plain',
+      }))
+      await this.requireClient().send(new HeadObjectCommand({ Bucket: this.settings.bucket, Key: key }))
+      await this.requireClient().send(new DeleteObjectCommand({ Bucket: this.settings.bucket, Key: key }))
+    } catch (error) {
+      throw new VisionToolkitError('service', `object storage test failed: ${publicError(error)}`, { cause: error })
+    }
+    const urlMode = this.settings.publicBase !== undefined && this.settings.publicBase.length > 0
+      ? `public base ${this.settings.publicBase}`
+      : 'presigned URL'
+    return { detail: `bucket ${this.settings.bucket} reachable; model URLs will use ${urlMode}` }
+  }
+}
+
+/**
+ * Split a credential value of the form `accessKeyId:secretAccessKey` into its
+ * two parts. The access key id never contains a colon, so splitting on the
+ * first colon is safe.
+ */
+export function splitObjectStorageCredential(value: string): { accessKeyId: string; secretAccessKey: string } {
+  const index = value.indexOf(':')
+  if (index <= 0) {
+    throw new VisionToolkitError('config', 'object storage credential must be "accessKeyId:secretAccessKey"')
+  }
+  return {
+    accessKeyId: value.slice(0, index),
+    secretAccessKey: value.slice(index + 1),
+  }
+}

package/src/paths.ts

@@ -16,6 +16,12 @@ import { VisionToolkitError } from './errors.ts'
 /** Supported input image extensions (the upstream client's allowlist). */
 export const SUPPORTED_IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp'] as const
 
+/** Supported input video extensions probed with the bundled ffprobe binary. */
+export const SUPPORTED_VIDEO_EXTENSIONS = [
+  '.mp4', '.mov', '.webm', '.mkv', '.avi', '.m4v',
+  '.mpg', '.mpeg', '.wmv', '.flv', '.ts', '.m2ts', '.3gp',
+] as const
+
 /** Resolved path policy for one tool invocation. */
 export interface PathPolicy {
   /** Real workspace root. */
@@ -399,6 +405,11 @@ export function resolveHtmlFile(raw: string, policy: PathPolicy): Promise<{ path
   return resolveAuthorizedFile(raw, policy, ['.html', '.htm'], 'HTML source')
 }
 
+/** Validate one input video path against the video extension allowlist. */
+export function resolveInputVideo(raw: string, policy: PathPolicy): Promise<{ path: string; bytes: number }> {
+  return resolveAuthorizedFile(raw, policy, SUPPORTED_VIDEO_EXTENSIONS, 'video')
+}
+
 /**
  * Resolve an optional user-supplied output filename inside the plugin output
  * directory. Absolute paths, `..` segments, and wrong extensions are rejected.