cozyclay 1.0.0 → 1.2.0

package/tools/ardy/setup-text-encoder.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""setup-text-encoder.py - provision the ARDY text-encoder models without a
+Hugging Face account, approval wait, or access token.
+
+ARDY's text encoder is LLM2Vec on top of meta-llama/Meta-Llama-3-8B-Instruct.
+The official Meta repository is gated (manual approval + token). This script
+instead downloads a byte-pinned stack from public, ungated repositories:
+
+  base       NousResearch/Meta-Llama-3-8B-Instruct   (public mirror of the
+             official weights; every safetensors shard is verified against a
+             pinned SHA-256 before use)
+  adapters   McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp
+             McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp-supervised
+
+and lays them out for ARDY's `TEXT_ENCODERS_DIR` override
+(ardy/model/llm2vec/llm2vec_wrapper.py), rewriting each adapter's
+`base_model_name_or_path` to the local base directory so nothing ever
+resolves back to the gated meta-llama repository at runtime.
+
+Every revision is pinned to a full commit SHA and every LFS payload to a
+SHA-256, so re-runs are reproducible and a tampered or changed upstream file
+fails loudly instead of silently drifting the embeddings (and with them the
+generated motion).
+
+Licenses: the base weights are Meta Llama 3 Community License (the LICENSE
+and USE_POLICY.md files are downloaded alongside the weights and must stay
+there); the McGill adapters are MIT. This script only downloads for local
+use - it does not redistribute anything.
+
+Usage (typically on the ARDY box; stdlib only, python >= 3.8):
+
+  python3 setup-text-encoder.py                  # into ~/cclay-text-encoders
+  python3 setup-text-encoder.py --dest /srv/enc  # custom destination
+  python3 setup-text-encoder.py --verify-only    # re-hash an existing tree
+
+Afterwards start the encoder service with the printed environment:
+
+  TEXT_ENCODERS_DIR=<dest> python scripts/run_text_encoder_server.py
+"""
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+
+HF = "https://huggingface.co"
+
+BASE_DIR = "NousResearch/Meta-Llama-3-8B-Instruct"
+MNTP_DIR = "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp"
+# The mntp *download* lands in a -src dir: merge-text-encoder.py bakes the
+# base+MNTP merge into the runtime MNTP_DIR path (transformers v5 dropped
+# automatic adapter-dir resolution, so the runtime path must be a full model).
+MNTP_SRC_DIR = MNTP_DIR + "-src"
+SUP_DIR = "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp-supervised"
+
+# (local dir, repo id, pinned full commit SHA, files)
+# Each file: (path, size, sha256-or-None). SHA-256 comes from the HF LFS
+# metadata of the pinned revision; small non-LFS files carry only a size and
+# are already immutable because the revision is a commit hash.
+# Pins match nv-tlabs/ardy issue #9's reproduction stack.
+MANIFEST = [
+    (
+        BASE_DIR,
+        "NousResearch/Meta-Llama-3-8B-Instruct",
+        "53346005fb0ef11d3b6a83b12c895cca40156b6c",
+        [
+            ("LICENSE", 7801, None),
+            ("USE_POLICY.md", 4696, None),
+            ("config.json", 654, None),
+            ("generation_config.json", 187, None),
+            ("model-00001-of-00004.safetensors", 4976698672,
+             "d8cf9c4d0dd972e1a2131bfe656235ee98221679711a3beef6d46dadf0f20b5c"),
+            ("model-00002-of-00004.safetensors", 4999802720,
+             "8d4782b4a69ef03845159ce1a15e272aadaaf134dc138d68f616098e8531729c"),
+            ("model-00003-of-00004.safetensors", 4915916176,
+             "3acdd690e65c24f42a24581b8467af98bd3ca357444580f8012aacd2bd607921"),
+            ("model-00004-of-00004.safetensors", 1168138808,
+             "67e9ad31c8c32abf3a55ee7fc7217b3ecb35fd3c74d98a5bd233e0e4d6964f46"),
+            ("model.safetensors.index.json", 23950, None),
+            ("special_tokens_map.json", 73, None),
+            ("tokenizer.json", 9085698, None),
+            ("tokenizer_config.json", 50977, None),
+        ],
+    ),
+    (
+        MNTP_SRC_DIR,
+        "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp",
+        "31474e395ada192e8ed1586db6be79fb3b70c9c0",
+        [
+            ("README.md", 3315, None),
+            ("adapter_config.json", 794, None),
+            ("adapter_model.safetensors", 167829552,
+             "de9c8736618a13173c6a1623cdef1b75e86c69317f1073ae82cd516ac36a632d"),
+            ("attn_mask_utils.py", 11132, None),
+            ("config.json", 781, None),
+            ("modeling_llama_encoder.py", 2856, None),
+            ("special_tokens_map.json", 335, None),
+            ("tokenizer.json", 9085671, None),
+            ("tokenizer_config.json", 51042, None),
+        ],
+    ),
+    (
+        SUP_DIR,
+        "McGill-NLP/LLM2Vec-Meta-Llama-3-8B-Instruct-mntp-supervised",
+        "baa8ebf04a1c2500e61288e7dad65e8ae42601a7",
+        [
+            ("README.md", 62702, None),
+            ("adapter_config.json", 794, None),
+            ("adapter_model.safetensors", 167829552,
+             "53f8f94ebdf396667ba99dd96e78203edae27bbcdbd1cf5f12b611e1d916b225"),
+        ],
+    ),
+]
+
+# adapter_config.json is rewritten after download (base_model_name_or_path ->
+# local base dir), so its byte size legitimately changes; everything else must
+# keep the manifest size forever.
+MUTATED = {"adapter_config.json"}
+
+CHUNK = 1024 * 1024
+
+
+def log(msg):
+    print("setup-text-encoder: %s" % msg, flush=True)
+
+
+def fail(msg):
+    print("setup-text-encoder: ERROR: %s" % msg, file=sys.stderr, flush=True)
+    sys.exit(1)
+
+
+def sha256_file(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            block = f.read(CHUNK)
+            if not block:
+                break
+            h.update(block)
+    return h.hexdigest()
+
+
+def file_ok(path, size, sha, verify_hash):
+    """Is the on-disk file already the pinned artifact?"""
+    if not os.path.isfile(path):
+        return False
+    name = os.path.basename(path)
+    if name in MUTATED:
+        return True  # rewritten in place; checked by rewrite_adapter_config
+    if os.path.getsize(path) != size:
+        return False
+    if sha is not None and verify_hash:
+        return sha256_file(path) == sha
+    return True
+
+
+def download(url, dest, size, sha):
+    """Resumable download to dest + '.partial', verified, then atomic rename."""
+    part = dest + ".partial"
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+    for attempt in range(1, 6):
+        try:
+            have = os.path.getsize(part) if os.path.isfile(part) else 0
+            if have > size:
+                os.remove(part)
+                have = 0
+            if have < size:
+                req = urllib.request.Request(url)
+                req.add_header("User-Agent", "cozyclay-setup-text-encoder/1")
+                if have:
+                    req.add_header("Range", "bytes=%d-" % have)
+                with urllib.request.urlopen(req, timeout=60) as resp:
+                    if have and resp.status != 206:
+                        # Server ignored the Range header; start over.
+                        have = 0
+                        mode = "wb"
+                    else:
+                        mode = "ab" if have else "wb"
+                    done = have
+                    t0 = time.time()
+                    with open(part, mode) as out:
+                        while True:
+                            block = resp.read(CHUNK)
+                            if not block:
+                                break
+                            out.write(block)
+                            done += len(block)
+                            if size > CHUNK and time.time() - t0 > 5:
+                                log("  ... %d / %d MiB" % (done // 2**20, size // 2**20))
+                                t0 = time.time()
+            got = os.path.getsize(part)
+            if got != size:
+                raise IOError("size mismatch: got %d, want %d" % (got, size))
+            if sha is not None:
+                actual = sha256_file(part)
+                if actual != sha:
+                    os.remove(part)
+                    raise IOError("sha256 mismatch: got %s, want %s" % (actual, sha))
+            os.replace(part, dest)
+            return
+        except (urllib.error.URLError, IOError, OSError) as e:
+            if attempt == 5:
+                fail("giving up on %s after 5 attempts: %s" % (url, e))
+            log("  retry %d/5 for %s (%s)" % (attempt, os.path.basename(dest), e))
+            time.sleep(2 * attempt)
+
+
+def rewrite_adapter_config(path, base_path):
+    """Point the adapter at the local base so nothing resolves to gated repos."""
+    with open(path, "r", encoding="utf-8") as f:
+        cfg = json.load(f)
+    if cfg.get("base_model_name_or_path") == base_path:
+        return False
+    cfg["base_model_name_or_path"] = base_path
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(cfg, f, indent=2)
+        f.write("\n")
+    os.replace(tmp, path)
+    return True
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--dest", default=os.environ.get(
+        "TEXT_ENCODERS_DIR", os.path.expanduser("~/cclay-text-encoders")),
+        help="target directory (default: $TEXT_ENCODERS_DIR or ~/cclay-text-encoders)")
+    ap.add_argument("--verify-only", action="store_true",
+                    help="verify an existing tree (sizes + SHA-256), download nothing")
+    ap.add_argument("--print-plan", action="store_true",
+                    help="list every pinned file and exit")
+    args = ap.parse_args()
+
+    dest = os.path.abspath(os.path.expanduser(args.dest))
+    base_path = os.path.join(dest, BASE_DIR)
+
+    if args.print_plan:
+        for local_dir, repo, rev, files in MANIFEST:
+            print("%s @ %s" % (repo, rev))
+            for path, size, sha in files:
+                print("  %-40s %12d  %s" % (path, size, sha or "-"))
+        return
+
+    total = sum(size for _, _, _, files in MANIFEST for _, size, _ in files)
+    missing = []
+    for local_dir, repo, rev, files in MANIFEST:
+        for path, size, sha in files:
+            target = os.path.join(dest, local_dir, path)
+            if not file_ok(target, size, sha, verify_hash=args.verify_only):
+                missing.append((local_dir, repo, rev, path, size, sha))
+
+    if args.verify_only:
+        if missing:
+            for local_dir, _, _, path, _, _ in missing:
+                print("  BAD/MISSING  %s/%s" % (local_dir, path))
+            fail("%d file(s) failed verification under %s" % (len(missing), dest))
+        log("all %d files verified OK under %s" % (
+            sum(len(f) for _, _, _, f in MANIFEST), dest))
+        return
+
+    if missing:
+        todo = sum(m[4] for m in missing)
+        log("destination: %s" % dest)
+        log("downloading %d file(s), %.1f GiB of %.1f GiB total pinned payload"
+            % (len(missing), todo / 2**30, total / 2**30))
+        for local_dir, repo, rev, path, size, sha in missing:
+            url = "%s/%s/resolve/%s/%s?download=true" % (HF, repo, rev, path)
+            log("fetch %s/%s (%d bytes)" % (local_dir, path, size))
+            download(url, os.path.join(dest, local_dir, path), size, sha)
+    else:
+        log("all pinned files already present under %s" % dest)
+
+    for adapter_dir in (MNTP_SRC_DIR, SUP_DIR):
+        cfg = os.path.join(dest, adapter_dir, "adapter_config.json")
+        if rewrite_adapter_config(cfg, base_path):
+            log("repointed %s -> local base" % os.path.join(adapter_dir, "adapter_config.json"))
+
+    log("downloads verified. Bake the MNTP merge next (one-time, ~5 min):")
+    log("  cd <ardy checkout> && <ardy venv python> merge-text-encoder.py --dest %s" % dest)
+    print()
+    print("Start ARDY's text-encoder service (and any local ARDY run) with:")
+    print()
+    print("  export TEXT_ENCODERS_DIR=%s" % dest)
+    print("  python scripts/run_text_encoder_server.py")
+    print()
+    print("The base weights are Meta Llama 3 (Meta Llama 3 Community License;")
+    print("see %s/LICENSE)." % base_path)
+    print("This product is built with Meta Llama 3.")
+
+
+if __name__ == "__main__":
+    main()

package/tools/generation/README.md

@@ -0,0 +1,29 @@
+# Video generation bridge
+
+The bridge keeps provider credentials out of the browser and translates CozyClay's provider-neutral ShotSpec into provider requests.
+
+## Run locally
+
+```bash
+RUNWAYML_API_SECRET=key_here npm run dev
+```
+
+The bridge binds to `127.0.0.1:5182`; Vite proxies `/generation` to it. The static GitHub Pages build remains generation-free.
+
+## Endpoints
+
+- `GET /generation/health`
+- `GET /generation/models`
+- `POST /generation/validate`
+- `POST /generation/jobs`
+- `GET /generation/jobs/:id`
+- `DELETE /generation/jobs/:id` (when the provider exposes verified remote cancellation)
+
+## Provider credentials
+
+- Runway: `RUNWAYML_API_SECRET`
+- Seedance / BytePlus ModelArk: `ARK_API_KEY`
+- Kling: `KLING_API_TOKEN` (a server-side bearer token produced by Kling's authentication flow)
+- Veo / Vertex AI: `GOOGLE_CLOUD_ACCESS_TOKEN`, `GOOGLE_CLOUD_PROJECT`, and optionally `GOOGLE_CLOUD_LOCATION`
+
+The browser receives only model descriptors. Provider payloads and credentials stay inside `providers/`; completed MP4 files are downloaded immediately into the shared local job store.

package/tools/generation/bridge.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, rename, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+import { pathToFileURL } from "node:url";
+import { createJobStore } from "./job-store.mjs";
+import { klingProvider } from "./providers/kling.mjs";
+import { runwayProvider } from "./providers/runway.mjs";
+import { seedanceProvider } from "./providers/seedance.mjs";
+import { veoProvider } from "./providers/veo.mjs";
+
+const HOST = "127.0.0.1";
+const PORT = Number(process.env.CCLAY_GENERATION_PORT || 5182);
+const MAX_BODY = 16 * 1024 * 1024;
+const RETRYABLE = new Set([429, 502, 503, 504]);
+
+function json(res, status, body) {
+  const data = Buffer.from(JSON.stringify(body));
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Content-Length": data.length, "Cache-Control": "no-store" });
+  res.end(data);
+}
+
+async function readJson(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_BODY) throw Object.assign(new Error("request body exceeds 16 MB"), { status: 413 });
+    chunks.push(chunk);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+  catch { throw Object.assign(new Error("invalid JSON body"), { status: 400 }); }
+}
+
+function publicJob(job) {
+  const { raw, outputPath, remoteOutputUrl, ...safe } = job;
+  return { ...safe, outputUrl: outputPath ? `/generation/jobs/${encodeURIComponent(job.id)}/output` : null };
+}
+
+export async function downloadResult(url, target, { fetchImpl = fetch, retries = 3, timeoutMs = 30000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {}) {
+  await mkdir(join(target, ".."), { recursive: true });
+  const temp = `${target}.${process.pid}.tmp`;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    const response = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (response.ok && response.body) {
+      await pipeline(Readable.fromWeb(response.body), await import("node:fs").then(({ createWriteStream }) => createWriteStream(temp)));
+      await rename(temp, target);
+      return target;
+    }
+    await response.body?.cancel().catch(() => {});
+    if (!RETRYABLE.has(response.status) || attempt === retries) throw new Error(`result download failed (HTTP ${response.status})`);
+    await sleep(250 * (2 ** attempt));
+  }
+  throw new Error("result download failed");
+}
+
+export function createGenerationServer({ store = createJobStore(), providers = { runway: runwayProvider, seedance: seedanceProvider, kling: klingProvider, veo: veoProvider }, download = downloadResult, now = () => new Date().toISOString() } = {}) {
+  const ready = store.load();
+  return createServer(async (req, res) => {
+    try {
+      await ready;
+      const url = new URL(req.url, `http://${HOST}:${PORT}`);
+      if (req.method === "GET" && url.pathname === "/generation/health") {
+        return json(res, 200, { ok: true, providers: Object.fromEntries(Object.entries(providers).map(([id, provider]) => [id, provider.available()])) });
+      }
+      if (req.method === "GET" && url.pathname === "/generation/models") {
+        const models = Object.entries(providers).flatMap(([providerId, provider]) => provider.models.map((model) => ({ ...model, provider: providerId, available: provider.available() })));
+        return json(res, 200, { models });
+      }
+      if (req.method === "GET" && url.pathname === "/generation/jobs") {
+        return json(res, 200, { jobs: store.list().map(publicJob) });
+      }
+      if (req.method === "POST" && url.pathname === "/generation/validate") {
+        const spec = await readJson(req);
+        const provider = providers[spec.provider];
+        if (!provider) return json(res, 422, { reason: spec.provider ? `unsupported provider: ${spec.provider}` : "provider is required" });
+        if (!spec.model) return json(res, 422, { reason: "model is required" });
+        const verdict = provider.validate(spec);
+        return json(res, verdict.ok ? 200 : 422, { ok: verdict.ok, errors: verdict.errors, warnings: verdict.warnings, estimatedCostUsd: verdict.ok ? provider.estimateCost(spec) : null });
+      }
+      if (req.method === "POST" && url.pathname === "/generation/jobs") {
+        const spec = await readJson(req);
+        const provider = providers[spec.provider];
+        if (!provider) return json(res, 422, { reason: spec.provider ? `unsupported provider: ${spec.provider}` : "provider is required" });
+        if (!provider.available()) return json(res, 503, { reason: `${spec.provider} is not configured` });
+        const verdict = provider.validate(spec);
+        if (!verdict.ok) return json(res, 422, { reason: verdict.errors[0], errors: verdict.errors, warnings: verdict.warnings });
+        const submitted = await provider.submit(spec);
+        const timestamp = now();
+        const job = { id: randomUUID(), provider: spec.provider, model: spec.model, shot: spec.shot ?? null, camera: spec.camera ?? null, subjects: spec.subjects ?? [], providerJobId: submitted.providerJobId, status: "processing", progress: null, outputPath: null, remoteOutputUrl: null, failure: null, warnings: submitted.warnings, estimatedCostUsd: provider.estimateCost(spec), createdAt: timestamp, updatedAt: timestamp };
+        await store.set(job);
+        return json(res, 202, publicJob(job));
+      }
+      const outputMatch = url.pathname.match(/^\/generation\/jobs\/([^/]+)\/output$/);
+      if (req.method === "GET" && outputMatch) {
+        const job = store.get(outputMatch[1]);
+        if (!job?.outputPath) return json(res, 404, { reason: "result not available" });
+        const info = await stat(job.outputPath).catch(() => null);
+        if (!info) return json(res, 410, { reason: "saved result is missing" });
+        res.writeHead(200, { "Content-Type": "video/mp4", "Content-Length": info.size, "Content-Disposition": `attachment; filename="cozyclay-${job.id}.mp4"`, "Cache-Control": "no-store" });
+        createReadStream(job.outputPath).pipe(res);
+        return;
+      }
+      const match = url.pathname.match(/^\/generation\/jobs\/([^/]+)$/);
+      if (req.method === "DELETE" && match) {
+        const job = store.get(match[1]);
+        if (!job) return json(res, 404, { reason: "job not found" });
+        if (job.status !== "processing") return json(res, 200, publicJob(job));
+        const provider = providers[job.provider];
+        if (!provider?.cancel) return json(res, 409, { reason: `${job.provider} does not expose a verified remote cancellation operation` });
+        if (!provider.available()) return json(res, 503, { reason: `${job.provider} is not configured; restore its key to cancel this job` });
+        await provider.cancel(job.providerJobId, { model: job.model });
+        Object.assign(job, { status: "canceled", failure: "generation canceled", updatedAt: now() });
+        await store.set(job);
+        return json(res, 200, publicJob(job));
+      }
+      if (req.method === "GET" && match) {
+        const job = store.get(match[1]);
+        if (!job) return json(res, 404, { reason: "job not found" });
+        if (job.status === "processing") {
+          const provider = providers[job.provider];
+          if (!provider?.available()) return json(res, 503, { reason: `${job.provider} is not configured; restore its key to resume this job` });
+          const state = await provider.poll(job.providerJobId, { model: job.model });
+          Object.assign(job, state, { remoteOutputUrl: state.outputUrl ?? job.remoteOutputUrl, updatedAt: now() });
+          if (state.status === "succeeded" && state.outputUrl) {
+            const target = join(store.resultDir, `${job.id}.mp4`);
+            try { await download(state.outputUrl, target); job.outputPath = target; }
+            catch (error) { job.status = "failed"; job.failure = `provider finished, but its expiring output could not be saved locally: ${error.message}`; }
+          }
+          await store.set(job);
+        }
+        return json(res, 200, publicJob(job));
+      }
+      return json(res, 404, { reason: "not found" });
+    } catch (error) {
+      return json(res, error.status || 500, { reason: error.message || String(error) });
+    }
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const server = createGenerationServer();
+  server.listen(PORT, HOST, () => console.log(`[generation] listening on http://${HOST}:${PORT}`));
+  for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, () => server.close(() => process.exit(0)));
+}

package/tools/generation/job-store.mjs

@@ -0,0 +1,51 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+export const DEFAULT_JOB_FILE = join(homedir(), ".cozyclay", "jobs.json");
+export const DEFAULT_RESULT_DIR = join(homedir(), ".cozyclay", "results");
+export const DEFAULT_COMPLETED_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const TERMINAL = new Set(["succeeded", "failed"]);
+
+export function createJobStore({ file = DEFAULT_JOB_FILE, resultDir = DEFAULT_RESULT_DIR, completedTtlMs = DEFAULT_COMPLETED_TTL_MS, now = () => Date.now() } = {}) {
+  const jobs = new Map();
+  let writeQueue = Promise.resolve();
+
+  async function load() {
+    try {
+      const parsed = JSON.parse(await readFile(file, "utf8"));
+      for (const job of Array.isArray(parsed.jobs) ? parsed.jobs : []) if (job?.id) jobs.set(job.id, job);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    await cleanup();
+    return jobs;
+  }
+
+  function persist() {
+    writeQueue = writeQueue.then(async () => {
+      await mkdir(dirname(file), { recursive: true });
+      const temp = `${file}.${process.pid}.tmp`;
+      await writeFile(temp, JSON.stringify({ version: 1, jobs: [...jobs.values()] }, null, 2));
+      await rename(temp, file);
+    });
+    return writeQueue;
+  }
+
+  async function cleanup() {
+    const cutoff = now() - completedTtlMs;
+    let changed = false;
+    for (const [id, job] of jobs) {
+      if (!TERMINAL.has(job.status) || Date.parse(job.updatedAt) >= cutoff) continue;
+      jobs.delete(id);
+      if (job.outputPath) await unlink(job.outputPath).catch(() => {});
+      changed = true;
+    }
+    if (changed) await persist();
+  }
+
+  async function set(job) { jobs.set(job.id, job); await persist(); return job; }
+  function get(id) { return jobs.get(id) ?? null; }
+  function list() { return [...jobs.values()].sort((a, b) => b.createdAt.localeCompare(a.createdAt)); }
+  return { file, resultDir, load, cleanup, set, get, list };
+}

package/tools/generation/providers/kling.mjs

@@ -0,0 +1,76 @@
+import { fetchProviderJson, findModel, noKnownUsdEstimate } from "./shared.mjs";
+
+const API = "https://api.klingai.com/v1/videos/image2video";
+
+export const KLING_MODELS = Object.freeze([
+  {
+    id: "kling-v3",
+    label: "Kling Video 3.0",
+    durations: [5, 10],
+    resolutions: ["720p", "1080p"],
+    capabilities: { prompt: true, startFrame: true, endFrame: true, referenceVideo: false, cameraControl: false, audio: true },
+  },
+]);
+
+const authHeaders = (token) => ({ Authorization: `Bearer ${token}`, "Content-Type": "application/json" });
+const modelOf = (id) => findModel(KLING_MODELS, id, "Kling");
+
+export function validateKlingSpec(spec) {
+  const model = modelOf(spec.model);
+  const errors = [];
+  const warnings = [];
+  if (!spec.prompt?.trim()) errors.push("prompt is required");
+  if (!model.durations.includes(spec.durationSeconds)) errors.push(`${model.label} duration must be 5 or 10 seconds`);
+  if (!model.resolutions.includes(spec.resolution)) errors.push(`${model.label} resolution must be 720p or 1080p`);
+  if (!spec.conditioning?.startFrame) errors.push(`${model.label} requires a staged start frame`);
+  if (spec.conditioning?.referenceVideo) warnings.push("Kling reference-video request mapping is unverified and will not be sent");
+  if (spec.camera) warnings.push("Kling 3.0 camera-control payload is unverified; staged frames and composed prompt will carry the authored camera move");
+  return { ok: errors.length === 0, errors, warnings, model };
+}
+
+export function mapKlingRequest(spec) {
+  const verdict = validateKlingSpec(spec);
+  if (!verdict.ok) throw new Error(verdict.errors[0]);
+  const body = {
+    model_name: verdict.model.id,
+    image: spec.conditioning.startFrame,
+    prompt: spec.prompt,
+    mode: spec.resolution === "1080p" ? "pro" : "std",
+    duration: String(spec.durationSeconds),
+    sound: "on",
+  };
+  if (spec.conditioning.endFrame) body.image_tail = spec.conditioning.endFrame;
+  return body;
+}
+
+export async function submitKling(spec, { token = process.env.KLING_API_TOKEN, fetchImpl = fetch, signal, ...retryOptions } = {}) {
+  if (!token) throw new Error("KLING_API_TOKEN is not configured; provide a server-side token generated by Kling's documented authentication flow");
+  const verdict = validateKlingSpec(spec);
+  if (!verdict.ok) throw new Error(verdict.errors[0]);
+  const { response, payload } = await fetchProviderJson(API, { method: "POST", headers: authHeaders(token), body: JSON.stringify(mapKlingRequest(spec)) }, { fetchImpl, signal, ...retryOptions });
+  if (!response.ok) throw new Error(`Kling submit failed (HTTP ${response.status})`);
+  const providerJobId = payload.data?.task_id;
+  if (!providerJobId) throw new Error("Kling submit response has no task id");
+  return { providerJobId, warnings: verdict.warnings };
+}
+
+export async function pollKling(providerJobId, { token = process.env.KLING_API_TOKEN, fetchImpl = fetch, signal, ...retryOptions } = {}) {
+  if (!token) throw new Error("KLING_API_TOKEN is not configured");
+  const { response, payload } = await fetchProviderJson(`${API}/${encodeURIComponent(providerJobId)}`, { headers: authHeaders(token) }, { fetchImpl, signal, ...retryOptions });
+  if (!response.ok) throw new Error(`Kling poll failed (HTTP ${response.status})`);
+  const remote = String(payload.data?.task_status || "").toLowerCase();
+  const status = remote === "succeed" || remote === "succeeded" ? "succeeded" : ["failed", "canceled", "cancelled"].includes(remote) ? "failed" : "processing";
+  return { status, progress: null, outputUrl: status === "succeeded" ? payload.data?.task_result?.videos?.[0]?.url ?? null : null, failure: status === "failed" ? payload.data?.task_status_msg || payload.message || "generation failed" : null, raw: payload };
+}
+
+export const klingProvider = Object.freeze({
+  id: "kling",
+  label: "Kling AI",
+  auth: { type: "bearer-env", env: "KLING_API_TOKEN" },
+  available: () => Boolean(process.env.KLING_API_TOKEN),
+  models: KLING_MODELS,
+  validate: validateKlingSpec,
+  estimateCost: noKnownUsdEstimate,
+  submit: submitKling,
+  poll: pollKling,
+});