@cloudglue/tinycloud 0.3.6 → 0.3.7

package/README.md

@@ -1,9 +1,10 @@
 # Tinycloud
 
-Agent CLI for deep video work. Point it at videos and ask for analysis,
-dashboards, subtitles, clips, search, or repurposed content — or drive its
-verbs directly from your own agent. Powered by [Cloudglue](https://cloudglue.dev).
-Learn more at [tinycloud.sh](https://tinycloud.sh).
+Agent CLI for deep video and image work. Point it at videos or images and ask
+for analysis, dashboards, subtitles, clips, search, or repurposed content — or
+drive its verbs directly from your own agent. Powered by
+[Cloudglue](https://cloudglue.dev). Learn more at
+[tinycloud.sh](https://tinycloud.sh).
 
 ## Install
 
@@ -16,11 +17,11 @@ The npm package is a small launcher: on first run it downloads the matching
 platform distribution from Cloudglue's CDN (cached under
 `~/.tinycloud/versions/<version>/`), verifies its checksum, and execs the real
 binary. The package version pins the binary version, so
-`npx @cloudglue/tinycloud@0.3.6` always runs tinycloud 0.3.6. It also adds two
+`npx @cloudglue/tinycloud@0.3.7` always runs tinycloud 0.3.7. It also adds two
 wrapper commands:
 
 ```bash
-tinycloud install --version 0.3.6   # pre-download a version
+tinycloud install --version 0.3.7   # pre-download a version
 tinycloud install --latest          # install latest stable and pin to it
 tinycloud update                    # move to latest stable, prune old versions
 ```
@@ -116,7 +117,8 @@ go to stderr) — pass `--json`.
 | Command | What it does |
 |---|---|
 | `watch` | Analyze a video → reusable cached context + Cloudglue-ready ref |
-| `extract` | Pull structured facts, entities, or moments (free-form or JSON-schema) |
+| `see` | Analyze an image → reusable cached context + Cloudglue-ready ref (JPEG/PNG/WebP) |
+| `extract` | Pull structured facts, entities, or moments from a video or image (free-form or JSON-schema) |
 | `caption` | Subtitles and transcripts (SRT/VTT/ASS) |
 | `search` | Keyword search over cached video context |
 | `probe` | Semantic moment/video search over a Cloudglue scope |
@@ -135,8 +137,12 @@ A few common invocations:
 ```bash
 # Analyze a video into reusable, cached context + a Cloudglue-ready ref
 tinycloud watch ./demo.mp4 --json
+# Describe an image — the file-level counterpart of watch (JPEG/PNG/WebP)
+tinycloud see ./photo.jpg --json
 # Pull structured findings (free-form query here; pass --schema for a fixed shape)
 tinycloud extract "key moments with timestamps" ./demo.mp4 --json
+# extract also works on an image source (no segment/shot flags on images)
+tinycloud extract "on-screen text and key objects" ./photo.png --json
 # Subtitles plus a markdown transcript
 tinycloud caption ./demo.mp4 --format srt --transcript --json
 # Trim a clip locally — no upload, ffmpeg-backed

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloudglue/tinycloud",
-  "version": "0.3.6",
-  "description": "Agent CLI for deep video work, by Cloudglue. Downloads the tinycloud binary on first run.",
+  "version": "0.3.7",
+  "description": "Agent CLI for deep video and image work, by Cloudglue. Downloads the tinycloud binary on first run.",
   "bin": {
     "tinycloud": "bin/tinycloud.js"
   },

package/skills/tinycloud/SKILL.md

@@ -1,15 +1,17 @@
 ---
 name: tinycloud
 description: >-
-  Deep video work via the tinycloud CLI (Cloudglue). Use whenever the task
-  involves understanding or manipulating video or audio-visual media: analyze
-  or summarize a video, extract structured facts/moments/entities, generate
-  captions or transcripts (SRT/VTT), search inside videos, answer questions
-  about footage, cut/stitch/thumbnail/transcode clips, download remote videos,
-  browse Cloudglue collections, or run packaged video workflows. Triggers on
-  video files (.mp4, .mov, .webm, ...), YouTube/video URLs, Cloudglue
-  collections, or any "what's in this video / make clips / caption this"
-  request. Every command returns a machine-readable JSON envelope.
+  Deep video and image work via the tinycloud CLI (Cloudglue). Use whenever the
+  task involves understanding or manipulating video, audio-visual media, or
+  images: analyze or summarize a video, describe or analyze an image, extract
+  structured facts/moments/entities from a video or image, generate captions or
+  transcripts (SRT/VTT), search inside videos, answer questions about footage,
+  cut/stitch/thumbnail/transcode clips, download remote videos, browse Cloudglue
+  collections, or run packaged video workflows. Triggers on video files (.mp4,
+  .mov, .webm, ...), image files (.jpg, .png, .webp), YouTube/video URLs,
+  Cloudglue collections, or any "what's in this video / describe this image /
+  make clips / caption this" request. Every command returns a machine-readable
+  JSON envelope.
 ---
 
 # Tinycloud: video operations for agents
@@ -61,7 +63,7 @@ Full schema and error codes: [reference/envelope.md](reference/envelope.md).
 
 ## 2. Core verbs (cheat sheet)
 
-Cloud verbs (`watch extract probe ask publish face`) call the Cloudglue API
+Cloud verbs (`watch see extract probe ask publish face`) call the Cloudglue API
 using the configured key — usage is billed per the
 [rate card](https://app.cloudglue.dev/home/billing/rate-card). `search clip
 setup` are local and free; `grab jobs` are network-only.
@@ -71,9 +73,14 @@ setup` are local and free; `grab jobs` are network-only.
 # Understand a video (creates reusable cached context + cloud-ready ref)
 tinycloud watch ./demo.mp4 --json
 
+# Understand an image — the file-level counterpart of watch (0.3.7+, JPEG/PNG/WebP)
+tinycloud see ./photo.jpg --json
+
 # Pipe context into structured extraction (JSONL flows between pipes)
 tinycloud watch ./demo.mp4 --json | tinycloud extract "key moments with timestamps" --json
 tinycloud extract --schema ./schema.json ./demo.mp4 --segment-level --json
+# extract also takes an image source (0.3.7+) — no segment/shot flags on images
+tinycloud extract "on-screen text and key objects" ./photo.png --json
 
 # Captions / transcripts
 tinycloud caption ./demo.mp4 --format srt --transcript -o ./tinycloud-output/captions/ --json
@@ -166,8 +173,16 @@ Authoring your own recipes: [reference/workflow-authoring.md](reference/workflow
 - Sources: local paths, URLs, `cloudglue://files/<id>` URIs,
   `collection:col_…`, or a bare Cloudglue file-id UUID (normalized to
   `cloudglue://files/<id>`; an existing local path of the same name wins).
+- Images (0.3.7+): use `see` to describe an image and `extract` to pull
+  structured data from one — **JPEG/PNG/WebP only** (HEIC/GIF/BMP are rejected
+  with a "transcode first" hint). `watch <image>` and `caption <image>` error
+  and redirect you to `see`/`extract` (an image has no video track to analyze
+  or speech to caption); images have no segments, so drop `--segment-level`/
+  `--segmentation`/`--shot-*` on an image source. A local image uploads first; a
+  public `http(s)` image URL is analyzed in place (no upload). Images can't be
+  added to collections. Local `search` can match cached `see` results.
 - Do not pass `--background` to `ask`; background jobs exist only for tracked
-  async ops (`watch`, `extract`).
+  async ops (`watch`, `see`, `extract`).
 - `workflow status` / `workflow resume` are not implemented in 0.3.x; treat
   `paused`/`partial` as terminal and surface `resume` metadata to the user.
 - `--no-upload` / `--no-download` make commands refuse cloud upload / local

package/skills/tinycloud/reference/glossary.md

@@ -41,15 +41,18 @@ connector?" or an envelope field needs explaining.
   `cloudglue://files/<id>` URI, connector URI, collection, or a bare file-id
   UUID (normalized to `cloudglue://files/<id>`; an existing local path of the
   same name wins).
-- **Supported inputs** — local uploads (`watch`, `extract`, `face`,
+- **Supported inputs** — local uploads (`watch`, `see`, `extract`, `face`,
   `library collections add`) map by extension: video `.mp4 .mov .webm .mkv .m4v`,
-  audio `.mp3 .wav .m4a`. Other extensions upload as `application/octet-stream`
+  audio `.mp3 .wav .m4a`, and (for `see`/`extract` only, 0.3.7+) image
+  `.jpg .jpeg .png .webp`. Other extensions upload as `application/octet-stream`
   and may be rejected upstream — transcode to a mapped container first
-  (`clip transcode`). Local uploads are bounded by Cloudglue at ~3 GB and
-  2 s–3 h (connector ingests allow more). `face match`/`face search` query
-  images must be **JPEG or PNG**. Use `grab` for YouTube and
-  `library connectors sync` for share links rather than passing those URLs to
-  upload verbs.
+  (`clip transcode`); unsupported image types (HEIC/GIF/BMP) are rejected before
+  upload with a "transcode to JPEG, PNG, or WebP" hint. Local uploads are bounded
+  by Cloudglue at ~3 GB and 2 s–3 h (connector ingests allow more); a public
+  `http(s)` image URL is analyzed in place with no upload. `face match`/`face
+  search` query images must be **JPEG or PNG**. Images can't be added to
+  collections. Use `grab` for YouTube and `library connectors sync` for share
+  links rather than passing those URLs to upload verbs.
 - **`ref` / `source_id` / `result_id`** — stable identifiers in every
   envelope. `ref` is a reusable pointer to the analyzed source (including
   `cloud_ready` and the Cloudglue file id) that pipes between verbs;
@@ -64,6 +67,11 @@ connector?" or an envelope field needs explaining.
   produces (summary, segments, transcript-ish context). Cached locally and
   mirrored in Cloudglue, so later `extract`/`ask`/`search` reuse it instead
   of re-analyzing.
+- **See / image describe (0.3.7+)** — the image counterpart of `watch`:
+  `tinycloud see <image>` produces file-level image context (title,
+  description, on-screen text) and a reusable `ref`, with no segmentation or
+  shots. JPEG/PNG/WebP only; `extract` accepts the same image sources for
+  structured pulls.
 - **Segmentation** — how a video is split for analysis: `chapters`
   (semantic), `shots` (visual cuts; bounds tunable via
   `--shot-min-seconds`/`--shot-max-seconds`, sub-second min allowed),

package/skills/tinycloud/reference/pipelines.md

@@ -41,7 +41,7 @@ tinycloud caption ./talks/*.mp4 --format srt -o ./tinycloud-output/captions/ --j
 
 ## Async jobs
 
-Long cloud operations (`watch`, `extract`) support `--background`:
+Long cloud operations (`watch`, `see`, `extract`) support `--background`:
 
 ```bash
 tinycloud watch ./long.mp4 --background --json   # → status:"pending", meta.job_id

package/skills/tinycloud/reference/setup.md

@@ -101,8 +101,9 @@ binary reports in `--version --json`.
 | `TINYCLOUD_HTTP_TIMEOUT_MS` | Hard deadline per Cloudglue request (default 120s; `0` disables) |
 | `TINYCLOUD_UPLOAD_TIMEOUT_MS` | Total deadline for upload-shaped requests (default 60min; `0` disables) |
 | `TINYCLOUD_UPLOAD_IDLE_TIMEOUT_MS` | Idle (no-progress) deadline for an upload — aborts a wedged transfer in ~1min instead of waiting out the total upload deadline (default 60s; `0` disables) |
-| `TINYCLOUD_HTTP_RETRIES` | Bounded auto-retries for idempotent (GET/HEAD) Cloudglue calls on transient errors — 408/429/5xx, network blips (default 3; `0` disables) |
+| `TINYCLOUD_HTTP_RETRIES` | Bounded auto-retries for idempotent (GET/HEAD) Cloudglue calls on transient errors — 408/429/5xx, network blips (default 5; `0` disables) |
 | `TINYCLOUD_JOB_WAIT_TIMEOUT_MS` | Wall-clock budget for async job waits (the `waitForReady` poll behind `watch`/`extract`/`face`) (default 10min; `0` disables) |
+| `TINYCLOUD_MODEL_RETRIES` | Client-side retries for the interactive agent's chat-model turns on transient connection errors (default 5; `0` disables). 0.3.7+ |
 
 Every Cloudglue request carries a hard deadline, so a stalled route can never
 hang the CLI indefinitely; a timeout surfaces as a retryable `upstream` error

package/skills/tinycloud/reference/verbs.md

@@ -7,7 +7,8 @@ every verb. Regenerate doubts from it instead of trusting prose.
 | Verb | Cost | Auth | Use |
 |---|---|---|---|
 | `watch` | cloud | yes | Analyze a video → reusable context + Cloudglue-ready ref |
-| `extract` | cloud | yes | Pull structured facts, entities, or moments |
+| `see` | cloud | yes | Analyze an image → reusable context + Cloudglue-ready ref (0.3.7+) |
+| `extract` | cloud | yes | Pull structured facts, entities, or moments (from a video **or** image) |
 | `caption` | varies | no | Subtitles and transcripts (SRT/VTT/ASS) |
 | `search` | local | no | Local keyword search over cached context |
 | `probe` | cloud | yes | Semantic moment/video search over a Cloudglue-ready scope |
@@ -60,9 +61,30 @@ Shot bounds tune `--segment shots` only: min 0.6–600 (fractional/sub-second
 values catch flash frames and rapid cuts), max 1–600, min ≤ max. Out-of-range
 or wrong-mode values fail with a validation envelope before any upload. The
 bounds are part of the cache key, so tuned and default shot passes never
-collide.
+collide. `watch` is **video/audio only** — point it at an image and it errors
+("watch analyzes video/audio; for an image use `tinycloud see`").
 
-### extract — structured facts
+### see — analyze an image (cloud, 0.3.7+)
+
+```bash
+tinycloud see <image> [--visual-only] [--background] --json
+```
+
+The image counterpart of `watch`: file-level image understanding (title +
+description + on-screen text) that produces reusable cached context and a
+Cloudglue-ready ref. Images are **file-level only** — there is no segmentation,
+no shots, no speech/transcript, and no `--start`/`--end` window, so `see` carries
+none of those flags (only `--visual-only` to skip the textual read, plus the
+shared output/cache/upload/source-reuse flags). Accepts **JPEG, PNG, or WebP**;
+other types (HEIC/GIF/BMP/…) are rejected before upload with
+`Unsupported image type for see: <name>. Transcode to JPEG, PNG, or WebP first.`
+A local image uploads first (`needs_upload` without `--no-upload`); a public
+`http(s)` URL that points directly at a JPEG/PNG/WebP image is analyzed **in
+place — no upload** (a URL that can't be recognized as a direct image returns
+`needs_download` — fetch it first with `grab`). Results cache by source +
+options, so re-runs are free.
+
+### extract — structured facts (video or image)
 
 ```bash
 tinycloud extract "<query>" <source> --json          # free-form query
@@ -72,8 +94,13 @@ tinycloud extract --schema ./schema.json <source>    # JSON-schema-shaped output
   [--include-thumbnails] [--transcript-mode] [--background]
 ```
 
-`--shot-min-seconds`/`--shot-max-seconds` work exactly as on `watch`, against
-`--segmentation shots`.
+`<source>` may be a video **or an image** (0.3.7+) — same JPEG/PNG/WebP rule
+and local-upload-vs-URL-in-place behavior as `see`. The segmentation flags
+(`--segment-level`/`--segmentation`/`--shot-*`) apply to video only; pass any of
+them with an image source and `extract` rejects it before upload
+(`Images have no segments — drop --segment-level/--segmentation/--shot-* for an
+image source.`). `--shot-min-seconds`/`--shot-max-seconds` work exactly as on
+`watch`, against `--segmentation shots`.
 
 ### caption — subtitles and transcripts
 
@@ -82,6 +109,9 @@ tinycloud caption <source> [--format srt|vtt|ass] [--transcript]
   [--diarize] [--word-level] [-o <file-or-dir>]
 ```
 
+Video/audio only — an image source is rejected ("Images have no speech to
+caption — use `tinycloud see` or `tinycloud extract` to read an image's text.").
+
 ### search — local keyword search (free)
 
 ```bash
@@ -89,6 +119,9 @@ tinycloud search "<keyword>" [--in <paths|source-ids|collection-ids|all>]
   [--field speech|visual|text|entities] [--limit 50]
 ```
 
+Searches cached context locally, including cached `see` image results (0.3.7+),
+so a describe you've already run is greppable without another cloud call.
+
 ### probe — semantic search (cloud)
 
 ```bash
@@ -385,18 +418,18 @@ Output: `--json` (force JSONL envelopes), `--pretty` (one JSON array),
 `--data raw`, `--raw-output` (raw backend payload; disables pipe protocol),
 `--quiet`, `--verbose`.
 
-Cache — on `watch`, `extract`, `caption`, `face`, and `workflow` only:
+Cache — on `watch`, `see`, `extract`, `caption`, `face`, and `workflow` only:
 `--refresh` (recompute), `--no-cache` (no persistence), `--cached` (reuse
 exact-match history). `ask`/`probe` always call the cloud; use `search` for a
 free cached lookup.
 
 Upload/download refusal — on every verb that resolves a source:
-`--no-upload` (refuse cloud upload → `needs_upload`) on `watch`/`extract`/
+`--no-upload` (refuse cloud upload → `needs_upload`) on `watch`/`see`/`extract`/
 `caption`/`face`/`workflow`/`publish` and `library collections add`;
 `--no-download` (refuse local materialization → `needs_download`) on the same
 set minus `publish`.
 
-Source reuse (`watch`/`extract`/`caption`): `--source-id <id>`, `--result-id <id>`.
+Source reuse (`watch`/`see`/`extract`/`caption`): `--source-id <id>`, `--result-id <id>`.
 
 Sources: local paths, URLs, `cloudglue://files/<id>` URIs,
 `collection:col_…`, or a bare Cloudglue file-id UUID — bare ids are

package/skills/tinycloud/scripts/preflight.sh

@@ -9,11 +9,11 @@ set -u
 
 # Mirror tinycloud-skill.json: min_version / supported_range upper bound
 # (CI diffs these against the manifest).
-MIN_VERSION="0.3.4"
+MIN_VERSION="0.3.7"
 MAX_VERSION_EXCLUSIVE="0.4.0"
 INSTALL_CMD='curl -fsSL https://app.cloudglue.dev/tinycloud.sh | bash'
 # Kept in sync with ../tinycloud-skill.json required_features (CI diffs them).
-REQUIRED_FEATURES="envelope.v1 watch.v1 extract.v1 caption.v1 search.v1 probe.v1 ask.v1 clip.v1 grab.v1 face.v1 jobs.v1 library.collections.v1 library.collections.create.v1 library.collections.mutate.v1 library.collections.entities.v1 library.sync.url.v1 workflow.v1 publish.v1 publish.manage.v1 publish.video.v1 setup.v1"
+REQUIRED_FEATURES="envelope.v1 watch.v1 see.v1 extract.v1 extract.images.v1 caption.v1 search.v1 probe.v1 ask.v1 clip.v1 grab.v1 face.v1 jobs.v1 library.collections.v1 library.collections.create.v1 library.collections.mutate.v1 library.collections.entities.v1 library.sync.url.v1 workflow.v1 publish.v1 publish.manage.v1 publish.video.v1 setup.v1"
 
 # 1) Binary present and responsive?
 if ! command -v tinycloud >/dev/null 2>&1; then

package/skills/tinycloud/tinycloud-skill.json

@@ -1,12 +1,14 @@
 {
-  "skill_version": "0.3.6",
+  "skill_version": "0.3.7",
   "tinycloud": {
-    "min_version": "0.3.4",
-    "supported_range": ">=0.3.4 <0.4.0",
+    "min_version": "0.3.7",
+    "supported_range": ">=0.3.7 <0.4.0",
     "required_features": [
       "envelope.v1",
       "watch.v1",
+      "see.v1",
       "extract.v1",
+      "extract.images.v1",
       "caption.v1",
       "search.v1",
       "probe.v1",

package/skills/tinycloud-init/SKILL.md

@@ -22,8 +22,8 @@ in order, skipping any that already pass.
 command -v tinycloud && tinycloud --version --json </dev/null
 ```
 
-If installed and the JSON reports `"version"` ≥ 0.3.4 (the floor the tinycloud
-skill requires), go to step 2. If missing, older than 0.3.4, or no
+If installed and the JSON reports `"version"` ≥ 0.3.7 (the floor the tinycloud
+skill requires), go to step 2. If missing, older than 0.3.7, or no
 machine-readable version, install or upgrade it — ask the user which they
 prefer: