@mengruo/dsh-vision-toolkit 0.1.3 → 0.1.5

package/src/storage-history.ts

@@ -0,0 +1,172 @@
+/** Durable configured-storage history used to authorize persisted image paths after Profile restarts. */
+
+import type { Context, Fiber } from '@deepseek-ai/cordis'
+import { defineDomain } from '@deepseek-ai/dsh-storage-domain'
+import type { DomainGlobal } from '@deepseek-ai/dsh-storage-domain'
+import { z } from 'zod'
+import { resolveConfig, type VisionToolkitConfig } from './config.ts'
+
+const storageHistoryStateSchema = z.object({
+  roots: z.array(z.string().min(1)),
+})
+
+type StorageHistoryState = z.infer<typeof storageHistoryStateSchema>
+
+/** Plugin-owned storage roots that survive Settings-provider and Profile restarts. */
+export const storageHistoryDomainSpec = defineDomain({
+  name: 'vision_toolkit_storage',
+  version: 0,
+  global: {
+    schema: storageHistoryStateSchema,
+    initial: { roots: [] },
+  },
+  tables: {},
+})
+
+interface StorageBinding {
+  accepting: boolean
+  global: DomainGlobal<StorageHistoryState>
+}
+
+function sameRoots(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((root, index) => root === right[index])
+}
+
+/**
+ * Return every configured root that must remain readable, including the active root.
+ * @param config - Settings generation to summarize.
+ * @returns normalized configured roots in retention order.
+ */
+export function configuredStorageRoots(config: VisionToolkitConfig): string[] {
+  const resolved = resolveConfig(config)
+  return [...new Set([
+    ...resolved.storageHistory,
+    ...(resolved.storageDir === undefined ? [] : [resolved.storageDir]),
+  ])]
+}
+
+/**
+ * Merge plugin-owned roots into a Settings generation without retaining its active root as history.
+ * @param config - Settings generation being restored.
+ * @param durableRoots - roots loaded from the plugin-owned sidecar.
+ * @returns the original generation when unchanged, otherwise a generation with restored history.
+ */
+export function restoreDurableStorageHistory(
+  config: VisionToolkitConfig,
+  durableRoots: readonly string[],
+): VisionToolkitConfig {
+  const resolved = resolveConfig(config)
+  const storageHistory = [...new Set([...resolved.storageHistory, ...durableRoots])]
+    .filter(root => root !== resolved.storageDir)
+  if (sameRoots(storageHistory, resolved.storageHistory)) return config
+  return { ...config, storageHistory }
+}
+
+/** Optional storage-domain sidecar for storage roots that Settings cannot persist itself. */
+export class StorageHistoryStore {
+  private storage: StorageBinding | undefined
+  private storageFiber: (Fiber & PromiseLike<Fiber>) | undefined
+  private storageReady: Promise<void> | undefined
+  private mutationTail: Promise<void> = Promise.resolve()
+  private desiredRoots: readonly string[] | undefined
+  private persistenceTicket = 0
+  private warned = false
+
+  constructor(private readonly ctx: Context) {
+    if (typeof ctx.inject !== 'function') return
+    this.storageFiber = ctx.inject(['storageDomain'], async (storageCtx: Context) => {
+      const domain = await storageCtx.storageDomain.open(storageHistoryDomainSpec)
+      const binding: StorageBinding = { accepting: true, global: domain.global }
+      this.storage = binding
+      try {
+        if (this.desiredRoots !== undefined) {
+          await this.write(binding, this.desiredRoots, this.persistenceTicket)
+        }
+      } catch (error) {
+        this.storage = undefined
+        await domain.close()
+        throw error
+      }
+      return async () => {
+        binding.accepting = false
+        if (this.storage === binding) this.storage = undefined
+        await this.mutationTail
+        await domain.close()
+      }
+    })
+    this.storageReady = Promise.resolve(this.storageFiber).then(
+      () => undefined,
+      (error: unknown) => { this.warnOnce(error) },
+    )
+  }
+
+  /**
+   * Restore durable roots into one Settings generation before runtime preparation.
+   * @param config - Settings generation to restore.
+   * @returns the generation with available durable roots merged into its history.
+   */
+  async restore(config: VisionToolkitConfig): Promise<VisionToolkitConfig> {
+    const binding = await this.prepareStorage()
+    return restoreDurableStorageHistory(config, binding?.global.get().roots ?? [])
+  }
+
+  /**
+   * Persist the active and historical configured roots.
+   * @param config - validated generation whose roots must survive restart.
+   * @returns false when no storage-domain is available; true after persistence or when there are no roots.
+   */
+  async persist(config: VisionToolkitConfig): Promise<boolean> {
+    const roots = configuredStorageRoots(config)
+    const ticket = ++this.persistenceTicket
+    this.desiredRoots = roots
+    if (roots.length === 0) return true
+    const binding = await this.prepareStorage()
+    if (binding === undefined) return false
+    await this.write(binding, roots, ticket)
+    return true
+  }
+
+  /** Release the optional storage-domain binding with the plugin lifecycle. */
+  dispose(): void {
+    const fiber = this.storageFiber
+    this.storageFiber = undefined
+    this.storageReady = undefined
+    if (fiber !== undefined) void fiber.dispose().catch(error => { this.warnOnce(error) })
+  }
+
+  private async prepareStorage(): Promise<StorageBinding | undefined> {
+    const current = this.activeStorage()
+    if (current !== undefined) return current
+    if (this.ctx.get('storageDomain') === undefined) return undefined
+    await this.storageReady
+    return this.activeStorage()
+  }
+
+  private activeStorage(): StorageBinding | undefined {
+    return this.storage?.accepting === true ? this.storage : undefined
+  }
+
+  private write(binding: StorageBinding, roots: readonly string[], ticket: number): Promise<void> {
+    return this.enqueueMutation(async () => {
+      if (!binding.accepting) throw new Error('the storage-domain provider changed while storage history was pending')
+      if (ticket !== this.persistenceTicket) return
+      if (sameRoots(binding.global.get().roots, roots)) return
+      await binding.global.set({ roots: [...roots] })
+    })
+  }
+
+  private enqueueMutation(operation: () => Promise<void>): Promise<void> {
+    const result = this.mutationTail.then(operation)
+    this.mutationTail = result.then(() => undefined, () => undefined)
+    return result
+  }
+
+  private warnOnce(error: unknown): void {
+    if (this.warned) return
+    this.warned = true
+    this.ctx.logger?.warn(
+      'dsh-vision-toolkit: configured storage history sidecar is unavailable. %s',
+      (error instanceof Error ? error.message : String(error)).slice(0, 500),
+    )
+  }
+}

package/src/upstream.ts

@@ -41,6 +41,7 @@ export interface UpstreamEnvironment {
   VISION_API_PROTOCOL: 'chat_completions' | 'anthropic'
   VISION_ANTHROPIC_THINKING: 'omit' | 'disabled' | 'adaptive'
   VISION_SSL_VERIFY?: string
+  VISION_STREAM?: string
   VISION_USER_AGENT: string
   LANG: 'zh' | 'en'
 }
@@ -761,6 +762,9 @@ export class UpstreamAdapter {
           ...(options.env.VISION_SSL_VERIFY === undefined
             ? {}
             : { VISION_SSL_VERIFY: options.env.VISION_SSL_VERIFY }),
+          ...(options.env.VISION_STREAM === undefined
+            ? {}
+            : { VISION_STREAM: options.env.VISION_STREAM }),
           VISION_USER_AGENT: options.env.VISION_USER_AGENT,
           LANG: options.env.LANG,
           VISION_ENV_FILE: join(prepared.cleanHome, 'vision.env'),
@@ -1059,22 +1063,47 @@ export class UpstreamAdapter {
       return new VisionToolkitError('output', `${tool}: upstream output exceeded the capture limit`)
     }
     const message = upstreamFailureMessage(tool, result.stderr, options.secrets ?? [])
-    if (/HTTP 401|\b401\b|Unauthorized|authentication/i.test(result.stderr)) {
-      return new VisionToolkitError('service', `${message}; verify the configured credential`)
+    const stderr = result.stderr
+
+    // Remote provider failures, classified into a machine-routable taxonomy so
+    // the failover loop retries transient errors and fails over immediately on
+    // deterministic ones. Order matters: auth/quota/rate-limit/region/tos are
+    // checked before the broader server/network/request-shape patterns.
+    if (/HTTP 401|\b401\b|HTTP 403|\b403\b|Unauthorized|Forbidden|authentication|Invalid API-key|invalid api key|check the api key/i.test(stderr)) {
+      return new VisionToolkitError('auth', `${message}; verify the configured credential`)
+    }
+    if (/HTTP 402|\b402\b|Payment Required|insufficient balance|insufficient quota|insufficient credits|billing|out of credits|out of quota/i.test(stderr)) {
+      return new VisionToolkitError('quota', `${message}; the provider account is out of quota or unpaid`)
     }
-    if (/HTTP 429|\b429\b|rate limit|quota/i.test(result.stderr)) {
+    if (/HTTP 429|\b429\b|rate ?limit|too many requests/i.test(stderr)) {
       return new VisionToolkitError('rate_limit', `${message}; retry later or reduce concurrency`)
     }
-    if (/Missing config VISION_/i.test(result.stderr)) {
+    if (/not available in your region|prohibited region|unsupported region|region is not supported/i.test(stderr)) {
+      return new VisionToolkitError('region', `${message}; the provider is not available in this region`)
+    }
+    if (/terms of service|\btos\b|content policy|safety system/i.test(stderr)) {
+      return new VisionToolkitError('tos', `${message}; the request was rejected by the provider content policy`)
+    }
+    if (/HTTP 5\d\d|\b500\b|\b502\b|\b503\b|\b504\b|bad gateway|service unavailable|internal server error/i.test(stderr)) {
+      return new VisionToolkitError('server', `${message}; the provider returned a server error`)
+    }
+    if (/connection refused|connection reset|ECONN|ENOTFOUND|EAI_AGAIN|getaddrinfo|fetch failed|name resolution|network error|network is unreachable/i.test(stderr)) {
+      return new VisionToolkitError('network', `${message}; network failure reaching the provider`)
+    }
+    if (/HTTP 400|\b400\b|HTTP 404|\b404\b|HTTP 422|\b422\b|invalid request|invalid model|no such model|model not exist|unknown model/i.test(stderr)) {
+      return new VisionToolkitError('invalid_request', `${message}; the request or model is not supported by this provider`)
+    }
+
+    if (/Missing config VISION_/i.test(stderr)) {
       return new VisionToolkitError('config', message)
     }
-    if (/maxImagePixels|exceed(?:s|ing).*pixels/i.test(result.stderr)) {
+    if (/maxImagePixels|exceed(?:s|ing).*pixels/i.test(stderr)) {
       return new VisionToolkitError('capacity', message)
     }
-    if (/not found|only PNG|unsupported|cannot open|empty region|must be|expects|invalid colour|needs at least/i.test(result.stderr)) {
+    if (/not found|only PNG|unsupported|cannot open|empty region|must be|expects|invalid colour|needs at least/i.test(stderr)) {
       return new VisionToolkitError('input', message)
     }
-    if (/requires Pillow|requires numpy|requires vtracer|no Chrome|capture failed/i.test(result.stderr)) {
+    if (/requires Pillow|requires numpy|requires vtracer|no Chrome|capture failed/i.test(stderr)) {
       return new VisionToolkitError('runtime', message)
     }
     return new VisionToolkitError(

package/src/web.ts

@@ -22,6 +22,7 @@ import {
 } from './paste-images.ts'
 import {
   resolveConfig,
+  retainedStorageHistory,
   isBuiltInFreeVisionProvider,
   VISION_TOOLKIT_SETTINGS_NAMESPACE,
   type ResolvedProvider,
@@ -74,6 +75,12 @@ export interface VisionToolkitSettingsSnapshot {
     source?: string
     writable: boolean
   }>
+  /** Object-storage credential state; `ref` is empty when object storage is unset. */
+  objectStorageCredential: {
+    ref: string
+    configured: boolean
+    writable: boolean
+  }
   runtime: RuntimeManagerStatus
   release: {
     pluginVersion: string
@@ -120,7 +127,11 @@ interface ApplyUpdateRequest {
   expectedVersion: string
 }
 
-type SettingsRequest = SaveRequest | HealthRequest | CredentialRequest | DeleteCredentialRequest | CheckUpdateRequest | ApplyUpdateRequest
+interface StorageTestRequest {
+  action: 'test-storage'
+}
+
+type SettingsRequest = SaveRequest | HealthRequest | CredentialRequest | DeleteCredentialRequest | CheckUpdateRequest | ApplyUpdateRequest | StorageTestRequest
 
 interface JsonError {
   ok: false
@@ -260,6 +271,7 @@ function parseRequest(value: unknown): SettingsRequest {
     }
     return { action: 'apply-update', expectedVersion: value.expectedVersion.trim() }
   }
+  if (value.action === 'test-storage') return { action: 'test-storage' }
   throw new TypeError(`unsupported action: ${value.action}`)
 }
 
@@ -314,6 +326,14 @@ export class VisionToolkitWebBackend {
         writable: info.writable,
       }
     }))
+    const objectStorageRef = resolved.objectStorage.credential === undefined ? '' : String(resolved.objectStorage.credential)
+    const objectStorageCredential = objectStorageRef === ''
+      ? { ref: '', configured: false, writable: this.ctx.settings.writable }
+      : await this.ctx.credentials.describe(credentialRef(objectStorageRef)).then(info => ({
+        ref: objectStorageRef,
+        configured: info.configured,
+        writable: info.writable,
+      }))
     const update = await this.updater.capability()
     return {
       schemaVersion: 1,
@@ -332,6 +352,7 @@ export class VisionToolkitWebBackend {
         writable: credential.writable,
       },
       credentials,
+      objectStorageCredential,
       runtime: this.manager.status(),
       release: {
         pluginVersion: PLUGIN_VERSION,
@@ -346,16 +367,22 @@ export class VisionToolkitWebBackend {
 
   private async save(request: SaveRequest): Promise<VisionToolkitSettingsSnapshot> {
     if (!this.ctx.settings.writable) throw new Error('settings provider is read-only')
+    const current = resolveConfig(descriptorOf(this.ctx).value as VisionToolkitConfig)
+    const storageHistory = retainedStorageHistory(request.value, current)
+    const value: VisionToolkitConfig = {
+      ...request.value,
+      ...(storageHistory.length === 0 ? {} : { storageHistory }),
+    }
     let candidate: PreparedRuntimeGeneration
     try {
-      candidate = await this.manager.prepareCandidate(request.value)
+      candidate = await this.manager.prepareCandidate(value)
     } catch (error) {
       this.manager.recordFailure(error)
       throw error
     }
     await this.ctx.settings.replace(
       VISION_TOOLKIT_SETTINGS_NAMESPACE,
-      request.value as object,
+      value as object,
       request.expectedRevision,
     )
     this.manager.activateCandidate(candidate)
@@ -373,10 +400,18 @@ export class VisionToolkitWebBackend {
       )
     }
     const resolved = resolveConfig(descriptor.value as VisionToolkitConfig)
-    const provider = resolved.providers.find(entry => String(entry.credential) === String(request.ref))
+    const ref = String(request.ref)
+    if (resolved.objectStorage.credential !== undefined && String(resolved.objectStorage.credential) === ref) {
+      if (!request.value.includes(':')) {
+        throw new Error('object storage credential must be "accessKeyId:secretAccessKey"')
+      }
+      await this.ctx.credentials.set(request.ref, request.value)
+      return this.snapshot()
+    }
+    const provider = resolved.providers.find(entry => String(entry.credential) === ref)
     if (provider === undefined) {
       throw new CredentialReferenceConflictError(
-        `credential reference "${String(request.ref)}" does not match any configured vision provider; reload Settings and try again`,
+        `credential reference "${ref}" does not match any configured vision provider; reload Settings and try again`,
       )
     }
     if (isBuiltInFreeVisionProvider(provider)) {
@@ -419,6 +454,11 @@ export class VisionToolkitWebBackend {
     }
   }
 
+  private async testStorage(): Promise<{ detail: string }> {
+    if (!this.manager.ready) throw new Error('runtime is not ready; fix Settings and save a valid configuration first')
+    return this.manager.current().testObjectStorage()
+  }
+
   /** Handle the exact Settings route. */
   async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
     if (req.method === 'GET') {
@@ -451,6 +491,9 @@ export class VisionToolkitWebBackend {
         case 'health':
           responseJson(res, 200, { ok: true, value: await this.health(parsed, req) })
           break
+        case 'test-storage':
+          responseJson(res, 200, { ok: true, value: await this.testStorage() })
+          break
         case 'save':
           responseJson(res, 200, { ok: true, value: await this.save(parsed) })
           break
@@ -479,14 +522,16 @@ export class VisionToolkitWebBackend {
             ? error.code
           : parsed.action === 'health'
             ? 'health-failed'
-            : parsed.action === 'credential'
-              ? 'credential-rejected'
-              : 'settings-rejected'
+            : parsed.action === 'test-storage'
+              ? 'storage-test-failed'
+              : parsed.action === 'credential'
+                ? 'credential-rejected'
+                : 'settings-rejected'
       const updateConflict = updateError && ['update-in-progress', 'update-stale', 'update-unavailable', 'already-current'].includes(error.code)
       const updateGateway = updateError && error.code === 'update-check-failed'
       const status = settingsConflict || credentialConflict || updateConflict
         ? 409
-        : parsed.action === 'health'
+        : parsed.action === 'health' || parsed.action === 'test-storage'
           ? 503
           : updateGateway
             ? 502

package/vendor/agent-vision-toolkit/UPSTREAM_MANIFEST.json

@@ -3,7 +3,7 @@
   "repository": "https://github.com/Anionex/agent-vision-toolkit",
   "version": "v0.1.0+snapshot.bc9803d",
   "commit": "bc9803d7d6300c864d17460ecbb33540b26638e0",
-  "contentSha256": "0eaa22a0d1d0dd6d6523a0ddd3fa8197246005042bc164a703fb05102b287a38",
+  "contentSha256": "09bedf007e1469a28981227def5aa33e03667ea21fe2972937f0359898e2928e",
   "files": [
     {
       "path": "CHANGELOG.md",
@@ -32,8 +32,8 @@
     },
     {
       "path": "bin/glance",
-      "bytes": 3742,
-      "sha256": "fa4ba52e8e180475b948daec817151d893d957f973f7d9df1b8bbf201051cefc"
+      "bytes": 3941,
+      "sha256": "7552bef0ba396162f64e8fc4c4a53404dfe2d3149ca3d1c5c8bd717facf82af6"
     },
     {
       "path": "bin/ground",
@@ -47,13 +47,13 @@
     },
     {
       "path": "detect.py",
-      "bytes": 2218,
-      "sha256": "48a7070084f5b23b1477fa9a690ef1e679da8a03228e64a1ac583de633040bfc"
+      "bytes": 2532,
+      "sha256": "cac2135f9d835215f3ba90bfd70fd84dd02b0e88299f2b60e109e006b4f3a4d9"
     },
     {
       "path": "ground.py",
-      "bytes": 10117,
-      "sha256": "845e56dbdf92f2c79495170f5d215de49985b3099012b4d398231d3c78bd0090"
+      "bytes": 11289,
+      "sha256": "6d3175d3f5a7d561d55b2a967c5ca3d49940e80014de658ed9a3e5d45a233a2f"
     },
     {
       "path": "skills/vision-tools/scripts/dominant_colors.py",
@@ -82,13 +82,13 @@
     },
     {
       "path": "tests/test_vision_client.py",
-      "bytes": 20481,
-      "sha256": "b019f0da28b7567226292044f791059ee34d7f0088bd9ceb328cfa1bab250a48"
+      "bytes": 24882,
+      "sha256": "87e39429766b38caed6a4ccb1ac8b193094c69858a0f7541940a005f66421e45"
     },
     {
       "path": "vision_client.py",
-      "bytes": 11838,
-      "sha256": "c6a48048c864e99513faf90ba17c4ac0d9462bb718683682ed8eda12c0e2cfe0"
+      "bytes": 15053,
+      "sha256": "6800843b99df500a476b1dd6ff5a4c05aa8122ed990f6f91b16a11ee07bdebe6"
     }
   ]
 }

package/vendor/agent-vision-toolkit/bin/glance

@@ -40,6 +40,13 @@ def region_data_url(path, region):
     return "data:image/png;base64," + base64.b64encode(buffer.getvalue()).decode()
 
 
+def image_url(path):
+    """Pass http(s) URLs through unchanged; encode local files as data URLs."""
+    if path.startswith(("http://", "https://")):
+        return path
+    return image_path_to_data_url(path)
+
+
 def build_prompt(args, count):
     if args.ocr is not None:
         extra = f" Additional requirements: {args.ocr}" if args.ocr else ""
@@ -77,7 +84,7 @@ def main():
         if args.region and len(args.images) > 1:
             raise VisionError("--region works with exactly one image")
         urls = ([region_data_url(args.images[0], args.region)] if args.region
-                else [image_path_to_data_url(path) for path in args.images])
+                else [image_url(path) for path in args.images])
         answer = describe_image(
             urls,
             build_prompt(args, len(urls)),

package/vendor/agent-vision-toolkit/detect.py

@@ -8,7 +8,7 @@ try:
 except ImportError:
     Image = None
 
-from ground import GroundError, _position, locate
+from ground import GroundError, _parse_size, _position, locate
 from vision_client import VisionError
 
 DEFAULT_CATEGORY = ("UI element (buttons, links, inputs, icons, labels, "
@@ -38,18 +38,24 @@ def main() -> None:
         prog="detect",
         description="Inventory the elements in an image (or a region) with pixel bounding boxes",
     )
-    parser.add_argument("image", type=Path, help="path to the image")
+    parser.add_argument("image", help="path or http(s) URL to the image")
     parser.add_argument("category", nargs="?",
                         help='restrict to a category, e.g. "buttons" or "icons" (default: all UI elements)')
     parser.add_argument("--region", metavar="X1,Y1,X2,Y2",
                         help="inventory only this pixel box; output stays in original-image coordinates")
+    parser.add_argument("--size", metavar="WxH",
+                        help="analyzed image dimensions when the image is an http(s) URL")
     args = parser.parse_args()
     try:
-        matches = locate(args.image.expanduser(), build_target(args.category), region=args.region)
-        if Image is None:
-            raise GroundError("detect requires Pillow; install the optional dependency pillow first")
-        with Image.open(args.image.expanduser()) as image:
-            width, height = image.size
+        size = _parse_size(args.size) if args.size else None
+        matches = locate(args.image, build_target(args.category), region=args.region, size=size)
+        if size is not None:
+            width, height = size
+        else:
+            if Image is None:
+                raise GroundError("detect requires Pillow; install the optional dependency pillow first")
+            with Image.open(Path(args.image).expanduser()) as image:
+                width, height = image.size
     except (GroundError, VisionError) as exc:
         parser.exit(1, f"detect: {exc}\n")
     for line in format_inventory(matches, width, height):

package/vendor/agent-vision-toolkit/ground.py

@@ -184,23 +184,32 @@ def _parse_region(region: str, width: int, height: int) -> tuple[int, int, int,
     return box
 
 
-def locate(image_path: Path, target: str, region: str | None = None) -> list[Match]:
+def locate(image_path: str, target: str, region: str | None = None,
+           size: tuple[int, int] | None = None) -> list[Match]:
     if Image is None:
         raise GroundError("ground requires Pillow; install the optional dependency pillow first")
     load_default_env()
     box = None
-    try:
-        with Image.open(image_path) as image:
-            width, height = image.size
-            if region:
-                box = _parse_region(region, width, height)
-                buffer = io.BytesIO()
-                image.crop(box).save(buffer, format="PNG")
-                url = "data:image/png;base64," + base64.b64encode(buffer.getvalue()).decode()
-    except (OSError, ValueError) as exc:
-        raise GroundError(f"Cannot read image: {image_path}") from exc
+    if size is not None:
+        # URL transfer: the image was uploaded to object storage and this caller
+        # supplies the analyzed dimensions, so no local file access is needed.
+        width, height = size
+        url = image_path if image_path.startswith(("http://", "https://")) else image_path_to_data_url(image_path)
+    else:
+        local = Path(image_path).expanduser()
+        try:
+            with Image.open(local) as image:
+                width, height = image.size
+                if region:
+                    box = _parse_region(region, width, height)
+                    buffer = io.BytesIO()
+                    image.crop(box).save(buffer, format="PNG")
+                    url = "data:image/png;base64," + base64.b64encode(buffer.getvalue()).decode()
+        except (OSError, ValueError) as exc:
+            raise GroundError(f"Cannot read image: {image_path}") from exc
+        if box is None:
+            url = image_path_to_data_url(local)
     if box is None:
-        url = image_path_to_data_url(image_path)
         width_used, height_used = width, height
     else:
         width_used, height_used = box[2] - box[0], box[3] - box[1]
@@ -216,6 +225,16 @@ def locate(image_path: Path, target: str, region: str | None = None) -> list[Mat
                             m.bbox[2] + box[0], m.bbox[3] + box[1])) for m in matches]
 
 
+def _parse_size(value: str) -> tuple[int, int]:
+    try:
+        width, height = (int(part) for part in value.lower().split("x"))
+    except (ValueError, AttributeError):
+        raise GroundError("--size expects WIDTHxHEIGHT (e.g. 1024x768)") from None
+    if width <= 0 or height <= 0:
+        raise GroundError("--size expects positive WIDTHxHEIGHT")
+    return width, height
+
+
 def _position(box: tuple[int, int, int, int], width: int, height: int) -> str:
     x1, y1, x2, y2 = box
     x = (x1 + x2) / 2
@@ -246,17 +265,23 @@ def main() -> None:
         prog="ground",
         description="Locate targets in an image with natural language and output pixel coordinates",
     )
-    parser.add_argument("image", type=Path, help="path to the image")
+    parser.add_argument("image", help="path or http(s) URL to the image")
     parser.add_argument("target", help="target object or region to locate")
     parser.add_argument("--region", metavar="X1,Y1,X2,Y2",
                         help="search only this pixel box; output stays in original-image coordinates")
+    parser.add_argument("--size", metavar="WxH",
+                        help="analyzed image dimensions when the image is an http(s) URL")
     args = parser.parse_args()
     try:
-        matches = locate(args.image.expanduser(), args.target, region=args.region)
-        if Image is None:
-            raise GroundError("ground requires Pillow; install the optional dependency pillow first")
-        with Image.open(args.image.expanduser()) as image:
-            width, height = image.size
+        size = _parse_size(args.size) if args.size else None
+        matches = locate(args.image, args.target, region=args.region, size=size)
+        if size is not None:
+            width, height = size
+        else:
+            if Image is None:
+                raise GroundError("ground requires Pillow; install the optional dependency pillow first")
+            with Image.open(Path(args.image).expanduser()) as image:
+                width, height = image.size
     except (GroundError, VisionError) as exc:
         parser.exit(1, f"ground: {exc}\n")
     for line in format_matches(matches, width, height):