From 1a695734476f7a5593e45b4babf7486ddf1af1a2 Mon Sep 17 00:00:00 2001 From: KDR Date: Thu, 30 Jul 2026 06:41:32 -0500 Subject: [PATCH] =?UTF-8?q?Prepare=20for=20tinycloud=200.3.16:=20truthful?= =?UTF-8?q?=20watch=20segmentation,=20collections=20--describe=20+=20pagin?= =?UTF-8?q?ation=20(skill=20floor=20=E2=86=92=200.3.16)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the 0.3.16 binary across the skill surfaces: - verbs.md: data.segmentation now reports the segmentation that produced segments[] (pre-0.3.16 binaries mislabeled shots/chapters runs as uniform:20 — trust describe.primary_segmentation there), the degenerate-shots note on cut-less footage, collections create --describe (API default indexes speech+summary ONLY, immutable post-create), and collections show pagination (--limit/--page-token, data.total, page until next_page_token is null; pre-0.3.16 capped listings at 50 with a wrong has_more and a redacted token). - SKILL.md: --describe full in the collections cheat sheet with the speech-only-default warning. - Floor raised to 0.3.16 (min_version/preflight + 2 new required features: library.collections.describe.v1, library.collections.pagination.v1) — the skill teaches the new flag and pagination contract. - Version bumps: package.json, plugin.json, marketplace.json, README. DO NOT MERGE until CDN channels.stable = 0.3.16 (the 0.3.15 merge-after-CDN gate). Wrapper suite 42/42, plugin validate + shellcheck + metadata sync pass locally. --- .claude-plugin/marketplace.json | 4 +-- .claude-plugin/plugin.json | 2 +- CLAUDE.md | 25 ++++++++++++++++++- README.md | 4 +-- package.json | 2 +- skills/tinycloud/SKILL.md | 5 +++- skills/tinycloud/reference/verbs.md | 36 ++++++++++++++++++++++++--- skills/tinycloud/scripts/preflight.sh | 4 +-- skills/tinycloud/tinycloud-skill.json | 8 +++--- 9 files changed, 74 insertions(+), 16 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 01df166..51a0d8b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,14 +7,14 @@ }, "metadata": { "description": "Deep video and image work for coding agents: analyze, describe, search, caption, clip, detect faces, and publish via the tinycloud CLI.", - "version": "0.3.15" + "version": "0.3.16" }, "plugins": [ { "name": "tinycloud", "source": "./", "description": "Video and image understanding and editing via the tinycloud CLI (Cloudglue): watch/see/extract/search/ask/face over videos and images, captions, clips, collections, plus one-command workflows for sales coaching, blog posts, ad analysis, meeting breakdowns, and YouTube publishing.", - "version": "0.3.15", + "version": "0.3.16", "author": { "name": "Cloudglue" }, "homepage": "https://tinycloud.sh", "repository": "https://github.com/cloudglue/tinycloud", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 23febd8..2550c85 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "name": "tinycloud", "displayName": "Tinycloud Video", "description": "Video and image understanding and editing via the tinycloud CLI (Cloudglue): watch/see/extract/search/ask/face over videos and images, captions, clips, collections, and one-command video workflows.", - "version": "0.3.15", + "version": "0.3.16", "author": { "name": "Cloudglue", "url": "https://cloudglue.dev" }, "homepage": "https://tinycloud.sh", "repository": "https://github.com/cloudglue/tinycloud", diff --git a/CLAUDE.md b/CLAUDE.md index f4099f6..dabfa20 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -185,7 +185,30 @@ connector and re-indexes its metadata collections — free (feature `library.connectors.refresh.v1`; refresh takes a SOURCE, unlike inspect/sync which take `[connector-id] `). Because the skill teaches the new flags/subcommands, the floor was raised to 0.3.15 (same -merge-after-CDN gate). The host-level `profile` verb and the leading global flags `--home`/`--profile` +merge-after-CDN gate). 0.3.16 is an envelope-truth and collections release +(features 38→40, verbs stay 16), fixing the failure modes a live agent +session surfaced: `watch`'s `data.segmentation` now reports the segmentation +that actually produced `segments[]` (shots/chapters runs were mislabeled +`uniform:20`, manufacturing a phantom "silent fallback" — the synthesized +speech-only label is unchanged), a shots run over cut-less footage that +max-caps every window gets an explanatory `data.segmentation_note`, and +per-verb `--help` names every shared flag per group (`[cache: --refresh +--no-cache …]`) instead of the "[common output/cache/source options]" +placeholder that hid the cache flags from grepping agents. `library +collections create` gains `--describe full|speech|light|` +(feature `library.collections.describe.v1`; media-descriptions only) because +the Cloudglue API default indexes speech+summary ONLY and the choice is +immutable post-create — `collections show` now surfaces `describe_config`, +and the create summary names the indexed modalities. Collections listings +switch to the API's real offset pagination (feature +`library.collections.pagination.v1`): `show` returns `data.total` plus a +working `has_more`/`next_page_token` (numeric offset cursors accepted via +`--page-token`), pagination cursors are exempt from the `_token` secret +redaction that shipped the literal `[redacted]` where the cursor belonged, +and `collections sync` mirrors no longer silently truncate at 100 files +(pre-0.3.16, every listing was the first 50 rows with `has_more: false`). +Because the skill teaches `--describe` and show pagination, the floor was +raised to 0.3.16 (same merge-after-CDN gate). The host-level `profile` verb and the leading global flags `--home`/`--profile` (also `$TINYCLOUD_HOME`; 0.3.3+) relocate state and are intentionally absent from `commands --json` — like the launcher's install/update, they're CLI/host concerns, not video operations. diff --git a/README.md b/README.md index ef2a146..14d8761 100644 --- a/README.md +++ b/README.md @@ -17,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//`), verifies its checksum, and execs the real binary. The package version pins the binary version, so -`npx @cloudglue/tinycloud@0.3.15` always runs tinycloud 0.3.15. It also adds two +`npx @cloudglue/tinycloud@0.3.16` always runs tinycloud 0.3.16. It also adds two wrapper commands: ```bash -tinycloud install --version 0.3.15 # pre-download a version +tinycloud install --version 0.3.16 # pre-download a version tinycloud install --latest # install latest stable and pin to it tinycloud update # move to latest stable, prune old versions ``` diff --git a/package.json b/package.json index 482a640..1d414ca 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@cloudglue/tinycloud", - "version": "0.3.15", + "version": "0.3.16", "description": "Agent CLI for deep video and image work, by Cloudglue. Downloads the tinycloud binary on first run.", "bin": { "tinycloud": "bin/tinycloud.js" diff --git a/skills/tinycloud/SKILL.md b/skills/tinycloud/SKILL.md index 70cdff1..6d674e2 100644 --- a/skills/tinycloud/SKILL.md +++ b/skills/tinycloud/SKILL.md @@ -112,7 +112,10 @@ tinycloud jobs wait --timeout 120s --json # Collections (0.3.4+) — turn videos into a reusable, queryable knowledge base. # Lifecycle (every --type): create → add → poll show → query → delete. tinycloud library collections list --json -tinycloud library collections create my-desc --type media-descriptions --json # types: media-descriptions | face-analysis | entities (--prompt) | rich-transcripts | metadata (0.3.15+) +tinycloud library collections create my-desc --type media-descriptions --describe full --json # types: media-descriptions | face-analysis | entities (--prompt) | rich-transcripts | metadata (0.3.15+) +# --describe full|speech|light (0.3.16+): which modalities a media-descriptions collection indexes. +# The API default is speech+summary ONLY (no visuals/scene text) and it is IMMUTABLE after create — +# pass --describe full when visual probe/ask queries matter. `show` reports describe_config. tinycloud library collections add ./demo.mp4 --to col_desc --json # uploads a local source first; enrichment is async (pending) tinycloud library collections show col_desc --json # poll files[].status until completed, then query — # the collection's --type decides the read verb (each line below is a DIFFERENT, matching-type collection): diff --git a/skills/tinycloud/reference/verbs.md b/skills/tinycloud/reference/verbs.md index 27c27a5..e24b11c 100644 --- a/skills/tinycloud/reference/verbs.md +++ b/skills/tinycloud/reference/verbs.md @@ -65,6 +65,17 @@ bounds are part of the cache key, so tuned and default shot passes never collide. `watch` is **video/audio only** — point it at an image and it errors ("watch analyzes video/audio; for an image use `tinycloud see`"). +`data.segmentation` reports the segmentation that actually produced +`segments[]` (0.3.16+ — earlier binaries mislabeled shots/chapters runs as +`uniform:20`; on those, trust `data.describe.primary_segmentation` instead). +On footage with no detectable cuts (talks, screencasts, locked-off cameras) a +shots run degenerates to max-duration windows — every shot hits +`--shot-max-seconds` (default 300), so boundaries land on exact multiples. +That is shot detection working on cut-less footage, **not** a fallback to +uniform; 0.3.16+ flags it in `data.segmentation_note`. Re-runs are served +from cache — `--refresh` recomputes and `--no-cache` bypasses (no `--home` +workarounds needed). + Segments carry the spoken words (0.3.12+): each segment (and embedded shot) inlines its overlapping utterances as `speech: string[]`. A source with speech but no visual segmentation — an audio file, `--speech-only`, a very @@ -234,10 +245,10 @@ finds the query face across one or more collections (`--min-score`, ```bash tinycloud library collections list --json -tinycloud library collections show --json # files[].status: pending|processing|completed (readiness) +tinycloud library collections show [--limit ] [--page-token ] --json # files[].status: pending|processing|completed (readiness) tinycloud library collections sync --artifacts descriptions,transcripts,thumbnails,metadata --json # Collection writes (0.3.4+) — the only write paths in library: -tinycloud library collections create [--type media-descriptions|entities|rich-transcripts|face-analysis|metadata] [--description ] [--prompt | --schema ] --json +tinycloud library collections create [--type media-descriptions|entities|rich-transcripts|face-analysis|metadata] [--describe full|speech|light|] [--description ] [--prompt | --schema ] --json tinycloud library collections add --to [--metadata ''] [--no-upload] [--no-download] --json tinycloud library collections remove --from --json tinycloud library collections delete --json @@ -255,7 +266,20 @@ read-only `library` (gated by the `library.collections.create.v1` / `--type media-descriptions`; an `entities` collection also needs an extraction spec — `--prompt ` or `--schema ` — or `create` errors, and a `metadata` collection takes NO processing configs (`create` rejects -`--prompt`/`--schema`). `add` +`--prompt`/`--schema`). + +**A media-descriptions collection indexes only the modalities chosen at +create time, and the API default is speech+summary ONLY** — no visual scene +descriptions, no scene text — so visual `probe`/`ask` queries over a +default-created collection come back empty. `--describe` (0.3.16+, feature +`library.collections.describe.v1`) picks the modalities: `full` +(speech+visual+scene-text+audio+summary — matches a standalone `watch`), +`speech` (the API default, explicit), `light` (speech+visual+summary), or a +comma list from `speech,visual,scene-text,audio,summary`. The choice is +**immutable after create** (the API ignores config updates), so pass +`--describe full` up front when visual search matters; `collections show` +reports the collection's `describe_config`, and the create summary names the +indexed modalities. `add` (`--to `, or `--collection`) resolves the source like `watch`/`extract` — a local file uploads first (or `needs_upload` with `--no-upload`) — and records the file→collection mapping; `--metadata ''` (0.3.15+) @@ -271,6 +295,12 @@ asynchronously and returns `pending`. Poll `collections show --json` and wait until every `files[].status` is `completed` (`pending → processing → completed`; `failed` is terminal) — a query before then returns empty or errors. +`collections show` lists ONE page of files (default 50) with `data.total`, +`has_more`, and `next_page_token` — page with `--page-token` until the token +is null (0.3.16+, feature `library.collections.pagination.v1`; earlier +binaries capped every listing at 50 with a wrong `has_more: false` and a +redacted token, so a >50-file collection could not be enumerated). + The collection's `--type` decides which verb reads it (every type follows the same `create → add → poll show → query → delete` lifecycle): diff --git a/skills/tinycloud/scripts/preflight.sh b/skills/tinycloud/scripts/preflight.sh index 4068b5b..52a2b67 100755 --- a/skills/tinycloud/scripts/preflight.sh +++ b/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.15" +MIN_VERSION="0.3.16" 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 watch.speech.v1 see.v1 extract.v1 extract.images.v1 caption.v1 search.v1 probe.v1 probe.filters.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.collections.metadata.v1 library.sync.url.v1 workflow.v1 publish.v1 publish.manage.v1 publish.video.v1 publish.link.preview.v1 setup.v1" +REQUIRED_FEATURES="envelope.v1 watch.v1 watch.speech.v1 see.v1 extract.v1 extract.images.v1 caption.v1 search.v1 probe.v1 probe.filters.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.collections.metadata.v1 library.collections.describe.v1 library.collections.pagination.v1 library.sync.url.v1 workflow.v1 publish.v1 publish.manage.v1 publish.video.v1 publish.link.preview.v1 setup.v1" # 1) Binary present and responsive? if ! command -v tinycloud >/dev/null 2>&1; then diff --git a/skills/tinycloud/tinycloud-skill.json b/skills/tinycloud/tinycloud-skill.json index 728ed28..2b1bd65 100644 --- a/skills/tinycloud/tinycloud-skill.json +++ b/skills/tinycloud/tinycloud-skill.json @@ -1,8 +1,8 @@ { - "skill_version": "0.3.15", + "skill_version": "0.3.16", "tinycloud": { - "min_version": "0.3.15", - "supported_range": ">=0.3.15 <0.4.0", + "min_version": "0.3.16", + "supported_range": ">=0.3.16 <0.4.0", "required_features": [ "envelope.v1", "watch.v1", @@ -24,6 +24,8 @@ "library.collections.mutate.v1", "library.collections.entities.v1", "library.collections.metadata.v1", + "library.collections.describe.v1", + "library.collections.pagination.v1", "library.sync.url.v1", "workflow.v1", "publish.v1",